GETPARAM Function
Retrieves parameters and data sent from a JWAVE client application.
Usage
result = GETPARAM(client_data, param_name)
result = GETPARAM(client_data, param_name, /Value)
result = GETPARAM(client_data, param_name, /Positional)
Input Parameters
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. |
Keywords
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:
ExpectType = type_number 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:
ExpectArray = [400, 600] 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:
” , param_name=param_ref ”
where param_name is the keyword name and param_ref is a symbolic reference to the value associated with the keyword. For example:
result = GETPARAM(client_data, 'PARAM_NAME', $
Keyword_Name = 'PARAM_KEY')
produces a string of the form:
" ,PARAM_KEY=param_name_ref "
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:
” , param_ref ”
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.
Discussion
You can use GETPARAM to return:
single values positional parameters keyword parameters See Chapter 3: JWAVE Client Development for additional information on using GETPARAM. The rest of this section describes these types of results briefly.
Returning Single Values
To return a single value with GETPARAM, use the Value keyword. For example:
result = GETPARAM(client_data, 'X', /Value, $
Default=FINDGEN(100))
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:
PLOT, result
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. |
Returning Positional Parameters
To return a positional parameter string, use the Positional keyword. For example:
p1 = GETPARAM(client_data, 'X', /Positional)
returns a string of the form:
" , param_ref " 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:
status = EXECUTE('PLOT' + p1)
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".
Returning Keyword Parameters
To return a string of keyword parameters, call GETPARAM without either the Value or Positional keywords. For example:
title = GETPARAM(client_data, 'TITLE')
returns a string of the form:
" , param_name=param_ref " 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:
status = EXECUTE('PLOT' + p1 + title)
If the second parameter to GETPARAM is an array, the function returns a string in the following form:
" , param_name_1=param_ref_1, param_name_2=param_ref_2, ... "
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".
Returning All Keyword Parameters
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:
result = GETPARAM(client_data, /All)
returns a string of the form:
", param_name_1=param_ref1, param_name_2=param_ref2, ... "
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. |
Parameters Are Retrieved Once
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.
Notes and Restrictions
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.If you specify Positional, Value, or All, you cannot use Keyword_Names.Keyword_Names must be a string (array) with the same number of elements as param_names.ExpectNumeric, ExpectString, and ExpectType are mutually exclusive.ExpectArray and ExpectScalar are mutually exclusive.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. Examples
Here is an example showing how the SessionID keyword can be used to build a unique, temporary filename:
temp_file = STRTRIM(getParam(client_data), /SessionID), 2)
temp_file = FILEPATH(temp_file, /Tmp)
See the previous Discussion section for other examples. See also Chapter 5: JWAVE Server Development for additional information and examples.
See Also
In the PV‑WAVE Reference: EXECUTE
