Display Program References (DSPPGMREF)

The Display Program References (DSPPGMREF) command provides a list of the system objects referred to by the specified programs. The following list shows the system objects provided for the respective program types:

BAS
*FILE (externally described) and *PGM
C
no information is provided for C-language programs except for ILE C-language programs (CLE)
CBLLE
*FILE, *PGM, and *SRVPGM
CLP
*FILE, *PGM, and *DTAARA
CLE
*SRVPGM
CLLE
*FILE, *PGM, *DTAARA, and *SRVPGM
CBL
*FILE and *PGM (literal names on CALL command)
CSP
*FILE, *PGM, *MSGF, *CSPMAP, and *CSPTBL
PAS
no information is provided for programs in PASCAL
PLI
*FILE and *PGM
RPG
*FILE, *DTAARA, and *PGM
RPGLE
*FILE, *PGM, *DTAARA, and *SRVPGM
QRYDFN
*FILE

This information can be displayed, printed, or placed in a database output file.

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:

For files, the record contains the following additional fields:

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. For a query definition, this command list which files are referenced when the object is created or updated using some of the Query for IBM i commands.

Restrictions:

Parameters

Keyword Description Choices Notes
PGM Program Qualified object name Required, Positional 1
Qualifier 1: Program Generic name, name, *ALL
Qualifier 2: Library Name, *LIBL, *CURLIB, *USRLIBL, *ALLUSR, *ALL
OUTPUT Output *, *PRINT, *OUTFILE Optional, Positional 2
OBJTYPE Object type Single values: *ALL
Other values (up to 5 repetitions): *PGM, *SQLPKG, *SRVPGM, *MODULE, *QRYDFN
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

Program (PGM)

Specifies the programs whose information is shown.

This is a required parameter.

Qualifier 1: Program

*ALL
The information is shown for all programs and query definitions in the library or libraries.
name
Specify the full name of a program. Information is shown only for the specified program.
generic-name
Specify a generic program name. Information is shown for all programs whose names begin with the specified characters.

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 thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
*USRLIBL
If a current library entry exists in the library list for the current thread, the current library and the libraries in the user portion of the library list are searched. If there is no current library entry, only the libraries in the user portion of the library list are searched.
*ALLUSR
All user libraries are searched. All libraries with names that do not begin with the letter Q are searched except for the following:

#CGULIB     #DSULIB     #SEULIB
#COBLIB     #RPGLIB
#DFULIB     #SDALIB

Although the following Qxxx libraries are provided by IBM, they typically contain user data that changes frequently. Therefore, these libraries are considered user libraries and are also searched:

QDSNX       QRCLxxxxx   QUSRDIRDB   QUSRVI
QGPL        QSRVAGT     QUSRIJS     QUSRVxRxMx
QGPL38      QSYS2       QUSRINFSKR
QMGTC       QSYS2xxxxx  QUSRNOTES
QMGTC2      QS36F       QUSROND
QMPGDATA    QUSER38     QUSRPOSGS
QMQMDATA    QUSRADSM    QUSRPOSSA
QMQMPROC    QUSRBRM     QUSRPYMSVR
QPFRDATA    QUSRDIRCF   QUSRRDARS
QRCL        QUSRDIRCL   QUSRSYS

  1. 'xxxxx' is the number of a primary auxiliary storage pool (ASP).
  2. A different library name, in the format QUSRVxRxMx, can be created by the user for each previous release supported by IBM to contain any user commands to be compiled in a CL program for the previous release. For the QUSRVxRxMx user library, VxRxMx is the version, release, and modification level of a previous release that IBM continues to support.
*ALL
All libraries in the system, including QSYS, are searched.
name
Specify the name of the library to be searched.

Output (OUTPUT)

Specifies where the output from the command is sent.

*
The output is displayed (if requested by an interactive job) or printed with the job's spooled output (if requested by a batch job).
*PRINT
The output is printed with the job's spooled output.
*OUTFILE
The output is directed to the database file specified for the File to receive output (OUTFILE) parameter.

Object type (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.
*QRYDFN
Query definition information is displayed.

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.

Note: The outfile format must be the same as QWHDRPPR of the system file QADSPPGM in library QSYS. More information on the OUTFILE format is in the Database category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

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.

Examples

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.

Example 3: Displaying a List of Files Used by a Query Definition

DSPPGMREF   PGM(LIBRARY1/QUERY1) OBJTYPE(*QRYDFN)  OUTPUT(*)

This command displays a list of files that are referenced by the QUERY1 query definition in LIBRARY1.

Error messages

*ESCAPE Messages

CPF3033
Object &1 in library &2 of type &3 not found.
CPF3034
Object &1 in library &2 of type &3 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.