result = GETPARAM(client_data, param_name, /Value)
result = GETPARAM(client_data, param_name, /Positional)
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.
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 be used if the given param_name was not provided by the client. This keyword can only be used when the Value keyword 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
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]
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 "
result = GETPARAM(client_data, 'PARAM_NAME', $
Keyword_Name = 'PARAM_KEY')
" ,PARAM_KEY=param_name_ref "
NOTE: The Keyword_Names keyword cannot be used when either the Value or Positional keyword is specified.
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 "
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.
Returning Single Values
result = GETPARAM(client_data, 'X', /Value, Default=FINDGEN(100))
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
p1 = GETPARAM(client_data, 'X', /Positional)
" , param_ref "
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.
Returning Keyword Parameters
title = GETPARAM(client_data, 'TITLE')
" , param_name=param_ref "
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)
" , 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.
Returning All Keyword Parameters
result = GETPARAM(client_data, /All)
", 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
Notes and Restrictions
temp_file = STRTRIM(getParam(client_data), /SessionID), 2) temp_file = FILEPATH(temp_file, /Tmp)
