Retrieve Document (RTVDOC)

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

The Retrieve Document (RTVDOC) command allows you to retrieve information from a specific document.

Restrictions:

To retrieve any records from the document to a database file, you must have use (*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, you must have at least change (*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, you must have either all object (*ALLOBJ) special authority or special permission (granted with the Grant User Permission (GRTUSRPMN) command).

Parameters

Keyword	Description	Choices	Notes
FROMDOC	From document	Character value, *DOCID	Required, Positional 1
FROMFLR	From folder	Character value, *NONE	Optional, Positional 2
OUTFILE	File to receive output	Single values: *NONE Other values: 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
OUTDTATYP	Type of data for output	Single values: DFT, ALL Other values (up to 21 repetitions): DOCD, DOCCLS, SUBJECT, AUTHOR, FILCAB, CPYLST, KWD, DOCDATE, FILDATE, CRTDATE, CHGDATE, EXPDATE, ACTDATE, CMPDATE, REF, STATUS, PROJECT, IDP, *DOC	Optional
USRID	User identifier	Single values: *CURRENT Other values: Element list	Optional
	Element 1: User ID	Character value
	Element 2: Address	Character value
DOCID	Document identifier	Character value, *NONE	Optional
CHKOUT	Check out	NO, YES	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

From document (FROMDOC)

Specifies the name of the document being retrieved.

name: Specify the user-assigned name of the document being retrieved.
*DOCID: The document being retrieved is identified by the library-assigned document name that must be specified on the Document identifier (DOCID) parameter.

Top

From folder (FROMFLR)

Specifies the name of the folder that contains the document being retrieved. This is the name assigned to the folder when it is created. This parameter must be specified if a document name is specified.

*NONE: No folder name is specified when the document is identified by the library-assigned document name.
name: Specify the name of the folder that contains the retrieved document.

Top

File to receive output (OUTFILE)

Specifies 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. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.

Qualifier 1: File to receive output

name: Specify the name of the database file to which the command output is directed.

Qualifier 2: Library

*LIBL: The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
*CURLIB: The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.

name: Specify the name of the library to be searched.

Note: If a new file is created, the system uses QAOSIRTV in QSYS with a format name of OSRTVD as a model.

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.

Top

Output member options (OUTMBR)

Specifies the name of the database file member that receives the output of the command.

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 for the File to receive output (OUTFILE) parameter. If the member already exists, you have the option to add new records to the end of the existing member or clear the member and then add the new records.

name: Specify the name of the file member that receives the output. If it does not exist, the system creates it.

Element 2: Replace or add records

*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

Type of data for output (OUTDTATYP)

Specifies the parts of information about the document that are written to the database file.

*DFT

The document information record is written. This is the same as specifying *DOCD and *DOC.

Record code - 105, Document description
Record code - 800, Document data

*ALL

All information records are written.

*ACTDATE: The action due date record is written. The record code is 135.
*AUTHOR: The author records are written. The record code is 145.
*CHGDATE: The date last changed record is written. The record code is 130.
*CMPDATE: The completion date record is written. The record code is 140.
*CPYLST: The copy list records are written. The record code is 150.
*CRTDATE: The create date record is written. The record code is 110.
*DOCCLS: The document class record is written. The record code is 155.
*DOCD: The document description record is written. The record code is 105.
*DOCDATE: The document date record is written. The record code is 120.
*EXPDATE: The expiration date record is written. The record code is 115.
*FILCAB: The file cabinet reference record is written. The record code is 160.
*FILDATE: The file date record is written. The record code is 125.
*IDP: The interchange document profile (IDP) is written. The record code is 500.
*IDXDATE: The last indexed date record is written to the output file.
*KWD: The keyword records are written. The record code is 170.
*PROJECT: The project record is written. The record code is 185.
*REF: The reference record is written. The record code is 175.
*REVDATE: The date of the last revision to the document content is written to the output file.
*STATUS: The status record is written. The record code is 180.
*SUBJECT: The subject records are written. The record code is 165.
*USEDATE: The date last used record is written. The record code is 200.

*DOC: The document data record is written. The record code is 800.

Top

User identifier (USRID)

Specifies which user ID and user ID address should be associated with the request.

Single values

*CURRENT: You are performing the request for yourself.

Element 1: User ID

character: Specify another user's user ID or your user ID. You must have been given permission to work on behalf of another user or have all object (*ALLOBJ) special authority.

Element 2: Address

character: Specify another user's address or your address. You must have been given permission to work on behalf of another user or have *ALLOBJ authority.

Top

Document identifier (DOCID)

Specifies the library-assigned name of the document. This is the name assigned to the document by the system when it was created. Documents filed outside the local system have only library-assigned document names. The library-assigned document names can be determined by using the Query Document Library (QRYDOCLIB) command or by the message returned from the File Document (FILDOC) command.

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 on the Document (DOC) parameter.
name: Specify the library-assigned name of the document being sent.

Top

Check out (CHKOUT)

Specifies that the document being retrieved can be replaced with new or changed data. If the document is read only, then specify *NO. If the document being retrieved cannot be replaced, and *YES is specified, this will cause an error to occur.

*NO: The retrieve request only reads the data. Users requesting this function need only read (*READ) authority to the document. Public authority is *READ authority.
*YES: The document data can be updated and replaced later. Users requesting this function must have change (*CHANGE) authority. The document will be unavailable for other users to update until the replacement of this document is done. The replacement can be done by using the Replace Document (RPLDOC) command.

Top

Command character identifier (CMDCHRID)

Specifies the character identifier (graphic character set and code page) for the data being entered as command parameter values. The character identifier is related to the display device used to enter the command.

The value specified on the User identifier (USRID) parameter is translated to character set and code page '930 500'.

Single values

*SYSVAL: The system determines the graphic character set and code page values for the command parameters from the QCHRID system value.

*DEVD: The system determines the graphic character set and code page values from the display device description where this command was entered. This option is valid only when entered from an interactive job. If this option is specified in a batch job, an error occurs.

Element 1: Graphic character set

1-32767: Specify the graphic character set to use.

Element 2: Code page

1-32767: Specify the code page to use.

Top

Examples

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.

Top

Error messages

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

Top