Skip to main content

$TEXT (ObjectScript)

Returns a line of source code found at the specified location.

Synopsis

$TEXT(label+offset^routine)
$T(label+offset^routine)

$TEXT(@expr_atom)
$T(@expr_atom)

Arguments

Argument Description
label Optional — A line label in a 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.
+offset Optional — An expression that resolves to a positive integer that identifies the line to be returned as an offset number of lines. If omitted, the line identified by label is returned.
^routine Optional — The name of a routine. Must be a literal value; a variable cannot be used to specify routine. (Note that the ^ character is a separator character, not part of the routine name.) If the routine is not in the current namespace, you can specify the namespace that contains the routine using an extended routine reference, as follows: ^|"namespace"|routine. If omitted, defaults to the currently loaded routine.
@expr_atom An expression atom that uses indirection to supply a location. Resolves to some form of label+offset^routine.

Description

$TEXT returns a line of code found at the specified location. If $TEXT does not find source code at the specified location, it returns the null string.

To identify a single line of source code, you must specify either a label, an +offset, or both. By default, $TEXT accesses the currently loaded routine. Either $TEXT is coded in the currently executing routine, or accesses the currently loaded routine as the static routine most recently loaded using ZLOAD. You can use ^routine to specify a routine location other than the currently loaded routine. You can use indirection (@expr_atom) to specify a location.

$TEXT returns the specified line from the INT code version of a routine. INT code does not count or include preprocessor statements. INT code includes all labels and most comments, but 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.

The +offset argument counts lines using the INT code version of the routine. After modifying a routine, you must re-compile the routine for $TEXT to correctly count lines and line offsets that correspond to the INT version.

In the returned source code, if the first whitespace character in the line is a tab, $TEXT replaces it with a single space character. All other tabs and space characters are returned unchanged. Thus $PIECE($TEXT(line)," ",1) always returns a label, and $PIECE($TEXT(line)," ",2,*) returns all code except a label.

When a routine is distributed as object code only, the ;; comment is the only comment type retained in the object code. Thus only ;; comments are available to $TEXT in those routines. For a ;; comment to be returned by $TEXT, it must either appear on its own line, or on the same line as a label. It cannot appear on a line containing a command, or a line declaring a function or subroutine. For further details on the different types of InterSystems IRIS comments, refer to Comments.

You can use the PRINT or ZPRINT commands to display a single line (or multiple lines) of source code from the currently loaded routine. ZPRINT (or PRINT) sets the edit pointer to the end of the lines it printed. $TEXT does not change the edit pointer.

Arguments

label

The label within the current routine or, if the routine argument is also supplied, a label in the specified routine. Must be specified as a literal, without quotes. Label names are case-sensitive, and may contain Unicode characters. A label may be longer than 31 characters, but must be unique within the first 31 characters. $TEXT matches only the first 31 characters of a specified label.

If you omit the offset option, or specify label+0, InterSystems IRIS prints the label line. label+1 prints the line after the label. If label is not found in the routine, $TEXT returns the empty string.

offset

A positive integer specifying a line count, or as an expression that evaluates to a positive integer. The leading plus sign (+) is mandatory. If specified alone, the +offset specifies a line count from the beginning of the routine, with +1 being the first line of the routine. If specified with the label argument, the line count is calculated from the label location, with +0 being the label line itself, and +1 being the line after the label. If +offset is larger than the number of lines in the routine (or the number of lines from label to the end of the routine) $TEXT returns the empty string.

You can specify an offset of +0. When label is specified, $TEXT(mylabel+0) is the same as $TEXT(mylabel). If you invoke $TEXT(+0), it returns the name of the currently loaded routine.

InterSystems IRIS resolves an +offset value to a canonical positive integer. A negative integer offset value generates a <NOLINE> error.

Note that InterSystems IRIS resolves numbers and numeric strings to canonical form, which involves removal of the leading plus sign (+). For this reason, you must specify the plus sign in the $TEXT function to use it as an offset.

To use a variable as the offset it must be preceded by a plus sign as shown in the following example:

  SET x=7
  WRITE $TEXT(x)    /* because there is no plus sign, search for a label named x  */
  WRITE $TEXT(+x)   /* locates the offset +7 code line */

routine

If specified alone, it indicates the first line of code in the routine. If specified with only the label argument, the line found at that specified label within the routine is returned. If specified with only the offset argument, the line at the specified offset within the routine is returned. If both label and offset are supplied, the line found at the specified offset within the specified label within the routine is returned.

The routine argument must be specified as a literal, without quotes. You cannot use a variable to specify the routine name. The leading caret (^) is mandatory.

By default, InterSystems IRIS searches for the routine in the current namespace. If the desired routine resides in another namespace, you can specify that namespace using extended global reference. For example, $TEXT(mylabel+2^|"SAMPLES"|myroutine). Note that only vertical bars can be used here; square brackets cannot be used. You can specify the namespace portion of ^routine as a variable.

$TEXT returns the empty string if the specified routine or namespace does not exist, or if the user does not have access privileges for the namespace.

expression atom (@expr_atom)

An indirect argument that evaluates to a $TEXT argument (label+offset^routine). For more information, refer to the Indirection Operator reference page.

Examples

The following four examples demonstrate a routine saved with object code only. The first two examples return the referenced line, including the ;; comment. The third and fourth examples return the null string:

Start ;; this comment is on a label line
  WRITE $TEXT(Start)
Start 
  ;; this comment is on its own line
  WRITE $TEXT(Start+1)
Start 
  SET x="fred" ;; this comment is on a command line
  WRITE $TEXT(Start+1)
MyFunc() ;; this comment is on a function declaration line
  WRITE $TEXT(MyFunc)

The following example shows that only the first 31 characters of label are matched with the specified label:

StartabcdefghijklmnopqrstuvwxyzA ;; 32-character label
  WRITE $TEXT(StartabcdefghijklmnopqrstuvwxyzB)

The following example shows the $TEXT(label) form, which returns the line found at the specified label within the current routine. The label is also returned. If the user enters "?", the Info text is written out, along with the line label, and control returns to the initial prompt:

Start
  READ !,"Array name or ? for Info: ",ary QUIT:ary=""
  IF ary="?" {
    WRITE !,$TEXT(Info),! 
    GOTO Start }
  ELSE { DO ArrayOutput(ary) }
  QUIT
Info  ;; This routine outputs the first-level subscripts of a variable.
  QUIT
ArrayOutput(val)
   SET i=1
   WHILE $DATA(@val@(i)) {
     WRITE !,"subscript ",i," is ",@val@(i)
     SET i=i+1
   }
   QUIT

The following example shows the $TEXT(label+offset) form, which returns the line found at the offset within the specified label, which must be within the current routine. If the offset is 0, the label line, with the label, is returned. This example uses a FOR loop to access multiline text, avoiding displaying the label or the multiline comment delimiters:

Start
  READ !,"Array name or ? for Info: ",ary QUIT:ary=""
  IF ary="?" {
    DO Info
    GOTO Start }
  ELSE { DO ArrayOutput(ary) }
  QUIT
Info  FOR loop=2:1:6 { WRITE !,$TEXT(Info+loop) }
     /* 
    This routine outputs the first-level subscripts of a variable.
    Specifically, it asks you to supply the name of the variable
    and then writes out the current values for each subscript
    node that contains data. It stops when it encounters a node
    that does not contain data.
    */
  QUIT
ArrayOutput(val)
   SET i=1
   WHILE $DATA(@val@(i)) {
     WRITE !,"subscript ",i," is ",@val@(i)
     SET i=i+1
   }
   QUIT

The following example uses extended routine reference to access a line of code from a routine in the SAMPLES namespace. It accesses the first line of code after the ErrorTest label in the routine named myroutine. It can be executed from any namespace:

    WRITE $TEXT(ErrorTest+1^|"SAMPLES"|myroutine)

Argument Indirection

Indirection of the entire $TEXT argument is a convenient way to make an indirect reference to both the line and the routine. For example, if the variable ENTRYREF contains both a line label and a routine name, you can reference the variable:

$TEXT(@ENTRYREF)

rather than referencing the line and the routine separately:

$TEXT(@$PIECE(ENTRYREF,"^",1)^@$PIECE(ENTRYREF,"^",2))

See Also

FeedbackOpens in a new tab