Chapter 7: Deploying Services and Generating Clients

This chapter describes the deployment of CICS and IMS service interfaces to Enterprise Server and the generation of clients.

Overview

When you deploy a CICS or an IMS service interface, you copy service files to the location from which the service runs. Deployment is not significantly different than deployment for any other type of service running on Enterprise Server.

Once your service interface is deployed, you can generate a client for it. Again, client generation is much the same for CICS and IMS services as it is for other services.

Deploying to Enterprise Server

To deploy a service interface to Enterprise Server, set its deployment options, then run the Deploy Tool.

For most applications, the default deployment settings are acceptable. However, you might want to check the following:

Be sure to set the appropriate legacy character set, ASCII or EBCDIC, for your application.
If your CICS application interfaces with a terminal type other than MOD2, set the Facilitylike name as follows:

Terminal Type Facilitylike Name

MOD3 MER3

MOD4 MER4

MOD5 MER5
Note: The Facilitylike name for MOD2 terminals can be blank (default) or you can set it to MER2.
The context help on the Mapping Properties dialog box, CICS or IMS tab provides a full explanation of each setting.

Terminal Type	Facilitylike Name
MOD3	MER3
MOD4	MER4
MOD5	MER5

For information on tracing service execution, see the section Tracing Service Execution later in this chapter.

Once your options are set, run the Deploy Tool to generate the appropriate files and install them to your enterprise server.

How to...

Deploying to Enterprise Server/MTO under UNIX

If your enterprise server is running on a UNIX installation of Enterprise Server/MTO, you can still deploy a service to that enterprise server. Enterprise Server/MTO can run on UNIX as a standalone application or as part of a Server Express installation. Either way, you must compile the generated driver program for your service on the platform where Enterprise Server/MTO is running. This requires that you install the Server Express COBOL Development System such that it is licensed to compile and run CICS and/or IMS applications. For more information, see the COBOL Development System Licensing Guide and the Mainframe Transaction Option Configuration and Administration Guide in your Server Express documentation.

To compile your service driver program:

Close Net Express if it is open.
To set the location of your target Enterprise Server/MTO installation, use any text editor to edit the mf-client.dat file found in your Net Express ver\base\bin folder as follows:
1. Find the following lines:
```
[directories]
; Point MFCC to local MFDS
mrpi://localhost:86
```
2. Change:
```
mrpi://localhost:86
```
  To:
```
mrpi://dnsipaddress:86
```
  Where dnsipaddress is the DNS name or the IP address of the UNIX machine where Enterprise Server/MTO is installed.
3. Save the file and close the editor.
Start your enterprise server on the target UNIX machine.
Start Net Express and open the Service Interfaces window.
To set deployment options for your service, right-click the service interface you want to deploy and click Settings from the popup menu.
On the Deployment Server tab, click Change.
On the list of available servers, click your target enterprise server, then click OK.
Click OK to close the Mapping Properties dialog box.
To deploy your service, right-click the service interface and click Deploy from the popup menu. The Deploy Tool sends the deployment package to the appropriate enterprise server on the target machine.

To transfer the service driver program source to the target machine:

In a browser, access the Enterprise Server Administration console for the target machine using the following URL:
http://machinename:86

Where machinename is the machine name of the UNIX machine running Enterprise Server/MTO.
To locate the package path associated with your deployed service, click the Details button next to Packages (located under the Objects column for the target server), then look for the package path. For example, home/hub/sx5/deploy/servintname.X_EX_A0H where servintname is the name of your service interface.
Take note of the package path so you can easily refer to it later, or copy it to the clipboard for future use.
Transfer your service driver program source to the package path folder using a file transfer utility. The path and filename of your service driver program source is:
nxprojdir\servintprojname\REPOS\servintname.deploy\SERVINTNAME.cbl

Where nxprojdir is your Net Express project directory, servintprojname is the name of your service interfaces project, and servintname is the name of your service interface.
Note: The filename prefix is in upper case and the extension (.cbl) is in lower case. This is important because UNIX is case sensitive.

To compile the service driver program on the target UNIX machine:

Log on to the target machine.
Go to the package path folder. If you are using a telnet session originating from your devleopment machine, you can paste the package path from the clipboard.

Compile the service driver source using the cob command and appropriate directives, depending on the type of service interface as follows:

Note: The service interface filename prefix (SERVINTNAME) is always upper case.

Service Interface Type	Compiled As	Command Line
CICS screen or EBCDIC commarea	GNT	cob –vu servintname.cbl –C “CICSECM() DIALECT(OS390) DEFAULTBYTE(00) WARNING(1) COPYEXT(cpy)”
CICS screen or EBCDIC commarea	Shared Object	cob –vUz servintname.cbl –C “CICSECM() DIALECT(OS390) DEFAULTBYTE(00) WARNING(1) COPYEXT(cpy)”
ASCII commarea	GNT	cob –vu servintname.cbl –C “CICSECM() DIALECT(OS390) CHARSET(ASCII) DEFAULTBYTE(00) WARNING(1) COPYEXT(cpy)”
ASCII commarea	Shared Object	cob –vUz servintname.cbl –C “CICSECM() DIALECT(OS390) CHARSET(ASCII) DEFAULTBYTE(00) WARNING(1) COPYEXT(cpy)”
IMS Screen	GNT	cob –vu servintname.cbl
IMS Screen	Shared Object	cob –vUz servintname.cbl

Generating Clients

You can use a generated client to test a service, or as a sample of accessing a service, you created using the Interface Mapping Toolkit. As part of the COBOL, Windows Form and Web Form client generation, a proxy program is also generated. The proxy provides a standard mechanism for invoking the service, and is intended to be used by production clients.

The type of client generated depends on the type of service interface:

Interface Type	Client(s) Generated
Java - EJB or Java Bean	JSP
Web services	COBOL Windows Form Web Form
.NET	Windows Form Web Form

Client generation for CICS services is handled the same as for non-CICS services. For more information about:

JSP clients - See the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book.
COBOL console clients - See the chapter COBOL Web Services with the Interface Mapping Toolkit in your Web Services and COBOL book.
Windows Form and Web Form clients - See the section Running Windows and Web Form Clients later in this chapter.

How to...

Running Windows and Web Form Clients

You can run Windows Form and Web Form clients from the Service Interfaces window. To do so, you must have your enterprise server started, your service deployed to your enterprise server, and your client generated.

How to...

Editing Clients

You can edit clients to enhance their appearance and usability.

Java

You can edit the generated Java JSP file using any JSP editor. Generated JSP files are contained in the servintname.war archive file located in the following folder:

nxprojdir\servintprojname\REPOS\servintname.deploy

Where nxprojdir is your Net Express project directory, servintprojname is the name of the service interfaces group, which is typically the same as the Net Express project, and servintname is the name of your service interface.

You can extract the JSP file using a utility such as WinZip.

Note: If you edit the JSP file, add it back to the .war archive and save a copy of it to another location to ensure it does not get overwritten. If you were to redeploy the service interface, all files in the \servintname.deploy folder are deleted and replaced by new deployment files.

Windows Form

When you generate a client for a Web service or .NET interface, the Client Generator generates service interface support files, Windows Form client files, an associated Visual Studio project file and, for .NET interfaces only, a .NET proxy module. To edit the Windows Form for your client, open the generated project in Visual Studio and edit it there. All generated Windows Form client files, including the Visual Studio project file, are located in the following folder:

nxprojdir\servintprojname\client\servintname\Windows

The Visual Studio project file takes the following form:

servintnameApp.cblproj

All other generated files such as support files and proxy files are located in the following folder:

nxprojdir\servintprojname\client\servintname

For information on editing Windows Forms in Visual Studio, see the topic Tutorial: Creating Windows Forms in COBOL in your Help for .NET COBOL within Visual Studio.

Web Form

The Client Generator generates an .aspx file, including its codebehind file, as your Web Form that you can edit using Visual Studio Form Designer. Generated Web Form .aspx files are located in the following folder:

nxprojdir\servintprojname\client\servintname\Website

All other support components such as DLLs are located in the following folder:

nxprojdir\servintprojname\client\servintname\Website\bin

If IIS is installed on the local machine, an IIS "alias" is also created, and all files are copied to it's mapped directory. For example, an IIS alias directory for a service in the project named bankdemo might be c:\inetpub\wwwroot\bankdemo. IIS and Internet Explorer are required to execute Web Form clients.

For information on editing Web Forms in Visual Studio, see the topic Tutorial: Creating Web Forms in COBOL in your Help for Net Express with .NET within Visual Studio.

Deploying Clients

Clients generated for CICS services can be deployed to other machines in the same manner as clients generated for non-CICS services.

The process of deploying a Java client is documented in the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book.

The process of deploying generated Windows Form and Web Form clients to another machine is documented in your Help for .NET COBOL within Visual Studio in the topics To deploy a Windows application to the .NET environment and To deploy a CICS service interface to the .NET environment .

Tracing Service Execution

You can use the Trace utility to collect information on the execution of your service.

Tracing CICS Service Execution

You enable the Trace utility on the Mapping Properties dialog box CICS tab, and specify a trace queue name of eight characters or fewer.

How to...

We provide a trace viewer you can run using a TN3270 emulator. You must have your service deployed to an enterprise server configured with a TN3270 listener. You can retrieve information about transactions and render screens.

How to...

Note: Before redeploying your service for production, turn the Trace utility off.

Tracing IMS Service Execution

You can trace IMS service execution using the Micro Focus Consolidated Tracing Facility (CTF). To enable tracing, set the appropriate IMS deployment options and then configure the CTF by setting the MFTRACE_CONFIG environment variable to point to the ctf.cfg configuration file.

The following is an example of the contents of a typical ctf.cfg file:

mftrace.emitter.es#level             = 99999
mftrace.application                  = cassi
mftrace.dest                         = textfile
mftrace.emitter.textfile#Location    = c:\ctf
mftrace.level                        = debug
mftrace.comp.mf.rts#api              = true
mftrace.comp.mf.rts#container        = true
mftrace.comp.mf.rts#external         = true
mftrace.comp.mf.rts#fsys             = false
mftrace.comp.mf.rts#jsem             = false
mftrace.comp.mf.rts#memory           = false
mftrace.comp.mf.rts#mfentmap         = true
mftrace.comp.mf.rts#mfpm             = false
mftrace.comp.mf.rts#pgm              = true
mftrace.comp.mf.rts#pgmload          = true
mftrace.comp.mf.rts#pgmsearch        = false
mftrace.comp.mf.rts#syspgm           = true
mftrace.comp.mf.rts#signal           = true

After running a trace, search the resulting logfile for the text string MFEBI, which starts the section where IMS service execution trace information begins.

How to...