DSPOPT (Display Optical) Command Description

DSPOPT Command syntax diagram

Purpose

The Display Optical (DSPOPT) command displays volume, directory, or file attributes depending on the value specified on the DATA parameter. The information can be printed, displayed, or written to an output file. If the output is directed to an outfile it will have one of the following record formats:

When DATA(*VOLATR) is specified the database file will have a record format named QAMODVA. The fields in the database are the same as the fields in the IBM-supplied format QAMODVA in file QAMODVAF located in library QSYS.

When DATA(*DIRATR) is specified the database file will have a record format named QAMODPA. The fields in the database are the same as the fields in the IBM-supplied format QAMODPA in file QAMODPAF located in library QSYS.

When DATA(*FILATR) is specified the database file will have a record format named QAMODFA. The fields in the database are the same as the fields in the IBM-supplied format QAMODFA in file QAMODFAF located in library QSYS.

Restriction: To use this command have *USE authority to the authorization list securing the volumes being displayed.

Required Parameter

VOL
Specifies the identifier of the optical volume which contains the information being shown.

*ALL: The information is shown for all optical volumes on the specified directly attached optical device (DEV parameter).

*MOUNTED: The information is shown for the volume mounted on the specified device (DEV parameter).

Note: This value is valid only for optical devices, not for library devices.

volume-identifier: Specify the identifier of an optical volume.

generic*-volume-identifier: Specify the generic name of the volume identifier. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic names, refer to generic names.

Optional Parameters

DEV
Specifies the name of the optical device containing the optical volume whose information is displayed.

Note: This parameter is ignored when a specific volume name is specified on the VOL parameter.

*ALL: The volume attributes are displayed for optical volumes on all directly attached optical devices.

Note: This value is valid only when VOL(*ALL) or VOL(generic*) is specified.

optical-device: Specify the name of an optical device.

DATA
Specifies the type of information that is displayed when specified on the PATH parameter. If DATA(*SAVRST) is specified, the information includes a description of each object saved to the optical file and summary information about the saved objects. To determine whether the volume being displayed contains data in the basic stream file format or in the save and restore format, you can specify DATA(*FILATR) and check the data file identifiers listed.

*VOLATR: The volume attributes for the specified volume or volumes are displayed.

*DIRATR: The directory attributes for the specified directory or directories are displayed.

*FILATR: The file attributes for the specified file or files are displayed.

*SAVRST: The specified files contain save and restore data. Summary information is displayed for the command and each saved object.

PATH
Specifies the path name of the directory or the file on the volume being displayed, beginning with the root directory of the volume. The DATA parameter indicates whether the directory or the file attributes are displayed. The object path name can be either a simple name or a name that is qualified with the name of the directory in which the object is located. A pattern can be specified in the last part of the path name. An asterisk (*) matches any number of characters. If the path name is qualified or contains a pattern, it must be enclosed in apostrophes.

Note: This parameter is ignored if DATA(*VOLATR) is specified.

path-name: Specify either a path for a directory or file. The DATA parameter indicates whether directory or file attributes will be displayed for the specified path.

A pattern can be specified in the last part of the name by specifying an asterisk as the last character. If a pattern is specified, all files or directories with names that begin with the specified characters will be displayed.

*ALL can be specified in the last part of the name. If specified, all files or directories in the specified path will be displayed.

*ALL: *ALL can have different meanings based on how parameter DATA is specified. Following is a list of combinations and their meanings.

  • DATA(*VOLATR) and PATH(*ALL), the PATH parameter is ignored.

  • DATA(*SAVRST) and PATH(*ALL), all save/restore files for all directories on the volume will be listed.

  • DATA(*SAVRST) and PATH(/directory1/*ALL), all save/restore files in the path /directory1 will be listed.

  • DATA(*DIRATR) and PATH(*ALL), all directories attributes for all directories on the volume will be listed.

  • DATA(*DIRATR) and PATH(/directory1/*ALL), all directories attributes for directories in the path /directory1 will be listed.

  • DATA(*FILATR) and PATH(*ALL), all file attributes for files in the root directory (/) of the volume will be listed.

  • DATA(*FILATR) and PATH(/directory1/*ALL), all file attributes for files in /directory1 of the volume will be listed.

OUTPUT
Specifies whether the output from the command is displayed at the requesting work station, printed with the job's spooled output, added to a database file or directed to a user space.

*: Output requested by an interactive job is shown on the display. If the command is run as part of a batch job, the output is printed with the job's spooled output.

*PRINT: The output is printed with the job's spooled output.

*OUTFILE: The output is directed to the database file specified on the OUTFILE parameter.

*USRSPC: The output is added to the user space specified on the USRSPC parameter.

USRSPC
Specifies the qualified name of the user space to which the output of the display is added.

Note: This parameter is valid only if OUTPUT(*USRSPC) is specified.

The name of the user space can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

user-space-name: Specify the name of the user space that receives the output.

REPLACE
Indicates whether to replace an existing user space.

Note: This parameter is valid only if OUTPUT(*USRSPC) is specified and is ignored if the user space is not found in the specified library.

*YES: The user space is replaced if found. The existing authorities of the original user space are retained, but the contents are replaced.

*NO: The user space is not replaced if found. The request ends and a message is sent to the job log indicating that the user space already exists in the library and cannot be created.

OUTFILE
Specifies the name of the database file to which the output of the display is added.

Note: This parameter is valid only if OUTPUT(*OUTFILE) is specified.

The name of the database file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

database-file-name: Specify the name of the database file that receives the output of the display. If the database file is qualified with the *LIBL value but the system cannot find the file, one is created in the user's default library. If a default library is not specified, the file is created in library QGPL.

OUTMBR
Specifies the name of the database file member to which the output is directed.

Note: This parameter is valid only if OUTPUT(*OUTFILE) is specified.

Element 1: Member to Receive Output

*FIRST: The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified on the OUTFILE parameter.

member-name: Specify the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.

Element 2: Action on Member

*REPLACE: The data currently contained in the output file member is replaced with the output of this command.

*ADD: The new records are added to the existing information in the specified database file member.

Examples for DSPOPT

Example 1: Displaying Attributes for All Optical Volumes 

DSPOPT   VOL(*ALL)  DEV(*ALL)

This command displays the volume attributes for all volumes in all local optical devices and libraries.

Example 2: Displaying Attributes Using a Generic Search 

DSPOPT   VOL(PAY*)  DATA(*DIRATR)  PATH('/*')

This command displays the attributes for all directories in the root directory of all optical volumes beginning with the characters PAY.

Example 3: Displaying Attributes of a Specific Directory 

DSPOPT   VOL(VOL01)  DEV(OPT01)  DATA(*FILATR)
  PATH('/DIR1/DIR2/*')

This command displays the file attributes for all files in the directory /DIR1/DIR2 of optical volume VOL01.

Example 4: Displaying Save and Restore Data 

DSPOPT   VOL(*MOUNTED)  DEV(OPT01)  DATA(*SAVRST)
  PATH('*ALL')

This command displays the save and restore data for all files found on the optical volume mounted in device OPT01.

Error messages for DSPOPT

*ESCAPE Messages

CPF1247
Subsystem &1 cannot start prestart job &2.
CPF384C
Error occurred during CCSID conversion.
CPF3864
&2 &1 in &3 not restored.
CPF386A
File not found.
CPF5729
Not able to allocate object &1.
CPF9810
Library &1 not found.
CPF9815
Member &5 file &2 in library &3 not found.
CPF9845
Error occurred while opening file &1.
CPF9850
Override of printer file &1 not allowed.
CPF9851
Overflow value for file &1 in &2 too small.
CPF9860
Error occurred during output file processing.
OPT1115
File not found.
OPT1125
File is in use.
OPT1135
Request failed because number of open files is at the limit.
OPT1140
Unexpected error occurred during file processing.
OPT1185
Cannot access held optical file.
OPT1205
Directory not found.
OPT1212
Directory in use.
OPT1224
Path length exceeds the maximum of 256 bytes.
OPT1247
User space &1 not created in library &2.
OPT1255
File is corrupted.
OPT1317
Directory name is too long.
OPT1320
Optical volume &1 in use.
OPT1325
Optical volume format not recognized.
OPT1330
Optical volume not found or not useable.
OPT1331
Optical volume &1 not found.
OPT1340
Optical volume &1 not initialized.
OPT1346
Operation not allowed to volume located in a remote optical device.
OPT1360
Media directory corrupted on optical volume &1.
OPT1427
A generic or *ALL volume request is not allowed with DATA value.
OPT1460
Optical volume &1 is not in an optical device.
OPT1463
Operation not completed, optical volume is not a primary volume.
OPT1489
Volume parameter is not permitted for device &1.
OPT1530
&1 does not represent a valid optical device.
OPT1555
Optical device &1 in use.
OPT1605
Media or device error occurred.
OPT1640
Error occurred reading files or directories.
OPT1790
Operation conflicts with another request.
OPT1805
Error accessing optical volume index file.
OPT1810
Error accessing optical directory index file.
OPT1813
Unexpected error occurred.
OPT1815
Internal program error occurred.
OPT1820
Internal error occurred on optical device &1.
OPT1821
Internal error occurred on optical device &1.
OPT1825
Optical indexes are incorrect for optical device &1.
OPT1860
Request to optical device &1 failed.
OPT1861
No device description configured for resource &1.
OPT1862
No active device description for resource &1.
OPT1863
Optical libraries need to be reclaimed.
OPT1872
Optical request timed out.
OPT2040
Error accessing backup control file.
OPT2301
Internal system object in use.
OPT6713
Display volume details failed.
OPT7740
User not authorized to object &2 in library &3 type &4.