Client/Server Binding for Enterprise Server

This chapter describes the introduction of Client/Server Binding support for Enterprise Server, and describes the key differences between this and previous implementations.

In this Chapter

Prerequisites

You should be familiar with the use of Client/Server Binding as described in the chapter Client/Server Binding.

Overview

Writing client/server applications typically requires you to include complex code to manage communications. Client/Server Binding refers to a Micro Focus middleware feature that enables you to write client/server applications in COBOL using a simple call interface.

The introduction of Client/Server Binding for Enterprise Server enables you to run the server part of such an application under Enterprise Server. It also provides a number of features that were not available in previous releases, along with improvements in performance, reliability and robustness.

As with previous releases, the client part of your Client/Server Binding application is a conventional COBOL program running under Net Express, Server Express or Micro Focus Server.

The server part is run by a service on your enterprise server. Each service can run servers for one or many applications. However, you may want to configure a separate service for each application. Clients can use dynamic name resolution to locate the service.

Note: If you do not want to run your servers under Enterprise Server, you can still use Client/Server Binding with CCI and AAI as with previous versions. For more information, see the chapter Client/Server Binding.

How it Works

Enterprise Server provides an execution environment for your COBOL programs. It exposes these programs as services that can be called by clients. Client/Server Binding for Enterprise Server supplies a service package, CSBIND, that runs the server programs of your client/server applications, and handles their communication requirements.

CSBIND is provided in a COBOL archive file which you deploy to the enterprise server of your choice. When you do this, CSBIND is installed along with the default client/server service, MFCLISRV. This service exposes CSBIND so that clients can call it. You can create additional services that expose CSBIND. Each service is associated with one or more listeners, which listen for service requests.

Your client program calls the supplied client module, MFCLIENT, which resolves the service name by contacting a Micro Focus Directory Server. MFCLIENT then connects to an appropriate listener on your enterprise server. The enterprise server runs the CSBIND module and passes it the client request. The CSBIND module then calls your server program. The response is returned via the listener connection to your client.

CSBIND runs in a conversational mode and does not exit when the response is returned to the client. When the client is prepared to make its next request, it again calls MFCLIENT which sends the request over the existing connection, continuing the conversation with the same CSBIND process.

Note: Enterprise Server runs service programs within Server Execution Processes (SEPs). When a service completes, the SEP that ran it is available to handle further service requests. A conversational program, like CSBIND, may run for a long period of time, and only terminates when the conversation with the client is complete. While the program is running, the SEP is occupied and is not available to handle other service requests. Therefore, for each CSBIND conversation that is taking place, Enterprise Server starts an additional SEP to ensure that it has sufficient to deal with new service requests.

Summary of Changes

Previous versions of Client/Server Binding used the transport mechanisms provided by Micro Focus Common Communications Interface (CCI) or the legacy middleware Application to Application Interface (AAI). This new version uses the new Micro Focus Common Client (MFCC) and the Micro Focus Communications Server (MFCS). It supports most of the features available with the previous versions. Those features not supported are detailed in the section Not Supported in this Release. You still have the option of using the CCI and AAI transports.

Client/Server Binding for Enterprise Server uses the same APIs and the same configuration file format as previous versions of Client/Server Binding. With a few exceptions it will work correctly with existing compiled Client/Server Binding applications.

Not Supported in this Release

Supported in this Release

New Features in this Release

Improvements

Advantages over Implementations using CCI

Advantages over Implementations using AAI

Client Side Requirements

Component/Module Description
COBOL runtime This is installed with Net Express, Server Express, Enterprise Server, and Micro Focus Server.
Micro Focus Common Client component (mclient.dll) version 1.9.0 or later Also installed with Net Express, Server Express, Enterprise Server, and Micro Focus Server.
mfclient.int This is the new client runtime that handles the MFCC API
mfoldcsb.int This is the client runtime module that handles the CCI API
aaiclnt.int This is the client runtime module that handles the AAI API

For development, the mfclisrv.cpy copybook is required.

Server Side Requirements

Enterprise Server
Micro Focus Communications Server version 1.10.0 or later Installed with Enterprise Server. To check your version of Micro Focus Communications Server, use mfcs -v at the command line.
mfdepinst version 1.4.0 or later This is supplied with Enterprise Server and is used to install the default service that will run the server part of your application. You can also do the service installation manually.

You also need to deploy the CSBIND service (provided in COBOL archive file csbind.car) to your enterprise server. This is the default service for running the server parts of your client/server applications. You can use the package that it contains to create additional services. See the section Deploying the default service

Development and Sample files

What You Need To Do

To run your application, you will also need to ensure that:

Starting the Directory Server

On Windows, when Enterprise Server is installed, the Directory Server is started automatically as a Windows service. You can stop the Directory Server and start it again using the Windows Control Panel.

On unix, depending on how Enterprise Server has been installed, either you can use the mfds command to start it, or it can start automatically when the machine is started. To stop the Directory Server, you use a menu option of the Web interface.

Deploying the Default Service

The default service, MFCLISRV, is provided in a COBOL archive file, csbind.car. You can install the service to your enterprise server using the imtkmake or mfdepinst utilities.

For example, to deploy the MFCLISRV service under the ESDEMO server using the default configuration:

  1. At the command prompt, change to the deployment directory for ESDEMO; this is Base\Deploy under your Net Express installation, $COBDIR/deploy in Server Express.
  2. Create a subdirectory named "csbind" and change to it.
  3. Copy csbind.car to the csbind directory.
  4. Run "mfdepinst csbind.car".
  5. When mfdepinst completes, look at the file deploylog.txt in the current directory to see if deployment completed successfully.

The deployment process extracts the files needed to run servers under Enterprise Server. These are:

It then creates two new objects in the Micro Focus Directory Server repository, under the enterprise server where the service is being installed. These are:

You can use the MFCLISRV as the service for all of your Client/Server Binding applications or you can use Enterprise Server Administration to create additional services that use the CSBIND package (see the section Adding Extra Services). The client part of the application supplies the name of the server program when making the connection, so more than one application can use the same service.

Adding Extra Services

After you have deployed the default server, you can add extra services that expose the CSBIND package. You do this with Enterprise Server Administration.

When you add the service, you select CSBIND as the package, and MFRHBINP as the handler.

For example, to add a CSBIND service called CSTEST, which uses the Web Services listener, to ESDEMO:

  1. On your server machine, start a web browser and enter the URL http://localhost:86.

    This displays the Enterprise Server Administration home page. The current status column tells you whether or not a server is started.

  2. Click the Edit button in the left hand column for ESDEMO.

    This displays a screen containing tabs that provide detailed administrative options.

  3. Click Services.
  4. Click Add.
  5. In Name, type CSTEST.
  6. Choose the type of transaction management appropriate to this service: check Container unless your application does explicit commits and rollbacks.
  7. In Available Listeners, click the Web Services listener and then click Add.

    This places the Web Services listener in the list of accepting listeners for this service.

  8. In Available Request Handlers, click MFRHBINP and then click Select Handler. The selection is active immediately.
  9. In Available Packages, click CSBIND and then click Select Package. The selection is active immediately.
  10. Choose a status for the service from the list in Initial status. By default the initial status is Available.
  11. Click Add.

Installing the Server Module

The simplest way to install your program is to put it into the same directory as you used for deploying the default service. This directory contains the CSBIND package module. In the example given in the section Deploying the Default Service, the directory is base\deploy\csbind.

Alternatively, you can place your server module in a directory that is on the COBPATH for your enterprise server. When an enterprise server starts, it inherits its environment from the Directory Server. However, you can set environment variables for an enterprise server by using Enterprise Server Administration. See the chapter Configuration in your Enterprise Server Configuration and Administration Guide for more information.

Start the Enterprise Server

You do this using Enterprise Server Administration.

For example, to start ESDEMO.

Setting the Service Status

You can set status of a service to Available or Disabled. If you set the status to Disabled, your client programs will no longer be able to establish a connection to that service. In effect, this is the same as closing down the master server under CCI.

To alter the availability of a service, you use Enterprise Server Administration.

For example, to alter the availability of MFCLISRV on ESDEMO:

  1. On your server machine, start a web browser and enter the URL http://localhost:86.

    This displays the Enterprise Server Administration home page. The current status column tells you whether or not a server is started.

  2. Click Details in the Objects column for ESDEMO.
  3. Click Edit in the Operation column MFCLISRV.
  4. Choose the new status from the list in New Status.
  5. Click Apply.

Setting the Listener Status

Typically, you will configure a separate service for each of your Client/Server Binding applications, and you will have one listener (such as the "Web Services" listener included with the sample configuration) which receives the requests. You can also give CSBIND requests their own listener, or multiple listeners.

If you change the status of the service's listener to "Blocked", then all services belonging to that listener will be hidden. If you change the status of the listener to "Stopped", then it will stop accepting new conversations until it is changed back to "Started" or the enterprise server is restarted. If you set the status to "Disabled" the listener will be stopped and will not be restarted when the enterprise server is restarted.

For example, to change the status of the Web Services listener for ESDEMO.

  1. On your server machine, start a web browser and enter the URL http://localhost:86.
  2. Click Details in the Communications Processes column for ESDEMO.
  3. Choose All from the Process list.
  4. Click Edit in the row for the Web Services listener.
  5. Choose the new status from the list in New Status.
  6. Click OK.

Migrating from CCI/AAI

Migration Considerations

Client/Server Binding for Enterprise Server uses the same APIs and configuration file format as other versions of Client/Server Binding, and in most cases should work correctly with existing compiled Client/Server Binding-based application program modules.

As with CCI and AAI, Enterprise Server mode for Client/Server Binding is selected using the "commsapi" parameter in the client's configuration file. This lets developers easily compare Client/Server Binding for Enterprise Server with other Client/Server Binding transports simply by changing their configuration. To use Client/Server Binding for Enterprise Server, follow the steps in the section What You Need To Do.

Once Client/Server Binding for Enterprise Server servers have been configured, existing Client/Server Binding clients can be upgraded to Client/Server Binding for Enterprise Server simply by upgrading Micro Focus Server to the latest version (or at least installing the MFCC modules, listed below) and updating the client configuration file. It's possible to run CSBIND/ES and CSBIND/CCI or CSBIND/AAI servers in parallel on the same system, in order to gradually upgrade a large client base.

Understanding the Changes in Server Management

Client/Server Binding with CCI required a non-dedicated server module, MFSERVER, to run on the server machine. For each new client conversation, this spawned a dedicated instance of itself to handle the server part of the application. The non-dedicated module was usually started manually, either by a user from the command line or by a system script. When a system administrator wanted to stop the server, the usual mechanism was to run the "mfcsmgr" utility with the "-t" option.

With Client/Server Binding using AAI (CSBIND/AAI), the spawning of the dedicated server module was controlled by AAI, and the system administrator would start and stop it by starting and stopping the AAI subsystem.

Client/Server Binding for Enterprise Server is similar to AAI in this area, though it is more flexible. It provides a service package, CSBIND, which runs the server part of your application. The package can be associated with one or more services and one or more listeners (which receive client requests and pass them to the package module). Typically, you will configure a separate service for each of your Client/Server Binding applications, and you will have one listener (such as the "Web Services" listener included with the sample configuration) which receives the requests. You can also give CSBIND requests their own listener, or multiple listeners.

If the CSBIND services are configured as "Available" and their listeners are configured to start when the enterprise server is started - the default configuration - then your Client/Server Binding servers will be available whenever that enterprise server is running.

If you change the status of a CSBIND service to "Disabled" while your enterprise server is running, your client programs will no longer be able to establish a connection with that service. If you change the status of the service's listener to "Blocked", then all services belonging to that listener will be hidden from all clients (except for clients which connect directly using the "machinename" configuration option - see below). If you change the status of the listener to "Stopped", then it will stop accepting new conversations until it is changed back to "Started" or the enterprise server is restarted.

How to Migrate your Application

Notes and Recommendations

Configuring Micro Focus Common Client

Client/Server Binding for Enterprise Server uses Micro Focus Common Client (MFCC), as its client communications API. MFCC is configured using the text file mf-client.dat in the base\bin directory (Windows) or $COBDIR/etc (Unix). See the COBOL product documentation for more information on configuring MFCC using mf-client.dat.

Some MFCC configuration parameters deserve special mention in the context of Client/Server Binding applications:

Using a Fixed TCP Port

You can use a fixed TCP port on the server machine for Client/Server Binding conversations. Simply configure the listener that is used by the service or services for your applications to use a fixed port in Enterprise Server Administration.

Note: Regardless of how your listener is configured, Client/Server Binding for Enterprise Server uses only one port for each conversation. This contrasts with Client/Server Binding when used with CCI, which opened a new port every time a client connected.

Using the machinename parameter

Under Client/Server Binding for Enterprise Server, the "machinename" parameter has somewhat different behavior and syntax than with previous versions. When using Client/Server Binding with CCI, specifying a machinename simply told CCI to look for the named service on the given machine. CCI still had to query the service directory on the named machine to find the service.

Client/Server Binding for Enterprise Server uses Micro Focus Common Client (MFCC), the configuration file of which specifies the directories to query. The machinename parameter is now used to tell the client exactly where to connect to the service's listener - just like a URL for a web page. When machinename is used, there is no directory lookup.

Using machinename has some advantages. First, the client (and the user) knows exactly which service it will connect to. Second, it is faster than querying a directory. Third, it is useful for penetrating a firewall, since the firewall does not have to be configured to allow Micro Focus Directory Server (MFDS) queries.

However, using directory lookup (and not using machinename) also has advantages. It frees the client (and the user) from having to know where the service is located. It lets the system administrator move the service from one machine to another, or change the port of its listener, or let the operating system select the port. It permits simple failover (if the service is supplied on multiple machines, directory search will find a running instance) and load balancing (MFCC will pick an available instance of the service at random, so clients will be spread roughly equally among servers).

Broadly speaking, directory lookup is more resilient and direct addressing using machinename gives you more control. Your application requirements and execution environment will determine which is better for you.

When you use the machinename parameter with Client/Server Binding for Enterprise Server, the value can be in several forms:

Using the New Configuration Options

Performance Planning

The number of clients that a Client/Server Binding for Enterprise Server application can run is dependent on the hardware and software environment to which it is deployed. With a suitable small server configuration, it can support up to 1000 clients.

Restrictions

At this point in time Enterprise Server does not support 64 bit applications.