ZLOAD:pc routine ZL:pc routine
|pc||Optional — A postconditional expression.|
|routine||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.|
The ZLOAD command loads the INT code version of an ObjectScript routine as the current routine. ZLOAD has two forms:
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.
ZLOAD without an Argument
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 ZSAVE routine. Note that because the routine is unnamed you cannot use the $ZNAME special variable to determine if a current routine is loaded.
Argumentless ZLOAD can be used in two ways:
To load a routine from a sequential file or other device.
To create a routine using the Terminal.
An argumentless ZLOAD command can specify a postconditional expression.
Load a Routine from a Device
To load a routine from a device, execute the following:
Issue an OPEN command to open the device.
Issue a USE 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 ZSAVE routine 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 ZSAVE routine to save this routine with the specified name.
When done, use argumentless ZREMOVE to unload the current routine.
Alternatively, you can use ZINSERT to create an unnamed routine as the current routine from the Terminal.
ZLOAD with an Argument
ZLOAD routine 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.
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.
Routine Behavior with ZLOAD
If you specify ZLOAD routine, 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.
^rINDEX Routine Timestamp and Size
You can use the ^rINDEX global to return the local timestamp and number of characters for the MAC, INT, and OBJ code versions of a routine, as shown in the following Terminal example:
USER>ZWRITE ^rINDEX("MyTest") ^rINDEX("MyTest","INT")=$lb("2019-12-13 06:37:49",475) ^rINDEX("MyTest","MAC")=$lb("2019-12-13 06:34:04.235011",452) ^rINDEX("MyTest","OBJ")=$lb("2019-12-13 06:37:49",476) USER>
The MAC timestamp is when the MAC code was last saved after being modified. The INT and OBJ timestamps are when the MAC code was last compiled. Issuing a ZSAVE after modifying the INT code version updates the INT and OBJ timestamps and character counts. Issuing a ZSAVE without modifying the INT code updates just the OBJ timestamp.
INT Code and the ^ROUTINE Global
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.
^ROUTINE("MyRoutine",0,0)=8: The number of lines in the INT code version of the routine.
^ROUTINE("MyRoutine",0,1)="Main": The first line of the INT code version of the routine. In this case, the label Main.
^ROUTINE("MyRoutine",0,2)=" WRITE ""This is line 2"",!": The second line of the INT code version of the routine. In this case, an indented line of executable ObjectScript code. Additional lines of code follow the same pattern.
^ROUTINE does not reflect ZINSERT, and ZREMOVE changes to the current routine until these changes are saved using ZSAVE.
If the routine was loaded from a MAC code source, the following ^ROUTINE subscripts are also displayed:
^ROUTINE("MyRoutine","GENERATED")=1: Indicating that the INT code was generated.
^ROUTINE("MyRoutine","INC","%occStatus")="65301,60553": If the MAC version contains #Include files, one of these subscripts is included for each #Include file, specifying the timestamp when the #Include file was created.
^ROUTINE("MyRoutine","SIZE")=134: The number of characters in the INT code version of the source file.
^ROUTINE("MyRoutine","MAC")="65309,36920.45721": The local date and time in $HOROLOG format when the MAC version of the routine was last saved. This timestamp is only updated if the MAC code was modified, saved, and then re-compiled.
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:
USER>LOCK +^ROUTINE("MyRoutine") USER>ZLOAD MyRoutine USER>ZPRINT +1:+10 USER>ZINSERT " WRITE ""Hello, World!""":+1 USER>ZPRINT +1:+11 USER>ZSAVE USER>LOCK -^ROUTINE("MyRoutine")
The following Terminal example loads the first routine from the device dev:
USER>OPEN dev USER>USE dev USER>ZLOAD