SECTION 3 -- PARAMETER AND VARIABLE MANIPULATION

This section describes the p_ and q_ packages, consisting of functions that allow a TAE application program to manipulate process parameters and variables. These packages use data buffers provided by the caller. The Vm_ package, described in the TAE Plus C Reference Manual, provides the same capabilities, but allocates the memory internally. (The Vm_ package is the recommended package.)

As noted in Section 2 of the TAE Command Language (TCL) Programmer's Manual, the process parameters and variables consist of the following:

Parameters declared in the PDF using the PARM command.
Local variables declared in the PDF using the LOCAL command.
Global variables referenced in the PDF using the REFGBL command.
The implicit local and global variables listed in Section 3.3.2 of the TAE Command Language (TCL) Programmer's Manual.

Note that, as described in Section 3.3.2 of the TAE Command Language (TCL) Programmer's Manual, process parameters are, in fact, TCL variables. All references to "TCL variables" in succeeding sections apply to locals, globals, and parameters.

The most common use of the packages is the receipt of user-supplied parameters by the application program. Also described are functions for:

Initiating a dynamic tutor session.
Reading variable values from disk.
Writing variable values to disk.
Sending process outputs (i.e., NAME parameters and referenced global variables) to the Terminal Monitor (TM).

Three function packages are available for parameter and variable manipulation:

The p package provides for:
- Receipt of process inputs, i.e., those values set by the end-user while in command mode or tutor mode.
- Receipt of variables upon the completion of a dynamic tutor session.
- Receipt of variables from a disk file.
The q_ package is oriented towards "emitting" variable values from an application process; q_ is used for:
- Setting the values of process outputs.
- Writing variable values to disk.
- Initiating a dynamic tutor session and supplying default values.

The detailed calling sequences of the two packages are described below. The following introductory paragraphs explain variable manipulation.

3.1 VARIABLE TYPES

As described in Section 2 of the TAE Command Language (TCL) Programmer's Manual, the variables for a process are defined in the PDF. The caller of the variable manipulation functions receives the process variables in the following formats:

An INTEGER variable is received as TAEINT.
A REAL variable is received as TAEFLOAT.
A STRING, KEYWORD, or FILE variable is received as TEXT string with zero terminator.

Note that the NAME type (see Section 2.3.2 of the TAE Command Language (TCL) Programmer's Manual) is not seen directly by the p_/q_ packages: the caller of the p_ functions receives the type and value of the variable that is referenced by the NAME parameter.

3.2 THE V-BLOCK

3.2.1 Contents

The "V-block" (for "variable block") is the standard data structure for packaging process variables. A V-block is sent from TM when the process is initiated, and it is also the data structure used when variables are saved on disk. A V-block contains, for each process variable, the following items:

Parameter or variable name
Type (INTEGER, REAL, STRING, or FILE)
Value(s)
Value count
Whether or not the parameter or variable was defaulted

The C declaration of a V-block is "struct PARBLK vblock".

3.2.2 Uses of the V-Block

The Terminal Monitor obtains parameter values from the command line (if command activation) or from the tutor commands (if tutor mode activation). The V-block is created and transmitted to the application program for receipt by the p_ package. The application program receives this block with the p_inim function.
SAVE/RESTORE: The TCL SAVE command and the tutor SAVE command create a V-block from current values and write the V-block to a disk file. The TCL RESTORE command and the tutor RESTORE command restore the block. Disk-resident V-blocks may be accessed by a process using the p_rdb initialization function followed by calls to p_find function.
Dynamic Parameters: An application program initiates a dynamic tutor session by calling q_ functions to build a V-block containing initial tutor values and transmitting the block to TM with the q_dynp function. (The dynamic tutor session is terminated by the user with the RUN or EXIT commands.)
q_wrtb: The q_wrtb function may be used by a program to save a V-block on disk. This block may be subsequently retrieved via TCL RESTORE command or via the p_rdb function. In addition, a disk-resident block may be read using p_rdb, updated using q_ functions, and written back to disk with q_wrtb.
q_out: The q_out function may be used by a program to send output parameters and updated global variables to the Terminal Monitor. The output values are placed in a V-block using q_ functions (e.g., q_intg to output an integer) and sent to TM using q_out.

3.3 OVERVIEW OF BASIC VARIABLE MANIPULATION ALGORITHMS

3.3.1 Variable Receipt

An application program reads variables as follows:

The block is defined as a PARBLK structure.
The V-block is read into the block: p_inim or z_init is called to receive the block from the Terminal Monitor or p_rdb is called to read the block from disk. The block read from TM may be either the initial set of process variables or the result of a dynamic tutor session.
p_find function is called to retrieve variables (of type INTEGER, REAL, FILE, and STRING) from the block. For variables of type FILE, p find should be followed by a p_file function call.

3.3.2 Changing Values in an Existing V-Block

A programmer might update an existing V-block when it is to be saved on disk, or used in a dynamic tutor session. This is done as follows:

The block is defined as a PARBLK structure.
The existing V-block is read into the block: p_inim or z_init is called to receive the block from the Terminal Monitor or p_rdb is called to read the block from disk. The block read from TM may be either the initial set of process variables or the result of a dynamic tutor session.
q_intg, q_real and/or q_string functions are called to change the values of parameters and variables (of type INTEGER, REAL, FILE, and STRING) in the block. New variables may also be added to the block with these functions.
Additional fuctions are available to change the characteristics of a parameter variable:
- q_min, q_max change the minimum or maximum count of a variable.
- q_validintg, q_validreal, q_validstr set the valid values of a variable.
- q_stringlength sets the maximum string length of a variable of type string.
- q_parmpage sets the "page indicator" of a variable (that is, the variable is made to appear at the top of a new page in a tutor session).

After update, the block may be written to disk (q_wrtb) and/or used to initiate a dynamic tutor session (q_dynp) or to send outputs (i.e., TCL variables) to TM (q_out).

3.3.3 Construction of a V-Block

An application program constructs a V-block as follows:

The block is defined as a PARBLK structure.
q_init is called to initialize the block's structure.
q_intg, q_real and/or q string functions are called to add parameters and variables (of type INTEGER, REAL, FILE, and STRING) to the block.
Additional functions are used to change the characteristics of a variable. (See Section 3.3.2 above.)

After construction, the block may be written to disk (q_wrtb) and/or used to initiate a dynamic tutor session (q_dynp) or to send outputs (i.e., TCL variables) to TM (q_out).

3.3.4 Additional Notes on V-Blocks

The parblk.inc include file provides a macro, DEF_PARBLK, that can be used to define PARBLKs of any size up to a limit of MAXINT bytes. The two arguments to the macro are the name of the parblk structure to be defined and the pool size. An example of its use is provided in the include file itself, in the definition of LARGE_PARBLK:

DEF_PARBLK(LARGE_PARBLK, LARGE_P_BYTES.);

where LARGE_PARBLK uses a pool space of LARGE_P_BYTES, and LARGE_P_BYTES is currently defined as 5_*MAX_COMPACT_UCOUNT bytes.

The DEF_PARBLK macro can be used to define very large parblk's to be written to disk (in association with q_wrtb and p_rdb, the routines to write a parblk to disk and to read a parblk back).

3.4 PROCESS OUTPUTS

As described in Section 2 of the TAE Command Language (TCL) Programmer's Manual, the possible outputs of a process are TCL parameters of type NAME; global variables declared in a PDF (using REFGBL); and the implicit globals listed in Section 3.3.2 of the TAE Command Language (TCL) Programmer's Manual. The values for outputs may be set using q_intg, q_real and q_string into a V-block built using q_init (or an existing block received by p_inim or read by p_rdb). The V-block is sent to TM using q_out; q_out may be called at any time during process execution. The values for globals $SFI and $SKEY may also be set using z_exit (see Section 8).

3.5 DYNAMIC TUTOR SESSIONS

After initiation, an application process may request additional parameters from the user. When the parameters are requested, TM places the user in dynamic tutor.

Dynamic tutor is not available for batch or ASYNC-PROCESS jobs. For normal asynchronous jobs, the interactive user must respond to the dynamic tutor request with the TAE REPLY command.

An application process initiates and receives the results of a dynamic tutor session as follows:

A new V-block is constructed or an existing block is read into process storage as described above. The values in the block become initial tutor values for the dynamic tutor session.
The q_dynp function is called to pass the V-block to TM and to initiate the dynamic tutor session.
The p_inim function is called to receive the V-block containing the user-supplied parameters. p_inim does not return until the dynamic tutor session is complete.
The p_find function is called to extract parameter values (of type INTEGER, REAL, FILE, and STRING) from the V-block. For variables of type FILE, the above call should be followed by a p_file function call.

Note that prior to step 2, functions may be called to change the minimum or maximum count of a variable (q_min, q_max) to set the maximum string length (q_stringlength), or to set the valids (q_validintg, q_validreal, q_validstr).

An existing PDF must be associated with a dynamic tutor session. The PDF name is an input argument to the q_dynp call. The PDF is used by TM to determine the full declarations of the parameters and to locate the related help file.

The PDF may be the PDF for the executing process or may be an entirely different PDF. The PDF need not be a proc PDF; it may be a PARMSET PDF as described in Section 2 of the TAE Command Language (TCL)Programmer's Manual.

The q_dynp function accepts a "sub-PDF/full-PDF" flag, directing whether or not all of the parameters in the PDF are to participate in the dynamic tutor session. In sub-PDF mode, only the parameters in the V-block constructed by the process participate in the session. In full-PDF mode, all of the PDF parameters participate in the session, even if the V-block contains only some of them.

The sub-PDF feature is provided to avoid proliferation of PDFs; with subsetting, one PDF may be used for many combinations of parameters in dynamic tutor sessions.

At the beginning of a dynamic tutor session, TM checks that the V-block received from the application process is compatible with the PDF parameter definitions. If discrepancies are detected (e.g., a parameter placed in the block via q_intg is defined to be of type REAL in the PDF), the application program is aborted.

A common situation is a request for a dynamic tutor session with full-PDF, where the programmer is content to use defaults defined in the PDF. In this case, the V-block passed to TM has no parameters, i.e., the q_dynp call may immediately follow the q_mit call.

3.6 STATUS CODES AND ABORT/CONTINUE MODES

The p_/q_ packages run in "abort" or "continue" mode as selected by an argument to p_inim, z_init, p_rdb, or q_init. In continue mode, errors detected by subsequent p_/q_ function calls are returned as function codes to the calling routine; in abort mode, the p_/q_ packages generate an error message and terminate the process.

Abort mode is provided as a convenience to the programmer; in this mode there is no need for the program to check function codes and generate error messages.

When errors are detected in continue mode, a host-independent function code is returned to the p_/q_ caller. In addition, the parameter/variable manipulation package provides a function, p_herr, that retrieves the host-dependent error code for the last error reported.

The abort/continue flag is maintained by TAE in the V-block. Thus, the abort/continue mode applies to the V-block and not the entire p_/q_ package. Should there be a need for altering the setting of the abort/continue flag in a V-block, the programmer can directly store the constants P_ABORT or P_CONT into the V-block member name "mode".

3.7 IMPLICITLY-DEFINED VARIABLES

As described in Section 2 of the TAE Command Language (TCL) Programmer's Manual, the V-block passed to an application process by the Terminal Monitor contains, in addition to the process parameters and explicitly declared variables, the implicitly declared TCL variables, _PROC, _STDOUT, _SUBCMD, ONFAIL, $RUNTYPE, $SESSION, $SFI, $SKEY and $SWITCH. (In addition blocks for ASYNC-PROCESS jobs contain _PARENT, _CHILD and _JOB.) See Section 3.3.2 of the TAE Command Language (TCL) Programmer's Manual for a description of these TCL variables.

These TCL variables may be obtained via standard p_find calls.

3.8 PROGRAM EXAMPLE

See template.c in $TAEDEMOCLASSIC for a basic program that contains many of the parameter manipulation functions. Use the command TAEBUILDEONE (in VMS) or taeccone (in UNIX) to build an executable based on template.c. See Appendix B of this manual for more elaborate examples.

3.9 VARIABLE MANIPULATION FUNCTIONS

3.9.1 p_file - Get Host File

CODE p_file (taefile, access, hostfile)

Function return:

SUCCESS: the file specification was successfully translated.
P_FAIL: general failure indication.

Arguments:

taefile: input, TEXT taefile[];
TAE file specification to be translated.

access: input, FUNINT access;

The file access specification. Possible values are:

V_IN: access=IN

V_INOUT: access=INOUT

V_OUT: access=OUT

V_NOCHECK: access=NOCHECK

hostfile: output, TEXT hostfile[];
The argument to receive the translated host specification, dimensioned FSPECSIZ+1.

p_file translates the TAE file specification into a host specification.

The following program segment demonstrates the use of p_files:


struct VARIABLE     *v, *p_find();
struct PARBLK       block;
CODE                code;
TEXT                hostspec [FSPECSIZ+1];

p_inim (&block, P_BYTES, P_ABORT); 
v = p_find (&block, ".FILE");
code = p_file (SVAL(*v,0), (*v).v_filemode, hostspec);

3.9.2 p_find - Find Variables with Error Check

struct VARIABLE *p_find (vptr, name)

Function return:

Pointer to a VARIABLE structure in the parameter block.
NULL: the variable does not exist. This return is available only if the V-block is in "continue" mode.

Arguments:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to a parameter block (PARBLK structure) -containing the V-block (VARIABLE structure) where the variable name is to be searched.
```
name: input, TEXT name[];
```
Name of the variable.

p_find is used to help retrieve the individual variables from the parameter block. P_find differs from p_fvar in that p_find honors abort mode if the variable does not exist.

Each variable is defined as a VARIABLE structure; the VARIABLE structure is defined in the symtab.inc include file.

Assuming that "v" is the returned value of a successful p_find call, the following information is available:

(*v).v_type: The type of the variable: V_REAL, V_STRING, or V_INTEGER. File and keyword type variables have a V_STRING in this field.
(*v).v_class: The class of the variable (V_GLOBAL, V_PARM, or V_LOCAL).
(*v).v_file: TRUE if a file type variable.
(*v).v_filemode: Type of access for a file type variable: V_IN, V_OUT, V_INOUT, or V_NOCHECK.
(*v).v_count: The current value count. A -1 means "no value" and 0 means "null value".
(*v).v_minc: The minimum value count as defined in the PDF.
(*v).v_maxc: The maximum value count as defined in the PDF.
(*v).v_nullable: TRUE if the variable is nullable.
(*v).v_cvp: Current value pointer, described below.

The (*v).v_cvp field is a pointer (in char * format) to a value vector. A value vector is:

For real variables, an array of TAEFLOAT.
For integer variables, an array of TAEINT.
For string variables, an array of string pointers.

The following C macros are defined in the SYMTAB include file to assist in accessing the values of a VARIABLE structure:

RVAL(*v,i) is the ith value of v for real variables. RVAL is of type TAEFLOAT.
IVAL(*v,i) is the ith value of v for integer variables. IVAL is of type TAEINT.
SVAL(*v,i) is a pointer to the ith string for string variables. SVAL is of type "char *"

The indexing above is "C indexing", i.e., the first component of a variable is index zero. The VALUE_* macros (where * is defined to be _I, _R, or _S) are the same as the macro names IVAL, RVAL, and SVAL.

The values of a variable may also be accessed by casting the(*v) .vcvp pointer into the proper form. The following C program segment demonstrates:

struct PARBLK parblk     /* parameter block      */
TAEFLOAT    *real;       /* value vector pointer */
TAEINT      *intg;       /* value vector pointer */
TEXT        **str;       /* value vector pointer */
struct VARIABLE     *vx, *vi, *vs, *p_find();
COUNT

P_inim (&parblk, sizeof(struct PARBLK), P_ABORT);

vx = p_find (&parblk, "X");          /* find VARIABLE structures     */
vi = p_find (&parblk, "I");
vs = p_find (&parblk, "5");

real = (TAEFLOAT *) (*vx).v_cvp;     /* cast value vector pointers   */
intg = (TAEINT *) (*vi).v_cvp; 
str = (TEXT **) (*vs).v_cvp;

for (i=O; i < (*vx).v_count; i++)
    printf ("X(%d) = %f\n", i+1, real[i]);
for (i=O; i < (*vi).v_count; i++)
    printf ("I(%d) = %d\n", i+1, intg[i]);
for (i=O; i < (*vs).v count; i++)
    printf ("S(%d) = %s\n", i+1, str[i]);

3.9.3 p_forp - Format Variables

CODE p_forp (vptr, line, length)

Function return:

SUCCESS: line is obtained.
FP_EOP: no more lines exist.
FP_NULL: line length is not large enough to receive the next variable.

Arguments:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to a PARBLK structure with the V-block from p_inifor call.
```
line: output, TEXT line[];
```
String containing next n variables from the V-block in "name=value" format. The number n is determined by the number of variables that fit within the length of the line.

Line must be long enough to receive the longest variable value (form is "name=value" including quotes) plus room for the continuation character.
```
length: input, COUNT length;
```
Length of output line in bytes.

p_forp obtains parameter values and values of global and local variables in a displayable form, i.e., as lines of text.

p_forp must be called multiple times to obtain the values in character form. Each call to p_forp receives one line of variable text, in the order the variables appear in the V-block. The format for all values is "name=value" where "name" is the name of the variable.

p_inifor must be called to initialize for a sequence of p_forp calls.

3.9.4 p_fvar - Find Variable

struct VARIABLE *p_fvar (vptr, name)

Function return:

Pointer to the VARIABLE structure for the variable name.
NULL: the variable does not exist.

Arguments:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to a PARBLK structure containing the V-block where the variable name is to be searched
```
name: input, TEXT name[];
```
Name of the variable.

p_fvar is same as p_find, except that pfvar ignores the ABORT flag of the V-block.

3.9.5 p_herr - Get Host-dependent Error Code

VOID p_herr (vptr, hcode)

Function return:

None

Arguments:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to the PARBLK structure with the V-block containing TCL variables.
```
hcode: output, CODE *hcode;
```
Pointer to the host-dependent error code.

p_herr gets the host-dependent error code associated with the last operation (that is, a p_ or q_ operation) on the specified block.

3.9.6 p_inifor - Initialize p_forp for Formatting Variables

VOID p_inifor (vptr)

Function return:

None

Argument:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to the PARBLK structure with the V-block containing TCL variables.

p_inifor initializes for multiple calls to p_forp.

3.9.7 p_inim - Receive V-Block from TM

CODE p_inim (vptr, size, mode)

Function return:

SUCCESS: the message containing the variables was successfully received from the Terminal Monitor.
P_KILLED: the user exited from dynamic tutor mode, implicitly requesting that the application be aborted.
P_NOROOM: the V-block is not dimensioned large enough.
FAIL: general failure indication.

Note that the status codes listed above are available only if the block was initialized in "continue" mode.

Arguments:

```
vptr: input, struct PARBLK *vptr;
```
Pointer to a PARBLK structure to receive the V-block from the Terminal Monitor.
```
size: input, FUNINT size;
```
This argument must be sizeof(struct PARBLK).
```
mode: input, FUNINT mode;
```
- P_ABORT: indicates that the process is to be aborted (with an appropriate error message) when errors are detected in the variable passing mechanism.
- P_CONT: requests that the package report errors to the calling program via the function return.

p_inim or p_rdb must be called before any other call to the p package using the same V-block. P_inim receives a V-block from the Terminal Monitor. Variables in this block may then be accessed with the p_find calls.

If p_inim is called to receive the variables of a dynamic tutor session, only the parameters are returned, the implicit variables(_STDOUT, etc.) are not.

If a status code of P_KILLED is returned, the application should terminate after performing any necessary clean-up operations.

3.9.8 p_rdb - Read a Saved V-Block File

CODE p_rdb (spec, lun, vptr, size, mode)

Function return:

SUCCESS: file successfully read and the V-block initialized.
P ERROR: the V-block file was incorrectly structured.
P_FAIL: general failure indication.

Note that the status codes listed above are available only if the block was initialized in "continue" mode.

Arguments:

```
spec: input, TEXT spec[];
```
Host file specification of file to be read.
```
lun: input, COUNT lun;
```
Logical unit number to use for the file I/O. On VMS and UNIX systems, this argument is ignored.
```
vptr: input, struct PARBLK *vptr;
```
Pointer to an PARBLK structure to receive the V-block.
```
size: input, COUNT size;
```
This argument must be the constant sizeof(struct PARBLK)
```
mode: input, FUNINT mode;
```
- P_ABORT: indicates that the process is to be aborted (with an appropriate error message) when errors are detected in the variable passing mechanism.
- P_CONT: requests that the package report errors to the calling program via the function return.
p_rdb or p_inim must be called before any other call to the p_ package using the same V-block. P_rdb reads a V-block data file into the PARBLK structure pointed to by vptr.

A V-block file is created by the tutor SAVE command, or a command mode SAVE qualifier, or by a call to q_wrtb from an executing process.

3.9.9 q_dynp - Send V-Block for Dynamic Parameters
```
CODE q_dynp (vptr, pdfname, pdfset)
```
Function return:
- SUCCESS: block successfully sent.
- P_NOROOM: no space available to send block.
- A host-dependent error code if the block could not be sent for a host-dependent reason.
  
  Note that the status codes listed above are available only if the block was initialized in "continue" mode.
Arguments:
1. ```
vptr: input, struct PARBLK *vptr;
```
  Pointer to a PARBLK structure containing the V-block that has been built by the application and is to be sent to the Terminal Monitor. Any parameters or variables whose values are specified in the V-block must be defined in the PDF.
2. ```
pdfname: input, TEXT pdfname[];
```
  The PDF name to be used by the Terminal Monitor. This PDF should define all variables in the V-block. If pdfname is a simple alphanumeric string, TAE performs a standard "proc hierarchy search" to locate the PDF. If the pdfname string contains a library name, then TM uses the name as is and no hierarchy search is performed.
  
  The pdfname may be the empty string, in which case the PDF of the current process is used.
  
  The pdfname may include a subcommand, in which case the parameters participating in the dynamic tutor session are the parameters associated with the specified subcommand. A subcommand must be specified if the PDF has subcommands but no default subcommand.
3. ```
pdfset: input, FUNINT pdfset;
```
  pdfset is either "sub-PDF" or "full-PDF"
  - M_SUBPDF: tells the Terminal Monitor to display parameter values only for those parameters specified in V-block (i.e., that the application process desires only a subset of all parameters in the PDF to be updated).
  - M_FULLPDF: the Terminal Monitor is to display values for all parameters defined in the PDF, whether or not specified in V-block.
  The q_dynp sends the V-block to the Terminal Monitor as a set of initial values for a dynamic tutor session. After calling q_dynp, the application program waits on completion of the dynamic tutor session by calling p_inim. The V-block must be constructed before calling q_dynp. p_inim, p_rdb, q_init, q_intg, q_real, q_string are functions that may be used to construct a V-block.
  
  q_dynp is not acceptable in a batch job or an ASYNC-PROCESS job.
  
  3.9.10 q_init - Initialize V-Block Construction
```
VOID q_init (vptr, size, mode)
```
  Function Return: None
  
  Arguments:
  1. ```
  vptr: input, struct PARBLK (or LARGE_PARBLK) *vptr;
```
  Pointer to a PARBLK (LARGE_PARBLK) structure that will become the initialized V-block.
2. ```
size: input, FUNINT size;
```
    This argument must be the size of the storage pool in the PARBLK (LARGE_PARBLK) structure, currently P_BYTES ( LARGE P_BYTES ).
  3. mode: input, FUNINT mode;
    - P_ABORT: indicates that the q package is to abort the process (with an appropriate error message) when errors are detected in the V-block construction or passing mechanism.
    - P_CONT: requests that the package report errors to the calling program via the function return.
    The q_init is called to initialize a V-block in preparation for other q_ calls. (A V-block may also be initialized by p_inim or p_rdb.) After q_init is called, the V-block is properly formatted with zero variables.
    
    3.9.11 q_intg - Set Integer Variable
```
CODE q_intg (vptr, name, count, intg, mode)
```
    Function return:
    - SUCCESS: variable successfully placed in the V-block.
    - P_NOROOM: no room left in block for the variable.
    - P_BADNAME: the variable does not exist.
    - P_BADCOUNT: the count is either less than the minimum or greater than the maximum allowed for this variable.
    - P_BADTYPE: the variable has a type other than integer.
    - P_DUPNAME: the variable already exists (for P_ADD mode).
    - P_NOPARM: the variable, a parameter qualifier, does not exist. See Section 2.3 of the "TAE Command Language (TCL) Programmer's Manual" for a discussion on parameter qualifiers.
    - P_OLDPARM: the variable, a parameter qualifier, cannot be aided to a block created previous to Version 1.3 of TAE. See Section 2.3 of the "TAE Command Language (TCL) Programmer's Manual" for a discussion on parameter qualifiers.
    Note that the status codes listed above are available only if the block was initialized in "continue" mode.
    
    Arguments:
    1. ```
    vptr: input/output, struct PARBLK *vptr;
```
  Pointer to a PARBLK structure with the V-block in which the variable value is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
2. name: input, TEXT name[];
  
  Name of the TCL integer variable to be set.
3. ```
count: input, FUNINT count;
```
      Multiplicity of the variable, i.e., the number of integers in the intg array.
      
      The count values 0, -1, and -2 are special: a count of 0 means "null value"; a count of -1 means "no value", in which case the parameter becomes a mandatory parameter; and a count of -2 means "use the default value defined in the PDF."
    4. ```
    intg: input, TAEINT intg[];
```
  An array of integer values (an integer value vector) for the variable. If count is one, note that intg must nonetheless be an array of dimension one. (See the program examples in Appendix B.) If count is less than one, then the intg argument is ignored.
5. ```
mode: input, FUNINT mode;
```
      - P_ADD: indicates that the variable is being added to the block.
      - P_UPDATE: indicates that the variable is already in the block but its value and/or count is being modified.
    3.9.12 q_out - Send V-Block for Variable Outputs
```
CODE qout (vptr)
```
    Function return:
    - SUCCESS: block successfully sent.
    - A host-dependent error code if the block could not be sent for a host-dependent reason.
      
      Note that the status code listed above is available the only if block was initialized in "continue" mode.
    Argument:
    1. ```
    vptr: input, struct PARBLK *vptr;
```
  Pointer to a PARBLK structure with the V-block that has been built by the application program and is to be sent to the Terminal Monitor. Any parameters or variables whose values are specified in V-block must be defined in the PDF for the executing process.
q_out sends the V-block containing the values of name parameters and global variables to the Terminal Monitor.

The V-block argument must be constructed before calling q_out; p_inim, p_rdb, q_init, q_intg, q_real, q_string are functions that may be used to construct a V-block. See Section 3.3 for more details.

3.9.13 q_real - Set Real Variable
```
    CODE qreal (vptr, name, count, real, mode)
```
Function return:
- SUCCESS: variable successfully placed in the V-block.
- P_NOROOM: no room left in block for the variable.
- P_BADNAME: the variable does not exist.
- P_BADCOUNT: the count is either less than the minimum or greater than the maximum allowed for this variable.
- P_BADTYPE: the variable has a type other than real.
- P_DUPNAME: the variable already exists (for P_ADD mode).
- P_NOPARM: the parameter does not exist for the variable, a parameter qualifier, to be added. See Section 2.3 of the TAE Command Language (TCL) Programmer's Manual for a discussion on parameter qualifiers.
- P_OLDPARM: the variable, a parameter qualifier, cannot be added to a block created previous to Version 1.3 of TAE. See Section 2.3 of the TAE Command Language (TCL) Programmer's Manual for a discussion on parameter qualifiers.
Note that the status codes listed above are available only if the block was initialized in "continue" mode.

Arguments:
1. ```
vptr: input/output, struct PARBLK *vptr;
```
      Pointer to a PARBLK structure with the V-block in which the variable value is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the TCL real variable to be set.
3. ```
count: input, FUNINT count;
```
      Multiplicity of the variable, i.e., the number of real values in the real array.
      
      The count values 0, -1, and -2 are special: a count of 0 means "null value"; a count of -1 means "no value", in which case the parameter becomes a mandatory parameter; and a count of -2 means "use the default value defined in the PDF."
    4. ```
    real: input, TAEFLOAT real[];
```
  An array of real values (a real value vector) for the variable. If count is one, note that real must nonetheless be an array of dimension one. (See program examples in Appendix B.) If count is less than one, the real argument is ignored.
5. ```
mode: input, FUNINT mode;
```
      - P_ADD: indicates that the variable is being added to the block.
      - P_UPDATE: indicates that the variable is already in the block but its value and/or count is being modified.
    3.9.14 q_string - Set String or Keyword Variable
```
CODE q_string (v_ptr, name, count, vector, mode)
```
    Function return:
    - SUCCESS: variable successfully placed in the V-block.
    - P_NOROOM: no room left in block for the variable.
    - P_BADNAME: the variable does not exist.
    - P_BADCOUNT: the count is either less than the minimum or greater than the maximum allowed for this variable.
    - P_BADTYPE: the variable has a type other than string.
    - P_DUPNAME: the variable already exists (for P_ADD mode).
    - P_NOPARM: the parameter does not exist for the variable, a parameter qualifier, to be added. See Section 2.3 of the TAE Command Language (TCL) Programmer's Manual for a discussion on parameter qualifiers.
    - P_OLDPARM: the variable, a parameter qualifier, cannot be aided to a block created previous to Version 1.3 of TAE. See Section 2.3 of the TAE Command Language (TCL) Programmer's Manual for a discussion on parameter qualifiers.
    Note that the status codes listed above are available only if the block was initialized in "continue" mode.
    
    Arguments:
    1. ```
    vptr: input/output, struct PARBLK *vptr;
```
  Pointer to a PARBLK structure with the V-block in which the variable value is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
2. ```
name: input, TEXT name[];
```
      Name of the TCL string or keyword variable to be set.
    3. ```
    count: input, FUNINT count;
```
  Multiplicity of the variable, i.e., the number of string pointers in the vector argument.
  
  The count values 0, -1, and -2 are special: a count of 0 means "null value"; a count of -1 means "no value", in which case the parameter becomes a mandatory parameter; and a count of -2 means "use the default value defined in the PDF."
4. ```
vector: input, TEXT *vector[];
```
      An array of pointers to strings (a string value vector) for the variable. If count is one, note that vector must nonetheless be an array of dimension one (see program example in Appendix B). If count is less than one, then the vector argument is ignored.
    5. ```
    mode: input, FUNINT mode;
```
  - P_ADD: indicates that the variable is being added to the block.
  - P_UPDATE: indicates that the variable is already in the block but its value and/or count is being modified.
3.9.15 q_wrtb - Write V-Block to a Disk File
```
    CODE q_wrtb (spec, lun, vptr)
```
Function return:
- SUCCESS: V-block successfully written.
- P_FAIL: general failure indication.
  
  Note that the status codes listed above are available only if the block was initialized in "continue" mode.
Arguments:
1. ```
spec: input, TEXT spec[];
```
      Host file specification of file to be created.
    2. ```
    lun: input, FUNINT lun;
```
  Logical unit number to use for the file I/O. On VAX/VMS and UNIX systems, this argument is ignored.
3. ```
vptr: input, struct PARBLK *vptr;
```
      Pointer to the PARBLK structure with the V-block to be written. q_wrtb writes a PARBLK structure into a V-block data file.
    3.9.16 q_max - Set Maximum Vector Count of a Variable
```
CODE qmax (p, name, max)
```
    Function return:
    - SUCCESS: variable's maximum count successfully updated.
    - P_BADCOUNT: min count > max count
    - P_BADNAME: the variable does not exist.
    Arguments:
    1. ```
    p: input/output, struct PARBLK *p;
```
  Pointer to a PARBLK structure with the V-block in which the variable's maximum vector count is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
2. ```
name: input, TEXT name[];
```
      Name of the variable.
    3. ```
    max: input, FUNINT max;
```
  An integer value for the maximum count of the variable
q_max sets the maximum count of a variable.

If the variable has more than "max" values set, then array elements beyond the "max"th one will be lost.

3.9.17 q_min - Set Minimum Vector Count of a Variable
```
    CODE q_min (p, name, min)
```
Function return:
- SUCCESS: variable's minimum vector count successfully updated.
- P_BADCOUNT: min count > max count
- P_BADNAME: the variable does not exist.
Arguments:
1. ```
p: input/output, struct PARBLK *p;
```
      Pointer to a PARBLK structure with the V-block in which the variable's minimum vector count is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the variable.
3. ```
min: input, FUNINT min;
```
      An integer value for the minimum count of the variable
    q_min sets the minimum count of a variable.
    
    3.9.18 q_parmpage - Set the Page Indicator of a Variable
```
CODE q_parmpage (p, name, flag)
```
    Function return:
    - SUCCESS: variable's page indicator successfully set.
    - P_BADNAME: the variable does not exist.
    Arguments:
    1. ```
    p: input/output, struct PARBLK *p;
```
  Pointer to a PARBLK structure with the V-block in which the variable's page indicator is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
2. ```
name: input, TEXT name[];
```
      Name of the variable.
    3. ```
    flag: input, BOOL flag;
```
  - TRUE: sets the page indicator to TRUE.
  - FALSE: sets the page indicator to FALSE.
q_parmpage sets the page indicator of a variable. This causes the variable to appear at the top of a new page in a tutor session.

3.9.19 q_setnextmenu - Set the Next Menu to be Executed
```
    CODE q setnextmenu (p, name)
```
Function return:
- SUCCESS: successfully set the next menu to be executed.
- FAIL: failed to set the next menu to be executed; MDF does not exist or the specified PARBLK does not contain the global $MENU.
- P_BADNAME: name is null string.
- M_NESTERR: Maximum menu tree nesting has been exceeded.
  
  P_error code values are defined in include file pgminc.inc; M_ error code values are defined in include file menuinc.inc.
Arguments:
1. ```
p: input/output, struct PARBLK *p;
```
      Pointer to a PARBLK structure with the V-block in which the global $MENU is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the next MDF to be executed.
q_setnextmenu sets the next menu to be displayed by TM. The specified MDF is added onto the current menu stack specified by $MENU. The updated parameter block is then sent to TM.

Note that the related PDF must have a global reference (refgbl) to $MENU.

3.9.20 q_stringlength - Set the Maximum String Length of a String or Keyword Variable
```
    CODE q_stringlength (p, name, strlen)
```
Function return:
- SUCCESS: variable's string length successfully set.
- P_BADNAME: the variable does not exist.
- P_BADSIZE: the string length is either less than the minimum or greater than the maximum string length allowed for a string variable (STRINGSIZ).
  
  Note that the status codes listed above are available only if the object was initialized in "continue" mode with a call to p_inim, z_init, q_init, or p_rdb.
Arguments:
1. ```
p: input/output, struct PARBLK *p;
```
      Pointer to a PARBLK structure with the V-block in which the variable is to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the TCL string or keyword variable to be set.
3. ```
strlen: input, FUNINT strlen;
```
      The maximum length of a string for the variable.
    q_stringlength sets the maximum length of a string for the variable.
    
    3.9.21 q_validintg - Set Integer Valids
```
CODE q_validintg (p, name, count, ilow, ihigh)
```
    Function return:
    - SUCCESS: successfully placed valids in the V-block.
    - P_NOROOM: no room left in block for the valids.
    - P_BADNAME: the variable does not exist.
    - P_BMINMAX: an invalid range is specified (ilow > ihigh).
    - P_BADTYPE: the variable has a type other than integer.
    Arguments:
    1. ```
    p: input/output, struct PARBLK *p;
```
  Pointer to a PARBLK structure with the V-block in which the variable's valids are to be set. This block must have been initialized with a call to q_init, p_inim, z_init, or p_rdb.
2. ```
name: input, TEXT name [];
```
      Name of the TCL integer variable.
    3. ```
    count: input, FUNINT count;
```
  Multiplicity of the valids; i.e., the number of ranges.
4. ```
ilow: input, TAEINT ilow[];
```
      An array of integer values (an integer value vector) for the low values of the ranges.
    5. ```
    ihigh: input, TAEINT ihigh[];
```
  An array of integer values (an integer value vector) for the high values of the ranges.
  
  If count is one, note that ihigh and ilow must nonetheless be an array of dimension one. If count is less than one, then the ihigh and ilow arguments are ignored.
q_validintg sets valids of an integer variable.

A call to q_validintg will replace any current valids for the specified variable that were set by previous calls to q_validintg.

The contents of the ilow and ihigh arrays are paired to form valid ranges. For example: ilow[] = {1, 2, 25}; ihigh[] = {1, 5, 73}; is equivalent to a specification of VALID=(1, 2:5, 25:73) on a PARM statement.

The valids specified in the call to q_validintg are not applied to any values that the variable might have from an earlier call to q_intg.

3.9.22 q_validreal - Set Real Valids
```
    CODE q_validreal (p, name, count, rlow, rhigh)
```
Function return:
- SUCCESS: successfully placed valids in the V-block.
- P_NOROOM: no room left in block for the valids.
- P_BADNAME: the variable does not exist.
- P_BMINMAX: an invalid range is specified (rlow > rhigh).
- P_BADTYPE: the variable has a type other than real.
Arguments:
1. ```
p: input/output, struct PARBLK *p;
```
      Pointer to a PARBLK structure with the V-block in which the variable's valids are to be set. This block must have been initialized with a call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the TCL integer variable.
3. count: input, FUNINT count;
  
  Multiplicity of the valids i.e., the number of ranges.
4. rlow: input, TAEFLOAT rlow[];
  
  An array of real values (a real value vector) for the low values of the ranges.
5. rhigh: input, TAEFLOAT rhigh[];
  
  An array of real values for the high values of the ranges.
  
  If count is one, note that rhigh and rlow must nonetheless be an array of dimension one. If count is less than one, then the rhigh and rlow arguments are ignored.
  
  q_validreal sets valids of a real variable.
  
  A call to q_validreal will replace any current valids for the specified variable that were set by previous calls to q_validreal.
  The contents of the rlow and rhigh arrays are paired to form valid ranges. For example: rlow[] = (2.3, 21.5); rhigh[] = (5.0, 55.9); is equivalent to a specification of VALID=(2.3:5.O, 21.5:55.9) on a PARM statement.
  
  The valids specified in the call to q_validreal are not applied to any values that the variable might have from an earlier call to q_real.
3.9.23 q_validstr - Set String Valids
```
    CODE q_validstr (p, name, count, vector)
```
Function return:
- SUCCESS: variable successfully placed in the V-block.
- P_NOROOM: no room left in block for the variable.
- P_BADNAME: the variable does not exist.
- P_BADTYPE: the variable has a type other than string.
- P_OVER: A string pointed to by "vector" contains more chracters than the value of VALIDSIZ in the file symtab.inc in the directory $TAEINC.
Arguments:
1. ```
p: input/output, struct PARBLK *p;
```
      Pointer to a PARBLK structure with the V-block in which the variable's valids are to be set. This block must have been initialized with call to q_init, p_inim, z_init or p_rdb.
    2. ```
    name: input, TEXT name[];
```
  Name of the TCL string variable.
3. ```
count: input, FUNINT count;
```
      Multiplicity of the valids, i.e., the number of string pointers in the vector argument.
    4. ```
    vector: input, TEXT *vector[];
```
  An array of pointers to strings (a string value vector) for the variable. If count is one, note that the vector must nonetheless be an array of dimension one. If count is less than one, then the vector argument is ignored.
q_validstr sets valids of a string variable.

A valid string may contain at most the number of characters as defined by VALIDSIZ in the file symtab.inc in the directory $TAEINC.

A call to q_validstr will replace any valids that had previously been specified for that variable.