Tivoli Service Desk 6.0 Developer's Toolkit Script Programming Guide

Chapter 7: The Form System

Back to Table of Contents


Introduction

Definition

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:

Form controls

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.

Form files

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.

Sample form code

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.

DlgBox statement arguments

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
specify $NullHandler. In this case, $NullHandler allows the user to move from form control to form control
and to type values into the form.

When the user chooses a button with the Accept property, TSD Script automatically copies the contents of the form controls into
corresponding fields in the result variable.

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
the corresponding fields of the record variable. The record variable can then be written to a database, displayed
in a window, or whatever is appropriate for the application.

DlgBox example

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.

Form Event Handlers

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.

Event handler example

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.

The $MsgSelect Event

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.

Generating a $MsgSelect event

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.

Other Form Events

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
a message notifying the user of the problem. Return 0 to prevent this box from being displayed.

Form Control Names

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.

Additional control attributes

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

Description

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:

  • The window handle of the form
  • The name of the Table control
  • A string expression representing a SQLSelect statement

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:
  • the form window handle
  • the control name
  • a record variable that receives information from the highlighted row

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 form window handle
  • Control name
  • A record variable whose fields are to be matched with column names of Table

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 form window handle
  • The control name
  • A record variable whose fields are matched with column names of the Table control

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:

  • The form window handle
  • The name of the Table control

Table example

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 *); 

Example explanation

The role of WorkWithUsers is to create a form with the following controls:

The UserEvent event handler for the form processes these events:

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.

Creating Forms

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.

Modal forms

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.

Modeless forms

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.

Tabbed forms

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

Back to Table of Contents

Copyright