This section describes each element in the template that documents the Intrinsics, OSF/Motif Toolkit, and Digital Extension routines.

Routine Name

The generic name of the routine.

Format

The generic routine call format. The bindings file for each language supplies the correct elements for that language. Table 1-5 describes the syntax conventions.

Table 1-5 Syntax Conventions

Element	Conventions
Routine entry point name	The name is shown in its generic form, mixed case, with the prefixes Xt, Xm or DXm corresponding to Intrinsic, OSF/Motif Toolkit, or Digital Extension Routines. The routine entry point name is required.
Return values	If there is a return value, it precedes the entry point name and is in the same font as the arguments. A void is implied when there is no return value.
Parentheses	Open and close parentheses surround the argument list in a routine call. Parentheses are required.
Argument names	Argument names, including names of return arguments, appear in mixed case. Arguments in brackets are optional. In a program, list the arguments in the order they appear in the format.
Spaces	One or more spaces are shown between the entry point name and the first argument, and between each argument. Spaces are not required.
Brackets	Brackets ([]) surround optional arguments. Commas that appear inside brackets are optional and appear only when the optional argument appears. Brackets are not required.
Commas	Commas must appear between required arguments. When commas appear inside brackets ([]), they appear only when the optional argument appears.

A table containing information about each argument follows the format section. Arguments are described in order, beginning with the return value, if any. The table lists each argument name, type, access, and mechanism.

Type

Table 1-6 describes the argument type entries. Type names in all caps are generic types; the bindings files for each language translate them into the conventions of that language. Types in mixed case are defined within the language bindings files and can, in most cases, be used as documented.

Table 1-6 Type Entries

Entry	Description
ADDRESS	An unsigned longword containing the virtual address of data or code.
ANY	An unsigned longword containing either data or a pointer to data.
Arg	A structure consisting of two fields: name (the address of a character string) and value (a longword integer containing either data or a pointer to data).
ArgList	An array of Arg structures.
Atom	An unsigned longword integer interpreted as an X atom.
Boolean	A single byte with the predefined values of 1 for true and 0 for false. The language bindings define the constants XtTrue as one and XtFalse as zero for the purpose of setting Boolean values in languages where the native values of true and false do not equate to one and zero.
BYTE	A signed byte integer.
BYTE UNSIGNED	An unsigned byte integer.
Cardinal	An unsigned longword integer.
CHARACTER	A byte integer containing an ASCII character value.
Colormap	An unsigned longword integer interpreted as an X color map.
Cursor	An unsigned longword integer interpreted as an X cursor.
Dimension	An unsigned word integer.
Display	An unsigned longword integer interpreted as an X display.
DXmColorMixWidget	A DXm color mix widget.
DXmCSTextStatus	An unsigned longword integer (actually a C enumerated type).
DXmCSTextPosition	A signed longword integer.
DxmCSTextWidget	A DXm compound string text widget.
Event	An X event structure.
EventMask	An unsigned longword integer interpreted as an X event mask.
Font	An unsigned longword integer interpreted as an X font.
GC	An unsigned longword integer interpreted as an X graphics context.
I18nContext	Address of an I18nContextRec structure.
KeyCode	An unsigned longword integer interpreted as an X keycode.
KeySym	An unsigned longword integer interpreted as an X keysym.
LONGWORD	A signed longword integer.
LONGWORD UNSIGNED	An unsigned longword integer.
Modifiers	An unsigned longword integer interpreted as an Intrinsics modifier key mask.
MrmCode	A signed word integer.
MrmCount	A signed word integer.
MrmHierarchy	An address interpreted as an Mrm hierarchy pointer.
MrmOsOpenParamPtr	The address of an MrmOsOpenParam structure.
MrmRegisterArg	A structure consisting of two fields: name (the address of a character string) and value (of type Opaque).
MrmType	A signed word integer.
Opaque	A value of type address.
Pixel	An unsigned longword integer interpreted as an X pixel.
Pixmap	An unsigned longwrd integer interpreted as an X pixmap.
Position	A signed word integer.
Region	An unsigned longword integer interpreted as an X region.
Screen	An unsigned longword integer interpreted as an X screen.
Substitution	The address of an Intrinsics Substitution Rec.
Time	An unsigned longword integer interpreted as an X timestamp value.
VoidProc	An entry mask to a procedure with no return value.
Widget	An address interpreted as a widget identifier.
WidgetClass	An address interpreted as a widget class pointer.
WidgetList	An array of widgets.
Window	An unsigned longword integer interpreted as an X window.
WORD UNSIGNED	An unsigned word integer.
XEvent	An Xlib event structure.
XImage	An Xlib XImage structure.
XGCValues	An unsigned longword interpreted as a pointer to an Xlib XGCValues structure.
XKeyPressedEvent	An X event.
XmClipboardPendingList	An array of XmClipboardPendingRec structures.
XmColorProc	An entry mask to a procedure with no return value.
XmCutPasteProc	A callback procedure.
XmDropSiteVisuals	An XmDropSiteVisualsRec structure type.
XmDropTransferEntry	An XmDropTransferEntryRec structure type.
XmFontContext	An address interpreted as a Motif font context.
XmFontList	An address interpreted as a Motif font list.
XmFontListEntry	An XmFontListRec structure type.
XmFontType	An unsigned longword.
XmHighlightMode	An unsigned longword (actually a C enumerated type).
XmOffset	A signed longword integer.
XmOffsetPtr	The address of a variable of type XmOffset.
XmRepTypeId	An unsigned word.
XmRepTypeList	An XmRepTypeListRec structure type.
XmString	An address interpreted as a Motif compound string.
XmStringCharSet	An address interpreted as a Motif character set identifier.
XmStringComponentType	An unsigned byte integer.
XmStringContext	An address interpreted as a Motif compound string context.
XmStringDirection	An unsigned byte integer.
XmStringTable	An array of XmStrings.
XmStringTextBlock	The address of an XmTextBlockRec.
XmStringTextFormat	An unsigned longword integer.
XmTextBlock	A structure used to pass text.
XmTextDirection	An unsigned longword.
XmTextPosition	A signed longword integer.
XmTextSource	An address interpreted as a Motif text source.
XmTraversalDirection	An unsigned longword that describes traversal direction.
XmVisibility	An unsigned longword.
XRectangle	An X rectangle structure.
XrmDatabase	An unsigned longword integer.
XrmValuePtr	An address interpreted as an Xrm value pointer.
XtAddressMode	An unsigned longword integer (actually a C enumerated type).
XtAccelerators	An address interpreted as a compiled Intrinsics accelerator table.
XtActionHookId	A value of Opaque type.
XtActionHookProc	An entry mask to a procedure with no return value.
XtActionList	An array of Intrinsics XtActionsRec structures.
XtActionProc	An entry mask to a procedure with no return value.
XtAppContext	An address interpreted as an Intrinsics application context.
XtArgVal	A signed longword integer.
XtCallbackList	An array of Intrinsics XtCallbackRec structures.
XtCallbackProc	An entry mask to a procedure with no return value.
XtCacheRef	A value of Opaque type.
XtCacheType	A signed longword integer.
XtCancelConvertSelectionProc	An entry mask to a procedure with no return value.
XtCaseProc	An entry mask to a procedure with no return value.
XtConvertSelectionProc	An entry mask to a procedure with a Boolean return value.
XtConverter	An entry mask to a procedure with no return value.
XtDestructor	An entry mask to a procedure with no return value.
XtErrorHandler	An entry mask to a procedure with no return value.
XtErrorMsgHandler	An entry mask to a procedure with no return value.
XtEventHandler	An entry mask to a procedure with no return value.
XtFilePredicate	An entry mask to a procedure with a Boolean return value.
XtGCmask	An unsigned longword integer.
XtGeometryMask	An unsigned longword integer.
XtGeometryResult	An unsigned longword integer (actually a C enumerated type).
XtGrabKind	An unsigned longword integer (actually a C enumerated type).
XtIntervalId	An unsigned longword integer.
XtInputCallbackProc	An entry mask to a procedure with no return value.
XtInputId	An unsigned longword integer.
XtInputMask	An unsigned longword integer.
XtLanguageProc	An entry mask to a procedure that returns a null-terminated string.
XtListPosition	An unsigned longword integer.
XtLoseSelectionProc	An entry mask to a procedure with no return value.
XtPointer	A value of type address.
XtSelectionCallbackProc	An entry mask to a procedure with no return value.
XtSelectionDoneProc	An entry mask to a procedure with no return value.
XtString	A null-terminated string of from 0 to 65,535 8-bit characters.
XtStringArray	An array of XtStrings.
XtTimerCallbackProc	An entry mask to a procedure with no return value.
XtTranslations	An address interpreted as a compiled Intrinsics translation table.
XtTypeConverter	An entry mask to a procedure with a Boolean return value.
XtWidgetGeometry	An XtWidgetGeometry structure.
XtWorkProc	An entry mask to a procedure with a Boolean return value.
XtWorkProcID	An unsigned longword integer.

Access

The Access column specifies the way in which the called routine accesses the argument. For example, when the argument is passed as input, the access is "read only" and when the argument is returned by the routine, the access is "write only." See Table 1-7 for a list of access entries used.

Table 1-7 Access Entries

Entry	Description
read	Input data required by the routine to perform its operation must be readable. When an argument specifies input data, the access entry is readable. The routine cannot write data back to this argument.
write	Output data returned by the routine to a specific location. When an argument specifies output data, the access entry is writable. The routine does not read the contents of the location either before or after it writes into the location.
modify	The routine reads the input data, which it uses in its operation, and then overwrites the input data with the results (the output data) of the operation. Thus, when the routine completes execution, the input data specified by the argument is lost.

Mechanism

The Mechanism column specifies the passing mechanism used by the called routine. For example, when the argument is the value itself, the mechanism is "by value" and when the argument is a pointer to the value, the mechanism is "by reference." See Table 1-8 for a complete list of mechanism entries.

Table 1-8 Mechanism Entries

Entry	Description
value	The argument contains the actual data to be used by the routine.
reference	The argument contains the address of the data to be used by the routine. The argument is a pointer to the actual data.