What is CICS DOCUMENT RETRIEVE command?

CICS DOCUMENT RETRIEVE is a command that retrieves content from existing documents in CICS environments, enabling programs to access document data for processing, display, and analysis purposes.

How does CICS DOCUMENT RETRIEVE work?

DOCUMENT RETRIEVE gets content from documents by specifying a document name, destination data area, data length, and optional starting position within the document.

What are the main parameters for CICS DOCUMENT RETRIEVE?

The main parameters include DOCUMENT for the document name, INTO for the destination data area, LENGTH for data length, POSITION for starting position, and RESP for response codes.

How do you handle errors with CICS DOCUMENT RETRIEVE?

Error handling involves checking response codes, with code 0 indicating success, code 8 indicating invalid document name, code 12 indicating document not found, code 16 indicating invalid position, and other codes indicating various error conditions.

What types of retrieval operations are supported by CICS DOCUMENT RETRIEVE?

Retrieval types include full document retrieval (complete content), partial content retrieval (specific sections), position-based retrieval (from specific positions), and sequential retrieval (step-by-step access).

CICS DOCUMENT RETRIEVE - Document Content Retrieval

CICS DOCUMENT RETRIEVE provides document content retrieval capabilities in CICS environments. It enables programs to retrieve document content, manage document operations, and handle document content retrieval for processing and display purposes.

Command Syntax

cobol

1
2
3
4
5
6
7
8
       EXEC CICS DOCUMENT RETRIEVE
            [DOCUMENT(document-name)]
            [INTO(data-area)]
            [LENGTH(data-length)]
            [POSITION(position-value)]
            [RESP(response-code)]
            [RESP2(response-code-2)]
       END-EXEC.

Parameters

DOCUMENT(document-name)

Specifies the name of the document from which content will be retrieved. This parameter identifies the source document for retrieval operations.

INTO(data-area)

Specifies the data area to receive the retrieved document content. This parameter provides the destination for retrieved data.

LENGTH(data-length)

Specifies the length of the data area to receive retrieved content. This parameter controls the amount of content retrieved.

POSITION(position-value)

Specifies the position within the document from which content will be retrieved. This parameter determines the retrieval starting point.

RESP(response-code)

Specifies the response code variable to receive the operation result. This parameter provides error handling and status information.

RESP2(response-code-2)

Specifies the secondary response code variable for additional error information. This parameter provides extended error details when available.

Retrieval Types

Full Document Retrieval

DOCUMENT RETRIEVE retrieves complete document content, enabling full document processing and analysis operations.

Partial Content Retrieval

The command supports partial content retrieval for accessing specific sections or portions of documents efficiently.

Position-Based Retrieval

Position-based retrieval allows content retrieval starting from specific positions within documents for targeted access.

Sequential Retrieval

Sequential retrieval enables step-by-step content access for processing large documents in manageable chunks.

Programming Examples

Basic Document Retrieval

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'INVOICE-001'.
       01  RETRIEVE-DATA     PIC X(1000).
       01  DATA-LENGTH       PIC S9(8) COMP VALUE 1000.
       01  RETRIEVE-POSITION PIC S9(8) COMP VALUE 1.
       01  RESPONSE-CODE     PIC S9(8) COMP.
       01  RESPONSE-CODE-2   PIC S9(8) COMP.
 
       PROCEDURE DIVISION.
           EXEC CICS DOCUMENT RETRIEVE
                DOCUMENT(DOCUMENT-NAME)
                INTO(RETRIEVE-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(RETRIEVE-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           
           IF RESPONSE-CODE = 0
               DISPLAY 'Document content retrieved successfully'
               DISPLAY 'Retrieved data: ' RETRIEVE-DATA
           ELSE
               DISPLAY 'Error retrieving document: ' RESPONSE-CODE
           END-IF.

Multiple Content Retrievals

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'REPORT-001'.
       01  RETRIEVE-DATA     PIC X(500).
       01  DATA-LENGTH       PIC S9(8) COMP VALUE 500.
       01  RETRIEVE-POSITION PIC S9(8) COMP.
       01  RESPONSE-CODE     PIC S9(8) COMP.
       01  RESPONSE-CODE-2   PIC S9(8) COMP.
       01  RETRIEVE-COUNT    PIC S9(8) COMP VALUE 0.
 
       PROCEDURE DIVISION.
           PERFORM RETRIEVE-HEADER-SECTION
           PERFORM RETRIEVE-DETAIL-SECTION
           PERFORM RETRIEVE-FOOTER-SECTION.
           
       RETRIEVE-HEADER-SECTION.
           MOVE 1 TO RETRIEVE-POSITION
           EXEC CICS DOCUMENT RETRIEVE
                DOCUMENT(DOCUMENT-NAME)
                INTO(RETRIEVE-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(RETRIEVE-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO RETRIEVE-COUNT
               DISPLAY 'Header section retrieved'
               DISPLAY 'Header: ' RETRIEVE-DATA
           END-IF.
           
       RETRIEVE-DETAIL-SECTION.
           MOVE 501 TO RETRIEVE-POSITION
           EXEC CICS DOCUMENT RETRIEVE
                DOCUMENT(DOCUMENT-NAME)
                INTO(RETRIEVE-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(RETRIEVE-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO RETRIEVE-COUNT
               DISPLAY 'Detail section retrieved'
               DISPLAY 'Details: ' RETRIEVE-DATA
           END-IF.
           
       RETRIEVE-FOOTER-SECTION.
           MOVE 1001 TO RETRIEVE-POSITION
           EXEC CICS DOCUMENT RETRIEVE
                DOCUMENT(DOCUMENT-NAME)
                INTO(RETRIEVE-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(RETRIEVE-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO RETRIEVE-COUNT
               DISPLAY 'Footer section retrieved'
               DISPLAY 'Footer: ' RETRIEVE-DATA
           END-IF.

Sequential Document Processing

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'LARGE-DOCUMENT'.
       01  RETRIEVE-DATA     PIC X(200).
       01  DATA-LENGTH       PIC S9(8) COMP VALUE 200.
       01  RETRIEVE-POSITION PIC S9(8) COMP VALUE 1.
       01  RESPONSE-CODE     PIC S9(8) COMP.
       01  RESPONSE-CODE-2   PIC S9(8) COMP.
       01  PROCESSING-COUNT PIC S9(8) COMP VALUE 0.
 
       PROCEDURE DIVISION.
           PERFORM VARYING PROCESSING-COUNT FROM 1 BY 1
           UNTIL PROCESSING-COUNT > 10
               PERFORM CALCULATE-POSITION
               PERFORM RETRIEVE-CONTENT
               PERFORM PROCESS-CONTENT
           END-PERFORM.
           
       CALCULATE-POSITION.
           COMPUTE RETRIEVE-POSITION = (PROCESSING-COUNT - 1) * 200 + 1.
           
       RETRIEVE-CONTENT.
           EXEC CICS DOCUMENT RETRIEVE
                DOCUMENT(DOCUMENT-NAME)
                INTO(RETRIEVE-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(RETRIEVE-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           
           IF RESPONSE-CODE = 0
               DISPLAY 'Content retrieved at position ' RETRIEVE-POSITION
           ELSE
               DISPLAY 'Error retrieving content: ' RESPONSE-CODE
           END-IF.
           
       PROCESS-CONTENT.
           IF RESPONSE-CODE = 0
               DISPLAY 'Processing content: ' RETRIEVE-DATA
               PERFORM BUSINESS-LOGIC-PROCESSING
           END-IF.

Error Handling

Response Code 0

Successful content retrieval. The document content has been successfully retrieved into the specified data area.

Response Code 8

Invalid document name. The specified document name is invalid or not supported.

Response Code 12

Document not found. The specified document does not exist in the system.

Response Code 16

Invalid position. The specified retrieval position is invalid or out of range.

Response Code 20

Retrieval failed. The content retrieval operation failed due to system conditions.

Performance Considerations

Data Transfer Efficiency

DOCUMENT RETRIEVE efficiently transfers document content, but large retrievals may impact system performance temporarily.

Memory Management

Proper memory management ensures efficient content retrieval and prevents memory exhaustion in high-volume operations.

Position Optimization

Optimize retrieval positions to minimize data transfer overhead and improve processing efficiency.

Best Practices

Error Handling

Always check response codes and handle errors appropriately, especially for document existence and position validation.

Data Validation

Validate retrieved content to ensure data integrity and proper processing of document information.

Memory Allocation

Allocate appropriate memory sizes for data areas to accommodate retrieved content without overflow.

Retrieval Optimization

Optimize retrieval operations by using appropriate data lengths and efficient retrieval strategies.

Explain It Like I's 5 Years Old

Imagine you have a big book with lots of stories, and you want to read a specific part of the book. CICS DOCUMENT RETRIEVE is like opening the book to a specific page and reading the words from that page.

The document name is like the name of the book, and the position is like telling the program which page to open. The program reads the words from that page and puts them in a special place for you to use.

Just like you need to make sure you have enough space to write down the words you read, the program needs to make sure it has enough space to store the words it retrieves.

Exercises

Exercise 1: Basic Document Retrieval

Write a program that uses DOCUMENT RETRIEVE to get content from a document and display the retrieved information.

Exercise 2: Partial Content Retrieval

Create a program that retrieves specific sections of a document by using different position values.

Exercise 3: Sequential Document Processing

Implement a document processing system that retrieves and processes document content in sequential chunks.

CICS DOCUMENT RETRIEVE - Document Content Retrieval

Command Syntax

Parameters

DOCUMENT(document-name)

INTO(data-area)

LENGTH(data-length)

POSITION(position-value)

RESP(response-code)

RESP2(response-code-2)

Retrieval Types

Full Document Retrieval

Partial Content Retrieval

Position-Based Retrieval

Sequential Retrieval

Programming Examples

Basic Document Retrieval

Multiple Content Retrievals

Sequential Document Processing

Error Handling

Response Code 0

Response Code 8

Response Code 12

Response Code 16

Response Code 20

Performance Considerations

Data Transfer Efficiency

Memory Management

Position Optimization

Best Practices

Error Handling

Data Validation

Memory Allocation

Retrieval Optimization

Explain It Like I's 5 Years Old

Exercises

Exercise 1: Basic Document Retrieval

Exercise 2: Partial Content Retrieval

Exercise 3: Sequential Document Processing

Related Concepts

CICS Document Management

CICS Content Processing

CICS Data Retrieval

CICS Error Handling

Related Pages