Each command description follows the same format and includes the parts
discussed in the following paragraphs.
At the beginning of the command description documentation, there are links to
the Parameters, Examples, and Error messages sections.
It should be noted that, because a command is an OS/400(R)
object, each command can be authorized for specific users or authorized for
use by the public (all users authorized in some way to use the system).
Because this is true for nearly every command, it is not stated in each
command description. The iSeries Security
Reference
book contains additional information about IBM(R)-supplied user
profiles and the commands authorized for each.
Environment and threadsafe classification
At the very top of the command description documentation are environment and threadsafe classifications. Where allowed to run: indicates in which environments the command can be run. Threadsafe: indicates whether a command is threadsafe.
For more details about environment, see Environment. For more details about threadsafe classifications,
see Threadsafe classification.
Command description
The general description of the command follows the environment and threadsafe
classification.
It briefly explains the function of the command and any relationships it has
with a program or with other commands. If there are restrictions on the
use of the command, they are described under the heading
"Restrictions."
Parameters
The Parameters section provides a parameter summary table.
The parameter summary table shows all the parameters and values that are valid
for the command. Possible values are indicated in the Choices
column. The default value, as shipped by IBM, is underlined in the
Choices column. The default values are used by the system for
parameters or parts of parameters that are not coded.
See Parameter summary table for more details.
Parameter descriptions
Parameter descriptions follow the parameter summary table. Parameter
descriptions are presented in the same order as the parameters are listed in
the parameter summary table. Each parameter description includes an
explanation of the function of the parameter, followed by a description of
each possible parameter value. The default parameter value, if there
is one, is usually described first and is shown as an underlined heading at
the beginning of the text that describes the value.
The description of each parameter explains what the parameter means, what it specifies, and the dependent relationships it has with other parameters in the command. When the parameter has more than one value, the information that applies to the parameter as a whole is covered first, then the specific information for each of the values is described after the name of each value.
Command coding examples
The Examples section provides at least one coded example for the command. Where necessary, several examples are provided for commands with many parameters and several logical combinations.
For clarity, examples are coded in keyword form only. The same examples
could be coded either in positional form or in a combination of keyword and
positional forms, for commands that support one or more positional
parameters.
See Code disclaimer information (page ***) for information pertaining to code examples.
Error messages
The Error messages section lists error messages that can be
issued for the command.
Where allowed to run indicates in which environments the command can be entered. This is the same information that is shown in the output of the Display Command (DSPCMD) command, which reflects what was specified for the ALLOW parameter when the command definition object was created. The "Where allowed to run" value includes the symbolic special values specified for the ALLOW parameter and a brief description that explains the environments where the command is allowed to run.
The majority of commands are created with ALLOW(*ALL); *ALL is also the shipped default value for the ALLOW parameter. In this case, the description will be "All environments (*ALL)".
For commands that must be run interactively, the ALLOW values specified when the command was created are usually (*INTERACT *IPGM *IREXX *EXEC) or (*INTERACT *IPGM *IMOD *IREXX *EXEC). In these two cases, the description shown will be "Interactive environments (*INTERACT *IPGM *IREXX *EXEC)" or "Interactive environments (*INTERACT *IPGM *IMOD *IREXX *EXEC)".
For commands that are created to be run only in a compiled CL or interpreted REXX program, the ALLOW values specified when the command was created are usually (*BPGM *IPGM *BREXX *IREXX) or (*BPGM *IPGM *BMOD *IMOD *BREXX *IREXX). In these two cases, the description shown will be "Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX)" or "Compiled CL or interpreted REXX (*BPGM *IPGM *BMOD *IMOD *BREXX *IREXX)".
If the combination of values specified for the ALLOW parameter when the command was created is not one of the above combinations, a bulleted list is shown that gives a brief description of each value that was specified.
Note: Some command definition objects shipped as part of
OS/400(R) are not intended to be used as CL commands. For
example, the CMD and PARM command definition objects are used in command
definition source. These special-purpose command objects will not have
any "Where allowed to run" information.
The threadsafe classification indicates whether a command is threadsafe. Each command has a threadsafe classification. The three types of threadsafe classifications are as follows:
This classification indicates that you can safely call the command simultaneously in multiple threads without restrictions. This classification also indicates that all functions called by this command are threadsafe.
This classification indicates that not all functions provided by the command are threadsafe. The Restrictions section of the command provides information relating to thread safety limitations. Many commands are classified conditionally threadsafe because either some underlying system support is not threadsafe or the command can cause an exit point to be called. Some conditionally threadsafe commands may deny access under some circumstances. The command restriction section describes the conditions that cause the command to deny access.
This classification indicates that the command is not threadsafe and should not be used in a multithreaded program. While some thread unsafe commands may deny access, most thread unsafe commands do not. A diagnostic message, CPD000D, may be sent to the job log to indicate that a non-threadsafe command has been called. Whether or not the diagnostic message CPD000D is sent to the job log depends on the "multithreaded job action" attribute of the command; that attribute can be determined by using the Display Command (DSPCMD) command. The possible values and actions are:
If the command is run, the results are unpredictable.
Note: Some command definition objects shipped as part of OS/400(R) are not intended to be used as CL commands. For example, the CMD and PARM command definition objects are used in command definition source. These special-purpose command objects will not have any "Threadsafe" information.
The parameter summary table summarizes parameters and values for CL commands. The parameter summary table replaces the syntax diagrams used in past releases.
See the following topics for information about parameter summary table format.
This column shows the parameter keyword name. Every CL command parameter has a keyword name associated with it. When you are viewing the command documentation using a browser, you can click on the keyword name to link to the start of the information for the parameter within the command documentation file.
This column shows the prompt text defined for the parameter, a parameter qualifier, or a parameter element. Qualifiers are normally used for qualified object names or qualified job names. Elements are used to define multiple input fields for a single parameter. The description for a qualifier or element contains the qualifier or element number within the parameter.
This column shows the possible values for the parameter, qualifier, or element.
This column shows additional information about each parameter.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.