QRYDST (Query Distribution)

QRYDST Command syntax diagram

 

Purpose

The Query Distribution (QRYDST) command allows a request for distribution information for the user or on behalf of another user.

 

Restrictions

1. If the current user of this command requests distribution information for another user, the current user must have been granted the authority to work on behalf of the other user by means of the Grant User Permission (GRTUSRPMN) command.
2. If USRID(*ALLAUT) is specified and the current user of this command does not have the authority to work on behalf of the other user, only the information about the current user's distributions is returned.
3. DLTSTS does not apply to incoming distributions. When OPTION(*IN) is specified, the DLTSTS parameter is ignored.
4. The requester of the command (the user who is signed on) must be enrolled in the system distribution directory.
5. Personal distribution cannot be questioned if the requester is working on behalf of another user.

Note:

The formats of the output files must be OSLIN or OSLOUT. These formats are defined in the physical files QAOSILIN or QAOSILOT, respectively. These files are located in library QSYS. Users can specify the Create Duplicate Object (CRTDUPOBJ) command to create duplicates of these files for their libraries. If the user's library does not contain the files, the files are created when the command is run.

 

Optional Parameters

USRID

Specifies the user ID and address of the user making this request. The user specifying this command must have authority to work on behalf of the user specified in this parameter if the named user ID and address differs from that of the current user.

*CURRENT: The user profile that is currently running is used.

*ALLAUT: Distribution information is returned for users who have given the current user of this command the authority to work on their behalf.

Element 1: User ID

user-ID: Specify the user ID of the user for whom the distribution information is returned.

Element 2: User Address

user-address: Specify the user address of the user for whom the distribution information is returned.

OPTION

Specifies the type of distribution information that is returned.

*IN: Information about incoming distributions is returned. If an output file is specified in the OUTFILE parameter, one incoming distribution information record per distribution is written to the output file.

*OUT: Information about outgoing distributions is returned. If an output file is specified, N outgoing distribution information records per distribution are written to the output file. N is the number of original receivers of the distribution or the number of receivers that have distribution errors.

DLTSTS

Specifies whether the status being kept for outgoing distributions is deleted from the system. This can be error or confirmation of delivery status.

*NO: The distribution status is not deleted from the system. The information is kept by the system and can be returned by a request using the QRYDST command.

*YES: The distribution status is deleted if all receivers are at returned status or completed confirmation of delivery status.

Note:

Other products use this status information. Care should be taken not to delete information used by other products to track their distributions.

Status is deleted by the system if all receivers have returned status or the status is returned to another product (such as the OfficeVision) for this user.

OUTFILE

Specifies the qualified name of 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.

For incoming distributions, the system uses QAOSILIN in QSYS with the format name of OSLIN as a model.

For outgoing distributions, the system uses QAOSILOT in QSYS with the format name of OSLOUT as a model.

The authority for users with no specific authority to the output file is *EXCLUDE. More information on defining the format of database files (output file) is in the Office Services Concepts and Programmer's Guide book.

*NONE: The output is not directed to a database file. If *NONE is specified, the output from this command is a completion message containing the number of distributions on the DIA Distribution Recipient Index (*DRX) for the specified category and user.

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 qualified name of the database file that receives the output of the display.

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.

STATUS

Specifies the mail entry status of the distribution for which the user is requesting information. This parameter is valid only if *IN is specified on the OPTION parameter and an output file is specified on the OUTFILE parameter.

*ALL: Distribution information is returned regardless of the distribution's mail entry status.

*NEW: Distribution information is returned only for distributions with a mail entry status of NEW.

*OLD: Distribution information is returned only for distributions with a mail entry status of OLD. A mail entry status of OLD indicates that the distribution has been queried once but has not been processed.

*OPENED: Distribution information is returned only for distributions with a mail entry status of OPENED.

*UNOPENED: Distribution information is returned for distributions with a mail entry status of OLD or NEW.

*LOCAL: Distribution information is returned only for distributions with a mail entry status of LOCAL. A mail entry status of LOCAL indicates that the distribution has been filed on the local system.

*REMOTE: Distribution information is returned only for distributions with a mail entry status of REMOTE. A mail entry status of REMOTE indicates that the distribution has been filed on a remote system.

*FILEPND: Distribution information is returned only for distributions with a mail entry status of FILEPND. A mail entry status of FILEPND indicates that the distribution is being filed on a local or remote system but the filing has not been completed.

*DELETED: Distribution information is returned only for distributions with a mail entry status of DELETED. A mail entry status of DELETED indicates that the document referred to by the distribution has been deleted.

*DAMAGED: Distribution information is returned only for distributions with a mail entry status of DAMAGED. A mail entry status of DAMAGED indicates that the document referred to by the distribution is damaged.

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.

Note:

This value translates the USRID parameter to the character set and code page set of '930 500'. The SNA Distribution Services book contains the character set and code page table for '930 500'.

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

Element 2: Code Page

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

Example for QRYDST

QRYDST  USER(*CURRENT)  OPTION(*IN)
  OUTFILE(*CURLIB/MYFILE)  OUTMBR(*FIRST *ADD)

This command requests information about incoming distributions for the current user of this command. The output is directed to the database file MYFILE in the user's current library and is added to the first member in that file.

Error messages for QRYDST

*ESCAPE Messages

CPF900B

User ID and address &1 &2 not in System Distribution Directory.

CPF900C

Sign on and verify of user failed.

CPF905C

Error occurred trying to find a translation table.

CPF907C

&1 requested distributions completed, acknowledge failed.

CPF9096

Cannot use CMDCHRID(*DEVD), DOCCHRID(*DEVD) in batch job.

CPF9097

Query distribution request failed.

CPF9845

Error occurred while opening file &1.

CPF9847

Error occurred while closing file &1 in library &2.

CPF9860

Error occurred during output file processing.