GETPARAM Function

client_data—A variable containing parameters and data that were passed to the JWAVE wrapper function from a JWAVE client application. (This parameter receives the information that was set with calls to the setParam method on the client.)

param_name—A string or string array specifying the name(s) of the parameter(s) to extract from the client_data variable.

note	The param_name parameter cannot be an array when either the Value or Positional keyword is specified.

All—If nonzero, returns all of the keywords in the client_data variable. You do not need to specify the param_name parameter if you use the All keyword. Any keywords that were previously retrieved are ignored. Note that All retrieves parameters as keywords only. It does not retrieve positional parameters or values. The All keyword cannot be used when either the Value or Positional keyword is specified.

ClientID—If nonzero, returns a unique number identifying the client making this request. You can use this keyword without specifying a param_name parameter.

Default—Specifies a default value to use if the given param_name was not provided by the client. This keyword can only be used when Value is specified. The default value can be any valid PV‑WAVE data type.

ExpectType—Provides type checking of returned values. This keyword is only allowed when the /Value keyword is specified. For example:

where type_number is the PV‑WAVE data type number (for instance, the number returned from the PV‑WAVE function: SIZE(val, /Type).

This test fails if the returned parameter does not match the expected type. On failure, the MESSAGE procedure is called.

ExpectNumeric, ExpectString—If nonzero, provides type checking of returned values.

These tests fail if the returned parameter does not match the expected type. On failure, the MESSAGE procedure is called.

ExpectArray—Ensures that the function returns an array of the specified dimensions. If the param_name represents a scalar, a one-element array is returned. For example:

tests for a 400-by-600 element array. If any dimension is a zero (0), that dimension is taken as a wildcard (that dimension may be of any size).

This test fails if the returned parameter is not of the specified dimensions. On failure, the MESSAGE procedure is called.

ExpectScalar—Ensures that the function returns a scalar. If the parameter is a one-element array, it is converted to a scalar, and a scalar is returned. This test fails if the returned parameter is an array of more than one element. On failure, the MESSAGE procedure is called.

Keyword_Names—A string or string array of keyword names. Keywords are returned in the form:

where param_name is the keyword name and param_ref is a symbolic reference to the value associated with the keyword. For example:

produces a string of the form:

By default, the parameter name and keyword name are the same. If Keyword_Names is an array, it must be the same number of elements as param_name.

note	The Keyword_Names keyword cannot be used when either the Value or Positional keyword is specified.

See the Discussion section for more information on Keyword_Names.

IgnoreUsed—If nonzero, the parameters you request are returned regardless of if they have been previously retrieved. In addition, the parameters that you request are not added to the list of “used” parameters.

Positional—If nonzero, indicates that the requested parameter is a positional parameter. The returned string is of the form:

where param_ref is a symbolic reference to data. See the Discussion section for more information on this keyword.

SessionID—If nonzero, returns a unique number identifying this PV‑WAVE session. This keyword is useful if you need to build a unique temporary filename. You can use this keyword without specifying a param_name parameter.

Value—If nonzero, indicates that the actual data be returned rather than a string. See the Discussion section for more information on this keyword.

WrapperName—If nonzero, returns a string naming the JWAVE wrapper function called by the client. You can use this keyword without specifying a param_name parameter.

You can use GETPARAM to return:

See JWAVE Client Development for additional information on using GETPARAM. The rest of this section describes these types of results briefly.

To return a single value with GETPARAM, use the Value keyword. For example:

In this case, the actual value associated with the parameter X (which was passed to the JWAVE wrapper from the client application) is stored in result. The value can then be used in any PV‑WAVE routine within the JWAVE wrapper. For example:

note	If the param_name parameter is not set by the client, then GETPARAM returns either zero (0) or the value specified with the Default keyword.

To return a positional parameter string, use the Positional keyword. For example:

returns a string of the form:

where param_ref is a symbolic reference to the value of the parameter X. Usually this value is a data reference or function call.

The comma (,) is included in the string so you can concatenate strings of this form together to build a command. Such a command string, then, can be used as input to an EXECUTE function. For example:

note	If the param_name parameter to GETPARAM was not set by the client, GETPARAM returns an empty string.

For more information on positional parameters, see "Unpacking Command Strings".

To return a string of keyword parameters, call GETPARAM without either the Value or Positional keywords. For example:

returns a string of the form:

where param_name is the name of the parameter (for example, TITLE) and param_ref is a symbolic reference to the value of the parameter.

The comma (,) is included in the string so you can concatenate strings of this form together to build a command. Such command strings, then, can be used as input to an EXECUTE function. For example:

If the second parameter to GETPARAM is an array, the function returns a string in the following form:

note	If the param_name parameter to GETPARAM was not set by the client, GETPARAM returns an empty string.

For more information on positional parameters, see "Unpacking Command Strings".

Use the All keyword to return all of the keyword parameters that were sent by the client in one string array. For example, the command:

returns a string of the form:

where param_name_* are all parameters sent by the client, and param_ref* are symbolic references to the values of those parameters.

note	Call GETPARAM with the All keyword after you have retrieved all of the positional and value parameters to ensure that you retrieve only the remaining keywords.

tip	We suggest that you use a param_name array rather than All so that the client cannot accidently send invalid parameters to the JWAVE wrapper function.

In all the cases above, you can only retrieve a parameter once. After you have retrieved a parameter, it is marked as used, and further calls to GETPARAM will not retrieve it again. This feature allows you to call GETPARAM for some parameters, and then call GETPARAM with /All to obtain a string containing all the rest of the keyword parameters. You can use the IgnoreUsed keyword to circumvent this restriction.

The keywords All, Positional, and Value are mutually exclusive, that is you can only use one of them for each call to GETPARAM.

All and Positional are exclusive because the returned order of the parameters is not known.

Similarly, if you specify either Positional or Value, then param_names cannot be an array.

Keyword_Names must be a string (array) with the same number of elements as param_names.

The Expect* tests do not check your Default value, but only values supplied by the client.

The client_data parameter must be a plain variable reference, and not a subscripted array or expression.

ClientID, SessionID, and WrapperName are mutually exclusive. These keywords also cause all other keywords to be ignored.

Here is an example showing how the SessionID keyword can be used to build a unique, temporary filename:

See the previous Discussion section for other examples. See also JWAVE Server Development for additional information and examples.