Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
------------------------------------------------------------------------
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.
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.
$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.
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;
------------------------------------------------------------------------
Indicates the key pressed by the user when a $MsgChar event occurs.
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.
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;
Also see Key Codes.
------------------------------------------------------------------------
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.
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 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. |
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].
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.
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.
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.
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.
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.
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 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. |
For information on creating dialog box specification files, see the Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.
------------------------------------------------------------------------
Creates a modeless dialog box from a dialog box specification file.
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. |
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.
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.
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.
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.
Unless otherwise noted, the first two event parameters of all dialog box messages are:
For more information on creating dialog box specification files, see the
Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.
------------------------------------------------------------------------
Loads a subform from a form file and displays it in the context of an existing dialog form.
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. |
WHEN $Event IS $MsgCreate THEN
DlgCreateSubForm($Handle, instanceData.theSubForm, 'screens[theSubForm]', SubFormHandler, 3, 50);
END;
For more information on creating dialog box specification files, see the Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer's Guide.
------------------------------------------------------------------------
Removes an existing page from a notebook on an existing form.
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) |
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;
------------------------------------------------------------------------
Queries the value of a dialog box control.
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. |
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.
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;
------------------------------------------------------------------------
Queries the current text of a button.
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. |
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;
------------------------------------------------------------------------
Retrieves the selected text from a text box in a dialog box.
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. |
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;
------------------------------------------------------------------------
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.
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. |
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;
------------------------------------------------------------------------
Inserts a string at the cursor location in a text box, list box, or combo box.
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. |
Selected text is replaced by the inserted text.
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;
------------------------------------------------------------------------
Allows you to query whether a dialog control is enabled or disabled.
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. |
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;
------------------------------------------------------------------------
Clears all values from any text box, SQLManage, or table control.
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. |
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.
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;
------------------------------------------------------------------------
Deletes the selected element from any text box, SQLManage, or table control.
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. |
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.
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;
------------------------------------------------------------------------
Queries the index of the selected item of a list box, SQLManage, or table control.
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. |
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;
------------------------------------------------------------------------
Inserts a value into any text box, SQLManage, or table control.
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. |
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;
------------------------------------------------------------------------
Updates the selected value of an SQLManage or a table control.
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. |
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;
------------------------------------------------------------------------
Loads a form from a .df file into an existing subform control. (Any existing form is replaced.)
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. |
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;
------------------------------------------------------------------------
Queries the declared columns of an SQLManage or a table control.
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. |
As shown in this example, WinWriteLN writes the entire list of strings sequentially.
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;
------------------------------------------------------------------------
Queries the number of items that are currently contained in a list box, combo box, table control, or SQLManage.
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. |
This function works only with controls that contain lists of data (a list box, combo box, table control, or SQLManage).
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;
------------------------------------------------------------------------
Queries the contents of a given row for a list box, combo box, or table.
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. |
This function works only with controls that hold lists of data (that is, a list box, combo box, or table).
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;
------------------------------------------------------------------------
Moves the cursor to the specified control.
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. |
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.
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;
------------------------------------------------------------------------
Changes the label on a button.
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. |
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 *);
------------------------------------------------------------------------
Sets the enabled or disabled status of a control.
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. |
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;
------------------------------------------------------------------------
Sets the value of a dialog box control and any associated instance data.
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. |
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.
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.
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;
------------------------------------------------------------------------
Sets the visible or hidden state of a control.
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. |
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;
------------------------------------------------------------------------
Selects an item or items in a list box or table control by its index or indices.
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. |
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.
DlgSetListBoxIndex($Handle,'USER_LIST',5);
------------------------------------------------------------------------
Sets the mandatory state of a control.
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. |
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.
DlgSetMandatory ($Handle,'SOCIAL_SECURITY_NUMBER',TRUE);
------------------------------------------------------------------------
Sets the read-only state of a dialog box control.
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. |
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.
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 *);
------------------------------------------------------------------------
Issues an SQL Select statement and fills a SQLManage with the resulting table.
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. |
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.
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;
------------------------------------------------------------------------
Changes the present tab in a tabbed dialog box to the chosen tab.
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. |
(* 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;
------------------------------------------------------------------------
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.
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. |
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:
Tivoli Service Desk 6.0 Developer's Toolkit TSD Script Language Reference