Command Definition (CMD)
Parameters Examples Error messages |
The Command (CMD) command definition statement specifies the prompt text for the command being created and allows many of the parameters specified on the Create Command (CRTCMD) command to be overridden. The prompt text is displayed when a user requests prompting while entering the command that is being defined.
- Specifying command creation options on the CMD command definition statement ensures that the generated *CMD object has the desired command attributes.
- The command creation parameters on CMD do not have default values. If no value is specified, the value specified or defaulted on the CRTCMD command is used to create the *CMD object.
- If a listing is generated by CRTCMD, the first page will show the parameters passed in from the CRTCMD command. Any of these parameters overridden on the CMD command definition statement will affect the generated *CMD, but will not be reflected on the first page of the CRTCMD listing.
The CMD statement can be anywhere in the source file referred to by the CRTCMD command; one and only one CMD statement must exist in the source file.
Top |
Parameters
Keyword | Description | Choices | Notes |
---|---|---|---|
PROMPT | Prompt text or message ID | Character value, *NONE | Optional, Positional 1 |
PMTFILE | Message file for prompt text | Single values: *NONE Other values: Element list |
Optional |
Element 1: Message file | Qualified object name | ||
Qualifier 1: Message file | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
Element 2: Message text | *STATIC, *DYNAMIC | ||
MSGF | Message file | Qualified object name | Optional |
Qualifier 1: Message file | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
TEXT | Text 'description' | Character value, *SRCMBRTXT, *CMDPMT, *BLANK | Optional |
MAXPOS | Maximum positional parameters | 0-99, *NOMAX | Optional |
ALLOW | Where allowed to run | Single values: *ALL Other values (up to 9 repetitions): *BATCH, *INTERACT, *BPGM, *IPGM, *BREXX, *IREXX, *EXEC, *BMOD, *IMOD |
Optional |
MODE | Mode in which valid | Single values: *ALL Other values (up to 3 repetitions): *PROD, *DEBUG, *SERVICE |
Optional |
ALWLMTUSR | Allow limited users | *NO, *YES | Optional |
THDSAFE | Threadsafe | *YES, *NO, *COND | Optional |
MLTTHDACN | Multithreaded job action | *SYSVAL, *RUN, *MSG, *NORUN | Optional |
VLDCKR | Validity checking program | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Validity checking program | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
PMTOVRPGM | Prompt override program | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Prompt override program | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
HLPID | Help identifier | Character value, *CMD, *NONE | Optional |
HLPPNLGRP | Help panel group | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Help panel group | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
HLPSCHIDX | Help search index | Single values: *NONE Other values: Qualified object name |
Optional |
Qualifier 1: Help search index | Name | ||
Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
CURLIB | Current library | Name, *NOCHG, *CRTDFT | Optional |
PRDLIB | Product library | Name, *NOCHG, *NONE | Optional |
AUT | Authority | Name, *LIBCRTAUT, *USE, *ALL, *CHANGE, *EXCLUDE | Optional |
Top |
Prompt text or message ID (PROMPT)
Specifies the prompt text, if any, that is included in the heading (title) of the prompt display for the command being defined. The prompt text further describes the name of the command.
Note: Prompt text for each of the parameters of this command can be specified in the PROMPT parameters of the PARM, ELEM, and QUAL command definition statements, which specify the prompt text for the parameters, elements, and qualifiers, just as the PROMPT parameter in this statement specifies the prompt text for the command.
- *NONE
- No prompt text is included in the displayed heading of the prompt when the command is being prompted.
- message-identifier
- Specify the message identifier that specifies the message, containing no more than 30 bytes, for the prompt text displayed when the command is being prompted. If a message having the specified identifier cannot be found in the message file specified on the PMTFILE parameter of the Create Command (CRTCMD) command, the message identifier itself is used as the prompt text.
- character-value
- Specify the prompt text that is displayed during the command prompting. It must be a character string of no more than 30 bytes, enclosed in apostrophes.
Variables cannot be coded for this parameter.
Top |
Message file for prompt text (PMTFILE)
Specifies the message file from which the prompt text for the command is retrieved.
Single values
- *NONE
- No message file is needed for the prompt text. The text, if any, is supplied in the definition statements that define the command.
Element 1: Message file for prompt text
Qualifier 1: Message file
- name
- Specify the name of the message file.
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 thread is used to locate the message file. If no library is specified as the current library for the thread, QGPL is used.
- name
- Specify the name of the library where the message file is located.
Element 2: Message text
Specifies how the command being created will use the prompt message information stored in the command object when the command is prompted.
- *STATIC
- When the command is prompted, the prompt text will be retrieved from the static copies of the messages stored in the *CMD object when the command was created. If you want the command to have prompt text in more than one national language, you will need to create a separate *CMD for each national language.
- *DYNAMIC
- When the command is prompted, prompt text messages will be dynamically retrieved from the message file specified for this parameter using the message identifiers stored in the *CMD object when the command was created. The message identifier specified for the PROMPT or CHOICE parameter on a CMD, PARM, QUAL, or ELEM command definition statement must be found in the prompt text message file both when the command is being created and when the command is being prompted.
If an error occurs locating the message file when the command is prompted, all prompt text will be retrieved from the static copies of prompt messages stored in the *CMD object. If the message file is found, but an individual prompt text message is not found in the message file, the static copy of the prompt text stored in the *CMD object is used for that one message.
Creating a command with message identifiers specified for PROMPT and CHOICE, a message file specified the first element of this parameter, and *DYNAMIC specified for the second element results in a single command that can have prompt text in more than one national language. By having a copy of the prompt text message file in the desired national language found in the library list at prompt time, the same command can prompt in any national language. CL commands for the operating system and most IBM products use the *DYNAMIC option to enable a single copy of the command to handle all installed national language versions.
Top |
Message file (MSGF)
Specifies the message file from which messages identified on the Dependency (DEP) command definition statements are retrieved. The Message identifier (MSGID) parameter on the DEP statements lets you specify the message identifier to be sent if a parameter syntax error is detected. For message identifies with a three-character prefix other than 'CPF', the message file specified for this parameter will be used. QCPFMSG is always used for as the message file for messages that have the prefix 'CPF' in the message identifier.
Qualifier 1: Message file
- name
- Specify the name of the message file from which DEP error messages are retrieved.
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 thread is used to locate the message file. If no library is specified as the current library for the thread, QGPL is used.
- name
- Specify the name of the library where the message file is located.
Top |
Text 'description' (TEXT)
Specifies the text that briefly describes the object.
- *SRCMBRTXT
- The text is taken from the source file member used to create the CL command.
- *CMDPMT
- The text description will be the same as the command title shown when the command is prompted.
- *BLANK
- No text is specified.
- character-value
- Specify no more than 50 bytes of text, enclosed in apostrophes.
Top |
Maximum positional parameters (MAXPOS)
Specifies the maximum number of parameters that can be specified positionally (without the parameter keyword) for this command. This parameter value must be greater than the number of nonconstant required parameters and less than the total number of nonconstant parameters. Parameters of TYPE(*ZEROELEM), parameters with the CONSTANT attribute, and lists and qualified names whose ELEMs and QUALs have the CONSTANT attribute or are of TYPE(*ZEROELEM) are not included in the number of parameters that can be coded positionally for this command.
- *NOMAX
- No maximum positional coding limit is specified for this command.
- 0-99
- Specify the maximum number of positional parameters.
Top |
Where allowed to run (ALLOW)
Specifies where the command can be processed.
Single values
- *ALL
- The command can be processed in a batch input stream, in a CL program, in a REXX procedure, in a CL ILE module, or when processed interactively. It can also be passed to the system API programs QCMDEXC, QCAEXEC, and QCAPCMD for processing.
Other values (up to 9 repetitions)
- *BATCH
- The command can be processed in a batch input stream, external to a compiled CL program.
- *INTERACT
- The command can be processed interactively, external to a compiled CL program.
- *BPGM
- The command can be processed in a compiled CL program that is called from batch entry.
- *IPGM
- The command can be processed in a compiled CL program that is called from interactive entry.
- *BREXX
- The command can be used in a REXX procedure run in a batch job.
- *IREXX
- The command can be used in a REXX procedure run in an interactive job.
- *BMOD
- The command can be used in a batch CL ILE program only.
- *IMOD
- The command can be used in a interactive CL ILE program only.
- *EXEC
- The command can be used as a parameter on the CALL command and be passed as a character string to the system API programs QCMDEXC, QCAEXEC, and QCAPCMD for processing. If *EXEC is specified, either *BATCH or *INTERACT must also be specified.
Top |
Mode in which valid (MODE)
Specifies the modes of operating environment to which the newly defined command applies.
Single values
- *ALL
- The command is valid in all the types of modes: production, debug, and service.
Other values (up to 3 repetitions)
- *PROD
- The command is valid for production mode operations.
- *DEBUG
- The command is valid for debug mode operations.
- *SERVICE
- The command is valid for service mode operations.
Top |
Allow limited users (ALWLMTUSR)
Specifies whether a user whose profile is set for limited capabilities is allowed to use the command by typing it in the command line on a menu.
- *NO
- This command cannot be entered in the command line on a menu by a user whose profile is set for limited capabilities.
- *YES
- This command can be entered in the command line on a menu by a user whose profile is set for limited capabilities.
Top |
Threadsafe (THDSAFE)
Specifies whether the command is threadsafe and can be used safely in a job that has multiple threads.
- *NO
- The command is not threadsafe and should not be used in a job that has multiple threads.
- *YES
- The command is threadsafe and can be used safely in a job that has multiple threads.
- *COND
- The command is threadsafe under certain conditions. See the online help or other documentation for the command to determine the conditions under which the command is threadsafe.
Top |
Multithreaded job action (MLTTHDACN)
Specify the multithreaded job action for this command.
- *SYSVAL
- The multithreaded job action specified in the QMLTTHDACN system value is used.
- *RUN
- Run the command.
- *MSG
- Run the command and send a diagnostic message.
- *NORUN
- Do not run the command.
Top |
Validity checking program (VLDCKR)
Specifies the program that performs additional validity checking on the parameters in the command being created. The same parameters that are passed to the command processing program (CPP) are also passed to the validity checking program. The validity checker performs additional parameter checking beyond that specified by the command definition statements in the source file, and beyond normal control language syntax checking. More information on validity checking is in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Single values
- *NONE
- There is no separate validity checking program for this command. All validity checking is done by the command analyzer and the command processing program. Whenever the command is processed or checked for validity, provided variables and expressions are not used.
Qualifier 1: Validity checking program
- name
- Specify the name and library of the validity checking program that checks the validity of the command.
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 thread is used to locate the program. If no library is specified as the current library for the thread, QGPL is used.
- name
- Specify the name of the library where the validity checking program is located.
Top |
Prompt override program (PMTOVRPGM)
Specifies the name and library of the prompt override program (POP) that will replace (on the prompt display) the default values with the current actual values specified for the parameter. If a POP is specified, the key parameters (specified as KEYPARM(*YES) on the PARM statement in the command definition source) are the only parameters visible on the initial prompt display. When values are input for the key parameters, the remaining parameters are shown on the display with the actual values instead of the default values.
- *NONE
- No prompt override program is specified.
Note: If *NONE is specified when key parameters exist in the command definition source (that is when KEYPARM(*YES) is specified on the PARM statement), a warning message is issued when the command is created, and KEYPARM(*NO) will be assumed for all parameters.
- name
- Specify the name of the prompt override program for the command.
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 thread is used to locate the prompt override program. If no library is specified as the current library for the thread, QGPL is used.
- name
- Specify the name of the library where the prompt override program is located.
Top |
Help identifier (HLPID)
Specifies the root name for all help section identifiers for this command. All help sections in the help panel group associated with this command will begin with this name.
- *NONE
- No help identifier is specified. *NONE is not allowed if a panel group name is specified for the Help panel group (HLPPNLGRP) parameter.
- *CMD
- The name of the command is to be used as the root for help section identifiers in the help panel group.
- name
- Specify the root name for the help section identifiers for this command.
Top |
Help panel group (HLPPNLGRP)
Specifies the help panel group for this command.
Single values
- *NONE
- No help panel group is specified.
Qualifier 1: Help panel group
- name
- Specify the name of the help panel group for this command.
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 thread is used to locate the panel group. If no library is specified as the current library for the thread, QGPL is used.
- name
- Specify the name of the library where the panel group is located.
Top |
Help search index (HLPSCHIDX)
Specifies the help search index to use when the search index function key is pressed from the help screen.
Single values
- *NONE
- No help search index is associated with this command.
Qualifier 1: Help search index
- name
- Specify the name of the search index to be used when the search index function key is pressed.
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 thread is used to locate the search index. If no library is specified as the current library for the thread, the QGPL library is used.
- name
- Specify the name of the library where the search index is located.
Top |
Current library (CURLIB)
Specifies the name of the current library associated with the job being run.
Note: This library is also the current library when the validity checker program (if any) is processed for the command.
- *NOCHG
- The current library does not change for the processing of this command. If the current library is changed during processing of the command, the change remains in effect after command processing is complete.
- *CRTDFT
- No current library is active during the processing of the command. The current library that was active before command processing began is restored when processing is completed.
If *CURLIB was specified as the to-value for any single values or special values for this command, or for any command processed while no current library is active, the QGPL library is used as the current library.
- name
- Specify the name of the library that is used as the current library. The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the current library is restored to its previous value. If the current library is changed during command processing by the Change Library List (CHGLIBL) command or Change Current Library (CHGCURLIB) command, the change is effective only until the command is processed. QTEMP cannot be specified for the current library.
Top |
Product library (PRDLIB)
Specifies the product library that is to be in effect during the processing of the command.
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 menu started.
- *NOCHG
- The product library is not changed when processing of the command starts. If the product library is changed during the processing of the command, the change remains in effect after command processing is complete.
- *NONE
- There is no product library in the job's library list. The product library is restored to its previous value when command processing is complete.
- name
- Specify the name of the library to be used as the product library during command processing. The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the product library is restored to its previous value. QTEMP cannot be specified for the product library.
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 on the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified on the Create authority (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. Users included on the authorization list are granted authority to the object as specified by the list. The authorization list must exist when the object is created.
Top |
Examples
Example 1: Defining the Command-level Prompt Text
CMD PROMPT(UCD0001)
This statement describes a command that is prompted with additional text in the display heading. The command prompt text comes from the message identified by UCD0001. The message file which contains message identifier UCD0001 must be specified on the PMTFILE parameter of the Create Command (CRTCMD) command used to create the command definition object.
Example 2: Defining Prompt Text and Command Creation Options
CMD PROMPT(UCD0002) PMTFILE(MYCMDPMT *DYNAMIC) + MSGF(MYCMDMSG) TEXT(*CMDPMT) MAXPOS(2) + PRDLIB(MYAPPLIB) HLPID(*CMD) HLPPNLGRP(MYAPPHLP)
This statement will set the prompt text for the command from message UCD0002 in message file MYCMDPMT which is located using the library list. All prompt text messages defined for the command will be retrieved dynamically when the command is prompted. Error messages sent from Dependency (DEP) statements in the command definition will be found in message file MYCMDMSG which is located using the library list. The text for the command object will be the same as the command prompt text. Only the first two parameters of the command will be allowed to be specified in positional form without the associated parameter keyword. When the command is run, library MYAPPLIB will be automatically added to the library list before the command is run and removed from the library list when the command completes. The help identifier for the command help modules in panel group MYAPPHLP will all start with the name of the command object being created by the CRTCMD command.
Top |
Error messages
None
Top |