EXAMPLE 3 - COMMAND LINE INPUT

This example is based on the BUILD_JOB Program described in detail in CDF-386. The Code fragments in this example are incomplete, but anyone interested in the actual code can look at the Build_Job CMS Library. The BUILD_JOB Program basically operates in Command Line Mode, but uses Menus extensively in order to define the valid responses at various stages of the execution. BUILD_JOB uses a UIPACK Definition File, a portion of which is used in this example. The Example File defines the Verbs QUIT (which exits the program), SET (which sets some attribute of the program) and SHOW (which displays the setting of some attribute). QUIT takes no parameters or qualifiers. SET has the following legal Parameter Names - FILENAME and UTILITIES. These legal Parameters are therefore defined as another Verb Group. SHOW has the following legal Parameter Names - FILENAME, UTILITIES and VERSION. These are again defined within another Verb Group. Most of these Commands take some Qualifiers and thus the legal Commands are:-

QUIT                            Quit the Program

SET FILENAME <Filename>         Specify a new Filename

SET FILENAME/DEFAULT            Restore Default Filename

SET UTILITIES/YBOS=<On/Off>     Enable or Disable YBOS

SET UTILITIES/YHIST=<On/Off>    Enable or Disable YHIST

SET UTILITIES/DEFAULT           Restore Default On/Off

SHOW FILENAME                   Display Current Filename

SHOW UTILITIES                  Display Utilities 

SHOW VERSION                    Display Program Version

!--------------- EXAMPLE 3 Definition File ----------------
!
!       This Verb Group contains all User accessible 
!       Verbs & Menus

Group 100                                                       (1)

Verb Quit

Verb Set

Verb Show

Menu   1 /Title="BuildJob Commands"/Prompt="Build>"
Button 1 /Description="Display Something" -
         /Response="Show"
Button 2 /Description="Set Something"     -
         /Response="Set"
Button 4 /Description="Display Output Filename" -
         /Response="Show Filename"
Button 5 /Description="Display Utilities" -
         /Response="Show Utilities"
Button 7 /Description="Specify Output Filename" -
         /Response="Set Filename"
Button 9 /Description="Quit Program"/Response=Quit

Lock 12345                                                      (2)

!       SET Command Verb Group
!       ======================
!
!       This Group contains all valid Parameters 
!       for the SET Command

Group 101

Verb Filename/Default

Verb Utilities/YBOS=OnOff/YHIST=OnOff

Menu 2/Title="SET Actions"/Prompt="What:"

Button 1 /Description="Set Output Filename" -
         /Response=Filename
Button 2 /Description="Restore Default Output Filename" -
         /Response="Filename/Default"
Button 4 /Description="Set YBOS On/Off" -
         /Response="Utilities/YBOS="
Button 5 /Description="Set YHIST On/Off" -
         /Response="Utilities/YHIST="
Button 6 /Description="Restore Default Utilities On/Off" -
         /Response="Utilities/Default"

Lock 2345

!       SHOW Command Verb Group
!       =======================
!
!       This Group contains all valid Parameters 
!       for the SHOW Command

Group 102                                                       (3)

Verb Filename

Verb Utilities

Verb Version

Menu 3/Title="SHOW Actions"/Prompt="What:"

Button 1 /Description="Show Output Filename" -
         /Response=Filename
Button 2 /Description="Show Utilities" -
         /Response=Utilities

Lock 2345

!------------ End of EXAMPLE 3 Definition File ------------

C------------------ EXAMPLE 3 CODE ------------------------

      PROGRAM BJMAIN
C     ==============
C
C       Description:-
C       =============
C       Main Program for BUILDJOB (EXAMPLE ONLY)
C
$$If VAX
      Implicit None
$$Endif
$$Include 'BuildJob$Library:BJPack.Inc'                        (4)
$$Include 'UIPack$Library:UIParam.Inc'
$$Include 'UIPack$Library:UIError.Inc'
C
C       External Declarations:-
C       =======================
C
      INTEGER   UIINIT
      INTEGER   UIFINI
      INTEGER   UIDFFI
      INTEGER   UIACME
C
C       Local Declarations:-
C       ====================
C
      INTEGER     STATUS
      CHARACTER*4   VERB
C
C       Executable Code:-
C       =================
C
      STATUS = UIINIT(UIPRMD)                                   (5)
      IF (STATUS .EQ. UISUCC) THEN
C
C       Define Dictionary of Allowed Verbs etc.
C       =======================================
C
         STATUS = UIDFFI(BJDFIL)                                        (6)
C
C       Loop awaiting User Input & Branching as necessary
C       =================================================
C
100      CONTINUE
         IF (STATUS .EQ. UISUCC) THEN
C
C       Await User Input
C       ================
C
            STATUS = UIACME(BJPMEN,VERB)                        (7)
            IF (STATUS .EQ. UISUCC  .OR. 
     &          STATUS .EQ. UIQUPR) THEN
               IF     (VERB .EQ. 'QUIT') THEN
C
C       "QUIT" Command
C       ==============
C
                  STATUS = UIFINI()                             (8)
                  STATUS = UIEOF
               ELSEIF (VERB .EQ. 'SET ') THEN
C
C       "SET" Command
C       =============
C
                  CALL BJSET
                  STATUS = UISUCC
               ELSEIF (VERB .EQ. 'SHOW') THEN
C
C       "SHOW" Command
C       ==============
C
                  CALL BJSHOW
                  STATUS = UISUCC
               ENDIF
            ENDIF
            GO TO 100
         ENDIF
      ENDIF
C
C       Program Termination
C       ===================
C
      STOP 
      END

      SUBROUTINE BJSET
C     ================
C
C       Description:-
C       =============
C       This is the Handler for the "SET" Command. 
C       This Command takes one Parameter:-
C
C       What:           Object to be Set
C
C       where the following Objects are valid:-
C
C       FILENAME        Set current Output Filename
C
C       UTILITIES       Set current Utilities enabled
C
C       Global Declarations:-
C       =====================
C
$$If VAX
      Implicit None
$$Endif
$$Include 'BuildJob$Source:BJPack.Inc'
$$Include 'UIPack$Library:UIError.Inc'
C
C       External Declarations:-
C       =======================
C
      INTEGER   BJFILE
      INTEGER   BJUTIL
      INTEGER   UIACME
C
C       Local Declarations:-
C       ====================
C
      INTEGER     STATUS
      CHARACTER*4   VERB
C
C       Executable Code:-
C       =================
C
C       Pickup Object to be Displayed
C       =============================
C
      STATUS = UIACME(BJSEME,VERB)                              (9)
      IF (STATUS .EQ. UISUCC  .OR. 
     &    STATUS .EQ. UIQUPR) THEN
         IF     (VERB .EQ. 'FILE') THEN
C
C       "SET FILENAME" Command
C       ======================
C
            CALL BJFILE
         ELSEIF (VERB .EQ. 'UTIL') THEN
C
C       "SET UTILITIES" Command
C       =======================
C
            CALL BJUTIL
         ENDIF
      ENDIF
C
C       Return to Caller
C       ================
C
      RETURN
      END

      SUBROUTINE BJFILE
C     =================
C
C
C       Description:-
C       =============
C       This Subroutine is the Handler for the 
C       "SET FILENAME" Command. This Command
C       takes one Parameter:-
C
C       Filename:               Output Filename
C
C       OR the following Qualifier:-
C
C       /DEFAULT
C
C       where this latter restores the Default Filename.
C
C       Global Declarations:-
C       =====================
C
$$If VAX
      Implicit None
$$Endif
$$Include 'UIPack$Library:UIError.Inc'
C
C       External Declarations:-
C       =======================
C
      INTEGER   UIGTFI
      INTEGER   UIGTQU
C
C       Local Declarations:-
C       ====================
C
      INTEGER       STATUS
      INTEGER       FILLEN
      CHARACTER*4     QUAL
      CHARACTER*132 FILNAM
C
C       Executable Code:-
C       =================
C
      DEFALT = .FALSE.
C
C       Pickup any Qualifiers attached to the Verb
C       ==========================================
C
      STATUS = UIQUPR
100   CONTINUE
      IF (STATUS .NE. UIQUAB) THEN                              (10)
         STATUS = UIGTQU(QUAL) 
         IF (STATUS .EQ. UIQUPR  .OR.                           (11)
     &       STATUS .EQ. UIQUNE  .OR.
     &       STATUS .EQ. UIQUVA  .OR. 
     &       STATUS .EQ. UIQUDF) THEN
            IF     (QUAL .EQ. 'DEFA') THEN
C
C       "DEFAULT" Qualifier
C       ===================
C
               DEFALT = .TRUE.
            ENDIF
         ENDIF
         GO TO 100
      ENDIF
      IF (DEFALT) THEN
C
C       "SET FILENAME/DEFAULT" Command - Restore Default 
C       ================================================
C
         FILNAM = .....                                         (12)
         FILLEN = LEN(FILNAM)
      ELSE
C
C       "SET FILENAME <Filename>" Command - Pickup Filename
C       ===================================================
C
         FILNAM = .....                                         (13)
         STATUS = UIGTFI('Filename',FILNAM,FILLEN)              (14)
      ENDIF
C
C       Save New Output Filename
C       ========================
C
      ......                                                    (15)
C
C       Return to Caller
C       ================
C
      RETURN
      END

      SUBROUTINE BJUTIL
C     =================
C
C       Description:-
C       =============
C       This Subroutine is the Handler for the 
C       "SET UTILITIES" Command. This Command
C       takes no Parameters, but must be accompanied
C       by ate least one of the following Qualifiers:-
C
C       /DEFAULT                Setup Default States
C
C       /YBOS[=On/Off]          Enable/Disable YBOS Utility
C
C       /YHIST[=On/Off]         Enable/Disable YHIST Utility
C
C       Global Declarations:-
C       =====================
C
$$If VAX
      Implicit None
$$Endif
$$Include 'BuildJob$Source:BJPack.Inc'
$$Include 'UIPack$Library:UIError.Inc'
C
      INTEGER   DUMMY
C
C       External Declarations:-
C       =======================
C
      INTEGER   UIGTON
      INTEGER   UIGTQU
      INTEGER   UIUSLE
C
C       Local Declarations:-
C       ====================
C
      INTEGER      STATUS
      LOGICAL       STATE
      CHARACTER*4    QUAL
C
C       Executable Code:-
C       =================
C
C       Pickup any Qualifiers attached to the Verb
C       ==========================================
C
      STATUS = UIQUPR
100   CONTINUE
      IF (STATUS .NE. UIQUAB) THEN
         STATUS = UIGTQU(QUAL)                                  (16)
         IF (STATUS .EQ. UIQUPR  .OR. 
     &       STATUS .EQ. UIQUNE  .OR.
     &       STATUS .EQ. UIQUVA  .OR. 
     &       STATUS .EQ. UIQUDF) THEN
            IF     (QUAL .EQ. 'DEFA') THEN
C
C       "SET UTILITIES/DEFAULT" Command - Setup Defaults
C       ================================================
C
               .....                                            (17)
            IF     (QUAL .EQ. 'YBOS') THEN
C
C       "SET UTILITIES/YBOS" Command - Pickup new On/Off State
C       ======================================================
C
               STATE = .....                                    (18)
               IF (STATUS .EQ. UIQUVA) THEN
                  STATUS = UIGTON('YBOS Utility',STATE)
               ENDIF
               .....                                            (19)
            ELSEIF (QUAL .EQ. 'YHIS') THEN
C
C       "SET UTILITIES/YHIST" Command - Pickup new On/Off State
C       =======================================================
C
               STATE = .....                                    (20)
               IF (STATUS .EQ. UIQUVA) THEN
                  STATUS = UIGTON('YHIST Utility',STATE)
               ENDIF
               .....                                            (21)
            ENDIF
         GO TO 100
      ENDIF
C
C       Return to Caller
C       ================
C
      RETURN
      END

      SUBROUTINE BJSHOW
C     =================
C
C
C       Description:-
C       =============
C       This Subroutine is the Handler for the 
C       "SHOW" Command. This Command takes one Parameter:-
C
C       What:           Object to be shown
C
C       where the following Objects are valid:-
C
C       FILENAME        Show current Output Filename
C
C       UTILITIES       Show current Utilities enabled
C
C       Global Declarations:-
C       =====================
C
$$If VAX
      Implicit None
$$Endif
$$Include 'BuildJob$Source:BJPack.Inc'
$$Include 'UIPack$Library:UIError.Inc'
C
C       External Declarations:-
C       =======================
C
      INTEGER   UIACME
C
C       Local Declarations:-
C       ====================
C
      CHARACTER*4  VERB
C
C       Executable Code:-
C       =================
C
C       Pickup Object to be Displayed
C       =============================
C
      BJSHOW = UIACME(BJSHME,VERB)                              (22)
      IF (BJSHOW .EQ. UISUCC  .OR. 
     &    BJSHOW .EQ. UIQUPR) THEN
         IF     (VERB .EQ. 'FILE') THEN
C
C       "SHOW FILENAME" Command
C       =======================
C
            .....                                               (23)
         ELSEIF (VERB .EQ. 'UTIL') THEN
C
C       "SHOW UTILITIES" Command
C       ========================
C
            .....                                               (24)
         ELSEIF (VERB .EQ. 'VERS') THEN
C
C       "SHOW VERSION" Command
C       ======================
C
            .....                                               (25)
         ENDIF
      ENDIF
C
C       Return to Caller
C       ================
C
      RETURN
      END
C ------------------- END OF EXAMPLE 3 ---------------------

Notes:

1. The Group Numbers used are essentially arbitrary since they are never referenced in the FORTRAN Code.
2. The LOCK Command ensures that bugs in the FORTRAN Code cannot modify the Verbs and Qualifiers in the current Group.
3. Although the allowed Parameter Names for the SET and SHOW Commands are very similar, those for the SET Command being a subset of those for the SHOW Command, they appear in two separate Groups because the Qualifiers on them are different.
4. BJPACK.INC is assumed to contain Parameters for the Menu IDs corresponding to the Definition File Values.
5. This call overrides the default initialisation of UIPACK, setting Prompted Mode instead of Scroll Mode.
6. This call reads in the Definition File (where the Argument is a CHARACTER PARAMETER assumed to be defined in BJPACK.INC)
7. The Argument BJPMEN is the Menu ID and is assumed to be defined within BJPACK.INC to be 100. This call displays the prompt to the User and awaits User Input. Since an Action Menu has been used, the User can either specify one of the valid Commands, or identify a prebuilt response by giving the corresponding button number. This total list of prebuilt responses may be displayed by typing ``?". Once a valid response has been typed in by the User, the Program need only look at as many characters of the Verb as it needs to differentiate the different responses. This example uses 4 throughout since this is always adequate.
8. By setting STATUS to be not UISUCC the QUIT Command will exit the Program.
9. The Argument BJSEME is the Menu ID and is assumed to be defined within BJPACK.INC to be 101. See also Note 7.
10. Any Qualifiers attached to the Verb must be processed by calling UIGTQU until STATUS is set to UIQUAB (Qualifier Absent).
11. The Function Value indicates whether a Qualifier is present, whether it is negated, defaulted or has an associated value.
12. Code should be inserted here to setup the default filename.
13. Code should be inserted here to setup the current filename as the default for a null response.
14. Code should be inserted here to setup a new current filename.
15. See Notes 10 and 11.
16. Code should be inserted here to set the default states (On/Off) for the known Utilities (YBOS and YHIST).
17. Code should be inserted here to set STATE to either default or current state for YBOS. This will be the state to which this Utility will be set if the Qualifier is defaulted (no associated Value has been specified).
18. Insert code here to set the new YBOS state.
19. See Note 18.
20. See Note 20.
21. The Argument BJSHME is the Menu ID and is assumed to be defined within BJPACK.INC to be 102. See also Note 7.
22. Code should be inserted here to display the current Filename.
23. Code should be inserted here to display the Utility states (On/Off).
24. Code should be inserted here to display the program version number.