Display Directory Entries (DSPDIRE)

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

The Display Directory Entries (DSPDIRE) command is used to display, print, or create a database file for some or all system distribution directory entries. The database file output is displayed, printed, or created based on the following:

For displayed output, when the USRID or the USER parameters apply to more than one directory entry, the system provides a list of entries. When these parameters uniquely identify a directory entry, the system provides the details for the entry.
For printed or database file output, if the USRID parameter specifies the full directory, the DETAIL parameter determines whether a list of the entries or the full details for each entry is the output. If the USRID or the USER parameters specify a user ID or profile, the full details for that user are sent to the output.

The DSPDIRE command does not update the directory. That function is provided interactively, with display support by the Work with Directory Entries (WRKDIRE) command, the Add Directory Entry (ADDDIRE) command, the Remove Directory Entry (RMVDIRE) command, the Change Directory Entry (CHGDIRE) command, and the Rename Directory Entry (RNMDIRE) command.

Top

Parameters

Keyword	Description	Choices	Notes
USRID	User identifier	Single values: *ALL Other values: Element list	Optional, Positional 1
	Element 1: User ID	Character value
	Element 2: Address	Character value
USER	User profile	Name, *CURRENT	Optional, Positional 2
OUTPUT	Output	, PRINT, *OUTFILE	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
DETAIL	Detail	BASIC, FULL	Optional
OUTFILFMT	Outfile format	TYPE1, TYPE2, *TYPE3	Optional
OUTDTA	Data to output	LCL, ALL	Optional
CMDCHRID	Command character identifier	Single values: SYSVAL, DEVD Other values: Element list	Optional
	Element 1: Graphic character set	Integer
	Element 2: Code page	Integer

Top

User identifier (USRID)

Specifies the user ID and address of the user for whom the directory entries are displayed, printed, or directed to a database file. If the USRID parameter is specified, the USER parameter cannot be specified.

For displayed output, if the user ID and address specify an entry that has only one description, the directory details for that entry are displayed. If several descriptions are associated with the specified user ID and address, a list of matching user IDs and addresses is displayed from which the user can select a user ID and address to view the details.

For printed output or database file output, the full directory details, including all descriptions for that user ID and address, are printed or sent to a database file. More information on specifying the user ID and address is in the SNA Distribution Services book, SC41-5410.

*ALL: All entries in the system distribution directory are displayed, printed, or directed to a database file. The entries are provided in alphabetical order by user ID and address. If the output is directed to a printed list or output file, the DETAIL parameter specifies whether a list of user IDs, addresses, and descriptions is the output or if the full directory detail is the output.

The possible user ID value is:

user-ID: Specify the user ID of the user for whom an existing directory entry is displayed, printed, or directed to a database file.

The possible user address value is:

user-address: Specify the user address of the user for whom an existing directory entry is displayed, printed, or directed to a database file.

Top

User profile (USER)

Specifies a user profile for which directory entries are displayed, printed, or written to a database file. If the USER parameter is specified, the USRID parameter cannot be specified.

For displayed output, if the profile specifies an entry that has only one description associated with it, the directory details for that entry are displayed. If multiple descriptions are associated with the specified profile, a list of all the user IDs and addresses matching the profile is displayed. The user can then select a user ID and address to view the details.

*CURRENT: The user profile under which the current job is running is used.
user-profile-name: Specify a user profile name whose corresponding directory entry details are the output.

Top

Output (OUTPUT)

Specifies whether the output from the command is shown at the requesting work station, printed with the job's spooled output, or written to an output file.

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

Top

File to receive output (OUTFILE)

Specifies the qualified name of the database file to which the output of the display is directed. If the database file does not exist, this command creates it in the specified library. If no library is specified, the database file is created in the user default library specified in the user profile. If no default library is specified, the database output file is created in the QGPL library.

If the database file is qualified with *LIBL but the system cannot find the file, the database file is created in the user's default library, if it is specified in the user profile. If the default library is not specified, the file is created in the QGPL library.

See the OUTFILFMT parameter for the valid output file types and their names.

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

*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 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 *LIBL but the system cannot find the file, one is created in the user's default library, if specified. If the default library is not specified, the file is created in the QGPL library.

Top

Output member options (OUTMBR)

Specifies the name of the database file member to which the output is directed. If a member already exists, the system uses the second element of this parameter to determine whether the member is cleared before the new records are added. If the member does not exist and a member name is not specified, the system creates a member with the name of the output file specified on the OUTFILE parameter. If an output file member name is specified, but the member does not exist, the system creates it.

The possible member to receive output values are:

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

The possible operation to perform on member values are:

*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

Detail (DETAIL)

Specifies how much detail is printed or directed to the database file. This parameter is not used when the output is directed to a display (OUTPUT(*)) or when a specific user ID or profile is specified.

*BASIC: The output is a list of all user IDs, addresses, and descriptions contained in the directory.
*FULL: The output is the full set of details for the user in the directory. When USRID(*ALL) is specified, the printed list contains a page for each unique user ID and address from the directory, with all of the details for that entry. Multiple descriptions for a user ID and address are included with the details. For a database file, a record is created for each unique user ID, address, and description, containing all of the details for each entry. When several descriptions exist for a user ID and address, a full record is the output for each description, and only the description field is different.
When a user ID and address or user profile name is specified on an input parameter, the printed list contains one page of output with all descriptions included with the details for the user ID and address. The output file has a full detail record for each description. Only the description field is different between the records.

Top

Outfile format (OUTFILFMT)

Specifies the format of the output file.

*TYPE1: The format is defined by model output file QAOSDIRO in library QSYS with record format name OSDIRE. This format does not include the new directory fields added since Release 2.0.
*TYPE2: The output file format is defined by model output files QAOSDIRB and QAOSDIRF in library QSYS.
If DETAIL(*BASIC) is specified, the output file contains only the basic fields, and the model output file QAOSDIRB is used with the record format name OSDIRB. If DETAIL(*FULL) is specified, the output file contains all of the detail fields, and the model output file QAOSDIRF is used with the record format name OSDIRF.
*TYPE3: The output file contains all the detail fields and the X.400 originator/recipient (O/R) name. The model output file QAOSDIRX in library QSYS is used with the record format name OSDIRX.

Top

Data to output (OUTDTA)

Specifies the type of data to include as output to the value specified on the OUTPUT parameter. This parameter is not used when the output is directed to a display (OUTPUT(*)) or when a specific user ID or profile is specified.

*LCL: Locally-defined data is included. Shadowed data is not included.
*ALL: All directory entry data is included. This includes locally-defined data and shadowed data.

Top

Command character identifier (CMDCHRID)

Specifies the character identifier (graphic character set and code page) for data being specified as parameter values on this command. This character identifier (CHRID) is related to the display device used to specify the command. More information about CHRID processing is in Application Display Programming book, SC41-5715.

*SYSVAL: The system determines the graphic character set and code page values for the command parameters from the QCHRID system values.
*DEVD: The system determines the graphic character set and code page values for the command parameter from the display device description where the command is entered. This option is valid only when specified from an interactive job. If this value is specified in an interactive CL program or a batch job, an error message is sent.

The possible character set value is:

graphic-character-set: Specify the graphic character set values used to create the command parameters. Valid values range from 1 through 9999.

The possible code page value is:

code-page: Specify the code page. Valid values range from 1 through 9999.

Top

Examples

Example 1: Showing the Display for One Description

DSPDIRE   USRID(HURST NEWYORK)

This command shows the Display Directory Entry Details display for user ID and address HURST NEWYORK if this user ID has only one description associated with it. If more than one description exists, the Display Directory Entries display is shown with all entries for the user ID and address.

Example 2: Printing Directory Information

DSPDIRE   USER(JONES)  OUTPUT(*PRINT)

This command prints the full directory details for user profile JONES. If there is more than one description in the directory for JONES, the printed output contains each description.

Example 3: Sending Full Details to a Database File

DSPDIRE   OUTPUT(*OUTFILE)
          OUTFILE(MYLIB/DIRLIST)  OUTMBR(*FIRST *REPLACE)
          DETAIL(*FULL)

This command sends a record to the database file DIRLIST in library MYLIB for each entry in the directory. This record contains the full details for each user. The format of the output file is the one used prior to Release 3.0 because of the default of OUTFILFMT(*TYPE1). If the file does not exist, it is created. If the file does exist, it is replaced.

Example 4: Sending Basic Information to a Database File

DSPDIRE   OUTPUT(*OUTFILE)
          OUTFILE(MYLIB/DIRLIST)  DETAIL(*BASIC)
          OUTFILFMT(*TYPE2)

This command sends a record to the database file named DIRLIST in the MYLIB library for each entry in the directory. The data contains only the basic fields, user ID, address, and description. If the file named DIRLIST in the MYLIB library already exists for releases 1.0 or 2.0 data (see Example 2), an error occurs; otherwise, the file is be created in the Release 3.0 format.

Top

Error messages

*ESCAPE Messages

CPF2204: User profile &1 not found.
CPF9006: User not enrolled in system distribution directory.
CPF9009: System requires file &1 in &2 be journaled.
CPF905C: Error occurred trying to find a translation table.
CPF9096: Cannot use CMDCHRID(*DEVD), DOCCHRID(*DEVD) in batch job.
CPF9820: Not authorized to use library &1.
CPF9822: Not authorized to file &1 in library &2.
CPF9838: User profile storage limit exceeded.
CPF9845: Error occurred while opening file &1.
CPF9846: Error while processing file &1 in library &2.
CPF9847: Error occurred while closing file &1 in library &2.
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.

Top