COBOL program units as subroutines

UTM program units and event exits are subroutines of the UTM main routine. This fact leads to the following consequences:

• The program name defines the start address.

• At least one data structure must be defined in the LINKAGE SECTION.

• The program unit is terminated dynamically with the PEND call. Event exits that are exited with the statement EXIT PROGRAM are the exception. The statement STOP RUN is not permitted (exceptions: the START and SHUT event exits).

A series of COPY members are available to ensure compatibility and to enable you to work with error-free data structures. The section “Data structures for COBOL program units” on "Data structures for COBOL program units" describes how to use these COPY elements.

PROGRAM-ID as a start name

You define the start name for the program unit in the PROGRAM-ID paragraph. This name is freely definable, but must be unique within a given application program. There must be no naming conflicts between the program name and the runtime systems, the database systems, the formatting system, the communication components and openUTM.

When choosing names, it is therefore important to bear in mind the following points:

• For BS2000 systems:

  • All names that begin with KDC, KC or I are reserved.

• For Unix, Linux and Windows systems:

  • All names that begin with KDC, KC, x or ITS are reserved.

  • Names that begin with t_ are reserved for CMX and PCMX.

  • Names that begin with a_, o_ or s_ are reserved for OSS.

• The names you define must comply with COBOL conventions.

You must also specify the program names (start names) when generating the UTM application - each of them must be named in the KDCDEF application PROGRAM (see the openUTM manual “Generating Applications”).

Please note what the COBOL compiler manual has to say about how program names are to be handled in the IDENTIFICATION DIVISION and in the CALL call.

WORKING-STORAGE SECTION

The WORKING-STORAGE SECTION is used primarily for constant data.

To ensure that program units remain compatibility and to make them easier to read, a series of constants with predefined KDCS names is provided in the form of COPY members.

It is a good idea only to store fields with fixed values in the WORKING-STORAGE SECTION. If you also want to store areas which contain variable data in the WORKING-STORAGE SECTION, you can also define the KDCS parameter area and the message area. However, since it is useful to accommodate them in the SPAB in the interests of saving storage space, these areas are described in the following section.

LINKAGE SECTION

You can use the LINKAGE SECTION for passing parameters and as a working area.

In the LINKAGE SECTION, each program unit must have a data structure with the level number 01 which describes the KDCS communication area.

This can be followed by a further data structure with the level number 01. This data structure describes the standard primary working area (SPAB). You can accommodate the KDCS parameter area and the message areas in the SPAB.

The data structures in the KB and in the KDCS parameter area are available as COPY members (KCKBC and KCPAC).

You will need to define the message areas yourself. However, specific data structures are provided in COPY members for calls which request information from openUTM (e.g. INFO, INIT PU). If you are working with a formatting system, you will be able to use automatically generated addressing aids to structure the message area (see the formatting system manual).

Example

LINKAGE SECTION.
    COPY KCKBC.                       1)
    05   KB-ANY           PIC X(22).  2)
    05   KB-STARTLOC      PIC X(2).   2)
    05   KB-DESTLOC       PIC X(2).   2)
    05   KB-FLGTAG        PIC X(5).   2)
    05   KB-FLGNO1        PIC X(5).   2)
    05   KB-FLGNO2        PIC X(5).   2)
    COPY KCPAC.                       3)
    03   NB.                          4)
    COPY IFORMA3.                     4)

¹⁾ KDCS communication area
²⁾ User-specific declaration of the KB program area
³⁾ SPAB with KDCS parameter area
⁴⁾ Message area: the COPY statement fetches the input addressing aid for the format "FORMA3".

Extending the LINKAGE SECTION

In addition to the communication area and the SPAB, you can also accommodate still other areas in the LINKAGE SECTION which can then be used as common data areas within a UTM application.

You can declare these areas with the KDCDEF statement AREA. For more information, refer to the openUTM manual “Generating Applications”.

In COBOL program units you can use AREAs as follows:

• In the LINKAGE SECTION you define these areas with the level number 01.

• In the PROCEDURE DIVISION you specify these areas under USING.

The order in which these areas are defined with the AREA statement is also important. If the area defined in nth position is required, you will need to specify all areas up until this one both in the LINKAGE SECTION and in the PROCEDURE DIVISION in the case of USING.

This function is not reflected in DIN standard 66 265.

Example 1

The areas AREA1, AREA2 and AREA3 were defined in this order using the AREA statement. AREA3 is required in a program unit. All areas are defined with the length 2000.

      .
      .
LINKAGE SECTION.
    COPY KCKBC.
      .
      .
    COPY KCPAC.
      .
      .
      .
01 AREA1  PIC X(2000).
01 AREA2  PIC X(2000).
01 AREA3  PIC X(2000).
      .
      .
PROCEDURE DIVISION USING KCKBC, KCSPAB, AREA1, AREA2, AREA3.
      .
      .

Example 2. Program unit in COBOL (on Unix, Linux and Windows systems)

In the following, two areas are generated, defined in a C source (see "Other data areas (AREAs)") and passed to a program unit. The following are defined:

• the area area for direct access (i.e. the data area is passed to the program unit directly)

• the area areaind for indirect access

  IDENTIFICATION DIVISION. 
  PROGRAM-ID. COBAREA. 
  ENVIRONMENT DIVISION. 
  DATA DIVISION. 
  WORKING-STORAGE SECTION. 
  LINKAGE SECTION. 
      COPY KCKBC. 
      05 PROG PIC X. 
      COPY KCPAC. 
      03 NB PIC X(4000). 
  01 AREA1 PIC X(20).
  01 AREA2 PIC X(30). 
  PROCEDURE DIVISION USING KCKBC KCSPAB AREA1 AREA2. 
      MOVE AREA1 TO BUFFER. 
      MOVE AREA2 TO BUFFER1. 
      PERFORM INIT-OP. 
  . 
  . 
  . 
  

Alternatives to AREAs

If program units which use AREAs are to be copied from one application to another, problems may arise when using AREAs owing to possible differences in the parameter lists. For this reason, AREAs in the local part of an application program should be replaced by data declarations with the EXTERNAL clause. In this case, you do not have to program the AREA declaration in KDCDEF or the AREA data declaration in the LINKAGE SECTION and in the PROCEDURE DIVISION; a data declaration is required in the WORKING-STORAGESECTION with an EXTERNAL clause.

Example

Rather than define:

LINKAGE SECTION.
   .
   .
01 AREA1. 
    02 DATA-ID  PIC X(8). 
    02 DATA-EX  PIC X(4000).

it would be better to define:

WORKING-STORAGE SECTION.
01 COMMON1 IS  EXTERNAL.
    02 DATA-ID  PIC X(8).
    02 DATA-EX PIC X(4000).

In this example, the COMMON area COMMON1 is defined in such a way that can be loaded as shareable. It can be defined as follows:

For BS2000 systems, for example, in assembly language

COMMON1  CSECT PUBLIC 
COMMON1  RMODE ANY
COMMON1  AMODE ANY
* 
DATA_ID  DC C'DATA-ID1'
DATA_EX  DS CL4000 
         END

If the COMMON area is to be loaded locally in the process, then you do not need to specify the PUBLIC attribute.

For Unix, Linux and Windows systems in C

struct COMMON1 {
char DATA_ID [8] = "DATA-ID1";
char DATA_EX [4000];
}