Create Menu (CRTMNU)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The Create Menu (CRTMNU) command is used to create a menu object. Both Display File (*DSPF) and Program (*PGM) menus can be created by using this command. A menu can be displayed using the Go to Menu (GO) command.

Restrictions:

You must have change (*CHANGE), read (*READ), and add (*ADD) authorities for the library where the menu is to be created.

Top

Parameters

Keyword	Description	Choices	Notes
MENU	Menu	Qualified object name	Required, Positional 1
	Qualifier 1: Menu	Name
	Qualifier 2: Library	Name, *CURLIB
TYPE	Menu type	DSPF, PGM, *UIM	Required, Positional 2
DSPF	Display file	Qualified object name	Optional
	Qualifier 1: Display file	Name, *MENU
	Qualifier 2: Library	Name, LIBL, CURLIB
MSGF	Message file	Qualified object name	Optional
	Qualifier 1: Message file	Name, *MENU
	Qualifier 2: Library	Name, LIBL, CURLIB
CMDLIN	Command line	LONG, SHORT, *NONE	Optional
DSPKEY	Display function keys	NO, YES	Optional
PGM	Program	Qualified object name	Optional
	Qualifier 1: Program	Name, *MENU
	Qualifier 2: Library	Name, LIBL, CURLIB
SRCFILE	Source file	Qualified object name	Optional
	Qualifier 1: Source file	Name, QMNUSRC
	Qualifier 2:	Name, LIBL, CURLIB
SRCMBR	Source member	Name, *MENU	Optional
OPTION	Source listing options	Values (up to 3 repetitions): SOURCE, NOSOURCE, SRC, NOSRC, NOSECLVL, SECLVL, NOEVENTF, EVENTF	Optional
INCFILE	Include file	Single values: *SRCFILE Other values: Qualified object name	Optional
	Qualifier 1: Include file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
CURLIB	Current library	Name, NOCHG, MNULIB, *CRTDFT	Optional
PRDLIB	Product library	Name, NOCHG, NONE	Optional
CHRID	Character identifier	Integer, DEVD, JOBCCSID, *CHRIDCTL	Optional
REPLACE	Replace menu	YES, NO	Optional
TEXT	Text 'description'	Character value, SRCMBRTXT, BLANK	Optional
AUT	Authority	Name, LIBCRTAUT, CHANGE, ALL, USE, *EXCLUDE	Optional

Top

Menu (MENU)

Specifies the menu to be created.

This is a required parameter.

Qualifier 1: Menu

name: Specify the name of the menu.

Qualifier 2: Library

*CURLIB: The current library for the job is used to store the new menu. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the menu is to be stored.

Top

Menu type (TYPE)

Specifies the type of menu to be created.

Note: *DSPF must be specified for values to be specified for the Display file (DSPF) and Message file (MSGF) parameters. The Program (PGM) parameter is valid only if *PGM is specified here.

This is a required parameter.

*DSPF: An existing display file and message file are used to create a menu.
*PGM: The menu being created calls a program when the menu is requested.
*UIM: The menu is created using the UIM tag language found in the file specified for the Source file (SRCFILE) and Source member (SRCMBR) parameters.

Top

Display file (DSPF)

Specifies the display file to be used in creating the menu object. The display file must include one record format with the same name as the display file itself, called the menu format. Help formats may also be included in the file.

Help formats follow the naming convention #Hxxyy, where xx is the first and yy is the last menu option to which the help format applies. For example, #H0306 would apply to menu options 3 to 6. #H0000 designates the general help for the menu.

The display file must have a separate indicator area (INDARA keyword) and contain no subfile descriptions.

This parameter can be specified only if *DSPF is specified for the Menu type (TYPE) parameter.

Qualifier 1: Display file

*MENU: The display file has the same name as the menu name specified for the Menu (MENU) parameter.
name: Specify the name of the display file to be used.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the display file. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the display file is located.

Top

Message file (MSGF)

Specifies the message file containing the commands to run when a menu option is selected. The MSGIDs of the messages in this file are of the form USRxxxx where xxxx is the menu option number typed on the command line.

Note: If the message file being created is to be used for menus, you must add message file members to the file using the Add Message Description (ADDMSGD) command.

Qualifier 1: Message file

*MENU: The message file containing the commands to run has the same name as the menu name specified for the Menu (MENU) parameter.
name: Specify the name of the message file to be used.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the message file. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the message file is located.

Top

Command line (CMDLIN)

Specifies whether a long command line, a short command line, or no command line (an option line) is used.

*LONG: A 153-byte long command line is used.
*SHORT: A 73-byte long command line is used.
*NONE: No command line is used. A 4-byte option line is used.

Top

Display function keys (DSPKEY)

Specifies whether the function key legend appears at the bottom of the menu when the menu is shown.

*NO: The function key legend is not shown at the bottom of the display.
*YES: The function key legend is shown at the bottom of the display.

Top

Program (PGM)

Specifies the program to call when the menu is shown.

Three parameters are passed to the program:

The first parameter is the ten-character name of the menu object which identifies the program to call.
The second parameter is the ten-character name of the library containing the menu object.
The third parameter is a two-character binary return code declared as a variable in the called program. The program must set one of the following return codes:

    Return
     Code   Hex     Description
       0    0000    Call the program
                    (display the menu) again
      -1    FFFF    Exit function requested
      -2    FFFE    Previous function requested
      -4    FFFC    Home function requested
                    (display the home menu)

Qualifier 1: Program

*MENU: The program called has the same name as the menu name specified for the Menu (MENU) parameter.
name: Specify the name of the program to be called.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the program. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the program is located.

Top

Source file (SRCFILE)

Specifies the source file containing the menu description source statements.

Qualifier 1: Source file

QMNUSRC: The source file QMNUSRC contains the menu description source statements.
name: Specify the name of the source file containing the menu description source statements.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the source file. If no library is specified as the current library for the job, the QGPL library is used.
name: Specify the name of the library where the source file is located.

Top

Source member (SRCMBR)

Specifies the member of the source file containing the menu description.

*MENU: The member name is the same as the menu name specified for the Menu (MENU) parameter.
name: Specify the name of the source file member containing the menu description.

Top

Source listing options (OPTION)

Specifies options for the output produced during the compile. Multiple option values can be specified in any order on this parameter. If neither or both of the values in each group are specified, the underlined value will be used.

Note: The underlined values for this parameter are similar to, but not actually default values, and therefore, cannot be changed with the Change Command Default (CHGCMDDFT) command.

Source Listing Option

*SRC or *SOURCE: A source listing is produced.
*NOSRC or *NOSOURCE: No source listing is produced unless errors are detected.

Second-Level Message Text Option

*NOSECLVL: Second-level text is not provided with the first-level text when the messages are printed at the end of the listing.
*SECLVL: Second-level text is provided with the first-level text when the messages are printed at the end of the listing.

Event File Creation Option

*NOEVENTF: The compiler does not produce an event file for the CoOperative Development Environment (CODE).
*EVENTF: The compiler produces an event file that can be used by the CODE product. The event file is created as a member in the file EVFEVENT in your object library. The CODE product uses this file to offer error feedback integrated with the CODE editor. This value is normally specified by the CODE product on your behalf.

Top

Include file (INCFILE)

Specifies the source file containing the members to be included.

Note: If the coded character set identifier (CCSID) of the source file is different than the CCSID of the primary source file specified for the Source file (SRCFILE) parameter, the CCSID is changed to the CCSID of the primary source file. The CCSID must be the same for all source members used to create the object.

Single values

*SRCFILE: The include file is the same file as the file specified for the SRCFILE parameter.

Qualifier 1: Include file

name: Specify the name of the source file containing the members to be included.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the source file. If no library is specified as the current library for the job, the QGPL library is used.
name: Specify the name of the library where the source file is located.

Top

Current library (CURLIB)

Specifies the library used as the current library when menu is shown.

*NOCHG: The current library does not change for the processing of this menu.
*MNULIB: The current library is changed to the library containing the menu while the menu is shown.
*CRTDFT: There is no current library when the menu is shown.
name: Specify the library name used as the current library when the menu is shown.

Top

Product library (PRDLIB)

Specifies the library used as the product library when the menu is shown.

Note: The product library for a command or menu remains in the library list while a command or menu is active, unless another command or menu changes the product library. When a command or menu that changed the product library ends, the product library is restored to what it was when the command or library started.

*NOCHG: The product library is not changed when the menu is shown and is not restored after exiting the menu.
*NONE: The product library entry in the library list is not used while the menu is shown.
name: Specify the library name used as the product library when the menu is shown.

Top

Character identifier (CHRID)

Specifies whether the character identifier (graphic character set and code page) of the menu object is changed to the character identifier of the device when the menu is displayed.

Note: This parameter can be specified only if *UIM is specified for the Menu type (TYPE) parameter.

*DEVD: No change occurs. The character identifier of the menu object is the same as the character identifier of the device.
*JOBCCSID: The character identifier of the menu object is changed from the CCSID of the file specified for the Source file (SRCFILE) parameter to the character identifier of the device.
*CHRIDCTL: The system checks the CHRIDCTL job attribute to determine whether to use *JOBCCSID or *DEVD on the CHRID command parameter for this menu.

Top

Replace menu (REPLACE)

Specifies whether an existing menu with the same name is replaced.

Note: The menu cannot be replaced if it is in use by this job or another job.

*YES: The existing menu is moved to the system library QRPLOBJ and replaced with the new menu.
*NO: The existing menu is not replaced with the new menu.

Top

Text 'description' (TEXT)

Specifies the descriptive text associated with the menu.

*SRCMBRTXT: The text for the menu is obtained from the text associated with the source file member. Please note that this special value will only retrieve the text from the source file member if the menu is a *UIM type. For other menu types, the text will be set to blanks.
*BLANK: No text description is given for the menu.
character-value: Specify no more than 50 characters of text, enclosed in apostrophes.

Top

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*LIBCRTAUT: The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.

*USE: The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.

*EXCLUDE: The user cannot access the object.

name: Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Top

Examples

CRTMNU   MENU(ARLIB/ARPERS)  TYPE(*PGM)

This command creates a menu named ARPERS in library ARLIB. The menu calls a program (also named ARPERS) when the menu is run.

Top

Error messages

*ESCAPE Messages

CPF6AC3: Menu not created.

Top