Mainframe Call Generator (MCG) Refresh - Micro Focus

Mainframe Call Generator (MCG) Refresh 

Confidential - 1 - December 2004 

Randy Witek Revision 3a 

Micro Focus Development

Mainframe Call Generator Refresh 


Randy Witek 

Micro Focus Development 

Contents 

Introduction _____________________________________________________ 3 

MCG operation __________________________________________________ 5 

DB2 attachment__________________________________________________ 8 

Dumping support ________________________________________________ 11 

Termination of misbehaving MCG programs ___________________________ 12 

New startup parameter ___________________________________________ 13 

New messages _________________________________________________ 14 

Appendix A: IGZERRE entry conditions and return codes_________________ 17 

Appendix B: MCG setup checklist ___________________________________ 18 

Appendix C: Sample MFA Server trace of MCG processing _______________ 19 

Figures 

Figure 1 - Mainframe Call Generator overview __________________________ 3 

Figure 2 - MFA Server task structure for MCG operation __________________ 5 

Figure 3 - Selecting MCG DB2 support during stub generation______________ 8 

Figure 4 - Specifying MCG DB2 connection information at runtime___________ 9


Introduction 

This article describes changes to Mainframe Call Generator that are introduced by Mainframe 

Access Server Version 3 software service. In order to use the features and operation as 

described in this article, MFA Server must be at the following minimum service level: 

MFA Server Version 3 + Service Pack 1 (SP1, July 2004) + FixPack 1a (FP1A, December 2004) 

-or- 

MFA Server Version 3 + Service Pack 2 (SP2, 1st quarter 2005) 

The Mainframe Call Generator (MCG) feature of Mainframe Express (MFE) provides a Remote 

Procedure Call (RPC) mechanism that allows PC-resident COBOL programs to transparently call 

z/OS-resident subprograms. Mainframe Access Server (MFA Server) provides the server-side 

support for the RPC and the called subprograms are dynamically loaded and executed by the 

server. 

Mainframe Express 

identification division. 

program-id. MYPCPROG. 

environment division. 

data division. 

working-storage section. 

01 ws-parm pic x(50). 

procedure division. 

move ’Calling mainframe program’ to ws-parm. 

call ’MYMFPROG’ using ws-parm. 

display ws-parm. 

goback. 

Figure 1 - Mainframe Call Generator overview 

The MCG z/OS execution framework is redesigned and enhanced in MFA Server FixPack 1a. 

The new design resolves a problem documented in RPI 1054397 and other issues highlighted by 

informal field inquiries. The most difficult problems were related to MFA Server’s z/OS task 

sharing architecture. The efficiency of sharing a z/OS task among multiple user sessions 

conflicted with some IBM service architectures that depend on a separate task instance for each 

concurrent user. IBM’s COBOL runtime environment and IBM’s DB2 attachment facilities are 

notable examples of such services. 


Randy Witek 


Mainframe 

Call 

Generator 

feature 

Mainframe Access Server 

identification division. 

program-id. MYMFPROG. 

environment division. 

data division. 

linkage section. 

01 lk-parm pic x(50). 

procedure division using lk-parm. 

move ’In MYMFPROG’ to lk-parm. 

display lk-parm. 

goback.


The solution is to manage the execution of each active MCG process in a subordinate z/OS task. 

This new MCG task is dedicated to one user’s MCG activity, but only for the duration of the user’s 

MFE-to-MFA Server MCG connection. The MCG user program executes as a separate z/OS 

work unit where program loops, excessive CPU consumption, long waits, etc. have little or no 

effect on other user activity. This also isolates the IBM COBOL runtime environment and/or DB2 

attachment for the user in that same task. Subordinate z/OS tasks are created on demand, one 

for each concurrent MCG user. When MCG activity for a user is completed, the subtask remains 

active, but waiting, to service the next MCG requester. 

This new design allows Mainframe Access Server Version 3 to support all of the MCG processing 

previously possible in Mainframe Access Version 2. In addition to merely supporting the old 

functionality, Version 3’s new design also improves the MCG feature with selectable DB2 

attachment, termination of looping and waiting MCG programs, improved diagnostic messaging, 

and detailed tracing of MCG activity. The FixPack maintenance description for this change 

summarizes the above discussion: 

Mainframe Call Generator (MCG) refresh (RPI 1054397) 

-------------------------------------------------------------------- 

The Mainframe Call Generator (MCG) feature is corrected and enhanced 

with the following changes: 

- Maintaining a mainframe COBOL runtime environment across multiple 

remote calls to, possibly, multiple program load modules 

- Execution of MCG programs under a separate z/OS Task Control Block 

- Formatted dumping to SYSUDUMP/SYSMDUMP for user program failures 

- Termination for user programs that may be looping or stuck in 

a WAIT that cannot be satisfied. 

- Ability to perform detailed tracing of MCG program activity 

- Ability to select either Call Attach Facility (CAF) or the 

Recoverable Resource Attachment Facility (RRSAF) as the 

DB2 connection type for SQL processing. 

*** SPECIAL NOTE *** 

The new parameter MFA_MCG_DB2CONNECTION can be used to explicitly 

select the DB2 connection type for SQL processing. The valid 

values for this parameter are RRSAF or CAF. The default value 

is RRSAF. 

*** SPECIAL NOTE *** 

You will need to add a SYSUDUMP or SYSMDUMP DD statement to each of 

your Mainframe Access Server started task JCL procedures to enable 

the dumping support for user program ABENDs. 

The remainder of this document describes the MCG refresh in detail. Appendix B provides a 

handy checklist for MCG program preparation. The annotated sample trace in Appendix C 

contains excellent tutorial information that may be useful to technical support and customer 

personnel. 


Randy Witek 



MCG operation 

The following diagram depicts the MFA Server z/OS task structure for MCG processing. The 

message flow on the left summarizes the client-server exchanges for a simple MCG remote 

program execution. The description that follows is keyed to the numbering of the client-server 

requests in this diagram. The same request sequence and numbering is used in the annotated 

sample trace of a MCG session. 

Figure 2 - MFA Server task structure for MCG operation 


Randy Witek 


XDBMFADM task 

XDBMFADM task 

1 - MFA connect (“logon”) 

2 - LSC logon with authentication 

3 - LSC RPC request 

4 - RPC send parameters 

5 - RPC execute ATTACH 

6 - RPC fetch parameters 



9 - RPC execute (with CLEANUP flag) 

MFARPC00 module 

parameter data 

MD@MCGEX module 

inter-task 

messaging 

MCGEXEC task MCGEXEC task MCGEXEC task 

MCGEXEC module 

user program load 

module 

BASSM


1 - MFA connect (“logon”) 

The initial connection message is really client identification. The Mainframe Access client 

connects to MFA Server through a TCP/IP listener that is common to all of the MFA Server client 

types. The content of this first message is examined by the server to determine the client type. 

2 - LSC logon with authentication 

The second exchange contains the userid and password. The message is a Library Services 

Connectivity (LSC) type-252 (0xFC action code is imbedded in the request) logon request. SAF 

authentication is mandatory for MFA clients and the server performs SAF authentication for the 

userid and password combination. 

The MFA client usually sends in a pre-set server return code at offset eight (8) into the message 

body. The 2-byte value is preset to 0x3030 (ASCII zeroes), a value that indicates success. The 

server updates this return field before sending each response. A return value of 0x3030 indicates 

success and other values provide error code information used by the client in preparing an error 

notification to the end user. The first 0x6C bytes of each message are a File Control Descriptor 

(FCD) structure that identifies the request type. Data, if required for a particular request or 

response, follows the FCD. 


The third exchange signals the beginning of a MCG RPC operation. The server will expect an 

ordered sequence of RPC exchanges to follow. At this point, the server directs subsequent 

message arrivals to the MFARPC00 module for processing. 


The next exchange sends the RPC parameters from the client to the server. The name of the 

load module and the call parameters from the COBOL “CALL module USING …” statement are 

packaged in a structure and sent in to the server. This data is saved in a corresponding serverside 

data structure. Multiple exchanges may be used, if needed, to send large amounts of 

parameter data. 

5 - RPC execute 

When all parameter data has been received, the execute request starts the real server-side 

action for the RPC. MFA server locates the requested program module and LOADs it in to virtual 

storage from the program library(s) identified by the MCGLIB DD statement in the MFA Server 

started task JCL procedure. A special z/OS directed LOAD is used that allows loading of 

unauthorized programs from unauthorized program libraries. The server selects an available 

MCG processing subtask (a new subtask is started if none are available), allocates the subtask to 

the current RPC request, and passes the RPC parameters to the subtask. Processing up to this 

point has all occurred in the threaded execution environment of the XDBMFADM task. 

The MCGEXEC subtask executes the RPC request by first establishing an ESTAE routine to trap 

any ABENDs. Then a COBOL environment is established if this is the first call in this MCG 

session. Otherwise, the existing COBOL environment is reused. IBM utility module IGZERRE is 

called to set up this COBOL environment and the overhead of this action is minimal. There is no 

requirement that the called program is a COBOL load module and the establishment (and 

maintenance of the environment across multiple calls during the MCG session) of the COBOL 

environment does not affect the execution of non-COBOL programs. Then register 1 is set with 

the parameter list address for the program and the program load module is branch entered. The 

BASSM branch instructions also sets the AMODE (24-bit or 31-bit addressing mode) required for 


Randy Witek 



specified load module. At this point the user program is in control of the MCGEXEC task and the 

XDBMFADM task is busy handling the threads of execution for other Mainframe Access clients. 

When the user program exits, the MFA Server support code in the MCGEXEC subtask receives 

control to complete the execution. The ESTAE protection is removed and the XDBMFADM task 

is signaled to complete the RPC execute request. The response to the client is sent indicating 

either successful execution (the user program was called and returned without ABENDing) or 

execution failure due to an ABEND or other server-side condition. 

In the above diagram, the MD@MCGEX module contains most of the server support logic for the 

execution phase. It is interesting to note that portions of this module execute as part of the 

XDBMFADM task, and other portions execute as part of the MCGEXEC subtask. 

6 - RPC fetch parameters 

The sixth client-server exchange is normally a fetch operation. When the client receives an 

indication of successful program execution, the fetch request is sent to retrieve the RPC 

parameters from the server. Any data areas in the RPC parameters that were updated by the 

called program can be seen in the returned RPC parameter structure. 

This fetch completes the first remote program execution. Repeated calls to a remote program in 

this MCG session would be seen as a series of 

- LSC RPC request 

- RPC send parameters 

- RPC execute 

- RPC fetch parameters 


In this simple example, there is only one call to a remote program. The final client-server 

exchanges appear to be the start of a second execution. The seventh exchange again signals 

the start of a MCG call operation. 


The eighth exchange is technically a “send parameters” request but there is no real parameter 

data. 

9 - RPC execute (with CLEANUP flag) 

The last exchange is an execute request. A special flag bit in the request data indicates that this 

is a request for an RPC cleanup operation. At this time, the MCGEXEC subtask is signaled to 

perform its cleanup and terminate the COBOL environment that was previously established. 

Successful completion of the cleanup marks the MCGEXEC subtask as available. This subtask 

can now be reassigned to a new MCG session of program calls initiated by any Mainframe 

Access user. 


Randy Witek 



DB2 attachment 

The Mainframe Call Generator feature provides special support for z/OS subprograms that issue 

dynamic SQL calls to DB2. This DB2 support allows you to explicitly specify the DB2 subsystem 

and DB2 plan name used for the program’s attachment to DB2. 

The DB2 support is selected during MCG stub generation for the calling program in Mainframe 

Express. The following screen print shows the “Uses DB2” check box in the calling program’s 

MCG properties dialog. 

Figure 3 - Selecting MCG DB2 support during stub generation 


Randy Witek 



During MFE runtime, the MCG support for this subprogram call will prompt the end user for the 

DB2 subsystem name and the DB2 plan name to be used during the call. A sample of the 

prompting dialog is shown in the following screen print. 

Figure 4 - Specifying MCG DB2 connection information at runtime 

The DB2 subsystem and plan names are sent to MFA Server in a special subprogram call issued 

by MCG runtime support. MCG runtime calls pseudo-program TRANSCAF immediately before 

issuing the call for the DB2-using program. MFA Server recognizes this reserved pseudoprogram 

name and uses the parameter data (the DB2 subsystem name and the DB2 plan name) 

to establish a connection to the desired DB2 subsystem. This connection is then active when the 

next MCG subprogram call request is received, the call to the requested DB2-using subprogram. 

MCG runtime also issues a pseudo-program call to end the DB2 connection at the completion of 

client-side program execution. 

Prior to FixPack 1a, MFA Server’s connection to a DB2 subsystem was always established using 

the DB2 Recoverable Resource Manager Services attachment facility (RRSAF). Previous 

support for the DB2 call attach facility (CAF) was not brought forward to MFA Server. Beginning 

with FixPack 1a, MFA Server now allows the DB2 connection type to be selected using a startup 

parameter. You may specify the connection type as RRSAF or CAF. The default is RRSAF if 

this parameter is not specified. 

IBM DB2 imposes a restriction on calling address spaces that limits callers to the use of only one 

attachment facility. This means that the MFA Server startup parameter setting will direct all MCG 

DB2 calls to the selected attachment facility, either RRSAF or CAF. This is important to note 

because the attachment facility that is in use may conflict with the attachment facility specified 

during DB2 precompilation for a program. The situation is further complicated by the setting of 

the COBOL compiler DYNAM and NODYNAM option when compiling the program. The following 

table shows the result of MCG DB2 SQL execution for the various settings of these options. 


Randy Witek 



DB2 precompiler 

ATTACH option 


Randy Witek 


MFA Server 

attachment type 

COBOL compiler 

call option 

CAF RRSAF NODYNAM -991 

CAF RRSAF DYNAM -991 

CAF CAF DYNAM OK 

CAF CAF NODYNAM OK 

RRSAF RRSAF NODYNAM OK 

RRSAF RRSAF DYNAM OK 

RRSAF CAF DYNAM -981 

RRSAF CAF NODYNAM -981 

TSO RRSAF NODYNAM -927 

TSO RRSAF DYNAM OK 

TSO CAF DYNAM OK 

TSO CAF NODYNAM -927 

Not specified RRSAF NODYNAM -927 

Not specified RRSAF DYNAM OK 

Not specified CAF DYNAM OK 

Not specified CAF NODYNAM -927 

Explanation for SQL return codes: 

SQL result 

-981 The SQL statement failed because the RRSAF connection is not in a state that allows 

SQL operations. 

-927 The language interface was called when the connecting environment was not 

established. The program should be invoked under the DSN command. 

-991 Call attach was unable to establish an implicit connect or open to DB2. 

The table shows that the combination of the COBOL DYNAM option for dynamic program calls 

and the ATTACH(TSO) DB2 precompilation option (or simply omitting the ATTACH option) 

provides flexibility in the actual connection type. This is because the ATTACH(TSO) and 

ATTACH() specifications generate a call to entry point DSNHLI for SQL execution. MFA Server 

provides a dummy DSNHLI entry point that becomes the target of dynamic calls. The MFA 

Server DSNHLI routine routes the SQL execution to the attachment facility (RRSAF or CAF) that 

has been selected, or defaulted, at startup. The ATTACH(RRSAF) and ATTACH(CAF) 

specifications generate calls to DSNHLIR and DSNHLI2, respectively, and no dummy entry points 

are provided for these attachments. Therefore, the real DB2 interface routines are selected, 

either statically or dynamically, and these interface routines expect the required attachment to 

have been activated by MFA Server.


Dumping support 

MFA Server uses the z/OS SVCDUMP service to record software failures that occur in the server 

address spaces. This service provides high-speed recording of large amounts of system 

information that may be needed to resolve a server problem. The SVCDUMP mechanism is the 

ideal method of recording unexpected server programming failures that may involve z/OS 

component failures and/or failures in third-party software. 

The typical developer of MCG-based programs is used to analyzing program failures using 

formatted application program dumps captured by z/OS and recorded on SYSUDUMP (or 

SYSMDUMP, for machine-readable) files. The amount of system information captured is at the 

discretion of the customer systems programmer, but it is usually much less than is requested by 

our server SVCDUMPs. 

FixPack 1a expands the diagnostic dumping facilities provided by MFA Server’s ESTAE 

processing to include SYSUDUMP recording for MCG RPC program ABENDs. The ESTAE 

extension routine in module MD@MCGEX that intercepts MCG ABENDs uses new server 

ESTAE processing options to suppress the SVCDUMP and request the less rigorous 

SYSUDUMP. The new server ESTAE processing options for dumps are generalized and can be 

used in other MFA Server ESTAE extension routines in the future. 

No dump is produced for MCG program ABENDs unless an appropriate SYSUDUMP or 

SYSMDUMP DD statement is added to the server’s started task JCL procedure. The MFA 

Server started task JCL procedures, as distributed in the GA and Service Pack 1 samples prior to 

this FixPack, do not include the SYSUDUMP DD statement needed for this new dump recording. 

You must add the SYSUDUMP DD statement to any existing MFA Server JCL procedures. 


Randy Witek 



Termination of misbehaving MCG programs 

No restrictions are placed on the MCG RPC program logic and it is possible for a program to loop 

or enter a WAIT that will never be satisfied. In these cases, the end user only sees that the client 

is busy with a remote program call. Eventually, the client will be interrupted by a communications 

timeout and close the TCP/IP stream socket connection to the server. 

In previous implementations of the MCG RPC function (both Mainframe Access Version 2 and the 

original MFA Server Version 3), the socket close would not be recognized at the server. This is 

because the user program is in control of the task execution (either looping or waiting) and the 

server logic does not receive control to process communications events. 

In the new design, the user program execution in the MCGEXEC task is separated from the 

communications processing that now continues normally in the multi-threaded XDBMFADM task. 

MFA Server can respond to the client’s socket close and log the user off. The logoff cleanup 

processing for the user’s Mainframe Access session recognizes that a MCG subtask is still 

allocated to the user, and can force it down using the z/OS CALLRTM service to ABEND the 

subtask. The subtask is unconditionally ended with a User 201 ABEND code in this case. The 

end user can also force a program out using the “stop debugging” action before the expiration of 

the timeout period. 

The following excerpt from a test system shows a program starting at 14:40:53.2 hours. This test 

program enters an endless loop of processing and waiting. The MFE timeout value (a Windows 

environment variable) used in this test was set at 100 seconds and the socket connection was 

closed due to a communications error (a timeout) exactly 100 seconds later, at 14:42:33.2 hours. 

Message MFM0131E is issued during the cleanup processing to log the forced termination of the 

MCGEXEC task with a U201 ABEND. 

14:40:53.2 MCGEXEC 20 TMCGTEST - Input test name is "LOOP " 

14:42:33.2 XDBMFADM 19 MFM0112I SAF logoff for CSIRLW1 (sd=8 (13EDA970) rc=0 type=0) 

14:42:33.3 XDBMFADM 19 MFADirect close for sd=8 (13EDA970) ip=10.10.1.7 sent=8 rcvd=9 

14:42:33.3 XDBMFADM 19 MFM0131E Task MCGEXEC 13E99E28 TCB 008B7280 terminated U0201; 

callrtm rc=000 

Many cases of incorrect MCG program execution can be recognized and cleaned up using this 

forced termination. However, there are no restrictions placed on the user program and a MCG 

program can possibly damage the server address space in such a way that simple task 

termination fails to provide adequate cleanup. For example, the program can overlay server 

control blocks and data areas, allocate excessive virtual storage without releasing it at the 

conclusion of processing, consume address space and/or system resources without releasing, 

etc. It is also possible for incorrect MCG program execution to cause the server address space to 

fail without warning. In all cases of program failure and recovery (that is what the forced 

termination actually is), it is advisable to shutdown and restart the server at the earliest 

convenient time. 


Randy Witek 



New startup parameter 

FixPack 1a introduces one new startup parameter to select the DB2 attachment facility used for 

MCG DB2 SQL calls. 

Parameter Description 

MFA_MCG_DB2CONNECTION 

Example 

... 


Randy Witek 


Controls which attachment facility is used by MFA 

Server for DB2 connections. Specify CAF to use the 

DB2 call attach facility. Specify RRSAF to use the DB2 

Recoverable Resource Manager Services attachment 

facility. RRSAF is the default if this parameter is 

omitted. 

CGMQOTMA LOGDD=SYSOUT --- CG production log DDname or "SYSOUT" 

WEB_ROOT=HLQ.WEBROOT 

* 

*--------------------------------------------------------------------* 

* Mainframe Access services parameters * 

*--------------------------------------------------------------------* 

* 

MFA_ENDEVOR_HISTORY=YES --- Endevor MFALOGE history (YES,NO) 

MFA_LIBRARIAN_HISTORY=YES --- Librarian MFALOG history (YES,NO) 

MFA_LIBRARIAN_UPD_MODULE=AFOLIBR - Librarian batch update module name 

MFA_PANVALET_HISTORY=YES --- Panvalet MFALOG history (YES,NO) 

MFA_PANVALET_UPD_MODULE=PAN#1 --- Panvalet batch update module name 

MFA_SAF_HISTORY=YES --- Data set access MFALOG history 

MFA_SYSOUT_CLASS=A --- MFALOG,MFALOGE,SNAPDUMP class 

MFA_SYSOUT_DEST=LOCAL --- MFALOG,MFALOGE,SNAPDUMP dest 

MFA_MCG_DB2CONNECTION=CAF --- Select DB2 call attach facility 

* 

*--------------------------------------------------------------------* 

* Services to be activated * 

*--------------------------------------------------------------------* 

* 

TCP LINK FEATURE=YES --- MFE SQL Option, Telnet client 

MFADIRECT=YES --- Mainframe Access services 

...


New messages 

New diagnostic messages and tracing messages make it easy to follow the execution of MCG 

programs by reviewing MFA Server’s XDBOUT SYSOUT logging data set. When tracing is not 

active, new diagnostic messages are used to record program failures (for example, inability to 

load a requested program, ABENDs occurring within a MCG program, etc.) and exceptional 

conditions. When tracing is activated using the MFA Server "trace on" command, the new trace 

messages make it easy to examine the flow and content of client-server RPC data and the 

execution activity in the mainframe server. 

The new messages are presented here, grouped together with other new messages issued by 

the same module. The sample trace in Appendix C provides actual examples for most of the 

messages. 

Module MD@MCGEX messages 

This module provides support for MCG program execution and logic to interface between the 

MFA Server communications task (XDBMFADM) and the MCG program execution subtask 

(MCGEXEC). 

Messages for logging exceptional conditions 

MFM0128I MCG subtask MCGEXEC cc xxxxxxxx started for XDBMFADM cc xxxxxxxx 

This is a normal operational message to log the fact that a new subtask was started for MCG 

program execution. 

MFM0128E MCG Non-zero return from IGZERRE set call; rc=ddd 

The IBM IGZERRE module was called to establish a COBOL runtime environment but has 

indicated there is a problem by returning with a non-zero return code. See Appendix A for a 

description of the return code values. 

MFM0128E MCG Module IGZERRE is not available for set call 

This message indicates that the IBM IGZERRE module was not loaded during startup and could 

therefore not be called to establish a COBOL runtime environment. 

MFM0128E MCG Non-zero return from IGZERRE reset call; rc=ddd 

The IBM IGZERRE module was called to terminate a COBOL runtime environment during MCG 

cleanup but has indicated there is a problem by returning with a non-zero return code. See 

Appendix A for a description of the return code values. 

MFM0128E MCG No IGZERRE COBOL environment found for reset 

The MCG cleanup service found that no COBOL environment was previously established for the 

MCG session that is ending. 

Trace messages 

MCG COBOL environment set; IGZERRE rc=ddd 

The IBM IGZERRE module was successfully called to establish a COBOL runtime environment. 


Randy Witek 



MCG COBOL environment reset; IGZERRE rc=ddd 

The IBM IGZERRE module was successfully called to terminate a COBOL runtime environment 

during MCG cleanup. 

Module MFARPC00 messages 

This module is the driver for the MCG session. Processing of MCG client request messages 

starts in this driver module. 


MFM0129E MCG Unable to execute user program cccccccc 

An execute request could not be completed for the named program. Preceding error messages 

will identify the exact cause. 

MFM0129E MCG Unable to find or load user program cccccccc 

The z/OS BLDL or LOAD operation for the named program failed. Preceding error messages will 

identify the exact cause. 

MFM0129E MCG Request message sequence error 

An unexpected MCG request message was received from the client. The MCG request is not 

appropriate for the current state of the remote execution operation. Start the MFA Server trace 

facility and recreate the problem to create a log of messages showing the sequence of messages 

being exchanged. 

MFM0129E MCG Request message not recognized 

An unexpected request message was received from the client. The request message could not 

be identified as a MCG request. Start the MFA Server trace facility and recreate the problem to 

log the erroneous message. 

Trace messages 

MCG program parameter list located at xxxxxxxx 

This trace message is issued just before calling the user program. The “xxxxxxxx” is the virtual 

storage address of the parameter list that passed to the program in Register 1. This trace 

message is followed by a formatted dump of the parameter list. 

MCG rpc data (program parms are embedded) located at xxxxxxxx (before) 

This trace message is issued before and after the call to the user program. The RPC data area 

contains the RPC parameter data that is passed back and forth between the client calling 

program and the mainframe called program. The RPC data area also contains control 

information used by MFA Server to manage the MCG operations. This message identifies the 

virtual storage address of the RPC data area and it is followed by a formatted dump of the RPC 

data. The addresses of parameters in the program parameter list can be resolved to data items 

that are imbedded in the RPC data area. The before trace of the RPC data shows what was 

received from the client and the after trace shows any changes to the data areas that have been 

made by the called program. 


Randy Witek 



MCG BLDL information for load module 

This trace message is issued following a successful BLDL and LOAD of the user program 

module. Each user program is loaded only once during a MCG operation. This message is 

followed by a formatted dump of the BLDL data area. 

MCG module xxxxxxxx starts at xxxxxxxx entry at xxxxxxxx 

This trace message is issued following a LOAD of the user program module. The starts at value 

gives the virtual storage address where the user load module begins. The entry at value gives 

the virtual storage address of the entry point that will be called. This address is also set to 

indicate the addressing mode in which the user program will receive control, either 24-bit mode 

(00xxxxxx actual entry address) or 31-bit mode (0x80000000 + actual entry address xxxxxxxx). 

MCG request received - FCD_ACT1/2 xxxx description 

This trace message is issued for each MCG request received from the client. The hexadecimal 

FCD action code bytes identify the type of MCG request message. The description field provides 

a descriptive name for the request type. 

Module MCGEXEC messages 

This module is the driver for MCG program execution, the actual call to the user program, in the 

MCGEXEC subtask. 


MFM0130E MCG cccccccc ABENDed, System=Sxxxx Reason=xxxxxxxx User=Udddd 

This message is issued after the MCG ESTAE extension has trapped and recovered from an 

ABEND condition. The message provides the system (hexadecimal) or user (decimal) ABEND 

code. System reason codes are also logged for system ABENDs. If a SYSUDUMP (or 

SYSMDUMP) DD statement is available to the server, a dump is recorded for the ABEND. 

MFM0130E MCG unable to call cccccccc, iSvcRC=dddd iSvcRS=dddd 

This message is issued when server preparation for the MCG call operation encounters an 

internal logic error. The MD_MCGEXEC_RUN service was called to execute the user program 

but this service ended with an error indicated by the return code and reason code values. 

Preceding error messages identify the exact cause. 

MFM0130E MCG cleanup failed, iSvcRC=dddd iSvcRS=dddd 

This message is issued if the MD_MCGEXEC_CLEANUP service encounters an internal logic 

error. Preceding error messages identify the exact cause. 

Module SR@KILLT messages 

This module provides a generalized CALLRTM interface for MFA Server. This service is called to 

end “lost” MCGEXEC subtasks (for example, a looping user program). 


MFM0131E Task cccccccc xxxxxxxx TCB xxxxxxxx terminated Udddd; callrtm rc=ddd 

This message is issued when a subtask is forcibly terminated by MFA Server. The Udddd user 

ABEND code will be U201 for forced terminations of a MCGEXEC subtask. This may occur when 

the end user logs off or terminates the MFE client while a MCG session is active. 


Randy Witek 



Appendix A: IGZERRE entry conditions and return codes 

In non-CICS environments, IBM’s IGZERRE entry point can be invoked to explicitly drive 

COBOL's initialization and termination functions to create or destroy a reusable run-time 

environment. Upon entry to IGZERRE, the following register contents must exist: 

Register Contents 

1 

If initializing: function code of 1 

If terminating: function code of 2 

If parm list form: address of pointer to a word containing 

function code as above 

13 

Pointer to standard register save area 

14 

Return address 

15 

IGZERRE’s entry address 

Upon return, register 15 will contain one of the following return codes: 

Return code Explanation 

0 

Function completed correctly 

4 

COBOL already initialized (applies to initialization function only) 

8 

Invalid function code in Register 1 or parameter list (not 1 or 2) 

12 

ILBOSTP0 not part of load module (applies to initialization of 

NORES only) 

16 

COBOL was not previously initialized (applies to termination 

function only) 

20 

COBTEST is being used (applies to termination of RES only) 

The originally requested function is performed only when the return code is 0. 


Randy Witek 



Appendix B: MCG setup checklist 

This appendix provides a concise checklist of the preparations and activities required, in MFE and 

in MFA Server, to enable a Mainframe Call Generator subprogram call. References are given to 

the more complete documentation that is available. 

Setup activity Description and References 

Enable MCG Create a Windows user environment variable named 

MCGADMIN and set its value to any non-blank value 

Mainframe Express Administrator’s Guide 

Chapter 7: Calling Program’s on the Mainframe 

Define a NODE 

and a drive for 

SourceConnect 

Build the calling 

program 

Generate the MCG 

stub 

Make the target 

mainframe load 

module available 

to MFA Server 

Run the calling 

program 


Randy Witek 


Use MFE Options Server Access Configuration to define 

the MFA Server node and a SourceConnect drive that 

maps to that server node. 

Mainframe Access Installation and Usage Guide 

Chapter 9: SourceConnect for Mainframe Express and Revolve 

Use MFE to build a COBOL program that contains a call to 

the target mainframe load module. 

Mainframe Express User’s Guide 

Use the MFE MCG feature to create a stub that 

communicates with MFA Server to execute the target 

mainframe load module when you run the calling program. 

Right click on the program.INT file in the Load Libraries 

folder found in the project’s Workgroup tab, select 

Mainframe Call Generator… from the menu and use the 

MCG dialog to create the stub. 


Chapter 7: Calling Program’s on the Mainframe 

Add the target mainframe load module to a program library 

defined to MFA Server using the MCGLIB DD statement. 

Mainframe Access Administrator’s Guide 

Appendix D: Mainframe Call Generator 

Use MFE to run the calling program in the usual way. 

When a call to the target mainframe load module is 

encountered, MFE will execute the generated MCG stub. 

You are prompted for your mainframe userid and password 

if this is the first access to the mainframe. You are 

prompted for DB2 connection information if this program 

uses DB2. 


Chapter 7: Calling Program’s on the Mainframe


Appendix C: Sample MFA Server trace of MCG processing 

The service level indication (fp1a) in the startup message confirms that this MFA Server is running with the FixPack containing the Mainframe Call 

Generator Refresh. 

11/03/04 10:00:54.2 XDRMAIN 01 MFM0001I Mainframe Access V3.01 (fp1a) is active 

11/03/04 10:00:54.2 XDRMAIN 01 

This trace activity is in the common TCP/IP listener that receives the initial client connection message from all MFA Server clients. When a 

Mainframe Access client is identified, the stream socket connection is passed to one of the XDBMFADM communications tasks dedicated to MFA 

client processing. 

11/03/04 10:01:17.6 XDBTCPM0 0A Client connection on socket sd=7 

11/03/04 10:01:17.6 XDBTCPM0 0A Connection at 11/03/04 10:01:18 on sd=7 from ip=10.10.1.7 

11/03/04 10:01:17.6 XDBTCPM0 0A MFM0071E XDBTCPM access list check warning for client 10.10.1.7 

11/03/04 10:01:17.6 XDBTCPM0 0A Security OK at 11/03/04 10:01:18 on sd=7 from ip=10.10.1.7 

11/03/04 10:01:17.6 XDBTCPM0 0A Receive for sd=7, size=4 (0x0004) at 11/03/04 10:01:18 

11/03/04 10:01:17.6 XDBTCPM0 0A recv 0000 0000006C 

11/03/04 10:01:17.6 XDBTCPM0 0A Receive for sd=7, size=16 (0x0010) at 11/03/04 10:01:18 

11/03/04 10:01:17.6 XDBTCPM0 0A recv 0000 006C7F01 0000FF00 00004C53 43204E4F


11/03/04 10:01:17.7 XDBMFADM 19 MFA server initialization complete for sd=9 (13EDC970), tsa=13F36000, rc=0 

11/03/04 10:01:17.7 XDBMFADM 19 Client request from sd=9 (13EDC970) starting 

11/03/04 10:01:17.7 XDBMFADM 19 Receive for sd=9 (13EDC970), size=108 (0x006C) at 11/03/04 10:01:18 

11/03/04 10:01:17.7 XDBMFADM 19 recv 0000 006C7F01 0000FF00 00004C53 43204E4F 

11/03/04 10:01:17.7 XDBMFADM 19 MFA server msg processing starting for sd=9 (13EDC970) 

11/03/04 10:01:17.7 XDBMFADM 19 MFA server msg processing complete for sd=9 (13EDC970) rc=0 

11/03/04 10:01:17.7 XDBMFADM 19 Send for sd=9 (13EDC970), size=4 (0x0004) at 11/03/04 10:01:18 

11/03/04 10:01:17.7 XDBMFADM 19 send 0000 0000006C 

11/03/04 10:01:17.7 XDBMFADM 19 Send for sd=9 (13EDC970), size=108 (0x006C) at 11/03/04 10:01:18 

11/03/04 10:01:17.7 XDBMFADM 19 send 0000 006C7F01 0100FF00 30304C53 43204E4F


The userid begins at offset 0x73, “CSIRLW1” in this example. Password data at offset 0x87 is encrypted in the message flows and is replaced 

with a string of 0x7C in tracing messages. The MFM0111I message indicates successful SAF processing of the userid/password and a 0x3030 

success response is returned to the client. 

11/03/04 10:01:18.0 XDBMFADM 19 Receive for sd=9 (13EDC970), size=4 (0x0004) at 11/03/04 10:01:18 

11/03/04 10:01:18.0 XDBMFADM 19 recv 0000 000002BF 

11/03/04 10:01:18.0 XDBMFADM 19 Header received for sd=9 (13EDC970) 


11/03/04 10:01:18.1 XDBMFADM 19 Receive for sd=9 (13EDC970), size=167 (0x00A7) at 11/03/04 10:01:18 

11/03/04 10:01:18.1 XDBMFADM 19 recv 0000 02BF0000 0000FF14 30304C53 43204E4F 

11/03/04 10:01:18.1 XDBMFADM 19 recv 00C0 6C507D4D 5D5C4E6B 604B61F0 F1F2F3F4


11/03/04 10:01:18.1 XDBMFADM 19 recv 0250 75767778 797AA1BF D0DDDEAE 5EA3A5B7 

11/03/04 10:01:18.1 XDBMFADM 19 recv 0260 A9A7B6BC BDBE5B5D AFA8B4D7 7B414243 

11/03/04 10:01:18.1 XDBMFADM 19 recv 0270 44454647 4849ADF4 F6F2F3F5 7D4A4B4C 

11/03/04 10:01:18.1 XDBMFADM 19 Client request complete for sd=9 (13EDC970) 

3 


The third exchange signals the beginning of a MCG RPC operation. The server will expect an ordered sequence of RPC exchanges to follow. At 

this point, the server directs subsequent message arrivals to the MFARPC00 module for MCG processing. 






11/03/04 10:01:18.4 XDBMFADM 19 recv 0000 02BF0000 0000FF14 30304C53 43204E4F


11/03/04 10:01:18.4 XDBMFADM 19 recv 0050 00000000 00000100 00000000 00000000 

11/03/04 10:01:18.4 XDBMFADM 19 recv 0060 00109331 60002700 0000D3E2 00000300


11/03/04 10:01:18.4 XDBMFADM 19 send 0060 00109331 60002700 0000D3E2 

11/03/04 10:01:18.6 XDBMFADM 19 recv 0070 4D565340 52504300 2CB300B4 20B900B8 

11/03/04 10:01:18.6 XDBMFADM 19 recv 0080 00B400D4 C3C7C9C2 D4C340B3 0002B240 

11/03/04 10:01:18.6 XDBMFADM 19 recv 0090 B3000AC6 99969440 D4C6C5B4 40B3000A 

11/03/04 10:01:18.6 XDBMFADM 19 recv 00A0 E396C285 C6899393 8584 


11/03/04 10:01:18.6 XDBMFADM 19 MCG request received - FCD_ACT1/2 FAF3 send parm 





Randy Witek 


Confidential - 24 - December 2004


11/03/04 10:01:18.6 XDBMFADM 19 send 0000 006C0000 0100FAF3 30304C53 43204E4F


In the MCG operation diagram, the MD@MCGEX module is interesting to note because it contains most of the supporting program logic for the 

execution phase, and portions of this module execute as part of the XDBMFADM task and other portions execute as part of the MCGEXEC 

subtask. 


11/03/04 10:01:19.0 XDBMFADM 19 recv 0000 0000006C 




11/03/04 10:01:19.0 XDBMFADM 19 recv 0000 006C0000 0000FA0E 30304C53 43204E4F


and the entry point address are also shown in a trace message. The hi-bit of the entry address indicates the addressing mode for the program. In 

this example the module starts at 0x13E94200 and the entry address is the same at 0x939E94200. The hi-bit on in the entry address indicates 

the program will be entered in 31-bit addressing mode. 

11/03/04 10:01:19.0 XDBMFADM 19 MCG BLDL information for load module MCGIBMC 

11/03/04 10:01:19.0 XDBMFADM 19 bldl info 0000 0001004C D4C3C7C9 C2D4C340 00292400


At this point, the MCGEXEC subtask is idle, but still dedicated to this MCG session. The XDBMFADM communications task processes completion 

for the execute request. The display of the RPC data at this time will show any alterations made by the called program. In this example, the 

“ToBeFilled” parameter area was changed to “From IBMc “. The 0x3030 value in the response message sent to the client indicates that the 

remote call was successful. 

11/03/04 10:01:19.2 XDBMFADM 19 MCG execution complete for sd=9 (13EDC970) 

11/03/04 10:01:19.2 XDBMFADM 19 MFA server MCG completion starting for sd=9 (13EDC970) 

11/03/04 10:01:19.2 XDBMFADM 19 MCG rpc data (program parms are embedded) located at 00307AC8 (after) 

11/03/04 10:01:19.2 XDBMFADM 19 rpc data 0000 02000A00 4D565340 52504300 2C000000


- LSC RPC request 

- RPC send parameters 

- RPC execute 

- RPC fetch parameters 


11/03/04 10:01:19.5 XDBMFADM 19 recv 0000 0000006C 




11/03/04 10:01:19.5 XDBMFADM 19 recv 0000 006C0000 0000FAF5 30304C53 43204E4F 

11/03/04 10:01:19.5 XDBMFADM 19 send 0070 4D565340 52504300 2CB400B9 003078A0 

11/03/04 10:01:19.5 XDBMFADM 19 send 0080 B70001B4 00D4C3C7 C9C2D4C3 40B30002 

11/03/04 10:01:19.5 XDBMFADM 19 send 0090 B240B300 0AC69996 9440D4C6 C5B440B3 < @³..ñ @…ñ˜Ø@³> 

11/03/04 10:01:19.5 XDBMFADM 19 send 00A0 000AC699 969440C9 C2D48300 

11/03/04 10:01:19.5 XDBMFADM 19 Client request complete for sd=9 (13EDC970) 

7 

Randy Witek 





In this simple example, there is only one call to a remote program. The final client-server exchanges appear to be the start of a second execution. 

The seventh exchange again signals the start of a MCG call operation. 






11/03/04 10:01:24.8 XDBMFADM 19 recv 0000 02BF0000 0000FF14 30304C53 43204E4F


11/03/04 10:01:24.8 XDBMFADM 19 recv 0260 20202020 20202020 20202020 20202020 < > 

11/03/04 10:01:24.8 XDBMFADM 19 recv 0270 20202020 20202020 20202020 20202020 < > 

11/03/04 10:01:24.8 XDBMFADM 19 recv 0280 20202020 20202020 20202020 20202020 < > 

11/03/04 10:01:24.8 XDBMFADM 19 recv 0290 20202020 20202020 20202020 20202020 < > 

11/03/04 10:01:24.8 XDBMFADM 19 recv 02A0 20202020 20202020 20202020 00000000 < ....> 

11/03/04 10:01:24.8 XDBMFADM 19 recv 02B0 03000000 00000000 00000030 000000 


11/03/04 10:01:24.8 XDBMFADM 19 MCG request received - FCD_ACT1/2 FF14 rpc start 





11/03/04 10:01:24.8 XDBMFADM 19 send 0000 006C0000 0100FF14 30304C53 43204E4F 

11/03/04 10:01:25.0 XDBMFADM 19 recv 0070 4D565340 525043B8 00B50001 B8003078 

11/03/04 10:01:25.0 XDBMFADM 19 recv 0080 A0B70001 B400 < ·..Ø. > 

Randy Witek 





11/03/04 10:01:25.0 XDBMFADM 19 MCG request received - FCD_ACT1/2 FAF3 send parm 





11/03/04 10:01:25.1 XDBMFADM 19 send 0000 006C0000 0100FAF3 30304C53 43204E4F 


The cleanup flag is detected and this execute request is correctly identified as a “cleanup”. 

Randy Witek 




11/03/04 10:01:25.3 XDBMFADM 19 MCG request received - FCD_ACT1/2 FA0E cleanup 

Here the MCGEXEC subtask releases the COBOL environment (by calling IBM’s IGZERRE utility) that was previously created for the MCG 

session. When cleanup is successful, the subtask is available for reassignment to a new MCG session. 

11/03/04 10:01:25.3 MCGEXEC 20 Work popped (nwo=13BA9BA0 nwowhat=13) 

11/03/04 10:01:25.3 MCGEXEC 20 nwo 0000 D5E6D640 00000130 00000001 00000000 

11/03/04 10:01:25.3 MCGEXEC 20 nwo 0010 00000000 0000000D 13F36000 00000000 

11/03/04 10:01:25.3 MCGEXEC 20 nwo 0020 00000000 13E3337C 13EB38A0 00000000 

11/03/04 10:01:25.3 MCGEXEC 20 Work is Mcgexec_Cleanup (Tsa=13F36000) 

11/03/04 10:01:25.4 MCGEXEC 20 MCG COBOL environment reset; IGZERRE rc=00000000 

11/03/04 10:01:25.4 MCGEXEC 20 MCG cleanup successful 





11/03/04 10:01:25.4 XDBMFADM 19 send 0000 006C0000 0100FA0E 30304C53 43204E4F

Mainframe Call Generator (MCG) Refresh - Micro Focus

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?