5.2.1 x/zvintract—Prompt user for interactive command
5.2.2 x/zviparm—Return interactive parameter values
5.2.3 x/zvip—Interactive version of x/zvp; abbreviated version of x/zviparm
5.2.4 x/zviparmd—Interactive version of x/zvparmd
5.2.5 x/zvipcnt—Return the count of a parameter.
5.2.6 x/zvipone—Interactive version of x/zvpone
5.2.7 x/zvipstat—Interactive version of x/zvpstat
5.2.8 x/zviptst—Interactive version of x/zvptst
5.2.9 x/zvp—Abbreviated version of x/zvparm
5.2.10 x/zvparm—Return a parameter value
5.2.11 x/zvparmd—Double-precision version of x/zvparm
5.2.12 x/zvpcnt—Return the count of a parameter.
5.2.13 x/zvpone—Single value from a multivalued parameter
5.2.14 x/zvpstat—Information about a parameter
5.2.15 x/zvptst Indicate whether key word was specified

5.2 Parameter I/O API

VICAR has sixteen parameter retrieval routines that may be called from an application program:

5.2.1 x/zvintract—Prompt user for interactive command

call xvintract( subcmd, prompt) 
zvintract( subcmd, prompt) 

A call to this subroutine initiates a TAE interactive parameter session and returns in a buffer the parameters input by the user. This buffer is not visible to the program, but these parameters can be retrieved by the program using subroutine x/zviparm.

Arguments:

• SUBCMD: input, string
  Subcommand in the PDF. The string may contain up to 9 characters, and it maybe specified either as a FORTRAN CHARACTER type (by descriptor) or as a char* for C. If it's an empty string or a single blank, the entire PDF is used. This string may include the leading dash (“-”); one will be added if the programmer omits it. If this string only contains a dash, then the user will be required to specify a subcommand name as the first interactive input item.
• PROMPT: input, string
  Prompt string to be used in the interactive parameter session. The string may contain up to 20 characters, and it may be specified either as a FORTRAN CHARACTER type(by Descriptor) ) or as a char* for C. If it's an empty string or a single blank, the TAE default (a list of the parameters) is used.

5.2.2 x/zviparm—Return interactive parameter values

call xviparm(name, value, count, def, maxcnt)
status = zviparm(name, value, count, def, maxcnt, length);

x/zviparm returns information about the value(s) specified for a parameter interactively, given a parameter name. The returned information includes:

• The value(s) specified by the user or by default.
• The count, i.e. number of values specified for the parameter.
• The default flag. This flag should not be used. It is maintained for compatibility reasons, but the parameter count should be used instead.

Both the parameter name and, if it is a character string, the value may be specified as CHARACTER*n type for FORTRAN or char for C.
For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter. If the length is 0, or a BYTE array is passed in Fortran, then the strings will be returned in the old x/zvsptr format, which has been deprecated and should no longer be used.
A call to subroutine x/zvintract is required before this routine is called, in order to initiate an interactive parameter session.
If an error occurs, such as the parameter wasn't found, then COUNT is returned as 0, and the action specified by x/zveaction is taken.

Arguments:

• NAMARG: input, string, maximum length 8
  NAMARG specifies the parameter name as given in the PDF.
• VALARG: output, string
  If integer/real: parameter value(s) returned. This may be an array of string: argument for returned string. CHARACTER*n type for FORTRAN or char for C. For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter.
• COUNT: output, integer
  COUNT gives the number of parameter values returned. If zero, the parameter was not found.
• DEF: output, integer
  DEF is the default flag. If DEF = 0, then values are user-specified. If DEF = 1, then values are PDF defaults. This flag should not be used. It is maintained for compatibility reasons, but the parameter count should be used instead. If you want to have a program-supplied default, then allow the parameter to be nullable. If there are no values entered, then you can provide a default value in the program. Otherwise, the defaults in the PDF should be real default values, and it shouldn't matter whether the user entered them or not.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

Optional arguments:

• MAXCNT: input, integer
  The maximum number of parameter values to be returned. This should be the dimension of the parameter array in the calling routine.

5.2.3 x/zvip—Interactive version of x/zvp; abbreviated version of x/zviparm

call xvip(name, value, count) 
status = zvip(name, value, count);

Interactive version of x/zvp; abbreviated version of x/zviparm. Returns the value(s) of the given interactive parameter, and the number of values.

Arguments:

• NAME: string, input
  NAME is the name of the interactive parameter to get values from.
• VALUE: parameter—value-array, output
  The value of the parameter is returned in the VALUE array. The type of the value depends on the type of the parameter, which is either INTEGER, STRING or REAL (single-precision).
  There is no provision for providing a string length under C. Therefore, zvip should not be used for a string array. It is okay for a single string value, but if you want to get a multi-valued string, use zviparm instead. If you do get a multi valued string with zvip, it is returned in the zvsptr packed format, which is obsolete and should not be used. In FORTRAN, this restriction does not apply, since the string length for each element can be obtained from the string itself.
  There is no way to specify the size of the value buffer, so make sure it is big enough to handle the maximum count allowed in the PDF.
• COUNT: integer, output
  The number of values in the parameter is returned in COUNT.
  Warning: In xvp, the value of COUNT is set to 0 if the parameter has been defaulted. This is actually a design flaw, but has been retained for compatibility. The other three routines, zvp, xvip, and zvip, do not have this flaw. Being new routines, they can be done correctly without compatibility problems. The COUNT parameter returns the actual number of parameters in the value parameter, whether they are defaults or not. However, the variant behavior of xvp is likely to cause some confusion. Do not depend on this behavior in xvp, as it may change to be consistent in the future. If you are using xvp, either construct the PDF such that this problem won't matter, or use xvpcnt to get the actual count. This is a design flaw for two reasons: With the count returned as 0, there is no way to know if there is anything valid in the VALUE parameter, so it becomes useless. Second, the default flag should never be used; it is maintained for compatibility purposes only. The count of the parameter should be used instead.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.4 x/zviparmd—Interactive version of x/zvparmd

call xviparmd(name, value, count, def, maxcnt) 
status = zviparmd(name, value, count, def, maxcnt, length);

Interactive version of x/zvparmd.
This routine is exactly like x/zviparm, except that if the interactive parameter being returned is REAL, the VALUE parameter is returned in double precision format. x/zviparm returns the value in single precision. Although VALUE supports integers and strings as well, x/zviparmd should generally be used only for double-precision numbers. x/zviparm should be used for integers and strings.
This routine replaces the functionality of the R8FLAG parameter that was previously on x/zviparm.

Arguments:

• NAME: string, input
  NAME is the name of the interactive parameter to get values from.
• VALUE: parameter—value-array, output
  The value of the parameter is returned in the VALUE array. The type of the value depends on the type of the parameter, which is either INTEGER, STRING, or REAL (double-precision).
• COUNT: integer, output
  Reports the number of values returned in the VALUE parameter. A COUNT of 0 means the parameter either had a null value or was not found.
• DEF: integer, output
  Returns 1 if the parameter was defaulted, and 0 otherwise.
  NOTE: The DEF flag is obsolete and should not be used.
• MAXCNT: integer, input
  Specifies the maximum number of values to return. 0 means no limit.
• LENGTH: integer, input
  Specifies the length of each string if a string array is passed in for VALUE. Useful only from C; FORTRAN gets string lengths automatically. If the parameter is not a string, or is only a single string, set LENGTH to 0.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.5 x/zvipcnt—Return the count of a parameter.

call xvipcnt(name, count)
status = zvipcnt(name, count);

x/zvpcnt returns the parameter size information for an interactive parameter whose name is passed in the NAMARG parameter.
If only two arguments are given, the actual count, or dimension of the parameter is passed back in COUNT.
If an error occurs, such as the parameter wasn't found, then COUNT is returned as 0, and the action specified by x/zveaction is taken.
x/zvipcnt may only be called after the user is prompted with x/zvintract.

Arguments:

• NAMARG: input, string
  The name of the parameter whose count is desired. NAMARG may be passed either by descriptor ( FORTRAN character) or by reference.
• COUNT: output, integer
  The actual count of the parameter. For example, if the parameter is declared in the PDF file as having a count of up to 3, as in PARM I TYPE=INTEGER COUNT=1:3, and if the user specifies I=(4,7), then COUNT will be returned as 2.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.6 x/zvipone—Interactive version of x/zvpone

status = xvipone(name, value, instance, maxlen) 
status = zvipone(name, value, instance, maxlen);

Interactive version of x/zvpone.
This routine returns a single value from a multi-valued interactive parameter. It is most useful to get a string from a list of strings without having to mess with string arrays, but can be used for integer or real (single-precision) values as well. Note that x/zvipone is a FORTRAN function with a status return, which differs from most FORTRAN RTL routines .

Arguments:

• NAME: string, input
  NAME is the name of the interactive parameter to get a value from.
• VALUE: parameter—value, output
  The value of the parameter is returned in VALUE. The type of the value depends on the type of the parameter, which is either INTEGER, STRING, or REAL (single-precision). There is no equivalent to x/zvipone for double precision floating point; use x/zviparmd instead.
• INSTANCE: integer, input
  INSTANCE specifies which value you want. INSTANCE starts counting at 1, so the fifth value would have an INSTANCE of 5.
• MAXLEN: integer, input
  MAXLEN specifies the maximum length of the string buffer if the parameter is a string. It is used to avoid overflowing your buffer. If the parameter is not a string, or you don't care, set MAXLEN to 0. MAXLEN is rarely needed in FORTRAN, since string lengths are available from the strings themselves.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.7 x/zvipstat—Interactive version of x/zvpstat

call xvipstat(name, count, def, maxlen, type) 
status = zvipstat(name, count, def, maxlen, type);

This routine returns information about an interactive parameter without returning its value. It is most useful to get the maximum length of any string and the number of strings in order to allocate a buffer before calling x/zviparm. This routine is also the only way to determine the data type of a parameter given only its name. The program should know the type in the PDF, but there are situations where this could be useful.

Arguments:

• NAME: string, input
  NAME is the name of the interactive parameter to get information about.
• COUNT: integer, output
  Returns the number o f items in the parameter. If 0, parameter is either not found or is null.
• DEF: integer, output
  Returns 1 if the parameter was defaulted, and 0 otherwise.
  NOTE: The DEF flag is obsolete and should not be used.
• MAXLEN: integer, output
  Returns the maximum length of any value in the parameter. For REAL and INT, it is just the size of a REAL or INT. For STRING, it is the length of the longest string in the parameter. It does not include the null terminator, so you should add one before allocating a buffer in C.
• TYPE: string, output
  Returns the data type of the parameter. The possible values are “INT”, “REAL”, and “STRING”.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.8 x/zviptst—Interactive version of x/zvptst

GIVEN = xviptst ( KEY )
GIVEN = zviptst ( KEY ); 

The interactive version of x/zvptst. This function returns true if a key word was specified and false if not. For example, a program could check if the value “HALF” was given for a key word parameter with the code:

logical lhalf,xviptst

      lhalf = xviptst('HALF')
      if (lhalf) then
        .
        .
        .

The key word must be a value specified for a parameter of type KEY WORD.

xviptst must be declared LOGICAL in a FORTRAN program calling it.

x/zviptst, like the other x/zvi routines, may only be called after the user is prompted with x/zvintract.

Arguments:

• KEY: input, string
  Name of key word to be tested for. Note this is not the parameter name, but one of the valid values for the key word parameter. Passed either by descriptor in FORTRAN (if CHARACTER string is passed) or reference in C (if char* is passed).

5.2.9 x/zvp—Abbreviated version of x/zvparm

call xvp(name, val, count) 
status = zvp(name, val, count) 

x/zvp returns information about the value(s) specified for a parameter whenthe program was run, given a parameter name. It is an abbreviated version of x/zvparm, for user convenience. The returned information includes:

• The value(s) specified by the user or by default.
• The count, i.e. number of values specified for the parameter.

Both the parameter name and, if it is a character string, the value may be specified as CHARACTER*n type for FORTRAN or char for C.
For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter. If the length is 0, or a BYTE array is passed in Fortran, then the strings will be returned in the old x/zvsptr format, which has been deprecated and should no longer be used.
If an error occurs, such as the parameter wasn't found, then COUNT is returned as 0, and the action specified by x/zveaction is taken.

Arguments:

• NAME: input, string
  NAME is the parameter name argument. This specifies the parameter name. It maybe either a descriptor, if a FORTAN CHARACTER type is passed, or reference (memory address), if a char (C) array is passed).
• VALARG: output, string
  If integer/real: parameter value(s) returned. This may be an array of string: argument for returned string. CHARACTER*n type for FORTRAN or char for C. For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter.
• COUNT: output, integer
  COUNT gives the number of parameter values returned. If zero, the parameter was not found or the parameter was defaulted by the user. If the parameter was defaulted (given a default in the PDF but not by the user), then COUNT is returned as 0, regardless of the actual number of parameters in the defaulted value. This is a design flaw that must be maintained for historical reasons.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.10 x/zvparm—Return a parameter value

call xvparm( namarg, valarg, count, def, maxcnt) 
status = zvparm( namarg, valarg, count, def, maxcnt, length) 

x/zvparm returns information about the value(s) specified for a parameter when the program was run, given a parameter name. The returned information includes:

• The value(s) specified by the user or by default.
• The count, i.e. number of values specified for the parameter.
• The default flag. This flag should not be used. It is maintained for compatibility reasons, but the parameter count should be used instead.

Both the parameter name and, if it is a character string, the value may be specified as CHARACTER*n type for FORTRAN or char for C.
For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter. If the length is 0, or a BYTE array is passed in Fortran, then the strings will be returned in the old x/zvsptr format, which has been deprecated and should no longer be used.
If an error occurs, such as the parameter wasn't found, then COUNT is returned as 0, and the action specified by x/zveaction is taken.

Arguments:

• NAMARG: input, string
  NAMARG is the parameter name argument. It specifies the parameter name. It may be either a descriptor, if a CHARACTER (FORTRAN) type is passed, or reference (memory address), if a char (C) array is passed.
• VALARG: output, string
  If integer/real: parameter value(s) returned. This may be an array of string: argument for returned string. CHARACTER*n type for FORTRAN or char for C. For multivalued strings, the value should be a two-dimensional array of char (C) or an array of CHARACTER*n (Fortran). For C, the length of the inner dimension must be specified via the "length" parameter.
• COUNT: output, integer
  COUNT gives the number of parameter values returned. If zero, the parameter was not found.
• DEF: output, integer
  DEF is the default flag. If DEF = 0, then values are user-specified. If DEF = 1, then values are PDF defaults. This flag should not be used. It is maintained for compatibility reasons, but the parameter count should be used instead. If y o u want to have a program-supplied default, then allow the parameter to be nullable. If there are no values entered, then you can provide a default value in the program. Otherwise, the defaults in the PDF should be real default values, and it shouldn't matter whether the user entered them or not.
• MAXCNT: input, integer
  MAXCNT is the maximum number of parameter values to be returned. This should be the dimension of the parameter array in the calling routine.
• LENGTH: integer, input
  Specifies the length of each string if a string array is passed in for VALUE. Useful only from C; FORTRAN gets string lengths automatically. If the parameter is not a string, or is only a single string, set LENGTH to 0.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.11 x/zvparmd—Double-precision version of x/zvparm

call xvparmd(name, value, count, def, maxcnt) 
status = zvparmd(name, value,count, def, maxcnt, length);

Double-precision version of x/zvparm.
This routine is exactly like x/zvparm, except that if the parameter being returned is REAL, the VALUE parameter is returned in double precision format. x/zvparm returns the value in single precision. Although VALUE supports integers and strings as well, x/zvparmd should generally be used only for double-precision numbers. x/zvparm should be used for integers and strings.
This routine replaces the functionality of the R8FLAG parameter that was previously on x/zvparm.

Arguments:

• NAME: string, input
  NAME is the name of the parameter to get values from.
• VALUE: parameter—value-array, output
  The value of the parameter is returned in the VALUE array. The type of the value depends on the type of the parameter, which is either INTEGER, STRING, or REAL (double-precision).
• COUNT: integer, output
  Reports the number of values returned in the VALUE parameter. A COUNT of 0 means the parameter either had a null value or was not found.
• DEF: integer, output
  Returns 1 if the parameter was defaulted, and 0 otherwise.
  NOTE: The DEF flag is obsolete and should not be used.
• MAXCNT: integer, input
  Specifies the maximum number of values to return. 0 means no limit.
• LENGTH: integer, input
  Specifies the length of each string if a string array is passed in for VALUE. Useful only from C; FORTRAN gets string lengths automatically. If the parameter is not a string, or is only a single string, set LENGTH to 0.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.12 x/zvpcnt—Return the count of a parameter.

call xvpcnt( namarg, count) 
status = zvpcnt( namarg, count) 

x/zvpcnt returns the parameter size information for a given parameter whose name is passed in the NAMARG parameter.
If an error occurs, such as the parameter wasn't found, then COUNT is returned as 0, and the action specified by x/zveaction is taken.

Arguments:

• NAMARG: input, string
  The name of the parameter whose count is desired. NAMARG may be passed either by descriptor ( FORTRAN character) or by reference.
• COUNT: output, integer
  The actual count of the parameter. For example, if the parameter is declared in the PDF file as having a count of up to 3, as in PARM I TYPE=INTEGER COUNT=1:3, and if the user specifies I=(4,7), then COUNT will be returned as 2.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.13 x/zvpone—Single value from a multivalued parameter

status = xvpone(name, value, instance, maxlen) 
status = zvpone(name, value,instance, maxlen);

This routine returns a single value from a multi-valued parameter. It is most useful to get a string from a list of strings without having to mess with string arrays, but can be used for integer or real (single-precision) values as well. xvpone is a FORTRAN function with a status return, which differs from most FORTRAN RTL routines .

Arguments:

• NAME: string, input
  NAME is the name of the parameter to get a value from.
• VALUE: parameter—value, output
  The value of the parameter is returned in VALUE. The type of the value depends on the type of the parameter, which is either INTEGER, STRING, or REAL (single-precision). There is no equivalent to x/zvpone for double precision floating point; use x/zvparmd instead.
• INSTANCE: integer, input
  INSTANCE specifies which value you want. INSTANCE starts counting at 1, so the fifth value would have an INSTANCE of 5.
• MAXLEN: integer, input
  MAXLEN specifies the maximum length of the string buffer if the parameter is a string. It is used to avoid overflowing your buffer. If the parameter is not a string, or you don't care, set MAXLEN to 0. MAXLEN is rarely needed in FORTRAN, since string lengths are available from the strings themselves.
• STATUS: output, integer
  Error status code. A value of one indicates success. The error codes are listed in 10 Appendix B: Error Messages .

5.2.14 x/zvpstat—Information about a parameter

call xvpstat(name, count, def, maxlen, type) 
status = zvpstat(name, count,def, maxlen, type);

This routine returns information about a parameter without returning its value. It is most useful to get the maximum length of any string and the number of strings in order to allocate a buffer before calling x/zvparm. This routine is also the only way to determine the data type of a parameter given only its name. The program should know the type in the PDF, but there are situations where this could be useful .

Arguments:

• NAME: string, input
  NAME is the name of the parameter to get information about.
• COUNT: integer, output
  Returns the number of items in the parameter. If 0, parameter is either not found or is null.
• DEF: integer, output
  Returns 1 if the parameter was defaulted, and 0 otherwise.
  NOTE: The DEF flag is obsolete and should not be used.
• MAXLEN: integer, output
  Returns the maximum length of any value in the parameter. For REAL and INT, it is just the size of a REAL or INT. For STRING, it is the length of the longest string in the parameter. It does not include the null terminator, so you should add one before allocating a buffer in C.
• TYPE: string, output
  Returns the data type of the parameter. The possible values are “INT”, “REAL”, and “STRING”.

5.2.15 x/zvptst Indicate whether key word was specified

GIVEN = xvptst( key ) 
GIVEN = zvptst( key ); 

This function returns true if a key word was specified and false if not. For example, a program could check if the value “HALF” was given for a key word parameter with the code:

logical lhalf,xviptst

      lhalf = xviptst('HALF')
      if (lhalf) then
        .
        .
        .

The key word must be a value specified for a parameter of type KEYWORD. Note: Should be declared as a LOGICAL function in FORTRAN, as in the above example.

Arguments:

• KEY: input, string
  Name of key word to be tested for. Note this is not the parameter name, but one of the valid values for the key word parameter. Passed either by descriptor in FORTRAN (if CHARACTER string is passed) or reference in C (if char* array is passed).