VOC M-Type Records  -  Menu Definitions

 Top  Previous  Next

 

A VOC menu record defines a menu of numbered options to be displayed to the user when the menu entry is executed. Because menu records may be very large, they are often stored in some other file with a VOC R-type record as a remote pointer to the actual menu definition.

 

A menu record has 11 fields:

 

1:M  { descriptive text }
2:Menu title line to appear at the top of the screen.
3:Item text. This field is multivalued with one value for each menu entry. Blank entries are allowed to insert spacing in the menu. Each menu entry is numbered except as described under field 4 below.

The descriptions are normally displayed starting on the third line of the screen, left justified. If the menu has more items than will fit in a single column on the screen and the items are all sufficiently short, the menu will be displayed as two columns. Any menu items that will not fit on the screen are lost.

4:Action. This field is multivalued with entries corresponding to the text in field 3. If the action is terminated by a semicolon, the menu processor issues a "Press return to continue" prompt when the command is completed. Blank entries cause the field 3 text to be treated as a sub-title and not numbered on the displayed menu.
5:Help text. A multivalued set of one line help texts corresponding to each menu option in the previous fields.
6:Access key. An optional multivalued set of access control keys corresponding to the menu items. The access key value is passed to the access control subroutine if this is used.
7:Hide inaccessible entries. This field may be single valued in which case it applies to all menu entries or it may have one value for each menu item. Each value present is a numeric representation of a Boolean (1 or 0 corresponding to True or False) flag indicating whether inaccessible menu entries should be hidden (not displayed) or shown as unavailable.
8:Access subroutine. This optional field contains the name of an access control subroutine (see below).
9:Prompt text. If present, this text replaces the default option prompt.
10:Exit codes. An optional multivalued list of codes which when entered at the option prompt will exit from the menu. If this field is blank, entering a null response to the menu prompt will exit from the menu. Because exit codes are processed before option numbers, it is possible to include an option that causes an exit by specifying the option number as an exit code.
11:Stop codes. An optional multivalued list of codes which when entered at the option prompt will generate an abort event, terminating all active processing and returning to the command prompt. If this field is blank, it defaults to Q. Because stop codes are processed before option numbers, it is possible to include an option that causes a stop by specifying the option number as a stop code.

 

Menus may be constructed and maintained using the menu editor MED.

 

A summary of M-type VOC records may be displayed or printed using LISTM.

 

 

Access Control

 

A menu may include run time selection of which options are to be offered to the user. This is managed by a user written access control subroutine named in field 8 of the menu definition. When the menu is displayed, this subroutine is called for all entries that have an access key defined in field 6 to determine whether the option is to be offered. The subroutine takes three arguments; the returned True/False accessibility flag, the menu name and the access key. Typically, the access key would be a name that refers to a group of users such as ADMIN or SALES. Access control subroutines may be used by multiple menus and, where necessary, can use the menu name in the decision process that controls display. The subroutine should return the first argument as True (or numeric value 1) if the menu item is to be allowed, False (or numeric value 0) if it is to be disabled.

 

Field 7 of the menu definition contains the "hide" flag which controls the action taken when a menu option is disabled for a user. Setting this to 0 or leaving it blank, displays the option with its option number enclosed in parentheses. Entry of this option number at the menu prompt will be ignored. Setting the hide flag to 1, completely hides the disabled option.

 

An example of a simple access control subroutine is shown below:

 

SUBROUTINE ACCESS(OK, MENU.NAME, KEY)

  BEGIN CASE

     CASE KEY = 'ADMIN'

        OK = (@LOGNAME = 'ADMINISTRATOR')

     CASE 1

        OK = @FALSE

        OPEN 'USERS' TO USER.F THEN

           READ USER.REC FROM USER.F, @LOGNAME THEN

              OK = (USER.REC<U.DEPT> = KEY)

           END
        END

  END CASE

  RETURN

END

 

For an access key of ADMIN, this subroutine enables the menu option only if the user is logged in as an administrator. For all other access key values, it reads a user record and checks that the user is in the relevant department. The U.DEPT token used above would be defined in an include record.