DSPPGMREF (Display Program References) Command Description
DSPPGMREF Command syntax diagram
Purpose
The Display Program References (DSPPGMREF) command provides a list of the system objects to which the specified programs refer.
- Program Type
- System Objects
- BASIC
- *FILE (externally described) and *PGM
- C
- No information is provided for programs in C except for ILE C (program type CLE)
- CBLLE
- *FILE, *PGM, and *SRVPGM
- CL
- *FILE, *PGM, and *DTAARA
- CLE
- *SRVPGM
- CLLE
- *FILE, *PGM, *DTAARA, and *SRVPGM
- COBOL
- *FILE and *PGM (literal names on the CALL command)
- CSP
- *FILE, *PGM, *MSGF, *CSPMAP, and *CSPTBL
- PASCAL
- No information is provided for programs in Pascal
- PL/I
- *FILE and *PGM
- RPG
- *FILE, *DTAARA, *PGM
- RPGLE
- *FILE, *PGM, *DTAARA, and *SRVPGM
This information can be shown, printed, or written to (stored in) a database output file (an OUTFILE).
If the information is shown or printed, a list (by library) of the specified user-authorized programs, along with the objects referenced by each program, is created. For files, information about how each file is used (input, output, update, unspecified, or any combination of these four) is also shown or printed.
If the information is written to a database file, the database file will have a record format named QWHDRPPR. The fields in record format QWHDRPPR are the same as the fields in the IBM-supplied format QWHDRPPR in file QADSPPGM in the library QSYS. The following information is contained in the database file:
- The name of the program and its text description
- The name of the library containing the program
- The number of objects referenced by the program
- The qualified name of the system object
- The information retrieval dates
- The object type of the referenced object
For files, the record contains the following additional fields:
- The name of the file in the program (possibly different from the system object name if an override was in effect when the program was created)
- The program use of the file (1=input, 2=output, 4=update, 8=unspecified, or a number representing a combination of any of these four; for example, a code of 11 is a combination of 1, 2, and 8, which is input, output, and unspecified)
- The number of record formats referenced, if any
- The name of the record format used by the file and its record format level identifier
- The number of fields referenced for each format
Note: This command lists which objects are referenced when the object is created or updated using UPDPGM or UPDSRVPGM. The referenced object names and libraries listed may be different than the actual names of the objects, since this information is stored when the program is created. Entries can be added as the ILE program or service program is updated using UPDPGM or UPDSRVPGM, but entries are never removed. If the object has been moved since the program was created, or an override was in effect during creation, the names listed may differ from the actual names. Restrictions:
- The user must have object operational authority for the program.
- Also, of the libraries specified by the library qualifier, only the libraries for which the user has read authority are searched for the programs.
Required Parameter
- PGM
- Specifies the qualified name of the program (or all programs) that has a list of the files and other related system objects that are referenced by the program. A specific program name or a generic program name is specified; either type can be optionally qualified by a library name. Only the libraries in the specified library qualifier that the user either owns or is authorized to use are searched for the program(s).
The name of the program 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.
*USRLIBL: Only the libraries in the user portion of the job's library list are searched.
*ALL: All libraries in the system, including QSYS, are searched.
library-name: Specify the name of the library to be searched.
*ALL: All programs in the specified library (or all the libraries identified in the library qualifier to which the user has access) have their information shown.
generic*-program-name: Specify the name of the program or the generic name of several programs in the specified library (or all libraries identified in the library qualifier) that has information shown. 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.
program-name: Specify the name of the program to have information shown.
Optional Parameters
- OUTPUT
- Specifies whether the output from this command is displayed, printed, or directed to a database file. More information on this parameter is in commonly used parameters.
*: Output requested by an interactive job is shown on the display. Output requested by a batch job 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.
- OBJTYPE
- Specifies the object type for which information is displayed.
*PGM: Only program information is displayed.
*ALL: Program information and SQL package information are displayed.
*SQLPKG: Only SQL package information is displayed.
*SRVPGM: Service program information is displayed.
*MODULE: Module information is displayed.
- OUTFILE
- Specifies the qualified name of the database output file in which the program-related information is written.
When creating the database output file, the current date, time, and system name must be included. The system name is the name of the source system, not the target system. If the specified file does not exist, the system creates a database output file and member. If the file is created, the description text is 'Outfile for DSPPGMREF' and the public authority is *EXCLUDE.
Note: The format of the output file must be the same as QWHDRPPR of the system file QADSPPGM. More information on the OUTFILE format is in the Database Programming topic in the Information Center. 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 output file in which the program-related information is placed. If the specified file is not found, a file by that name is created and stored in the specified library, or in *CURLIB if not qualified. This file can be used again when other DSPPGMREF commands are entered. The IBM-supplied database file QADSPPGM cannot be specified.
- OUTMBR
- Specifies the name of the database file member to which the output is directed.
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. If the member exists, the user has the option to add records to the end of the existing member or to clear the existing member and add the new records.
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: Operation to Perform on Member
*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.
Examples for DSPPGMREF
Example 1: Storing a List of Programs
DSPPGMREF PGM(LIBRARY1/*ALL) OUTPUT(*OUTFILE) OUTFILE(LIB2/FILE2)This command creates a list of all authorized programs found in LIBRARY1, and of the files and other system objects that the programs reference. It stores the list in a database file named FILE2 in LIB2.
Example 2: Printing a List of Objects
DSPPGMREF PGM(LIBRARY1/BILLING) OUTPUT(*PRINT)This command creates a list of system objects that are referenced by the BILLING program in LIBRARY1. The output is spooled for printing.
Additional Considerations
When the DSPPGMREF command is entered, the library is searched for the program or programs specified on the PGM parameter; then a group of records that give system object-related information about each program is created. The records are placed in the printer device file named QPDSPPGM. If OUTPUT(*PRINT) is specified on the command, the records are listed on the printer in the following order:
- Header information: Lists the DSPPGMREF command input values.
- Program-related information: Lists, for each program identified by the PGM parameter, all of the system objects (including files) that are referenced by the program. If more than one program is identified, the beginning of the next one follows the end of the previous one.
If the DSPPGMREF command is entered interactively and OUTPUT(*) is specified or assumed, the records in the printer device file are shown instead of being printed.
Error messages for DSPPGMREF
*ESCAPE Messages
- CPF3033
- Object &1 in library &2 not found.
- CPF3034
- Object &1 in library &2 not displayed.
- CPF3052
- Description for file &1 not available.
- CPF3061
- Record format &3 not found for outfile &1.
- CPF3063
- Output file &1 in &2 not physical file.
- CPF3064
- Library &1 not found.
- CPF3066
- Error creating output file &1 in &2.
- CPF3067
- Error while opening file &1 in &2.
- CPF3068
- Error while writing to file &1 in &2.
- CPF3069
- Error while closing file &1 in &2.
- CPF3070
- Error creating member &3 in file &1.
- CPF3072
- File &1 in &2 is a system file.
- CPF3074
- Not authorized to library &1.
- CPF3075
- Library &1 not available.
- CPF3076
- Error occurred when on display.
- CPF3077
- Error occurred when canceling display.
- CPF3084
- Error clearing member &3 in file &1.