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

Saves the current routine.
Synopsis
ZSAVE:pc routine
ZS:pc routine
Arguments
pc Optional — A postconditional expression.
routine Optional — A new name for the routine, specified as a simple literal. Must be a valid identifier. Routine names are case-sensitive. 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.
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.
Caution:
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:
ZSAVE Without an Argument
ZSAVE without an argument saves the current routine under its current name. This is the name specified in ZLOAD, or the name under which you previously saved it using ZSAVE. ZSAVE saves the routine in the current namespace.
The following example loads a routine from the USER namespace, modifies the routine, then changes to a different namespace and performs a ZSAVE. The results of these operations are that there are now routines named MyRoutine in both the USER and SAMPLES namespace. The MyRoutine in SAMPLES contains the inserted line of code. The MyRoutine in USER does not contain the inserted line of code:
USER>ZLOAD MyRoutine

USER>ZPRINT +1:+4
   WRITE "this is line 1",!
   WRITE "this is line 2",!
   WRITE "this is line 3",!
   WRITE "this is line 4",!

USER>ZINSERT "  WRITE 123,!":+3

USER>ZPRINT +1:+5
   WRITE "this is line 1",!
   WRITE "this is line 2",!
   WRITE "this is line 3",!
   WRITE 123,!
   WRITE "this is line 4",!

USER>ZNSPACE "SAMPLES"

SAMPLES>ZPRINT +1:+5
   WRITE "this is line 1",!
   WRITE "this is line 2",!
   WRITE "this is line 3",!
   WRITE 123,!
   WRITE "this is line 4",!

SAMPLES>ZSAVE
If the current routine does not yet have a name, an argumentless ZSAVE generates a <COMMAND> error.
An argumentless ZSAVE command can specify a postconditional expression.
ZSAVE With an Argument
ZSAVE routine saves the current routine to disk as the specified routine name. It makes the specified routine the current routine. For example, if you load a routine named MyRoutine, modify it, then save it with ZSAVE MyNewRoutine, the current routine is now MyNewRoutine, which contains the changes. The routine named MyRoutine does not contain these changes, and it is no longer loaded as the current routine.
ZSAVE routine saves the current routine in the current namespace. For example, if you load a routine named MyRoutine from the USER namespace, modify the routine, then change to the SAMPLES namespace and performs a ZSAVE MyNewRoutine, MyNewRoutine is saved in namespace SAMPLES, not the USER 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,! 
 
ZSAVE routine is used to name a routine loaded with an argumentless ZLOAD.
ZSAVE routine is used to name a nameless routine created by ZINSERT commands.
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 in the current namespace, 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 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 ^test 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 ^test 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.
See Also


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