This chapter describes the technical aspects of developing CICS applications with Mainframe Express.
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.
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).
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.
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.
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:
Mainframe Express issues the ASSA abend code if it encounters either of the following:
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.
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.
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.
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.
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.
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.
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.
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.
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|
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.
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.
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:
You also need to modify every program that uses the addresses in the resulting Page List.
Enter the following on the command line:
call "DFHMFSET" using page-list-entry
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.
The following restrictions on using DFHMFSET apply:
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.
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.
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. .
. . 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. .
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.