RTVDOC (Retrieve Document)
RTVDOC Command syntax diagram
Purpose
The Retrieve Document (RTVDOC) command allows a user to copy information from a specific document to a database file and allows the user to check out a document from the document library. Documents whose storage has been freed (STG(*FREE) specified on the Save Document Library Object (SAVDLO) command) cannot be retrieved.
Restrictions
- To retrieve any records from the document to a database file, have *USE authority to the document or be working on behalf of a user that has *USE authority to the document.
- To check out the document, have at least *CHANGE authority to the document, or be working on behalf of a user that has *CHANGE authority to the document.
- To work on behalf of another user, have either *ALLOBJ authority or special permission (granted with the Grant User Permission (GRTUSRPMN) command).
Required Parameters
- FROMDOC
- Specifies the name of the document being retrieved.
*DOCID: The document being retrieved is identified by the library-assigned document name specified on the DOCID parameter.
document-name: Specify the name of the document that is retrieved.
Optional Parameters
- FROMFLR
- Specifies the name of the folder that contains the document being
retrieved.
*NONE: No folder name is specified when the document is identified by the DOCID parameter.
folder-name: Specify the name of the folder that contains the document being retrieved.
- DOCID
- Specifies the library-assigned name of the document being retrieved. This
is the name assigned to the document by the system when it is created. The
library-assigned document names can be determined by using the Query Document
Library (QRYDOCLIB) command. The library-assigned document name is also
returned in a completion message when the File Document (FILDOC) command is
used.
Library-assigned document names are 24 characters in length with the following format: YYYYMMDDHHMNSSHSSNSNSNSN where:
- YYYY = year
- MM = month
- DD = day
- HH = hour
- MN = minute
- SS = second
- HS = hundredths of a second
- SNSNSNSN = system name
*NONE: No library-assigned document name is required when the document is identified by the FROMDOC parameter.
library-assigned-document-name: Specify the library-assigned document name sent. More information on library-assigned document names is in the Communications Configuration book.
- USRID
- Specifies the user ID and address of the user for whom the 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 document is retrieved.
Element 2: User Address
user-address: Specify the user address of the user for whom the document is retrieved.
- CHKOUT
- Specifies whether the document being retrieved can be replaced with new or
changed data. If the document is read only, then specify CHKOUT(*NO). If the
document being retrieved cannot be replaced, and CHKOUT(*YES) is specified, an
error occurs.
Note: If a user is retrieving a document to check it out and a cancel request is entered, the document may or may not be checked out. *NO: The retrieve request only reads the data. Users requesting this function need only *USE authority to the document. The authority for the public is *READ authority.
*YES: The document data can be updated and replaced later. Users requesting this function must have *CHANGE authority. The document is unavailable to other users until a replace operation is done using the Replace Document Command (RPLDOC) The checkout flag can be reset with the CHGDOCD or EDTDLOAUT command.
- OUTFILE
- Specifies the name of the database file where the document data of the
display 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 text "OUTFILE created by RTVDOC" is shown and the authority given
to users with no specific authority is *EXCLUDE.
Note: The output file format must be the same as the OSRTVD of the system file QSYS/QAOSIRTV. More information on defining the format of database files (output files) is in the Office Services Concepts and Programmer's Guide book.
*NONE: The output is not directed to a database file.
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 to receive the output.
This file can be reused when other RTVDOC commands are used. Output can be added to the file or can replace the existing records. The IBM-supplied database file QAOSIRTV in library QSYS 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.
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.
Note: Document data for more than one document can be added to the same member. However, an error occurs if the member is filed to another document with the FILDOC command. The FILDOC command only files the first document in the member and issues an error message. *ADD: The system adds the new records to the end of the existing records.
- OUTDTATYP
- Specifies what parts of information about the selected documents are
written to the output file if one is specified.
*DFT: The document information record is written to the output file. The following record codes are written to the output file:
Record Code Description 105 Document Description 800 Document Data
*ALL: All information records about the document are written to the output file.
Record Code Description 105 Document Description 110 Creation Date 115 Expiration date 120 Document date 125 File date 130 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 500 Interchange document profile data 800 Document Data*DOCD: The document information 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.
*FILCAB: The filing cabinet reference code 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.
*FILDATE: The file date record is written to the output file.
*EXPDATE: The expiration date record is written to the output file.
*DOCDATE: The document date record 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.
*CHGDATE: The date last changed record is written to the output file.
*CMPDATE: The completion date record is 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.
*IDP: The interchange document profile (IDP) is written to the output file.
*DOC: The document data record is written to the output file.
- 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 character set and code page set of '930 256'. The SNA Distribution Services 
book contains the character set and code
page table for '930 256'.*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.
Examples for RTVDOC
Example 1: Copying All Information
RTVDOC FROMDOC(MYDOC) FROMFLR(PERSONAL) USRID(*CURRENT) OUTFILE(*CURLIB/MYFILE) OUTMBR(*FIRST) MBROPT(*ADD) OUTDTATYP(*ALL)
This command copies all information about document MYDOC located in folder PERSONAL for the current user of this command. CHECKOUT(*NO) is assumed; therefore, the document data can only be read. 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.
Example 2: Copying Default Information
RTVDOC FROMDOC(SECOP) FROMFLR(PERSONAL) USRID(MARY SYSTEM1 ) CHKOUT(*YES) OUTFILE(MARLIB/SECFILE) OUTMBR(*FIRST *ADD)
This command copies the default information (*DOCD and *DOC) about document SECOP located in folder PERSONAL for MARY. The document can be updated with new data and then replaced. The current user of this command must have the authority to work on behalf of MARY given by Mary by using the GRTUSRPMN command. The output is directed to the database file SECFILE in Mary's library MARLIB. The output is added to the first member of SECFILE.
Error messages for RTVDOC
*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.
- CPF905F
- Retrieval of document from library failed.
- CPF9096
- Cannot use CMDCHRID(*DEVD), DOCCHRID(*DEVD) in batch job.
- CPF9860
- Error occurred during output file processing.