.lm 5
.indent -5;1 COMPILE

.paragraph 0
The COMPILE utility provides a simple method for students to compile, link, and
run their programs.  The program writes a DCL command procedure to compile,
link and run the program.  If any of the three steps cause or detect an error,
the utility will stop execution. 

.paragraph 0
The command COMPILE has the following format:

.paragraph 0
COMPILE [/qualifier [/...] ] file__spec

.note LOCATION OF FILES
Source files and external object files can be located in any directory.  All
output files, such as object files and executable images will be placed in the
current default directory.
.END NOTE 

.blank
.indent -5;2 Parameters

.paragraph
The only required parameter is the file that is to be compiled, linked,
and executed.  The standard VAX/VMS file specification is used.

.blank
.indent -5;2 Languages

.paragraph
The language qualifiers indicate to the COMPILE utility which compiler is
to be used.  If this qualifier is not specified, the utility uses the file
type on the file spec that is to be compiled.  If the file type is not
specified, the utility then tries to search for all possible language
extensions until a valid file with the file name and a language extension
is found.  If no file is found, then the utility prints an error message
and stops execution.

.paragraph
The language qualfiers are mutually exclusive.  Only one language qualifier
may be specified on a command line.

.paragraph
The language qualifier also provides a method to pass language dependant
qualifiers into the COMPILE utility to be included on the compile command
line in the command procedure.

.blank
.indent -5;/BASIC

.paragraph
Format:

.paragraph
/BASIC[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is BASIC and that the optional
qualifiers are to be included in the command procedure.  If the BASIC language
qualifiers are specified, the quotes are required.

.blank
.indent -5;/PLI

.paragraph
Format:

.paragraph
/PLI[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is PLI and that the optional qualifiers
are to be included in the command procedure.  If the PLI language qualifiers
are specified, the quotes are required. 

.blank
.indent -5;/FORTRAN

.paragraph
Format:

.paragraph
/FORTRAN[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is FORTRAN and that the optional
qualifiers are to be included in the command procedure.  If the FORTRAN
language qualifiers are specified, the quotes are required. 

.blank
.indent -5;/MACRO

.paragraph
Format:

.paragraph
/MACRO[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is MACRO and that the optional
qualifiers are to be included in the command procedure.  If the MACRO language
qualifiers are specified, the quotes are required. 

.blank
.indent -5;/CC

.paragraph
Format:

.paragraph
/CC[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is CC and that the optional qualifiers
are to be included in the command procedure.  If the CC language qualifiers
are specified, the quotes are required. 

.blank
.indent -5;/RPG

.paragraph
Format:

.paragraph
/RPG[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is RPG and that the optional qualifiers
are to be included in the command procedure.  If the RPG language qualifiers
are specified, the quotes are required. 

.blank
.indent -5;/COBOL

.paragraph
Format:

.paragraph
/COBOL[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is COBOL and that the optional
qualifiers are to be included in the command procedure.  If the COBOL language
qualifiers are specified, the quotes are required. 

.blank
.indent -5;/PASCAL

.paragraph
Format:

.paragraph
/PASCAL[="/language__qualifiers"]

.paragraph
Indicates that the language to be used is PASCAL and that the optional
qualifiers are to be included in the command procedure.  If the PASCAL language
qualifiers are specified, the quotes are required. 

.blank
.indent -5;2 Qualifiers

.blank
.indent -5;/AUDIT

.paragraph
Format:

.paragraph
/[NO]AUDIT #####Default -- /NOAUDIT

.paragraph
The /AUDIT qualifier causes the COMPILE utility to generate a command procedure
that audits the execution of the program and includes a listing of the program
in the audit. 

.paragraph
The /AUDIT qualifier cannot be used with the /INSTALL or /DEBUG qualifier,
and must be used with the /LIST qualifier.

.blank
.indent -5;/DEBUG

.paragraph
Format:

.paragraph
/[NO]DEBUG #####Default -- /NODEBUG

.paragraph
The /DEBUG qualifier causes the source program to be compiled, the object
module to be linked, and the executable image to be run with the debugger.
Since the debugger is most efficient on non-optimized programs, the /NOOPTIMIZE
qualifier is included when /DEBUG is specified.  To override the /NOOPTIMIZE
qualifier when using /DEBUG, use the /OPTIMIZE qualifier in the COMPILE
command. 

.blank
.indent -5;/EXTERNAL

.paragraph
Format:

.paragraph
/[NO]EXTERNAL=["]file__spec["] #####Default -- /NOEXTERNAL

.paragraph
The /EXTERNAL qualifier allows an external file to be linked to the file being
linked from the COMPILE command.

.blank
.indent -5;/LIBRARY

.paragraph
Format:

.paragraph
/[NO]LIBRARY #####Default -- /NOLIBRARY

.paragraph
The /LIBRARY qualifier allows a library to be linked with the object module.

.blank
.indent -5;/LIST

.paragraph
Format:

.paragraph
/[NO]LIST[=file__spec] ####Default -- /NOLIST

.paragraph
The /LIST  qualifier causes a list file to be created during the compile.  The
list file will have the source file name with a .LIS extension unless specified
with the qualifier.  If this qualifier is not specified, no list file is created. 

.blank
.indent -5;/LINK

.paragraph
Format:

.paragraph
/LINK="link__command__qualifiers" #####Default -- /LINK=""

.paragraph
The /LINK="" qualifier adds the string enclosed in the quotes to the link
command.  The quotation marks are required.

.blank
.indent -5;/OBJECT

.paragraph
Format:

.paragraph
/[NO]OBJECT=file__spec #####Default -- /OBJECT

.paragraph
The /OBJECT qualifier causes the compiler output to be placed into the specified
file.  If this qualifier is not specified, the default is a file with the same
name as the source file with an extension of .OBJ. 

.blank
.indent -5;/OPTIMIZE

.paragraph
Format:

.paragraph
/[NO]OPTIMIZE #####Default -- /OPTIMIZE for most languages

.paragraph
The /OPTIMIZE qualifier causes the compiler to optimize the program during
compiliation.   Specifying NOOPTIMIZE turns off the optimization.

.blank
.indent -5;/INSTALL

.paragraph
Format:

.paragraph
/[NO]INSTALL[=file__spec] #####Default -- /NOINSTALL

.paragraph
This qualifier causes the COMPILE utility to place the created command file
on the users current directory and defines a symbol that is used to invoke
the command procedure.  If no file specification is indicated in the /INSTALL
qualifier, the name of the file to be compiled is used.  To delete the command
file and the symbol definition, enter the invoking command with a parameter
DELETE.

.paragraph
COMPILE/INSTALL THIS.PLI creates a command file called THIS.COM and defines
a symbol THIS.  To delete the command procedure and the symbol definition,
enter the command THIS DELETE.

.blank
.indent -5;/STEP

.paragraph
Format:

.paragraph
/STEP={[NO]LINK,[NO]RUN} #####Default -- /STEP=RUN

.paragraph
This qualifier takes on one of two values (the two values can also be negated).
Specifying LINK will cause the compile utility to generate a command procedure
that will only compile and link the program, without attempting to run the
program.  Specifying NOLINK will only cause the program to be compiled.
Specifying NORUN is the same as specifying LINK.  Specifying RUN is the
same as not specifying /STEP at all.

.blank
.indent -5;/INVOKE

.paragraph
Format:

.paragraph
/[NO]INVOKE #####Default -- /INVOKE when /INSTALL not specified,
.break;############################/NOINVOKE when /INSTALL specified

.paragraph
The qualifier /INVOKE will cause the command procedure to be invoked after
it is created.  Specifying /NOINVOKE will prevent the command procedure
not to be invoked.  This can be used to overide the default action.  If
the /INSTALL is missing or negated, the default action is to invoke the
procedure.  If the /INSTALL qualifier is specified, the action is not to
invoke the procedure.

.blank
.indent -5;2 Examples

.nofill;.keep;
COMPILE/BASIC PROG1            -- compiles the file PROG1.BAS
COMPILE PROG1.BAS              -- compiles the file PROG1.BAS
COMPILE PROG1                  -- compiles the file PROG1.  A
                                  search is made for the proper
                                  extension.
COMPILE PROG2.PLI/LIST         -- compiles the file PROG2.PLI and
                                  provides a list file.
COMPILE/LIST/STEP=NORUN PROG2  -- compiles the file PROG2 after
                                  searching for the proper
                                  extension, provides a list file
                                  but does run the program.
COMPILE/INSTALL=COMP PROG3.COB -- generates a command procedure
                                  to compile the COBOL program
                                  PROG3 and writes the command
                                  procedure to the default dir-
                                  ectory, defines a symbol COMP to
                                  invoke the procedure COMP.COM.
.fill;.nokeep;