Chapter 7: Calling Programs on the Mainframe

Moving your mainframe applications to the PC enables you to take advantage of Mainframe Express' powerful editing and debugging environment. There are instances, however, when it is not possible to move part of an application from the mainframe, and in some of these cases you can use Mainframe Express' Mainframe Call Generator.

The following are all things that an application might do that, without the use of the Mainframe Call Generator, would prevent it from being used with Mainframe Express:

Communicate with a third-party product on the mainframe.
Use MVS/390 control blocks that are not supported by Mainframe Express.
Communicate with database systems that are not available on the PC, such as DATACOM.
Call subprograms written in an MVS/390 programming language such as C, C++ and Java, for which there is no PC version because of the required EBCDIC support.

This chapter describes the Mainframe Call Generator, how it works, and how you use it your applications.

7.1 How the Mainframe Call Generator Works

The Mainframe Call Generator works by creating a stub program for each mainframe-hosted program your application needs to call. When invoked, a stub program calls the corresponding program on the mainframe (using communications provided by Mainframe Access' SourceConnect). Figure 7-1 shows the events that happen when a stub program is invoked.

Figure 7-1: A Stub Program Calling a Mainframe-hosted Program

7.2 Preparations

Before you start using the Mainframe Call Generator, there are a few preparatory steps you need to perform:

Check the information in the Known Errors and Restrictions section of the Readme help to make sure your application is suitable for use with the Mainframe Call Generator.
Ensure that you have the correct software installed and correctly configured. You need to have the Mainframe Call Generator PTF (MFCG01) installed on your mainframe, and IDE FixPack v2.5.008 (ide08m25) installed on the PC.
Ensure that each user who will be running stubs is set up with the following:
- A valid user id and password for the mainframe.
- A working Mainframe Access connection, including a drive defined to be used with SourceConnect. See your Mainframe Access documentation for information on how to do this..
In addition to these steps, each user who will be creating stubs must have the environment variable MCGAdmin set to any value. See your operating system documentation for details of setting environment variables.
Create a folder you want to store the generated stubs in. You need to consider whether you want to use one folder per application or one folder for all of your applications.
Create a template project. When creating the project, specify the stubs folder as the last of the project's load libraries in the lowest workgrouping level (to ensure that the subprogram is only called on the mainframe if a version does not exist anywhere else). This is the project that each user will need to use when creating their own projects, so should be made available to each user.

7.3 Creating Stubs

The process for generating and using stubs to run programs on a mainframe is as follows:

Carry out the steps in the section Preparations, to make sure that your environment is set up correctly and that your programs are suitable for use with the Mainframe Call Generator.
Specify the program containing the subprograms you want to create stubs for. Note that Mainframe Call Generator will not generate a stub for a subprogram that does not take at least one parameter.
Create the stubs using the Mainframe Call Generator window. Full information on how to do this is in the online help. When you create a stub, an extra tab, MCG Build is added to the Output window to show the status of the stub generation.
Run your program as normal. When a subprogram with a generated stub is encountered, control is passed to the subprogram on the mainframe, which executes, then control returns to your program.

7.3.1 The Mainframe Call Generator Dialog Box

Once you have specified the programs containing the subprograms you want to create stubs for, information about the subprograms is displayed in the Mainframe Call Generator dialog box. It is from the Mainframe Call Generator dialog box that you specify the subprograms to create stubs for. Figure 7-2 shows a typical Mainframe Call Generator dialog box.

Figure 7-2: The Mainframe Call Generator Dialog Box

The following list shows the information presented by the Mainframe Call Generator dialog box:

Column	Description
Name	The name of the called subprogram. If the called subprogram's name is specified by a data item, the name of the data item is shown.
Target	The name of the subprogram to be called on the mainframe. This is usually the same as the program-name in the Name column, but can be changed by editing a subprogram's properties.
Status	The status of the call to the subprogram. This can be one of the following: Resolved - the called subprogram's .gnt or .int code has been found in one of the load libraries of the Mainframe Express project. Unresolved - the called subprogram's .gnt or .int code has been found in one of the load libraries of the Mainframe Express project. Dynamic call, questionable name - the call is to a subprogram whose name is specified by a data item.
Module Type	Whether or not the COBOL subprogram is optimized. This can be one of the following: COBOL load module (non-optimized) - the subprogram has been compiled to intermediate (.int) code. COBOL load module (optimized) - the subprogram has been compiled to generated (.gnt) code. Assembler - the subprogram is written in Assembler. Dynamic link library (DLL) - the subprogram is in a dynamic link library.
DB2	Whether or not the called subprogram uses DB2. Edit the subprogram's properties to change this setting.
Call Type	The type of call made that will be made when the application is run. This can be one of: Application - the application will call a user-written subprogram. MCG - the application will call a stub generated by the Mainframe Call Generator. blank - Mainframe Call Generator is unable to determine the type of call.
Location	The location of the found subprogram.

7.4 Running the Generated Stubs

Once you have created the stubs for your subprograms, you can run the calling program in the usual way. When calls to the mainframe-hosted subprograms are encountered, those subprograms are invoked by the generated stubs, so the calling application runs in the same way regardless of whether its subprograms are hosted on the mainframe or a local PC.

When a stub executes, you might be prompted for additional information:

When running a stub for the first time, Mainframe Access prompts you for your user id and password.
When running a stub for a subprogram that uses DB2, Mainframe Call Generator prompts you for the subsystem and plan to connect to. An extra tab, MCG DB2 Connection Status is added to the Output window to show the status of the connection to the DB2 data.

7.5 Tailoring the Mainframe Call Generator's Behavior

Most of the time, the Mainframe Call Generator's default behavior will be enough to enable you to run your mainframe-hosted subprograms. This section describes aspects of the Mainframe Call Generator's behavior that you can change when the default behavior is not right for your application.

7.5.1 Specifying that a Subprogram uses DB2

If the subprogram you are calling uses DB2, you need to specify this in the subprogram's properties, in order for the Mainframe Call Generator to insert additional code in the generated stub. See the online help information on how to change the properties of a subprogram to specify that it calls DB2.

When using Mainframe Call Generator to run a mainframe-hosted subprogram that uses DB2, you are prompted to specify the subsystem and plan to connect to.

7.5.2 Specifying a Different Name for a Subprogram

By default, the stub created by the Mainframe Call Generator calls a mainframe subprogram with the same name as the stub. However, if you want the stub to call a program with a name different to that of the stub, the Mainframe Call Generator lets you do this by specifying a different target name in a subprogram's properties. This would be useful if you wanted to call a mainframe program that had an alias on the mainframe environment. For example, to call a program called MQGET on the mainframe, where the program MQGET has an alias called CSQBGET on the mainframe batch environment, you could create a stub called MQGET that called subprogram CSQBGET on the mainframe. See the online help information on how to change the properties of a subprogram to specify it calls an alternative target name.

7.5.3 Keeping the Stub Source Code

By default, when you create a stub for a subprogram, the Mainframe Call Generator creates a COBOL program, compiles it to .gnt code, then deletes the COBOL program (as it is only the .gnt code that is required for your program to access the subprogram on the mainframe).

If you need to keep the COBOL program that the Mainframe Call Generator produces, check Keep stub program source on the Mainframe Call Generator window before you generate the stubs. The programs generated with this option are created in the specified generation directory, with the extension .bb.