Use Action Menu Retained

This Subprogram will display the specified Menu (if it isn't already displayed) and prompt the User to supply input (either explicitly by typing a text string at the keyboard, or implicitly by selecting a Menu Button).

Short Name Calling Sequence

STATUS = UIACME(MENUID,VERB[,BUTTID])

Long Name Calling Sequence

STATUS = UI_ACTION_MENU(...)

Input Arguments

MENUID (Integer) Menu ID

Output Arguments

VERB (Character) Verb response BUTTID (Integer) Button ID (Optional)

Function Value

UI__SUCCESS ) Success UISUCC )

UI__QUAL_PRESENT ) Qualifier Present UIQUPR )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__ILLEGAL_MENU ) Illegal Menu ID UIILME )

UI__NO_INPUT ) No Input UINOIN )

UI__INPUT_ABORTED ) Input Aborted (Ctrl-Z) UIABRT )

UI__END_OF_FILE ) End-of-File detected UIEOF ) in Batch Mode

Note:

1. Depending on the currently setup Mode of Operation, the specified Menu will be displayed (if it isn't already displayed) and the Operator will be prompted to supply input (either from the keyboard or by movement of the Cursor around the screen).
2. In ViewText Mode of Operation, if the Viewport associated with the Menu is hidden (invisible) it will be displayed and then hidden once the User has responded to the Menu Prompt. If the Viewport should be kept visible it must be made explicitly visible (via a call to UI_DISPLAY_VIEWPORT) prior to this call.
3. It is possible that the Menu Viewport is still hidden by other visible Viewports if its priority is lower than them. It is the Application Programmers responsibility to ensure that the relative priorities are adjusted so as to avoid this.
4. It is not necessary to setup a Verb Group prior to calling UI_ACTION_MENU, since the Verb Group associated with the Menu (at the time of the call to UI_DEFINE_MENU) will be setup automatically as the new current Group.
5. The VERB Argument returned to the caller is the full text (in upper case) of the verb portion of the Response Command Text associated with the selected Button via a prior call to UI_DEFINE_RESPONSES or UI_MODIFY_RESPONSE. This Verb text will be truncated or padded out with trailing spaces as appropriate.
6. The BUTTID Argument is optional and, if present, will be set to the Button ID corresponding to the User Response.
7. UI__QUAL_PRESENT indicates that the Verb has some Qualifiers present which must be scanned using UI_GET_QUALIFIER until this indicates that no more are present.
8. The UI__NO_INPUT Function Value indicates that this call was made in Asynchronous Input Mode and no input has been received yet (the VERB Argument will be set to spaces). Later, following the detection of Input (via a call to UI_TEST_INPUT), this call should be repeated (which will not cause the Menu to be redisplayed), and the Verb portion of the response text will be returned.
9. The UI__INPUT_ABORTED Function Value indicates that the User typed Ctrl-Z to abort input. This is only implemented on a VAX/VMS system. It is an informational function value only, no error message will be reported.
10. The UI__END_OF_FILE Function Value indicates that an End-of-File was detected on the main Input Stream in Batch or non-interactive mode where Input is not taken from a terminal but rather from a file. It is a severe error and therefore causes an error to be reported (unless this has been inhibited by a prior call to UI_ERROR_LEVEL).