A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name of the data you wish to copy. new_var_name
A string containing a new variable name.
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name of the data you wish to copy. new_var_name
A string containing a new variable name.
Storage for the domain and data are automatically created if they do not already exist. If data with the new_var_name already exists, it is overwritten. The data name and domain name are used to uniquely identify a dataset stored on the JWAVE server. Normally, these names are set in the JWAVE client application.
To be valid, the domain name and data name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
STUFF from the default domain ($GLOBAL) and stores it in data named STUFF_COPY (in the same domain).
DMCopyData, ['$GLOBAL', 'STUFF' ], 'STUFF_COPY'
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name.
Returns true if the named data exists; returns false otherwise. Also returns false if the data_name is invalid.
A string containing the name of the domain that you wish to enumerate. If not specified (i.e., DMEnumerateData()), then the default domain ($GLOBAL) is enumerated.
A string array containing the data names for the data stored in the specified domain.
To be valid, the data_name input parameter name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name.
The data values stored under the specified data_name.
To be valid, the data_name input parameter name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
STUFF from the default domain ($GLOBAL) and stores it in a variable named my_data.
my_data = DMGetData( ['$GLOBAL', 'STUFF' ] )
NOTE: Normally, you do not need to run this procedure, because it is run automatically by the PV-WAVE server and by the WRAPPER_TEST_INIT routine.
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name of the data you wish to remove.
To be valid, the data_name input parameter name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name of the data you wish to rename. new_var_name
A string containing a new variable name.
The original data_name data no longer exists after this function is called.
Storage for the domain and data are automatically created if they do not already exist. If data with the new_var_name already exists, it is overwritten. The data name and domain name are used to uniquely identify a dataset stored on the JWAVE server. Normally, these names are set in the JWAVE client application.
To be valid, the data_name input parameter name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
STUFF from the default domain ($GLOBAL) and gives it a new name of NEW_STUFF (in the same domain).
DMRenameData, ['$GLOBAL', 'STUFF' ], 'NEW_STUFF'
A string containing the name of the data file to restore. This file must have been created with DMSave.
Erases everything in the Data Manager before restoring the contents of the file. By default, data from the file is added to the current Data Manager. Verbose
Prints information to the screen about the data that is being restored.
a JWAVE wrapper called initially by the client, or by the procedure indicated with the JWAVE_STARTUP configuration parameter. This configuration parameter is specified with the Configuration Tool, described in Setting Up the JWAVE Server. (By default, the initialization routine is called JWAVE_START.) ; Restore data from previous session
DMRestore, my_dm_data_file
; Add new 'STUFF' data if it does not already exist
IF (NOT DMDataExists( ['$GLOBAL', 'STUFF'] ) THEN BEGIN
status = DC_READ_FREE(my_ascii_data, stuff)
DMStoreData, ['$GLOBAL', 'STUFF'], stuff
ENDIF
A string containing the name of the file in which to save the data.
Prints information to the screen about the data that is being saved.
JWAVE_SHUTDOWN). This example first removes (deletes) any data that has been stored in a domain named TEMP. Then, everything else is saved to a DM data file. That file may be restored (with DMRestore) for later use by another session.
; Enumerate all data stored in the TEMP domain
temp_data = DMEnumerateData('TEMP')
IF temp_data(0) NE '' THEN BEGIN
; Remove all data from TEMP domain
FOR i = 0, N_ELEMENTS(temp_data)-1 DO BEGIN
DMRemoveData, ['TEMP', temp_data(i) ]
ENDFOR
ENDIF
; Save everything else
DMSave, my_dm_data_file
A scalar string containing a data name (in the default domain, $GLOBAL) or a 2-element string array containing a domain name and data name.value
The data that you wish to store.
To be valid, the data_name input parameter name must begin with a letter. The name is not case-sensitive, and may contain letters, underscores, and numbers.
The data specified with value can be of any PV-WAVE data type. Note that client applications can only store on the server scalars and arrays (up to eight dimensions) of the following data types:
| JAVA Data Types | Corresponding PV-WAVE Data Types |
|---|---|
| Byte | BYTE |
| Short | INTEGER |
| Integer | LONG |
| Float | FLOAT |
| Double | DOUBLE |
| String | STRING |
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)
A string containing the name of the color you wish to retrieve from the client. (This name must have been supplied in the client Java application using the JWaveView.setNamedColoror setNamedColorSetmethod.)
If set, GET_NAMED_COLOR returns an array of colors corresponding to a named color set. (In other words, use this keyword to retrieve colors that were packed by the client with the JWaveView.setNamedColorSet method.) You may have a color and a color set with the same name. DefaultRGB
Specifies a long integer (RGB value) representing the default color if the named color does not exist. (Default: '000000'xL (black))
Retrieves the a two-element array containing the range of colors that are available for use by images. The first element represents the first color in the range, and the second element represents the last color. This range is equivalent to the number of colors in the color table minus the number of named colors that have been retrieved. See the Discussion for information on how this keyword is used.
A color value that can be used by PV-WAVE.
For example, the following calls might appear in a Java client application. They associate names with color objects. These name/color object pairs are sent to the JWAVE wrapper function when the
execute method is called in the Java application.
myJWaveView.setNamedColor("BACKGROUND", java.awt.Color.lightGray)
myJWaveView.setNamedColor("COLOR", java.awt.Color.red)
back = GET_NAMED_COLOR("BACKGROUND", Default='000000'xL)
fore = GET_NAMED_COLOR("COLOR", Default = 'ffffff'xL)
back and fore can be used in any PV-WAVE expression that takes a color value. For example:
PLOT, x, Color=fore, Background=back
Managing the Color Table
Figure A-1 illustrates how a color table is created in a JWAVE wrapper. When LOAD_JWAVECT is called, a color table is created with the named colors loaded into a subset of the color table.
Figure A-1 A color is retrieved by GET_NAMED_COLOR in the JWAVE wrapper. When LOAD_JWAVECT is called, the named color is loaded into a subset of the specified color table. All remaining colors in the color table are available for use by images.
range=[5, 255].
Figure A-2 Named colors occupy a subset of the color table.
Example 1-1
; Get colors
JWAVE_LOADCT, 1
back = get_Named_Color("BACKGROUND", Default = '000000'xL)
fore = get_Named_Color("COLOR", Default = 'ffffff'xL)
bot = get_Named_Color("BOTTOM", Default = fore, $
Range_Of_Colors=crange)
; Re-map image values into the range of image colors.
s = BYTSCL(s, Top = crange(1)-crange(0)) + crange(0)
Notes and Restrictions
setNamedColorSet), then GET_NAMED_COLOR returns an array of color indices. This is useful for things such as the CONTOUR procedure's C_Color keyword.
TIP: To create a default color, supply a long integer containing red, green, and blue components of the desired color. For example, the color chartreuse is represented by red=127, green=255, and blue=0 (in hex, 7F, FF, and 00). To create this color, use '00ff7f'xL as a constant. In an equation, you can form this constant using PV-WAVE expressions such as:
red + 256L*(green + 256L*blue)
LONG(red) OR ISHFT(LONG(green), 8) OR ISHFT(LONG(blue), 16)
For more information on color tables and using color in PV-WAVE, refer to the PV-WAVE User's Guide.
(optional) The text to output to the log. By default, the name of the calling procedure and a time stamp are output if no text is supplied.
If nonzero, the log text is output to only the session log, and not the manager log. TimeStamp
If nonzero, a time stamp is prefixed to the text. The default is no time stamp if you supply text. The format of a timestamped log is:
The JWAVE Manager controls whether or not any logging occurs. If you not receiving a log file, you must configure the JWAVE Manager to produce a log file. See Using the JWAVE Configuration Tool for information on changing the log output.
UPDATE_LOG, /TimeStamp
WRAPPER_TEST_RETURN_INFO and WRAPPER_TEST_GETRETURN can be used to retrieve the results returned from the JWAVE wrapper.
If the JWAVE wrapper produces a plot, that plot is displayed in a PV-WAVE window.
A string containing the name of the return parameter that you wish to retrieve.
The value of the parameter.
WRAPPER_TEST_GETRETURN issues a warning message and returns 0 if the requested parameter does not exist.
This function imitates the behavior of the
JWaveExecute.getReturnData method in the Java client application.
A string containing the name of the wrapper function that you wish to test. width, height
(optional) Specifies the width and height of the graphics window, in pixels.
If width and height are not set, then WRAPPER_TEST_EXECUTE does not display a plot, even if the JWAVE wrapper returns a graphic. If width and height are set, a PV-WAVE window appears even if the JWAVE wrapper does not return any graphics.
testplot.pro. You can find this wrapper in:
VNI_DIR/jwave-3_0/lib/user
VNI_DIR\jwave-3_0\lib\user
VNI_DIR is the main Visual Numerics installation directory.
WAVEWRAPPER_TEST_INIT, 'TESTPLOT', 400, 300 WAVE
WAVE
simple.pro wrapper is used. This wrapper returns the square root of the input parameter. You can find this procedure in the same directory as testplot.pro, described previously. This wrapper only returns a numerical result and not graphics.
WAVE
This function imitates the behavior of the
Parameter.printInfo method in a Java client application.
A string specifying the name of the color to set. rgb
A long integer (RGB value) specifying the color value to set. For example, black is represented by the long value: '000000'xL.
If set, the procedure sets a named array of RGB values. In this case, the rgb parameter must specify an array of long integers.
This function imitates the behavior of the
JWaveView.setNamedColor method in a Java client application. The Color_Set keyword allows this procedure to imitate the behavior of the
JWaveView.setNamedColor method in a Java client application.
A string containing the name of the parameter to set.val
The value to be associated with the parameter.
This function imitates the behavior of the
JWaveExecute.setParam method in a Java client application.
