# A Complex Scriptscript, complex

This chapter describes a much more complex script than that described in Chapter 2. Because of its length, the entire script is listed in Appendix C. Remember that this guide is not a tutorial on KornShell programming. If you are not familiar with KornShell programming, you should obtain a book on the subject and have it handy for reference.

## Using script_find

The script,
`script_find`, demonstrates how you can use `dtksh` to provide a graphical interface to the `find` command. `script_find` produces a window within which you can specify parameters for the `find` command. To fully understand the script, you should be familiar with the `find` command and you should have its man page available. A number of the toggle button menu choices in the window produced by `script_find` require some knowledge of the `find` command.

The script's window allows you to specify a search directory and a file name. Other options allow you to place restrictions on the type of file system to search and the file type on which to match. Figure 4-1 shows the script's window.

### Window for script_find

Enter the search directory and file name you're looking for in the text fields at the top of the window. In addition, select any applicable choice (or choices) from the five toggle buttons. You can further restrict the search with the option menus. When you have made all the necessary selections, click OK. If all is well, a window appears shortly thereafter and displays the results of the `find` operation. An error dialog appears if you don't specify a search directory or file name, or if the specified search directory is invalid. For example, suppose you want to find a file called `two_letter_calls`, and you think it resides somewhere in the directory `/users/dlm`. When you enter the directory in the Search Directory text field, you inadvertently type `/users/dln` instead of /`users/dlm`. When you click OK or Apply, `script_find` can't find the directory `/users/dln`, so it creates the error dialog to notify you of this.

### script_find error dialog

When you correct the mistake, `script_find` then executes properly and creates a `dtterm` window within which it displays the complete path of the file you requested, providing that the file is found.

### Window showing complete path

If `script_find` cannot find the file in the specified directory, nothing appears in the `dtterm` window.

## Analyzing script_find

The structure of `script_find` is similar to a C program: some functions and callbacks appear first, followed by the main script.

The first two lines of the script are important, and should be included in every `dtksh` script you write:

    #! /usr/dt/bin/dtksh
    . /usr/dt/lib/dtksh/DtFunc.dtsh

The first line executes the `dtksh` system and the second loads the `dtksh` convenience functions. The second line wasn't used in the scripts described in Chapter 2 because those scripts did not use any `dtksh` convenience functions.

### Functions and Callbacks

`script_find` has the following functions and callbacks:

- `PostErrorDialog()`

- `OkCallback()`

- LoadStickyValues()

- `EvalCmd()`

- `RetrieveAndSaveCurrentValues()`

#### PostErrorDialog()

This function is called when an error is detected, such as when the user enters an invalid directory. The function calls the convenience function `
DtkshDisplayErrorDialog()` which displays a dialog box whose title is Find Error and whose message is contained in the variable $1, which is passed from the calling location.

    dialogPostErrorDialog()
    {
         DtDisplayErrorDialog “Find Error” “$1” \
         DIALOG_PRIMARY_APPLICATION_MODAL
    }

The last parameter, `DIALOG_PRIMARY_APPLICATION_MODAL`, tells `dtksh` to create a dialog that must be responded to before any other interaction can occur.

#### OkCallback()

`OkCallback()` is called when either the OK or Apply button on the main `script_find` window is pressed. If the OK button is pressed, the script_find window is unmanaged. For either Apply or OK, the input search directory is validated; if it is invalid, then `OkCallback()` calls `PostErrorDialog()`. If it is valid, checks are made on the status of the toggle buttons on the `script_find` window and corresponding adjustments are made to the variable `$CMD`. This variable contains the entire command that is ultimately executed.

#### LoadStickyValues()

This function is called from the main program after the window has been created and managed. It loads all the values from the most recent execution of the script. These values are saved in a file called `Find.sticky` by the function `RetrieveandSaveCurrentValues()`.

#### EvalCmd()

`EvalCmd()` is used by `LoadStickyValues()` to evaluate each line in `Find.sticky` as a `dtksh` command. The following is a list of a `Find.sticky` file:

    XmTextSetString $SD “/users/dlm”
    XmTextFieldSetInsertionPosition $SD 10
    XmTextSetString $FNP “two_letter_calls”
    XmTextFieldSetInsertionPosition $FNP 16
    XtSetValues $FSTYPE menuHistory:$NODIR
    XtSetValues $FILETYPE menuHistory:$NOTYPE
    XmToggleButtonSetState $T2 true false
    XmToggleButtonSetState $T4 true false

#### RetrievAndSaveCurrentValues()

`RetrieveAndSaveCurrentValues()` retrieves the current settings and values of the widgets in the `script_find` window and saves them in the file `Find.sticky`. `Find.sticky` is then used by `LoadStickyValues()` the next time the script is executed.

### Main Script

The remainder of the script is the equivalent of `Main()` in a C program. It initializes the Xt Intrinsics and creates all the widgets used in the `script_find` window. The `set -f` in the first line tells `dtksh` to suppress expansion of wildcard characters in path names. This is necessary so that the `find` command can perform this expansion.

The `script_find` window (see Figure 4-4) consists of a Form widget with four areas. The areas are marked by Separator widgets, and each area has several widgets, all of which are children of the Form.

#### Widgets in script_find window

The widgets are created in sequence by area, from top to bottom.

#### Initialize

Initialize is accomplished by the Xt Intrinsics function `XtInitialize`:

    XtInitialize TOPLEVEL find Dtksh $0 “${@:-}”

This creates a top-level shell that serves as the parent of a Form widget, which is created next.

#### Create a Form Widget

A Form widget is used as the main parent widget. Form is a Manager widget that allows you to place constraints on its children. Most of the widgets in the main `script_find` window are children of the Form. The description of the creation of the rest of the widgets is separated into the four areas of the window (see Figure 4-4).

#### First Area

The first area consists of two Label widgets, two TextField widgets, and a Separator widget that separates the first and second areas.

##### First area of `script_find` Window

The following code segment creates and positions the first Label widget and positions it within the Form using the `DtkshAnchorTop` and `DtkshAnchorLeft` convenience functions:

    XtCreateManagedWidget SDLABEL sdlabel XmLabel $FORM \
      labelString:”Search Directory:” \
      $(DtkshAnchorTop 12) \
      $(DtkshAnchorLeft 10)

The following code segment creates and positions the first TextField widget. Note that it is positioned in relation to both the Form and the Label widget.

    XtCreateManagedWidget SD sd XmText $FORM \
      columns:30 \
      value:”.” \
      $(DtkshAnchorTop 6) \
      $(DtkshRightOf $SDLABEL 10) \
      $(DtkshAnchorRight 10) \
      navigationType:EXCLUSIVE_TAB_GROUP
    XmTextFieldSetInsertionPosition $SD 1

The remaining Label widget and TextField widget are created in the same manner.

The Separator widget is created as a child of the Form widget and positioned under the second TextField widget.

    XtCreateManagedWidget SEP sep XmSeparator $FORM \
      separatorType:SINGLE_DASHED_LINE \
      $(DtkshUnder $FNP 10) \
      $(DtkshSpanWidth)

#### Second Area

The second area consists of a RowColumn widget, five ToggleButton gadgets, and another Separator widget.

##### Second Area of `script_find` Window

A gadget is a widget that relies on its parent for many of its attributes, thus saving memory resources.

The RowColumn widget is created as a child of the Form widget, and positioned directly under the Separator widget created in the first area.

    XtCreateManagedWidget RC rc XmRowColumn $FORM \
           orientation:HORIZONTAL \
           numColumns:3 \
           packing:PACK_COLUMN \
      $(DtkshUnder $SEP 10) \
      $(DtkshSpanWidth 10 10) \
      navigationType:EXCLUSIVE_TAB_GROUP

The five ToggleButton gadgets are created as children of the RowColumn using the convenience function `DtkshAddButtons`:

    DtkshAddButtons -w $RC XmToggleButtonGadget \
      T1 “Cross Mount Points”           ““\
      T2 “Print Matching Filenames”     ““\
      T3 “Search Hidden Subdirectories” ““\
      T4 “Follow Symbolic Links”        ““\
      T5 “Descend Subdirectories First” ““

Another Separator is then created to separate the second and third areas. Note that this Separator widget ID is called `SEP2`.

    XtCreateManagedWidget SEP2 sep XmSeparator $FORM \
     separatorType:SINGLE_DASHED_LINE \
     $(DtkshUnder $RC 10) \
     $(DtkshSpanWidth)

#### Third Area

The third area consists of two option menus and another Separator widget.

##### Third area of `script_find` Window

The Option Menus are pull-down menus. When the user clicks the option menu button, a menu pane with a number of choices appears. The user drags the pointer to the appropriate choice and releases the mouse button. The menu pane disappears and the option menu button label displays the new choice.

The first option menu menu pane consists of a number of push button gadgets, representing various restrictions that can be imposed upon the `find` command:

    XmCreatePulldownMenu PANE $FORM pane
    DtkshAddButtons -w $PANE XmPushButtonGadget \
      NODIR “no restrictions” ““\
      NFS   “nfs”             ““\
      CDFS  “cdfs”            ““\
      HFS   “hfs”             ““
    Next, the Option Menu button itself is created and managed, with the
    menu pane just created ($PANE) identified as a subMenuId:
    XmCreateOptionMenu FSTYPE $FORM fstype \
           labelString:”Restrict Search To File System Type:” \
           menuHistory:$NODIR \
           subMenuId:$PANE \
      $(DtkshUnder $SEP2 20) \
      $(DtkshSpanWidth 10 10) \
      navigationType:EXCLUSIVE_TAB_GROUP
    XtManageChild $FSTYPE

The second option menu button is created in the same manner. It provides further restrictions on the `find` command.

The third separator is created in the same manner as the other separators.

#### Fourth Area

The fourth area consists of four push button widgets, all children of the Form widget.

The four push buttons are used as follows:

- OK executes the `find` command with the parameters input in the `script_find` window and removes the `script_find` window.

- Apply executes the `find` command with the parameters input in the `script_find` window but does not remove the `script_find` window.

- Close terminates `script_find` without executing the `find` command.

- `Help` creates a dialog box with information on the use of `script_find`.

The push buttons are created and positioned in much the same manner as any of the other widgets, although they are each labeled differently. The following code segment shows how the OK push button is created:

    XtCreateManagedWidget OK ok XmPushButton $FORM \
           labelString:”Ok” \
      $(DtkshUnder $SEP3 10) \
      $(DtkshFloatLeft 4) \
      $(DtkshFloatRight 24) \
      $(DtkshAnchorBottom 10)
    XtAddCallback $OK activateCallback “OkCallback”

#### Set Operating Parameters

`XtSetValues` is used to set some initial operating parameters:

    XtSetValues $FORM \
      initialFocus:$SD \
      defaultButton:$OK \
      cancelButton:$CLOSE \
      navigationType:EXCLUSIVE_TAB_GROUP

- Initial focus is set to the first TextField widget in the first area.

- Default button is set to the OK push button in the fourth area.

- Cancel button is set to the Close button in the fourth area.

- Navigation type is set to `EXCLUSIVE_TAB_GROUP.`

The following line configures the TextField widgets so that pressing the return key does not activate the default button within the Form. See the description of `EXCLUSIVE_TAB_GROUP` in Appendix B for more information on its use.

    DtkshSetReturnKeyControls $SD $FNP $FORM $OK

#### Realize and Loop

The last three lines of the script load the previous values of the `script_find` window, realize the top-level widget, and then enter a loop waiting for user input.

    LoadStickyValues
    XtRealizeWidget $TOPLEVEL
    XtMainLoop