QRYDOCLIB (Query Document Library)
QRYDOCLIB Command syntax diagram
Purpose
The Query Document Library (QRYDOCLIB) command allows the user to search for documents within the document library to which the user is authorized and to copy information about the documents that satisfy the search request into a database file for processing.
When the QRYDOCLIB command is run, a document list object is created. The document list object is created regardless of whether an output file is produced unless the user specifies *NONE for the DOCL parameter. This document list object is used by the OfficeVision product as well as the SAVDLO command.
Restriction: The current user of this command must have the authority to work on behalf of the specified user ID address. To work on behalf of other users, the user must have special permission granted with the Grant User Permission (GRTUSRPMN) command. Several QRYDOCLIB commands can run concurrently. If the document list name or the output file is the same on more than one QRYDOCLIB command, errors may occur.
Note: The format of the output file must be the same as OSIQDL of the system file, QSYS/QAOSIQDL.
Optional Parameters
- USRID
- Specifies the user ID and address of the user for whom this request is made.
*CURRENT: The user profile that is currently running is used.
Element 1: User ID
user-ID: Specify the user ID of the user for whom the documents are requested.
Element 2: User Address
user-address: Specify the user address of the user for whom the documents are requested.
- OUTFILE
- Specifies the name of the database file to which the output is directed. If the output file does not exist, this command creates a database file in the specified library. If the file is created by this function, the descriptive text is OUTFILE created by QRYDOCLIB and the authority for users without specific authority to the file is *EXCLUDE.
*NONE: The output is not directed to a database file. A message is returned to the user indicating the number of documents that satisfied the search request. More information on defining the format of database files (output files) is in the Office Services Concepts and Programmer's Guide.
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. This file can be reused when other QRYDOCLIB commands are entered. Output from the file can start at the start of the file member or be added to the file, as specified in the OUTMBR parameter. The IBM-supplied database file, QSYS/QAOSIQDL, cannot be specified.
- 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. If the member exists, the system adds records to the end of the member or clears the member and then adds the records.
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.
- OUTDTATYP
- Specifies the type of information about the selected documents that is written to the output file if one is specified on the OUTFILE parameter.
*DFT: A system-created name is used as the default name. The document information record is written to the output file. Specifying OUTDTATYP(*DFT) is equivalent to specifying OUTDTATYP(*DOCD). The following record is written to the output file:
Record Code Description 105 Document Description*ALL: All record formats about the document are written to the output file. These record formats include the following:
Record Code Description 105 Document Description 110 Creation Date 115 Expiration date 120 Document date 125 File date 130 Last document change date 135 Action due date 140 Completion date 145 Author 150 Copy list 155 Document class 160 File cabinet reference 165 Subject 170 Keyword 175 Reference 180 Status 185 Project 190 Last indexed date 195 Last content revision date 200 Last used date 500 Interchange document profile data*DOCD: The document description record is written to the output file.
*DOCCLS: The document class record is written to the output file.
*SUBJECT: The subject records are written to the output file.
*EXPDATE: The expiration date record is written to the output file.
*FILDATE: The file date record is written to the output file.
*CHGDATE: The date of the last change to the document is written to the output file.
*USEDATE: The date of the last usage of the document is written to the output file.
*CRTDATE: The create date record is written to the output file.
*ACTDATE: The action due date record is written to the output file.
*CMPDATE: The completion date record is written to the output file.
*DOCDATE: The document date record is written to the output file.
*AUTHOR: The author records are written to the output file.
*KWD: The keyword records are written to the output file.
*CPYLST: The copy list records are written to the output file.
*REF: The reference record is written to the output file.
*STATUS: The status record is written to the output file.
*PROJECT: The project record is written to the output file.
*FILCAB: The file cabinet reference record is written to the output file.
*IDXDATE: The last indexed date record is written to the output file. OfficeVision text search services must be installed if this value is specified.
*REVDATE: The date of the last revision to the document content is written to the output file.
*IDP: The interchange document profile is written to the output file.
- DOCL
- Specifies the name of the document list. A document list is an object that contains a pointer to each document in the document library that the current user is authorized to request. This list is a copy of the library at the time the search was run. As documents are deleted from or added to the library, the document list is not updated. The document library list name is specified with the name of the user requesting the search. Users can use identical document names. For example, Tom could name his list SALES and so could Mary. The system knows the lists as TOM_SALES and MARY_SALES.
*DFT: A system-created name is used as the default document list name. The default list is the same as the user ID entered in the USRID parameter (TOM_TOM or MARY_MARY).
*NONE: No document list is created.
document-list-name: Specify the name of the document list. Up to 8 characters can be used.
- TEXT
- Specifies the text that briefly describes the document list object. More information on this parameter is in commonly used parameters.
*BLANK: Text is not specified.
'description': Specify no more than 50 characters of text, enclosed in apostrophes.
- TIMLMT
- Specifies the maximum run time (in minutes) the search request can use.
*NOMAX: No time limit for the search is set. All qualified documents are searched.
time-limit: Specify the maximum time limit (in minutes) that the search runs. Up to 4 digits, ranging from 1 through 9999, can be specified for the number of minutes. A two-hour limit is specified as TIMLMT(120). If the search has not been completed when the time limit is reached, the search ends with an informational message followed by a completion message. The output file, and if specified the document list, will contain the documents found within the specified time limit.
- SELLMT
- Specifies the number of documents to select in the search.
*NOMAX: No document limit for the search is set. All qualified documents are selected.
selection-limit: Specify the maximum number of documents to select. A value ranging from 1 through 32767 can be specified. If there are more query requests than the set limit, the document list and the output file contain the information about the selected documents up to this limit. If there is at least one more document that meets the query definition, an informational message is sent before the completion message.
- FLR
- Specifies the folders that are searched to locate the documents that match the query definition specified in the QRYDFN parameter.
*ALL: All of the folders on the system are searched to locate the documents.
*NONE: Documents not located in any folder are searched.
folder-name: Specify the name of the folders to search to locate the documents. A folder name can consist of a series of folder names (FLR1/FLR2/and so on) if the documents being searched for are located in a folder contained in another folder. A maximum of 100 folders can be specified and each folder name can be a maximum of 63 characters in length.
- SCHSUBFLR
- Specifies whether subfolders of the folder specified on the FLR parameter are searched.
*NO: Subfolders are not searched.
*YES: Subfolders of the specified folder are searched.
- QRYDFN
- Specifies whether a query definition is used to select documents. The values specified on this parameter are used to search the document library. If values other than *NONE are specified on both the QRYDFN parameter and QRYTXT parameter, only documents that match both sets of values are selected.
*NONE: No query definition is used to select the documents. All documents that are owned or accessible are selected.
*IF: A query definition is used to select the documents.
To specify the conditions under which documents are selected, a set of values is specified for each condition. Each set contains four values.
- The name of the document profile parameter to be compared
- One of the relational operator values
- The comparison value
- One of the logical operators, *AND or *OR
Values 1 and 3 are compared for the relationship specified by value 2.
Each QRYDFN relational set must be enclosed in parentheses. A maximum of 49 sets (conditions) can be specified.
Element 1: Profile Parameters
profile-parameter: Specify a value representing the profile parameters to be compared.
Value Description *DOCD Document description *DOCCLS Document class *SUBJECT Document subject *DOCDATE Document date *EXPDATE Expiration date *FILDATE File date *CRTDATE Create date *ACTDATE Action due date *CMPDATE Completion date *CHGDATE Last document change date *USEDATE Last used date *DOCTYPE Document type *IDXDATE Last indexed date *REVDATE Last content revision date *AUTHOR Document author *KWD Keyword *CPYLST Copy list *ALWRPL Allow document replacement *OWNER Document owner *PROJECT Document project *REF Reference *STATUS Document status *ASP Auxiliary storage pool IDElement 2: Relational Operator
relational-operator: Specify the operator that indicates the relationship that must exist between the profile parameter contents in the document and the value specified as the third part of this QRYDFN relation for the relation to be true. The operators that can be used are:
Value Description *EQ Equal *GT Greater than *LT Less than *NE Not equal *GE Greater than or equal *NL Not less than *LE Less than or equal *NG Not greater than *CT Contains *BG BeginsThe *CT operator performs a context search. It asks the system to determine whether the character string specified by this value is contained anywhere in the profile. For example, a query request of (*IF ((*SUBJECT *CT 'Sales'))) would find a match for subjects that were: '1985 Car Sales', 'Sales Awards', 'Salesperson Training Courses', 'Book of Sales Do's and Don'ts'.
The *BG operator performs a search that compares the specified value with the start of the profile parameter. The profile parameter is truncated or extended as necessary to match the length of the specified value. It asks the system to determine whether the character string specified by the value is contained at the start of the profile parameter. For example, a query request of (*IF ((*SUBJECT *BG 'Sales'))) would find a match for subjects of: 'Sales Awards', 'Salesperson Training Courses', and 'Sales by Phone'.
Some operators are excluded from being used with some profile parameters. If the excluded operators are specified in restricted profile parameters, the request is rejected with a diagnostic message followed by an escape message. Two cases are invalid:
- The *ALWRPL (allow document replacement) is a YES/NO value. The *EQ operator is the only operator allowed to have *ALWRPL.
- The *CT and *BG operators are not allowed with the *ASP value or date values such as *CRTDATE and *EXPDATE.
Element 3: Compare Values
compare-value: Specify the value to compare with the contents of the specified profile parameter. The parameter value is specified in apostrophes if it contains blanks or special characters.
The *ALWRPL field has two special values: *YES and *NO. When these are specified with the *ALWRPL field, they are changed to internal values for the indicator. When specified for the text field, *YES and *NO retain their original values.
The *OWNER field is an 8-character user ID followed by its address. Trailing blanks cannot be omitted from the user ID. For example, if the user ID is JMDOE and the address is SYSTEM1, the query request would be (*IF ((*OWNER *EQ 'JMDOE SYSTEM1'))). If the user ID is JIMSMITH, the query request would be (IF ((*OWNER *EQ 'JIMSMITHSYSTEM1'))).
Dates must be specified in the system date format.
The allowable length for the search fields is limited by the Document Interchange Architecture (DIA) search database. When the length of the value is greater than the maximum, the value is truncated to the allowed length. The maximum lengths are:
Value Maximum Length *DOCD 44 characters *DOCCLS 16 characters *SUBJECT 60 characters *AUTHOR 20 characters *KWD 60 characters *CPYLST 60 characters *OWNER 16 characters *REF 60 characters *STATUS 20 characters *PROJECT 10 charactersFor all operators except *CT and *BG, if a value that is shorter than the profile parameter value is specified, it is padded on the right with blanks to match the length of the profile parameter.
The case (upper, lower, or mixed) of the letter characters used to enter the original parameter value or the case of the comparison value does not matter. The system changes both the specified comparison value and the original parameter value to upper case before making a comparison. If the original document had been filed with a subject equal to 'Salesperson Training Courses', any of the following would be a match:
(*IF ((SUBJECT *EQ 'salesperson training courses'))) (*IF ((SUBJECT *EQ 'Salesperson Training Courses'))) (*IF ((SUBJECT *EQ 'SALESPERSON TRAINING COURSES'))) (*IF ((SUBJECT *CT 'PERSON'))) (*IF ((SUBJECT *CT 'person'))) (*IF ((SUBJECT *BG 'SALES'))) (*IF ((SUBJECT *BG 'sales')))Element 4: Logical Operator
*AND: The profile parameter value relational groups on both sides of the *AND value must be satisfied before a document is selected.
*OR: If the parameter value relational group on either side of the *OR value is satisfied, the document is selected.
The logical operators are used to group conditions. The first AND operator encountered signifies that a condition group starts with the condition immediately preceding the AND operator. Subsequent conditions with the AND operator are added to the condition group. The first condition encountered that contains the OR operator (when no more matrix entries exist) ends the condition group.
For example:
QRYDFN(*IF ((COND1 *OR) (COND2 *AND) <----| (COND3 *AND) |--Group 1 (COND4 *AND) <----| (COND5 *OR) (COND6 *OR) (COND7 *AND) <----| (COND8 *AND) |--Group 2 (COND9))) <----|The previous example could be expressed:
(cond1) | (cond2 & cond3 & cond4 & cond5) | cond6 | (cond7 & cond8 & cond9)Because the AND operator is used to group conditions, the following logical expression cannot be used by the QRYDFN parameter.
(cond1 | cond2) & (cond3 | cond4)Examples for QRYDFN
QRYDFN(*IF ((*ACTDATE *GE '6/1/1995' *AND) (*AUTHOR *EQ 'JOHN HARKER' *OR) (*ACTDATE *GE '6/1/1995' *AND) (*PROJECT *EQ 'MGMT')))All documents that have an action date later than or equal to 6/1/1995 with author John Harker or project MGMT are selected. This request is made up of two condition groups (AND sets). The first group requires that the documents selected 1) must have an action date of 6/1/1995 or later and 2) must have John Harker as the author. The second group requires that the documents selected 1) must have an action date of 6/1/1995 or later and 2) must be part of project MGMT. If either of these condition groups is true, the document is selected.
QRYDFN (*IF ((*AUTHOR *EQ 'SUSAN MICKLE' *OR) (*PROJECT *EQ 'BASEBALL' *AND) (*CMPDATE *GE '6/1/89')))All documents that with the author of Susan Mickle or that have a project of BASEBALL with a completion date on or after 6/1/89 are selected.
FLR('RECORDS/SPORTS/BASEBALL/NATIONAL') QRYDFN(*IF ((*DOCD *CT 'giants' *AND) (*FILDATE *GE '1/1/1984' *AND) (*FILDATE *LE '10/1/1986')))If the word 'giants' is contained somewhere in the document description profile parameter, and if the document file date is between 1/1/1984 and 10/1/1986, the document is selected.
The NATIONAL folder is contained in the BASEBALL folder, which is in the SPORTS folder, which is contained in the RECORDS folder.
QRYDFN(*IF ((*EXPDATE *LE '1/1/86')))All documents accessible by the user doing the search where the expiration date is less than or equal to 1/1/86, are selected.
QRYDFN(*IF ((*AUTHOR *EQ 'ANDERSON' *AND) (*DOCCLS *EQ 'account 431-2' *AND) (EXPDATE *LE '1/1/86')))All documents accessible by the user doing the search, when all three conditions on the author, document class, and expiration date profile parameters are met, are selected.
QRYDFN(*IF ((*KWD *EQ 'alphabet soup' *OR) (*KWD *CT Campbells *OR) (*KWD *BG 'good for you')))All documents accessible by the user doing the search, when any one of the three keyword tests is satisfied, are selected.
- QRYTXT
- Specifies the text search values used to select documents. The values specified on this parameter are used to search the text search index. If values other than *NONE are specified on both the QRYDFN parameter and the QRYTXT parameter, only documents that match both sets of values are selected.
*NONE: No text search values are used to select the documents.
*IF: Text search values are used in the document search.
Note: When *IF is specified, ordering is not allowed. *NONE must be specified on the ORDER parameter. To specify the conditions under which documents are selected, a set of values is specified for each condition. Each set contains four values:
- A phrase, which the system compares to entries in the text search index
- One of the type of phrase matching values
- One of the allow synonyms values
- One of the logical operators
A maximum of 30 sets of values can be specified. Each set must be enclosed in parentheses.
Element 1: Phrase
'phrase': Specify a phrase of one or more words, which the system compares to entries in the text search index. A maximum of 50 characters can be specified. When specifying phrases:
- an asterisk (*) can be used to mask a whole word within a phrase. For example, when searching for documents containing references to various annual reports, the following phrase can be specified:
annual * reportThe search results will include documents containing such phrases as annual budget report, annual progress report, and annual sales report. The search results will also include documents containing the phrase 'annual report' without a word in between.
When using a word mask, a word must be specified before and after the asterisk. A word mask at the beginning or end of a phrase is ignored.
- an asterisk (*) can be used to mask part of a word within a phrase. The mask can be used at the beginning, middle, or end of a word. For example, when searching for documents containing references to word processing, the following phrase can be specified:
word process*The search results will include documents containing such phrases as word processing, word processor, and word processed.
- a question mark (?) can be used to mask one or more characters in a word. For example, when searching for documents containing references to the various spellings of Johnson, the following phrase can be specified:
j?hns?nThe search results will include documents containing such phrases as Johnson, Johnsen, and Jahnson.
Element 2: Type of Phrase
*ALL: The phrase must be contained within one sentence, but the words do not have to be in the specified order.
*EXACT: The phrase must be contained within one sentence and the words must be in the specified order.
Element 3: Synonyms
*NO: No synonyms are used when searching for documents.
*YES: Synonyms for each word in the phrase, if available, are used to compare entries in the text index.
Note: Use synonyms may affect the performance of the request by causing more words to be searched for and by possibly causing more documents to be selected. Element 4: Logical Operator
*OR: If the phrase on either side of the *OR value is found, the document is selected.
*AND: If the phrases on both sides of the *AND value are found, the document is selected.
*ANDNOT: If the phrase following the *ANDNOT value is not found, the document is selected.
- TXTLANGID
- Specifies the language identifier of the document for which the user is searching. This parameter is not allowed if the QRYTXT parameter is not specified.
*JOB: The language identifier specified for the job in which this command is entered is used.
language-identifier: Specify the language identifier.
- ORDER
- Specifies the order in which selected documents are placed in the created document list object and the output file (if OUTFILE is specified). For example, if *SUBJECT is specified, the selected documents are returned in order, based on the collating sequence of the document subject.
When a user specifies an order to the search request, the performance of the request may be affected. The request performs best if an order is not specified. Up to 5 document profile parameters can be specified.
Element 1: Method of Order
*NONE: No order is applied to the selected documents.
*DOCD: The returned documents are ordered by the document name profile parameter.
*DOCCLS: The returned documents are ordered by the document class profile parameter.
*SUBJECT: The returned documents are ordered by the subject profile parameter.
*EXPDATE: The returned documents are ordered by the expiration date profile parameter.
*FILDATE: The returned documents are ordered by the file date profile parameter.
*CRTDATE: The returned documents are ordered by the create date profile parameter.
*ACTDATE: The returned documents are ordered by the action due date profile parameter.
*CMPDATE: The returned documents are ordered by the completion date profile parameter.
*CHGDATE: The returned documents are ordered by the last document change date.
*USEDATE: The returned documents are ordered by the last used date.
*DOCDATE: The returned documents are ordered by the document date profile parameter.
*DOCTYPE: The returned documents are ordered by the document type profile parameter. Valid values range from 2 through 65535.
*IDXDATE: The returned documents are ordered by the last indexed date profile parameter. Text search services must be installed if this value is specified.
*REVDATE: The returned documents are ordered by the last content revision date.
*KWD: The returned documents are ordered by the keyword profile parameter.
*AUTHOR: The returned documents are ordered by the author profile parameter.
*CPYLST: The returned documents are ordered by the copy list profile parameter.
*OWNER: The returned documents are ordered by the owner profile parameter.
*REF: The returned documents are ordered by the reference profile parameter.
*STATUS: The returned documents are ordered by the status profile parameter.
*PROJECT: The returned documents are ordered by the project profile parameter.
*ASP: The returned documents are ordered by the auxiary storage pool ID (ASPID) parameter.
Element 2: Ascending or Descending Order
*ASCEND: The returned documents are ordered in the ascending collating sequence.
*DESCEND: The returned documents are ordered in the descending collating sequence.
- 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: The CMDCHRID parameter applies to the following parameters and means that the data is translated to the code page and character set that is common to all of the documents in the search database. This value translates the DOCL, QRYDFN, USRID, QRYTEXT, and TEXT parameters to values for character set and code page of '697 500'.
This value translates the USRID parameter to character set and code page 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 value used to create the command parameters. Valid values range from 1 through 999.
Example for QRYDOCLIB
QRYDOCLIB USRID(*CURRENT) OUTFILE(*NONE) QRYDFN(*IF ((*DOCD *EQ DOCDESC *AND) (*DOCCLS *BG CLASS *OR) (*FILDATE *LE '06/13/88'))) DOCL(MYLIST)This command searches for documents that meet the following search conditions: document description equals DOCDESC and document class starts with Class; or the file date is on or before 06/13/88. The results of the search will be stored in the document list MYLIST.
Error messages for QRYDOCLIB
*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.
- CPF905D
- Query of document library failed.
- CPF9096
- Cannot use CMDCHRID(*DEVD), DOCCHRID(*DEVD) in batch job.
- CPF9860
- Error occurred during output file processing.