Optional The routine to be loaded, specified as a simple literal. The routine value is not enclosed with quotes. It is does not have a caret (^) prefix or a file type suffix. It cannot be specified using a variable or expression. If omitted, Caché loads an unnamed routine from the current device.
You can only use the ZLOAD command when you enter it from the Terminal or when you call it using an XECUTE command or a $XECUTE function. It should not be coded into the body of a routine because its operation would affect the execution of that routine. Specifying ZLOAD in a routine results in a compile error. Any attempt to execute ZLOAD from within a routine also generates an error.
Once you use ZLOAD to load a routine as the current routine, you can execute the current routine using the DO command, edit the current routine using ZINSERT and argumented ZREMOVE, display routine lines with ZPRINT, save (and optionally rename) the edited current routine using ZSAVE, and finally unload the current routine using an argumentless ZREMOVE.
The ZLOAD command without an argument loads an unnamed ObjectScript routine into the routine buffer as the current routine for the current process. You can subsequently name this routine using ZSAVEroutine. Note that because the routine is unnamed you cannot use the $ZNAME special variable to determine if a current routine is loaded.
Issue aUSE command to make the device the current device.
Issue an argumentless ZLOAD command to load the routine from the device as the current routine.
Line loading will continue until Caché reads a null string line (""). This loaded routine has no name until you file it with the ZSAVEroutine command.
Create a Routine from the Terminal
You can use an argumentless ZLOAD to create an unnamed routine as the current routine from the Terminal:
At the Terminal prompt, issue an argumentless ZLOAD command.
On the line following, type the first ObjectScript command of the routine (not enclosed with quotes), then press Enter twice. Commonly, this line is a label name or a label name followed by executable ObjectScript code. Executable ObjectScript code must be indented.
At the Terminal prompt, issue ZINSERT commands to add more lines to this current routine.
Optionally, at the Terminal prompt, issue ZSAVEroutine to save this routine with the specified name.
ZLOADroutine loads the INT code version of an existing ObjectScript routine from the current namespace into the routine buffer as the current routine for the current process. INT code does not count or include preprocessor statements.
ZLOAD does an implicit argumentless ZREMOVE when it loads the routine. That is, ZLOAD deletes any routine previously loaded, replacing it with the specified routine. You can use the $ZNAME special variable to determine the currently loaded routine. When ZLOAD loads a routine, it positions the line pointer at the beginning of the routine.
Once loaded, a routine remains the current routine for the process until you load another routine explicitly with a ZLOAD command, remove it with an argumentless ZREMOVE, or implicitly load another routine with a DO or a GOTO command.
As long as the routine is current, you can edit the routine (with ZINSERT and ZREMOVE commands), display one or more lines with the ZPRINT command, or return a single line with the $TEXT function.
An optional postconditional expression. Caché executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). Caché does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using Caché ObjectScript.
The name of an existing ObjectScript routine in the current namespace to be loaded as the current routine. Routine names are case-sensitive.
You must have execute permission for routine to be able to ZLOAD it. If you do not have this permission, Caché generates a <PROTECT> error.
If the specified routine does not exist, the system generates a <NOROUTINE> error. Note that a failed attempt to ZLOAD a routine removes the currently loaded routine.
All subsequent errors for this process append the name of the currently loaded routine. This occurs whether or not the error has any connection to the routine, and occurs across namespaces. For further details, refer to the $ZERROR special variable.
ZLOAD can only load a routine that exists in the current namespace. Once a routine is loaded, it becomes the currently loaded routine for this process in all namespaces. Therefore, you can insert or remove lines, display, execute, or unload the currently loaded routine from any namespace, not just the namespace from which it was loaded. ZSAVE saves the currently loaded routine in the current namespace. Therefore, if the ZLOAD namespace differs from the ZSAVE namespace, the modified version of the routine is saved in the namespace that is current when ZSAVE is issued. Changes are not saved in the version of the routine in the ZLOAD namespace.
If you specify ZLOADroutine, Caché looks for the routine in the pool of routine buffers in memory. If the routine is not there, Caché loads the ObjectScript object code version of the routine into one of the buffers. The ObjectScript INT (intermediate) code remains in the corresponding ^ROUTINE global of the current namespace, but is updated if you make edits then use ZSAVE to save the changes.
For example, ZLOAD MyTest loads the object code version of the routine MyTest (if it is not already loaded). The MyTest routine must be in the current namespace.
In a multi-user environment, you should establish a LOCK protocol to prevent more than one user concurrently loading and modifying the same routine. Each user should acquire an exclusive lock before issuing a ZLOAD on the corresponding routine.
If you omit routine, ZLOAD loads new lines of code that you enter from the current device, usually the keyboard, until you terminate the code by entering a null line (that is, just press <Return>). This routine has no name until you save it with a subsequent ZSAVE command.
The ObjectScript INT (intermediate) code for a routine is stored in the ^ROUTINE global. ^ROUTINE can only access routines in the current namespace. ^ROUTINE displays the INT code version of the routine on disk, not the currently loaded routine.
You can display the INT code for the specified routine using the ZWRITE command:
This display includes the following ^ROUTINE subscripts for the routine MyRoutine:
^ROUTINE("MyRoutine",0)="65309,36923.81262": The local date and time in $HOROLOG format when the INT code version of this routine was last compiled. This timestamp is updated even if no changes were made to the MAC code before re-compiling. If the specified routine is the currently loaded routine, issuing a ZSAVE updates this value if changes were made to the currently loaded routine.
You can view and edit the contents of the ^ROUTINE global using the Management Portal. Select System Explorer, Globals, then select the desired namespace from the drop-down list of namespaces in the left-hand column.
You can delete the ObjectScript INT (intermediate) code using the KILL command:
If the INT code for the routine is unavailable (has been KILLed), the routine can still be executed, but the INT code cannot be modified in the currently loaded routine. ZLOAD, ZINSERT, and ZREMOVE issue no errors, but ZSAVE fails with a <NO SOURCE> error.
ZLOAD and Language Modes
When a routine is loaded, the current language mode changes to the loaded routine’s language mode. At the conclusion of called routines, the language mode is restored to the language mode of the calling routine. However, at the conclusion of a routine loaded with ZLOAD the language mode is not restored to the previous language mode. For further details on checking and setting language modes, refer to the LanguageMode() method of the %SYSTEM.Process class.
The following Terminal example establishes an exclusive lock, then loads the corresponding routine MyRoutine. It displays the first 10 lines of the source code, adds a line of ObjectScript code as line 2, re-displays the source code, saves the changes and releases the lock: