DSPDIRE (Display Directory Entries)

DSPDIRE Command syntax diagram

Purpose

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:

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.

Optional Parameters

USRID
Specifies the user ID and address of the user for whom the directory entries are displayed, printed, or written 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.

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

Element 1: User ID

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

Element 2: User Address

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

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 that is currently running is used.

user-profile-name: Specify a user profile name whose corresponding directory entry details are the output.

OUTPUT
Specifies whether the output from the command is shown at the requesting workstation, printed with the job's spooled output or written to an output file. More information on this parameter is in commonly used parameters.

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

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

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.

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.

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.

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.

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.

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.

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 the Application Display Programming book.

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

Element 1: Character Set

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

Element 2: Code Page

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

Examples for DSPDIRE

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.

Additional Considerations

Error messages are returned when errors are encountered while processing the DSPDIRE command. If the command is entered interactively, error messages are displayed at the work station. When a batch job enters the command, error messages are returned, and the job that runs the command is responsible for processing them.

If the USRID parameter specifies the user ID and address of a user not currently in the directory, an error message is returned. Likewise, if a user profile not contained in the directory is specified on the USER parameter, an error message is returned.

Error messages for DSPDIRE

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