Configuring Batch Variables and
Expressions
Appendix A
Introduction
Expressions can be used in place of constant numeric or text values
in many configurable items encountered during batch configuration. These include, but are not limited to, the following items:
•
•
•
•
The compute batch manager action object.
The select unit batch manager action object.
The transition object.
Recipe parameter configuration.
Batch expressions use a C language-type syntax, incorporating
operators, parentheses, functions, values, variables and constants.
Batch Expression Structure
Operators are symbols used in expressions to represent arithmetic,
logical, or relational operations. An expression consists of operators
and operands, or values. The operand can be a constant or a computed value.
Numbers used as operands are assumed to be floating point values,
and can include digits, a decimal point, e or E (for exponentiation),
and a signed exponent in the following format:
<digits>.<digits>E<signed exponent>
A numeric value must include at least one digit or a decimal point (a
decimal point alone evaluates to 0). Use the unary negation operator
(-, described in Operators)
Operators immediately preceding the first digit to
express a negative number.
Variable names start with a letter, optionally followed by a string of
letters, numbers and underscores (_). Statements are terminated by
new lines (returns).
A backslash (\) is used to continue an expression on the next line.
WBPEEUI270012A0
A-1
Batch Expression Structure
Operators
Operators available for use in batch expressions are found in the
table below. Because expressions often include multiple operators
and operands, a set of rules exists to determine which operators get
performed first, which get performed second, third and so on. This
order is known as precedence. Some operators, such as multiply
and divide have equal precedence. If operators of equal precedence
are used in an expression, they are performed according to the order
in which they appear in the expression. Table A-1 lists operators in
order of decreasing precedence.
Precedence is an important concept to remember, as its effects on
the evaluation of an expression can be confusing to the novice. For
example, consider the following expression:
2+3*4
The resulting value of this expression is 14, not 20. Because the
multiplication operator has a higher precedence than the addition
operator, the multiplication portion of the expression (3 * 4) is performed first. If the expression were written:
(2 + 3) * 4
the value of the expression would be 20, because expressions contained within parentheses are evaluated first.
Table A-1. Batch Operators in Decreasing Precedence
Symbol
A-2
Operation
Description
^
Exponentiation
Corresponds to the FORTRAN operator "**", and is right associative.
!
Logical not
Evaluates the expression on the right and is true if that expression is false,
and vice versa.
-
Unary minus
Indicates or changes the algebraic sign of a value. This is a unary operator
which takes just one operand.
*
Multiplication
Multiplies the values on either side of it, yielding the product.
/
Division
Value to the left of the operator is divided by the value to the right.
+
Addition
Causes the two numeric operands on either side of it to be added together,
yielding the sum of the two values.
+
Concatenation
Produces one string by joining (or concatenating) two character strings (i.e.,
where the operands on either side of the concatenation operator are
strings).
-
Subtraction
Number after the subtraction operator is subtracted from the number before
the operator.
WBPEEUI270012A0
Batch Expression Structure
Table A-1. Batch Operators in Decreasing Precedence (continued)
Symbol
Operation
Description
>
Greater than
Evaluates two expressions and is true if the one on the left is greater than
the one on the right.
>=
Greater than or
equal to
Evaluates two expressions and is true if the one on the left is greater than or
equal to the one on the right.
<
Less than
Evaluates two expressions and is true if the one on the left is less than the
one on the right.
<=
Less than or
equal to
Evaluates two expressions, and is true if the one on the left is less than or
equal to the one on the right.
==
Equal
Evaluates two expressions, and is true if the one on the left is equal to the
one on the right.
!=
Not equal
Evaluates two expressions, and is true if they are not equal.
&&
Logical and
Evaluates two expressions, and is true if and only if both are true.
||
Logical or
Evaluates two expressions and is true if either one or both are true.
=
Assignment
Causes the value of the expression on the right to be assigned to the variable to the left of the assignment operator.
Punctuation
Table A-2 describes punctuation in batch expressions.
Table A-2. Punctuation in Batch Expressions
Operator
New line
Notes
Terminates an expression.
\
Line continuation character. Used when a single statement is divided into multiple lines.
,
Comma. Argument separator used in conjunction with built-in functions.
{}
Braces. Used to define a statement group.
()
Parentheses. Used to override precedence and control the order of evaluation.
IF/ELSE Syntax
IF and ELSE are keywords used in expressions. The syntax is:
if (expression) {statement 1}
if (expression) {statement 1} else {statement 2}
if (expression){statement1} \
else {statement2}
Parentheses and braces are a part of the syntax.
WBPEEUI270012A0
A-3
Batch Expression Structure
If the expression is true, statement 1 is executed. If the expression
is false, statement 2 is executed. The ELSE statement is optional
and therefore does not need to be included. If there is no ELSE
statement and the expression is false, program execution continues
at the statement after statement 1.
NOTE: Expressions must be properly parenthesized to ensure that pairs of conditions
are correctly evaluated. In the following example, a, b, and c are used to show valid
and invalid use of parentheses.
Invalid
if (a or b and c)
Valid
if (a or (b and c))
Valid
if ((a or b) and c) valid
Example
if (tstp == 0) {varputs("msg", "zero")} \
else {varputs("msg", "other")}
Constants
Several constants have been predefined for use in batch expressions. The constant names are reserved and cannot be used as variable names. These names and their values are listed in the Table
A-3.
Table A-3. Defined Constants
Constant
Value
PI
3.14159265358979323846
E
2.71828182845904523536
GAMMA
0.57721566490153286060
DEG
57.29577951308232087680 (degrees per radian)
PHI
1.61803398874989484820
Text Entry Format
Each text entry box in a batch management system configuration
window will accept one of the following types of entry:
•
•
•
An expression.
Dynamic text.
Static text.
The type of input expected by the text entry box corresponds with
the type of input a user would normally enter for that type of item.
A-4
WBPEEUI270012A0
Rules for Evaluating Expressions
For example, text entry boxes for parameters evaluate input as
expressions, while text entry boxes for block labels automatically
evaluate input as static text.
When the text entry box is expecting an expression (e.g., a parameter value assignment), anything entered will be evaluated as an
expression unless it is enclosed within double quotes (" "), in which
case it will be treated as text. (It is not necessary to enclose numeric
constants within double quotes.) This is the most common type of
text entry box, used for the entry of parameters in the recipe database.
A number of configuration items (e.g., batch report text sections,
SOP, attach notes and many of the message BMA configuration
items) expect input in the form of dynamic text. Dynamic text is processed as text except where it is enclosed within backquotes (` `), in
which case the portion within the backquotes will be treated as an
expression. Most of the items which can be configured for the message batch manager action treat input as dynamic text.
In all other cases, static text is expected. Static text is always processed as text. If present, backquotes are ignored and double quotes
are discarded. Labels for RPD blocks (phases, procedures, batch
manager actions) are good examples of static text.
Rules for Evaluating Expressions
The rules presented in this section are used when an expression is
evaluated. A list of the rules is presented in text format. This list is
followed by a table containing examples of expressions and results
which correspond to the rules in the list. These items are followed
by several examples of greater complexity. For most recipes, this
level of complexity would not be required.
WBPEEUI270012A0
Rule 1.
A constant equates to its numeric value.
Rule 2.
Recipe parameters are filled in (replaced) with their current value.
Rule 3.
Built-in functions are executed and the return value is then used in
the expression. The return value type (numeric or string) is dependent upon which function is being executed.
Rule 4.
When evaluating expressions, precedence determines the order of
operations. Parentheses are used to override precedence order.
Refer to Operators in this section.
A-5
Rules for Evaluating Expressions
Rule 5.
Data enclosed within double quotes (" ") is treated as a text string.
Rule 6.
In the cases where a built-in function requires the name of a control
system tag.atom, a tag key name, or a recipe variable (global, batch,
and local), the input must be an expression which evaluates to the
desired name.
Rule 7.
The expression must evaluate to the correct data type (float or
string) for the value which is being assigned. Refer to Table A-4.
Table A-4. Data Types
Parameter
Expression
Float
Float
String
String
List
String
Unit List
String
Recipe variables are defined to be either floats or strings according
to their initial configuration (batch recipe variable editor) or assignment (varput functions).
Rule 8.
Private functions may be defined to simplify the entry of complex
expressions containing if/else clauses. These functions are only
known to the single recipe block which contains them.
Rule 9.
Expressions are valid when entering recipe parameter values under
the batch scheduler.
Rule 10.
Expressions are not used in equipment database configuration.
Errors will be reported for these conditions:
•
Part of the expression cannot be evaluated (e.g., nonquoted data
is not recognized as an operator, a constant, a function name,
punctuation, keyword, or a recipe parameter name).
•
The expression does not evaluate to the correct data type for the
value which is being assigned.
NOTES:
1. The rules listed above apply to the evaluation of expressions. In cases where a
text entry window is expecting to receive dynamic text, data which is to be interpreted
as an expression should be enclosed within backquotes (` `). Dynamic text is discussed in Text Entry Format of this appendix.
A-6
WBPEEUI270012A0
Rules for Evaluating Expressions
2. Batch expression structure, punctuation, syntax, and operators are described in
Batch Expression Structure. Built-in functions are described in Built-In Functions.
Table A-5. Examples of Rules for Evaluating Expressions
Rule
Expression
Result
1
2.5
2.5
2
total * amount1 * 0.01
The percentage of amount1 is computed by multiplying the value of total by the value of amount1 by 0.01
3
sqrt(16)
4
4
2+3*4
14
5
"abc" + "def"
Text string abcdef
6
bdbput("TotalVol",vol1 + vol2 + vol3)
The values of vol1, vol2, and vol3 are added and the
result is saved as tag key data under the TotalVol
7
"FT1"
100
Unit list assignment
Float assignment
8
func SetUnits() {
Define the function SetUnits
if (selgrinder == "G1") {
varputs("MeatUnit","I1")
varputs("VegeUnit","I3")
varputs("SpiceUnit","I5")
varputs("WaterUnit","W1")
}
if (selgrinder == "G2") {
varputs("MeatUnit","I2")
varputs("VegeUnit","I4")
varputs("SpiceUnit","I6")
varputs("WaterUnit","W2")
}
8
(continued)
return 0
}
Define the function SetUnits
SetUnits()
9
ran()
A random number is assigned to the recipe parameter which is being entered.
The following examples are for illustrative purposes only. For most
recipes, this level of complexity would not be required.
Example 1:
WBPEEUI270012A0
This example (entered within a recipe compute block) defines a
function named update which updates the volume associated with
A-7
Rules for Evaluating Expressions
the global recipe variables HT1_Vol, HT2_Vol, HT3_Vol, and
HT4_Vol.
func update() {
tank = vargets("seltank")
soup = _SoupName
if (tank == "HT1") {
gvarputs ("HT1_Soup", soup)
oldvol = gvarget ("HT1_Vol")
gvarput ("HT1_Vol", (oldvol + num (_SoupAmt)))
}
if (tank == "HT2") {
gvarputs ("HT2_Soup", soup)
oldvol = gvarget ("HT2_Vol")
gvarput ("HT2_Vol", (oldvol + num (_SoupAmt)))
}
if (tank == "HT3") {
gvarputs ("HT3_Soup", soup)
oldvol = gvarget ("HT3_Vol")
gvarput ("HT3_Vol", (oldvol + num (_SoupAmt)))
}
if (tank == "HT4") {
gvarputs ("HT4_Soup", soup)
oldvol = gvarget ("HT4_Vol")
gvarput ("HT4_Vol", (oldvol + num (_SoupAmt)))
}
return 1
}
update()
Example 2:
This example uses the values for the recipe parameters MeatPct,
VegePct, SpicesPct, and WaterPct to compose the soup name.
bvarputs("SoupNamePart1", str(MeatPct) + " % " + Meat + " ")
bvarputs("SoupNamePart2", str(VegePct) + " % " + Vegetables + " ")
bvarputs("SoupNamePart3", str(SpicesPct) + " % Spices ")
bvarputs("SoupNamePart4", str(WaterPct) + " % Water")
bvarputs("SoupNameFull", bvargets("SoupNamePart1") \
+ bvargets("SoupNamePart2") + bvargets("SoupNamePart3") \
+ bvargets("SoupNamePart4"))
A-8
WBPEEUI270012A0
Built-In Functions
Built-In Functions
Batch
Batch functions are used to get data from and put data into variables (Table A-6). The scope of the function used determines
whether this action occurs locally (within one instance of one recipe
procedure diagram), within a single batch (which may consist of
multiple RPDs), or globally (in any RPD in any batch).
It is not necessary to declare these variables. Simply using an
expression putting the variable creates it. The value is put into a
storage space on Produce IT Batch from which it can be retrieved
using the get function. The value put may be a constant or an
expression.
Table A-6. Batch Functions
Name
Syntax
Description
get unit attribute
Scope
attget
attget(unit name, attribute_name)
attgets
attgets(unit name, attribute_name) get unit attribute string
Any RPD in any batch
Any RPD in any batch
bvarget
bvarget(variable_name)
get value of batch variable
Any RPD in one batch
bvargets
bvargets(variable_name)
get value of string batch variable
Any RPD in one batch
bvarput
bvarput(variable_name, value)
put value of batch variable
Any RPD in one batch
bvarputs
bvarputs(variable_name, value)
put value of string batch variable
Any RPD in one batch
evals
evals(“ `expr`”)
evaluate string with embedded
expressions
Ex. recipe
ex_abort
ex_abort()
issue ABORT command
Ex. recipe
ex_hold
ex_hold()
issue HOLD command
Ex. recipe
ex_isfinal
ex_isfinal()
check if all blocks are in final state
Ex. recipe
ex_isheld
ex_isheld()
check if all blocks are in HELD state
Ex. recipe
ex_ispaused ex_ispaused()
check if all blocks are in PAUSED
state
Ex. recipe
ex_pause
ex_pause()
issue PAUSE command
Ex. recipe
ex_restart
ex_restart()
issue RESTART command
Ex. recipe
ex_resume
ex_resume()
issue RESUME command
Ex. recipe
ex_stop
ex_stop()
issue STOP command
Ex. recipe
exkill
exkill()
terminate thread(s) parallel to this
exception recipe
Ex. recipe
exrestart
exrestart()
restart exception section
Ex. recipe
getbid
getbid( )
get batch id
Any RPD in one batch
WBPEEUI270012A0
A-9
Built-In Functions
Table A-6. Batch Functions
Name
getopid
(continued)
Syntax
Description
getopid()
returns ID of the current compute or
transition block
Scope
Block
gvardel
gvardel(var_name)
delete global varable
Any batch
gvarget
gvarget(variable_name)
get value of global variable
Any RPD in any batch
gvargets
gvargets(variable_name)
get value of string global variable
Any RPD in any batch
gvarput
gvarput(variable_name, value)
put value of global variable
Any RPD in any batch
gvarputs
gvarputs(variable_name, value)
put value of string global variable
Any RPD in any batch
is_int
is_int(string[,low[,high]])
check if string represents integer
number
-
is_num
is_num(string[string[,low[,high]])
check if string represents number
-
rcpexec
rcpexec(rcp_name,[recipe_
parameter_name,
recipe_parameter_value, ...])
execute a recipe
Acts on one RPD, which
can be configured to call
other RPDs
varget
varget(variable_name)
get value of numeric local variable
One RPD
vargets
vargets(variable_name)
get value of string local variable
One RPD
varput
varput(variable_name, value)
put value of numeric local variable
One RPD
varputs
varputs(variable_name, value)
put value of string local variable
One RPD
NOTE: Because unit attributes cannot be changed from a recipe, the attget function
has no corresponding put function.
DBA
The DBA functions which are built into the batch management system provide access to the control system global database. DBA
functions which can be used in batch expressions are described in
Table A-7.
Table A-7. DBA Functions in Batch Expressions
Function
Syntax
Description
bdbget
bdbget(tagkeyname)
get Tag Key Collected data
bdbgets
bdbgets(tagkeyname)
get Tag Key Collected string data
bdbput
bdbput(tagkeyname, expr)
put Tag Key Collected data
get
get(tagname.atom)
get current global data
put
put(tagname.atom, value)
put current global data
The expression (expr) which is part of the syntax for the bdbput
function can be a parameter name.
A - 10
WBPEEUI270012A0
Built-In Functions
For example:
bdbput("FeedTank",UnitFT)
where UnitFT is a parameter which represents a value in the equipment or recipe database. "FeedTank_1" is enclosed within double
quotation marks, so that it will be treated as text, as described in
Text Entry Format in this section.
Information regarding assignment of DBA functions is saved on a
per-batch basis.
General
In addition to the specialized functions discussed, a number of
functions which accomplish more general activities are also provided. These general functions are listed in Table A-8.
Table A-8. General Functions
Name
Description
Syntax
Trigonometric Functions
acos
acos(expr)
Arc cosine
asin
asin(expr)
Arc sine
atan
atan(expr)
Arc tangent
cos
cos(expr)
Cosine
cosh
cosh(expr)
Hyperbolic cosine
sin
sin(expr)
Sine
sinh
sinh(expr)
Hyperbolic sine
tan
tan(expr)
Tangent
tanh
tanh(expr)
Hyperbolic tangent
Math Functions
abs
abs(expr)
Absolute value
ceil
ceil(expr)
Round up
cond1
cond(expr, true_return, false Conditional test (true_return is the value to return if true,
return)
false_return is the value to return if false)
exp
exp(expr)
Exponent
floor
floor(expr)
Round down
int
int(expr)
Integer
log
log(expr)
Log
log10
log10(expr)
Log base 10
WBPEEUI270012A0
A - 11
Produce IT Batch Function Wizard
Table A-8. General Functions (continued)
Name
Description
Syntax
ran
ran()
Random number generator
sqrt
sqrt(expr)
Square root
String Functions
fgets
fgets(fnum)
Get string from a stream
fputs
fputs(str,fnum)
Put string on a stream
num
num(str)
Convert string to numeric value
parse
parse(str, separator, n)
Return nth token of str
str
str(nbr)
Convert number to string
strex
strex(str,p1,len)
Return substring of str starting at p1 for len characters
strlen
strlen(str)
Return length of string
File Functions
fclose
fclose(fnum)
File close
fopen
fopen(fname, type)
File open
getpid
getpid( )
Get process id
unlink
unlink(fname)
File delete
Time Functions
str2time
str2time("string_time")
Converts string_time expressed as HH:MM:SS DD-MMM-YY
to integer representing number of seconds since 1 January
1970
time
time()
Get current time expressed as integer representing number of
seconds since 1 January 1970
time2str
time2str(integer)
Converts integer representing number of seconds since 1 January 1970 to string time as HH:MM:SS DD-MMM-YY
times
times()
Get current time as string in the form HH:MM:SS
DD-MMM-YY
NOTE:
1. The cond command performs both the true_return and the false_return arguments before a decision is made. Therefore, it is recommended that cond not be used with write operations. Use the IF keyword instead of the cond command for write operations. Refer to IF/
ELSE Syntax of this appendix for information about use of IF.
Produce IT Batch Function Wizard
A function wizard is a tool which provides easy access to functions
and the syntax required for their use. By default, the Produce IT
Batch function wizard includes the set of standard Produce IT
Batch functions provided with the Produce IT Batch software and
documented in the preceding portions of this appendix.
A - 12
WBPEEUI270012A0
Produce IT Batch Function Wizard
In addition to the standard functions provided as a part of the Produce IT Batch software, the user can create custom functions. Configuration of custom functions is described later in this appendix.
Standard and custom functions are used in batch expressions during recipe configuration. Recipe configuration is discussed in Recipes in Section 4. All functions, both standard and user-created, can
also be accessed for use when editing a control recipe at run-time.
Run-time editing of control recipes is described in the Produce IT
Batch Operation instruction.
The Produce IT Batch function wizard is accessed by clicking FW
(Fig. A-1).
TC02199A
Figure A-1. Function Wizard Button
This button appears on recipe configuration windows where batch
expressions can be configured. Many such windows are used during
configuration of batch manager action blocks, including the compute, acquire, select unit, sequence start, release unit, reserve unit,
unreserve unit, set sop section, command and print report BMAs.
For example, when configuring a compute BMA, the following
sequence of selections provides access to the function wizard:
To Access FW Window
Recipe > Assign Object > Action Type > Compute >
Expression Editor > Add > Text Editor > Fw Button
The function wizard selection window (Fig. A-2) will be displayed.
The main portion of this window is occupied by a pair of list boxes
labelled function category and function name. The item selected in
the function category list box determines the contents of the function name list box.
Click a specific function in the Function Name box, and the Prototype and Description boxes are filled automatically. The Prototype
text box displays the syntax for using the selected function. The
Description entry contains text which describes what the function
does. These two items are for display only, and cannot be altered by
the user from this window. If the entry for either the description or
prototype is larger than can be displayed in the text box, click the
expand entry button (...). This causes a text editor window to be displayed, which contains the complete entry for the selected item.
WBPEEUI270012A0
A - 13
Produce IT Batch Function Wizard
TC02200B
Figure A-2. Function Wizard Selection Window
To view the long description for the function, and a description of
each parameter used in the function, click Detail. The function
detail window (Fig. A-3) will be displayed.
TC02201A
Figure A-3. Function Detail Window
The function detail window provides the ability to configure the
parameter values to be used in the function. Functions can be used
recursively. For example, one function can call another function,
even itself.
A - 14
WBPEEUI270012A0
Produce IT Batch Function Wizard
The following function returns the square root of a square root:
func root_of_root() {
a = sqrt(sqrt(#par1#)
return(a)
}
#par1# is a place holder for a parameter value that still needs to be
configured. This can be done manually in the function body, or it
can be done by entering additional functions. FW buttons are available for use in configuring each parameter in the function detail
window. These permit the use of the Produce IT Batch function wizard to be used to configure functions as parameter values of a parent function. As the function wizard is invoked recursively, the
window title bars are annotated to include the level number. (An
example is shown in Fig. A-4.) This assists in keeping track of how
many levels deep the recursion has progressed. Once configured,
any and all recursive function calls within the parameter will be displayed at the topmost level in the body of the function.
TC02202B
Figure A-4. Function Detail Window, Level 2
If the function being viewed in the function detail window is a custom user configured function, Body is included in the window. This
WBPEEUI270012A0
A - 15
Custom Functions with the Function Wizard
button provides a convenient way to view the text or body of the
function, as it was configured.
Custom Functions with the Function Wizard
A function wizard is a tool which provides a convenient way to
access standard and custom functions for use in batch expressions,
and the syntax required for their use. A set of standard Produce IT
Batch functions is provided with the Produce IT Batch software.
These standard functions are documented in Built-In Functions in
this section. In addition to the standard functions, custom functions
can be created.
Furthermore, the Produce IT Batch function wizard lets you test a
function before it is ever used in the execution of an actual batch.
To Access FW
Configuration Window
To configure custom functions, access the function wizard configuration window by selecting Tools > Batch Utilities > Function Wizard.
The function wizard configuration window (Fig. A-5) will be displayed.
TC02237B
Figure A-5. Function Wizard Configuration Window
The function wizard configuration window contains two list boxes
labelled Function Category and Function Name. Below the Function
Name list box are Edit, Add, Delete and Copy.
The Function Category is a list of all the categories of custom functions that have been created for the selected equipment database.
By default, it also contains the entry All. When All is selected, all
A - 16
WBPEEUI270012A0
Custom Functions with the Function Wizard
custom functions in all user-created categories will be included in
the Function Name list box. The selection made in the Function Category list box determines the contents of the Function Name list box.
Add
To create a new custom function using the function wizard, click
Add on the function wizard configuration window. The function definition window (Fig. A-6) will be displayed.
Enter the name to be used for the new function in the Name entry
box. The name can have a maximum of 20 characters.
The function must be a member of a function category. To create a
new category, enter the new category name in the Category box. To
add the function to an existing custom category, click the down
arrow and select a category from the list. The standard Produce IT
Batch function categories are not available from the Category box.
Custom functions cannot be added to the standard function categories.
Two text entry boxes are provided to enter Short and Long descriptions of the custom function. The descriptions are free format;
expand entry buttons (...) associated with each of these text entry
boxes provides access to a text editor window which permits text
entry in the width and length desired by the user. The Short description is used in the function wizard selection window. The Long
description is used in the function detail window. The same text can
be entered for both descriptions, which is the case for the standard
Produce IT Batch functions. The short and long descriptions are
optional.
The function itself is configured in the text entry portion of the window labelled Body. It can be typed directly into this portion of the
display. For larger functions, click the expand entry button (...) to
the right of the Body portion of the display. The function can then
be edited in the resulting text editor window shown in Figure A-6.
The fw button located on this window can be used to include other
functions within the function being configured.
To place a simple function in the Body text box, click Insert Stub.
The simplest possible function, shown here, will be placed in the
Body text box:
WBPEEUI270012A0
A - 17
Custom Functions with the Function Wizard
TC02336A
Figure A-6. Function Definition Window
func <function name>() {
return(0)
}
This skeleton of a function can then be expanded into a more complex function. If a function has already been configured in the Body
box, clicking Insert Stub will cause a confirmation box to ask:
Override current function body?
A - 18
WBPEEUI270012A0
Custom Functions with the Function Wizard
Click Yes to overwrite the currently configured function with the
simple skeleton function, or click No to exit the operation and leave
the existing function intact.
Parameters to be used in the function are defined by entering a
Parameter Name and Description in the appropriate text entry box
below the Parameters list. Once this information is entered, click
Apply and the new parameter will be added to the list. Click Clear to
remove the contents of the Name and Description text boxes. To
delete a parameter, click the item in the Parameters list, then click
Delete. The entry for the selected parameter will be removed from
the Parameters list.
When a parameter is added to the Parameters list box, a symbolic
name for the parameter will be created automatically and is the first
item in the entry for that parameter. This symbolic name consists of
a dollar sign followed by a number. The number reflects the parameter's position in the order of items in the Parameters list box. For
example, the first parameter would be $1, the second would be $2,
and so on. If a parameter is deleted, this number will change to
reflect the new order. That is, if the parameter represented by $1 is
deleted, the second parameter will then move up and it will then be
represented by $1.
NOTE: Use these symbolic names in the body of the function, rather than the parameter names.
Assume a function named newfunc is created, and four parameters
have been defined for this function: param1, param2, and param3
which are automatically given the symbolic names $1, $2, and $3.
An expression to add these parameters and return the sum would
be written:
func newfunc() {
a = $1 + $2 + $3
return(a)
}
Using Functions within Functions
A function can be configured using other functions, both the standard Produce IT Batch functions and user-configured custom functions. To include another function, click the expand entry (...)
button associated with the Body text box on the function definition
window. A text editor window containing the existing function and
an FW button (Fig. A-7) will be displayed.
WBPEEUI270012A0
A - 19
Custom Functions with the Function Wizard
TC02239A
Figure A-7. Text Editor Window with Function Wizard Button
In the text editor window, position the cursor at the location where
the new function is to be inserted, then click the fw button. The
function selection window will be displayed. This is the same window which is used in recipe configuration when configuring
expressions.
TC02240B
Figure A-8. Function Selection Window
Select the desired category and function. The syntax for the function will be displayed in the Prototype text box, and the Short
description (if configured) for that function appears in the
A - 20
WBPEEUI270012A0
Custom Functions with the Function Wizard
Description text box. If Detail is clicked, the function detail window
(Fig. A-9) is displayed.
TC02339A
Figure A-9. Function Detail Window
This window contains the name, syntax, long and short descriptions
for the selected function. It also contains a text box for configuring
parameter values for the selected function. These parameter values
can be calls to other functions. For example:
varput("myvar", varget("othervar"))
where the value for the variable myvar is a call to the varget function.
An fw button provides access to the available functions. Click it to
display a new copy of the function wizard selection window. The
level of the window is included in the title bar. Again, parameters,
variables and values can be replaced with other expressions, and
clicking the Detail button causes a new copy of the function detail
window (Level n) to be displayed. This recursive calling of functions
can continue to the depth desired by the user. The level of each successive window is indicated in the window's title bar, as illustrated
in Figure A-10. The entire set of nested functions will be included in
the body of the top level function. This means that the entire set of
WBPEEUI270012A0
A - 21
Custom Functions with the Function Wizard
nested functions is immediately visible to the user and accessible
for editing at the top level.
NOTE: When configuring a function, if no parameter value is supplied for a given
parameter, then the string #par<n># will be supplied as the parameter value, where n
is the number of the parameter. This string can later be manually edited in the body of
the function.
TC02242B
Figure A-10. Function Detail Window, Level 2
Test a Custom Function
Once the body of a function has been written, it can be tested before
it is used during the execution of an actual batch. The testing facilities built into the function wizard aid in the location and resolution
of logic and syntax errors. Values can be specified for each parameter defined in the function. These values will be supplied for use by
the parameters when the test is run. Batch variables of different
types can also be defined. During testing, these variables simulate
the variables that would exist during execution of a recipe. After the
test has completed, a window reports on the results, including
information on what has been set as a result of running the test.
A - 22
WBPEEUI270012A0
Custom Functions with the Function Wizard
For example, the function configured in Figure A-11 is designed to
create a name for a soup, based on the ingredients. It includes the
parameters named percent1 and percent2, and a variable named
ingred1.
TC02243A
Figure A-11. Sample Function with Parameters and Variable
To test the newly configured function, click Test Function in the
function definition window. The test function window will be displayed. Figure A-12 contains an example of the test function window
in which Test Parameter Values have been entered and a test variable has been configured. These values will be supplied to the
parameters when the test is run.
TC02244A
Figure A-12. Test Function Window
To create a test variable and assign a value to it, click Add. To edit
an existing test variable, select it and then click Edit. In either case,
the add/edit test variable window will be displayed. Figure A-13
WBPEEUI270012A0
A - 23
Custom Functions with the Function Wizard
illustrates the add/edit test variable window being used to assign
the string type value, “Tomato”, to the variable ingred1. There is no
need to enter the quotation marks around the string; they are added
automatically.
TC02245A
Figure A-13. Add/Edit Test Variable Window
Enter the variable name in the Name box as it appears in the function body. Click one of the Type buttons to specify the type of the
variable.
Variable types include:
•
•
•
•
Global - used in any RPD in any batch.
Batch - used in any RPD in a single batch.
Local - used within one instance of one RPD.
DBA - used with DBA functions in batch expressions.
Refer to Built-In Functions in this section for information on these
types of batch variables and their use in batch expressions.
Click the appropriate button to specify the Value Type; i.e., whether
the variable will contain a Number (the default) or a character String.
Finally, enter the Value to be used in the variable. Click OK to complete the variable definition operation (or click Cancel to exit and
discard the variable). The add/edit test variable window will close.
Focus will return to the test function window; the Test Variables list
will be updated to display the Type, Name and Value of the new variable. To modify a test variable, click the desired item in the list, then
click Edit. To delete a test variable, select the item, then click Delete.
Once all configuration of test variables has been completed, click
Run Test in the test function window. The test results window (Fig.
A-14) will be displayed. This window provides the value returned for
the function, as well as information on the variables that were
A - 24
WBPEEUI270012A0
Custom Functions with the Function Wizard
modified as a result of running the test. Errors encountered during
execution of the test will also be reported in the test results window.
TC02246A
Figure A-14. Test Results Window
Edit
Custom functions which have already been configured can be modified. In the Function Name list box of the function wizard configuration window (Fig. A-5), click the item to be changed, then click Edit.
The function definition window will be displayed. Modify as
described in Add in this section.
Delete
Custom functions can be deleted. In the Function Name list box of
the function wizard configuration window (Fig. A-5), select the item
to be deleted, then click Delete. A confirmation box will be displayed,
which asks:
Delete selected item(s)?
Click Yes to delete the function, or click No to exit the operation
without deleting anything.
Copy
Once a custom function has been created, you can save time when
creating similar functions by copying the existing function and
making alterations to the copy. To copy a custom function, open the
function wizard configuration window (Fig. A-5). In the Function
WBPEEUI270012A0
A - 25
Custom Functions with the Function Wizard
Name list box, click the item to be changed, then click Copy. The
function definition window will be displayed. The configuration of all
of the parameters in the window will be identical to that found in
the entry for the original function, but the Name text entry box will
be empty. Enter the name to be used for the new copy of the function. Changes to the function configuration can be performed and
tested as described in Test a Custom Function above.
Be sure to modify the first line of the function body so that the name
used in the function matches the new name entered in the Name
text entry box. For example, if the original function was named
FUN1, and the first line of the function body was:
func fun1() {
then when a copy named FUN2 is made, the first line of the function
body must be manually modified to read:
func fun2() {
If this is not changed, an error message will be displayed when the
Run Test button is used.
A - 26
WBPEEUI270012A0