The $TEXT function 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 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, $TEXT() returns the routine name.
If the entryref does not specify a routine, GT.M assumes the current routine, that is, the routine 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. $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.
To locate the source code, $TEXT() reads information in the routine header. If the image does not contain a copy of the routine, $TEXT() initiates an auto-ZLINK. If $TEXT() cannot locate the source file to which the header points, $TEXT() uses the $ZROUTINES search list to find a source file of the specified name.
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 the empty string.