Display Optical (DSPOPT)

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

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.

If the output is directed to a user space, the first 140 bytes of the user space will be header data, followed by the requested attribute data in the same format as in the equivalent outfile.

The 8 bytes starting at offset 72 (48 hex) in the header data indicate the type of attribute data in the user space in character format.
- QMODVA indicates volume attribute data.
- QMODPA indicates directory attribute data
- QMODFA indicates file attribute data.
The 4 bytes starting at offset 128 (80 hex) in the header data indicate the total size of the attribute data in binary format.
The 4 bytes starting at offset 132 (84 hex) in the header data indicate the number of attribute entries in binary format.
The 4 bytes starting at offset 136 (88 hex) in the header data indicate the size of the attribute entry in binary format.

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

Top

Parameters

Keyword	Description	Choices	Notes
VOL	Volume identifier	Character value, ALL, MOUNTED	Required, Positional 1
DEV	Optical device	Name, *ALL	Optional, Positional 2
DATA	Data type	VOLATR, SAVRST, FILATR, DIRATR	Optional, Positional 3
OUTPUT	Output	, PRINT, OUTFILE, USRSPC	Optional
PATH	Path	Character value, *ALL	Optional
USRSPC	User space	Qualified object name	Optional
	Qualifier 1: User space	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
REPLACE	Replace user space	YES, NO	Optional
OUTFILE	File to receive output	Qualified object name	Optional
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
OUTMBR	Output member options	Element list	Optional
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	REPLACE, ADD

Top

Volume identifier (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 directly-attached 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 will result in the display of all volumes in directly attached optical devices which begin with the generic prefix and 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.

Top

Optical device (DEV)

Specifies the directly-attached 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 in 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 a directly-attached optical device.

Top

Data type (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.

Top

Output (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.

Top

Path (PATH)

Specifies the path name of the directory or the file on the volume being displayed. 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.

*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.

path-name

Specify the fully qualified directory or file name which is to have its attributes listed.

generic*-path-name

Specify the generic name of the path identifier. A generic name is a character string of one or more characters followed by an asterisk (*); for example, /directory1/file*. The asterisk substitutes for any valid characters. A generic name will result in the display of all directories or files attributes which begin with the generic prefix and 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.

Top

User space (USRSPC)

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

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

Qualifier 1: User space

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

Qualifier 2: Library

*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.

Top

Replace user space (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.

Top

File to receive output (OUTFILE)

Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.

Qualifier 1: File to receive output

name: Specify the name of the database file to which the command output is directed.

Qualifier 2: Library

*LIBL: The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
*CURLIB: The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.

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

Top

Output member options (OUTMBR)

Specifies the name of the database file member that receives the output of the command.

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 for the File to receive output (OUTFILE) parameter. If the member already exists, you have the option to add new records to the end of the existing member or clear the member and then add the new records.

name: Specify the name of the file member that receives the output. If it does not exist, the system creates it.

Element 2: Replace or add records

*REPLACE: The system clears the existing member and adds the new records.

*ADD: The system adds the new records to the end of the existing records.

Top

Examples

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.

Top

Error messages

*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 not allowed or 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: 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 or was cancelled.
OPT2040: Error accessing backup control file.
OPT2301: Internal system object in use.
OPT2420: Not authorized to optical volume &2.
OPT2422: Not authorized to file or directory.
OPT6713: Display volume details failed.
OPT7740: User not authorized to object &2 in library &3 type &4.

Top