Generate Command Documentation (GENCMDDOC)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Generate Command Documentation (GENCMDDOC) command generates an output file which contains documentation for a Control Language (CL) command. The generated file will be one of the following:
- If *HTML is specified for the Generation options (GENOPT) parameter, the file will contain HyperText Markup Language (HTML) source. The generated file can be displayed using a standard internet browser, and conforms to HTML 4.0 specifications. The information used to generate the file is retrieved from the specified command (*CMD) object and any command help panel group (*PNLGRP) objects associated with the command.
- If *UIM is specified for the GENOPT parameter, the file will contain User Interface Manager (UIM) source. The generated source is an outline for the online command help for the command. The information used to generate the file is retrieved only from the specified command (*CMD) object. This option is intended to simplify the task of writing online help for CL commands.
See the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/, for more information on writing command documentation using UIM.
Restrictions:
- You must have use (*USE) authority to the specified command and execute (*EXECUTE) authority for the library that the command is in. If a generic name or *ALL is specified for the command name, no output file is generated for any commands that you do not have *USE authority for.
- For each associated panel group that contains command help information for the specified command, you must have *USE authority to the panel group and *EXECUTE authority for the library that the panel group is in.
- You must have execute (*X) authority to the directories in the path for the generated file, and write and execute (*WX) authorities to the parent directory of the generated file.
- If the output file does not exist, the public authority will be determined by the os400.file.create.auth Java property value. If this Java property has not been set, the public authority for a created stream file is set to *RW.
- If the output file already exists, you must have write (*W) authority to the file and *YES must be specified for the Replace file (REPLACE) parameter.
- This command does not support proxy CL commands.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| CMD | Command | Qualified object name | Required, Positional 1 |
| Qualifier 1: Command | Generic name, name, *ALL | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| TODIR | To directory | Path name, '.' | Optional |
| TOSTMF | To stream file | Character value, *CMD | Optional |
| REPLACE | Replace file | *YES, *NO | Optional |
| GENOPT | Generation options | Values (up to 3 repetitions): *HTML, *UIM, *NOSHOWCHOICEPGMVAL, *SHOWCHOICEPGMVAL, *NOSERVICE, *SERVICE | Optional |
| Top |
Command (CMD)
Specifies the command for which a documentation output file is to be generated.
Note: If a generic command name or *ALL is specified for the command name, *LIBL is not allowed as the library name qualifier and the value for the To stream file (TOSTMF) parameter must be *CMD.
This is a required parameter.
Qualifier 1: Command
- *ALL
- Documentation files for all of the commands in the specified library are to be generated.
- generic-name
- Specify the generic name of the commands for which documentation files are to be generated. A generic name is a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, all commands that have names with the same prefix as the generic command name will have documentation files generated.
- name
- Specify the name of the command for which you want to generate a documentation output 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 job is used to locate the command. If no library is specified as the current library for the job, QGPL is used.
- name
- Specify the name of the library where the command is located.
| Top |
To directory (TODIR)
Specifies the directory in which the generated command documentation file will be stored. The file name to be used within this directory is specified by the To stream file (TOSTMF) parameter.
- '.'
- The output file will be stored in the current working directory.
- path-name
- Specify the path name for the directory where you want the generated output file stored.
| Top |
To stream file (TOSTMF)
Specifies the target stream file to be used to store the generated command documentation file. The specified file will be located using the directory path specified for the To directory (TODIR) parameter.
Note: If a generic command name or *ALL is specified for the Command (CMD) parameter, the value specified or defaulted for this parameter must be *CMD.
- *CMD
- If the TODIR parameter specifies that the target is in the /QSYS.LIB file system, the generated file name will be same as the command name.
Otherwise, the generated file name depends on whether *HTML or *UIM is specified for the Generation options (GENOPT) parameter. If *HTML is specified, the generated file name will be libname_cmdname.html, where cmdname is the command name and libname is the name of the library where the command is located. If *UIM is specified, the generated file name will be libname_cmdname.uim
- character-value
- Specify the name to be used for the generated command documentation file.
| Top |
Replace file (REPLACE)
Specifies whether or not to replace an existing file in the target directory (TODIR parameter) by the file name specified or generated (TOSTMF parameter).
- *YES
- If a file already exists by the name specified or implied, the file contents will be replaced with the generated command documentation file.
- *NO
- If a file already exists by the name specified or implied, an error message is sent and no command documentation file is generated. If no file by the same name exists in the target directory, the file will be created and no error message sent.
| Top |
Generation options (GENOPT)
Specifies options to control the command information to be generated. 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.
Generated Source Option
- *HTML
- The generated file will contain HyperText Markup Language (HTML) source. The generated file can be displayed using a standard internet browser, and conforms to HTML 4.0 specifications. The information used to generate the file is retrieved from the specified command (*CMD) object and any command help panel group (*PNLGRP) objects associated with the command.
- *UIM
- The generated file will contain User Interface Manager (UIM) source. The generated source is an outline for the online command help for the command. The information used to generate the file is retrieved only from the specified command (*CMD) object. This option is intended to simplify the task of writing online help for CL commands. After editing the generated file to add descriptive text for the command and storing the source in a source file member, this UIM source can be used as input to the Create Panel Group (CRTPNLGRP) command to create a command help panel group for the command.
See the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/, for more information on writing command documentation using UIM.
Choice Program Values Option
- *NOSHOWCHOICEPGMVAL
- For command parameters that have an associated choices program, do not show the values which would be returned from the choices program in the generated parameter summary table. Choices program values can vary from system to system. Not showing the choices program values gives you just the parameter values defined in the command object.
- *SHOWCHOICEPGMVAL
- For command parameters that have an associated choices program, show the values returned from calling the choices program in the generated parameter summary table. Showing the choice program values gives you the same parameter values that you would see if prompting the command on this system.
Service Option
- *NOSERVICE
- No extra trace or dump information is generated.
- *SERVICE
- This option is intended to be used if the command is not working and you are told by your software service provider to write an APAR for the problem. Specifying this option will cause additional trace and dump information to be generated. Send this additional generated information with the APAR.
| Top |
Examples
Example 1: Generating HTML Documentation for an IBM i Command
GENCMDDOC CMD(CRTUSRPRF)
This command generates a documentation file for the CRTUSRPRF command. The command will be located using the library list for the current thread. The generated stream file will be stored in the current working directory of the job. Assuming the command is found in library QSYS, the generated file name will be QSYS_CRTUSRPRF.html. If a file by that name already exists in the target directory, it will be replaced by the generated file.
Example 2: Generating UIM Documentation for User Command
GENCMDDOC CMD(MYLIB/MYCMD)
TODIR('/QSYS.LIB/MYLIB.LIB/QPNLSRC.FILE')
TOSTMF('MYCMD.MBR') REPLACE(*NO) GENOPT(*UIM)
This command generates a documentation file for command MYCMD which is located in library MYLIB. The generated file will be stored in file QPNLSRC in library MYLIB with a member name of MYCMD. If a member already exists in the target file with this name, an error message will be sent and no documentation file will be generated.
| Top |
Error messages
*ESCAPE Messages
- CPF6E74
- &1 command documents failed; &2 command documents created successfully.
- CPF6E75
- Error detected on the CMD parameter.
- CPF9801
- Object &2 in library &3 not found.
- CPF9802
- Not authorized to object &2 in &3.
- CPF9810
- Library &1 not found.
- CPF9820
- Not authorized to use library &1.
- CPF9899
- Error occurred during processing of command.
- CPFA09C
- Not authorized to object. Object is &1.
- CPFA0A0
- Object already exists. Object is &1.
- CPFA0A9
- Object not found. Object is &1.
- CPF6E67
- Command documentation not generated for proxy command &1 in &2.
| Top |