Section 2.3

2.3 PARAMETERS AND PARAMETER QUALIFIERS

Values are passed to and from procs through parameters and parameter qualifiers. Parameters and parameter qualifiers are defined with the PARM command in all procs. See Section 3.4.2.15 for details on the PARM command.

2.3.1 Attributes of Parameters

The parameter attributes specify how the parameter value is handled when the proc is invoked. The parameter attributes, each of which is specified in the PARM command, are:

the parameter name;
the type of the parameter: INTEGER, REAL, STRING, FILE, KEYWORD, NAME, or VOID (see below for a discussion of KEYWORD and NAME parameters);
the minimum and maximum component values the parameter may have;
the default value, that is, the value used if no value is specified by the invoker of the proc;
an acceptable set of values (or ranges of values) for the parameter;
if the parameter is a file parameter, whether the file is an input, output, or input/output file;
the name of the proc defining parameter qualifiers.

2.3.2 NAME Parameters

If a parameter has type NAME, then the value of the parameter when the proc is invoked is expected to be the name of another variable. Whereas INTEGER, REAL, STRING and FILE parameters may be used only to pass values into a proc, NAME parameters permit values to be passed as output from a proc.

As an example, consider the PDF named ADDONE:

PROCEDURE
PARM  L  TYPE=NAME
BODY
LET L=L+1
END-PROC

The following portion of a procedure causes the variable J to be incremented:

PROCEDURE
LOCAL  J  TYPE=INTEGER,  INITIAL=0
     .
     .
     .
ADDONE J
     .
     . 
     .

Equivalently (but perhaps less descriptively), the following may also be used:

ADDONE  L=J

If L had been declared TYPE=INTEGER rather than TYPE=NAME, then the proc invocation line above would have failed because ADDONE would require an integer whereas "J" is a string constant; a NAME parameter requires as a value the name of a variable.

2.3.3 KEYWORD Parameters

If a parameter has type KEYWORD, then the value of the parameter must be one of a set of key values defined in a VALID list. The name of a KEYWORD parameter does not have to be explicitly specified when the proc is invoked: the single quote character may be used to flag a string value as a key; TAE automatically associates the value with a KEYWORD parameter.

Flagged key values must appear after parameters. Abbreviations are allowed provided the abbreviation is sufficient to avoid ambiguity among all of the KEYWORD parameters. For the proc named "keydemo":

PROCESS
PARM X      TYPE=INTEGER
PARM Y      TYPE=INTEGER
PARM Z      TYPE=INTEGER  DEFAULT= 1
PARM LIST   TYPE=KEYWORD VALID=(LIST, NOLIST)  +
            DEFAULT=NOLIST
PARM FORMAT TYPE=KEYWORD VALID=(BYTE, HALF, FULL)  +
            DEFAULT=BYTE
END-PROC

The following are proper command lines referencing "keydemo":



keydemo 1,2, 'BYTE
keydemo 1,2,'B, 'NOL, Z=3
keydemo 1,2, Z=3 'NOLIST
keydemo 1,2, LIST=NOLIST FORMAT=BYTE
keydemo 1,2,3,NOLIST,BYTE      !this is valid because positional
keydemo 1,2,3,'NOLIST, 'BYTE   !equivalent

Note that to avoid ambiguity, the valid list of key values may not contain any of the same values as another keyword parameter.

2.3.4 Parameter Qualifiers

Parameter qualifiers are sub-parameters associated with a parameter. Each parameter qualifier is defined with the PARM statement. All qualifiers to a specific parameter are defined within one proc and are associated with the parameter through the QUALS field of the PARM statement. For example:

PARM FILEl TYPE=STRING QUALS=FILEQ

where FILEQ is the name of a proc. The declarations for the parameters in FILEQ become the declarations for the qualifiers of the parameter FILEl. FILEQ may be any valid proc, even an internal proc (Section 2.9). FILEQ is located the same way as the proc invocation in a procedure is located (See Section 2.1.2). The parameter qualifiers have attributes in the same way that parameters have attributes (See Section 2.3.1).

There is no explicit limit to the nesting of qualifiers. Parameter P may, for example, be qualified by qualifier Q1, which may, in turn by qualified by Q2, etc. However, tutor may only be used for setting one level of qualifiers and there is a limit on the length of the qualified variable name in some contexts to 76 characters.

The QUALS= string may be a full TCL command line. This allows you to set new defaults and also restore a parfile:

parm x quals="y|restore=y| z=2" parm y quals="y|restore=yy| z=3"

Thus parms with the same qualifier set do not have to have the same defaults. If the TCL string contains a vertical bar (|) or a space, it must be quoted.

A parameter qualifier may be referenced wherever a parameter is referenced. Parameter qualifiers are referenced by appending the qualifier name to the end of the parameter name, separating the names with only a period (.). This string of parameter name, and qualifier name is known as the full qualifier name. The use of the full qualifier name in function or subroutine calls will be addressed in a later section. See the "TAE Command Language (TCL) User's Manual" for how parameter qualifier values are specified for proc activation, under tutor or command mode.

The following restriction applies to qualifiers:

A parameter of type NAME will not be accepted as a qualifier. If a NAME parameter is used for a qualifier, no error message is given, but the parameter is removed from the qualifier list.

2.3.5 Dynamic Parameters

Dynamic parameters are parameters or parameter qualifiers that the proc solicits from an interactive user after proc execution has started. If the proc is a procedure, it requests the parameters using the TCL GETPAR command; if the proc is a process, it solicits the parameters using the XQ/XR packages (Section 3.1 of the "TAE Command Language (TCL) Runtime Services, Volume 2:FORTRAN" manual), the p_ package, the q_ package (Section 3.9 in the "TAE Command Language (TCL) Runtime Services, Volume 1: C" manual, the Vm package in the "TAE Plus Programmer's Manual" and "TAE Plus C Reference Manual", the tae vm package (Appendix C of the "TAE Plus Ada Reference Manual"), or the TaeVar class in the "TAE Plus C++ Reference Manual".

Procs in batch and ASYNC-PROCESS execution may not request dynamic parameters. Procs in normal asynchronous execution may request dynamic parameters provided that the parent job is an interactive session.

When parameters are requested by a synchronous proc, TAE enters dynamic tutor. See the "TAE Command Language (TCL) User's Manual" for a description of the options available in dynamic tutor. When parameters are requested by an asynchronous job, the interactive user must execute the REPLY command before TAE enters dynamic tutor.

An example of a procedure with dynamic parameters follows:

PROCEDURE
PARM W INTEGER
PARM X INTEGER
LOCAL Y INTEGER INITIAL=10
LOCAL Z INTEGER INITIAL=1
BODY
    .
    .
    .
LET Y = 30
GETBAR PARMS = (X,Y,Z)
    .
    .
    .
END-PROC

This procedure is initiated with user-supplied values for W and X. When GETPAR is executed, TAE enters dynamic tutor and solicits X, Y, and Z. The initial settings of X, Y, and Z in tutor are the user-supplied value for X (since it is not initialized in the declaration or set in the body), 30 for Y (set in the body), and 1 for Z (initialized in the declaration).