Returns source text for the line specified by its argument.
The format for the $TEXT function is:
$T[EXT](entryref)
The entryref specifies the label, offset, and routine (or trigger name) of the source line that $TEXT() returns.
If the label+offset combination do not fall within the routine, $TEXT returns a null string.
If the entryref explicitly or implicitly specifies an offset of zero (0) from the beginning of the routine (or trigger name), $TEXT() returns the routine name or trigger name.
If the entryref does not specify a routine/trigger, GT.M assumes the current routine/trigger, that is, the routine/trigger at the top of a ZSHOW "S."
A GT.M extension to $TEXT() permits negative offsets; however, every offset must still be preceded by a plus sign (+) delimiter, (for example, LABEL+-3). If a negative offset points to a line prior to the zero line, $TEXT() generates a run-time error.
$TEXT() provides a tool for examining routine source code and the name of the current routine or trigger. $TEXT() assists, along with the ZPRINT command, in debugging programs. $TEXT() also allows the insertion of small tables of driver information into a routine. Because $TEXT() is not very efficient and the table-driven technique is generally best suited to minimal program changes, this approach is best used for prototyping and the tables should reside in global variables for production.
If $TEXT() cannot access the source file for the current object, either because it is not in the location from which it was compiled or because the process does not have access to some piece of the path to the source, or if the located source does not match the object currently in use by the process, $TEXT() returns an empty string.
Example:
for i=1:1 set x=$text(+i) quit:x="" write !,x
This loop uses $TEXT() to write out the entire source for the current routine.
Example:
GTM>write $text(+0) GTM$DMOD GTM>write $text(+1) GTM>
This uses $TEXT() to WRITE the name of the current routine, then it tries to access the source and returns an empty string. This occurs because the default Direct Mode image is compiled by FIS and delivered without source. The exact failure message may vary.