RP variables are variables that are created for use in Fluent and provide a means of passing data from your GUI (in Scheme) to your compiled or interpreted UDF (in C). RP variables can be accessed from both your GUI and your UDF. Therefore, to pass data from your GUI to your UDF, you simply create and assign values to RP variables in your GUI code, and then access these same variables in your UDF code.
To create a new RP variable in Scheme, you must use the macro
(rp-var-define). For example, the following command creates an
integer RP variable named user/myint with the default value of
1.
(rp-var-define 'user/myint 1 'integer #f)
Note: Symbols are usually used as arguments in Scheme functions rather than strings. To learn more about symbols, see Symbols.
Before you create an RP variable, it is good practice to check that an
RP variable by that name has not already been defined. One simple way to do this is to
create a function, called make-new-rpvar, which checks the presence
of a RP variable by that name before creating one. The
make-new-rpvar function is readily available in Fluent. It
expects three arguments: (1.) the name of the RP variable to create; (2.) the initial (and
default) value; and (3.) the type:
(make-new-rpvar 'user/myint 1 'integer)
Note: When you create a new RP variable, you should add a prefix to its name (for example,
user/) to ensure that the name will not conflict with a variable
that already exists in Fluent.
In order to change an RP variable from your Scheme GUI you must use the
(rpsetvar) macro. For example, if you want to change the
user/myint variable created in Creating an RP Variable to 3 instead of 1, you can use the following statement:
(rpsetvar 'user/myint 3)
Note: The new value that you assign to an existing RP variable must be of the type originally declared or else you will receive an error.
(rpsetvar) statements are often used
in the apply-cb function, which is called
when you click the button. In this way,
new values for RP variables are set when you click and the UDF can then access the new values when it needs to run.
It is often necessary to access RP variable values in your GUI as well as your UDF. This can
be useful in order to display the existing values of each variable each time the GUI is
opened. By doing this, you know the existing value of an RP variable each time you go to
change it. In order to access an RP variable in Scheme, you must use the
(%rpgetvar) macro. This macro is often used to set the value of a
local variable to the current value of an RP variable. For example, if you have an integer
entry box called localInt and an integer RP variable called
rpInt, you could set the value of
localInt to the value of rpInt by using
the following statement.
(cx-set-integer-entry localInt (%rpgetvar 'rpInt))
Since this statement is
meant to update the values in each field when you open your GUI, this type of statement is
usually seen in the update-cb function, which is called each time a
GUI dialog box or task page is opened.
In order to access the value of an RP variable for use in your UDF, see Accessing a Scheme Variable in a UDF.
Once new RP variables have been created their current values are stored in the case file each time the case file is saved. The order in which you load your case file and Scheme file does not matter when trying to load RP variable values from your case file. If the Scheme file is read before the case file, the RP variables will be created with the default values specified in the Scheme file. Then when the case file is read in, these values are overwritten with those in the case file. If the case file is read in before the Scheme file, the RP variables are created and set to the values specified in the case file. When the Scheme file is read in, it will ignore the RP variable create statements when it recognizes that these RP variables have already been created by the case file (see note below).
Note: In order to ensure that your Scheme file will recognize when RP variables have already been created by a case file, be sure to use the Scheme function defined in Creating an RP Variable when creating RP variables.