Writing JWAVE Wrapper Functions

JWAVE User Guide > JWAVE Server Development > 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 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

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

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

GETPARAM Function

The GETPARAM function unpacks the information sent in the client_data parameter. In Simple JWAVE wrapper function, GETPARAM happens to retrieve an array. The GETPARAM arguments include:

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.

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" for information on sending multiple results back to the client.

Wrapper Functions Must Be Compiled

The JWAVE server operates in PV‑WAVE runtime mode. Therefore, all functions and procedures (including wrapper functions) that run on the JWAVE server must be compiled into .cpr files using the PV‑WAVE COMPILE procedure.

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'

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

Version 3.6