Inserts a line of code in the current routine.
||Optional A postconditional expression.
||A line of ObjectScript code, specified as a string literal (enclosed in quotation marks) or a variable that contains a string literal. The first character must be either a space or a label name.
||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).
This command inserts a line of ObjectScript source code into the current routine and advances the edit pointer to immediately after the inserted line.
" inserts a specified line of ObjectScript code in the current routine at the current edit pointer position.
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.
inserts a line of code, it resets the edit pointer to the end of this new line of code. This means the next ZINSERT
places its line of code directly after the last inserted line, unless the next ZINSERT
explicitly specifies a location
effects only the local copy of the routine. It does not change the routine as stored on disk. To store inserted lines, you must use the ZSAVE
command to save the routine. ZINSERT
incrementally compiles each line.
command is usually executed from the Terminal. It should not be coded into the body of a routine, because its operation would effect the execution of that routine. To call ZINSERT
from a routine, use the XECUTE
You can access the $ZNAME
special variable to determine the name of the current routine.
The edit pointer is set as follows:
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
in Using ObjectScript
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.
The line after which ZINSERT
will insert the code. It can take either of the following forms:
||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.
||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.
||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.
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.
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 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.
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=12
ZINSERT "Altcheck SET y=12":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
You can use the ZREMOVE
command to remove one or more lines of code from the currently executing routine. Thus by using ZREMOVE
, 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, 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.
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.
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
can also supply a line of code to a WRITE
command, and thus supply a code line to the Terminal.