XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX''"> Syntax of Keywords
• Any line beginning with a # character is treated as a comment line.
• An asterisk (*) character as the first non-blank character in a line flags the start of a keyword.
• Values assigned to a keyword follow an equals sign (=).
• All function definitions need to include *INPUTID, *CLASS, *FUNCTION, and the appropriate number of widgets or hard-wired parameters which correspond to the PCL call arguments.
********************************************************************
The keyword *INPUTID is used to specify the function call index (cyl_coords_method1), 32-characters maximum.
*INPUTID = cyl_coords_method1
ASCII non-blank characters are required for the value listed under *INPUTID. 'null' will be the 4-character index name reserved for the case of no function call and a disabled "Apply Inputs" action button.
********************************************************************
The keywords *CLASS and *FUNCTION are used to specify the PCL function class and function name to call.
*CLASS = AANAV
*FUNCTION = make_cyl_coords
The PCL class name can be left blank indicating a global class function. A function name of 'null' means to disable the "Apply Inputs" action button and display no widgets in the "Inputs Box".
********************************************************************
The keyword *STATUSCHECK is an error status checking flag. When this keyword is listed, the integer return value is received into a global variable, and a status check is made with it.
*STATUSCHECK [=0]
The integer value flags a normal successful exit by this particular PCL function. A value of zero (0) is the most common. If the integer value associated with normal exit is not listed on the *STATUSCHECK line, then a value of zero is assumed.
This is an ***optional keyword***.
If *STATUSCHECK IS NOT used when the function is called:
• next dialog is quedlg no matter what (see <dialog> tag attributes)
• queftn (if listed) is invoked no matter what
If *STATUSCHECK IS used when the function is called (Encouraged!!!):
• next dialog is quedlg for success, errdlg or <returnerror> for failure
• queftn (if listed) is invoked for success, not for failure
********************************************************************
The keyword *DYNAMIC calls the referenced function to return a default value to be displayed in the widget. All widget types are supported by this keyword. This feature allows the dynamic computation of default widget values.
The author must write the *DYNAMIC referenced function to give the default values in a single string array, with each element of the array corresponding to a different displayed widget or HPARAM (hard wired parameter), which in turn corresponds to a different call sequence argument of the *INPUTID referenced PCL function. The STRING array elements are in the order of the call sequence arguments for the particular *INPUTID referenced function. For the listbox widget, the multiple values for default will be a single string where the individual values are comma separated. e.g. "load case1,load case2,load case3". A blank entry in the array will indicate that the default value given in the *.def file for that widget should be used.
For databox widgets with dynamic assignments, the following rules apply:
When a dynamic assignment is being used with a REAL or INTEGER databox, the value given to the number of values (NumVals) in the .def file has a special meaning.
- If NumVals is defined as 0 in the .def file, any number of values can be dynamically assigned, and the corresponding function is called with an array containing the values.
- If NumVals is set to 1 in the .def file, a single non-array value of INTEGER or REAL can be dynamically assigned.
- If NumVals is set to a value >1 in the .def file, the platform software will check the number of inputs received from the databox to make sure it matches the value set in NumVals.
For listbox or option menu widgets with dynamic assignments, the following rules apply:
When dynamically assigning values, the original displayed selectable label definitions are overwritten and the item values and labels become the same thing.
*DYNAMIC example with a single widget:
This is how the function definition in the .def file is referenced by the .xml file:
<dialog dlgid=”dlbtest”
inputid=”dyn_test_single”
quedlg=.#1.#dlbtest1”
...
</dialog>
This is how the 4 original listbox items are defined in the .def file:
*INPUTID = dyn_test_single
*CLASS = AANAV
*FUNCTION = dyn_test_single
*LBOX = Available Options,EXTEND,4
*LBOXITEMS = 4,YES,NO,MAYBE,NEVER
*LBOXLABS = YES,NO,MAYBE,NEVER
*DYNAMIC = AANAV.new_list_single
*STATUSCHECK
*LOAD ITEM
This is how the 4new listbox items are defined in the .pcl file:
FUNCTION new_list_single(new_string)
STRING new_string[]()
/* Allocate a string array for a single string entry which will contain the 5 new values for the listbox widget which are defined below */
sys_allocate_string(new_string,50)
sys_allocate_array(new_string,1,1)
/* These are the 4 new values that will appear in the listbox widget. */
new_string(1) = “test1,test2,test3,test4”
END FUNCTION
This is the .pcl file which receives the item selected from the listbox:
FUNCTION dyn_test_single(value)
/* Although value is a STRING ARRAY, it will be receiving only one value from the listbox */
STRING value[]()
...
END FUNCTION
*DYNAMIC example with multiple widgets:
This is how the function definition in the .def file is referenced by the .xml file:
<dialog dlgid=”dlbtest1”
inputid=”dyn_test_multiple”
quedlg=.#1.#st1ck1”
...
</dialog>
This is how the original widget values are defined in the .def file:
*INPUTID = dyn_test_multiple
*CLASS = AANAV
*FUNCTION = dyn_test_multiple
*TOG = Toggle, TRUE
*LBOX = Listbox Picks,EXTEND,5
*LBOXITEMS = 5,YES,NO,MAYBE,NEVER,SOMETIMES
*LBOXLABS = YES,NO,MAYBE,NEVER,SOMETIMES
*DBOX = REAL,Type: Real Value,3,1.,2.,3.
*OPT = Option Menu Picks,EXTEND,1
*OPTITEMS = 4,YES,NO,MAYBE,NEVER
*OPTLABS = YES,NO,MAYBE,NEVER
*HPARAM = REAL,7.
*DYNAMIC = AANAV.new_list_multiple
*STATUSCHECK
*LOAD ITEM
This is how the new widget values are defined in the .pcl file:
FUNCTION new_list_multiple(new_string)
STRING new_string[]()
/* Allocate a string array for the 5 string entries which will contain the new
values for the widgets */
sys_allocate_string(new_string,50)
sys_allocate_array(new_string,1,5)
/* These are the new values that will appear in the widgets */
new_string(1) = “FALSE”
new_string(2) = “list1,list2,list3,list4,list5”
new_string(3) = “100.,200.,300.”
new_string(4) = “opt1,opt2,opt3,opt4”
new_string(5) = “700.”
END FUNCTION
This is the .pcl file which receives the values from the multiple widgets:
FUNCTION dyn_test_multiple(toggle,listbox,databox,option,hparam)
INTEGER null_flag
STRING value[]()
STRING page[VIRTUAL]
STRING stepid[4]
STRING dyn_test_multiple_value[VIRTUAL]
LOGICAL toggle
STRING listbox[]()
REAL databox()
STRING option[]()
REAL hparam
...
END FUNCTION
********************************************************************
The keyword *LOADITEM is used to specify the end of a PCL function call definition under a specific *INPUTID listing.
Syntax for the Different Widget Types
Every call sequence argument in a PCL function must have a corresponding widget or hard-wired parameter. The widget types are explained below:
Data Box Widget
*DBOX = TypeOfInput, DboxLabel, NumVals, InitVal1, InitVal2, InitVal3,
...
Note that the type of input (datatype) can be: STRING, INTEGER, REAL. A STRING data type results in a single VIRTUAL STRING function call argument. Multiple REAL or INTEGER initial values (NumVals values) can be listed. If no intial value is listed, then the resulting data box will display as initially empty. Data is extracted from widgets as a VIRTUAL STRING. PCL list processor routines are used to evaluate the extracted data. The DboxLabel label value ONLY may be in multi-byte foreign language characters. The label is displayed above the databox. NumVals is the upper limit of the number of INTEGER or REAL values. For NumVals=1, a scalar REAL or INTEGER parameter is given to the function call. For NumVals > 1, a REAL or INTEGER ARRAY argument is given. List a value of 1 for NumVals for the case of a STRING data type. If a dynamic assignment (*DYNAMIC) is used with a REAL or INTEGER data type, special rules apply (please see the description for *DYNAMIC above).
Select Data Box Widget
*SDBOX = TypeofSelect, Label, InitValue
TypeofSelect may be: ANY, POINT, CURVE, SURFACE,....etc. InitValue is a STRING which may contain blanks, e.g. Curve 6. If no initial value is listed, the box will have no initial value. The label ONLY may be multi-byte font (displayed above the databox).
Toggle Widget
*TOG = Label, InitialValue
The data type for the initial value and the value read from the widget is LOGICAL. List InitialValue as TRUE or FALSE. The label ONLY can be multi-byte characters.
File Selection Widget
*FILE = Filtermask,Filterlabel,Dirlabel,Fileslabel,Filenamelabel,
Filterbuttonlabel
Filtermask is a STRING argument controlling file selection, e.g. '*.db'. The 5 labels for widget display may use multi-byte font. Note that the default directory that this widget points to for files is the user directory window that the user is running the MSC Patran application from.
Slide Bar Widget
*SBAR = Label, Minval, Maxval, Initval, DecPnts
Label may be multi-byte characters. Initval=initial numeric value. DecPnts=number of display digits beyond decimal. Minval and Maxval are the limit values for the slide bar.
List Box Widget
*LBOX = Label, SelectType, NumRows
*LBOXITEMS = NumItems, name1,name2,name3, ... , namen
*LBOXLABS = lab1, lab2, lab3, ... , labn
Three successive key word entries: LBOX, LBOXITEMS, LBOXLABS are required to specify a listbox widget display. The listbox is used to obtain a STRING array output of the selected list items. Label can be multi-byte characters. NumRows is the number of visible rows to display. SelectType can be BROWSE, EXTEND, MULTIPLE, or SINGLE. NumItems is the number of displayed items to select from. The actual STRING item values are listed with *LBOXITEMS. Corresponding displayed STRING labels are listed with *LBOXLABS. The labels are often the same as item values, but multi-byte characters are allowed for the labels only.
Option Menu Widget
*OPT = Label,SelectType,NumRows
*OPTITEMS = NumItems, name1, name2, name3, ...., namen
*OPTLABS = lab1, lab2, lab3, ..., labn
Three successive key word entries: OPT, OPTITEMS,OPTLABS are required to specify an option menu widget display. The option menu is used to obtain a single STRING value in a controlled fashion from an available list. Incorrect user typing is avoided. Label can be multi-byte. It appears above the widget. NumRows is the number of visible rows to display SelectType can be BROWSE, EXTEND, MULTIPLE, or SINGLE. NumItems is the number of item values to select from. Ui_item_create is used to create the items. The actual STRING item values (names) are listed with OPTITEMS. Corresponding displayed STRING labels are listed with OPTLABS. The default displayed item is the first one listed under OPTITEMS. The labels are often the same as item values, but multi-byte characters are allowed for the labels only.
Textbox Widget
*TBOX = Label, DefaultText, NumRows
The label can be composed of multi-byte characters. DefaultText is the actual text to be displayed in the widget. The default text should NOT contain "," or "=" characters. NumRows is the total number of rows to be displayed in the textbox widget.
Specification of call parameters for which no widgets are displayed
Hard-wired (hidden) call list parameters
The keyword *HPARAM is used to specify a PCL function input parameter which is hidden or "hard wired" and not available for the user to change via displayed widgets. The referenced function is called with specified fixed values as listed on HPARAM, and no corresponding widgets are displayed for user input.
Format for specifying a single value hard-wire parameter:
*HPARAM = DataType, Value
where for a single value parameter, DataType is STRING, REAL, INTEGER, or LOGICAL.
Format for specifying an array of hard-wired parameters:
*HPARAM = DataTypeA, NumVals, val1, val2, val3, ... , valn
where for an array or values, DataTypeA is STRINGA, REALA, LOGICALA, or INTEGERA. NumVals is the number of values listed for the input parameter array.
This is how the hidden parameter (*HPARAM)in the .def file is referenced by the .xml file:
<dialog dlgid=”hparam”
inputid=”hparam_test”
quedlg=.#1.#st1ck1”
...
</dialog>
This is how the hidden parameter (*HPARAM) is defined in the .def file:
*INPUTID = hparam_test
*CLASS = AANAV
*FUNCTION = hparam_test
# User can’t see the HPARAM value, it’s passed into the function
# without a widget
*HPARAM = REAL,111.
*STATUSCHECK
*LOAD ITEM
This is how the hidden value from *HPARAM is passed into the .pcl file:
FUNCTION hparam_test(arg1)
REAL arg1
/* The value arg1 is set in the .def file by using the keyword *HPARAM. This shows how a value can be passed into a function without the use of a widget */
END FUNCTION
Output return arguments
The keyword RETVAR is used to specify use of a global variable for a function return value or array of values. This creates a placeholder in the list of call sequence arguments to the function. This is useful for calling standard built-in functions because they typically have call sequence arguments for return values. Note that this automatically creates a global variable and uses it as a call sequence argument to the function, and functions of any class can subsequently access them.
Format for specifying a single valued parameter:
*RETVAR = VarName,DataType
VarName is the ASCII character name given to the global variable. DataType is listed as STRING, INTEGER, or REAL. A VIRTUAL STRING variable is declared and used as the parameter argument when a STRING type is specified. The called function will reallocate the string.
Format for specifying an array of parameters:
*RETVAR = VarName, DataTypeA, NumVals
VarName is the ASCII character name given to the global variable. DataTypeA is STRINGA, REALA, LOGICALA, or INTEGERA. A GLOBAL variable array of type DataType and dimension NumVals is declared and echoed to the session file before the function call is made.