ZSAVE (ObjectScript)
Synopsis
ZSAVE:pc routine
ZS:pc routine
Arguments
Argument | Description |
---|---|
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.
You can only use the ZSAVE 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 ZSAVE in a routine results in a compile error. Any attempt to execute ZSAVE from within a routine also generates an error.
ZSAVE does not move the edit pointer.
If you ZLOAD a routine as the current routine, then:
-
ZSAVE the current routine after modifying it using ZINSERT and/or ZREMOVE: InterSystems IRIS updates the ^rINDEX("MyRoutine","INT") and ^rINDEX("MyRoutine","OBJ") globals to the current timestamp and character count, and updates and the ^ROUTINE("MyRoutine",0) global.
-
ZSAVE the current routine without modifying the current routine: InterSystems IRIS updates the ^rINDEX("MyRoutine","OBJ") global; it does not change the ^rINDEX("MyRoutine","INT") global or the ^ROUTINE("MyRoutine",0) global.
Refer to INT Code and the ^ROUTINE Global for further details.
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 TESTNAMESPACE namespace. The MyRoutine in TESTNAMESPACE 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 "TESTNAMESPACE"
TESTNAMESPACE>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",!
TESTNAMESPACE>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 a different namespace and performs a ZSAVE MyNewRoutine, MyNewRoutine is saved in namespace you changed to, 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, InterSystems IRIS 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. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions.
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, InterSystems IRIS 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.
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.
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>