M source programs can be executed either from the shell or from GT.M (Direct Mode).
As discussed in the section on compiling source programs, the GT.M command ZLINK compiles the source code into an object module and adds the object module to the current image.
The run-time system also invokes auto-ZLINKing when an M command, in a program or in Direct Mode, refers to a routine that is not part of the current image.
M commands and functions that may initiate auto-ZLINKing are:
DO
GOTO
ZBREAK
ZGOTO
ZPRINT
$TEXT()
GT.M auto-ZLINKs the routine only under these conditions:
The routine has the same name as the source file.
ZLINK can locate the routine file using $ZROUTINES, or the current directory if $ZROUTINES is null.
$ZROUTINES is a read-write special variable that contains a directory search path used by ZLINK and auto-ZLINK to locate source and object files.
When the argument to a ZLINK command includes a pathname, $ZSOURCE maintains that pathname as a default for ZEDIT and ZLINK. $ZSOURCE is a read-write special variable.
Once you use the ZEDIT or ZLINK commands, $ZSOURCE can contain a partial file specification. The partial file specification can be a directory path (full or relative), a file name, and a file extension. You can set $ZSOURCE with an M SET command. A ZLINK without an argument is equivalent to ZLINK $ZSOURCE.
For additional information on $ZSOURCE and $ZROUTINES, refer to Chapter 8: “Intrinsic Special Variables”.
Example:
GTM>ZLINK "taxes"
If ZLINK finds taxes.m or taxes.o, the command adds the routine taxes to the current image. When ZLINK cannot locate taxes.o, or when it finds taxes.o is older than taxes.m, it compiles taxes.m, producing a new taxes.o. Then, it adds the contents of the new object file to the image.
A ZLINK command that does not specify a directory uses $ZROUTINES to locate files. When $ZROUTINES is null, ZLINK uses the current directory. $ZROUTINES is initialized to the value of the gtmroutines environment variable.
When the file being linked includes an explicit directory, ZLINK and auto-ZLINK searches only that directory for both the object and the source files. If compilation is required, ZLINK places the new object file in the named directory.
A subsequent ZLINK searching for this object file will never find the object file in the specified directory unless the directory is added to the search path in $ZROUTINES, or the object file is moved to another directory already in the search path.
ZLINK cannot change a currently active routine, (e.g., a routine displayed in a ZSHOW "S" of the stack). ZLINK a currently active routine by first removing it from the M stack, using ZGOTO, or one or more QUITs. For additional information on the functionality of ZGOTO and ZSHOW, see their entries in Chapter 6: “Commands”.
To maintain compatibility with other editions of GT.M that do not permit the percent sign (%) in a file name, GT.M uses an underscore (_) in place of the percent in the file name.
Example:
GTM>zlink "_MGR"
This ZLINK links the M routine %MGR into the current image.
