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

Deletes a line or a range of lines from the current routine, or unloads the current routine.
Synopsis
ZREMOVE:pc lineref1:lineref2 ,...
ZR:pc lineref1:lineref2 ,...
Arguments
pc Optional — A postconditional expression.
lineref1 Optional — The position of a single line, or the first line in a range of lines to be removed. Can be specified as a literal (+5) or a variable (+a). If you omit lineref1, ZREMOVE deletes the entire current routine.
:lineref2 Optional — The position of the last line in a range of lines to be removed.
Description
The ZREMOVE command operates on the currently loaded routine for the current process. Use ZLOAD to load the current routine. ZLOAD loads the INT code version of a routine. INT code does not count or include preprocessor statements. INT code does not count or include completely blank lines from the MAC version of the routine, whether in the source code or within a multiline comment. Once a routine is loaded, it becomes the currently loaded routine for the current 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.
You can only use the ZREMOVE command when you enter it from the Terminal or when you call it using an XECUTE command or a $XECUTE function. Specifying ZREMOVE in the body of a routine results in a compile error. Any attempt to execute ZREMOVE from within a routine also generates an error.
ZREMOVE has two forms:
Without an Argument
ZREMOVE without an argument removes (unloads) the currently loaded routine. Following an argumentless ZREMOVE, $ZNAME returns the empty string rather than the name of the current routine, and ZPRINT displays no lines. Because the routine has been removed, you cannot use ZSAVE to save the routine; attempting to do so results in a <COMMAND> error.
The following Terminal session shows this operation:
USER>ZLOAD myroutine

USER>WRITE $ZNAME
myroutine
USER>ZREMOVE

USER>WRITE $ZNAME

USER>
An argumentless ZREMOVE can specify a postconditional expression.
ZREMOVE with an argument can remove all the lines of the current routine, but does not remove the current routine itself. For example, ZREMOVE +1:NonexistentLabel removes all of the lines of the current routine, but you can use ZINSERT to insert new lines and use ZSAVE to save the routine.
With Arguments
ZREMOVE with arguments erases code lines in the current routine. ZREMOVE lineref1 erases the specified line. ZREMOVE lineref1:lineref2 erases the range for lines starting with the first line reference and ending with the second line reference, inclusive. It advances the edit pointer to immediately after the removed line(s). Therefore a ZREMOVE lineref1 followed by a ZINSERT replaces the specified line.
ZREMOVE can remove multiple lines (or multiple ranges) of ObjectScript source code by specifying a comma-separated series of any combination of lineref1 or lineref1:lineref2 arguments. Each specified line or range of lines of code is removed as a separate remove operation in the order specified.
You can use ZPRINT to display multiple lines of the currently loaded routine. You can execute the current routine using the DO command.
Only the local copy of the routine is affected, not the routine as stored on disk. To store the modified code, you must use the ZSAVE command to save the routine.
The following Terminal session shows this operation. This example uses a dummy routine (^myroutine) in which each line sets a variable to a string naming that line:
USER>ZLOAD myroutine

USER>ZPRINT +8
  WRITE "this is line 8",!
USER>ZREMOVE +8

USER>PRINT +8
  WRITE "this is line 9",!
USER>
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.
lineref1
The line to be removed, or the first in a range of lines to be removed. It can take any of the following formats:
+offset Specifies a line number within the routine. A positive integer, counting from 1.
label Specifies a label within the routine. ZREMOVE label erases only the label line itself. This includes any code that follows the label on that line.
label+offset Specifies a label and the number of line to offset within the labeled section, counting the label line as line 1.
A label may be longer than 31 characters, but must be unique within the first 31 characters. ZREMOVE matches only the first 31 characters of a specified label. Label names are case-sensitive, and may contain Unicode characters.
You can use lineref1 to specify a single line of code to remove. You specify the code line either as an offset from the beginning of the routine (+lineref1) or as an offset from a specified label (label+lineref1).
The INT code lines include all labels, comments, and whitespace found in the MAC version of the routine, with the exception that entirely blank lines in a MAC routine, which are removed by the compiler, are neither displayed nor counted in INT code. Blank lines in a multi-line comment are also removed. The #;, ##;, and /// comments in the MAC code may not appear in the INT code, and thus may affect line counts and offsets. Refer to Comments in MAC Code for Routines and Methods for further details.
lineref2
The last line in a range of lines to be removed. Specify lineref2 in any of the formats used for lineref1. The colon prefix (:) is mandatory.
You specify a range of lines as +lineref1:+lineref2. ZREMOVE removes the range of lines, inclusive of lineref1 and lineref2. If lineref1 and lineref2 refer to the same line, ZREMOVE removes that single line.
If lineref2 appears earlier in the routine code than lineref1, no operation is performed and no error is generated. For example: ZREMOVE +7:+2, ZREMOVE Test1+1:Test1, ZREMOVE Test2:Test1 would perform no operation.
Note:
Use caution when specifying a label name in lineref2. Label names are case-sensitive. If lineref2 contains a label name that does not exist in the routine, ZREMOVE removes the range of lines from lineref1 through the end of the routine.
Examples
This command erases the fourth line within the current routine.
   ZREMOVE +4
This command erases the sixth line after the label Test1; Test1 is counted as the first line.
   ZREMOVE Test1+6
This command erases lines three through ten, inclusive, within the current routine.
   ZREMOVE +3:+10
This command erases the label line Test1 through the line that immediately follows it, within the current routine.
   ZREMOVE Test1:Test1+1
This command erases all of the line from label Test1 through label Test2, inclusive of both labels, within the current routine.
   ZREMOVE Test1:Test2
See Also


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