Display Program References (DSPPGMREF)

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

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:

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

You must have object operational (*OBJOPR) authority for the program. Also, of the libraries specified by the library qualifier, only the libraries for which you have execute (*EXECUTE) authority are searched for the programs.

Top

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

Top

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

'xxxxx' is the number of a primary auxiliary storage pool (ASP).
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.

Top

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.

Top

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.

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.

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

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

Top

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.

Top