ZINSERT (ObjectScript)
Synopsis
ZINSERT:pc "code":location ,...
ZI:pc "code":location ,...
Arguments
Argument | Description |
---|---|
pc | Optional — A postconditional expression. |
code | A line of ObjectScript code, specified as a string literal (enclosed in quotation marks) or a variable that contains a string literal. For executable code, the first character must be a space. A line beginning with no space is treated as a label name. A line of code can include a label name followed by executable code. |
:location | Optional — The line after which ZINSERT inserts the code. Can be a label name, a numeric offset (+n) or a label name and a numeric offset. If you omit location, the code is inserted at the current line location (edit pointer). |
Description
This command inserts a line of ObjectScript source code into the currently loaded routine and advances the edit pointer to immediately after the inserted line. You can insert multiple lines of ObjectScript source code as a comma-separated series of code:location arguments. Lines of code are inserted as separate insert operations in the order specified.
From the Terminal, use ZLOAD to load a 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 ZINSERT command when you enter it from the Terminal or when you call it using an XECUTE command or a $XECUTE function. Specifying ZINSERT in the body of a routine results in a compile error. Any attempt to execute ZINSERT from within a routine also generates an error.
-
ZINSERT "code" inserts a specified line of ObjectScript code in the current routine at the current edit pointer position.
-
ZINSERT "code":location inserts the specified line of code in the current routine after the specified line location. You can specify a line location as the number of lines offset from the beginning of the routine, as a label, or as the number of lines offset from a specified label.
After ZINSERT inserts a line of code, it resets the edit pointer to the end of this new line of code. This means the next ZINSERT (or the next line of code in a ZINSERT comma-separated sequence of arguments) places its line of code directly after the last inserted line, unless the next ZINSERT explicitly specifies a location.
ZINSERT incrementally compiles each line. You can execute the current routine using the DO command.
ZINSERT effects only the local copy of the current routine. It does not change the routine as stored on disk. To store inserted lines, you must use the ZSAVE command to save the current routine.
You can access the $ZNAME special variable to determine the name of the current routine. You can use ZPRINT to display multiple lines of the currently loaded routine.
The Edit Pointer
ZINSERT moves the edit pointer.
The edit pointer is set as follows:
-
ZLOAD sets the edit pointer to the beginning of the routine.
-
ZINSERT sets the edit pointer to immediately after the line it inserts. For example, specifying ZINSERT " SET x=1":+4 then ZINSERT " SET y=2" inserts lines 5 and 6.
-
ZREMOVE sets the edit pointer to the line it removes. For example, specifying ZREMOVE +4 then ZINSERT " SET y=2" removes line 4 and replaces line 4 with the inserted line.
-
ZPRINT (or PRINT) sets the edit pointer to the end of the lines it printed. For example, specifying ZPRINT then ZINSERT " SET y=2" inserts the line at the end of the routine; specifying ZPRINT +1:+4 then ZINSERT " SET y=2" inserts the line as line 5. The $TEXT function prints a single line from the current routine but does not change the edit pointer.
-
ZSAVE does not change the edit pointer.
-
DO does not change the edit pointer.
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.
code
A line of ObjectScript code, specified as a string literal (in quotes), or a variable that contains a string literal. This line of code can contain one or more ObjectScript commands, a new label name, or both a label and one or more commands. Because the code is inserted into a routine, it must follow ObjectScript formatting. Therefore, the first character of the code string literal must either be a blank space (standard ObjectScript indentation) or a label. The enclosing quotation marks are required. Since quotation marks enclose the line of code you are inserting, quotes within the code itself must be doubled.
You can use the CheckSyntax()Opens in a new tab method of the %Library.RoutineOpens in a new tab class to perform syntax checking on a line of code before inserting it. Both CheckSyntax() and ZINSERT require one or more spaces before an executable line of ObjectScript code, and parse a line with no indentation as a label, or a label followed by executable code. Neither CheckSyntax() nor ZINSERT parse macro preprocessor code.
location
The line after which ZINSERT will insert the code. It can take either of the following forms:
Format | Description |
---|---|
+offset | An expression that resolves to a positive integer that identifies a line location as an offset number of lines from the beginning of the routine. ZINSERT inserts its code line immediately after this specified line. To insert a line at the beginning of the routine, specify +0. The plus sign is mandatory. If you omit +offset, the line identified by label is located. |
label | A existing line label in the current routine. Must be a literal value; a variable cannot be used to specify label. Line labels are case-sensitive. If omitted, +offset is counted from the beginning of the routine. |
label+offset | Specifies a label and a line count offset within the labelled section. If you omit the +offset value, or specify label+0, InterSystems IRIS locates the label line and inserts immediately after it. |
ZINSERT is only for use with the current routine. Attempting to specify label^routine for the location generates a <SYNTAX> error.
Lines of code are numbered beginning with 1. Thus a location of +1 inserts a line of code after the first line of the routine. To insert a line at the start of the routine or the start of a labelled section (before the existing first line), use an offset of +0. For example:
ZINSERT "Altstart SET c=12,d=8":+0
inserts the code line at the start of the routine. By using an offset of +0 (or omitting the location), you can insert a line into an otherwise empty current routine.
You can use the ^ROUTINE global to return the line numbering for an INT routine. Note that ^ROUTINE returns the version of the INT routine saved on disk; it does not return any unsaved changes made to the current routine. ^ROUTINE does not change the edit pointer.
A label may be longer than 31 characters, but must be unique within the first 31 characters. ZINSERT matches only the first 31 characters of a specified label. Label names are case-sensitive, and may contain Unicode characters.
The INT code lines include all labels, comments, and whitespace, with the exception that entirely blank lines in a MAC routine, which are removed by the compiler, are neither displayed nor counted. 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.
ZINSERT and ZREMOVE
You can use the ZREMOVE command to remove one or more lines of code from the currently executing routine. Thus by using ZREMOVE and ZINSERT, you can substitute a new code line for an existing code line. These operations only affect the copy of the routine currently being run by your process.
ZINSERT inserts a line after the specified location. ZREMOVE removes a line at the specified location. For example, if you insert a line with ZINSERT " SET x=1":+4, to remove this line you must specify ZREMOVE +5.
ZINSERT, XECUTE, and $TEXT
You use the XECUTE command to define and insert a single line of executable code from within a routine. You use the ZINSERT command to define and insert by line position a single line of executable code from outside a routine.
An XECUTE command cannot be used to define a new label. Therefore, XECUTE does not require an initial blank space before the first command in its code line. ZINSERT can be used to define a new label. Therefore ZINSERT does require an initial blank space (or the name of a new label) before the first command in its command line.
The $TEXT function permits you to extract a line of code by line position from within a routine. $TEXT simply copies the specified line of code as a text string; it does not affect the execution of that line or change the current line location (edit pointer) when extracting from the current routine. (Using $TEXT to extract code from a routine other than the current routine does change the current line location.) $TEXT can supply a line of code to the XECUTE command. $TEXT can also supply a line of code to a WRITE command, and thus supply a code line to the Terminal.
You use the XECUTE command to define and insert a single line of executable code from within a routine. You use the ZINSERT command to define and insert by line position a single line of executable code from outside a routine.
Using ZINSERT to Create a Routine
If there is no current routine, you can use ZINSERT to create an unnamed routine as the current routine.
-
At the Terminal prompt, issue a ZINSERT command specifying the first line of ObjectScript code. Commonly, this line is either a label name or a label name followed by executable ObjectScript code. If this first line contains a label name, you can use DO to execute this routine without saving it. Otherwise, you must use ZSAVE routine to name and save this routine before you can execute this code.
-
At the Terminal prompt, issue additional ZINSERT commands to add lines to the current routine.
-
If you wish to save the routine, issue ZSAVE routine at the Terminal prompt to save this routine with the specified name.
-
When done, use argumentless ZREMOVE to unload the current routine.
Using the Tab Key Shorthand to Create a Routine
If there is no current routine, the Terminal also recognizes a shorthand for creating a routine which uses the Tab key. With the exception of the first line (see below), the Tab key effectively acts as a substitute for the ZINSERT command.
-
At the Terminal prompt, provide the desired name for your routine (routine) then press Tab and enter the first line of the routine.
-
For each line you wish to add to the current routine, enter the line at the Terminal prompt preceded by a Tab.
-
Press Enter to complete this input.
-
To execute the routine, invoke the DO command, passing the routine name as the argument. (Do not, however, include a caret before the routine name; see the following example.)
-
When done, invoking ZREMOVE unloads the current routine, regardless of whether you provide routine as an argument.
For example, the following sequence of commands creates a simple routine called counter that writes the numbers 1 through 10, and then calls it:
USER>counter Tab for i=1:1:10 { USER>Tab write i,! USER>Tab } USER>DO counter
Using this shorthand, ZPRINT behaves normally. Unlike a routine created with explicit use of the ZLOAD and ZINSERT commands, you cannot specify a name for the routine after the fact using ZSAVE.
Examples
The following example inserts the code line SET x=24 after the fourth line within the current routine. Because this inserted code line does not begin with a label, an initial space must be included as the required line start character.
ZINSERT " SET x=24":+4
The following example inserts three code lines. It inserts SET x=24 after the fourth line within the current routine. It then inserts SET z=1 at the current edit pointer position (just after SET x=24) because the second code line does not specify a location It then sets SET y=1 at the new line location +5 (between SET x=24 and SET z=1):
ZINSERT " SET x=24":+4," SET z=1"," SET y=1":+5
In the following example, assume that the currently loaded routine contains a label called "Checktest". The ZINSERT command inserts a new line after the sixth line within Checktest (Checktest+6). This new line contains the label "Altcheck" and the command SET y=0.
ZINSERT "Altcheck SET y=0":Checktest+6
Note that because the inserted code line begins with the label “Altcheck”, no initial space is required after the quotation mark.
The following example inserts the code line SET x=24 WRITE !,"x is set to ",x after the fourth line within the current routine. Because an inserted code line is enclosed in quotation marks, the quotation marks in the WRITE command must be doubled.
ZINSERT " SET x=24 WRITE !,""x is set to "",x":+4