Common Desktop Environment: Desktop KornShell User's Guide

Appendix A
dtksh Commands

This appendix contains a list of the commands supported by dtksh. Many of these commands are almost identical to their Motif, Xt Intrinsics, or Xlib counterparts. Commands that return a value must have the return variable as an environment variable that is the first parameter in the call. Some commands have more differences.

The following subsections give a synopsis of each of the dtksh commands. In general, parameter ordering and types are the same as for corresponding C procedures; exceptions are noted. For more detail on the functionality and parameters of a command, see the standard documentation for the corresponding Xlib, Xt Intrinsics, or Motif procedure.

In the command definitions, parameters named var, var2, var3, and so on, indicate that the shell script should supply the name of an environment variable into which some value will be returned. The word variable indicates an environment variable that accepts a return value.

Commands that return a Boolean value (which can be used directly as part of an if statement), are noted as such.

Parameters enclosed within [] are optional.

Built-in Xlib Commands

XBell display volume

XClearArea display drawable [optional GC arguments] x y width height exposures

XClearWindow display drawable

XCopyArea display src dest srcX srcY width height destX destY [optional GC arguments]

XDefineCursor display window cursor

XDrawArc display drawable [optional GC arguments] x y width height angle1 angle2

XDrawLine display drawable [optional GC arguments] x1 y1 x2 y2

XDrawLines display drawable [-coordinateMode] [optional GC arguments] x1 y1 x2 y2 [x3 y3 ...
where coordinateMode is either CoordModeOrigin or CoordModePrevious.

XDrawPoint display drawable [optional GC arguments] x y

XDrawPoints display drawable [-coordinateMode] [optional GC arguments] x1 y1 [x2 y2 x3 y3 ...]
where coordinateMode is either CoordModeOrigin or CoordModePrevious.

XDrawRectangle display drawable [optional GC arguments] x y width height

XDrawSegments display drawable [optional GC arguments] x1 y1 x2 y2 [x3 y3 x4 y4 ...]

XDrawString display drawable [optional GC arguments] x y string

XDrawImageString display drawable [optional GC arguments] x y string

XFillArc display drawable [optional GC arguments] x y width height angle1 angle2

XFillPolygon display drawable [-shape] [-coordinateMode] [optional GC arguments] x1 y1 x2 y2 ...
where shape is either Complex, Convex, or Nonconvex, and coordinateMode is either CoordModeOrigin or CoordModePrevious.

XFillRectangle display drawable [optional GC arguments] x y width height

XFlush display

XHeightOfScreen variable screen

XRaiseWindow display window

XRootWindowOfScreen variable screen

XSync display discard
where discard is either true or false.

XTextWidth variable fontName string

Note: The XTextWidth command is different from the corresponding Xlib procedure because it takes the name of a font instead of a pointer to a font structure.
XUndefineCursor display window

XWidthOfScreen variable screen

Built-in Xt Intrinsic Commands

All the Xt Intrinsics commands used to create a new widget require that you specify a widget class for the new widget. The widget (or gadget) class name is the standard class name provided by Motif. For example, the class name for a Motif push button widget is XmPushButton, while the class name for the Motif label gadget is XmLabelGadget.

XtAddCallback widgetHandle callbackName ksh-command
where callbackName is one of the standard Motif or Xt callback names, with the Xt or Xm prefix dropped. For example, activateCallback.

XtAddEventHandler widgetHandle eventMask nonMaskableFlag ksh-command
where eventMask is of the form mask|mask|mask and the mask components are any of the standard set of X event masks, and nonMaskableFlag is either true or false.

XtAddInput variable [-r] fileDescriptor ksh-command
Registers the indicated file descriptor with the X Toolkit as an alternate input source. It is the responsibility of the shell script's input handler to unregister the input source when it is no longer needed and to close the file descriptor.

If the -r option is specified (raw mode), then dtksh does not automatically read any of the data available from the input source; it will be up to the specified kshell command to read all data. If the -r option is not specified, then the command specified in ksh-command is invoked only when a full line is read (that is, a line terminated by either an unescaped newline character or the end of the file) or when the end of the file is reached. The raw mode is useful for handlers that expect to process nontextual data, or for handlers that do not want dtksh automatically reading in a line of data. When the end of file is detected, it is the shell script's input handler's responsibility to use XtRemoveInput to remove the input source and to close the file descriptor, if necessary.

In all cases, several environment variables are set up, which can be used by the handler. These include:

INPUT_LINE
Empty if in raw mode; otherwise, it contains the next line to be processed.

INPUT_EOF
Set to true if end-of-file is reached; otherwise, set to false.

INPUT_SOURCE
File descriptor associated with this input source.

INPUT_ID
The ID associated with this input handler; returned by XtAddInput().

XtAddTimeout variable interval ksh-command

XtAddWorkProc variable ksh-command
In dtksh, the kshell command is typically a kshell function name. Like regular work procedures, this function is expected to return a value that indicates whether the work procedure wants to be called again, or whether it has completed its work and can be automatically unregistered. If the dtksh function returns 0, then the work procedure remains registered; any other value causes the work procedure to be automatically unregistered.

XtAugmentTranslations widgetHandle translations

XtCreateApplicationShell variable applicationName widgetClass [resource:value ...]

XtCallCallbacks widgetHandle callbackName
where callbackName is one of the standard Motif or Xt callback names, with
the Xt or Xm prefix dropped; for example, activateCallback.

XtClass variable widgetHandle
Returns the name of the widget class associated with the passed-in widget handle.

XtCreateManagedWidget variable widgetName widgetClass parentWidgetHandle [resource:value ...]

XtCreatePopupShell variable widgetName widgetClass parentWidgetHandle [resource:value ...]

XtCreateWidget variable widgetName widgetClass parentWidgetHandle [resource:value ...]

XtDestroyWidget widgetHandle [widgetHandle ...]

XtDisplay variable widgetHandle

XtDisplayOfObject variable widgetHandle

XtGetValues widgetHandle resource:var1 [resource:var2 ...]

XtHasCallbacks variable widgetHandle callbackName
where callbackName is one of the standard Motif or Xt callback names, with the Xt or Xm prefix dropped; for example, activateCallback.

variable is set to one of the strings CallbackNoList, CallbackHasNone, or CallbackHasSome.

XtInitialize variable shellName applicationClassName applicationName [arguments]
Using Dtksh as the applicationClassName causes the application to use the default dtksh app-defaults file. The arguments parameter is used to reference any command-line arguments that might have been specified by the user of the shell script; these are typically referred to using the shell syntax of "$@".

Returns a value which can be used in a conditional statement.

XtIsManaged widgetHandle
Returns a value which can be used in a conditional statement.

XtIsSubclass widgetHandle widgetClass
where widgetClass is the name of a widget class. Returns a value which can be used in a conditional statement.

XtNameToWidget variable referenceWidget name

XtIsRealized widgetHandle
Returns a value which can be used in a conditional statement.

XtIsSensitive widgetHandle
Returns a value which can be used in a conditional statement.

XtIsShell widgetHandle
eturns a value which can be used in a conditional statement.

XtLastTimestampProcessed variable display

XtMainLoop

XtManageChild widgetHandle

XtManageChildren widgetHandle [widgetHandle ...]

XtMapWidget widgetHandle

XtOverrideTranslations widgetHandle translations

XtParent variable widgetHandle

XtPopdown widgetHandle

XtPopup widgetHandle grabType
where grabType is one of the strings GrabNone, GrabNonexclusive or GrabExclusive.

XtRealizeWidget widgetHandle

XtRemoveAllCallbacks widgetHandle callbackName
where callbackName is one of the standard Motif or Xt callback names, with the Xt or Xm prefix dropped; for example, activateCallback

XtRemoveCallback widgetHandle callbackName ksh-command
where callbackName is one of the standard Motif or Xt callback names, with the Xt or Xm prefix dropped; for example, activateCallback. As is true with traditional Xt callbacks, when a callback is removed, the same kshell command string must be specified as was specified when the callback was originally registered.

XtRemoveEventHandler widgetHandle eventMask nonMaskableFlag ksh-command
where eventMask is of the form mask|mask|mask and the mask components are any of the standard set of X event masks; that is. ButtonPressMask where nonMaskableFlag is either true or false.

As is true with traditional Xt event handlers, when an event handler is removed, the same eventMask, nonMaskableFlag setting, and kshell command string must be specified as was specified when the event handler was originally registered.

XtRemoveInput inputId
where inputId is the handle that was returned in the specified environment variable when the alternate input source was registered using the XtAddInput command.

XtRemoveTimeOut timeoutId
where timeoutId is the handle that was returned in the specified environment variable when the timeout was registered using the XtAddTimeOut command.

XtRemoveWorkProc workprocID
where workprocID is the handle that was returned in the specified environment variable when the work procedure was registered using the XtAddWorkProc command.

XtScreen variable widgetHandle

XtSetSensitive widgetHandle state
where state is either true or false.

XtSetValues widgetHandle resource:value [resource:value ...]

XtUninstallTranslations widgetHandle

XtUnmanageChild widgetHandle

XtUnmanageChildren widgetHandle [widgetHandle ...]

XtUnmapWidget widgetHandle

XtUnrealizeWidget widgetHandle

XtWindow variable widgetHandle

Built-in Motif Commands

XmAddWMProtocolCallback widgetHandle protocolAtom ksh-command
where protocolAtom is typically obtained using the XmInternAtom command.

XmAddWMProtocols widgetHandle protocolAtom [protocolAtom ...]
where protocolAtom is typically obtained using the XmInternAtom command.

XmCommandAppendValue widgetHandle string

XmCommandError widgetHandle errorString

XmCommandGetChild variable widgetHandle childType
where childType is one of the strings DIALOG_COMMAND_TEXT, DIALOG_PROMPT_LABEL, DIALOG_HISTORY_LIST, or DIALOG_WORK_AREA.

XmCommandSetValue widgetHandle commandString

XmCreateArrowButton variable parentWidgetHandle name [resource:value ...]

XmCreateArrowButtonGadget variable parentWidgetHandle name [resource:value ...]

XmCreateBulletinBoard variable parentWidgetHandle name [resource:value ...]

XmCreateBulletinBoardDialog variable parentWidgetHandle name [resource:value ...]

XmCreateCascadeButton variable parentWidgetHandle name [resource:value ...]

XmCreateCascadeButtonGadget variable parentWidgetHandle name [resource:value ...]

XmCreateCommand variable parentWidgetHandle name [resource:value ...]

XmCreateDialogShell variable parentWidgetHandle name [resource:value ...]

XmCreateDrawingArea variable parentWidgetHandle name [resource:value ...]

XmCreateDrawnButton variable parentWidgetHandle name [resource:value ...]

XmCreateErrorDialog variable parentWidgetHandle name [resource:value ...]

XmCreateFileSelectionBox variable parentWidgetHandle name [resource:value ...]

XmCreateFileSelectionDialog variable parentWidgetHandle name [resource:value ...]

XmCreateForm variable parentWidgetHandle name [resource:value ...]

XmCreateFormDialog variable parentWidgetHandle name [resource:value ...]

XmCreateFrame variable parentWidgetHandle name [resource:value ...]

XmCreateInformationDialog variable parentWidgetHandle name [resource:value ...]

XmCreateLabel variable parentWidgetHandle name [resource:value ...]

XmCreateLabelGadget variable parentWidgetHandle name [resource:value ...]

XmCreateList variable parentWidgetHandle name [resource:value ...]

XmCreateMainWindow variable parentWidgetHandle name [resource:value ...]

XmCreateMenuBar variable parentWidgetHandle name [resource:value ...]

XmCreateMenuShell variable parentWidgetHandle name [resource:value ...]

XmCreateMessageBox variable parentWidgetHandle name [resource:value ...]

XmCreateMessageDialog variable parentWidgetHandle name [resource:value ...]

XmCreateOptionMenu variable parentWidgetHandle name [resource:value ...]

XmCreatePanedWindow variable parentWidgetHandle name [resource:value ...]

XmCreatePopupMenu variable parentWidgetHandle name [resource:value ...]

XmCreatePromptDialog variable parentWidgetHandle name [resource:value ...]

XmCreatePulldownMenu variable parentWidgetHandle name [resource:value ...]

XmCreatePushButton variable parentWidgetHandle name [resource:value ...]

XmCreatePushButtonGadget variable parentWidgetHandle name [resource:value ...]

XmCreateQuestionDialog variable parentWidgetHandle name [resource:value ...]

XmCreateRadioBox variable parentWidgetHandle name [resource:value ...]

XmCreateRowColumn variable parentWidgetHandle name [resource:value ...]

XmCreateScale variable parentWidgetHandle name [resource:value ...]

XmCreateScrollBar variable parentWidgetHandle name [resource:value ...]

XmCreateScrolledList variable parentWidgetHandle name [resource:value ...]

XmCreateScrolledText variable parentWidgetHandle name [resource:value ...]

XmCreateScrolledWindow variable parentWidgetHandle name [resource:value ...]

XmCreateSelectionBox variable parentWidgetHandle name [resource:value ...]

XmCreateSelectionDialog variable parentWidgetHandle name [resource:value ...]

XmCreateSeparator variable parentWidgetHandle name [resource:value ...]

XmCreateSeparatorGadget variable parentWidgetHandle name [resource:value ...]

XmCreateText variable parentWidgetHandle name [resource:value ...]

XmCreateTextField variable parentWidgetHandle name [resource:value ...]

XmCreateToggleButton variable parentWidgetHandle name [resource:value ...]

XmCreateToggleButtonGadget variable parentWidgetHandle name [resource:value ...]

XmCreateWarningDialog variable parentWidgetHandle name [resource:value ...]

XmCreateWorkArea variable parentWidgetHandle name [resource:value ...]

XmCreateWorkingDialog variable parentWidgetHandle name [resource:value ...]

XmFileSelectionDoSearch widgetHandle directoryMask

XmFileSelectionBoxGetChild variable widgetHandle childType
where childType is one of the strings DIALOG_APPLY_BUTTON, DIALOG_CANCEL_BUTTON, DIALOG_DEFAULT_BUTTON, DIALOG_DIR_LIST, DIALOG_DIR_LIST_LABEL, DIALOG_FILTER_LABEL, DIALOG_FILTER_TEXT, DIALOG_HELP_BUTTON, DIALOG_LIST, DIALOG_LIST_LABEL, DIALOG_OK_BUTTON, DIALOG_SEPARATOR, DIALOG_SELECTION_LABEL, DIALOG_TEXT, or DIALOG_WORK_AREA.

XmGetAtomName variable display atom

XmGetColors widgetHandle background variable var2 var3 var4
The XmGetColors command differs from the C procedure in that it takes a widgetHandle instead of a screen pointer and a colormap.

XmGetFocusWidget variable widgetHandle

XmGetPostedFromWidget variable widgetHandle

XmGetTabGroup variable widgetHandle

XmGetTearOffControl variable widgetHandle

XmGetVisibility variable widgetHandle

XmInternAtom variable display atomString onlyIfExistsFlag
where onlyIfExistsFlag can be set to either true or false.

XmIsTraversable widgetHandle
Returns a value which can be used in a conditional statement.

XmListAddItem widgetHandle position itemString
The order of the parameters for the XmListAddItem command is not identical to its corresponding C programming counterpart.

XmListAddItems widgetHandle position itemString [itemString ...]
The order of the parameters for the XmListAddItems command is not identical to its corresponding C programming counterpart.

XmListAddItemsUnselected widgetHandle position itemString [itemString ...]
The order of the parameters for the XmListAddItemsUnselected command is not identical to its corresponding C programming counterpart.

XmListAddItemUnselected widgetHandle position itemString
The ordering of the parameters to the XmListAddItemUnselected command are not identical to its corresponding C programming counterpart.

XmListDeleteAllItems widgetHandle

XmListDeleteItem widgetHandle itemString

XmListDeleteItems widgetHandle itemString [itemString ...]

XmListDeleteItemsPos widgetHandle itemCount position

XmListDeletePos widgetHandle position

XmListDeletePositions widgetHandle position [position ...]

XmListDeselectAllItems widgetHandle

XmListDeselectItem widgetHandle itemString

XmListDeselectPos widgetHandle position

XmListGetSelectedPos variable widgetHandle
Returns a comma-separated list of indices in variable. Returns a value which can be used in a conditional statement.

XmListGetKbdItemPos variable widgetHandle

XmListGetMatchPos variable widgetHandle itemString
Returns a comma-separated list of indices in variable. Returns a value which can be used in a conditional statement.

XmListItemExists widgetHandle itemString
Returns a value which can be used in a conditional statement.

XmListItemPos variable widgetHandle itemString

XmListPosSelected widgetHandle position
Returns a value which can be used in a conditional statement.

XmListPosToBounds widgetHandle position variable var2 var3 vari4
Returns a value which can be used in a conditional statement.

XmListReplaceItemsPos widgetHandle position itemString [itemString ...]
The order of the parameters for the XmListReplaceItemsPos command is not identical to its corresponding C programming counterpart.

XmListReplaceItemsPosUnselected widgetHandle position itemString [itemString ...]
The order of the parameters for the XmListReplaceItemsPosUnselected command is not identical to its corresponding C programming counterpart.

XmListSelectItem widgetHandle itemString notifyFlag
where notifyFlag can be set to either true or false.

XmListSelectPos widgetHandle position notifyFlag
where notifyFlag can be set to either true or false.

XmListSetAddMode widgetHandle state
where state can be set to either true or false.

XmListSetBottomItem widgetHandle itemString

XmListSetBottomPos widgetHandle position

XmListSetHorizPos widgetHandle position

XmListSetItem widgetHandle itemString

XmListSetKbdItemPos widgetHandle position
Returns a value which can be used in a conditional statement.

XmListSetPos widgetHandle position

XmListUpdateSelectedList widgetHandle

XmMainWindowSep1 variable widgetHandle

XmMainWindowSep2 variable widgetHandle

XmMainWindowSep3 variable widgetHandle

XmMainWindowSetAreas widgetHandle menuWidgetHandle commandWidgetHandle horizontalScrollbarWidgetHandle verticalScrollbarWidgetHandle workRegionWidgetHandle

XmMenuPosition widgetHandle eventHandle
where eventHandle refers to an X event, which has typically been obtained by accessing the CB_CALL_DATA.EVENT, EH_EVENT or TRANSLATION_EVENT environment variables.

XmMessageBoxGetChild variable widgetHandle childType
where childType is one of the strings DIALOG_CANCEL_BUTTON, DIALOG_DEFAULT_BUTTON, DIALOG_HELP_BUTTON, DIALOG_MESSAGE_LABEL, DIALOG_OK_BUTTON, DIALOG_SEPARATOR, or DIALOG_SYMBOL_LABEL.

XmOptionButtonGadget variable widgetHandle

XmOptionLabelGadget variable widgetHandle

XmProcessTraversal widgetHandle direction
where direction is one of the strings TRAVERSE_CURRENT, TRAVERSE_DOWN, TRAVERSE_HOME, TRAVERSE_LEFT, TRAVERSE_NEXT, TRAVERSE_NEXT_TAB_GROUP, TRAVERSE_PREV, TRAVERSE_PREV_TAB_GROUP, TRAVERSE_RIGHT, or TRAVERSE_UP.

Returns a value which can be used in a conditional statement.

XmRemoveWMProtocolCallback widgetHandle protocolAtom ksh-command
where protocolAtom is typically obtained using the XmInternAtom command.

As is true with traditional Window Manager callbacks, when a callback is removed, the same kshell command string must be specified, as was specified when the callback was originally registered.

XmRemoveWMProtocols widgetHandle protocolAtom [protocolAtom ...]
where protocolAtom is typically obtained using the XmInternAtom command.

XmScaleGetValue widgetHandle variable

XmScaleSetValue widgetHandle value

XmScrollBarGetValues widgetHandle variable var2 var3 var4

XmScrollBarSetValues widgetHandle value sliderSize increment pageIncrement
notifyFlagwhere notifyFlag can be set to either true or false.

XmScrollVisible widgetHandle widgetHandle leftRightMargin topBottomMargin

XmSelectionBoxGetChild variable widgetHandle childType
where childType is one of the strings DIALOG_CANCEL_BUTTON, DIALOG_DEFAULT_BUTTON, DIALOG_HELP_BUTTON, DIALOG_APPLY_BUTTON, DIALOG_LIST, DIALOG_LIST_LABEL, DIALOG_OK_BUTTON, DIALOG_SELECTION_LABEL, DIALOG_SEPARATOR, DIALOG_TEXT, or DIALOG_WORK_AREA.

XmTextClearSelection widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

XmTextCopy widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

Returns a value which can be used in a conditional statement.

XmTextCut widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

Returns a value which can be used in a conditional statement.

XmTextDisableRedisplay widgetHandle

XmTextEnableDisplay widgetHandle

XmTextFindString widgetHandle startPosition string direction variable
where direction is one of the strings TEXT_FORWARD or TEXT_BACKWARD.

Returns a value which can be used in a conditional statement.

XmTextGetBaseline variable widgetHandle

XmTextGetEditable widgetHandle
Returns a value which can be used in a conditional statement.

XmTextGetInsertionPosition variable widgetHandle

XmTextGetLastPosition variable widgetHandle

XmTextGetMaxLength variable widgetHandle

XmTextGetSelection variable widgetHandle

XmTextGetSelectionPosition widgetHandle variable var2
Returns a value which can be used in a conditional statement.

XmTextGetString variable widgetHandle

XmTextGetTopCharacter variable widgetHandle

XmTextInsert widgetHandle position string

XmTextPaste widgetHandle
Returns a value which can be used in a conditional statement.

XmTextPosToXY widgetHandle position variable var2
Returns a value which can be used in a conditional statement.

XmTextRemove widgetHandle
Returns a value which can be used in a conditional statement.

XmTextReplace widgetHandle fromPosition toPosition string

XmTextScroll widgetHandle lines

XmTextSetAddMode widgetHandle state
where state can be set to either true or false.

XmTextSetEditable widgetHandle editableFlag
where editableFlag can be set to either true or false.

XmTextSetHighlight widgetHandle leftPosition rightPosition mode
where mode is one of the strings HIGHLIGHT_NORMAL, HIGHLIGHT_SELECTED or HIGHLIGHT_SECONDARY_SELECTED.

XmTextSetInsertionPosition widgetHandle position

XmTextSetMaxLength widgetHandle maxLength

XmTextSetSelection widgetHandle firstPosition lastPosition time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

XmTextSetString widgetHandle string

XmTextSetTopCharacter widgetHandle topCharacterPosition

XmTextShowPosition widgetHandle position

XmTextXYToPos variable widgetHandle x y

XmTextFieldClearSelection widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

XmTextFieldGetBaseline variable widgetHandle

XmTextFieldGetEditable widgetHandle
Returns a value which can be used in a conditional statement.

XmTextFieldGetInsertionPosition variable widgetHandle

XmTextFieldGetLastPosition variable widgetHandle

XmTextFieldGetMaxLength variable widgetHandle

XmTextFieldGetSelection variable widgetHandle

XmTextFieldGetSelectionPosition widgetHandle variable var2
Returns a value which can be used in a conditional statement.

XmTextFieldGetString variable widgetHandle

XmTextFieldInsert widgetHandle position string

XmTextFieldPosToXY widgetHandle position variable var2
Returns a value which can be used in a conditional statement.

XmTextFieldRemove widgetHandle
Returns a value which can be used in a conditional statement.

XmTextFieldReplace widgetHandle fromPosition toPosition string

XmTextFieldSetEditable widgetHandle editableFlag
where editableFlag can be set to either true or false.

XmTextFieldSetHighlight widgetHandle leftPosition rightPosition mode
where mode is one of the strings HIGHLIGHT_NORMAL, HIGHLIGHT_SELECTED, or HIGHLIGHT_SECONDARY_SELECTED.

XmTextFieldSetInsertionPosition widgetHandle position

XmTextFieldSetMaxLength widgetHandle maxLength

XmTextFieldSetSelection widgetHandle firstPosition lastPosition time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

XmTextFieldSetString widgetHandle string

XmTextFieldShowPosition widgetHandle position

XmTextFieldXYToPos variable widgetHandle x y

XmTextFieldCopy widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

Returns a value which can be used in a conditional statement.

XmTextFieldCut widgetHandle time
where time is typically either obtained from within an X Event or is queried by a call to the XtLastTimestampProcessed command.

Returns a value which can be used in a conditional statement.

XmTextFieldPaste widgetHandle
Returns a value which can be used in a conditional statement.

XmTextFieldSetAddMode widgetHandle state
where state can be set to either true or false.

XmToggleButtonGadgetGetState widgetHandle
Returns a value which can be used in a conditional statement.

XmToggleButtonGadgetSetState widgetHandle state notifyFlag
where state can be set to either true or false, and where notifyFlag can be set to either true or false.

XmToggleButtonGetState widgetHandle
Returns a value which can be used in a conditional statement.

XmToggleButtonSetState widgetHandle state notifyFlag
where state can be set to either true or false, and where notifyFlag can be set to either true or false.

XmUpdateDisplay widgetHandle

Built-in Common Desktop Environment Application Help Commands

DtCreateQuickHelpDialog variable parentWidgetHandle name [resource:value ...]

DtCreateHelpDialog variable parentWidgetHandle name [resource:value ...]

DtHelpQuickDialogGetChild variable widgetHandle childType
where childType is one of the strings HELP_QUICK_OK_BUTTON, HELP_QUICK_PRINT_BUTTON, HELP_QUICK_HELP_BUTTON, HELP_QUICK_SEPARATOR, HELP_QUICK_MORE_BUTTON, or HELP_QUICK_BACK_BUTTON.

DtHelpReturnSelectedWidgetId variable widgetHandle var2
variable is set to one of the strings HELP_SELECT_VALID, HELP_SELECT_INVALID, HELP_SELECT_ABORT, or HELP_SELECT_ERROR. var2 is set to the widgetHandle for the selected widget.

DtHelpSetCatalogName catalogName

Built-in Localization Commands

catopen variable catalogName
Opens the indicated message catalog and returns the catalog ID in the environment variable specified by variable. If a shell script needs to close the file descriptor associated with a message catalog, then the catalog ID must be closed using the catclose command.

catgets variable catalogId setNumber messageNumber defaultMessageString
Attempts to extract the requested message string from the message catalog associated with the catalogId parameter. If the message string cannot be located, then the default message string is returned. In either case, the returned message string is placed into the environment variable indicated by variable.

catclose catalogId
Closes the message catalog associated with the indicated catalogId.

Built-in libDt Session Management Commands

DtSessionRestorePath widgetHandle variable sessionFile
Given the file name for the session file (excluding any path information), this command returns the full path for the session file in the environment variable variable.

Returns 0 if successful, 1 if unsuccessful.

DtSessionSavePath widgetHandle variable var2
The full path name for the session file is returned in the environment variable variable. The file name portion of the session file (excluding any path information) is returned in the environment variable indicated by var2.

Returns 0 if successful, 1 if unsuccessful.

DtShellIsIconified widgetHandle
Allows a shell script to query the iconified state of a shell window. Returns 0 if successful, 1 if unsuccessful.

DtSetStartupCommand widgetHandle commandString
Part of the session management process is telling the Session Manager how to restart your application the next time the user reopens the session. This command passes the specified command string to the Session Manager. The widget handle should refer to an application shell.

DtSetIconifyHint widgetHandle iconifyHint
where iconifyHint can be set to either true or false.

Allows the initial iconified state for a shell window to be set. This command only works if the window associated with the widget has been realized but not yet displayed.

Built-in libDt Workspace Management Commands

DtWsmAddCurrentWorkspaceCallback variable widgetHandle ksh-command
Evaluates the specified kshell command whenever the user changes workspaces. The handle associated with this callback is returned in the environment variable indicated by variable. The widget indicated by widgetHandle should be a shell widget.

DtWsmRemoveWorkspaceCallback callbackHandle
Removes a workspace notification callback. When removing a workspace callback, you must pass in the callback handle that was returned when you registered the callback with DtWsmAddCurrentWorkspaceCallback.

DtWsmGetCurrentWorkspace display rootWindow variable
Returns the X atom that represents the user's current workspace in the environment variable indicated by variable. Use the XmGetAtomName command to map the X atom into its string representation.

DtWsmSetCurrentWorkspace widgetHandle workspaceNameAtom
Changes the user's current workspace to the workspace indicated by workspaceNameAtom.

Returns 0 if successful, 1 if unsuccessful.

DtWsmGetWorkspaceList display rootWindow variable
Returns a string of comma-separated X atoms, representing the current set of workspaces defined for the user, in the environment variable indicated by variable.

Returns 0 if successful, 1 if unsuccessful.

DtWsmGetWorkspacesOccupied display window variable
Returns a string of comma-separated X atoms, representing the current set of workspaces occupied by the indicated shell window in the environment variable indicated by variable.

Returns 0 if successful, 1 if unsuccessful.

DtWsmSetWorkspacesOccupied display window workspaceList
Moves the indicated shell window to the set of workspaces indicated by the string workspaceList, which must be a comma-separated list of X atoms.

DtWsmAddWorkspaceFunctions display window
Forces the Window Manager menu to include the functions used to move the window to other workspaces. This command only works if the window is in the withdrawn state.

DtWsmRemoveWorkspaceFunctions display window
Forces the Window Manager menu to not display the functions used to move the window to other workspaces; this prevents the window from being moved to any other workspaces. This command only works if the window is in the withdrawn state.

DtWsmOccupyAllWorkspaces display window
Requests that a window occupy all workspaces, including new workspaces, as they are created.

DtWsmGetCurrentBackdropWindows display rootWindow variable
Returns a string of comma-separated window IDs, representing the set of root backdrop windows.

Built-in libDt Action Commands

The set of commands in this section provide you with the tools for loading the action databases, querying information about actions defined in the databases, and requesting that an action be initiated.

DtDbLoad
Reads in the action and data-types databases. If called multiple times, then the old databases are freed before the new ones are read. This command must be called before any of the other libDt action commands, or any of the libDt data typing commands. The shell script should also use the DtDbReloadNotify command, so that the shell script can be notified if new databases must be loaded.

DtDbReloadNotify ksh-command
Requests notification whenever the action or data-types databases need to be reloaded. The specified kshell command is executed when the notification is received. Typically, the kshell command includes a call to the DtDbLoad command.

DtActionExists actionName
Tests to see if an action exists in the database with the name specified by the actionName parameter. Returns a value which can be used in a conditional statement.

DtActionLabel variable actionName
Returns the localizable LABEL attribute associated with the indicated action. If the action does not exist, then an empty string is returned.

DtActionDescription variable actionName
Returns the value of the DESCRIPTION attribute associated with the indicated action. An empty string is returned if the action is not defined, or if the DESCRIPTION attribute was not specified.

Built-in libDt Data-Typing Commands

DtLoadDataTypes
Loads the data-typing databases and should be invoked before any of the other data-typing commands.

DtDtsFileToDataType variable filePath
Returns the name of the data type associated with the file indicated by the filePath argument in the variable argument. The variable argument is set to an empty string if the file cannot be typed.

DtDtsFileToAttributeValue variable filePath attrName
Returns the string representing the value of the specified attribute for the data type associated with the indicated file. If the attribute is not defined, or if the file could not be typed, then the variable argument is set to an empty string.

DtDtsFileToAttributeList variable filePath
Returns the space-separated list of attribute names defined for the data type associated with the indicated file. A shell script can then query the individual values for the attributes, using the DtDtsFileToAttributeValue command. The variable argument is set to an empty string if the file cannot be typed. This command differs from its corresponding C programming counterpart, in that it only returns the names of the defined attributes and not their values.

DtDtsDataTypeToAttributeValue variable dataType attrName optName
Returns the string representing the value of the specified attribute for the indicated data type. If the attribute is not defined, or if the indicated data type does not exist, then the variable argument is set to an empty string.

DtDtsDataTypeToAttributeList variable dataType optName
Returns the space-separated list of attribute names defined for the indicated data type. A shell script can then query the individual values for the attributes, using the DtDtsDataTypeToAttributeValue command. The variable argument is set to an empty string if the data type is not defined. This command differs from its corresponding C programming counterpart, in that it only returns the names of the defined attributes and not their values.

DtDtsFindAttribute variable name value
Returns a space-separated list of datatype names whose attribute indicated by the name argument has the value indicated by the value argument. If an error occurs, the variable argument is set to an empty string.

DtDtsDataTypeNames variable
Returns a space-separated list representing all the data types currently defined in the data-types database. If an error occurs, then the variable argument is set to an empty string.

DtDtsSetDataType variable filePath dataType override
Sets a data type for the specified directory. The variable argument is set to the resultant saved data type for the directory.

DtDtsDataTypeIsAction dataType
Determines whether a particular data type represents an action entry. Returns a value which can be used in a conditional statement.

Miscellaneous Built-in libDt Commands

DtGetHourGlassCursor variable display
Returns the X cursor ID associated with the standard Dt hourglass cursor.

DtTurnOnHourGlass widgetHandle
Turns on the standard Dt hourglass cursor for the indicated widget.

DtTurnOffHourGlass widgetHandle
Turns off the standard Dt hourglass cursor for the indicated widget.

Built-in Desktop Services Message Set Commands

The following set of commands implements the minimum subset of the Desktop Services Message Set required to allow a shell script to participate in the Desktop Services protocol. Many of the ToolTalk commands differ slightly from their associated C programming call. For ToolTalk commands that typically return a pointer, a C application validates that pointer by calling the tt_ptr_error() function; this function call returns a Tt_status value, which indicates whether the pointer was valid, and if not, why it was not valid. Because of the kshell code's design, the string pointer that the shell script sees is not typically the same as the string pointer returned by the underlying C code. Typically, during shell programming, this is not a problem because the important information is the string value, not the string pointer.

To allow shell scripts to get the status of a pointer, any of the commands that normally return a pointer also return the associated Tt_status value for the pointer automatically. This saves the shell script from needing to make an additional call to check the validity of the original pointer. In the case of a pointer error occurring, dtksh returns an empty string for the pointer value and sets the Tt_status code accordingly.

The Tt_status value is returned in the status argument. The Tt_status value is a string representing the error and can assume any of the following values:

TT_OK
TT_WRN_NOTFOUND
TT_WRN_STALE_OBJID
TT_WRN_STOPPED
TT_WRN_SAME_OBJID
TT_WRN_START_MESSAGE
TT_ERR_CLASS
TT_ERR_DBAVAIL
TT_ERR_DBEXIST
TT_ERR_FILE
TT_ERR_INVALID
TT_ERR_MODE
TT_ERR_ACCESS
TT_ERR_NOMP
TT_ERR_NOTHANDLER
TT_ERR_NUM
TT_ERR_OBJID
TT_ERR_OP
TT_ERR_OTYPE
TT_ERR_ADDRESS
TT_ERR_PATH
TT_ERR_POINTER
TT_ERR_PROCID
TT_ERR_PROPLEN
TT_ERR_PROPNAME
TT_ERR_PTYPE
TT_ERR_DISPOSITION
TT_ERR_SCOPE
TT_ERR_SESSION
TT_ERR_VTYPE
TT_ERR_NO_VALUE
TT_ERR_INTERNAL
TT_ERR_READONLY
TT_ERR_NO_MATCH
TT_ERR_UNIMP
TT_ERR_OVERFLOW
TT_ERR_PTPE_START
TT_ERR_CATEGORY
TT_ERR_DBUPDATE
TT_ERR_DBFULL
TT_ERR_DBCONSIST
TT_ERR_STATE
TT_ERR_NOMEM
TT_ERR_SLOTNAME
TT_ERR_XDR
TT_DESKTOP_EPERM
TT_DESKTOP_ENOENT
TT_DESKTOP_EINTR
TT_DESKTOP_EIO
TT_DESKTOP_EAGAIN
TT_DESKTOP_ENOMEM
TT_DESKTOP_EACCES
TT_DESKTOP_EFAULT
TT_DESKTOP_EEXIST
TT_DESKTOP_ENODEV
TT_DESKTOP_ENOTDIR
TT_DESKTOP_EISDIR
TT_DESKTOP_EINVAL
TT_DESKTOP_ENFILE
TT_DESKTOP_EMFILE
TT_DESKTOP_ETXBSY
TT_DESKTOP_EFBIG
TT_DESKTOP_ENOSPC
TT_DESKTOP_EROFS
TT_DESKTOP_EMLINK
TT_DESKTOP_EPIPE
TT_DESKTOP_ENOMSG
TT_DESKTOP_EDEADLK
TT_DESKTOP_ECANCELED
TT_DESKTOP_ENOTSUP
TT_DESKTOP_ENODATA
TT_DESKTOP_EPROTO
TT_DESKTOP_ENOTEMPTY
TT_DESKTOP_ETIMEDOUT
TT_DESKTOP_EALREADY
TT_DESKTOP_UNMODIFIED
TT_MEDIA_ERR_SIZE
TT_MEDIA_ERR_FORMAT
Some of the commands take a message scope as a parameter. The scope indicates which clients have the potential of receiving the outgoing message. For these commands, the scope parameter can be set to any of the following values:

TT_SCOPE_NONE
TT_SESSION
TT_FILE
TT_BOTH
TT_FILE_IN_SESSION
tt_file_netfile variable status filename
Converts the indicated filename, assumed to be a valid file name on the local host, to its corresponding netfilename format. A netfilename can be passed to other hosts on a network and then converted back to a path relative to the other host, using the tt_netfile_file command.

tt_netfile_file variable status netfilename
Converts the indicated netfilename to a path name that is valid on the local host.

tt_host_file_netfile variable status host filename
Converts the indicated file, assumed to be resident on the specified host, into its corresponding netfilename format.

tt_host_netfile_file variable status host netfilename
Converts the indicated netfilename into a valid path on the indicated host.

ttdt_open variable status var2 toolname vendor version sendStarted
Opens a ToolTalk communications endpoint. It returns in the variable argument the procID associated with this connection. It returns the file descriptor associated with this connection in var2; this file descriptor can be used to register an alternate Xt input handler. The sendStarted argument is a value and if set to true, causes a Started message to be automatically sent.

Any procIDs returned by ttdt_open contain embedded spaces. To prevent kshell from interpreting the procID as a multiple parameter (versus a single parameter with embedded spaces), you should always enclose any references to the environment variable containing the procID within double quotes, as shown:

ttdt_close STATUS "$PROC_ID" "" True

tttk_Xt_input_handler procID source id
For the ToolTalk messages to be received and processed, the shell script must register an Xt input handler for the file descriptor returned by the call to ttdt_open. The Xt input handler is registered using the XtAddInput command, and the handler must be registered as a raw input handler. The input handler that the shell script registers should invoke tttk_Xt_input_handler to get the message received and processed. The following code block demonstrates how this is done:

  ttdt_open PROC_ID STATUS FID "Tool" "HP" "1.0" True XtAddInput
  INPUT_ID -r $FID "ProcessTTInput \"$PROC_ID\""

  ProcessTTInput() 

  { 
    tttk_Xt_input_handler $1 $INPUT_SOURCE $INPUT_ID 
  }
Refer to the description of the XtAddInput command for more details about alternate Xt input handlers.

Note that the \" (backslash and double quotation mark) characters before and after the reference to the procID environment variable are necessary, because the value contained in the procID environment variable contains embedded spaces and could be misinterpreted unless escaped as shown.

ttdt_close status procID newProcId sendStopped
Closes the indicated communications connection and optionally sends a Stopped notice, if the sendStopped argument is set to true.

Because the procID returned by the call to ttdt_open contains embedded spaces, it is necessary to enclose any references to the procID environment variable within double quotation marks:

ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False

ttdt_session_join variable status sessId shellWidgetHandle join
Joins the session indicated by the sessId argument as a good desktop citizen, by registering patterns and default callbacks for many standard desktop message interfaces. If the sessId argument does not specify a value (that is, it is an empty string), then the default session is joined. If the shellWidgetHandle argument specifies a widget handle (that is, it is not an empty string), then it should refer to a mappedWhenManaged applicationShellWidget. The join argument is a Boolean and should be set to true or false. This command returns an opaque pattern handle in the variable argument; when no longer needed, this handle can be destroyed using the ttdt_session_quit command.

ttdt_session_quit status sessId sessPatterns quit
Destroys the message patterns specified by the sessPatterns argument and, if the quit argument is set to true, quits the session indicated by the sessId argument or quits the default session if sessId is empty.

ttdt_file_join variable status pathName scope join ksh-command
Registers interest in the deleted, modified, reverted, moved, and saved messages for the indicated file in the indicated scope. An opaque pattern handle is returned in the variable argument. When no longer interested in monitoring messages for the indicated file, this should be destroyed by calling ttdt_file_quit.

The requested ksh-command is evaluated anytime one of the messages is received for the indicated file. When this kshell command is evaluated, the following environment variables are defined and provide additional information about the received message:

DT_TT_MSG
Contains the opaque handle for the incoming message

DT_TT_OP
Contains the string representing the operation to be performed; that is, TTDT_DELETED, TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED or TTDT_SAVED.

DT_TT_PATHNAME
Contains the pathname for the file to which this message pertains.

DT_TT_SAME_EUID_EGID
Set to True if the message was sent by an application operating with the same effective user ID (euid) and effective group ID (egid) as this process.

DT_TT_SAME_PROCID
Set to True if the message was sent by an application with the same procID (as returned by ttdt_open).

When the callback completes, it must indicate whether the passed-in message was "consumed" (replied-to, failed, or rejected). If the callback returns the message (as passed-in in the DT_TT_MSG environment variable), then it is assumed that the message was not consumed. If the message was consumed, then the callback should return 0, or one of the values returned by the tt_error_pointer command. The callback can return its value in the following fashion:

return $DT_TT_MSG (or) return 0

ttdt_file_quit status patterns quit
Destroys the message patterns specified by the patterns argument and unregisters interest in the path name that was passed to the ttdt_file_join command, if quit is set to true. The patterns argument should be the value that was returned by the call to the ttdt_file_join command.

ttdt_file_event status op patterns send
Creates, and optionally sends, a ToolTalk notice announcing an event pertaining to a file. The file is indicated by the path name that was passed to the ttdt_file_join command when patterns was created. The op argument indicates what should be announced for the indicated file, and it can be set to TTDT_MODIFIED, TTDT_SAVED, or TTDT_REVERTED. If op is set to TTDT_MODIFIED, then this command registers to handle Get_Modified, Save and Revert messages in the scope specified when the patterns were created. If op is set to TTDT_SAVED or TTDT_REVERTED, this command unregisters from handling Get_Modified, Save, and Revert messages for this file. If the send argument is set to true, then the indicated message is sent.

ttdt_Get_Modified pathName scope timeout
Sends a Get_Modified request in the indicated scope and waits for a reply or for the specified timeout (in milliseconds) to elapse. A Get_Modified request asks other ToolTalk clients if they have any changes pending on pathname that they intend to make persistent. Returns a value which can be used in a conditional statement. A value of true is returned if an affirmative reply is received within the specified timeout; otherwise, false is returned.

ttdt_Save status pathName scope timeout
Sends a Save request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Save request asks the handling ToolTalk client to save any changes pending for the file specified in the pathName argument. A status of TT_OK is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard Tt_status error values is returned.

ttdt_Revert status pathName scope timeout
Sends a Revert request in the indicated scope and waits for a reply or for the indicated timeout (in milliseconds) to elapse. A Revert request asks the handling ToolTalk client to discard any changes pending for the file specified in the pathName argument. A status of TT_OK is returned if an affirmative reply is received before the timeout elapses. Otherwise, one of the standard Tt_status error values is returned.

The following commands are typically used by the callback registered with the ttdt_file_join command. They serve as the mechanism for consuming and destroying a message. A message is consumed by either rejecting, failing, or replying to it. tt_error_pointer can be used by the callback to obtain a return pointer for indicating an error condition.

tt_error_pointer variable ttStatus
Returns a "magic value," which is used by ToolTalk to represent an invalid pointer. The magic value returned depends upon the ttStatus value passed-in. Any of the valid Tt_status values may be specified.

tttk_message_destroy status msg
Destroys any patterns that may have been stored on the message indicated by the msg argument, and then destroys the message.

tttk_message_reject status msg msgStatus msgStatusString destroy
Sets the status and the status string for the indicated request message, and then rejects the message. It then destroys the passed-in message, if the destroy argument is set to True. This command is one way in which the callback specified with the ttdt_file_join command can consume a message. It is typically safe to destroy the message, using tttk_message_destroy, after rejecting the message.

tttk_message_fail status msg msgStatus msgStatusString destroy
Sets the status and the status string for the indicated request message, and then fails the message. It then destroys the passed-in message, if the destroy argument is set to True. This command is one way in which the callback specified with the ttdt_file_join command can consume a message. It is typically safe to destroy the message, using tttk_message_destroy, after failing the message.

tt_message_reply status msg
Informs the ToolTalk service that the shell script has handled the message and filled in all return values. The ToolTalk service then sends the reply back to the sending process, filling in the state as TT_HANDLED. After replying to a message, it is typically safe to destroy the message, using the tttk_message_destroy command.

Generated with CERN WebMaker