JWAVE Server Development

This chapter discusses the following topics:

How to write JWAVE wrappers
Retrieving parameters from the server
Using GETPARAM to unpack value, positional, and keyword parameters
Returning parameters to the client
Returning multiple results
Handling errors
Testing wrapper functions

JWAVE Server Overview

Client JWAVE Java programs communicate with PV-WAVE through a PV-WAVE function called a JWAVE wrapper. A JWAVE wrapper function is a PV-WAVE function that contains some specific JWAVE API calls. These JWAVE-specific functions are included in the dynamically loaded JWAVE library; therefore, to the JWAVE developer, these functions can be used just like any PV-WAVE function.

TIP: The JWAVE wrapper API functions are described in Appendix A, JWAVE Wrapper API.

Typically, a JWAVE wrapper function is used as an interface between the JWAVE client and one or more PV-WAVE applications. The JWAVE wrapper receives parameters from the client, processes those parameters in some manner, and returns information back to the client. The returned information can be numeric or string values (except complex numbers), including scalars and arrays. The server can also return graphics to the client if PV-WAVE graphics commands were used in the JWAVE wrapper.

Writing JWAVE Wrapper Functions

This section explains how to write JWAVE wrapper functions. JWAVE wrapper functions are PV-WAVE functions that contain JWAVE wrapper API calls, such as GETPARAM and GET_NAMED_COLOR. The wrapper API functions are described in

Appendix A, JWAVE Wrapper API

Example: Simple JWAVE Wrapper

The following JWAVE wrapper:

retrieves a single parameter from the client,
"unpacks" the parameter
processes the parameter
returns a result

Example 5-1 Simple JWAVE wrapper function

FUNCTION PASSARR, client_data

   ; Unpack parameters received from the client. 
   arr =    GETPARAM(client_data, 'ARRAY', /Value)

   ; Change the array. 
   mydata = arr * 1.5

   ; Return the changed array. 
   RETURN, mydata
END

The Input Parameter: client_data

All JWAVE wrappers have a consistent interface. They all are functions that accept one parameter called, by convention, client_data.

The client_data parameter passes parameter name(s) and data that were "packaged" by the client Java program. (JWAVE client developers use the setParam method of the JWaveExecute class to "package" the parameters.) When the Java client calls the JWaveExecute.execute method, the packaged parameters are automatically sent in an array to the appropriate JWAVE wrapper function. (The Java client application also specifies the name of the wrapper function it intends to execute.)

The GETPARAM Function

The GETPARAM function unpacks the information sent in the client_data parameter. In

Example 5-1

client_data The parameter information that was passed to the wrapper function from the client.

'ARRAY' The name of the parameter to unpack. This name was assigned in the client Java program at the time the parameter was "packaged" (with the setParam method).

/Value The Value keyword tells GETPARAM to retrieve just the value of the parameter that was sent. (See the following note.)

NOTE: In other situations, it is necessary for GETPARAM to return more than the value. For instance, in many cases, the JWAVE wrapper function will be used to execute one or more PV-WAVE functions. Typically, this is accomplished with the PV-WAVE EXECUTE command, and parameters from the client that were unpacked by GETPARAM are used to "build" a string containing the command for EXECUTE. To facilitate these cases, GETPARAM can return a string that is formatted appropriately. For example, if the Positional keyword were used instead of Value, GETPARAM would return a string of the form: ", param_reference" (where param_reference is a symbolic reference to a value). The result could then be used directly in an EXECUTE statement. For example:

x1=GETPARAM(client_data, 'ARRAY', /Positional)
status=EXECUTE("PLOT"+ x1)

We will discuss the use of the Positional and Value keywords later in this chapter.

The RETURN Statement

When RETURN is called in a JWAVE wrapper, the return parameters/data are automatically packaged and sent back to the client Java application. The client can access this data using the default return parameter name DATA. See

Returning Multiple Results to the Client

Wrapper Functions Must Be Compiled

The

.cpr

For example, a typical series of commands that you can use to compile a single PV-WAVE routine is:

WAVE DELPROC, /All 
WAVE DELFUNC, /All 
WAVE .RUN mywrapper.pro 
WAVE COMPILE, /All, File='mywrapper.cpr'

TIP: We have provided a set of routines that you can use to test your JWAVE wrapper functions before compiling them and publishing them on your Web server. See Testing Wrapper Functions for more information.

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.

In this case, the goal is to execute a PV-WAVE PLOT command with the 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

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

Example 5-5

page 64

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

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)

Unpacking Color Data

Another JWAVE wrapper function,

Unpacking Color Information with GET_NAMED_COLOR

Returning Multiple Results to the Client

You can easily package multiple results (arrays and scalars) and return them to the client where they can be unpacked and used.

To package multiple results on the server, create and return an associative array of data name/value pairs. For example:

Example 5-2 JWAVE wrapper function that returns multiple results to the client

FUNCTION PASSFFT, client_data
   ; Get the data from the client. 
   arr =    GETPARAM(client_data, 'ARRAY', /Value)
      ;Process the data, creating two separate variable results 
   freq = FLOAT(ABS(FFT(arr, -1)))
   distrib = HISTOGRAM(freq)
      ;Create an associative array to send results back to the client. 
      RETURN, ASARR('FDATA', freq, 'HIST', distrib)
END

The resulting arrays, freq and distrib are packaged are returned to the client in the associative array. The associative array keys become the names of the returned data referenced by the client with the getReturnData method. The names of the data returned by this example are FDATA and HIST.

The following example shows a Java code fragment used to retrieve the parameters sent from the server and to properly cast the values.

Example 5-3 Client calls to unpack the associative array sent from the server.

//Get the FFT data 
float[] d = (float[]) command.getReturnData("FDATA");
//Get the histogram data 
int[] h = (int[]) command.getReturnData("HIST");

Returning Graphical Data to the Client

Example 5-4

NOTE: The client developer uses the JWaveView class to request that the server return graphical data in addition to numerical data. Whenever JWaveView is used to execute a client request to the server, the server automatically creates a Viewable object. This object is then packaged and streamed back to the client where it can be displayed. If the client calls the wrapper with the JWaveExecute class, the graphics are discarded, and only the data are returned. For more information on JWaveView and graphics, see Chapter 4, JWAVE Graphics.

Example 5-4 Simple JWAVE wrapper that returns a 2D plot

FUNCTION APLOT, client_data

   ; Unpack the parameters and data from the client. 
   arr =    GETPARAM(client_data, 'ARRAY', /Value)
      PLOT, arr
RETURN, 0

END

NOTE: You must make sure that all coordinate system information is correct before you return a plot to the client. Also, note that the SURFACE and AXIS procedures create a temporary axis transformation that is not automatically saved by the PV-WAVE session. To ensure that the correct transformation and coordinate system information is sent back to the client, use the Save keyword with these procedures. This causes the correct transformation information to be sent automatically to the client. For more information on coordinate transformations, see Coordinate System Transformations.

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.

TIP: 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

Example 5-5

jwave_plot.pro

: (UNIX)jwave-3_0/lib

: (Windows)jwave-3_0\lib

Example 5-5 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', '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' ] )

   ; 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 5-5

Example 5-1

SCALING

Value

Default

SCALING

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 positional 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.

TIP: For more information on JWAVE graphics and color parameters, see Chapter 4, JWAVE Graphics. See also Managing the Color Table on page A-18.

Example 5-6 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)

TIP: The following lines show the corresponding calls that were made in the Java client program to set the colors retrieved in Example 5-6:

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 be sent 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.

The RETURN Statement

The

You Can Only Retrieve Parameters Once

GETPARAM can only retrieve a parameter (positional, keyword, or value) once.

For example, the following GETPARAM calls retrieve parameters from the client:

foo = GETPARAM(client_data, 'foo') 
bar = GETPARAM(client_data, /All)

However, after the foo parameter is retrieved, it cannot be retrieved again in the subsequent call with the /All keyword. Therefore, in this case, the bar command string will not contain the foo parameter.

TIP: You can use the Ignore_Used keyword with GETPARAM to request that all requested parameters will be returned whether they have been used or not.

Error Handling

This section discusses some error handling techniques and tips for use in JWAVE wrapper functions.

Using the MESSAGE Procedure

Use the PV-WAVE MESSAGE procedure to generate error messages from JWAVE wrapper functions. The error text that MESSAGE produces is automatically sent to the client as a Java Exception (specifically, a JWaveWrapperException object). The MESSAGE procedure also causes the wrapper function to stop processing (by default).

For detailed information on MESSAGE, refer to the PV-WAVE Reference.

Trapping Errors

If you use PV-WAVE error handling routines (such as ON_ERROR_GOTO or ON_ERROR) to trap and handle errors in a JWAVE wrapper function, be sure to set !Error=0 immediately after the error trap to ensure that the error is not reported back to the client.

ON_ERROR and ON_ERROR_GOTO are described in the PV-WAVE Reference.

Using the Expect Keywords

GETPARAM takes a set of optional keywords that can be used for trapping input errors. These keywords are only used in conjunction with the Value keyword. (This is because they are used to test values that are passed from the client.)

These keywords all begin with the word Expect. They are:

ExpectType = type_code
/ExpectNumeric
/ExpectString
ExpectArray = [ dim1, dim2, ... ] or /ExpectArray
/ExpectScalar

The first three keywords (ExpectType, ExpectNumeric, and ExpectString) produce an error if the returned parameter does not match the expected data type. The valid data type codes that you can use with JWAVE are listed in the following table.


Type Code	Data Type
1	Byte
2	Integer
3	Longword integer
4	Floating point
5	Double precision floating
7	String

The keyword ExpectArray produces an error if the input parameter is not an array of the specified dimensions. For more information on the Expect* keywords, see

GETPARAM Function

The keyword ExpectScalar produces an error if the input parameter is not a scalar or a 1-element array. If the parameter is a 1-element array, then the function returns that element as a scalar.

As the following lines show, you can use reasonable combinations of the Expect* keywords in a single GETPARAM function.

; y must be a numerical array 
y = GETPARAM(client_data, 'Y', /Value, /ExpectArray, /ExpectNumeric 
) 
; xcnt and ycnt must be numerical scalars 
xcnt = GETPARAM(client_data, 'XCENTER', /Value, Default = 0.5, $ 
            /ExpectScalar, /ExpectNumeric ) 
ycnt = GETPARAM(client_data, 'YCENTER', /Value, Default = 0.5, $ 
          /ExpectScalar, /ExpectNumeric ) 
; title must be a scalar string. 
title = GETPARAM(client_data, 'TITLE',  /Value, Default = 'The 
Title', $
          /ExpectScalar, /ExpectString)

Testing Wrapper Functions

This section explains how to test JWAVE wrapper functions without writing client Java programs. The WRAPPER_TEST_* procedures are PV-WAVE procedures that you can use to imitate the behavior of the Java client application, such as setting parameters, setting colors, and setting and executing the JWAVE wrapper.

Testing a Numerical Program

For example, let's look at how you can test the JWAVE wrapper simple.pro that we discussed in

Chapter 1, JWAVE System Introduction

simple.pro

WAVE WRAPPER_TEST_INIT, 'SIMPLE'
WAVE WRAPPER_TEST_SETPARAM, 'NUMBER', 2
WAVE WRAPPER_TEST_EXECUTE
WAVE WRAPPER_TEST_RETURN_INFO
DATA            FLOAT     =       1.41421
WAVE

Here we set the wrapper, set a parameter, executed the wrapper, and printed the return data.

The procedures used to test this wrapper correspond to the Java methods used to set parameters, and so on, in the client application. The following table shows the correspondence between these PV-WAVE test routines and the Java methods they imitate:


Test Procedure	JWAVE Java Method
`WRAPPER_TEST_INIT`	`JWaveExecute.setFunction` and JWaveView.setSize (optional)
`WRAPPER_TEST_SETCOLOR`	`JWaveView.setNamedColor`
`WRAPPER_TEST_SETPARAM`	`JWaveExecute.setParam`
`WRAPPER_TEST_EXECUTE`	`JWaveExecute.execute`
`WRAPPER_TEST_GETRETURN`	`JWaveExecute.getReturnData`
`WRAPPER_TEST_RETURN_INFO`	`Parameter.printInfo`

Testing a Graphics Program

You can also use the WRAPPER_TEST_* routines to test wrapper functions that generate graphics. To do this, specify the window size to WRAPPER_TEST_INIT, as shown in one of the examples below. If the wrapper returns a graphic, then the test procedure WRAPPER_TEST_EXECUTE displays the graphic in a PV-WAVE window.

Here is an example that tests the wrapper jwave_plot.pro. You can find this wrapper function in:

: (UNIX)VNI_DIR/jwave-3_0/lib

: (Windows)VNI_DIR\jwave-3_0\lib

where VNI_DIR is the main Visual Numerics installation directory.

WAVE WRAPPER_TEST_INIT, 'JWAVE_PLOT', 300, 300 
WAVE WRAPPER_TEST_SETCOLOR, 'BACKGROUND', '000000'xL ; black
WAVE WRAPPER_TEST_SETCOLOR, 'LINE', 'ff0000'xL ; blue
WAVE WRAPPER_TEST_SETPARAM, 'Y', HANNING(20,20)
WAVE WRAPPER_TEST_SETPARAM, 'PSYM', 1
WAVE WRAPPER_TEST_EXECUTE

Here, note that the WRAPPER_TEST_SETCOLOR procedure is used to set line and background colors. When WRAPPER_TEST_EXECUTE is run, the plot is displayed in a PV-WAVE graphics window.

For detailed information on each of the WRAPPER_TEST_* routines, see Appendix A, JWAVE Wrapper API.

Summary

This chapter explained how to develop and test JWAVE wrapper functions. A JWAVE wrapper function is a PV-WAVE function that communicates, through the JWAVE Manager, with a JWAVE client (Java) application. JWAVE wrappers use functions for "unpacking" parameters sent from the client. The RETURN statement in a JWAVE wrapper automatically packs and returns parameters and data to the Java client.

You can use standard PV-WAVE error trapping routines to trap errors in a JWAVE wrapper function. If you trap and handle errors within the wrapper function, be sure to reset the !Error system variable to 0 after the error is trapped to prevent an error message from being returned to the client.

Remember that JWAVE wrapper functions, and any PV-WAVE functions that run on the JWAVE server, must be compiled with the PV-WAVE COMPILE command.

JWAVE Server Development

JWAVE Server Overview

Writing JWAVE Wrapper Functions

Example: Simple JWAVE Wrapper

The Input Parameter: client_data

The GETPARAM Function

The RETURN Statement

Wrapper Functions Must Be Compiled

Using GETPARAM to Unpack Parameters

What Do You Want To Unpack?

Unpacking Values

Using the Default Keyword

The Expect* Keywords

Unpacking Command Strings

Positional vs. Keyword Parameters

Unpacking Positional Parameters

Unpacking Keyword Parameters

Building a PV-WAVE EXECUTE Command

Unpacking Color Data

Returning Multiple Results to the Client

Returning Graphical Data to the Client

Example: A Typical JWAVE Wrapper

Unpacking the Parameters

Unpacking Values

Unpacking Keywords

Unpacking Positional Parameters

Unpacking Color Information with GET_NAMED_COLOR

The RETURN Statement

You Can Only Retrieve Parameters Once

Error Handling

Using the MESSAGE Procedure

Trapping Errors

Using the Expect Keywords

Testing Wrapper Functions

Testing a Numerical Program

Testing a Graphics Program

Summary