Chapter 5: Developing CICS Applications

This chapter describes the technical aspects of developing CICS applications.

Mainframe-style Pointers

This COBOL system enables the contents of pointer items to be stored in a format that is compatible with that used on an IBM mainframe. You can redefine both USAGE POINTER and CICS BLL cell data items as USAGE PIC S9(9) COMP and can perform full arithmetic on such items. You control the use of mainframe-style pointers with the AMODE compiler directive; there is a choice between 24-bit pointers, 31-bit pointers or NO AMODE, depending on the dialect in use; programs compiled with NO AMODE use PC-style pointers and are known as non-AMODE compiled programs. For full details see AMODE Compiler Directive in the topic Compatibility with the Mainframe Environment.

AMODE and Non-AMODE Compiled Programs

You can run transactions that use both AMODE and non-AMODE compiled programs within the same region. However, within each discrete transaction all programs must be either AMODE-compiled or non-AMODE compiled. You should be especially aware of this when using supplied system transactions such as the mirror transaction (CVMI or CPMI) for inbound system communications or facilities such as the autoinstall exits, as these are non-AMODE compiled and could cause problems if you try to execute them with AMODE-compiled programs.

If you are using distributed program linking, you can get round this problem by setting a value for communications area override. We recommend that you set communications area override at the individual program level in the PPT definition. To do this, set a value in Commarea on the CICS PPT page of ESMAC. If you are not sure what value to set it to, set it to the maximum, 32,767 bytes.

Forcing a Program to be Reloaded

By default, when a transaction program is canceled, it remains in memory. This behavior improves performance because the program does not need to be reloaded if it is called a subsequent time. However, it also means that you can't load a updated version of the program without closing down the enterprise server and starting it up again. If you are actively working on one or more programs that run in your enterprise server, and you want to ensure that the latest version is loaded every time, you can force programs to be reloaded each time they are called by checking Program Force phase in on the SIT page in ESMAC. Alternatively, you can force an individual program to be reloaded by using the Phasein function of the transaction CPMT.

Accessing Large VSAM Files

You might find that VSAM files larger than 1 GB (gigabyte) cannot be accessed. This is because the default record locking mechanism in Mainframe Express uses the top two bits of the file address for locking and compression bits, thus reducing the address space for the maximum offset from 4 GB to 1 GB for a shared idxformat 3 or 4 file. If you encounter this problem, you should change the record locking mechanism for the file. To do this:

If the large VSAM files are set to OPEN, (which means that the files are opened when the CICS region is started) verify that Integrated Fileshare Support on the SIT is enabled.
Create a file handler configuration file that sets LOCKTYPE to 2 for the files causing the problem. With this setting, the file handling mechanism creates a separate file for storing record locks, with the same basename as the file and a .lck extension.
Set the EXTFH environment variable to point to the file. The default file name is extfh.cfg.

The file handler configuration file lists defaults for all files under the tag [XFH-DEFAULT], and settings for individual files under a tag consisting of the filename. For example, the following configuration file sets BASENAME=ON (which means that you do not need to supply pathnames for files) and sets the lock type to 2 for the file myfile:

[XFH-DEFAULT]
BASENAME=ON
[MYFILE]
LOCKTYPE=2

Abends in Transaction Programs

Transaction program abends are reported through the TXKC0001E system message. Generally these abends are caused by a standard CICS error condition. The abend codes (and descriptions) in these cases are the same as the abend codes issued for those conditions in the mainframe environment. You should refer to the IBM CICS/ESA Messages and Codes manual for these codes and descriptions.

In addition to these errors, the emulator can encounter conditions that do not match a standard CICS error condition but where the transaction cannot proceed successfully and so must be abended. These abend codes are:

ASSA

Your development system issues the ASSA abend code if it encounters either of the following:

an invalid resource name
a lack of storage

when it is dynamically creating a resource entry (for example, a PPT entry).

Use the diagnostic tools and log files to determine the cause of the error.

EXIF

Your development system issues the EXIF abend code if your program calls the CICS API with parameters that do not conform to the specifications. The most likely cause is that the transaction program was compiled from a translated source file that has been modified incorrectly.

FUNC

The FUNC abend code is issued when an unsupported CICS API function is requested. It is caused by the execution of an EXEC CICS command that was identified by the preprocessor as unsupported and the /CICSECM(FUNCTION=ABEND) preprocessor directive (abend at execution) was specified.

IRST

The IRST abend code is issued when the program control functions for saving and restoring Working Storage have encountered an illogical condition; generally a system error.

LANG

The LANG abend code is issued when different dialects of COBOL are mixed in a run unit, for example, a program written in VS COBOL II calls a program written in OS/VS COBOL.

MATP

The MATP abend code is issued when there is insufficient memory for the API Emulation server to allocate the control block needed for the target program of a LINK, XCTL, or VS COBOL II CALL.

MBLL

The MBLL abend code is issued when there is insufficient memory for the API Emulation server to allocate the BLL Cell List area for an OS/VS COBOL transaction program.

MCOM

The MCOM abend code is issued when there is insufficient memory for the API Emulation server to allocate a COMMAREA to be passed to a user transaction program invoked through XCTL.

MUSR

The MUSR abend code is issued when there is insufficient memory for the API Emulation server to allocate the file or terminal buffer for data to be returned to the user transaction program.

RECU

The RECU abend code is issued when an attempt is made to CALL (using DFHEIBLK) a user transaction program that is already active in the current CICS LINK level.

Using the SET Option of the BMS-related SEND Functions

To be able to support the SET option of the BMS-related SEND functions, your development system returns a fake TIOA address in the low-order three bytes of each entry in the Page List. To make use of a fake TIOA address, you need to convert it to a real (usable) TIOA address using DFHMFSET.

You need to modify every program that uses the SET option of the following BMS functions:

SEND CONTROL
SEND MAP
SEND PAGE
SEND TEXT

You also need to modify every program that uses the addresses in the resulting Page List.

Converting a Fake TIOA Address to a Real TIOA Address

Enter the following on the command line:

call "DFHMFSET" using page-list-entry
                      address-field

where:

page-list-entry is a four byte area, containing the value of one entry from the Page List (returned in the area addressed by the address returned for the SET option on a BMS SEND command). It might be the actual entry or some other area. Its value must be one of the current valid values in the list. The end of the list is marked by a mainframe NULL pointer data item (x'FF000000').
address-field is a four byte area.
- For OS/VS COBOL it should be defined and used as a BLL Cell value, that is S9(8) COMP.
- For VS COBOL II it should be defined and used as a POINTER data item.

Note: The end of the list is always signalled by an entry with high-values in the high-order byte and low-values in the low-order three bytes. On the mainframe, this corresponds to the defined value used for NULL pointer data items, but not to a NULL pointer value in the Micro Focus COBOL environment. The test for the end of the list should always be done by explicitly testing for high-values in the high-order byte of an entry.

Restrictions on Using DFHMFSET

The following restrictions on using DFHMFSET apply:

The DFHMFSET entry point should only be called in programs preprocessed by the CICS preprocessor.
The conversion of any fake TIOA addresses in the Page List must be done before the Page List is reused. Subsequent BMS SEND commands specifying the SET option will only reuse the Page List if the first "logical message" has been completed (by SEND PAGE, PURGE MESSAGE, or SYNCPOINT).
In OS/VS COBOL only, a SERVICE RELOAD must be done for the associated 01-level if the actual BLL cell is used as the second parameter on the call to DFHMFSET. This is necessary to let the compiler know that it must re-establish the base address for that 01-level using the (possibly) changed value in the BLL cell.
The Page List returned cannot exceed 127 entries (plus one for the "end-of-list" entry).

Examples

The OS/VS COBOL and VS COBOL II examples each provide the same function. They show a simple case of the use of the DFHMFSET entry point with the Page List that is returned for the SET option on BMS SEND commands.

They each do a SEND MAP command using the SET option that returns the address of a Page List containing the address of the datastream in the first entry. Note that the second entry of the Page List contains the end-of-list marker. The examples convert the Page List entry to a "real" TIOA address for the built datastream, establish the addressability for the datastream, and actually send it to the terminal using a SEND TEXT MAPPED command.

Note that the PIC X(9999) for PAGE-DSC-AREA and the value of 5 in the OCCURS clause for PAGE-LIST-ENTRY are not in themselves significant; they are just the values used in this example.

OS/VS COBOL Example

WORKING-STORAGE SECTION.
        .
        .
     05  PAGE-LIST-ADDRESS       PIC S9(8)   COMP.
     05  PAGE-DATA-ADDRESS       PIC S9(8)   COMP.
        .
        .
 LINKAGE SECTION.
        .
        .
 01  BLL-CELL-LIST.
     05  FILLER                  PIC S9(8)   COMP.
     05  PAGE-LIST-BLL-CELL      PIC S9(8)   COMP.
     05  PAGE-DATA-BLL-CELL      PIC S9(8)   COMP.
*
 01  PAGE-LIST.
     05  PAGE-LIST-ENTRY              OCCURS 5 TIMES.
         10  PAGE-TERMINAL-TYPE  PIC X.
         10  PAGE-DSC-ADDRESS    PIC XXX.
 01  PAGE-DATA-AREA.
     05  PAGE-TIOA-PREFIX.
         10  FILLER              PIC X(8).
         10  PAGE-LENGTH         PIC 9(4)    COMP.
         10  FILLER              PIC X(2).
     05  PAGE-DSC-AREA           PIC X(9999).
        .
        .
 PROCEDURE DIVISION.
        .
     EXEC CICS SEND    MAP    ('MAPNAME')
                       MAPSET ('MSETNAM')
                       SET    (PAGE-LIST-BLL)
     END-EXEC.
        .
        .
     CALL 'DFHMFSET' USING PAGE-LIST-ENTRY (1)
                           PAGE-DATA-ADDRESS.
     MOVE PAGE-DATA-ADDRESS TO PAGE-DATA-BLL-CELL.
        .
        .
     EXEC CICS SEND TEXT MAPPED
                       FROM    (PAGE-DSC-AREA)
                       LENGTH  (PAGE-LENGTH)
     END-EXEC.
        .

VS COBOL II Example

        .
        .
 WORKING-STORAGE SECTION.
        .
        .
     05  PAGE-LIST-ADDR          POINTER.
     05  PAGE-DATA-POINTER       POINTER.
        .
        .
 LINKAGE SECTION.
        .
        .
 01  PAGE-LIST.
     05  PAGE-LIST-ENTRY              OCCURS 5 TIMES.
         10  PAGE-TERMINAL-TYPE  PIC X.
         10  PAGE-DSC-ADDRESS    PIC XXX.
 01  PAGE-DATA-AREA.
     05  PAGE-TIOA-PREFIX.
         10  FILLER              PIC X(8).
         10  PAGE-LENGTH         PIC 9(4)    COMP.
         10  FILLER              PIC X(2).
     05  PAGE-DSC-AREA           PIC X(9999).
        .
        .
 PROCEDURE DIVISION.
        .
        .
     EXEC CICS SEND    MAP     ('MAPNAME')
                       MAPSET  ('MSETNAM')
                       SET     (PAGE-LIST-ADDR)
     END-EXEC.
        .
        .
     CALL 'DFHMFSET' USING PAGE-LIST-ENTRY (1)
                           PAGE-DATA-POINTER.
     SET ADDRESS OF PAGE-DATA-AREA TO PAGE-DATA-POINTER.
        .
        .
     EXEC CICS SEND TEXT MAPPED
                       FROM    (PAGE-DSC-AREA)
                       LENGTH  (PAGE-LENGTH)
     END-EXEC.
        .