Guardian Procedure Calls Reference Manual

means that this is a reference parameter, that is, the address of the parameter is passed.
(The statements within the program must access the actual parameter contents indirectly
ref:x
through the parameter location.) x indicates the number of elements the parameter
contains. In this example, * indicates that the number of elements in the nodename
parameter depends on another variable (in this case, length).
means the parameter is a reference parameter accessed by an extended pointer..EXT
If a parameter is defined as “STRING:ref,” or “STRING .EXT:ref,” an integer variable can be passed for
“STRING:ref” parameter in TAL, the compiler produces instructions to convert address of the integer variable
to the address (as a number of 8- bit characters) of the first character (byte) of that integer variable; this
conversion is erroneous if the original address is greater than 32767. For “STRING:ref,” parameters in TAL
or for pTAL, no address conversion is necessary and the limit does not apply.
This describes the information that is passed or returned in the parameter.7
String Output Variables
The syntax for some Guardian procedures contains one or more sets of three parameters that are
grouped together, where each set describes a string output variable. Figure 2 shows an example
of this use.
Note that the first two parameters are separated by a colon. (See Figure 1-1 for a general
description of the use of two parameters separated by a colon.) The filename parameter is an
output parameter that contains a character string on return; maxlen is an input parameter that
specifies the maximum number of characters that can be returned in filename;
filename-length is an output parameter that returns the actual number of characters returned
in filename.
When three parameters are grouped in this fashion, all of them must be either present or absent.
If only one or two of them are present, an error is returned.
Figure 2 Syntax With String Output Variable
Reference Parameter Overlap
No variable that you supply as an output parameter in a call to a Guardian procedure should
have the same address as, or overlap, any other reference parameter to the procedure. The only
exceptions to this occur where the procedure description explicitly allows such use.
Bounds Checking of Reference Parameters for Guardian Procedures
Starting in the D20 RVU, bounds checking of reference parameters to Guardian procedures is
different. The change does not affect programs that call procedures with correct parameters that
are within bounds; these programs will continue to work correctly.
In some cases where reference parameters to Guardian procedures point to areas that were formerly
considered out of bounds, the procedure might not detect the error. If the out-of-bounds parameter
would either breach security or compromise system integrity, however, it will continue to be detected.
As an example, many Guardian procedures now use a local data stack that is separate from the
user's local data stack. Before D20, it was an error to specify a reference to an array that extended
beyond the end of the user's local data area into the data area of the called Guardian procedure.
Starting in D20, you cannot rely on a Guardian procedure to return an error when you specify a
reference parameter in this manner. Those Guardian procedures that use a different local data
stack copy the caller's parameters to that stack before proceeding. Because the reference parameter
does not then intrude into the Guardian procedure's local data stack, it does not cause a bounds
violation error. It is possible, however, that the process will abnormally terminate on return from
Reference Parameter Overlap 35