ZINSERT
Synopsis
ZINSERT:pc "code":location ZI:pc "code":location
Arguments
| 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. The first character must be either a space or a label name. |
| 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 current routine and advances the edit pointer to immediately after the inserted line.
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 places its line of code directly after the last inserted line, unless the next ZINSERT explicitly specifies a location.
ZINSERT 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.
The ZINSERT command is usually executed from the programmer prompt. 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 command.
You can access the $ZNAME special variable to determine the name of the current 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 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.
-
ZSAVE sets the edit pointer to the end of the routine. For example, specifying ZSAVE myroutine then ZINSERT " SET y=2" inserts the line at the end of the routine.
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.
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.
location
The line after which ZINSERT will insert the code. It can take either of the following forms:
| +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, Caché 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":+0inserts 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.
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":+4In 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+6Note 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":+4Notes
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 programmer prompt.
