Chapter 15: Compatibility with the Mainframe Environment

This chapter describes facilities provided by Mainframe Express that enable emulation of the following mainframe features:

Mainframe pointers for COBOL programs
Entry point mapping for COBOL and Assembler programs

15.1 Mainframe Pointers

To provide compatibility with mainframe-style pointers in COBOL programs, Mainframe Express:

Provides and sets the AMODE compiler directive
Enables continued access to the data of a canceled subprogram by the calling program

15.1.1 AMODE Compiler Directive

You need the AMODE directive for any program module which:

Creates mainframe-style pointer items (using SET pointer-item TO ADDRESS OF data-item syntax)
Uses mainframe-style pointer items (using SET ADDRESS OF linkage-item TO pointer-item syntax)
Contains a Working-Storage item passed to a subprogram that creates a mainframe-style pointer item which points to that Working-Storage item

Mainframe Express also provides and sets the DATA compiler directive that can control the placement of the Data Division of a program compiled using the AMODE compiler directive.

Mainframe Express sets the directives as follows:

COBOL Dialect	Directive
COBOL 370	AMODE(31) DATA(31)
VS COBOL II (all releases)	AMODE(31) DATA(31)
OS/VS COBOL	AMODE(24)

Note: You cannot see the directives in the Build settings field on the Build Settings dialog box as they are set implicitly.

For more details of the AMODE and DATA directives, see the topics for these directives in the on-line help: Help Topics on the Mainframe Express Help menu, then on the Contents tab click Reference, Development Environment, Compiler Directives.

15.1.2 Accessing Data in a Canceled Program

On the mainframe, a COBOL program can continue to use the data defined in the Data Division of a subprogram even after that subprogram has been canceled. This facility has been emulated in Mainframe Express though we do not recommend it as good practice.

You can enable this facility by checking Enable access to canceled programs' Data Divisions on the General page of the Execution page of the Project Settings dialog box.

Before the subprogram is canceled, you should set pointer variables in the calling program to the addresses of the data in the subprogram that you want to continue to use. Then, after the subprogram is canceled, you can continue to use that data until Mainframe Express releases the Working-Storage of the canceled subprogram. This can occur if:

There is insufficient storage available to satisfy a new storage request
The canceled subprogram is reloaded. In this case, the old Working-Storage area is released and a new area allocated and initialized.
The application terminates

Any attempt to use a pointer variable that still points to a released Working-Storage area will have unpredictable results.

15.2 Entry Point Mapping for COBOL and Assembler Programs

The Entry Point Mapping facility enables you to specify entry points in COBOL and Assembler programs so that the application can find them at run time.You need to do this for any entry points in programs which will not have been loaded prior to them being called.

To appreciate the functions that this facility performs, you need to understand how calls to entry points are normally resolved using the run-time system.

When a program makes a call to an entry point in which the entry point has not been resolved by statically linking the program, the run-time system looks for the entry point to resolve it dynamically.

When a program is loaded, the name of the program and all the entry points in the program are recorded in a table. When a call to an entry point is made, the run-time system searches the table for the entry point-name. If it does not find the entry point-name, it looks on disk for an executable file of the same name. If it does not find one it returns an error.

Consequently, if your program calls an entry point that is not the name of an executable file or is not an entry point in a previously loaded program, the run-time system cannot find the entry point and your program fails. This is the only case where you need to use the Entry Point Mapper.

This problem often occurs when you take code that has been downloaded from a mainframe to the PC for further development. Mainframe programs often have several entry points in a single program. On the mainframe, entry points are resolved by linking, so calls can be made to a program and the entry point located whether or not the program has been called.

Using Mainframe Express, if the program containing the entry point has not already been called, the call to that entry point fails.

To get round this problem, you need to create an entry-name map file containing an entry point table and make it available to the run-time system. There are two methods of creating an entry-name map file:

The Entry Point Mapping facility provided in the IDE. We recommend this method if the programs in your application are in COBOL
Create the file using a text editor. This is the only method available if the programs are in Assembler.

If you have an application with a mixture of COBOL and Assembler programs, you can create the table entries for the COBOL programs using the Entry Point Mapping facility and add the table entries for the Assembler programs using the text editor.

The entry point map file is called mfentmap.dat and it must be held in the project's loadlib folder. For example, if your project is called myproject and you use the default directory names, the full path is:

mfuser\projects\myproject\mfentmap.dat

The Entry Point Mapping facility automatically creates the file in the correct folder.

15.2.1 Creating the Entry Name Map using Entry Point Mapping

To create an entry name map using Entry Point Mapping, click Alternate Entry Points on the Build menu. You see the Entry Point Mapping dialog box. Use this dialog box to specify the programs for which you want entry points mapped.

15.2.2 Creating the Entry Name Map using a Text Editor

If you create your map file with an editor you must manually enter all the text required. For each entry point you need to enter the following three lines:

[ENTRY-POINT] entry-point-name
[PROGRAM-NAME] main-program-name
[SUBPROGRAM-NAME] subprogram-containing-entry-point

Example

Consider a run unit with a main program A and subprogram C. Within the run unit, A calls entry point B which is in program C. The table entry in the mfentmap.dat file is:

[ENTRY-POINT] B
[PROGRAM-NAME] A 
[SUBPROGRAM-NAME] C

Note: A tag, that is, the text in square brackets, must be in upper case.

15.2.3 Making the Map File Available to the Run-time System

If you have created an entry name map for a project, the Entry Name Mapping facility is automatically switched on. If Mainframe Express cannot find an entry point when debugging or executing a program, it searches the map file mfentmap.dat for the name that has been called.

15.2.4 Creating an Alias

For Assembler programs you can use the ALIAS command to create an alias mfentmap.dat entry automatically during the static link process for a load module. For example, to create an alias name of pacct001, the Assembler (.lin) file command line is:

ALIAS pacct001

For COBOL programs you must use the manual method since it does not have automatic processing during linking. To do this you can use the Entry Point Mapper to emulate the alias function of an IBM mainframe linkage editor, which redirects the system to execute a program accessed via an alias name. To enter aliases manually, you must edit the file mfentmap.dat using a text editor. You cannot enter aliases into this file using the Entry Point Mapping dialog box.

At run time, Mainframe Express first looks for a program with the original name. If it finds one, it does not invoke the Entry Point Mapper.

Enter the alias on the [ENTRY-POINT] line and the actual program name on the [SUB-PROGRAM] line.

Example

Consider a run unit with a main program named progroot. Within the run unit, progroot issues a call using the name pacct001. The actual name of the subprogram required is tacct001. The table entry in the mfentmap.dat file is:

[ENTRY-POINT] pacct001 
[PROGRAM-NAME] progroot 
[SUBPROGRAM-NAME] tacct001

Rebuilding Corrupt Indexed Files

Running a TSO Session