Figure 9-1: The DFHCNV Maintenance Dialog Box
This chapter provides information about how you can use CICS Option in a client/server environment.
You can use Mainframe Express CICS Option in a client/server environment where the server component is a CICS system that normally runs on the mainframe. Applications that run in client/server environments are sometimes known as distributed applications. A typical development scenario in which you might want to use CICS Option is where you have written a graphical front-end that runs on PCs for a mainframe-based system that uses CICS to process large numbers of transactions, and you now want to ensure that the application works as planned, before running the server component on the mainframe. CICS Option can play a part in the following types of client/server environments:
Messages and data are passed between the server and client components using middleware. CICS Option supports several middleware products:
It also emulates two middleware products:
You can run both the client and server components on the same PC, or you can use two PCs. If you use two PCs, you need communications software running on both PCs.
The support offered by CICS Option for running client/server applications is specifically oriented towards the use of CICS Option alongside other Micro Focus products, to provide a complete environment for proving your applications before running them using the mainframe as the server. These products are:
The table below shows which middleware you can use between CICS Option and the EnterpriseLink products, and between CICS Option and Net Express:
| Middleware | EnterpriseLink | Net Express |
|---|---|---|
| MQSeries Version 5.x | Yes | Yes |
| MQSeries Version 2.0 | No | Yes |
| IBM Universal Clients | No | Yes |
| Micro Focus emulation of External Call Interface Version 0.9 | No | Yes |
| Micro Focus emulation of External Presentation Interface | No | Yes |
This section contains details about two typical uses of CICS Option in a client/server environment:
You can use CICS Option to test applications that you have Web-enabled using Component Generator. There are three components in a Web-enabled application:
When you use CICS Option to test Web-enabled applications, you can:
For full details of how to test applications that you have Web-enabled using Component Generator, see the chapter Testing eBiz Transactions in the EnterpriseLink Component Generator User's Guide.
You can use CICS Option and Net Express together to maintain and debug applications that have a Windows client component and a mainframe component. Instructions on how to debug such applications using both Mainframe Express and Net Express are available in the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click Development Environment, Debugging COBOL Programs, and Debugging Distributed Applications.
You must have Net Express installed on any PC on which you want to run the distributed client component. You must have Mainframe Express with CICS Option installed on any PC on which you want to run the mainframe component.
You can run Net Express and Mainframe Express on the same PC. Note that the minimum hardware requirements are the sum of the minimum requirements for both Net Express and Mainframe Express. Consequently, you will need a fast machine with sufficient memory.
Alternatively, you can have Net Express installed on one or more PCs, communicating with Mainframe Express on another PC. However, you can only run one debugging session for each instance of the Integrated Development Environment.
Demonstration programs provided with Mainframe Express illustrate how to use CICS Option with Net Express in detail; see the section Demonstration Programs for IBM Universal Clients.
Note: To use CICS Option and Net Express together in this way, you need to install a Net Express AddPack. This AddPack is provided in the \fixpacks folder of your Mainframe Express installation CD. For Net Express 3.1, the name of the file that installs the AddPack is eci00n31.exe. For Net Express 3.0, the name of the file is eci3setup.exe.
This section describes how to configure CICS Option to work with the middleware supported.
CICS Option provides APIs that are compatible with MQSeries Version 2.0 (server) and MQSeries Version 5.x (client and server).
To use MQSeries for communication between client and mainframe components of your distributed application, you must have MQSeries for Windows installed on your PC or PCs. However, on the PC running Mainframe Express you can issue calls to the MQSeries application programming interface (API) as if you were using MQSeries for MVS/ESA. This is because Mainframe Express intercepts your calls and adjusts them for the PC environment. If you use any calls that are only available in MQSeries for Windows, Mainframe Express ignores them.
The support provided for MQSeries Version 5.x enables you to use MQSeries event triggering. With event triggering, the queue manager detects certain conditions and sends a trigger message for each condition to a separate initiation queue. A special transaction, CKTI, monitors the queue and starts a user-defined transaction to process the trigger event. You can have the CKTI transaction start up at region initialisation, or start it up dynamically.
For full details of the MQSeries API, consult the IBM manual MQSeries Command Reference (SC33-1369).
You can enable MQSeries support either for:
To enable MQSeries support for a project you must check Enable Connector on the Overrides page of the CICS System Properties dialog box, then enter the Queue Manager Name. (In the CICS View, right-click CICS System in the left-hand pane, then click Properties.)
If you enable MQSeries support for a project, and you then decide that you want any project that uses the SIT to be able to use MQSeries, you can apply the project overrides to the resource definition file: in the CICS View, right-click CICS System in the left-hand pane, place the cursor over Apply Overrides to RDF, and select one of the options shown; you can apply overrides to the SIT only, the startup list only, or both.
To enable MQSeries support for a SIT you must check Enable Connector on the Communications page of the SIT properties dialog box, then enter the Queue Manager Name. (In the CICS View, click System Initialisation Table (SIT) in the left-hand pane, then double-click the SIT you want to update in the right-hand pane.)
If you enable MQSeries support for a SIT after you have created a project that uses the SIT, and you want your project to use MQSeries, you can refresh the project settings from the resource definition file: in the CICS View, right-click CICS System in the left-hand pane, then click Refresh from RDF.
You enter the same queue manager name that you specify in MQSeries. See the IBM manual MQSeries System Administration (SC33-1873) for further information about queue manager names.
CICS Option supports event triggering in MQSeries Version 5.x. You can configure it to start at region initialisation or you can start it up dynamically:
You need to define your processes, triggering and initiation queues to MQSeries. The method you use depends on which version of MQSeries you are using:
For further details consult the IBM manual MQSeries System Administration (SC33-1873).
Before you can run an application that uses MQSeries, you need to insert your calls to the API in your programs.
In a program running under Mainframe Express you do not need to connect explicitly to a message queue before you open it. When you open a message queue, Mainframe Express implicitly connects to the queue for you. This behavior is consistent with IBM MQSeries for MVS/ESA.
Syncpoints are handled as follows:
For information about data conversion issues, see the section Data Conversion.
Two sample programs, mfzqput and mfzqget, are provided in the folder \mfe\mfcics\source. Program mfzqput adds a single message to a specified queue and program mfzqget retrieves all the messages on a specified queue. The mfzqget program incorporates a delay before it completes to ensure that all messages on the queue have been retrieved. These programs work with both MQSeries Version 2.0 and MQSeries Version 5.x.
Before you can run the sample programs you need to:
The programs are supplied already compiled, but if you want to compile them, you need to add a dependency folder for the MQSeries copybooks: compile the programs using the CICS preprocessor and the MQSeries copybooks from mq-base-dir\tools\cobol\copybook, where mq-base-dir is the base MQSeries folder (which defaults to mqm).
The parameters for program mfzqput are:
QPUT {queue-name} {message}
The parameters for program mfzqget are:
QGET {queue-name}
You can use IBM Universal Clients as the middleware between your client application and CICS Option running under Mainframe Express. You need to have IBM's Universal Clients Version 3.0 (or above) installed on the client machine. CICS Option supports the External Call Interface (ECI) only. You must run CICS Option in multi-tasking mode.
To enable IBM Universal Clients support you need to specify that a CICS Universal Clients gateway should be initiated at region initialisation for a particular SIT as defined in the resource definition file, which may be shared between projects. To do this, check Enable Gateway in the Universal Clients group on the Communications page of the SIT properties dialog box, then enter the Port Number and number of Sessions you want to service inbound requests per client machine. (In the CICS View, click System Initialisation Table (SIT) in the left-hand pane, then double-click the SIT you want to update in the right-hand pane.)
The port number is the TCP/IP port number used for communications between the client and server machines. This must match the TCP/IP port number you specify in the Universal Clients configuration file except that if you use the defaults, the value in the configuration file is 0 whereas the value here is 1435.
You need to set the following options in the Universal Clients configuration file (cicscli.ini) on the client machine:
| Server | <name for the server> |
| Description | <description for the server> |
| Protocol | TCPIP |
| NetName | <TCP/IP address of server> |
| Port | 0 (meaning use the default) |
The only field that is mandatory is NetName.
You need to insert your calls to the ECI in your program. In COBOL, a call to the ECI via Universal Clients looks like this:
CALL "CICS_ExternalCall" USING ECI-PARMS
ECI-PARMS is the ECI parameter block, through which the program communicates with CICS Option. The parameter control block is available as a copybook in the copybook folder within your Universal Clients installation. It is called dfhcbeci.cpy.
When you compile your program, you must link it to the Universal Clients library, cclwin32.lib.
For further information about using Universal Clients, you should consult the IBM manual CICS Family: Client/Server Programming (SC33-1435).
The source of two COBOL programs that demonstrate the use of IBM Universal Clients is provided in \mfe\mfcics\source. The programs are:
| eci2oper.cbl | A server program that you run under Mainframe Express. It consists of a CICS transaction that writes a data area to the system console. This transaction program performs a WRITE OPERATOR command on the field ECI-DEMO-MESSAGE using the text passed in the DFHCOMMAREA. If the WRITE OPERATOR command fails, the EIBRESP and EIBRESP2 values are passed back to the calling program in the fields ECI-ERROR-EIBRESP and ECI-ERROR-EIBRESP2. | ||
| eci-call.cbl | A client program that you run under Net Express. This batch program has three main parts: | ||
| set-up-eci-call | Sets up an entry point to the module dfhtexst that handles the calling of the ECI. | ||
| call-eci-program | Calls dfhtexst and passes it the data area and program name to run. It contains the following fields: | ||
| eci-program | The name of the program to be run by CICS Option. | ||
| eci-commarea-pptr | A pointer to the data area to be passed to and from CICS Option. | ||
| eci-error-id | If the program completes successfully this contains a value of 0. If unsuccessful it contains the value of an an error condition described in the section ECI Return Codes. | ||
| eci-error-display | Checks for any error conditions returned by the program running under CICS Option or by dfhtexst. Any errors occurring during execution of the program running under CICS Option must be handled before returning to the calling ECI program. In this case the program under CICS Option returns EIBRESP and EIBRESP2. | ||
Before you run the demonstration, you have to prepare your Net Express client. You need to :
01 ECI-Client-Type.
03 pic x comp-x
*> --
*> --Change the following value to select client type
*> --
value 0.
88 ECI-MERANT-88 value 0.
88 ECI-UniCli-88 value 1.
Add code to set ECI-Client-Type to 1.
Before you run the demonstration, you have to prepare your Mainframe Express CICS server. To do this:
You do not need to compile the server program; a compiled version of eci2oper.cbl is supplied with Mainframe Express. The client program passes the Program-ID of the server program to CICS Option, which locates the program and starts it.
To run the program eci-call do the following:
Enter the message you want to send to the console ==>
appears in the Application Output window. Enter your message.
Mainframe Express includes ECI software that supports a subset of IBM's ECI level 0.9 consisting of the synchronous calls only. For information about the IBM ECI software see the IBM manual CICS Family: Client/Server Programming (SC33-1435). This section assumes that you are using Micro Focus Net Express as the vehicle for developing the client program.
Data is passed through the COMMAREA, as with a transaction program.
The mainframe program that runs under Mainframe Express assumes that all data is in EBCDIC, while the client program that runs under Net Express assumes that data is in ANSI. Mainframe Express supports data conversion by providing a facility for importing conversion macros (.mlc files) from the mainframe environment. These macro files are used to create a conversion table called DFHCNV, which is used to handle the data conversion. See the section Data Conversion for details of DFHCNV.
CICS option uses Micro Focus CCI to handle communications with ECI Clients. On the server machine, the one running CICS Option, you need to specify that a communications gateway should be initiated at region initialisation for a particular SIT as defined in the resource definition file, which may be shared between projects. To do this, check the protocol you want to use in the Client gateways group on the Communications page of the SIT properties dialog box; you can choose between TCP/IP, NetBIOS and Novell IPX. If you use TCP/IP, you also need to supply the Port number. If you want to use a CCITCP2 process to locate the server gateway process, you should enter its name in CCITCP2. (In the CICS View, click System Initialisation Table (SIT) in the left-hand pane, then double-click the SIT you want to update in the right-hand pane.)
For more information see your Configuring CCI.
Before you use ECI, you need to define the ECI environment in Net Express. You need to:
| Variable | Value |
|---|---|
| CICSLOC | LOCAL if Mainframe Express and
Net Express are running on the same PC. REMOTE (protocol-name) if Mainframe Express is running on a remote PC. protocol-name indicates which protocol is to be used; the default is CCITCP (for TCP/IP) |
| TXREGN | Name of the region running under Mainframe Express |
If you use the CCITCP protocol and you don't want to use the CCITCP2 process to locate the server gateway process, you also need to set the following environment variable:
| TXSOCKET | <machine-id>:<port-number>, where <machine-id> is either the IP address or the network name of the PC running Mainframe Express ( up to 16 characters) and <port-number> is the port number specified in the SIT on Mainframe Express . |
You need to insert your calls to the ECI in your program. In COBOL, a call to the ECI looks like this:
CALL "CICS_ExternalCall" USING ECI-PARMS
ECI-PARMS is the ECI parameter block, through which the program communicates with CICS Option.
When you compile your program, you must link it to the Micro Focus ECI library, dfhtexst.lib, which is in the folder \netexpress\base\bin.
The ECI parameter control block is an area of a COBOL program's Working-Storage Section that is used to communicate with CICS Option.
The parameter control block is available as a copybook in \netexpress\base\source and \mfe\mfcics\source\dfhcbeci.cpy.
You should move x"00" into the entire contents of the parameter control block before the start of each logical unit of work.
The ECI parameter control block copybook (dfhcbeci.cpy) reflects the IBM CICS ECI, and not all the fields are supported. For information about the IBM CICS ECI you should consult the IBM manual CICS Family: Client/Server Programming (SC33-1435). The supported fields are:
| ECI-CALL-TYPE | An integer value that determines whether
the call is processed synchronously or asynchronously. The only supported value
is given by the COBOL 88-level data description entry:
|
||||||
| ECI-PROGRAM-NAME | An 8-character string containing the name of the CICS transaction program to be executed. | ||||||
| ECI-USERID | An 8-character string containing a valid user ID. If necessary, pad the string with spaces on the right. | ||||||
| ECI-PASSWORD | An 8-character string containing a valid user password. If necessary, pad the string with spaces on the right. | ||||||
| ECI-TRANSID | A 4-character transaction ID. Use this field when the transaction program you are calling uses distributed program linking, and the transaction ID under which the program runs is important. If necessary, pad the string with spaces on the right. | ||||||
| ECI-ABEND-CODE | A 4-character field in which an abend code is returned if the transaction abends. This field is initialized to spaces before the request is passed to CICS Option. | ||||||
| ECI-COMMAREA | A pointer to an area of memory not larger than 32767 bytes, which the CICS program receives as its COMMAREA. If no COMMAREA is required, use a null pointer and set ECI-COMMAREA-LENGTH to zero. | ||||||
| ECI-COMMAREA-LENGTH | The length of ECI-COMMAREA, in bytes. | ||||||
| ECI-SYS-RETURN-CODE | The error number of any system error that may occur is returned in this field. | ||||||
| ECI-EXTEND-MODE | An integer value that determines whether or not the
connection to CICS Option is terminated at the end of the call. The valid
values are given by the COBOL 88-level data description entries:
|
A call to a transaction program using ECI can return any of the following values in RETURN-CODE. These values are supplied in dfhcbeci.cpy and can be used by moving the return code to ECI-ERROR-ID.
| ECI-NO-ERROR | The transaction finished with no errors. |
| ECI-ERR-INVALID-DATA-LENGTH | This can be caused by either of the following errors:
A positive user data length for a null user data area A zero user data length for a non-null user data area |
| ECI-ERR-INVALID-EXTEND-MODE | The extend mode is not 0, 1, or 2. |
| ECI-ERR-NO-CICS | CICS Option is not running. |
| ECI-ERR-CICS-DIED | CICS Option is no longer running. |
| ECI-ERR-TRANSACTION-ABEND | CICS Option accepted the request, but the transaction abended. |
| ECI-ERR-EXEC-NOT-RESIDENT | The program tried to cancel a previous request when there was none outstanding. |
| ECI-ERR-LUW-TOKEN | The LUW is not within the valid range or it is the wrong LUW token. |
| ECI-ERR-SYSTEM-ERROR | An internal error occurred. |
| ECI-ERR-RESOURCE-SHORTAGE | CICS Option has no space in the interval control table. |
The demonstration programs for ECI are the same as the demonstration programs for IBM Universal Clients, and you use them in the same way. The only difference is that ECI-Client-Type in the Working-Storage Section of program eci-call.cbl must be set to 0. For further details see the section Demonstration Programs for IBM Universal Clients
The External Presentation Interface (EPI) lets a non-CICS application program appear to the CICS system as one or more standard 3270 terminals. The non-CICS application can start CICS transactions, and send and receive standard 3270 data streams associated with those transactions.
The presentation of the 3270 data received by an EPI application is the responsibility of the application. The application can present the data in the normal way by emulating a 3270 terminal, or it can present a different view, for example, a graphical user interface.
The supported EPI calls are:
CICS-EpiInitialize
CICS-EpiListSystems
CICS-EpiAddTerminal
CICS-EpiStartTran
CICS-EpiGetEvent
CICS-EpiReply
CICS-EpiDelTerminal
CICS-EpiTerminate
CICS-EpiATIState
CICS-EpiGetSysError
For a description of these calls, see the IBM manual CICS Family: Client/Server Programming (SC33-1435).
If your COBOL program runs under Mainframe Express, it must first issue the following CALL statement to open the necessary linkage to the External Presentation Interface:
CALL "dfhtexst"
If your program runs under Net Express, when you compile your program, you must link it to the Micro Focus ECI library, dfhtexst.lib.
Within a single system using CICS Option, file data is always presented in the same codeset in which it was recorded. Between CICS Options, or between CICS Option and other CICS systems, data may need to be translated between EBCDIC and ANSI. The requirement and the method you use to meet it depend on which middleware you are using.
If you use IBM MQSeries, CICS Option itself takes care of translating all the system fields in each message. However, it is the responsibility of your application program to perform data conversion on the user data in each message. You do this by specifying the MQGMO_CONVERT option in the MQGMO structure passed to a MQGET call. More details are provided in the IBM manual MQSeries Application Programming Guide (SC33-0807) .
Note: If you run your client and server applications on the same machine using the same queue manager, user data is not correctly converted .
If you use IBM Universal Clients® or Micro Focus support for ECI, you can supply information that enables data to be converted in data conversion templates, which are held in an indexed file called dfhdrcnv, in the same folder as the project's resource definition file (by default mfe\config). Each data conversion template contains entries for resources that need translation and identifies which data fields require it. Each resource must have an entry in the resource definition file.
You cannot edit the file dfhdrcnv directly; instead you maintain it by importing mainframe-style DFHCNV macros, and by deleting templates that you no longer need.
Mainframe-style DFHCNV macros are organised into entries and templates. An entry is a set of conversion macros that apply to the same resource; the start of an entry is marked by a DFHCNV macro that begins TYPE=ENTRY and the entry continues until the next macro that begins TYPE=ENTRY, or until the END marker. An entry can contain one or several templates, depending on the type of resource it belongs to. For more information about mainframe-style DFHCNV macros, see the following IBM manuals:
CICS Family: Communicating from CICS on System/390
CICS Web Interface Guide CICS for MVS/ESA 4.1
Mainframe Express converts the data using its built-in conversion tables. You can customize these to handle non-standard requirements; for further information see the chapter National Language Support in your User's Guide.
You maintain data conversion templates using the DFHCNV maintenance dialog box shown in Figure 9-1.
Figure 9-1: The DFHCNV Maintenance Dialog Box
You can import templates that have been downloaded from the mainframe, and you can delete templates. When you click on Import, you see the Import DFHCNV macro source dialog box shown in Figure 9-2.
Figure 9-2: The Import DFHCNV Macro Source Dialog Box
Full details of how to use the template maintenance facilities are available in the online help: click Help Topics on the Mainframe Express Help menu, then on the Contents tab click CICS Option and Working with CICS Projects.
Note: If data conversion is required for a program's COMMAREA, you must define a PPT entry for that program; see the section Adding a PPT Entry in the chapter Developing CICS Applications in your User's Guide.
The following data conversion macros apply to a file (TESTFC), which has two data constructs, and to a program (TESTPC):
TITLE 'DFHCNV MACRO IMPORT' * --------- START OF DFHCNV MACROS ---------- * DFHCNV TYPE=INITIAL,CLINTCP=(932, 437,XXXX) SPACE 2 DFHCNV TYPE=ENTRY,RTYPE=FC,RNAME=TESTFC,USREXIT=NO DFHCNV TYPE=KEY DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3,LAST=YES DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='A' DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3 DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1 DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=PD,DATALEN=4 DFHCNV TYPE=FIELD,OFFSET=16,DATATYP=PD,DATALEN=4 DFHCNV TYPE=FIELD,OFFSET=20,DATATYP=BINARY,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=28,DATATYP=USERDATA,DATALEN=10, X23456789 USRTYPE=B'01010000' DFHCNV TYPE=FIELD,OFFSET=38,DATATYP=CHARACTER,DATALEN=50, X LAST=YES DFHCNV TYPE=SELECT,OPTION=COMPARE,OFFSET=11,DATA='B' DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=CHARACTER,DATALEN=8 DFHCNV TYPE=FIELD,OFFSET=8,DATATYP=PD,DATALEN=3 DFHCNV TYPE=FIELD,OFFSET=11,DATATYP=CHARACTER,DATALEN=1 DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=USERDATA,DATALEN=2 DFHCNV TYPE=FIELD,OFFSET=14,DATATYP=CHARACTER,DATALEN=20, X LAST=YES DFHCNV TYPE=ENTRY,RTYPE=PC,RNAME=TESTPC DFHCNV TYPE=SELECT,OPTION=DEFAULT DFHCNV TYPE=FIELD,OFFSET=0,DATATYP=BINARY,DATALEN=12 DFHCNV TYPE=FIELD,OFFSET=12,DATATYP=CHARACTER,DATALEN=96 DFHCNV TYPE=FINAL END
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.