Example: A Typical JWAVE Wrapper

JWAVE User Guide > JWAVE Server Development > Example: A Typical JWAVE Wrapper

This example demonstrates and reinforces concepts that were discussed previously in this chapter.

This JWAVE wrapper function retrieves positional and keyword parameters from the client, unpacks the parameters, and builds a command string for use in a PV‑WAVE EXECUTE function. This example also demonstrates the GET_NAMED_COLOR function, which allows colors to be passed by name from the client to the JWAVE wrapper.

note	Refer to the PV-WAVE Reference for information on the EXECUTE, PLOT, and OPLOT commands. These PV‑WAVE commands are used in the following example.

The code for the JWAVE wrapper, jwave_plot_simple, is a simplified version of jwave_plot.pro, which can be found in:

(UNIX) jwave-3_6/lib

(WIN) jwave-3_6\lib

; JWAVE wrapper that unpacks positional and keyword parameters

; and builds a command string.

FUNCTION JWAVE_PLOT_SIMPLE, client_data

; Determine plot type (Can also be done with [XY]Type)

CASE GETPARAM(client_data, 'SCALING', /Value, Default=0) OF

1: cmd = 'PLOT_OI'

2: cmd = 'PLOT_IO'

3: cmd = 'PLOT_OO'

ELSE: cmd = 'PLOT'

ENDCASE

; Get colors -- default is black lines on white background.

back = GET_NAMED_COLOR('BACKGROUND', Default='000000'xL)

fore = GET_NAMED_COLOR('COLOR', Default = 'ffffff'xL)

acol = GET_NAMED_COLOR('AXIS', Default = fore)

color_kwds = ', Background=back, Color=fore'

; Get allowed keywords for the PLOT command.

plot_kwds = GETPARAM(client_data, $
[ 'Box', 'Charsize', 'Charthick', 'Clip', 'Grid style', $
'Linestyle', 'Noclip', 'Nsum', 'Polar', 'Position', $
'Psym', 'Solid_Psym', 'Subtitle', 'Symsize', 'Thick', $
'Tick format', 'Ticklen', 'Title', 'XCharsize', $
'XGridstyle', 'XMar gin', 'XMinor', 'XRange', 'XStyle', $
'XTickformat', 'XTicklen', 'XTickname', 'XTicks', $
'XTickv', 'XTitle', 'XType', 'YCharsize', 'YGridstyle', $
'YMargin', 'YMinor', 'YNozero', 'YRange', 'YStyle', $
'YTickformat', 'YTicklen', 'YTickname', 'YTicks', $
'YTickv', 'YTitle', 'YType' ] )

; Get positional data.

y = GETPARAM(client_data, 'Y', /Positional)     ; REQUIRED

IF y EQ '' THEN $
MESSAGE, 'Parameter Y is required.'

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

; Execute the plotting function to draw the axes.

status = EXECUTE( cmd + x + y + color_kwds + plot_kwds )

RETURN, 0

END

Unpacking the Parameters

First, positional and keyword parameters sent from the client must be unpacked with GETPARAM.

note	Parameter names are not case sensitive. They must begin with a letter, and can contain only alphanumeric characters and the underscore character (_).

note

A client application that provides controls for generating and modifying the appearance of plots or other kinds of graphics probably needs to communicate positional and keyword parameter information to the server. The client user might use option menus to change the colors used in a plot, text fields to add plot titles, push buttons to add axes, and so on. The client developer must retrieve the parameter names and values from the user interface, package those parameters (with setParam and setNamedColor method calls), and send them to the server. As shown here, the JWAVE wrapper function then unpacks the parameters, generates the plot, and sends back a graphic for display on the client.

Unpacking Values

The first use of GETPARAM in Example: A Typical JWAVE Wrapper is basically the same as we’ve seen in previous examples (such as Example: Simple JWAVE Wrapper). Here, GETPARAM is used in a CASE statement to retrieve the appropriate PLOT command (PLOT, PLOT_IO, PLOT_OO, or PLOT_OI). The correct command is saved based on the value of the SCALING parameter that was passed from the client. As in previous examples, the Value keyword specifies that a simple value be returned. Also, the Default keyword is used to return a value, 0, if no SCALING parameter was sent from the client. In this case, no scaling causes the CASE statement to save the regular PLOT command.

CASE GETPARAM(client_data, 'SCALING', /Value, Default=0) OF

1: cmd = 'PLOT_OI'

2: cmd = 'PLOT_IO'

3: cmd = 'PLOT_OO'

ELSE: cmd = 'PLOT'

ENDCASE

Unpacking Keywords

The next GETPARAM call retrieves any of the supported plot keywords that may have been sent from the client. In this case, we include all of the keywords associated with the PV‑WAVE PLOT command. Positional parameters that are specifically related to the x and y data will be retrieved in a separate GETPARAM statement.

plot_kwds = GETPARAM(client_data, $
[ 'Box', 'Charsize', 'Charthick', 'Clip', 'Gridstyle', $
'Linestyle', 'Noclip', 'Nsum', 'Polar', 'Position', 'Psym', $
'Solid_Psym', 'Subtitle', 'Symsize', 'Thick', 'Tickformat', $
'Ticklen', 'Title', 'XCharsize', 'XGridstyle', 'XMargin', $
'XMinor', 'XRange', 'XStyle', 'XTickformat', 'XTicklen', $
'XTickname', 'XTicks', 'XTickv', 'XTitle', 'XType', $
'YCharsize', 'YGridstyle', 'YMargin', 'YMinor', 'YNozero', $
'YRange', 'YStyle', 'YTickformat', 'YTicklen', 'YTickname', $
'YTicks', 'YTickv', 'YTitle', 'YType' ] )

This statement extracts from client_data any keywords that were specified in the string array and their associated values. With this usage, the GETPARAM function returns a string array in the following form:

”, keyname_1=value_reference, keyname_2=value_reference, ... ”

where value_reference is a symbolic reference to a value that was either sent by the client or retrieved from the Data Manager.

For example, the client sends keyword/value pairs that the PLOT command expects, and GETPARAM unpacks them into a string array, containing keyword names and references to keyword values.

” , Title=title_ref, Ticklen=tick_ref, Charsize=charsize_ref ”

As noted previously, this “string array” can be used as part of a command in an EXECUTE call to produce a plot.

note	The list of keywords given in this GETPARAM function example represents all of the keywords that can be extracted. Any keywords in the list that are not sent by the client are simply ignored by GETPARAM. If no keywords are sent, this GETPARAM function would return a null (empty) string.

tip	We recommend that you use a string array (as was done in this example) to specify which keywords you wish to retrieve with GETPARAM. By specifying a string of names in GETPARAM, rather than using the /All keyword, you prevent your program from failing if the client sends unexpected information.

Unpacking Positional Parameters

The final two GETPARAM calls use the Positional keyword to retrieve positional parameters.

y = GETPARAM(client_data, 'Y', /Positional) ; REQUIRED

IF y EQ '' THEN $
MESSAGE, 'Parameter Y is required.'

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

The difference between keyword and positional parameters is their form. Keywords are of the form Keyname=value. For example, XTitle='Units Sold'. Positional parameters, on the other hand, of the form: paramname. For example, the PLOT command takes a required positional parameter (Y), an optional positional parameter (X), and numerous optional keywords. For example:

PLOT, y, Title='CO2 Content', Charsize=3

where y is a required parameter, and the other parameters are keywords.

When the Positional keyword is specified, GETPARAM returns the specified parameter in a string in the format: ”, param_reference ”, where param_reference is a symbolic reference to the data. The leading comma is needed because when this string is used in an EXECUTE command, it is concatenated with other strings to “build” a command.

If the required y parameter is not supplied by the client, this error is “trapped” (because GETPARAM returns an empty string) and the MESSAGE procedure is called. The effect of the MESSAGE procedure is discussed in "Error Handling".

Unpacking Color Information with GET_NAMED_COLOR

The GET_NAMED_COLOR function retrieves a color index from a color name set by the client. The client specifies a color name and a Java Color object. This object is sent to the JWAVE wrapper and GET_NAMED_COLOR translates that color object into a color that can be used by PV‑WAVE.

In this example, GET_NAMED_COLOR retrieves three colors that were specified by the client: BACKGROUND. COLOR, and AXIS.

note	For more information on JWAVE graphics and color parameters, see JWAVE Graphics. See also "Managing the Color Table".

JWAVE wrapper calls retrieve colors sent from the client.

back = GET_NAMED_COLOR('BACKGROUND', Default='000000'xL)

fore = GET_NAMED_COLOR('COLOR', Default = 'ffffff'xL)

axis = GET_NAMED_COLOR('AXIS', Default = fore)

The following lines show the corresponding calls that were made in the Java client program to set the colors previously retrieved:

myJWaveView.setNamedColor(”BACKGROUND”, java.awt.Color.lightGray)

myJWaveView.setNamedColor(”COLOR”, java.awt.Color.red)

myJWaveView.setNamedColor(”AXIS”, java.awt.Color.black)

These calls set colors to send to the server. The calls associate a color name (e.g., BACKGROUND) with a Java color object (e.g., Color.lightGray). These colors are packaged with the rest of the parameters and sent to the client.

RETURN Statement

The RETURN statement in a JWAVE wrapper can always be used to return data to the client. In this example, the primary function of the wrapper is to return a graphic—this particular wrapper does not generate any data that needs to be returned to the client. Thus, the RETURN statement simply returns 0. There is no reason, however, why this RETURN statement could not be used to return some other data.

Version 3.6