Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Dialog Box Handling

Return to Main Page

------------------------------------------------------------------------

$Desktop

Description

Returns a handle to the desktop window. This value is permanent during the current session. This value is not stored permanently, however.
The next time the program executes, this constant has a new value.

Syntax

FUNCTION $Desktop: WINDOW;

Caution: In OS/2, there are valid messages you can send to the desktop to pause processing.
For example, sending $MsgClose to the desktop pauses the execution of the program. This behavior is
controlled by the operating system.

Notes

$Desktop is a predefined system constant that contains the handle to either the OS/2 desktop or the Windows desktop.
It is often specified as the parent in window and dialog box statements.

Example

KNOWLEDGEBASE Desktop;
ROUTINES
PROCEDURE Example;
PRIVATE
ROUTINES
(* Create a scroll window parented by the desktop with
default event processing *)
PROCEDURE Example IS
VARIABLES
whdl: WINDOW;
ACTIONS
WinCreateScrollWindow($Desktop, (*Window is a child of
OS/2 desktop *)
whdl, (* return handle
of new window *)
$NullHandler, (* Default event
processing *)
5, 5, 80, 20, (* Window location
and size *)
'Example', (* Window title *)
'', (* Use default font
0, (* Point size is
ignored for default *)
BitOr( $WinTitle, $WinBorder, $WinSysMenu ));
WinWait( whdl );
END;

Return Codes

See Also

------------------------------------------------------------------------

$KeyCode

Description

Indicates the key pressed by the user when a $MsgChar event occurs.

Notes

Script defines several constants for special keys such as the cursor control keys, modified keys
(i.e., keys that are pressed in combination with others, such as Control or Alt), etc.

Note: For information see the TSD Script Messages page.

Example

EVENT MyEvent IS
ACTIONS
WHEN $Event IS $MsgChar THEN
WHEN $KeyCode IS $KeyUpArrow THEN
MoveUp;
ELSWHEN $KeyDownArrow THEN
MoveDown;
ELSWHEN $KeyLeftArrow THEN
MoveLeft;
ELSWHEN $KeyRightArrow THEN
MoveRight;
END;
END;

Return Codes

See Also

Also see Key Codes.

------------------------------------------------------------------------

DlgBox

Description

Creates a modal dialog box from a dialog box specification file. A modal dialog box is owned by the application main window.
A call sent to a modal dialog box does not return until the dialog box is destroyed. If the parent is not the desktop and the owner
is not specified, the parent window is disabled. When a modal dialog box is active, the end user may not interact with either its
parent window or any of its other child windows.

Syntax

FUNCTION DlgBox(VAL parent: WINDOW, VAL dialogFile: STRING,

VAL EventHandler: EVENT,

REF returnRec: RECORD of ANY): INTEGER;

Caution: Do not use DlgBox while you process a $MsgDDEInitiate message. If you do,
$MsgDDEInitiate broadcasts a message to the applications and locks the message queue until a
response is returned.

Meanwhile, the DlgBox statement initiates an event handler that is also waiting for a reply from the message queue.
DlgBox prevents the other applications from sending messages to the message queue. This results in a deadlock,
which effectively locks the user interface.

Argument Notes

Argument Name Description
dialogFile The file name of the dialog box specification file. The following search is performed:

1. If the file has any explicit directory specified, that directory is the only place searched.
2. Search the directories explicitly specified on the command line. Search current working directory.
3. Search the directory in which the Script interpreter is located.
4. Search the directories specified in the SAIPATH environment variable.
5. (OS/2 only) Search the directories specified in the DPATH environment variable.
6. Search the directories specified in the PATH environment variable.

If the file cannot be found using this strategy, DlgBox returns an error message indicating that the file was not found.
Optionally, you can specify the name of the dialog box to display. The form name is specified in the format: fileName[formName].

EventHandler

An event handler that processes events generated by the window or dialog box. If no event processing is required,
the keyword $NullHandler may be used. returnRec Return value. If the user accepts the dialog box, the data
contained in the dialog box is assigned to this record. This assignment is based on controls that have a control name that
matches an item name in the record definition. If the dialog box window is destroyed by any other means, the value is
unaltered. If an event handler is present, this record must be of the same type as the instance data parameter to the event handler.

Notes

First Message Received

When a dialog box is created, the following messages are received in the

order shown:

* $MsgEnterField places the cursor on the first control defined in the

tab order.

* $MsgInitialize initializes the controls that contain data. A separate $MsgInitialize message
is received for each control with data in the dialog box.

* $MsgCreate creates the actual dialog box.

Trimming White Space

White space is trimmed from a dialog box control if all spaces in the control are empty. This may occur if the
user enters a string of empty spaces in the control or if the dialog box specification file contains an empty string
for the control. In either case, if the value of the empty control is requested, $Unknown is returned.

Dialog Box Modality

To create a modal dialog box, create it with the DlgBox statement. A modal dialog box is owned by
the application main window. A call sent to a modal dialog box does not return until the dialog box is
destroyed. If the parent is not the desktop and the owner is not specified, the parent window is disabled.
When a modal dialog box is active, the end user may not interact with either its parent window or any of its
other child windows.

To create a modeless (or non-modal) dialog box, create it with the DlgCreate statement. A call sent to a
modeless dialog box returns immediately. The window exists until it is explicitly destroyed.

Dialog Box Specification File

The dialog box provides a template for user data entry. Various text boxes and controls are created from
the dialog box specification file. Each text box relates to a database field and has a unique name. One or more
of the text boxes may be bound to fields of instance data for the dialog box. Dialog box text boxes are bound
to instance data fields of the same name.

Event Handling

When a dialog box text box is updated by either the user or the application, the bound instance data field is updated.
The system performs a wide range of type conversions that force the dialog box data to the same type as the instance data.
If an event handler is present, the application is notified of the user's actions, and is given an opportunity to respond
and modify the actions.

Unless otherwise noted, the first two event parameters of all dialog box messages are:

* Event parameter one (integer) is the ID of the selected control. The alias $FieldID may be used to access it.

* Event parameter two (string) is the name of the selected control. The alias $FieldName may be used to access it.

For a list of messages that dialog boxes can receive, see "Dialog Box Receivable Messages" in this book.

Example

KNOWLEDGEBASE DlgExample;
TYPES
DlgData IS RECORD
sampleField: INTEGER;
END;
ROUTINES
PROCEDURE DialogExample;
PRIVATE
ROUTINES
EVENT DlgEvent(REF fields: DlgData) IS
ACTIONS
WHEN $Event IS $MsgCreate THEN
NOTHING; (* Sent once when dialog box is created *)
(* Has pseudo parameters $FormFile, and $FormName *)
ELSWHEN $MsgDestroy THEN
NOTHING; (* Sent once when dialog box is about to be destroyed *)
ELSWHEN $MsgHelp THEN
NOTHING; (* Sent when the help key or the help button*)(* is pressed and there is no help defined *)
(* for the current field, or the form *)
ELSWHEN $MsgEnterField THEN
NOTHING; (* Sent each time a new field becomes the *)
(* active field. The action may be refused*)
(* by returning 0 *)
ELSWHEN $MsgExitField THEN
NOTHING; (* Sent each time a field is about to *)
(* become inactive *)
(* The action may be refused by returning 0 *)
ELSWHEN $MsgAccept THEN
NOTHING; (* Sent when the user accepts the dialog
(* box. The accept action may be refused *)
(* by returning 0 *)
ELSWHEN $MsgCancel THEN
NOTHING; (* Sent when the user cancels the dialog box.*)(* The cancel action may be refused by *)
(* returning 0 *)
ELSWHEN $MsgSelect THEN
NOTHING;(* Sent when a change in a field value is *)
(* detected. *)
(* Changes made by the user in multiline
(* edit and entry fields are detected when*)(* the field is exited. Other changes are*)
(* detected immediately. *)
(* Returning 0 refuses the change. *)
(* The instance data is updated to
(* the new field *)
(* value. Event parameter three has the old(* field value, and Event parameter four*)
(* has the new field value *)
ELSWHEN $MsgMandField THEN
NOTHING; (* Sent when the user accepts the dialog box(* and a mandatory field does not have a*)
(* value. The system default action is to*)
(* display a message, and abort *)
(* the accept action. If the event handler*)
(* does not return 1 (the default) the *)
(* message is not displayed. If 0 is*)
(* returned the accept action is *)
(* processed and a $MsgAccept is sent *)
ELSWHEN $MsgUser THEN
NOTHING; (* Any message defined by the application *)
END;
END (* Dlg Event *);
PROCEDURE DialogExample IS
VARIABLES
dlghdl: WINDOW;
fields: DLGDATA;
ACTIONS
DlgBox ($Desktop,'example[dialog1]',
DlgEvent{fields},fields);
END (* dialog box Example *);

Return Codes for All Statements Beginning with Dlg or Win

Return Code Description
1 Successful completion.
0 User abort. The user closed the window or aborted the operation. Usually this is done by pressing the Esc key or the Cancel button, or by closing the window from the system menu.
-1 The window handle does not refer to a valid window. The window may no longer exist, or the window does not support the command.
-2 Unknown value
-3 Insufficient memory
-4 No creation. The operating system was unable to create the requested object. One possible cause is that a parent window handle references a window that no longer exists.
-7 The named control of a dialog box could not be found in the dialog box referenced by the window handle.
-8 The requested dialog box command may not be performed on the type of control named.
-10 A call failed at the operating system level. This may be caused by an improper configuration or inadequate resources.
-12 The SendMessage or PostMessage statement was called with a message that is not supported by the NETx statements. Messages must either be one of the supported $MsgNetx messages or a user-defined $MsgUser + n message that is specifically defined for use with the NETx statements.

See Also

For information on creating dialog box specification files, see the Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.

------------------------------------------------------------------------

DlgCreate

Description

Creates a modeless dialog box from a dialog box specification file.

Syntax

FUNCTION DlgCreate(VAL parent: WINDOW, REF whdlDialog: WINDOW,

VAL dialogFile: STRING,

VAL EventFunction: EVENT): INTEGER;

Argument Notes Argument Name Description
whdlParent This parameter specifies the parent window of the dialog box.
whdlDialog The handle of the new window is returned in this parameter. If there is an error, the variable is set to $Unknown.
dialogFile The file name of the dialog box specification file. The following search is performed:

1. If the file has any explicit directory specified, that directory is the only place searched.
2. Search the directories explicitly specified on the command line.
3. Search current working directory.
4. Search the directory in which the Script interpreter is located.
5. Search the directories specified in the SAIPATH environment variable.
6. (OS/2 only) Search the directories specified in the DPATH environment variable.
7. Search the directories specified in the PATH environment variable.

If the file cannot be found using this strategy, DlgBox returns an error message indicating that the file was not found. Optionally, you can specify the name of the dialog box to display. The form name is specified in the format: fileName[formName].
EventFunction An event handler that processes events generated by the window or dialog box. If no event processing is required, the keyword $NullHandler may be used.

Notes

First Messages Received

When a dialog box is created, the following messages are received in the order shown:

1. $MsgEnterField places the cursor on the first control defined in the tab order.

2. $MsgInitialize initializes the controls that contain data. A separate $MsgInitialize message
is received for each control with data in the dialog box.

3. $MsgCreate creates the actual dialog box.

Modality

To create a modal dialog box, create it with the DlgBox statement. A modal dialog box is owned by the
application main window. A call sent to a modal dialog box does not return until the dialog box is
destroyed. If the parent is not the desktop and the owner is not specified, the parent window is disabled.
When a modal dialog box is active, the end user may not interact with either its parent window or any of its
other child windows.

To create a modeless (or non-modal) dialog box, create it with the DlgCreate statement. A call sent to a
modeless dialog box returns immediately. The window exists until it is explicitly destroyed.


Dialog Box Controls

The dialog box provides a template for user data entry. Various controls, such as text boxes, are
defined in the dialog box specification file. Each control has a unique name. One or more of these may
be bound to database fields. The database provides instance data for the dialog box. The .df names of
the bound controls must be the same as the names of the instance data fields.

Each time a dialog box control is updated by either the user or the application, the bound instance data field is updated.
The system performs a range of type conversions that force the dialog box data to the same type as the instance
data. If an event handler is present, the application is notified of the user's actions, and is provided with an opportunity
to respond and modify them.

Trimming White Space

White space is trimmed from a dialog box control if all spaces in the control are empty. This may occur if the user
enters a string of empty spaces in the control or if the dialog box specification file contains an empty string for the control.
In either case, if the value of the empty control is requested, $Unknown is returned.

Dialog Box Messages: Parameters

Unless otherwise noted, the first two event parameters of all dialog box messages are:

Return Codes

See Also

For more information on creating dialog box specification files, see the

Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.

------------------------------------------------------------------------

DlgCreateSubForm

Description

Loads a subform from a form file and displays it in the context of an existing dialog form.

Syntax

FUNCTION DlgCreateSubForm(VAL whdl:WINDOW,
REF SubFormHandle: WINDOW,
VAL formSpec: STRING,
VAL EventHandler: EVENT,
VAL xPos: INTEGER,
VAL yPos: INTEGER
): INTEGER;
Argument Notes Argument Name Description
EventFunction An event handler that processes events generated by the window or dialog box. If no event processing is required, the keyword $NullHandler may be used.
EventHandler An event handler that processes events generated by the new subform. The keyword $NullHandler can be used if no event processing is required.
formSpec The form specification for the subform in the form "FILE[FORM_NAME]".
SubFormHandle The handle of the new subform is returned in this parameter. The variable is set to $Unknown if there is an error.
whdl Parent dialog form for the new subform
xPos The x position used in the upper left corner of the new subform. This coordinate is relative to the upper left corner of the parent dialog form.
yPos The y position used in the upper left corner of the new subform. This coordinate is relative to the upper left corner of the parent dialog form.

Example

WHEN $Event IS $MsgCreate THEN
DlgCreateSubForm($Handle, instanceData.theSubForm, 'screens[theSubForm]', 
SubFormHandler, 3, 50);
END;

Return Codes

See Also

For more information on creating dialog box specification files, see the Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.

------------------------------------------------------------------------

DlgDeletePage

Description

Removes an existing page from a notebook on an existing form.

Syntax

FUNCTION DlgDeletePage ( VAL PARENT : WINDOW,

VAL NOTEBOOKID : STRING,

VAL PAGEID : STRING ) : INTEGER;

Argument Notes Argument Name Description
Parent The window handle for the form which contains the notebok.
NotebookID The ID name of the notebook (from the .df specification)
PageID The ID name of the page to be removed (from the .df specification)


Example

KNOWLEDGEBASE dlgpage;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
(* Global Variable to hold the Window handle of the dialog box *)
mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
(* Create a dialog using the form PAGE_MAIN from dlgpage.df *)
(* PAGE_MAIN has a subform with notebook PAGE_NOTEBOOK as it's form *)
(* PAGE_NOTEBOOK currently has two tabs *)
DlgCreate($Desktop, mainWindow, 'dlgpage[PAGE_MAIN]', $NullHandler);
(* Remove the second page from the notebook. *)
(* This page has the ID FORM_TAB2 *)
DlgDeletePage(mainWindow, 'PAGE_NOTEBOOK', 'FORM_TAB2');
WinWait(mainWindow);
END;

Return Codes

See Also

DlgInsertPage

------------------------------------------------------------------------

DlgFieldValue

Description

Queries the value of a dialog box control.

Syntax

FUNCTION DlgFieldValue(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
REF fieldValue: ANY): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
fieldValue Returns the value of the control queried. The data is converted to the type of the parameter and the resulting value is assigned to the parameter. Some conversions do not produce meaningful results. If the control is an SQLManage control or a list box, the additional parameter may be a record or a list of integers. The action is performed control-by-control for each control of the record. If the control is capable of multiple selections, such as a list box and table, and the additional parameter is a single variable, the first item is returned. All the items are returned if it is a list of variables.

Notes

White space is trimmed from a dialog box control if all spaces in the control are empty. This may occur if the user enters
a string of empty spaces in the control or if the dialog box specification file contains an empty string for the control. In either case,
if the value of the empty control is requested, $Unknown is returned.

Example

KNOWLEDGEBASE DlgField;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
SQLDATA IS RECORD
firstName: STRING;
lastName: STRING;
END;
(* ******* PRIVATE ******** *)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER ******** *)
EVENT DlgEvent( REF fields: DLGDATA ) IS
VARIABLES
names: SQLDATA;
ACTIONS
(* All dialog box messages have pseudo parameters
$FieldID, *)
(* and $FieldName *)
WHEN $Event IS $MsgSelect THEN
IF $FieldName = 'insertButton' THEN
DlgFieldValue ( $Handle, 'sql_data', names );
IF DlgBox( $Desktop,'addDlg', $NullHandler{names},
names ) > 0
THEN
DlgListBoxInsert( $Handle, 'namesTable', names );
SQLInsert( 'names', names );
END;
END;
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]', DlgEvent{ fields },fields );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgGetButtonText

Description

Queries the current text of a button.

Syntax

FUNCTION DlgGetButtonText (VAL whdlDialog: WINDOW,

VAL fieldName: String,

REF buttonText STRING): Integer;

Argument Notes Argument Name Description
whdlDialog Window handle of a dialog box.
FieldName Control name of the button whose text is queried.
ButtonText Text returned for the button.

Example

KNOWLEDGEBASE GetButton;
TYPES
ROUTINES
PROCEDURE Main;
PRIVATE
ROUTINES
PROCEDURE Main IS
VARIABLES
handle : WINDOW;
text : STRING;
ACTIONS
DlgCreate($Desktop,
handle,
'sample.dfc[sample]',
$NullHandler);
DlgGetButtonText(handle, 'test_button', text);
WinMessageBox(handle, 'Button Text', $MBOK,
text);
WinWait(handle);
END;

Return Codes

See Also

DlgSetButtonText

------------------------------------------------------------------------

DlgGetSelectedText

Description

Retrieves the selected text from a text box in a dialog box.

Syntax

FUNCTION DlgGetSelectedText(REF whdlDialog: WINDOW, REF fieldName: STRING,
REF selectedText: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
selectedText The selected text of a text box is returned in this argument. If no text is selected, a 0-length string is returned. If there is an error, an unknown string is returned.


Example

KNOWLEDGEBASE dlgform;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
(* Global Variable to hold the Window handle of the dialog box *)
mainWindow : WINDOW;
ROUTINES
EVENT MainEvent is FORWARD;
PROCEDURE Main IS
ACTIONS
(* Create the dialog box using FORM_DLG from dlgform.df *)
(* FORM_DLG has one EntryField with id CONTROl_TEXT and *)
(* a button with the id BUTTON_TEXT *)
DlgCreate($Desktop, mainWindow, 'dlgform[FORM_DLG]', MainEvent);
WinWait(mainWindow);
END;
EVENT MainEvent IS
VARIABLES
selString : STRING;
ACTIONS
(* When the button is pressed, the selected text from the entryfield *)
(* is displayed in a messagebox *)
WHEN $Event IS $MsgSelect THEN
IF $fieldName = 'BUTTON_TEXT' THEN
DlgGetSelectedText(mainWindow, 'CONTROL_TEXT', sel String);
WinMessageBox(mainWindow, 'Selected Text', $MBOK, selString);
END;
END;
END;

Return Codes

See Also

DlgInsertString

------------------------------------------------------------------------

DlgInsertPage

Description

Inserts a new page from a .dfc file into a notebook on an existing form. The existing event handler and instance data applies to the new form.

Syntax

FUNCTION DlgInsertPage (VAL FORM : WINDOW
VAL NotebookId : STRING
VAL PageId : STRING
VAL FormSpec : STRING
VAL TabName : STRING
VAL Position : INTEGER
): INTEGER;
Argument Notes Argument Name Description
Form The form where the new page is inserted.
NotebookId The ID of the notebook where the page is inserted.
PageId The ID of the page being inserted.
FormSpec The form specification for the subform in the form "FILE[FORM_NAME]'.
TabName The tab text of the page being inserted.
Position The position of the tab, among the other tabs, being inserted.


Example

KNOWLEDGEBASE dlgpage;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
(* Global Variable to hold the Window handle of the dialog box *)
mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
(* Create a dialog using the form PAGE_MAIN from dlgpage.df *)
(* PAGE_MAIN has a subform with notebook PAGE_NOTEBOOK as it's form *)
(* PAGE_NOTEBOOK currently has two tabs *)
DlgCreate($Desktop, mainWindow, 'dlgpage[PAGE_MAIN]', $NullHandler);
(* Insert the form FORM_TAB3 from dlgpage.df into the notebook specified *)
(* with the id PAGE_NOTEBOOK after the last page. The tab will have the *)
(* id 'Tab 3' *)
DlgInsertPage(mainWindow, 'PAGE_NOTEBOOK', '', 'dlgpage[FORM_TAB3]', 'Tab 3', $After);
WinWait(mainWindow);
END;

Return Codes

See Also

DlgDeletePage

------------------------------------------------------------------------

DlgInsertString

Description

Inserts a string at the cursor location in a text box, list box, or combo box.

Syntax

FUNCTION DlgInsertString(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL insertString: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from within an eventhandler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
insertString A string to insert at the cursor location in the control. Selected text is replaced by the inserted text.

Notes

Selected text is replaced by the inserted text.

Example

KNOWLEDGEBASE DlgIns_text;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
(* ******* PRIVATE ******** *)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER ******** *)
EVENT DlgEvent( REF fields: DLGDATA ) IS
VARIABLES
insertString: STRING;
ACTIONS
(* All dialog box messages have pseudo parameters $FieldID, *)
(* and $FieldName *)
WHEN $Event IS $MsgChar THEN
WHEN $KeyCode IS $KeyFn2 THEN
(* Look for function key 2 *)
(* Prompt user for text to insert *)
IF WinEditField( $Desktop, insertString, 0, 0, 30,
'Enter insert text',
$WinAutoPos + $WinBorder
+ $WinTitle ) > 0
THEN
(* Field must be an MultiLineEditor, Entry Field, or ComboBox *)
DlgInsertString( $Handle, 'text_field', insertString );
END;
END;
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]', DlgEvent{ fields }, fields );
END;

Return Codes

See Also

DlgGetSelectedText

------------------------------------------------------------------------

DlgIsItemEnabled

Description

Allows you to query whether a dialog control is enabled or disabled.

Syntax

FUNCTION DlgIsItemEnabled (VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
REF enabledState: BOOLEAN):
Integer;
Argument Notes Argument Name Description
whdlDialog Window handle of dialog box
fieldName Name of the control to be tested (either enabled or disabled).
enabledState TRUE if control is enabled, FALSE if disabled.


Example

KNOWLEDGEBASE DlgEnabl;
ROUTINES
PROCEDURE Main;
PRIVATE
ROUTINES
PROCEDURE Main IS
VARIABLES
Handle : WINDOW;
enabled : BOOLEAN;
ACTIONS
DlgCreate($Desktop,
Handle,
'dlgenabl[sample]',
$NullHandler);
(* enable button, check button status, display
result *)
DlgSetEnabled(Handle, 'test_button', TRUE);
DlgIsItemEnabled(Handle, 'test_button',
enabled);
WinMessageBox(Handle, 'Button Status', $MBOK,
enabled);
(* disable button, check button status, display
result *)
DlgSetEnabled(Handle, 'test_button', FALSE);
DlgIsItemEnabled(Handle, 'test_button',
enabled);
WinMessageBox(Handle, 'Button Status', $MBOK,
enabled);
WinWait(Handle);
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgListBoxClear

Description

Clears all values from any text box, SQLManage, or table control.

Syntax

FUNCTION DlgListBoxClear(VAL whdlDialog: WINDOW,
VAL fieldName: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName A list of control names in the dialog box that is addressed. The control name may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The command is performed for each control name in the list. The number of controls processed is returned. If an error occurs, processing stops. If the error occurs on the first control processed, the error code is returned by the statement.

Notes

If a value is selected when the list box is cleared, a $MsgSelect (or $MsgInitialize) is sent. Because the selected value
no longer exists, refusing this message has no effect.

Example

KNOWLEDGEBASE dlglist;
TYPES
FIELDREC IS RECORD
test_list_box: STRING;
END;
ROUTINES
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
itemList IS { 'new item 1', 'new item 2', 'new item 3' }: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER ******** *)
EVENT DlgEvent( REF fields: FIELDREC ) IS
VARIABLES
index: INTEGER;
listEntry: STRING;
ACTIONS
WHEN $Event IS $MsgCreate THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'Init value'
ELSWHEN $MsgInitialize THEN
WinMessageBox( $Handle, 'Initialize message', $MBYesNo,
'Old value = ' & $EventParm( 3, STRING ) &
'New value = ' & $EventParm( 4, STRING ));
ELSWHEN $MsgSelect THEN
WHEN $FieldName IS 'but_lb_clear' THEN
DlgListBoxClear( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_insert' THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'new item' );
DlgListBoxInsert( $Handle, 'test_list_box',
itemList );
ELSWHEN 'but_lb_delete' THEN
DlgListBoxDelete( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_update' THEN
DlgFieldValue( $Handle, 'test_list_box',
listEntry );
WinEditField( $Desktop, listEntry, 0, 0, 30, 'New
value?',
$WinAutoPos + $WinBorder + $WinTitle );
DlgListBoxUpdate( $Handle, 'test_list_box',
listEntry );
ELSWHEN 'but_lb_set_index' THEN
WinEditField( $Desktop, index, 0, 0, 30,
'New Index?',
$WinAutoPos + $WinBorder
+ $WinTitle );
DlgSetListBoxIndex( $Handle,
'test_list_box', index );
ELSWHEN 'but_lb_index' THEN
WinMessageBox( $Handle, 'Listbox index', $MBOK,
DlgListBoxIndex( $Handle,
'test_list_box' ) );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
data: FIELDREC;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlglist', DlgEvent, {data});
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $MBOK + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgListBoxDelete

Description

Deletes the selected element from any text box, SQLManage, or table control.

Syntax

FUNCTION DlgListBoxDelete(VAL whdlDialog: WINDOW,
VAL fieldName: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.

Notes

Deleting the selected element in a list box causes a $MsgSelect (or $MsgInitialize) to be sent with a value
of $Unknown. Because the previously selected value no longer exists, refusing this message has no effect.

Example

KNOWLEDGEBASE dlglist;
TYPES
FIELDREC IS RECORD
test_list_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
itemList IS {'new item 1', 'new item 2', 'new item 3' }: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
VARIABLES
index: INTEGER;
listEntry: STRING;
ACTIONS
WHEN $Event IS $MsgCreate THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'Init value' );
ELSWHEN $MsgInitialize THEN
WinMessageBox( $Handle, 'Initialize message', $MBYesNo,
'Old value = ' & $EventParm( 3, STRING )
& '' 'New value = '
& $EventParm( 4, STRING ));
ELSWHEN $MsgSelect THEN
WHEN $FieldName IS 'but_lb_clear' THEN
DlgListBoxClear( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_insert' THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'new item' );
DlgListBoxInsert( $Handle, 'test_list_box',
itemList );
ELSWHEN 'but_lb_delete' THEN
DlgListBoxDelete( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_update' THEN
DlgFieldValue( $Handle, 'test_list_box', listEntry );
WinEditField( $Desktop, listEntry, 0, 0, 30,
'New value?',
$WinAutoPos + $WinBorder + $WinTitle );
DlgListBoxUpdate( $Handle, 'test_list_box',
listEntry );
ELSWHEN 'but_lb_set_index' THEN
WinEditField( $Desktop, index, 0, 0, 30,
'New Index?', $WinAutoPos + $WinBorder
+ $WinTitle );
DlgSetListBoxIndex( $Handle, 'test_list_box', index );
ELSWHEN 'but_lb_index' THEN
WinMessageBox( $Handle, 'Listbox index', $MBOK,
DlgListBoxIndex( $Handle,
'test_list_box' ) );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
data: FIELDREC
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlglist',
DlgEvent, {data});
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $MBOK + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgListBoxIndex

Description

Queries the index of the selected item of a list box, SQLManage, or table control.

Syntax

FUNCTION DlgListBoxIndex(VAL whdlDialog : WINDOW,
VAL fieldName : STRING
) : INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.

Example

KNOWLEDGEBASE dlglist;
TYPES
FIELDREC IS RECORD
test_list_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
itemList IS { 'new item 1', 'new item 2', 'new item 3' }: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
VARIABLES
index: INTEGER;
listEntry: STRING;
ACTIONS
WHEN $Event IS $MsgCreate THEN
DlgListBoxInsert( $Handle, 'test_list_box', 'Init value' );
ELSWHEN $MsgInitialize THEN
WinMessageBox( $Handle, 'Initialize message',
$MBYesNo, 'Old value' &
$EventParm( 3, STRING ) &
'' 'New value = ' &
$EventParm( 4, STRING ));
ELSWHEN $MsgSelect THEN
WHEN $FieldName IS 'but_lb_clear' THEN
DlgListBoxClear( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_insert' THEN
DlgListBoxInsert( $Handle, 'test_list_box', 'new item' );
DlgListBoxInsert( $Handle, 'test_list_box', itemList );
ELSWHEN 'but_lb_delete' THEN
DlgListBoxDelete( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_update' THEN
DlgFieldValue( $Handle, 'test_list_box',
listEntry );
WinEditField( $Desktop, listEntry, 0, 0, 30,'New value?',
$WinAutoPos + $WinBorder + $WinTitle );
DlgListBoxUpdate( $Handle, 'test_list_box', listEntry );
ELSWHEN 'but_lb_set_index' THEN
WinEditField( $Desktop, index, 0, 0, 30, 'New Index?',
$WinAutoPos + $WinBorder
+ $WinTitle );
DlgSetListBoxIndex( $Handle, 'test_list_box', index );
ELSWHEN 'but_lb_index' THEN
WinMessageBox( $Handle, 'Listbox index', $MBOK,
DlgListBoxIndex( $Handle, 'test_list_box' ) );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlglist',
DlgEvent );
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $MBOK + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgListBoxInsert

Description

Inserts a value into any text box, SQLManage, or table control.

Syntax

FUNCTION DlgListBoxInsert(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL newValues: LIST OF ANY): INTEGER;

Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
newValue A value or list of values to insert into the list box. Each item in the list is converted to a string and inserted into the list box. Insertion begins after the selected item. If no item is selected, the new value is inserted at the end. You may specify a sort order attribute. This attribute overrides the insertion location.

OS/2 supports both ascending and descending sorting.
Windows supports only ascending sorting.
Sort orders are not supported for table controls.

For table controls, this parameter can be a record or a list of strings. Record field names are matched to column field names. If a column field name does not match a record field name, the column is left empty.


Example

KNOWLEDGEBASE dlglist;
TYPES
FIELDREC IS RECORD
test_list_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
itemList IS { 'new item 1', 'new item 2', 'new item 3' }: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
VARIABLES
index: INTEGER;
listEntry: STRING;
ACTIONS
WHEN $Event IS $MsgCreate THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'Init value' );
ELSWHEN $MsgInitialize THEN
WinMessageBox( $Handle, 'Initialize message',
$MBYesNo, 'Old value = ' &
$EventParm( 3, STRING ) & ''
'New value = ' &
$EventParm( 4, STRING ));
ELSWHEN $MsgSelect THEN
WHEN $FieldName IS 'but_lb_clear' THEN
DlgListBoxClear( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_insert' THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'new item' );
DlgListBoxInsert( $Handle, 'test_list_box', itemList );
ELSWHEN 'but_lb_delete' THEN
DlgListBoxDelete( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_update' THEN
DlgFieldValue( $Handle, 'test_list_box',
listEntry );
WinEditField( $Desktop, listEntry, 0, 0, 30, 'New value?',
$WinAutoPos +
$WinBorder + $WinTitle );
DlgListBoxUpdate( $Handle, 'test_list_box',
listEntry );
ELSWHEN 'but_lb_set_index' THEN
WinEditField( $Desktop, index, 0, 0, 30,
'New Index?',
$WinAutoPos + $WinBorder +
$WinTitle );
DlgSetListBoxIndex( $Handle, 'test_list_box',
index );
ELSWHEN 'but_lb_index' THEN
WinMessageBox( $Handle, 'Listbox index', $MBOK,
DlgListBoxIndex( $Handle,
'test_list_box' ) );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlglist', DlgEvent );
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $MBOK + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgListBoxUpdate

Description

Updates the selected value of an SQLManage or a table control.

Syntax

FUNCTION DlgListBoxUpdate(VAL whdlDialog: WINDOW,
VAL fieldName: STRING, VAL
updateValue: ANY): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
updateValue The selected record or list of strings in a SQLManage or a table control is replaced with the value of this parameter. Record fields are matched to column names. Any column not matching a record field is left empty. If no record is selected, a Field Not Found error is returned.

Example

KNOWLEDGEBASE dlglist;
TYPES
FIELDREC IS RECORD
test_list_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
itemList IS { 'new item 1', 'new item 2', 'new item 3': LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
VARIABLES
index: INTEGER;
listEntry: STRING;
ACTIONS
WHEN $Event IS $MsgCreate THEN
DlgListBoxInsert( $Handle, 'test_list_box', 'Init value' );
ELSWHEN $MsgInitialize THEN
WinMessageBox( $Handle, 'Initialize message', $MBYesNo,
'Old value = ' & $EventParm( 3, STRING ) & ''
'New value = ' & $EventParm( 4, STRING ));
ELSWHEN $MsgSelect THEN
WHEN $FieldName IS 'but_lb_clear' THEN
DlgListBoxClear( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_insert' THEN
DlgListBoxInsert( $Handle, 'test_list_box',
'new item' );
DlgListBoxInsert( $Handle, 'test_list_box', itemList );
ELSWHEN 'but_lb_delete' THEN
DlgListBoxDelete( $Handle, 'test_list_box' );
ELSWHEN 'but_lb_update' THEN
DlgFieldValue( $Handle, 'test_list_box', listEntry );
WinEditField( $Desktop, listEntry, 0, 0, 30,
'New value?',
$WinAutoPos + $WinBorder + $WinTitle );
DlgListBoxUpdate( $Handle, 'test_list_box',
listEntry );
ELSWHEN 'but_lb_set_index' THEN
WinEditField( $Desktop, index, 0, 0, 30,
'New Index?', $WinAutoPos
+ $WinBorder + $WinTitle );
DlgSetListBoxIndex( $Handle, 'test_list_box',
index );
ELSWHEN 'but_lb_index' THEN
WinMessageBox( $Handle, 'Listbox index', $MBOK,
DlgListBoxIndex( $Handle,
'test_list_box' ) );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlglist',
DlgEvent );
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $MBOK + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog box );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgLoadSubForm

Description

Loads a form from a .df file into an existing subform control. (Any existing form is replaced.)

Syntax

FUNCTION DlgLoadSubForm( VAL dialog : WINDOW,
VAL subform : STRING,
VAL resource : STRING, ) : INTEGER;
Argument Notes Argument Name Description
subform The name of the subform control into which the new form is loaded.
resource Resource string reference of the form in standard format.


Example

KNOWLEDGEBASE dlgsub;
ROUTINES
PROCEDURE Main;
(* ***** PRIVATE ***** *)
PRIVATE
VARIABLES
(*Global Variable to hold the Window handle of the window *) mainWindow : WINDOW;
ROUTINES
PROCEDURE Main IS
VARIABLES
ACTIONS
DlgCreate($Desktop, mainWindow, 'dlgsub[FORM_MAIN]', $NullHandler);
(* Load the form FORM_NEW from dlgsub.df into the subform control *)
(* CONTROL_SUBFORM on the current form *)
DlgLoadSubForm(mainWindow, 'CONTROL_SUBFORM', 'dlgsub[FORM_NEW]');
WinWait(mainWindow);
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgQueryColumnNames

Description

Queries the declared columns of an SQLManage or a table control.

Syntax

FUNCTION DlgQueryColumnNames(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
REF columnNames LIST OF STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
columnName A list of strings in which the declared column names for the SQLManage or table control are returned. The column names are returned in the order in which they are declared.

Notes

As shown in this example, WinWriteLN writes the entire list of strings sequentially.

Example

KNOWLEDGEBASE DlgCols;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
SQLDATA IS RECORD
firstName: STRING;
lastName: STRING;
END;
(* ******* PRIVATE *********)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: DLGDATA ) IS
VARIABLES
columnNames: LIST OF STRING;
whdl: WINDOW;
ACTIONS
(* All dialog box messages have pseudo parameters $FieldID,
and $FieldName *)
WHEN $Event IS $MsgCreate THEN
DlgQueryColumnNames( $Handle, 'sql_manage_field',
columnNames );
WinCreateScrollWindow( $Desktop, whdl, $NullHandler,
0, 0, 30, 12,
Column Names', $TimesRoman, 12,
$WinBorder + $WinTitle +
WinResize + $WinMinMax +
$WinHScroll + $WinVScroll
+ $WinSysMenu + $WinAutoPos );
WinWriteLN( whdl, columnNames );
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]', DlgEvent{ fields },fields );
END;

Return Codes

See Also

DlgSQLSelect

------------------------------------------------------------------------

DlgQueryItemCount

Description

Queries the number of items that are currently contained in a list box, combo box, table control, or SQLManage.

Syntax

FUNCTION DlgQueryItemCount (VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
REF itemCount: INTEGER): Integer;
Argument Notes Argument Name Description
whdlDialog Window handle of dialog box.
fieldName Field name of the control to query for its item count.
itemCount After the function call is made, itemCount holds the number of items contained by the control.

Notes

This function works only with controls that contain lists of data (a list box, combo box, table control, or SQLManage).

Example

KNOWLEDGEBASE QueryCnt;
ROUTINES
PROCEDURE Main;
PRIVATE
ROUTINES
PROCEDURE Main IS
VARIABLES
Handle : WINDOW;
MyList : LIST OF STRING;
Count : INTEGER;
ACTIONS
DlgCreate($Desktop,
Handle,
'querycnt[sample]',
$NullHandler);
ListInsert(MyList, 'Item #1');
DlgListBoxInsert(Handle, 'list_box', MyList);
DlgQueryItemCount(Handle, 'list_box', Count);
WinMessageBox(Handle, 'DlgQueryItemCount', $MBOK,
Count & ' item(s).');
WinWait(Handle);
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgQueryRowData

Description

Queries the contents of a given row for a list box, combo box, or table.

Syntax

FUNCTION DlgQueryRowData (VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL index: INTEGER,
REF rowData: ANY ) : INTEGER
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command.
index The index of the row whose data is desired.
rowData Holds the value of the row queried. For controls of type LISTBOX and COMBOBOX, this parameter should be of type STRING. For table controls and SQLManage controls, this parameter should be of type RECORD.

Notes

This function works only with controls that hold lists of data (that is, a list box, combo box, or table).

Example

KNOWLEDGEBASE MCLB;
TYPES
TABLEREC IS RECORD
System : STRING;
Component : STRING;
Item : STRING;
Module : STRING;
END;
EVENT DlgEvent(REF form : FORMREC) IS
VARIABLES
rowdata : TABLEREC;
retval : INTEGER;
ACTIONS
WHEN $Event IS $MsgSelect THEN
IF $Fieldname = 'GetRow' THEN
-- Get row data for row number 5
retval := DlgQueryRowData($handle, 'TABLE1', 5, rowda ta);
IF (retval = 1) THEN
WinMessageBox($handle, 'Row Data&', $MBOK,
'System value for row 5 is ' &
rowdata.System);
END;
END;
END;
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgSelectField

Description

Moves the cursor to the specified control.

Syntax

FUNCTION DlgSelectField(VAL whdlDialog: WINDOW,
VAL fieldName: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.

Notes

Moving the cursor to a new control generates a $MsgExitField and a $MsgEnterField. The dialog box
event handler may refuse either of these messages and cause the operation to fail.

Example

KNOWLEDGEBASE DlgSLCT;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
(* ******* PRIVATE *********)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: DLGDATA ) IS
ACTIONS
(* All dialog box messages have pseudo parameters $FieldID, and $FieldName *)
WHEN $Event IS $MsgCreate THEN
(* Select initial field for cursor *)
DlgSelectField( $Handle, 'startField' );
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]', DlgEvent{ fields },fields );
END;

Return Codes

------------------------------------------------------------------------

DlgSetButtonText

Description

Changes the label on a button.

Syntax

FUNCTION DlgSetButtonText(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL ButtonText: STRING): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
ButtonText The new label for the button. The control must be a push button.


Example

KNOWLEDGEBASE DlgButton;
TYPES
DlgData IS RECORD
allowEdit: BOOLEAN;
sampleField: INTEGER;
END;
ROUTINES
PROCEDURE DialogExample;
PRIVATE
ROUTINES
EVENT DlgEvent(REF fields: DlgData) IS
ACTIONS
WHEN $Event IS $MsgCreate THEN
IF NOT fields.allowEdit THEN
DlgSetButtonText($Handle,'editButton','View');
(* SAMPLEFIELD must be a MultiLineEditor, entry field,or combo box *)
DlgSetReadonly($Handle,'SAMPLEFIELD',TRUE);
END;
END;
END (* Dlg Event *);
PROCEDURE DialogExample IS
VARIABLES
fields: DlgData;
ACTIONS
fields.allowEdit := FALSE;
DlgBox($Desktop,'example[dialog1]',
DlgEvent{fields},fields);
END (* dialog box Example *);

Return Codes

See Also

------------------------------------------------------------------------

DlgSetEnabled

Description

Sets the enabled or disabled status of a control.

Syntax

FUNCTION DlgSetEnabled(VAL whdlDialog: WINDOW,
VAL fieldNames: LIST OF STRING [,
VAL newState: BOOLEAN ]): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The command is performed for every control name in the list. The number of controls processed is returned. Processing stops when an error is encountered. The system variable
$DlgError is set to the error code. If an error occurs on the first control processed, the error code is returned by the statement.
newState The new state of the control. This parameter is optional. If omitted, TRUE is assumed.

Example

KNOWLEDGEBASE dlg_set;
TYPES
FIELDREC IS RECORD
field_entry: STRING;
field_radio: STRING;
field_slide: STRING;
field_list: STRING;
field_button: STRING;
field_check_box: STRING;
field_mle: STRING;
field_combo: STRING;
field_pattern: STRING;
test_list_box: STRING;
test_combo_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
fieldList IS { 'attrib_field_entry',
'attrib_field_radio',
'attrib_field_slide',
'attrib_field_list',
'attrib_field_button',
'attrib_field_check_box',
'attrib_field_mle',
'attrib_field_combo',
'attrib_field_pattern'
}: LIST OF STRING;
textFieldList IS { 'attrib_field_entry',
'attrib_field_mle',
'attrib_field_combo',
'attrib_field_pattern'
}: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
ACTIONS
WHEN $Event IS $MsgSelect THEN
WHEN $FieldName IS 'but_disabled_on' THEN
DlgSetEnabled( $Handle, fieldList, FALSE );
ELSWHEN 'but_disabled_off' THEN
DlgSetEnabled( $Handle, fieldList, TRUE );
ELSWHEN 'but_hidden_on' THEN
DlgSetHidden( $Handle, fieldList, TRUE );
ELSWHEN 'but_hidden_off' THEN
DlgSetHidden( $Handle, fieldList, FALSE );
ELSWHEN 'but_mandatory_on' THEN
DlgSetMandatory( $Handle, textFieldList, TRUE );
ELSWHEN 'but_mandatory_off' THEN
DlgSetMandatory( $Handle, textFieldList, FALSE );
ELSWHEN 'but_read_only_on' THEN
DlgSetReadOnly( $Handle, textFieldList, TRUE );
ELSWHEN 'but_read_only_off' THEN
DlgSetReadOnly( $Handle, textFieldList, FALSE );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlg_set',
DlgEvent );
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $mbok +
$MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog box );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgSetFieldValue

Description

Sets the value of a dialog box control and any associated instance data.

Syntax

FUNCTION DlgSetFieldValue(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL newValue: ANY): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
newValue The addressed control is set to the value of the parameter:

If the control is a check box, option button, or slider the new value is converted to an integer and the control is set to the resulting value. If the conversion fails, the result is normally zero.

For check boxes, zero is unchecked. Any other values are checked.

For all other control types, the value is converted to a string.

For text boxes, combo boxes, list boxes, and messages, the control is set to the new string.

For list boxes, the list is searched for a matching string. If a match is found, it is selected.

SQLManage and table controls are ignored. If the control is successfully updated and there is a field of the instance data bound to the dialog box control, the instance data is updated. Setting a field value generates a select message for the field.

Notes

Setting a control's value generates a $MsgSelect. If the value of the control is changed, $MsgInitialize is generated.
The $MsgSelect may be refused by the dialog box event handler.

Trimming White Space

White space is trimmed from a dialog box control if all spaces in the control are empty. This may occur if the
user enters a string of empty spaces in the control or if the dialog box specification file contains an
empty string for the control. In either case, if the value of the empty control is requested, $Unknown is returned.

Example

KNOWLEDGEBASE DlgSet_f;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
(* ******* PRIVATE *********)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: DLGDATA ) IS
ACTIONS
(* All dialog box messages have pseudo parameters $FieldID,and $FieldName*)
WHEN $Event IS $MsgCreate THEN
(* Select initial field for cursor *)
DlgSetFieldValue( $Handle, 'messageField',
'New text' );
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]', DlgEvent{ fields },fields );
END;

Return Codes

See Also

DlgFieldValue

------------------------------------------------------------------------

DlgSetHidden

Description

Sets the visible or hidden state of a control.

Syntax

FUNCTION DlgSetHidden(VAL whdlDialog: WINDOW,
VAL fieldNames: LIST OF STRING [,
VAL newState: BOOLEAN ]): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The command is performed for every control name in the list. The number of controls processed is returned. Processing stops when an error is encountered. The system variable $DlgError is set to the error code. If an error occurs on the first control processed, the error code is returned by the statement.
newState The new state of the control. This parameter is optional. If omitted, TRUE is assumed.


Example

KNOWLEDGEBASE dlg_set;
TYPES
FIELDREC IS RECORD
field_entry: STRING;
field_radio: STRING;
field_slide: STRING;
field_list: STRING;
field_button: STRING;
field_check_box: STRING;
field_mle: STRING;
field_combo: STRING;
field_pattern: STRING;
test_list_box: STRING;
test_combo_box: STRING;
END;
ROUTINES
EVENT DlgEvent( REF fields: FIELDREC );
PROCEDURE ExampleDialog;
PRIVATE
CONSTANTS
fieldList IS
{ 'attrib_field_entry',
'attrib_field_radio',
'attrib_field_slide',
'attrib_field_list',
'attrib_field_button',
'attrib_field_check_box',
'attrib_field_mle',
'attrib_field_combo',
'attrib_field_pattern'
}: LIST OF STRING;
textFieldList IS { 'attrib_field_entry',
'attrib_field_mle',
'attrib_field_combo',
'attrib_field_pattern'
}: LIST OF STRING;
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: FIELDREC ) IS
ACTIONS
WHEN $Event IS $MsgSelect THEN
WHEN $FieldName IS 'but_disabled_on' THEN
DlgSetEnabled( $Handle, fieldList, FALSE );
ELSWHEN 'but_disabled_off' THEN
DlgSetEnabled( $Handle, fieldList, TRUE );
ELSWHEN 'but_hidden_on' THEN
DlgSetHidden( $Handle, fieldList, TRUE );
ELSWHEN 'but_hidden_off' THEN
DlgSetHidden( $Handle, fieldList, FALSE );
ELSWHEN 'but_mandatory_on' THEN
DlgSetMandatory( $Handle, textFieldList, TRUE );
ELSWHEN 'but_mandatory_off' THEN
DlgSetMandatory( $Handle, textFieldList, FALSE );
ELSWHEN 'but_read_only_on' THEN
DlgSetReadOnly( $Handle, textFieldList, TRUE );
ELSWHEN 'but_read_only_off' THEN
DlgSetReadOnly( $Handle, textFieldList, FALSE );
END;
END;
END;
PROCEDURE ExampleDialog IS
VARIABLES
whdlDialog: WINDOW;
result: INTEGER;
ACTIONS
result := DlgCreate( $Desktop, whdlDialog, 'dlg_set',
DlgEvent );
IF result < 1 THEN
WinMessageBox( $Desktop, 'Error', $mbok + $MBIconError,
'dialog box Open failed' & result );
END;
WinWait( whdlDialog);
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgSetListBoxIndex

Description

Selects an item or items in a list box or table control by its index or indices.

Syntax

FUNCTION DlgSetListBoxIndex(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL newIndex:INTEGER | INTEGER
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive.
newIndex The 1-based index of the item to be selected. 0 is returned if the index is out of range. All the items in a list are selected if a list of integers is passed in and the control is capable of multiple selections.


Notes

Setting the list box index to a new value causes $MsgSelect (or $MsgInitialize) to be sent. The message is sent even if
the value at the new index is the same as the value at the old index.

Note: Setting the index to 0 deselects all items in a standard list box but not a table control.

Example

DlgSetListBoxIndex($Handle,'USER_LIST',5);

Return Codes

See Also

------------------------------------------------------------------------

DlgSetMandatory

Description

Sets the mandatory state of a control.

Syntax

FUNCTION DlgSetMandatory(VAL whdlDialog: WINDOW,
VAL fieldNames: LIST OF STRING,
VAL newState: BOOLEAN): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The command is performed for every control name in the list. The number of controls processed is returned. Processing stops when an error is encountered. The system variable $DlgError is set to the error code. If an error occurs on the first control processed, the error code is returned by the statement.
newState The new state of the control. This parameter is optional. If omitted, TRUE is assumed.


Notes

You can use DlgSetMandatory to change the mandatory state of a dialog box control. For instance, if a control
is not mandatory, but is under certain circumstances, you could use the statement DlgSetMandatory ($Handle,'THAT_FIELD',TRUE);
in the dialog box event handler for the dialog box to make the control mandatory. The Tivoli Service Desk Developer's Toolkit
dialog box system does not allow you to accept a dialog box with empty, mandatory fields. You receive an error message
and the cursor is in the first empty mandatory control.

Example

DlgSetMandatory ($Handle,'SOCIAL_SECURITY_NUMBER',TRUE);

Return Codes

See Also

------------------------------------------------------------------------

DlgSetReadOnly

Description

Sets the read-only state of a dialog box control.

Syntax

FUNCTION DlgSetReadOnly(VAL whdlDialog: WINDOW, VAL
fieldNames: LIST OF STRING [,
VAL newState: BOOLEAN ]): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The command is performed for every control name in the list. The number of controls processed is returned. Processing stops when an error is encountered. The system variable $DlgError is set to the error code. If an error occurs on the first control processed, the error code is returned by the statement.
newState The new state of the control. This parameter is optional. If omitted, TRUE is assumed.


Notes

DlgSetReadOnly allows you to change the read-only state of a dialog box control. For instance, you can make
a control read-only if the current user doesn't have the security necessary to modify the control's value.

Note: The types of fields that can be made read-only are: list boxes, text boxes, and combo boxes.

Example

KNOWLEDGEBASE Dlg_But;
TYPES
DlgData IS RECORD
allowEdit: BOOLEAN;
sampleField: INTEGER;
END;
ROUTINES
PROCEDURE DialogExample;
PRIVATE
ROUTINES
EVENT DlgEvent(REF fields: DlgData) IS
ACTIONS
WHEN $Event IS $MsgCreate THEN
IF NOT fields.allowEdit THEN
DlgSetButtonText($Handle,'editButton','View');
(* SAMPLEFIELD must be a MLE, entry field or combo box *)
DlgSetReadonly($Handle,'SAMPLEFIELD',TRUE);
END;
END;
END (* Dlg Event *);
PROCEDURE DialogExample IS
VARIABLES
fields: DlgData;
ACTIONS
fields.allowEdit := FALSE;
DlgBox($Desktop,'example[dialog1]',
DlgEvent{fields},fields);
END (* dialog box Example *);

Return Codes

See Also

------------------------------------------------------------------------

DlgSQLSelect

Description

Issues an SQL Select statement and fills a SQLManage with the resulting table.

Syntax

FUNCTION DlgSqlSelect(VAL whdlDialog: WINDOW,
VAL fieldName: STRING,
VAL selectString: STRING, VAL
StripHyperlinks: BOOLEAN): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box that contains the control on which to operate. If the command is issued from an event handler that contains the control, the pseudo parameter $Handle may be used.
fieldName The name of the control in the dialog box that is addressed by the command. This may be specified in the Interface Designer or in the DEFINE statement of the dialog box specification file. The name is case-insensitive. The control must be an SQLManage control.
selectString The parameter must be a correctly formatted SQL Select statement. The SQL Select statement is passed to the SQL database manager. If the Select is successful, the SQLManage is cleared and all records from the select are inserted into the field.
StringHyperlinks Reduces a hypertext string to only the button name in brackets. Any text before or after the hypertext string is unaffected.
UseHypertextFilter The current doc for DlgSqlSelect gives information for only Three input variables. However, various uses of this command in the EA application indicate there are 4. The forth variable appears to be a boolean. This needs to be documented as to what it is and its use.


Notes

An SQLManage in OS/2 may contain up to 65,535 records. In Windows, a SQLManage may contain the following:

* 64K of data per row

* 256 bytes per column per row

* 256 columns per row.

If the DlgSQLSelect statement generates an SQL error, the SQL error is returned.

Example

KNOWLEDGEBASE DlgSQL;
TYPES
DLGDATA IS RECORD
sampleField: INTEGER;
END;
(* ******* PRIVATE ******** *)
PRIVATE
ROUTINES
(* ******** dialog box EVENT HANDLER *********)
EVENT DlgEvent( REF fields: DLGDATA ) IS
VARIABLES
selectString: STRING;
ACTIONS
(* All dialog box messages have pseudo parameters $FieldID, and $FieldName*)
WHEN $Event IS $MsgChar THEN
WHEN $KeyCode IS $KeyAltS THEN (* Look for Alt-S *)
(* Prompt user for text to insert *)
IF WinEditField( $Desktop, selectString, 0, 0, 30,
'Enter new SQL select statement',
$WinAutoPos + $WinBorder +
$WinTitle ) > 0
THEN
DlgSQLSelect( $Handle, 'sql_manage_field',
selectString );
END;
END;
END;
END;
PROCEDURE DialogExample IS
VARIABLES
fields: DLGDATA;
ACTIONS
DlgBox( $Desktop,'example[dialog1]',
DlgEvent{ fields }, fields );
END;

Return Codes

See Also

------------------------------------------------------------------------

DlgTurnToPage

Description

Changes the present tab in a tabbed dialog box to the chosen tab.

Syntax

FUNCTION DlgTurnToPage( VAL whdlDialog: WINDOW,
VAL Notebook : STRING,
VAL page: INTEGER ): INTEGER;
Argument Notes Argument Name Description
whdlDialog The window handle of the dialog box containing the notebook.
notebook The name of the tabbed dialog box where the action is performed. This name is set when the form is created with the Interface Designer utility.
page An integer representing the number of the tab to turn to. The first tab is 1; the second 2, and so on.

Example

(* This example puts up a tabbed dialog box and, upon creation, changes the tab to tab 2; tab 2 would be the first tab the user sees. *)

KNOWLEDGEBASE Notebook;
ROUTINES
PROCEDURE MainProgram;
TYPES
record1 is RECORD
MLE1: String;
END;
PRIVATE
ROUTINES
EVENT WinEvent(REF rec: record1) IS
ACTIONS
WHEN $Event IS $MsgAccept THEN
Nothing;
ELSWHEN $MsgCreate THEN
DlgTurnToPage( $Handle, 'MyNotebook', 2);
END;
END;
PROCEDURE MainProgram IS
VARIABLES
rec: record1;
ACTIONS
DlgBox($Desktop, 'notebook[nbForm]',
WinEvent{rec}, rec);
END;
END;

------------------------------------------------------------------------

DlgWinCreate

Description

Creates a generic window or scroll window in an existing subform. Messages for the window are passed
to the specified event handler, not the dialog event handler. (The dialog event handler may filter some key
messages generated by the routine that traverses the keyboard.) If DlgWinCreate is called on a "non-empty" subform, it replaces the existing subform.

Syntax

FUNCTION DlgWinCreate( VAL form : WINDOW,
VAL subform : STRING,
REF win : WINDOW,
VAL eventHandler : EVENT,
VAL style : INTEGER
VAL scrollWindow : BOOLEAN
) : INTEGER;
Argument Notes Argument Name Description
form The name of the form.
subform ID of the subform control.
win The window in the existing subform.
eventHandler An event handler that processes events generated by the window or dialog box. If no event processing is required, the keyword $NullHandler can be used.
style An integer bit mask that represents a set of style flags used to control the window's appearance. For a list of the available style flags, see Window Styles.
scrollwindow If TRUE, a scroll window is created.


Notes

Not all functions work on the handle returned from this call. Unsupported functions fail because of a bad handler error
or general failure. The following functions do not work on windows created by DlgWinCreate:

Return Codes

See Also

Return to Main Page


Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Language Reference

Return to Main Page

Copyright