ZSAVE
Synopsis
ZSAVE:pc routine ZS:pc routine
Arguments
| pc | Optional — A postconditional expression. |
| routine | Optional — A new name for the routine. Must be a valid identifier. |
Description
The ZSAVE command saves the current routine. You use ZLOAD to load the routine, then use ZSAVE to save any changes you have made to the routine with ZINSERT and ZREMOVE commands. ZSAVE is also used to name a routine loaded with an argumentless ZLOAD, or a nameless routine created by ZINSERT commands.
ZSAVE moves the edit pointer to the end of the routine. Issuing ZSAVE moves the edit pointer even if no actual save was needed.
If you ZLOAD a routine and then ZSAVE it to the same routine name without making any changes to the routine, Caché does not update the routine’s timestamps or generated flag.
You can use ZSAVE in two contexts: from the Terminal prompt, or invoked by an XECUTE command within a program.
ZSAVE has two forms:
-
Without an argument
-
With an argument
ZSAVE without an argument saves the current routine under its current name (that is, the name under which you previously saved it) on disk in the current namespace. If the current routine does not yet have a name, an argumentless ZSAVE generates a <COMMAND> error.
ZSAVE routine saves the current routine to disk as the specified routine name in the current namespace.
If use the XECUTE command to invoke ZSAVE routine, the system creates a Load frame to preserve the current routine. When the XECUTE command concludes, Caché uses this Load frame to restore the routine name prior to the XECUTE as the current routine. This is shown in the following example:
WRITE "Current routine name",!
WRITE "initial name: ",$ZNAME,!
SET x = "WRITE $ZNAME"
SET y = "ZSAVE mytest"
SET z = "WRITE "" changed to "",$ZNAME,!"
XECUTE x,y,z
WRITE "restored name: ",$ZNAME,! 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
A name under which to save the routine. routine must be a valid routine name. You can use the $ZNAME("string",1) function to determine if string is a valid routine name. You can use the $ZNAME special variable to determine the name of the currently loaded routine.
Commonly, routine is a new name for the routine, but it can be the current routine name. If a routine by that name already exists, Caché overwrites it. Note that you are not asked to confirm the overwrite. A routine name must be unique within the first 255 characters; routine names longer than 220 characters should be avoided.
If you specify ZSAVE routine in an X
If you omit routine, the system saves the routine under its current name. If no current name exists, ZSAVE generates a <COMMAND> error.
Example
The following Terminal session example executes a ZSAVE command to save the currently loaded routine:
USER>DO ^myroutine
this is line 8
this is line 9
USER>ZLOAD myroutine
USER>PRINT +8
WRITE "this is line 8",!
USER>ZREMOVE +8
USER>PRINT +8
WRITE "this is line 9",!
USER>ZSAVE myroutine
USER>DO ^myroutine
this is line 9
USER>
Notes
Where to Use ZSAVE
The ZSAVE command works only when entered at the programmer prompt or when coded within an XECUTE statement in a routine. It should not be coded into the body of a routine because its operation would effect the execution of that routine. If you code ZSAVE in a routine, but outside of an XECUTE statement, that ZSAVE saves the current program.
ZSAVE and Routine Recompilation
If you have issued a command that modifies source code, ZSAVE recompiles and saves the routine. If the source code for the routine is unavailable, ZSAVE fails with a <NO SOURCE> error and does not replace the existing object code. For example, the following commands load the %SS object code routine, attempt to remove lines from the (nonexistent) source code, and then attempt to save to the ^text global. This operation fails with a <NO SOURCE> error:
ZLOAD %SS ZREMOVE +3 ZSAVE ^test
If you have not issued a command that modifies source code, ZSAVE saves the object code in the specified routine. (Obviously, no recompile occurs.) For example, the following commands load the %SS object code routine and then save it to the ^text global. This operation succeeds:
ZLOAD %SS ZSAVE ^test
ZSAVE with % Routines
You receive a <PROTECT> error if you try to ZSAVE a %routine to a remote dataset, even if that dataset is the current dataset for the process. The percent sign prefix is used for the names of non-modifiable routines, such as system utilities.
Concurrent ZSAVE Operations
When using ZSAVE in a networked environment, a situation may occur in which two different jobs might concurrently save a routine and assign it the same name. This operation has the potential for one routine overwriting part of the other, producing unpredictable results. When this possibility exists, acquire an advisory lock on the routine before the ZSAVE operation. For example, LOCK ^ROUTINE("name"). For further details, refer to the LOCK command. When running a job across ECP, the saved source is more vulnerable to such concurrent saves because local buffer protection is not visible to other clients.
