Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide
TSD Script offers a form system that is used to create windows from a description (resource) file.
A form is a window containing some type of data entry form. In a GUI environment, the form is the primary means of interaction between the user and the application. A developer places controls on the blank form by selecting them from a toolbar. Form controls include:
A form control is an element that is used either to obtain information from the user or to convey information to the user. For example, a data entry form usually contains one or more text box controls, an OK button, and a Cancel button. The Developer's Toolkit Interface Designer can be used to add controls to a form (see the Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide for additional information).
The following list includes all the form controls supported by TSD Script.
Control Name | Description |
Subform | Complex control containing several other controls. |
Text box | Rectangular region that allows the user to type a single line of information. If the user types more text than can fit on a single line, the box automatically scrolls. |
Multi-line text box | Rectangular region used to type multiple lines of text. Text can optionally be made to word wrap within the box. |
List box | Rectangular box that contains a list of possible choices. Users cannot type a selection in a list box. |
Combo box | Text box with a list box attached. The user can either type a value into the text box or select a value in the drop-down list. The selected value appears in the text box and the list box disappears. |
Tree | Control that displays hierarchical data. |
Option buttons | Button used to select one of a set of mutually-exclusive choices. Users select a button; then that button is filled in. |
Check box | Square boxes whose options can be selected or cleared to turn an option on or off. More than one check box can be selected at a time. |
Slider | A bar that moves interactively. |
Button | Rectangular button that initiates an action. |
Text | Field that displays text. Users cannot modify the text. |
Clock | A running time-of-day clock or an elapsed time counter. |
Table | Data structured in rows and columns. |
Hypertext | Region that displays text in a hypertext format. |
Group box | A rectangular frame that groups several controls by meaning or functionality. |
Image | Field that displays an image from a file. |
Forms are maintained as separate application resources. Developer's Toolkit allows you to create a collection of form specifications and store them in files with a .df extension. Like knowledgebase files, there is both a source form and an object form for such specifications. A .df file allows menus, toolbars, and strings.
The Interface Generator is an TSD Script program that takes a source .df file and creates an object .dfc file. The .dfc files are loaded and displayed by Developer's Toolkit at run time.
The following example of an TSD Script code fragment uses a form.
TYPES EmployeeRecord IS RECORD first, last, ssn : STRING; salary : REAL; department : STRING; END; VARIABLES employee : EmployeeRecord; ACTIONS IF DlgBox($Desktop,'EMPLOYEE.DFC[ADDFORM]', $NullHandler,employee) > 0 THEN SQLInsert('EMPLOYEES',employee); END;
In the example, a new EmployeeRecord type has been declared in the types section. In the variables section, there is also a variable of this type. Record field names are the same as form control names.
The DlgBox statement in the actions section does the following:
Forms also typically contain OK and Cancel buttons.
The DlgBox statement takes four arguments:
Argument Title | Description |
Parent Window | The handle to the window that parents the new form. |
Form File | The name of a compiled form specification file. If the file contains more
than one form specification, the name of the desired form must be enclosed in square brackets following the file name. |
Event Handler | Like the generic windows discussed previously, all forms have an event
handler associated with them. Sometimes, you may want the handler to perform the default
action for every event. In these cases, you can When the user chooses a button with the Accept property, TSD Script automatically
copies the contents of the form controls into |
Result Variable | A record variable whose fields correspond to controls in the form. When
a user exits a form by pressing a button with the Accept property, the contents of every
control on the form are copied into |
Consider another example:
TYPES EmployeeRecord IS RECORD first, last, ssn: STRING; salary : REAL; department : STRING; END; VARIABLES employee: EmployeeRecord; ACTIONS SQLSelectInto('SELECT * FROM EMPLOYEES WHERE SSN=305-33-4111',employee); IF DlgBox($Desktop,'EMPLOYEE.DFC[EDITFORM]', $NullHandler{employee},employee) >> 0 THEN SQLUpdate('EMPLOYEES','WHERE SSN=''' & employee.snn & '''',employee); END;
This example shows code that:
Two changes have been made to this DlgBox statement:
In the example, the user sees the information retrieved from the EMPLOYEES table in the form and can move to any form and change any information.
In order to handle advanced features, such as showing an employee's picture when the user chooses a button or validating the format of a social security number, you must use an event handler. To do this you need to create form event handlers.
This section introduces a form with an event handler. The example presents an entire knowledgebase called Employees that implements a single public function called AddEmployee. The body of AddEmployee is similar to previous examples, except that instead of using $NullHandler, it references an event handler called EmployeeEvent.
KNOWLEDGEBASE Employees; USES Globals; TYPES EmployeeRecord IS RECORD first, last, ssn : STRING; salary : REAL; department : STRING; END; ROUTINES FUNCTION AddEmployee: BOOLEAN; PRIVATE ROUTINES EVENT EmployeeEvent(REF employee: EmployeeRecord) IS ROUTINES
FUNCTION ValidSSN(VAL ssn: STRING): BOOLEAN IS VARIABLES i: INTEGER; ACTIONS IF StrLength(ssn) <> 11 THEN EXIT(FALSE); END; FOR i:=1 TO 11 DO IF (i = 4 OR i = 7) AND (ssn[i] <> '-') THEN EXIT(FALSE); ELSIF StrPos('0123456789',ssn[i]) = 0 THEN EXIT(FALSE); END; END; EXIT(TRUE); END (* Valid SSN *);
ACTIONS WHEN $Event IS $MsgSelect THEN WHEN $FieldName IS 'SSN' THEN IF NOT ValidSSN(employee.ssn) THEN Exit(0); END; ELSWHEN 'PICTURE_BUTTON' THEN ShowPicture(employee.last_name & '.BMP'); END; END; END (* Employee Event *);
FUNCTION AddEmployee: BOOLEAN IS VARIABLES employee: EmployeeRecord; ACTIONS IF DlgBox(mainWindow, 'EMPLOYEE.DFC[ADDFORM]', EmployeeEvent{employee},employee) > 0 THEN SQLInsert('EMPLOYEES',employee); EXIT(TRUE); ELSE EXIT(FALSE); END; END (* Add Employee *);
EmployeeEvent is an event handler that takes a single pass-by-reference parameter of the same type as the return variable passed in DlgBox.
The event handler tests for only one event, $MsgSelect, and is
generated whenever the form is about to move the cursor out of the current control.
If the user types a value into a text control and presses the TAB key, a $MsgSelect
event is generated. The name of the control that the user is about to leave comes along
with this event in an "invisible" parameter called $FieldName.
The next example looks more closely at the body of EmployeeEvent.
WHEN $Event IS $MsgSelect THEN WHEN $FieldName IS 'SSN' THEN IF NOT ValidSSN(employee.ssn) THEN Exit(0); END; ELSWHEN 'PICTURE_BUTTON' THEN ShowPicture(employee.last_name & '.BMP'); END; END;
This example illustrates the following:
The default result is "1," which indicates success. However, there are cases when it is necessary to return a different value.
Certain events that TSD Script generates automatically are refused when the event handler exits with a value of 0. $MsgSelect is such an event.
If EmployeeEvent finds that an invalid social security number was provided while processing the $MsgSelect event for the SSN field, it exits with a value of 0.
This occurrence is known as refusing the event. The result of this refusal is twofold.
Usually, the $MsgSelect event lets you know that something has changed in a form. $MsgSelect can be generated in one of three ways:
Note: $MsgSelect is generated only when a new value is different from the old one.
Note: Pressing ENTER is the same as choosing the default command button, if one has been defined. This generates a $MsgAccept event. If there is no default command button, a $MsgSelect event is generated.
When the event handler receives the $MsgSelect event, the window instance data (which the event handler references with its record argument) is updated to reflect the change. For example, when a user types a value into the SSN text box and presses the TAB key, the value is copied into the SSN field of the window instance variable and a $MsgSelect event is generated. The previous field value is available in the first unnamed event parameter.
The value of the control is undefined until the Select message is complete; therefore the control value cannot be queried.
Forms can generate a number of additional events including:
Form Events | Description |
$MsgInitialize | Special version of $MsgSelect that occurs only during the creation phase of a form. |
$MsgCreate | Received just before the form is displayed. This is a good time to perform
initializations such as adding the list of possible choices to a list box and so on. |
$MsgDestroy | Received just before a form is closed. |
$MsgAccept | Received when the user accepts a form, usually by pressing ENTER or choosing OK. |
$MsgCancel | Received when the user cancels a form, usually by pressing ESCAPE or choosing CANCEL. |
$MsgEnterField | Received when the cursor is just about to specify a new control. $FieldName
contains the name of the new control. |
$MsgExitField | Received when the cursor is just about to leave a control. $FieldName contains the name of that control. |
$MsgHelp | Received when the user chooses HELP or the F1 key. |
$MsgMandField | Received when the user tries to accept a form with one or more mandatory text entry
boxes not filled in. $FieldName contains the name of the first blank
mandatory text entry box. By default, the system displays |
Each control on a form has a name. In previous examples, a form has been used to obtain the information needed to fill a variable of type EmployeeRecord. Since that record has a field called FIRST_NAME, a form control called FIRST_NAME is also required. When a user types a value into the FIRST_NAME form control, the information is copied into the FIRST_NAME record field.
Note: Some controls do not carry data. For example, command buttons do not have a value; they generate events. Therefore, you do not need to have a record field for any button on a form.
You can specify additional attributes for form controls including:
Attributes | Description |
Read Only | Data in the control is initialized by the window instance record and cannot be changed by the user. |
Mandatory | The user cannot accept the form until values have been provided for all mandatory controls. |
Input Length | Specifies the number of characters the user can type into the control in a text field. |
There are other attributes that affect only specific controls. For example, you can turn word-wrap on or off for multi-line text boxes.
Table is a window used to view a SQL result table. A SQL result table is a set of rows and columns.
Table is used as a form control and allows you to:
Columns inside Table are resizable. A thin vertical bar separates
adjacent columns and users can reposition this bar to change column width.
The select statement may be specified in the .df file or programmatically.
Statements | Description |
DlgSQLSelect | This statement causes TSD Script to issue the indicated SQL query and to
refresh the contents of the indicated Table control with the results of
that query. This statement takes three arguments:
This is the most efficient way to get data from a database to a table control. |
DlgFieldValue | This statement can be used to retrieve a selected row. This statement takes three arguments:
Columns from the row are copied into the record fields which have identical names (for example, "FIRST_NAME" column copies into r.FIRST_NAME). |
DlgListBoxInsert | This statement inserts a new row into Table. This
command does not perform a SQLInsert statement, but adds a new row to the
indicated form control. This statement takes three arguments:
The matching values are copied into the appropriate columns and record fields with no column matches are ignored. |
DlgListBoxUpdate | This statement updates a selected row in Table. This
command does not perform a SQLUpdate statement, but updates the
information in the form. This statement takes three arguments:
The matching values are copied into the appropriate columns. Record fields with no column matches are ignored. |
DlgListBoxDelete | This statement deletes the selected row in the Table
control. This command does not perform a SQLDelete operation, but removes
a row from the indicated control in the form window. This statement takes two arguments:
|
This example creates a knowledgebase called Users with a single public procedure called WorkWithUsers.
KNOWLEDGEBASE Users; TYPES UserRecord IS RECORD $Select : String; user_ID : String; user_name : String; user_rights : Integer; END; ROUTINES PROCEDURE WorkWithUsers; PRIVATE ROUTINES EVENT UserEvent(REF user: UserRecord) IS; VARIABLES i: Integer; ROUTINES PROCEDURE AddUser IS; VARIABLES newUser: UserRecord; ACTIONS IF DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent, newUser) > 0 AND SQLInsert('USERS',newUser) > 0 THEN DlgListBoxInsert($Handle,'USERLIST',newUser); END; END (* Add User *);
PROCEDURE EditUser IS; ACTIONS IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent {user},user) > 0 AND SQLUpdate('USERS','USER_ID=''' user.user_ID & '''',user) > 0 THEN DlgListBoxUpdate($Handle,'USERLIST',user); END; END (* Edit User *);
PROCEDURE DeleteUser IS; ACTIONS IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND SQLDelete('USERS','USER_ID='''&user.user_ID&'''') > 0 THEN DlgListBoxDelete($Handle,'USERLIST',user); END; END (* Delete User *);
ACTIONS WHEN $Event IS $MsgCreate THEN DlgSQLSelect($Handle,'USERLIST',user.$select); ELSWHEN $MsgSelect THEN WHEN $FieldName IS 'ADD_BUTTON' THEN AddUser; ELSWHEN 'EDIT_BUTTON' THEN EditUser; ELSWHEN 'DELETE_BUTTON' THEN DeleteUser; END; END; END (* User Event *);
PROCEDURE WorkWithUsers IS; VARIABLES UserWindow: WINDOW; user: UserRecord; ACTIONS user.$select = 'SELECT * FROM USERS'; DlgCreate($Desktop,userWindow, 'USERS.DFC [WORKWITHUSERS]', UserEvent{user}); END (* Work With Users *);
The role of WorkWithUsers is to create a form with the following controls:
The UserEvent event handler for the form processes these events:
~ The $MsgSelect message is generated with the name of the command
button, EDIT_BUTTON, passed in $FieldName.
~ The event handler calls the EditUser procedure to handle this event.
EditUser first uses the DlgFieldValue statement to retrieve the value of
the selected row.
~ It then uses the EDITFORM form from USERS.DFC to create a form in which the user can
make desired changes.
~ When the user accepts this form, the SQLUpdate statement is used to update the row in
the USERS table and DlgListBoxUpdate
is used to update the corresponding row in the USERLIST Table control.
Table holds only the information specified by its column description.
This could be a subset of the columns contained in the SQL result table. When you use the DlgFieldValue
command to retrieve a row from the Table control, only fields
corresponding to columns in that control are returned. You may need to perform a SQLSelectInto
or SQLSelect in order to complete the rest of the record.
TSD Script creates a new form in a process that involves several steps:
Note: Data in the record instance variable overrides initialization values provided in the form file.
A modal form is one in which the program waits for the user to accept or cancel the form before proceeding. When a modal dialog box is displayed, no other windows can be selected.
Modal forms are created with DlgBox. The statement following DlgBox is not executed until the user finishes with the form it creates. The information specified by the user is returned in the fourth argument to DlgBox. This is the output record variable.
Modal forms should be reserved primarily for important error messages or critical dialog boxes where the user cannot continue without answering a query. An example of this type of form might be a message regarding file deletion.
A modeless (non-modal) form is one in which the application does not wait for the user before proceeding. This means the user is able to switch to other windows while the form is displayed.
Modeless forms are created with DlgCreate. When you make a call to DlgCreate, the process of creating a form is set into motion. However, the execution of the next statement happens simultaneously.
The new form has its own user interface and its own program (its event handler). It continues to exist until the user either accepts or cancels the form, or until another part of the application sends it a close message ($MsgClose).
Note: In event-driven programming, modeless forms are preferred.
TSD Script offers a special kind of form with tabbed "pages." To move from page to page, the user chooses the tabs.
You create tabbed forms in the Developer's Toolkit Interface Designer by specifying one or more forms to combine. At run time, you can use these forms just as you do other types of forms. They can be created with either DlgBox or DlgCreate. To manage their events, you can create an event handler.
When you work with tabbed forms, remember the following:
Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide