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.
ZLOAD without an Argument
The ZLOAD command without an argument loads an ObjectScript routine from the current device into the routine buffer. To load a routine from a device, execute the following:
  1. An OPEN command to open the device.
  2. A USE command to make the device the current device.
  3. A ZLOAD command without arguments.
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.
An argumentless ZLOAD command can specify a postconditional expression.
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 display, modify, or remove the currently loaded routine from any namespace. 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.
Source 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.
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