Using GETPARAM to Unpack Parameters

JWAVE User Guide > JWAVE Server Development > Using GETPARAM to Unpack Parameters

As explained in the previous section, parameters sent from the client are received as input by the JWAVE wrapper function on the server. The GETPARAM function (a PV‑WAVE function) is used to retrieve and unpack these parameters. The GETPARAM function provides keywords that let you control how parameters are unpacked. This section discusses GETPARAM and how its keywords are used to unpack parameters.

What Do You Want To Unpack?

When you write a JWAVE wrapper function, typically your goal is to retrieve parameters from the client and then execute some PV‑WAVE functions that use those parameters.

For instance, if your JWAVE client application displays a 2D plot, you might send the following parameter information to the server:

X—An array of floating point values to plot.

TITLE—A title for the plot.

LINESTYLE—Type of line to plot.

The setParam methods used on the client to set these parameters might look like this:

setParam(”X”, anarray)

setParam(”TITLE”, ”Peak Concentrations”)

setParam(”LINESTYLE”, 1)

When the client calls its execute method, the JWAVE wrapper on the server receives this information through its input argument, usually called client_data. You must decide how to unpack this data.

Here, the goal is to execute a PV‑WAVE PLOT command with parameters that were received from the client. For example, you might want to run a PV‑WAVE PLOT command with these parameters and keywords:

PLOT, X, Title=thetitle, Linestyle=thestyle

Generally, you can unpack values or command strings. These topics are discussed in following sections.

Unpacking Values

You can use GETPARAM to unpack data in two ways: as values or as command strings. To unpack values, you specify the Value keyword with GETPARAM. For example:

x_val = GETPARAM( client_data, 'X', /Value )

note	client_data is the single parameter passed to a JWAVE wrapper function, as in: FUNCTION MY_WRAPPER, client_data

In this instance, a reference to the value of the X parameter (set by a client’s
setParam call) is assigned to the PV‑WAVE variable x_val. Then, x_val can be used in any valid context. For example:

PLOT, SQRT( x_val )

Using the Default Keyword

When you use the Value keyword, you may also use the Default keyword to specify a default value to be assigned if the client did not pass that parameter.

For example, if the client sets parameters as follows:

setParam(”X”, anarray)

setParam(”TITLE”, ”Peak Concentrations”)

setParam(”LINESTYLE”, 1)

The body of a JWAVE wrapper function that retrieves those parameters might look like this:

x_val=GETPARAM( client_data, 'X', /Value, Default=FINDGEN(10) )

the_title = GETPARAM( client_data, 'TITLE', /Value, Default='' )

lstyle = GETPARAM( client_data, 'LINESTYLE', /Value, Default=0 )

PLOT, x_val, Title=the_title, Linestyle=lstyle

This makes a plot with the specified data, a title, and a linestyle. If the client did not specify the data X, then the default dataset FINDGEN(10) is used. The default plot title is an empty string, and the default linestyle is 0 (solid).

The Expect* Keywords

When using the Value keyword, you can use a set of Expect* keywords to help you ensure that the data the client has passed is what you expect. These keywords cause GETPARAM to test the data to ensure that it meets your expectations, and an error is generated if the data is invalid. (If an error occurs, the client’s execute method throws an exception.)

The Expect* keyword options are:

/ExpectScalar

/ExpectArray or ExpectArray = array_of_dimensions

ExpectType = wave_type_code

/ExpectNumeric

/ExpectString

These keywords help you to ensure that the client does not “break” the wrapper by passing unexpected or invalid data.

For examples that use the Expect* keywords, see "Using the Expect Keywords".

Unpacking Command Strings

The other method for unpacking data allows you to build a command string for use with the PV‑WAVE EXECUTE function. In this mode, GETPARAM returns strings that can be concatenated together to form a coherent command string.

There are two distinct kinds of parameters in PV‑WAVE: positional and keyword. Thus there are two methods used to get these strings from GETPARAM. Positional and keyword parameters will be discussed in more detail in the next section, but as an example, the JWAVE wrapper code we saw in the previous section might be re-written as follows:

cmd = 'PLOT'

cmd = cmd + GETPARAM( client_data, 'X', /Positional )

cmd = cmd + GETPARAM( client_data, [ 'TITLE', 'LINESTYLE' ] )

status = EXECUTE( cmd )

A string representation of X is used as a positional parameter, and LINESTYLE and TITLE are used as keywords. The resulting string cmd might look something like this:

”PLOT, x_reference, TITLE=title_reference, LINESTYLE=linestyle_reference”

note

GETPARAM does not extract actual data from client_data; rather, it extracts a symbolic reference to data. The data that is referenced might have been sent by the client or retrieved from memory on the server. Therefore, the command:

x = GETPARAM(client_data, 'X', /Positional)

returns a string in the form “ , param_reference”, where param_reference is a reference to data that was either sent from the client or retrieved from the Data Manager. This concept is discussed further in the next few sections.

When you use GETPARAM without the Value keyword, you do not have the option of using the Default or Expect* keywords. The returned string for a missing parameter (a parameter not passed by the client) is an empty string (that is, the keyword parameter is left off of the command if it was not supplied by the client.) You can easily check to ensure required parameters are received, as shown in ; JWAVE wrapper that unpacks positional and keyword parameters on ; JWAVE wrapper that unpacks positional and keyword parameters.

Positional vs. Keyword Parameters

Note that the PLOT command that you need to build (for use in the EXECUTE function) consists of a positional parameter, X, and two keyword parameters, Title and Linestyle. In PV‑WAVE, positional parameters are of the form:

”, param”

while keyword parameters are of the form:

”, KeywordName=Value”

PV-WAVE PLOT Command shows the PV‑WAVE PLOT command with one positional parameter and one keyword:

Figure 5-1: PV-WAVE PLOT Command

The way in which you unpack parameters in the JWAVE wrapper depends on whether you are unpacking a positional or a keyword parameter.

Unpacking Positional Parameters

Continuing the PLOT example used previously, the JWAVE wrapper function must use the GETPARAM function to unpack the parameters.

The first parameter to unpack is the data parameter X. Note that X is a positional parameter in the PV‑WAVE PLOT command.

To unpack a positional parameter, use the GETPARAM function with the Positional keyword, as follows:

param1=GETPARAM(client_data, 'X', /Positional)

If the value assigned to X is an array, this function might return the following string in the param1 variable.

” , array_reference ”

where array_reference is a symbolic reference to the data. (The actual data could have been sent from the client or retrieved from the Data Manager.)

As noted before, this returned string is in the expected form of a positional parameter in a PV‑WAVE function:

” , param”

The returned string can now be used to “build” a PLOT command using the EXECUTE function. For example:

ret=EXECUTE('PLOT' + param1)

Unpacking Keyword Parameters

If the Positional keyword is not used, then GETPARAM assumes the parameter is a keyword parameter and returns a string in the form:

”, KeywordName=keyword_reference”

where keyword_reference is a reference to the value of the keyword. (This value could have been sent from the client or retrieved from the server.)

For example, to unpack the Title keyword, use the following GETPARAM call:

title=GETPARAM(client_data, 'TITLE')

Here, the function returns the following string in the title variable:

” , TITLE=title_reference ”

where title_reference is a symbolic reference to the title data.

note	Again, remember that GETPARAM does not extract and return an actual value from client_data. Rather, the function builds a symbolic reference to a value into the string.

Building a PV-WAVE EXECUTE Command

The GETPARAM function returns strings that are formatted appropriately to be used in a PV‑WAVE EXECUTE command. EXECUTE compiles and executes one or more PV‑WAVE statements contained in a string at runtime.

For example, the client application (written in Java) packs the data:

command= new JWaveView(connection, ”JWAVE_PLOT”)

int[] data = {1,2,3,4,5};

command.setParam(”X”, data);

command.setParam(”TITLE”, ”CO2 Data”);

command.setParam(”LINESTYLE”, 1);

On the server, JWAVE wrapper commands unpack the parameters and build an EXECUTE command:

result=GETPARAM(client_data, 'X', /Positional)

keywords=GETPARAM(client_data, ['TITLE', 'LINESTYLE'])

status=EXECUTE(”PLOT” +result + keywords)

Version 3.6