Chapter 15: Compatibility with the Mainframe Environment

This chapter describes facilities provided by Mainframe Express that emulate the following mainframe features:

Mainframe pointers for COBOL programs
Entry point mapping for COBOL and Assembler programs
Allocating a data set using the DATACLAS parameter through Storage Management Subsystem (SMS)

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

AMODE Compiler Directive

You need the AMODE directive for any program module which:

Creates mainframe-style pointer items - using the syntax:
```
SETpointer-item
TO ADDRESS OF data-item
```
Uses mainframe-style pointer items using the syntax:
```
SET ADDRESS OFlinkage-item
TO pointer-item
```
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.

The following table shows the settings for AMODE and DATA that are required for a number of COBOL dialects:

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

Mainframe Express implicitly sets the AMODE and DATA directives depending on the dialect you have specified, so they are not displayed in the Build settings field on the COBOL tab of the Build Settings dialog box.

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, although we do not recommend it as good practice.

You can enable this facility by using the mfpm_access_cancelled_data tunable or by checking Enable access to canceled programs' Data Divisions on the COBOL 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 Section 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.

Entry Point Mapping for COBOL and Assembler Programs

The Entry Point Mapper 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 that will not have been loaded prior to them being called.

To appreciate why and when to use this facility, you need to understand how calls to entry points are resolved by the run-time system:

When a program that is not statically linked makes a call to an entry point, the run-time system looks for the entry point to resolve it dynamically. In statically linked programs, the entry points are resolved during linking, and the Entry Point Mapper isn't needed.
When the 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.
Consequently, if your program calls an entry point that is not the name of an executable file and 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 when you need to use the Entry Point Mapper.

Entry points are often not found 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 ensure the enty points are found, you use the Entry Point Mapper. You create an entry name map file containing an entry point table and make it available to the run-time system.

Creating an Entry Name Map File

There are two tools you can use to create 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.
A text editor.

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.

Creating the Entry Name Map File 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.

Note: If you check the Use concatenated MFENTMAP.DAT search option on the Project Settings dialog box, you cannot specify a location in the Generated file location field of the Entry Point Mapping dialog box. Instead, this field shows the first folder in the load library search order.

Creating the Entry Name Map File 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 entry name map file file is:

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

You can also specify an optional [ALIASED-ENTRY-POINT] line following the [ENTRY-POINT] line. If specified, this line defines an entry point name onto which the entry point specified by [ENTRY-POINT] is aliased.

For example:

[ENTRY-POINT]  XYZ 
[ALIASED-ENTRY-POINT] ENTA 
[PROGRAM-NAME]  * 
[SUBPROGRAM-NAME]  PGMA

causes XYZ to be aliased on the ENTA entry point in the program PGMA. This means that when XYZ is called by a program, entry point ENTA will be invoked.

Notes:

A tag, that is, the text in square brackets, must be in upper case.
A line beginning with # is treated as a comment.
You can specify an asterisk (*) for program name to indicate that any program in the run unit can call entry point B in program C.

Making Entry Name Map Files Available to the Run-time System

If you have created an entry name map file 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.

The entry point map file is called mfentmap.dat and by default 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.

To give you more flexibility when working with mfentmap.dat files, you can specify that Mainframe Express searches for them in different locations. The General subtab of the Execution tab of the Project Settings dialog box includes options that enable you to change where Mainframe Express looks for mfentmap.dat files as follows:

The Folder containing MFENTMAP.DAT field enables you to specify an alternative folder containing mfentmap.dat. The folder you specify can be on your local machine or on a network. Specifying a folder on a network is useful when there are a number of Mainframe Express users needing to use a common mfentmap.dat file.
Checking Use concatenated MFENTMAP.DAT search specifies that Mainframe Express looks for an mfentmap.dat file in each of the load libraries defined in a project's different workgrouping levels. If there are a number of mfentmap.dat files, the same entry point could be defined differently in multiple files; in this case, precedence is given to the definition in the mfentmap.dat file that was found first. To change the order in which Mainframe Express finds mfentmap.dat files, change the order in which the load library folders appear in the Workgroup View.

The General subtab of the Execution tab of the Project Settings dialog box also provides an option that enables you to control whether Mainframe Express looks for programs to load using mfentmap.dat before or after searching the load libraries for them; this is Search MFENTMAP.DAT before file system.

CICS-specific Entry Name Map Files

You can specify CICS-specific entry name maps in the file cics.mfentmap.dat in the project folder. These definitions take precedence over any definitions in other mfentmap.dat files. If you are not running or debugging a CICS application, the CICS-specific file is ignored and the usual precedence rules are used.

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 do this you must edit the entry name map file 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 1

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

Example 2

Consider the situation where you want to load a program by using a different name to that given to the source program. For example, your JCL might contain an instruction to load myprogx, whereas the actual name of the program is myprog. On the mainframe, you could achieve this by linking the program and giving it the required name. However, you cannot link COBOL programs in Mainframe Express; you therefore need to use the Entry Point Mapper to make an association between the name used to load the program and the actual program name.

For example, suppose your program is called myprog, but you instead want to use myprogx as the name to load to the program. The table entry required in the mfentmap.dat file is:

 [ENTRY-POINT] myprogx
 [PROGRAM-NAME] *
 [SUBPROGRAM-NAME] myprog

where [ENTRY-POINT] defines the alias name and [SUBPROGRAM-NAME] is the name of the executable program.

Using SMS Data Classes

A Storage Management Subsystem (SMS) data class is a template of data set attributes (such as record length and format) that you can specify is to be used when creating a new data set. Mainframe Express includes support for SMS data classes.

How to...

Once you have defined some data classes and made the data class definition file available you can refer to them using any of the following methods:

DATACLAS parameter of a JCL DD statement
DATACLASS parameter of a TSO ALLOCATE command
DATACLASS parameter of an IDCAMS DEFINE command
data class text unit (TU) of SVC 99 (DYNALLOC)

The same definitions file can be used by more than one user, ensuring consistency of data class definitions. Whenever a data class specification is missing, a default data class called MFEDFTDC is used, if it exists. This data class must exist in a project's data class definitions file for it to be available for that project.

For full information on SMS, see the DFSMSdfp Storage Administration Reference available from the IBM BookManager Server Library.