docs.intersystems.com
Caché ObjectScript Reference
ZLOAD
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Search:    

Loads a routine into the current routine buffer.
Synopsis
ZLOAD:pc routine
ZL:pc routine
Arguments
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.
Description
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:
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:
  1. Issue an OPEN command to open the device.
  2. Issue aUSE command to make the device the current device.
  3. 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:
  1. At the Terminal prompt, issue an argumentless ZLOAD command.
  2. 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.
  3. At the Terminal prompt, issue ZINSERT commands to add more lines to this current routine.
  4. Optionally, at the Terminal prompt, issue ZSAVE routine to save this routine with the specified name.
  5. 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.
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.
Arguments
pc
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.
routine
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.
Notes
Namespaces
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.
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.
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.
Examples
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
See Also


Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA