Return Values

Graphical commands in dtksh fall into one of four categories, based on the definition of the corresponding C function:

1. The function is void and returns no values. Example: XtMapWidget()

2. The function is void, but returns one or more values through reference parameters. Example: XmGetColors()

3. The function returns a non-Boolean value. Example: XtCreateManagedWidget()

4. The function returns a Boolean value. Example: XtIsSensitive()

Category 1

A dtksh category 1 command follows the calling sequence of its corresponding C function. The number and order of parameters can be determined by looking at the standard documentation for the function. Example:

XtMapWidget $FORM

Category 2

A dtksh category 2 command also generally follows the calling sequence of its corresponding C function. It returns a value in an environment variable, instead of passing a pointer to a return variable. Example:

XmGetColors $FORM $BG FOREGROUND TOPSHADOW BOTTOMSHADOW SELECT  
echo "Foreground color = " $FOREGROUND

Category 3

A dtksh category 3 command differs slightly from its corresponding C function. Where the C function returns its value as the value of the procedure call, a dtksh command requires an additional parameter. This parameter is the name of an environment variable into which the return value is to be placed. It is always the first parameter. Example:

XmTextGetString TEXT_VALUE $TEXT_WIDGET  
echo "The value of the text field is "$TEXT_VALUE

Category 4

A dtksh category 4 command returns a value that can be used in a conditional expression just as in C. If the C function also returns values through reference variables (as in category 2), the dtksh command also uses variable names for the corresponding parameters. Example:

if XmIsTraversable $PUSH_BUTTON; then  
echo "The pushbutton is traversable"  
else 
echo "The pushbutton is not traversable"  fi

Generally, the order and type of parameters passed to a command matches those passed to the corresponding C function, except as noted for category 3 commands.