As discussed in the section on compiling source programs, the GT.M command ZLINK compiles the source code into an object module, then adds the object module to the current image.
The run-time system provides auto-ZLINKing whenever an M command references a routine that is not part of the current image. If a program or a Direct Mode command references a routine that was not referenced in the LINK of the image and has not been previously used, that is, is not part of the current image, the run-time system provides auto-ZLINKing.
M commands and functions that may cause auto-ZLINKing are:
DO
GOTO
ZBREAK
ZGOTO
ZPRINT
$TEXT()
GT.M auto-ZLINKs the routine only under these conditions:
ZLINK can locate the routine file using $ZROUTINES or the current directory if $ZROUTINES is null.
The name of the routine is the same as the name of the source file.
The referencing routine has not been the subject of a missing reference error in a VMS LINK of the image.
ZLINK and auto-ZLINK require the name of the routine to be the same as the name of the source file.
The ZLINK method is preferred over LINKing for:
Adding modifications to code during a debugging session.
Adding generated code to a running M process.
Making changes to a production system between LINKs.
Providing access to seldom used parts of a system that are not part of the "everyday" image.
This allows the normal size of the image to be reduced for faster image startup and rundown and still permits access to the entire system when necessary.
When the argument to a ZLINK command includes a file-specification, $ZSOURCE maintains that file-specification as a default for ZEDIT and ZLINK.
$ZSOURCE is a read-write special variable that maintains this default file-specification. $ZSOURCE initially contains the null string.
Once you use the ZEDIT or ZLINK commands, $ZSOURCE contains a partial file specification. The partial file specification consists of a device name, a directory path and a file name. The file specification may contain a file type but not a version number. You can set $ZSOURCE with an M SET command.
A ZLINK without an argument is equivalent to ZLINK $ZSOURCE. For more information on $ZSOURCE, refer to the "Intrinsic Special Variables" chapter in this manual.
Example:
GTM>ZLINK "TAXES"
If ZLINK finds TAXES.M or TAXES.OBJ, the command adds the routine "TAXES" to the current image. When ZLINK cannot locate TAXES.OBJ, or when it finds TAXES.OBJ is older that TAXES.M, it compiles TAXES.M, producing a new TAXES.OBJ, nad adds the contents of the new object file to the image. For more information on ZLINK operation, refer to the "Commands" chapter in this manual.
When the intrinsic special variable $ZROUTINES is not null, a ZLINK command that does not specify a directory uses $ZROUTINES to locate files. When $ZROUTINES is null, ZLINK uses the current directory. For more information on $ZROUTINES, refer to the "Intrinsic Special Variables" chapter in this manual.
When the file-specification includes an explicit directory, ZLINK searches only that directory. If you specify a ZLINK with a directory other than your default and with no file extension, GT.M searches for both the object and the source in the named directory. If a compile is required, ZLINK places the new object file in the default directory. A ZLINK repeated under these conditions always recompiles, since GT.M will never find the object file in the specified directory, and adds object modules to the default directory. To avoid this, move the object module to the named directory, move the source to the default directory, or set $ZROUTINES to the named directory before ZLINKing.
Auto-ZLINK uses the same method for locating and selecting a file as does an explicit ZLINK without a specified directory and file extension.
ZLINK cannot change a currently active routine, that is, a routine displayed in a ZSHOW "S" of the stack. ZLINK a currently active routine by first removing it from the M stack, using a ZGOTO, or one or more QUITs.
Because RMS does not permit the percent sign in a file name, if the name of the routine to ZLINK begins with a percent (%) sign, GT.M uses an underscore (_) in place of the percent in the file-specification.
Example:
GTM>ZLINK "_MGR"
This ZLINK links the M routine %MGR into the current image.
Example:
GTM>ZLINK "[SMITH]TAXES.M":"/OBJ=[]"
This ZLINK compiles TAXES.M in the directory [SMITH] to produce TAXES.OBJ in the current default directory, and then includes the new object file in the current image.