If you wish to focus on program development from the GT.M environment rather than from the VMS environment, you can skip over this section and continue with the section on "Executing from DCL" which follows.
Invoke the LINK utility by entering LINK, followed by the object file names at the DCL prompt. If the object modules are in a library file, as in our introductory example, instruct LINK to refer to that library by using the /LIBRARY qualifier after the name of the library.
Example:
$ LINK PAYROLL,TOOLS/LIB
This LINK command instructs the Linker to combine the modules into one executable image PAYROLL.EXE. The Linker resolves external references in PAYROLL to the labels STATE^TAXES and FEDERAL^TAXES, as well as references to TAXES, LOOKUP and SUM, which are in the TOOLS.OLB library. Note that we do not have to refer to the TAXES, LOOKUP and SUM routines explicitly. Because the example uses the default file extensions, it does not specify them.
When not using a library, link your modules as shown in the following example.
Example:
$ LINK PAYROLL,TAXES,LOOKUP,SUM
This LINK command instructs the Linker to combine the modules into one executable image, PAYROLL.EXE. The Linker resolves external references in PAYROLL to the labels STATE^TAXES, FEDERAL^TAXES, TAXES, LOOKUP and SUM. Note that we must refer to the TAXES, LOOKUP and SUM routines explicitly. Because the example uses the default file extensions, it does not specify them.
GT.M produces the results specified in the ANSI standard for M indirection and XECUTEs. When you use these M features, M defers the resolution of the resulting commands, arguments and expression atoms until run-time. When using indirection in transfers of control, such as with DO and GOTO commands, the compiler generates code that effectively has "place holders" where the entryref components are normally found. When a "place holder" occurs instead of a routine name, the object file gives the Linker no information as to which routines to include in the image. If your application includes routines that are only referenced by indirection or as part of an XECUTE argument, the Linker does not automatically include those routines in the image.
To have indirectly referenced routines included in a link, you must:
Name the routines explicitly with the LINK command or in a Linker options file.
Place indirectly referenced subroutines in modules that have at least one label referenced without indirection.
Create .OBJ files for linking by extracting multiple routines out of a library and placing them into one or more "super" object modules that contain at least one directly referenced label.
Create, and explicitly include in the link, one or more "forcing" routines (use DOs or GOTOs to refer to the modules that you want the Linker to include) that are not actually invoked, but that contain a list of direct references to the labels normally referenced indirectly.
You can include the modules by making either the source or (preferably) the object accessible, usually using $ZROUTINES and relying on auto-ZLINK. Or, you can explicitly ZLINK the modules.
If instead of DO STATE^TAXES and DO FEDERAL^TAXES, our payroll routine uses DO @TAXTYP, we may choose to include TAXES in the LINK, because PAYROLL does not call TAXES directly.
Example:
$ LINK PAYROLL,TOOLS/LIBRARY/INCLUDE=TAXES
The LINK command uses the /INCLUDE qualifier to the file-specification for the library, TOOLS.OLB, to specify the inclusion of the routine TAXES in the run-time image. Although the Linker has access to TOOLS.OBJ, which contains TAXES, it does not "know" to look for TAXES because, by using indirection, the PAYROLL object does not explicitly refer to TAXES.
References in the LINK command are resolved to the right. Thus, if library A is referenced before library B in the LINK command, a program in library B cannot refer to a program in library A. In this case, library B must be referenced again, to the right of library A, or the referenced routine must be specifically included in the run-time image with the INCLUDE command.
The format for the LINK command is:
LINK[/qualifier...] file-spec[/qualifier[...]][...]
The command qualifiers generally determine the kind of output the Linker produces, such as the filename of the executable image, and whether or not the Linker produces a memory allocation map.
Qualifiers may be applied globally by placing them on the LINK command or locally by placing them on a file-specification in the parameter list; local qualifiers override global qualifiers.
The file-specification list and argument qualifiers describe the input to the Linker; for example, they inform the Linker whether the input file is a library or a shared image.
By default, object files have an extension of .OBJ.
VMS does not accept wildcards in a file_specification for a LINK command.
By default, the Linker constructs the file-specification for the output file using the name from the first input file and an extension of .EXE.