.XLOWER .FLAGS BOLD .CH ^*MENU SYSTEM\* .LM 6 .RM 72 .SK 2 .HL1 ^*GENERAL INFORMATION\* .X MENU > Description .p The menu system is a software program that allows a software system (group of related programs) to interact with a person. The menu system displays menus with up to 9 selections for the person to choose from by entering a number. They can display another menu at a lower level or depress the 0 key and return to a higher level. Further, they can run a program at their terminal or start a job that will run separately, called a batch job. .sk The command format is : .nf $ MENU [] .f .X DCL Symbols > MENU .p The form-library-name is the name of a form library which contains a group of menus. The menu system can only use one form library per execution. The menu system displays the form 'MAINMU' as the main menu of the group. .p It is necessary to become familiar with the VAX/FMS form editor. The menu system gets all of the control information from menu forms in the specified form library. The control information is stored in the named data section of the form using the VAX/FMS form editor or form language. .p The subprocess-name is the name given to the process that executes all of the images or command procedures that are selected on the menu. A subprocess does the work, since the menu system image is executing in the current process. .x MENU > Elements .p A menu is a VAX/FMS form with the following elements, a title, a menu id, a maximum of 9 choices, a selection prompt, and a selection field. .hl2 A title .p The title is centered on line one. It is concise and consists of all capital letters. .hl2 A menu id .p The menu id is the VAX/FMS form name. Using the menu id, a programmer will know the form name to make any changes. The menu id is placed on line two and right justified. .hl2 A maximum of nine choices .p A maximum of nine choices are allowed. They are numbered from one to nine. Zero is reserved for exiting the current menu to the previous menu if there is one. Each choice has the selection number in column 20, a period in 21, and the selection description starting in column 25. The description (in upper and lower case ) will be clear and concise with no abbreviations. .p The selections should be arranged in groups of three for easier recall. .hl2 A selection prompt .p The selection prompt, 'Selection:' for example, is placed on line 19 a few spaces before the selection field. .hl2 A selection field .p The selection field, which must be called 'SELECT', is a one character field on line 19 and col 20. The field should be autotab to allow single keystroke selections, but this is not necessary. .sk .tp 26 .x MENU > Example The following is an example menu form: .NF +---------------------------------------------------------------+ | A TITLE CENTERED | | MENUID| | | | | | | | | | | | 1. First | | 2. Second | | 3. Third | | | | 4. Fourth | | | | | | | | | | | | | | Selection: __ | | _^ | | | | | +---------- SELECT field | +---------------------------------------------------------------+ .F .x MENU > Setting it up .HL1 ^*SETTING IT UP\* .p The only connection between the selection number and the description is their proximity to each other in the form layout. The selection description describes what can be done and the number they select is used as the name key into the named data section of the form. .p For each form there are a number of named data items that are required to tell the menu system what to do when a selection is chosen. A selection has one named data item, whose name is the selected number, which describes that selection for the menu system. The following describes these named data items required for the menu system. .hl2 Specifying the range of selections .x MENU > RANGE .p The named data item named 'RANGE' is message printed on the last line of the menu to tell the user what to select. For our previous example the 'RANGE' named data item could have been: .sk Depress 1,2,3 or 4, to exit depress the 0 key. .sk .hl2 Interactive selection .X MENU > SELECTIONS > Interactive .p An interactive selection activates an image at the terminal. Possible interactive application programs are Datatrieve, an VAX/VMS based data entry/query program, and a backup procedure that asks questions. The format for the menu command is (note the ';' delimits parts): .sk I;[;] .sk Notice the three parts of the interactive command string, (1) 'I' interactive command code, (2) the command to execute, and (3) an optional comment. When the interactive selection is made, the main process sleeps until the subprocess completes the command. After completion, the menu is redisplayed and the menu system waits for another entry. .hl2 Message display selection .X MENU > SELECTIONS > Message display .p The second type of selection is the message display. Simply, a message is displayed on the screen when the selection is chosen. The format of this menu command is: .sk M; .sk After the message is displayed, the menu system waits for the user to hit a return. When the return is depressed, the system clears the message , redisplays the 'RANGE' string and waits for another entry. .hl2 Display another menu .X MENU > SELECTIONS > Display new menu .p The third type of selection is the one that allows you to display a new menu. Optionally, a one to six character password may be required; setting up for the password screen is described later. The menu to be displayed must be in the form library specified. The format of the display menu command is: .sk D;[];[;] .sk The password is case sensitive, if you enter it in lower case the user must enter it in lower case too. .p You can have many levels of menus. Think of these menus as different depths, somewhat like a family tree. The 'MAINMU' form is displayed as the highest depth. When a new menu is displayed, it is displayed at a lower depth. When a lower depth menu exits (depressing 0) it returns to the menu that requested it, at a higher depth. The maximum depth allowed by the menu system is 20 menus. .hl2 Submit a batch job .X MENU > SELECTIONS > Submit a batch job .p The last type of menu selection command submits a batch job. It allows you to specify a particular queue for the batch job, or just default to SYS$BATCH. Furthermore, it allows you to run a interactive command to request input, before the batch command is submitted. The format of the batch menu command is: .sk B;[;];<batch command>[;<queue>] .sk The five parts provide for a flexible batch submission facility. The 'B' is the menu command code for a batch selection. Let's take a more detailed view of the other four parts. .hl3 input command .p The optional input command is any DCL command you want to run interactively before the batch job gets started. You may want to enter selection criteria for a report or create a command file for the batch process to run later. The menu system changes your default directory to the directory that the batch job will be running. Then it executes the input command. Once completed, the menu system submits batch command and resets your default directory. .hl3 title .p The title is passed to the input command as a foreign command line. If the input command is a command file, you can get the title by using the P1 through P8 DCL symbols. If the input command is a program, you can get the title by calling the VOS routine GETCMD. .hl3 batch command .p The batch command is a DCL command that gets executed in the batch process. It will execute in the directory the menu system has allocated for it. The batch command is responsible for cleaning up all of the files created in the default directory. .hl3 queue .p The batch command will execute in the specified queue or SYS$BATCH if queue is not specified. The batch queue should be one that is available from your computer node. .hl1 ^*OPTIONAL NAMED DATA\* .p Special named data elements not mentioned above are covered in detail here. The ENVIRONMENT named data item can change the way the selections and batch jobs run. The other three change the way the menu system acts to the user. .hl2 ENVIRONMENT .X MENU > ENVIRONMENT .p The ENVIRONMENT named data specifies a command file to be executed before any selection or batch command. Be cautioned however, if you define logical names, the subprocess will keep the definitions until they are redefined. For example, if you define MY__FILE in an environment command file, MY__FILE will remain defined until it is deleted or you leave the menu. .p The menu system uses the ENVIRONMENT named data specified in the current menu screen. If one is not defined, no action is taken. .HL2 NO__RETURN .X MENU > NO__RETURN .p The menu system allows the operator to see fatal error messages displayed by interactive programs before the menu is displayed over them. The NO__RETURN named data item, if defined in 'MAINMU', tells the menu system not to wait for the operator to hit a return after an interactive command. If this is not in the named data section the menu system retains screen context until a terminator is depressed. .HL2 NO__SUBMIT__MESSAGE .X MENU > NO__SUBMIT__MESSAGE .p The menu system, by default, displays the message the batch job controller returns when the submission is taken. This message includes the job name and job number. If the NO__SUBMIT__MESSAGE named data item is found in 'MAINMU' the menu system does not display this message and immediately redisplays the current menu. .HL2 NO__NOTIFY .X MENU > NO__NOTIFY .p The menu system, by default, requests the batch job controller to notify the operator when a batch job is completed. If the NO__NOTIFY named data item is found in the menu 'MAINMU' the menu system skips this request. .HL1 ^*VOS__BATCH__DISK: WHAT IS IT?\* .X MENU > VOS__BATCH__DISK .p The batch jobs created by the menu system all execute in a directory allocated for it by the menu system. This keeps concurrently executing batch jobs from executing in the same directory and perhaps interfering with each other. These directories are of the form VOS__BATCH__DISK:[VOSBATCH.0000xx]. .hl2 Logical name .P For this to work the logical name VOS__BATCH__DISK must be created and assigned to a disk the directories will be on. .hl2 Directories .p 51 directories must be created on VOS__BATCH__DISK. Each should have WO:RWE protection. The first is VOS__BATCH__DISK:[VOSBATCH]; this directory contains 50 subdirectories and the BATCHDIR.IDX file. The rest of the directories are subdirectories of [VOSBATCH] in the form [.0000xx] from [.000001] to [.000050]. .hl2 BATCHDIR.IDX .X MENU > BATCHDIR.IDX .p The BATCHDIR.IDX file is used by the menu system to choose the next subdirectory for a batch job's current device and directory. The menu system increments the number from 1 to 50, and when it reaches 50 it changes it to 1 again to recycle through the directories. .p If 50 batch jobs will be running concurrently, or if a long job does not complete before 50 others, there can be a problem when next batch job runs. It will share the directory with the older batch job and the two jobs could disrupt each other. If this occurs the menu system should be modified to allow more directories, you could have up to 10000 if you really wanted. .HL1 ^*MENU HELP FACILITY\* .X MENU > Help facility .p The menu system has a help facility to provide user friendly guidance through your menus. When you depress the PF2(standard help) key, FMS tries to display some help information for the operator. With each depression of the PF2 key, the field help is displayed, then the form help is displayed, and finally the menu system help is displayed. If any one of the help does not exist, the next type is tried. For example, if there is no field help the first depression of the PF2 key displays the form help. .p The menu system uses a post help user action routine (UAR) to give the third type of help. The third type is a menu that allows the operator to select a help screen to describe a particular selection on the menu. The help menu should look like the menu however a reverse video border or some other distraction around it should prevent operator confusion. .P There are a few steps that you must take to set up this facility. The steps are (1)link menu with help, (2) create the help menu, and (3) create the selection help screens. These are further described below. .hl2 Link menu with help .p FMS needs to be informed of this facility. The string "MENU__HELP" must be placed in the post-help UAR field in the form definition. This is done using the FMS form editor, in the FORM phase. .hl2 Create the help menu Make a copy of the menu form you would like to set up help for. Its name should be <original-name>__HELP.FRM. Use the FMS form editor to change the name of the form to match the form file name. .p Use the layout phase of the form editor and put a reverse video border around the screen to distinguish it from the menu screen. .p Use the named data phase of the form editor to change the named data items for the menu. Instead of menu control commands, each selection will have a help screen to be displayed when chosen. If you prefer not to create a help screen for a selection do not include it in the named data list. .p While in the named data phase of the form editor, make a change to the 'RANGE' named data item to better define what their selection will provide. .hl2 Create the seletion help screens .p The help screens are restricted to one FMS form. Try to make it helpful, if not you are wasting their time. .HL1 ^*BATCH PRINT QUEUE --- VOS__BATCH__PRINT\* .X MENU > VOS__BATCH__PRINT .P The logical name VOS__BATCH__PRINT must be defined for in order to submit a batch job using the menu system. It is assigned to a valid print queue that you want the batch logs to come out on. .HL1 ^*CAPTIVE MENU SYSTEM VOS__SLAVE__MENU\* .X MENU > VOS__SLAVE__MENU .p If the logical name VOS__SLAVE__MENU is defined in the table LNM$JOB the menu system does not allow the operator to exit the 'MAINMU' screen. Combining this with a captive account allows you to set up captive menu systems. .pg .HL1 MENU INTERNALS .p The MENU program is a utility that provides a friendly interface between humans and the computer system. A menu system is the menu program and a group of forms that describe possible actions. These FMS forms are maintained in a form library. Whenever a menu system is started the MAINMU form in the specified form library is displayed. .P When a selection is made, the named data item is retrieved corresponding with the number selected. The first letter in the named data string is the command. The rest of the string is split into different pieces of information and delimited by a semicolon. The rest of the named data gives more information for the command. There are four possible commands, (1) "D" for display a new menu, (2) "I" for execute a DCL command, (3) "M" for print a message on the terminal, and (4) "B" submit a batch job. .HL2 MENU program - general flow .p The general flow of the program is described in this section. The next page has a rough graphic illusration of how the program flows. The following pages describe each of the numbered boxes in more detail. The commands will be described in more detail in the next section. .PG .LT MENU PROGRAM +-------------------+ | Parse command line| | and open library | +--------1----------+ | +-------------------+ | Spawn subprocess | | and start command | +--------2----------+ | +-------------------+ | Display MAINMU frm| |and check for menu | | directive namedata| +--------3----------+ | +-------------------+ | Loop while | | FORM_NUMBER GT 0 |-----------+ +-------------------+ | ^ +---------------+ | | Get input from| | | operator | | +------4--------+ | | | +---------------+ | |"PF4"-go back | +<---------------| to form 1 | | +------5--------+ | | | +---------------+ | |"0"-go back a | +<---------------| form | | +------6--------+ / | / +---------------+ / |get the command| / |for selection | / +------7--------+ / | | | | / +--- "M" ---+ "B" "I" +----- "D" -----+ / | / \ | / v v v v / +-----------+ +-----------+ +--------------+ +----------+ / |display a | |submit a | |execute an | |display a | | |message | |batch commd| |interactive | |new form | | +-----------+ +-----------+ +--------------+ +----------+ | | | | | | v v v v +<--------+<------------+<-------------+<--------------+ GENERAL FLOW OF MENU PROGRAM .EL .pg The following elements describe the numbered boxes in the previous figure. .ls .le Parse command line and open library .p The menu program calls the runtime library routine LIB$GET__FOREIGN to get the command that the operator has entered or was entered for them. The expected syntax in the command string is: .br $ MENU <menu library file name> [<subprocess name>] The command line is parsed and the library and process name are saved. If they are not on the line, LIB$GET__FOREIGN is called again. This time however, only the library name is prompted for. The FMS routine FDV$LOPEN is used to open the library file. .le Spawn subprocess and start command file .p Next we get the subprocess started. The first step is to create a temporary mailbox named MENU__MAILBOX. If the process name was filled in during the previous step, it is passed to LIB$SPAWN to create the subprocess. The mailbox is also passed to become the process permanent input device for the subprocess. .p Once the subprocess is created, we open the mailbox device and write the string "@VOS:[SHARED]SUBPROCESS.COM" to the mailbox for the subprocess to execute. This command file gets the commands from the menu program, executes them, and returns the status in a loop. .le Display MAINMU form and check for menu directives .p To start a trip through FMS land, we must attach a workspace for the MAINMU form to be displayed. Then display the form within it. If the form does not get displayed because of an error, the menu program is crippled and must exit. When the program has to exit in this way, it also deletes the subprocess on the way out. .P There are three named data items that can control the menu program, these are (1) NO__RETURN, (2) NO__NOTIFY, and (3) NO__SUBMIT__MESSAGE. If NO__RETURN is defined in named data of MAINMU, the variable HIT__RETURN is set to false. If NO__NOTIFY is defined, NOTIFY__BATCH is set to false. And, if NO__SUBMIT__MESSAGE is defined, SUBMIT__MESSAGE is set to false. .p Once the MAINMU form is displayed, the FDV$RETDN (return named data by name) is called for each named data item. If the call is successful, the named data is defined - the value is not important. .le Get input from operator .p To get the input from the operator, we get the prompt from named data, display it and then get the input from the operator. The prompt string is kept in each form in the "RANGE" named data. The menu program gets that with the FDV$RETDN routine, clears out the "SELECT" field, and uses FDV$PUTL to display the prompt. The next step is to call FDV$GET to get the selection from the operator. .le "PF4" - go back to form 1 .p If the operator depressed the "PF4" key, they want to return to the main menu. The "PF4" key is a field terminator. The terminator argument of the FDV$GET call contains the value FDV$K__PF__4 if they depress the key. .p If the "PF4" key is depressed the menu system loops back through the WORK_SPACE array and detaches all of the workspaces except the first and decrementing FORM__NUMBER along the way. After they are all detached, the first workspace (MAINMU's) is set as the default and it is redisplayed. .LE "0" - Go back one menu form .p If the operator presses the "0" key, the menu program must display the menu that was displayed before this menu. First, detach the current workspace, using the FDV$DWKSP routine. Second, decrease the FORM__NUMBER variable by one. And third, set the default workspace to be the current one and display it. .p If the FORM__NUMBER equals 1 and we are not slave, the workspace is detached and the FORM__NUMBER is decremented. The presence of the logical name VOS__SLAVE__MENU in the job logical name table makes this processes' menu program slave. This throws us out of the loop and causes the menu program to exit. On the other hand if we are slave, the menu program ignores this request to exit. .le Get the command for the valid selection .p If we have made it this far, the entry made by the operator is valid or the menu program is going to ignore it. The routine FDV$RETDN is called using the value entered by the operator. The named data is returned and further control is decided by the first character of the named data string. The next section gives more information about what is done for each type of command. .ELS .hl2 Commands .hl3 The "D" command - "D;[<password>];<new menu form name>;" .p The "D" command displays a new menu screen. The first parameter is the password to use. If this parameter is non-null, the "PASWRD" form, performs a FDV$GET on the field "PASSWD" and matches the string received with the parameter. If there is a match or if the password parameter is a null string, the next parameter is used as a form name to display. .p To display a new form, them menu program must take 4 steps. The first step is to increase the form number by one, there can be up to 20, this is our menu depth indicator. Then the form name is saved in the FORM__NAME array so we know which one we are working on now. The third step is to attach a FMS workspace to display the current form. The previous form's workspace is left intact. The last is to display the form in the workspace. .p This technique allows the menu program to go back one level (when they enter "0") by changing default workspaces and displaying the form that is in the workspace. .hl3 The "I" command - "I;<valid DCL command>" .p The "I" command executes an interactive DCL command in the subprocess. The DCL command is parsed out of the named data string. The environment command file is executed in the subprocess if there is one specified. The command is written to the mailbox which already has a read posted on it from the subprocess. Then the menu program posts a read on the mailbox lun to receive the completion status. .p After the completion status is returned, the corresponding error message is printed out if the HIT__RETURN is true. This message is printed out once the menu is redisplayed. .hl3 The "M" command - "M;<any message>" .p The "M" command displays a message to the screen. The message is parsed from the named data and the FDV$PUTL routine is used to display it on the screen. The operator is then signaled and the menu program waits for the operator to press return. No change is made to the menu currently displayed. .hl3 The "B" command - .c;"B;[<DCL interactive >;<title>];<Batch command>;[<Batch queue>]" .p The "B" command submits a batch job for the operator. This command is the most complicated. It also allows you to execute an interactive command with the same default directory as the batch job. The batch command can be controlled by the context defined by the interactive command. .p The subroutine SUBMIT__BATCH__JOB does the work for the "B" command. The named data is parsed to get the different parameters. If the DCL command parameter is blank, then there is no title and the parsed parameter values are off by one. The parameter values are updated accordingly in that event. .p The next step is to get the next available directory using the GET__DIRECTORY subroutine. This directory will be used as the default directory for the DCL command and the batch job. If the command is non-blank then we write three strings to the subprocess, (1) write the SET DEFAULT string to change the default directory to the one we got from GET__DIRECTORY, (2) call the SET__UP__ENVIRONMENT to execute an environment command if specified and (3) write the DCL command. .p IF THE STATUS RETURNED FROM THE DCL COMMAND IS NOT ODD, THE REST OF THESE STEPS ARE SKIPPED AND THE MENU IS REDISPLAYED. This feature allows the interative part to control whether the batch job is run. There may be insufficient data or the operator changed its mind. .P Once the interactive command has executed successfully, we need to create the batch procedure that will execute their batch command. The following things are put in the batch procedure: .ls "o" .le $ SET DEFAULT VOS__BATCH__DISK:[VOSBATCH.xxxxxx] .p This command sets the default directory for the batch process to the one that was selected earlier. This is the directory that the DCL command ran in. .LE $ <environment command> .p The environment command is returned from the ENVIRONMENT named data. The current menu form is used to get the value. The command is put into the batch procedure without any translation. .le $ <batch command> .p The batch command is the one from our selection. It is put into the batch procedure without translation. .le $ EXIT .p The exit command is put into the batch procedure for completeness .els .p The next step is to submit the batch procedure. All of the arguments are checked to make sure they are non-blank. For example, if the batch queue was not specified, batch queue is filled with the SYS$BATCH queue name. The item list for the SYS$SNDJBC, send job controller message, is filled in with all of the arguments and system service is called. .p If it failed the error message corresponding to the problem is displayed on the screen. Otherwise, if the NO__SUBMIT__MESSAGE named data exists (found this while initializing menu program) then no job status string is displayed to show success. If it did not exist, it would be displayed. .hl2 MENU from VMS's point of view .p The menu program executes in the process that types the MENU command. Nothing but the menu can run in this process. The menu program creates a subprocess using the LIB$SPAWN run-time library routine to execute any commands or images that are called for. The main program handles "M"essage commands and "D"isplay a new menu commands without the subprocess being involved. The menu program does the submission of the batch job. The subprocess handles the "I"nteractive command and the DCL interactive command part of the "B"atch command. .p The menu program creates a mailbox that is used for interprocess communication to/from the subprocess. The mailbox is defined as the subprocesses process permanent SYS$INPUT file. The menu program first tells the subprocess to run VOS:[SHARED]SUBPROCESS.COM by writing "@" and the file name to the mailbox. The subprocess command file opens the mailbox for read and write access and posts a read waiting for the next command. When it gets one it executes it and writes the severity code back to the menu program via the mailbox. Once the subprocess command file is running, all further interaction can be shown using the following figure. .bl 20 .LT $ MENU MENULIBRARY.FLB HARPO your process subprocess HARPO running:MENU.EXE @SUBPROCESS.COM -----------------+ +------------------ a selection is | |commands from main made and command\ / process are read sent |\ /| and executed | \------------->/ | . | ____________ | . | | mailbox | | | |__________| | | | | /<-------------\ | |/ \| / \ go get another | | return the severity selection | | to menu program -----------------+ +------------------ COMMUNICATION BETWEEN MENU PROGRAM AND SUBPROCESS .EL .PG .FIGURE .PG