Micro Focus Enterprise Developer 2.3 Update 2 for Eclipse > Programming > Mainframe Programming > AppMaster Builder > Reference > Data Communication Calls > TP-COMMAREA

TP-COMMAREA

TP-COMMAREA generates a Working-Storage record for passing data between programs or coordinates the placement of the AMB-generated Commarea structure with a user-provided redefinition of that structure.

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

CICS
DLG
IMS DC

CICS

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains AMB information as well as user data.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is 80--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields.

The following calls pass a Commarea:

SEND	Send a screen to the terminal and terminate the program. CICS saves the data stored in the TP-COMMAREA and makes it available to the next program when AMB returns the screen to CICS.
LINK	Link to a subprogram, passing it the TP-COMMAREA address. Define COMMAREA identically in each program.
XCTL	Transfer control to another program, passing a copy of TP-COMMAREA. Define TP-COMMAREA identically in both programs.

You can redefine TP-USERAREA to fit program requirements.

Code the redefinition in the Data Structure Editor. You must also specify the Commarea redefinition in Application View--code its name in the Data Str field and specify its type as CA (Commarea).
Code the redefinition in the Program Painter. Three keywords are available to redefine TP-USERAREA: CA, where you code the redefinition in Data Structure Editor syntax; CA05 and CA, where you code it in COBOL syntax.

Optionally, you can code the redefinition in a copybook or rule that you include.

Examples:

Redefine TP-USERAREA in the Program Painter.

 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA     AACA-USERAREA
            CA-DATE                X8
            CA-TIME                X8
            CA-CUST-NUMBER         X5
 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA05   AACA-USERAREA
        10  CA-DATE                X8
        10  CA-TIME                X8
        10  CA-CUST-NUMBER         X5

Redefine TP-USERAREA in the Data Structure Editor.

AACA-USERAREA
    CA-DATE                X8
    CA-TIME                X8
    CA-CUST-NUMBER         X5

Each of the above examples generates:

01  TP-COMMAREA
          .
          .
          .
01  FILLER REDEFINES TP-COMMAREA.
    05  FILLER                PIC X(40).
    05  TP-USERAREA           PIC X(21).
    05  AACA-USERAREA   REDEFINES TP-USERAREA.
        10  CA-DATE           PIC X(08).
        10  CA-TIME           PIC X(08).
        10  CA-CUST-NUMBER    PIC X(05).

DLG

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains AMB information and user data.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is zero-- determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the AMB variable &TP-USER-LEN. Code the following on one line.

 SYM1    % &TP-USER-LEN = number

SYM1 indicates &TP-USER-LEN is an Customizer variable and places the variable at the top of the program.
&TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. The default for number is zero.

To receive TP-COMMAREA as a passed data area from a calling program, code this assignment statement before NTRY.

        % &DLG-COMMAREA-IN-LINKAGE = "YES"

The results are:

AMB generates the following in the Linkage Section
```
01  DLG-LINKAGE-COMMAREA  PIC X(&TP-USER-LEN).
```
AMB generates the Procedure Division statement with
```
... USING DLG-LINKAGE-COMMAREA
```
Generated logic maps the data between TP-COMMAREA and DLG-LINKAGE-COMMAREA at the following points
- Upon program invocation, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
- Before execution of LINK or XCTL, from TP-COMMAREA to DLG-LINKAGE-COMMAREA
- After execution of LINK or XCTL, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
- Before program termination, from TP-COMMAREA to DLG-LINKAGE-COMMAREA

Example:

Redefine TP-USERAREA.

Program Painter source:

 SYM1   % &TP-USER-LEN = 49 
 CA05   PGM-USERAREA
            10  CA-EMPLOYEE-NAME    PIC X(20).
            10  CA-EMPLOYEE-TITLE   PIC X(20).
            10  CA-EMPLOYEE-SSN     PIC X(09).

Generated source:

01 TP-COMMAREA.
   05  TP-USERAREA              PIC (X49).
   05  PGM-USERAREA REDEFINES TP-USERAREA.
       10  CA-EMPLOYEE-NAME     PIC X(20).
       10  CA-EMPLOYEE-TITLE    PIC X(20).
       10  CA-EMPLOYEE-SSN      PIC X(09).

IMS DC

TP-COMMAREA coordinates the placement of the AMB-generated Commarea structure with a user-provided redefinition of that structure. Use it only with conversational IMS programs - nonconversational IMS programs do not use a Commarea.

In IMS, the Commarea is called a SPA (Scratch Pad Area). Its reserved prefix includes an IMS LLZZ field, the input trancode, and the AMB invocation mode flag.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is 0--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the AMB variable &TP-USER-LEN. Code the following on one line.

SYM1   % &TP-USER-LEN = number

SYM1 indicates &TP-USER-LEN is an Customizer variable and places the variable at the top of the program.
&TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. Caution An undefined &TP-USER-LEN defaults to zero; when prototyping, the default is 2048.

Examples:

Program Painter source:

 SYM1   % &TP-USER-LEN = 100 
 CA05   MY-REDEF
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).

Generated source:

% &TP-USER-LEN = 100
IDENTIFICATION DIVISION
          .
          .
WORKING-STORAGE SECTION.
$TP-WS-MARKER
$TP-COMMAREA
    05  MY-REDEF REDEFINES TP-USERAREA.
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).