Chapter 2: Developing CICS Applications

This chapter describes the technical aspects of developing CICS applications with Mainframe Express.

2.1 Mainframe-style Pointers

Mainframe Express 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 the section AMODE Compiler Directive in the chapter Compatibility with the Mainframe Environment in your User's Guide.

2.1.1 The AMODE Setting for the Project

As well as setting AMODE for individual programs, you may also need to set it for the CICS project as a whole. CICS Option runs in 24-bit AMODE by default. You don't need to change the default just because you compiled your CICS programs with AMODE 31, because the project-level setting only affects access to shared areas such as the common work area (CWA), and both AMODE 24 and AMODE 31 programs can access these areas when they have 24-bit addresses. However, if you have previously changed the setting from the default AMODE 24 to AMODE 31, you should make sure you reset it to AMODE 24 if your programs are compiled with AMODE 24. You change the setting by selecting AMODE 24 or AMODE 31 on the CICS page of the Project Settings dialog box (click Project Settings on the Project menu of the IDE).

2.1.2 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, in the CICS View double-click a PPT entry in the right-hand pane and on the Advanced page set a value for Commarea override. Alternatively you can set an override for the whole project. to do this, in the CICS View right-click CICS System in the left-hand pane and click Properties, then on the Overrides page set a value for Commarea override. This works because if you set an override value CICS Option stores the commarea separately and handles addressing according to the AMODE setting of the called program. If you are not sure what value to set it to, set it to the maximum, 32767 bytes.

2.2 Forcing a Program to be Reloaded

By default, when a transaction program running in a multi-tasking region 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 region and starting it up again. If you are actively working on one or more programs that run in your region, 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 Force program PHASEIN on the Development page of the SIT Properties dialog box. Alternatively, you can force an individual program to be reloaded by using the Phasein function of the transaction CPMT.

2.3 Abends in Transaction Programs

The CICS Option reports transaction program abends 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

Mainframe Express 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

Mainframe Express issues the EXIF abend code if your program calls the CICS Option 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.

MFPE

The MFPE abend code is issued when a program checked with AMODE(24) is invoked and AMODE support is set to 31 in the project. The following table shows the valid combinations of SIT/project settings and compile AMODE settings.

Program AMODE Setting	Project (SIT) AMODE Setting
Program AMODE Setting	24	31
24	Y	N
31	Y	Y

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 (a VSC2 CALL using DFHEIBLK) a user transaction program that is already active in the current CICS LINK level.

2.4 Using the SET Option of the BMS-related SEND Functions

To be able to support the SET option of the BMS-related SEND functions, Mainframe Express 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.

2.4.1 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.

2.4.2 Restrictions on Using DFHMFSET

The following restrictions on using DFHMFSET apply:

The DFHMFSET entry point should only be called in programs preprocessed by the Mainframe Express 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 by Mainframe Express cannot exceed 127 entries (plus one for the "end-of-list" entry).

2.4.3 Maintaining Mainframe Compatibility

You can still maintain full compatibility with the mainframe by coding a simple COBOL program (called DFHMFSET) for use on the mainframe that clears the high byte and returns the passed value as the converted TIOA address. You can then link this program on the mainframe, with any of the programs that were changed on the PC to use the DFHMFSET entry point.

2.4.4 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.

2.4.4.1 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.
        .

2.4.4.2 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.
        .