Syntax: PMENU Procedure | Base SAS 9.1 Procedures Guide, Volumes 1, 2, 3 and 4

Restriction: You must use at least one MENU statement followed by at least one ITEM statement.

Tip: Supports RUN group processing

Reminder: You can also use appropriate global statements with this procedure. See Chapter 2, Fundamental Concepts for Using Base SAS Procedures, on page 15 for a list.

See: PMENU Procedure in the documentation for your operating environment.

PROC PMENU <CATALOG=< libref .> catalog >

- <DESC entry-description >;
MENU menu-bar ;
- ITEM command < option(s) >;
- ITEM menu-item < option(s) >;
  - DIALOG dialog-box command-string
    - - field-number-specification ;
    - CHECKBOX <ON> #line @column
      - text-for-selection
        
        < COLOR = color > <SUBSTITUTE= text-for-substitution >;
    - RADIOBOX DEFAULT= button-number ;
      - RBUTTON <NONE> #line @column

text-for-selection <COLOR= color >
<SUBSTITUTE= text-for-substitution >;

TEXT # line @ column field-description

<ATTR= attribute > <COLOR= color >;

MENU pull-down-menu ;
SELECTION selection command-string ;
SEPARATOR;
SUBMENU submenu- name SAS-file ;

To do this	Use this statement
Define choices a user can make in a dialog box	CHECKBOX
Describe a dialog box that is associated with an item in a pull-down menu	DIALOG
Identify an item to be listed in a menu bar or in a pull-down menu	ITEM
Name the catalog entry or define a pull-down menu	MENU
List and define mutually exclusive choices within a dialog box	RADIOBOX and RBUTTON
Define a command that is submitted when an item is selected	SELECTION
Draw a line between items in a pull-down menu	SEPARATOR
Define a common submenu associated with an item	SUBMENU
Specify text and the input fields for a dialog box	TEXT

PROC PMENU Statement

Invokes the PMENU procedure and specifies where to store all PMENU catalog entries that are created in the PROC PMENU step.

PROC PMENU <CATALOG=< libref .> catalog >

<DESC entry-description >;

Options

CATALOG=< libref .> catalog

specifies the catalog in which you want to store PMENU entries.
Default: If you omit libref , then the PMENU entries are stored in a catalog in the SASUSER data library. If you omit CATALOG=, then the entries are stored in the SASUSER.PROFILE catalog.
Featured in: Example 1 on page 698

DESC entry-description

provides a description for the PMENU catalog entries created in the step.
Default: Menu description
Note: These descriptions are displayed when you use the CATALOG window in the windowing environment or the CONTENTS statement in the CATALOG procedure.

CHECKBOX Statement

Defines choices that a user can make within a dialog box.

Restriction: Must be used after a DIALOG statement.

CHECKBOX <ON> #line @column

text-for-selection
<COLOR= color > <SUBSTITUTE= text-for-substitution >;

Required Arguments

column

specifies the column in the dialog box where the check box and text are placed.

line

specifies the line in the dialog box where the check box and text are placed.

text-for-selection

defines the text that describes this check box. This text appears in the window and, if the SUBSTITUTE= option is not used, is also inserted into the command in the preceding DIALOG statement when the user selects the check box.

Options

COLOR= color

defines the color of the check box and the text that describes it.

indicates that by default this check box is active. If you use this option, then you must specify it immediately after the CHECKBOX keyword.

SUBSTITUTE= text-for-substitution

specifies the text that is to be inserted into the command in the DIALOG statement.

Check Boxes in a Dialog Box

Each CHECKBOX statement defines a single item that the user can select independent of other selections. That is, if you define five choices with five CHECKBOX statements, then the user can select any combination of these choices. When the user selects choices, the text-for-selection values that are associated with the selections are inserted into the command string of the previous DIALOG statement at field locations prefixed by an ampersand (&).

DIALOG Statement

Describes a dialog box that is associated with an item on a pull-down menu.

Restriction: Must be followed by at least one TEXT statement.

Featured in: Example 2 on page 701, Example 3 on page 703, and Example 4 on page 710

DIALOG dialog-box command-string

field-number-specification ;

Required Arguments

command-string

is the command or partial command that is executed when the item is selected. The limit of the command-string that results after the substitutions are made is the command-line limit for your operating environment. Typically, the command-line limit is approximately 80 characters .

The limit for command-string field-number-specification is 200 characters.

Note: If you are using PROC PMENU to submit any command that is valid only in the PROGRAM EDITOR window (such as the INCLUDE command), then you must have the windowing environment running, and you must return control to the PROGRAM EDITOR window.

dialog-box

is the same name specified for the DIALOG= option in a previous ITEM statement.

field-number-specification

can be one or more of the following:
@1 @ n
%1 % n
1 & n

You can embed the field numbers, for example @1, %1, or &1, in the command string and mix different types of field numbers within a command string. The numeric portion of the field number corresponds to the relative position of TEXT, RADIOBOX, and CHECKBOX statements, not to any actual number in these statements.
@1 @ n
- are optional TEXT statement numbers that can add information to the command before it is submitted. Numbers preceded by an at sign (@) correspond to TEXT statements that use the LEN= option to define input fields.
%1 % n
- are optional RADIOBOX statement numbers that can add information to the command before it is submitted. Numbers preceded by a percent sign (%) correspond to RADIOBOX statements following the DIALOG statement.
- Note: Keep in mind that the numbers correspond to RADIOBOX statements, not to RBUTTON statements.
&1 & n
- are optional CHECKBOX statement numbers that can add information to the command before it is submitted. Numbers preceded by an ampersand (&) correspond to CHECKBOX statements following the DIALOG statement.
Note: To specify a literal @ (at sign), % (percent sign), or & (ampersand) in the command-string , use a double character: @@ (at signs), %% (percent signs), or && (ampersands).

Details

You cannot control the placement of the dialog box. The dialog box is not scrollable. The size and placement of the dialog box are determined by your windowing environment.
To use the DIALOG statement, specify an ITEM statement with the DIALOG= option in the ITEM statement.
The ITEM statement creates an entry in a menu bar or in a pull-down menu, and the DIALOG= option specifies which DIALOG statement describes the dialog box.
You can use CHECKBOX, RADIOBOX, and RBUTTON statements to define the contents of the dialog box.
Figure 34.2 on page 686 shows a typical dialog box. A dialog box can request information in three ways:
- Fill in a field. Fields that accept text from a user are called text fields .
- Choose from a list of mutually exclusive choices. A group of selections of this type is called a radio box , and each individual selection is called a radio button .
- Indicate whether you want to select other independent choices. For example, you could choose to use various options by selecting any or all of the listed selections. A selection of this type is called a check box .
  
  Figure 34.2: A Typical Dialog Box

Dialog boxes have two or more buttons , such as OK and Cancel, automatically built into the box. ^[*] A button causes an action to occur.

ITEM Statement

Identifies an item to be listed in a menu bar or in a pull-down menu.

Featured in: Example 1 on page 698

ITEM command < option(s) >< action-options >;

ITEM menu-item < option(s) >< action-options >;

To do this		Use this option
Specify the action for the item
	Associate the item with a dialog box	DIALOG=
	Associate the item with a pull-down menu	MENU=
	Associate the item with a command	SELECTION=
	Associate the item with a common submenu	SUBMENU=
Specify help text for an item		HELP=
Define a key that can be used instead of the pull-down menu		ACCELERATE=
Indicate that the item is not an active choice in the window		GRAY
Provide an ID number for an item		ID=
Define a single character that can select the item		MNEMONIC=
Place a check box or a radio button next to an item		STATE=

Required Arguments

command

a single word that is a valid SAS command for the window in which the menu appears. Commands that are more than one word, such as WHERE CLEAR, must be enclosed in single quotation marks. The command appears in uppercase letters on the menu bar.

If you want to control the case of a SAS command on the menu, then enclose the command in single quotation marks. The case that you use then appears on the menu.

menu-item

a word or text string, enclosed in quotation marks, that describes the action that occurs when the user selects this item. A menu item should not begin with a percent sign (%).

Options

ACCELERATE= name-of-key

defines a key sequence that can be used instead of selecting an item. When the user presses the key sequence, it has the same effect as selecting the item from the menu bar or pull-down menu.
Restriction: The functionality of this option is limited to only a few characters. For details, see the SAS documentation for your operating environment.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.

action-option

is one of the following:
DIALOG= dialog-box
- the name of an associated DIALOG statement, which displays a dialog box when the user selects this item.
- Featured in: Example 3 on page 703
MENU= pull-down-menu
- the name of an associated MENU statement, which displays a pull-down menu when the user selects this item.
- Featured in: Example 1 on page 698
SELECTION= selection
- the name of an associated SELECTION statement, which submits a command when the user selects this item.
- Featured in: Example 1 on page 698
SUBMENU= submenu
- the name of an associated SUBMENU statement, which displays a pmenu entry when the user selects this item.
- Featured in: Example 1 on page 698
If no DIALOG=, MENU=, SELECTION=, or SUBMENU= option is specified, then the command or menu-item text string is submitted as a command-line command when the user selects the item.

GRAY

indicates that the item is not an active choice in this window. This option is useful when you want to define standard lists of items for many windows , but not all items are valid in all windows . When this option is set and the user selects the item, no action occurs.

HELP= help-text

specifies text that is displayed when the user displays the menu item. For example, if you use a mouse to pull down a menu, then position the mouse pointer over the item and the text is displayed.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.
Tip: The place where the text is displayed is operating environment-specific .

ID= integer

a value that is used as an identifier for an item in a pull-down menu. This identifier is used within a SAS/AF application to selectively activate or deactivate items in a menu or to set the state of an item as a check box or a radio button.
Minimum: 3001
Restriction: Integers from 0 to 3000 are reserved for operating environment and SAS use.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.
Tip: ID= is useful with the WINFO function in SAS Component Language.
Tip: You can use the same ID for more than one item.
See also: STATE= option on page 689

MNEMONIC= character

underlines the first occurrence of character in the text string that appears on the pull-down menu. The character must be in the text string.

The character is typically used in combination with another key, such as ALT. When you use the key sequence, it has the same effect as putting your cursor on the item. But it does not invoke the action that the item controls.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.

STATE=CHECKRADIO

provides the ability to place a check box or a radio button next to an item that has been selected.
Tip: STATE= is used with the ID= option and the WINFO function in SAS Component Language.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.

Defining Items on the Menu Bar

You must use ITEM statements to name all the items that appear in a menu bar. You also use the ITEM statement to name the items that appear in any pull-down menus . The items that you specify in the ITEM statement can be commands that are issued when the user selects the item, or they can be descriptions of other actions that are performed by associated DIA0LOG, MENU, SELECTION, or SUBMENU statements.

All ITEM statements for a menu must be placed immediately after the MENU statement and before any DIALOG, SELECTION, SUBMENU, or other MENU statements. In some operating environments, you can insert SEPARATOR statements between ITEM statements to produce lines separating groups of items in a pull-down menu. See SEPARATOR Statement on page 693 for more information.

Note: If you specify a menu bar that is too long for the window, then it might be truncated or wrapped to multiple lines.

MENU Statement

Names the catalog entry that stores the menus or defines a pull-down menu.

Featured in: Example 1 on page 698

MENU menu-bar ;

MENU pull-down-menu ;

Required Arguments

One of the following arguments is required:

menu-bar

names the catalog entry that stores the menus.

pull-down-menu

names the pull-down menu that appears when the user selects an item in the menu bar. The value of pull-down-menu must match the pull-down-menu name that is specified in the MENU= option in a previous ITEM statement.

Defining Pull-Down Menus

When used to define a pull-down menu, the MENU statement must follow an ITEM statement that specifies the MENU= option. Both the ITEM statement and the MENU statement for the pull-down menu must be in the same RUN group as the MENU statement that defines the menu bar for the PMENU catalog entry.

For both menu bars and pull-down menus, follow the MENU statement with ITEM statements that define each of the items that appear on the menu. Group all ITEM statements for a menu together. For example, the following PROC PMENU step creates one catalog entry, WINDOWS, which produces a menu bar with two items, Primary windows and Other windows . When you select one of these items, a pull-down menu is displayed.

 libname proclib '  SAS-data-library  ';  proc pmenu cat=proclib.mycat;        /* create catalog entry */     menu windows;     item 'Primary windows' menu=prime;     item 'Other windows' menu=other;        /* create first pull-down menu */     menu prime;     item output;     item manager;     item log;     item pgm;        /* create second pull-down menu */     menu other;     item keys;     item help;     item pmenu;     item bye;     /* end of run group */  run;

The following figure shows the resulting menu selections.

Figure 34.3: Pull-Down Menu

RADIOBOX Statement

Defines a box that contains mutually exclusive choices within a dialog box.

Restriction: Must be used after a DIALOG statement.

Restriction: Must be followed by one or more RBUTTON statements.

Featured in: Example 3 on page 703

RADIOBOX DEFAULT= button-number ;

Required Arguments

DEFAULT= button-number

indicates which radio button is the default.
Default: 1

Details

The RADIOBOX statement indicates the beginning of a list of selections. Immediately after the RADIOBOX statement, you must list an RBUTTON statement for each of the selections the user can make. When the user makes a choice, the text value that is associated with the selection is inserted into the command string of the previous DIALOG statement at field locations prefixed by a percent sign (%).

RBUTTON Statement

Lists mutually exclusive choices within a dialog box.

Restriction: Must be used after a RADIOBOX statement.

Featured in: Example 3 on page 703

RBUTTON <NONE> #line @column

text-for-selection <COLOR= color > <SUBSTITUTE= text-for-substitution >;

Required Arguments

column

specifies the column in the dialog box where the radio button and text are placed.

line

specifies the line in the dialog box where the radio button and text are placed.

text-for-selection

defines the text that appears in the dialog box and, if the SUBSTITUTE= option is not used, defines the text that is inserted into the command in the preceding DIALOG statement.

Note: Be careful not to overlap columns and lines when placing text and radio buttons; if you overlap text and buttons, you will get an error message. Also, specify space between other text and a radio button.

Options

COLOR= color

defines the color of the radio button and the text that describes the button.
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.

NONE

defines a button that indicates none of the other choices. Defining this button enables the user to ignore any of the other choices. No characters, including blanks, are inserted into the DIALOG statement.
Restriction: If you use this option, then it must appear immediately after the RBUTTON keyword.

SUBSTITUTE= text-for-substitution

specifies the text that is to be inserted into the command in the DIALOG statement.
Featured in: Example 3 on page 703

SELECTION Statement

Defines a command that is submitted when an item is selected.

Restriction: Must be used after an ITEM statement

Featured in: Example 1 on page 698 and Example 4 on page 710

SELECTION selection command-string ;

Required Arguments

selection

is the same name specified for the SELECTION= option in a previous ITEM statement.

command-string

is a text string, enclosed in quotation marks, that is submitted as a command-line command when the user selects this item. There is a limit of 200 characters for command-string . However, the command-line limit of approximately 80 characters cannot be exceeded. The command-line limit differs slightly for various operating environments.

Details

You define the name of the item in the ITEM statement and specify the SELECTION= option to associate the item with a subsequent SELECTION statement. The SELECTION statement then defines the actual command that is submitted when the user chooses the item in the menu bar or pull-down menu.

You are likely to use the SELECTION statement to define a command string. You create a simple alias by using the ITEM statement, which invokes a longer command string that is defined in the SELECTION statement. For example, you could include an item in the menu bar that invokes a WINDOW statement to enable data entry. The actual commands that are processed when the user selects this item are the commands to include and submit the application.

Note: If you are using PROC PMENU to issue any command that is valid only in the PROGRAM EDITOR window (such as the INCLUDE command), then you must have the windowing environment running, and you must return control to the PROGRAM EDITOR window.

SEPARATOR Statement

Draws a line between items on a pull-down menu.

Restriction: Must be used after an ITEM statement.

Restriction: Not available in all operating environments.

SEPARATOR;

SUBMENU Statement

Specifies the SAS file that contains a common submenu associated with an item.

Featured in: Example 1 on page 698

SUBMENU submenu-name SAS-file ;

Required Arguments

submenu-name

specifies a name for the submenu statement. To associate a submenu with a menu item, submenu-name must match the submenu name specified in the SUBMENU= action-option in the ITEM statement.

SAS-file

specifies the name of the SAS file that contains the common submenu.

TEXT Statement

Specifies text and the input fields for a dialog box.

Restriction: Can be used only after a DIALOG statement.

Featured in: Example 2 on page 701

TEXT # line @ column field-description

ATTR= attribute > <COLOR= color >;

Required Arguments

column

specifies the starting column for the text or input field.

field-description

defines how the TEXT statement is used. The field-description can be one of the following:
LEN= field-length
- is the length of an input field in which the user can enter information. If the LEN= argument is used, then the information entered in the field is inserted into the command string of the previous DIALOG statement at field locations prefixed by an at sign (@).
- Featured in: Example 2 on page 701
text
- is the text string that appears inside the dialog box at the location defined by line and column .

line

specifies the line number for the text or input field.

Options

ATTR= attribute

defines the attribute for the text or input field. Valid attribute values are
- BLINK
- HIGHLIGH
- REV_VIDE
- UNDERLIN
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.
Restriction: Your hardware may not support all of these attributes.

COLOR= color

defines the color for the text or input field characters. These are the color values that you can use:

BLACK

BROWN

GRAY

MAGENTA

PINK

WHITE

BLUE

CYAN

GREEN

ORANGE

RED

YELLOW
Restriction: This option is not available in all operating environments. If you include this option and it is not available in your operating environment, then the option is ignored.
Restriction: Your hardware may not support all of these colors.

^[*] The actual names of the buttons vary in different windowing environments.

BLACK	BROWN
GRAY	MAGENTA
PINK	WHITE
BLUE	CYAN
GREEN	ORANGE
RED	YELLOW