Progress0 of 0 lessons

CICS DOCUMENT INSERT - Document Content Insertion

CICS DOCUMENT INSERT provides document content insertion capabilities in CICS environments. It enables programs to insert content into documents, manage document operations, and handle document content insertion for dynamic document generation.

Command Syntax

cobol
1
2
3
4
5
6
7
8
       EXEC CICS DOCUMENT INSERT
            [DOCUMENT(document-name)]
            [FROM(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 into which content will be inserted. This parameter identifies the target document for insertion operations.

FROM(data-area)

Specifies the data area containing the content to be inserted into the document. This parameter provides the source data for insertion.

LENGTH(data-length)

Specifies the length of the data to be inserted into the document. This parameter controls the amount of content inserted.

POSITION(position-value)

Specifies the position within the document where content will be inserted. This parameter determines the insertion location.

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.

Insertion Types

Text Insertion

DOCUMENT INSERT adds text content to documents, enabling dynamic text generation and content customization for business documents.

Data Insertion

The command supports data insertion operations for incorporating variable data such as customer information, amounts, and dates.

Template Insertion

Template insertion allows insertion of predefined content blocks and formatted sections into document templates.

Conditional Insertion

Conditional insertion enables content insertion based on specific business rules and data conditions.

Programming Examples

Basic Content Insertion

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'INVOICE-001'.
       01  INSERT-DATA        PIC X(100) VALUE 'Customer: ABC Company'.
       01  DATA-LENGTH        PIC S9(8) COMP VALUE 100.
       01  INSERT-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 INSERT
                DOCUMENT(DOCUMENT-NAME)
                FROM(INSERT-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(INSERT-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           
           IF RESPONSE-CODE = 0
               DISPLAY 'Content inserted successfully'
           ELSE
               DISPLAY 'Error inserting content: ' RESPONSE-CODE
           END-IF.

Multiple Content Insertions

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
62
63
64
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'INVOICE-001'.
       01  INSERT-DATA        PIC X(200).
       01  DATA-LENGTH        PIC S9(8) COMP.
       01  INSERT-POSITION    PIC S9(8) COMP.
       01  RESPONSE-CODE      PIC S9(8) COMP.
       01  RESPONSE-CODE-2    PIC S9(8) COMP.
       01  INSERT-COUNT       PIC S9(8) COMP VALUE 0.
 
       PROCEDURE DIVISION.
           PERFORM INSERT-CUSTOMER-INFO
           PERFORM INSERT-INVOICE-DETAILS
           PERFORM INSERT-TOTAL-AMOUNT.
           
       INSERT-CUSTOMER-INFO.
           MOVE 'Customer: ABC Company' TO INSERT-DATA
           MOVE FUNCTION LENGTH(INSERT-DATA) TO DATA-LENGTH
           MOVE 1 TO INSERT-POSITION
           EXEC CICS DOCUMENT INSERT
                DOCUMENT(DOCUMENT-NAME)
                FROM(INSERT-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(INSERT-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO INSERT-COUNT
               DISPLAY 'Customer info inserted'
           END-IF.
           
       INSERT-INVOICE-DETAILS.
           MOVE 'Invoice Number: INV-001' TO INSERT-DATA
           MOVE FUNCTION LENGTH(INSERT-DATA) TO DATA-LENGTH
           MOVE 50 TO INSERT-POSITION
           EXEC CICS DOCUMENT INSERT
                DOCUMENT(DOCUMENT-NAME)
                FROM(INSERT-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(INSERT-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO INSERT-COUNT
               DISPLAY 'Invoice details inserted'
           END-IF.
           
       INSERT-TOTAL-AMOUNT.
           MOVE 'Total Amount: $1,250.00' TO INSERT-DATA
           MOVE FUNCTION LENGTH(INSERT-DATA) TO DATA-LENGTH
           MOVE 100 TO INSERT-POSITION
           EXEC CICS DOCUMENT INSERT
                DOCUMENT(DOCUMENT-NAME)
                FROM(INSERT-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(INSERT-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           IF RESPONSE-CODE = 0
               ADD 1 TO INSERT-COUNT
               DISPLAY 'Total amount inserted'
           END-IF.

Dynamic Content Insertion

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
       WORKING-STORAGE SECTION.
       01  DOCUMENT-NAME      PIC X(16) VALUE 'REPORT-001'.
       01  INSERT-DATA        PIC X(500).
       01  DATA-LENGTH        PIC S9(8) COMP.
       01  INSERT-POSITION    PIC S9(8) COMP.
       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 > 5
               PERFORM BUILD-INSERT-DATA
               PERFORM CALCULATE-POSITION
               PERFORM INSERT-CONTENT
           END-PERFORM.
           
       BUILD-INSERT-DATA.
           STRING 'Section ' DELIMITED BY SIZE
                  PROCESSING-COUNT DELIMITED BY SIZE
                  ': Processing data for step ' DELIMITED BY SIZE
                  PROCESSING-COUNT DELIMITED BY SIZE
                  ' completed at ' DELIMITED BY SIZE
                  FUNCTION CURRENT-DATE DELIMITED BY SIZE
                  INTO INSERT-DATA.
           MOVE FUNCTION LENGTH(INSERT-DATA) TO DATA-LENGTH.
           
       CALCULATE-POSITION.
           COMPUTE INSERT-POSITION = (PROCESSING-COUNT - 1) * 100 + 1.
           
       INSERT-CONTENT.
           EXEC CICS DOCUMENT INSERT
                DOCUMENT(DOCUMENT-NAME)
                FROM(INSERT-DATA)
                LENGTH(DATA-LENGTH)
                POSITION(INSERT-POSITION)
                RESP(RESPONSE-CODE)
                RESP2(RESPONSE-CODE-2)
           END-EXEC
           
           IF RESPONSE-CODE = 0
               DISPLAY 'Content inserted at position ' INSERT-POSITION
           ELSE
               DISPLAY 'Error inserting content: ' RESPONSE-CODE
           END-IF.

Error Handling

Response Code 0

Successful content insertion. The content has been successfully inserted into the document.

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 insertion position is invalid or out of range.

Response Code 20

Insertion failed. The content insertion operation failed due to system conditions.

Performance Considerations

Document Size Management

DOCUMENT INSERT efficiently manages document size, but large content insertions may impact document processing performance.

Position Management

Proper position management ensures efficient content insertion and prevents document structure issues.

Content Validation

Content validation before insertion ensures data integrity and prevents document corruption.

Best Practices

Error Handling

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

Content Validation

Validate content before insertion to ensure data integrity and prevent document corruption.

Position Management

Use appropriate insertion positions to maintain document structure and formatting integrity.

Content Optimization

Optimize content insertion by using appropriate data lengths and efficient insertion strategies.

Explain It Like I's 5 Years Old

Imagine you're writing a story in a notebook, and you want to add more words to your story. CICS DOCUMENT INSERT is like adding new words to your story at a specific place.

The document name is like the name of your story, and the position is like telling the program exactly where in your story to add the new words. The new words go right where you tell them to go.

Just like you need to make sure your notebook has enough space for the new words, the program needs to make sure the document has enough space for the new content.

Exercises

Exercise 1: Basic Content Insertion

Write a program that uses DOCUMENT INSERT to add content to a document at a specific position.

Exercise 2: Multiple Content Insertions

Create a program that inserts different types of content (text, data, formatting) into various positions in a document.

Exercise 3: Dynamic Document Building

Implement a dynamic document building system that inserts content based on business data and requirements.

Related Concepts

CICS Document Management

Understanding CICS document management and operations

CICS Content Management

Learning about CICS content management and formatting

CICS Dynamic Processing

Understanding CICS dynamic processing and data handling

CICS Error Handling

Learning about CICS error handling and response codes