Using Panels V2

Advanced Topics

Chapter 14: Using the Client/Server Binding

This chapter shows you how the Client/Server Binding works and then describes how to connect your user programs to the generic client/server modules.

14.1 Introduction

The Client/Server Binding enables you to implement a client/server architecture with a Dialog System front end using the Micro Focus Common Communications Interface component (CCI) "under the covers". The Client/Server Binding removes the requirement for you to include communications code in your application by providing two modules called mfclient and mfserver. These are generic modules which can be used to drive any application.

Based on information contained in a configuration file, the modules manage the communication and transfer of data between themselves and are able to interact with user-defined programs at each end of the link to process this data. mfclient is called by a user client program which handles the user interface, and mfserver calls a user server program which handles data access and business logic. However, as these user client and server programs are user-defined, they can do anything you require.

The user programs must use the copyfile mfclisrv.cpy, described in the section The mfclisrv.cpy Copyfile, to interact with the generic client/server modules.

A sample two-tier application, based on the Dialog System CUSTOMER demonstration, is available in the directory DialogSystem\demo\csbind of your installation directory. This sample application demonstrates how to use use the Client/Server Binding and is referred to throughout this chapter. For more information on the sample application please see the file csbind.txt installed in the DialogSystem\demo\csbind directory.

14.2 How the Client/Server Binding Works

This section illustrates how a two-tier application, created using the Client/Server Binding works.

The Client/Server Binding works by having a non­dedicated copy of mfserver running on the server tier; that is, mfserver communicates with any and all clients using an agreed server name. This mfserver module can be run with its built-in defaults since its only function is to receive the starting and ending communications from the client.

This process is illustrated in the next diagram, Figure 14-1. The flow of information illustrated in the diagram is explained below:

1. The user's client program (custint) CALLs mfclient.

2. The first time mfclient is called, it reads configuration information from the .cfg file.

3. mfserver receives the connection request.

4. mfserver spawns a secondary server for each client. The server name is internally generated, based on the name of the initial server with a numeric ID added (for example, mfserver01). Alternatively, you can specify a name in the configuration file.

5. mfserver sends the secondary server name (mfserver01) back to mfclient and terminates the conversation.

6. mfclient connects with the secondary server (mfserver01), passing parameters obtained from the configuration file via the LNK-PARAM-BLOCK. See the section The Client/Server Binding Configuration File.

7. mfserver01 CALLs the user server program (custdata), passing the parameters received from mfclient via the Linkage Section.

8. The first time the user server program (custdata) is called, it performs any application initialization code and exits the program. Control is returned to mfserver01.

   
   
   Figure 14-1: Client/Server Binding

9. mfserver01 returns control to mfclient.

10. mfclient ensures contact has been established and returns control to the user client program (custint).

11. In the user client program (custint), data associated with the user interface is mapped to areas assigned by mfclient within the Linkage Section.

12. The user client program (custint) calls the user interface. up the screenset and CALLs Dialog System.

13. The user enters input in the user interface (CUSTOMER).

14. The user client program CALLs mfclient again to pass back the user-entered data (for example a Customer Code) and any other information required by the application server program (custdata) via the Linkage Section.

15. mfclient passes the data to mfserver01 via its internal buffer.

16. mfserver01 CALLs the user server program (custdata).

17. The user server program (custdata) performs any appropriate data access and business logic and returns the results to mfserver01 via the Linkage Section.

18. mfserver01 returns control to mfclient.

19. mfclient passes the data back to the user client program (custint) via the Linkage Section.

20. The user client program (custint) CALLs the user interface to display data and accept any new user input.

    Steps 14 thru 20 are repeated until the user exits the application.

21. mfclient informs the base server (mfserver), that the secondary server (mfserver01) has terminated.

    This use of initial and secondary servers resolves several issues:

    • There is no need to have specific servers for different applications. The secondary server is provided with relevant details by the client from the client configuration file. Users can still set up multiple servers, but there is no longer a requirement to do so.

    • There are no data access conflicts, as each user has his or her own run unit which ensures that files are always in the same state as when last accessed.

    • In the event that a user makes a time-intensive request, only that user will experience any delay. All other users will continue to receive optimum responses. Processing time­intensive requests can cause the client to lock up the interface. You can deal with this in the following way:

      You can issue an asynchronous request which returns a request id to the program. You then make regular checks for the completion of the request using the id which was returned. An example of using asynchronous requests is given in the section Connecting Your Client Program to mfclient.

14.3 Connecting Your Programs to the Generic Modules

The following sections show you how to:

• Connect your user programs to the generic client and server modules.

• Prepare the communications link.

14.3.1 Connecting Your Client Application to mfclient

This section shows you how to connect your client program to the mfclient module, which handles communications with the server. The mfclient and mfserver modules pass information to each other via a parameter block described in the mfclisrv.cpy copyfile.

The modules also use the same parameter block to pass information to any user programs they have been requested to call in the configuration files. For details on the LNK-PARAM-BLOCK, see the section Connecting Your Server Application to mfserver.

To connect your client program calling the user interface, you must add code to pass parameters to mfclient.

To use the Client/Server Binding, your client program will need to include code similar to that below. This is an extract of the user interface program (custint.cbl) supplied with Dialog System to demonstrate how to use the Client/Server Binding.

$SET ANS85
 WORKING-STORAGE SECTION.
 COPY "MFCLISRV.CPY".
 LINKAGE SECTION.
* The following two copyfiles are used by Dialog System
* user interfaces to communicate with the COBOL program
* which calls the interface
 COPY "DS-CNTRL.V1".
 COPY "CUSTOMER.CPB".
 PROCEDURE DIVISION.
 CLIENT-CONTROL SECTION.
     PERFORM UNTIL END-CONNECTION
         CALL LNK-CLIENT USING LNK-PARAM-BLOCK
         EVALUATE TRUE
          WHEN START-CONNECTION
             SET ADDRESS OF DS-CONTROL-BLOCK TO LNK-CBLOCK-PTR
             SET ADDRESS OF CUSTOMER-DATA-BLOCK TO LNK-DBLOCK-PTR
             PERFORM SETUP-SCRNSET
             PERFORM CALL-DIALOG-SYSTEM
          WHEN END-CONNECTION
             EXIT PERFORM
          WHEN OTHER
             PERFORM CALL-DIALOG-SYSTEM
         END-EVALUATE
         IF CUSTOMER-EXIT-FLG-TRUE
            SET CLIENT-ENDING TO TRUE
         END-IF
     END-PERFORM.
 CLIENT-CONTROL-END.
     STOP RUN.

You can add code to enable client counting, handle error message displays yourself or handle asynchronous requests. For details, see the sections Connecting Your Client Program to mfclient and Connecting Your Server Program to mfserver.

14.3.2 Connecting Your Server Application to mfserver

This section shows you how to connect your server program, which performs data access and/or business logic, to the mfserver module which handles communications with the client. The mfclient and mfserver modules pass information to each other via a parameter block described in the mfclisrv.cpy copyfile. The modules also use the same parameter block to pass information to any user programs they have been requested to call in the configuration files.

The following information does not apply if you are using an existing application as your server program. For details on using the Client/Server Binding in that way, see the section Running a Client/Server Binding Application.

To use the Client/Server Binding:

• Your server program will need to include in the Linkage Section the binding copyfile, mfclisrv.cpy, and any copyfiles required to pass information between your client program and the user interface.

• Modify the Procedure Division header to include "LNK-PARAM-BLOCK", which passes parameters from mfserver.

• Associate addresses passed by mfserver in the mfclisrv.cpy with the copyfiles used by your user interface, in this example DS­CONTROL­BLOCK and the SCREENSET-DATA-BLOCK are the data structures defined in ds-cntrl.cpy and customer.cpb. For details on the LNK-PARAM-BLOCK, see the section Connecting Your Server Program to mfserver.

This is shown below in the code extract of the server program (custdata.cbl) used to run the Client/Server Binding.

 LINKAGE SECTION.
 COPY "DS-CNTRL.V1".
 COPY "CUSTOMER.CPB".
 COPY "MFCLISRV.CPY".
 PROCEDURE DIVISION USING LNK-PARAM-BLOCK.
 CONTROLLING SECTION.
*---------------------------------------------------------------*
*  ASSOCIATE THE DIALOG SYSTEM COPYBOOKS WITH AREAS RESERVED
*  FOR THEM WITHIN LNK-PARAM-BLOCK
*---------------------------------------------------------------*
     SET ADDRESS OF DS-CONTROL-BLOCK TO LNK-CBLOCK-PTR.
     SET ADDRESS OF CUSTOMER-DATA-BLOCK TO LNK-DBLOCK-PTR.
     EVALUATE TRUE
      WHEN START-CONNECTION
         PERFORM PROGRAM-INITIALIZE
      WHEN OTHER
         PERFORM PROGRAM-BODY
     END-EVALUATE.
     EXIT PROGRAM.
 PROGRAM-INITIALIZE SECTION.
     OPEN I-O CUSTOMER-FILE.
 PROGRAM-BODY SECTION.
     MOVE CUSTOMER-C-CODE TO FILE-C-CODE
     READ CUSTOMER-FILE
     ..........
     PERFORM DERIVATIONS

You can add code to handle error message displays yourself. For details, see the section Connecting Your Server Program to mfserver.

14.3.3 Preparing a Communications Link

The Client/Server Binding controls the communications between your client and server programs based on the contents of the configuration file. That means there is no complicated communications programming for you to do.

To run the demonstration, use the appropriate configuration (.cfg) file unmodified. For your own application, you must copy and modify the contents of one of these configuration files. The configuration file is an ASCII text file containing parameters allowing you to specify key information such as:

• The name of the user program to be called by mfserver.

• The maximum number of clients allowed to connect to the server.

For more details on using configuration files with the Client/Server Binding, see the section The Client/Server Binding Configuration File.

Notes:

• This document assumes your communications link using CCI is already correctly installed, configured and working on both your client and server machines.

• You must use a network software vendor supported by Micro Focus CCI. For full details on supported vendor's software, see the product description on Micro Focus Worldwide Web homepage, contact your Micro Focus Sales representative or see the documentation supplied with the Micro Focus software.

14.4 Before Using the Client/Server Binding

You can use the client/server binding with an existing standalone application or an application architectured for client/server. For more information on using existing standalone applications, see the section Running a Client/Server Binding Application.

In either case, your application contains the following (examples of the supplied Dialog System demonstration programs are shown):

You can use the client/server binding instead of creating your own middleware code. For this, you need to:

• Create a configuration(.cfg) file to control the behavior of the mfclient and mfserver modules and the communications connection.

  The configuration file is an ASCII text file containing parameters allowing you to specify key information such as:

  • Which communications protocol will be used.

  • The name of the user program to be called by mfserver.

  This configuration file format is described in detail in the section The Client/Server Binding Configuration File. Sample configuration files (custgui.cfg and customer.cfg) are provided with the client/server binding demonstration programs.

  You can have separate configuration files for each application or you can supply multiple entries in a single file. If using multiple entries, each one must have its own tag name followed by the list of parameters to which the tag relates. You also need to supply the tag name to be used, by putting the relevant name in lnk-tagname in your client interface program. This technique can be used to reduce your command line length by specifying your multiple entries in a file called mfclisrv.cfg for which the binding will search if no other name is specified. This technique can also be used to allow you to drive different applications from a single menu.

• Add code to your client program to call the mfclient module with linkage parameters. This is explained in the section Connecting Your Client Application to mfclient.

• Add code to your server program to enable it to be called with linkage parameters from the mfserver module. This is explained in the section Connecting Your Server Application to mfserver.

14.4.1 The mfclisrv.cpy Copyfile

The mfclient and mfserver modules pass information to each other via the parameter block defined in the copyfile mfclisrv.cpy. For example, the information includes addresses for the Dialog System screensetdata-block and ds-control-block. The modules also use this parameter block to pass information to any user programs they have been requested to call in the configuration files. The mfclisrv.cpy copyfile must be included in any of your COBOL programs which use the mfclient and mfserver modules.

The mfclisrv.cpy copyfile is installed in the SOURCE directory of your Net Express base installation directory.

14.4.2 The Client/Server Binding Configuration File

This section describes the configuration file for the client/server binding. This configuration file controls the behavior of the mfclient and mfserver modules as well as the communications link.

You create one or more configuration files for your application. You can have as many configuration files as your application requires, but each file must have a .cfg extension. If you do not supply a configuration filename yourself, the program will default to using the name mfclisrv.cfg. You do not need a configuration file, but if you do not supply one, the demonstration programs supplied with the client/server binding are run by default.

If your client/server application is incorrectly set up, any invalid entries found in the configuration file cause the programs reading them to terminate with a message displayed on the screen detailing the invalid entries.

These errors are also logged in the mfclisrv.log file, which is created in the current directory, or in the directory indicated by the MFLOGDIR environment variable. This enables a server which is not directly connected to a terminal to log messages regarding problems it encounters.

14.4.2.1 Possible Entries for the Configuration File

Below are possible entries for the mfclisrv.cfg configuration file. Entries are listed in alphabetical order. Any entries which you do not specify in your configuration file will assume the default values.

**********************************************************
* Micro Focus - Client/Server Module Configuration File


**********************************************************

14.4.2.2 Minimum Required Configuration File Entries

The minimum number of entries required in the configuration files varies depending on which of the following factors are being used:

• The application (for example Dialog System).

• The version of Dialog System (hence the size of the Dialog System control block required).

• The functions of Dialog System (for example callouts).

• The number of servers.

• The communications protocol (for example CCITCP).

The following table shows the different entries needed for Dialog applications which are and are not using an existing Dialog System program as the server.

When running multiple servers, you must supply the name of the server to be used via the servername entry.

Any configuration file entries which are unset assume the specified default values.

If you are not using TCP/IP, you must set the protocol entry.

14.4.2.3 Locating The Configuration File

You can specify where to locate the configuration file. The mfclient and mfserver programs attempt to locate the configuration file in the following ways:

1. They look for the MFCSCFG environment variable and use the supplied filename if one is specified.

2. They examine the command line and use any filename defined there in preference to that supplied via the MFCSCFG environment variable.

3. If MFCSCFG is not set or contains no value, or if no filename has been specified on the command line, the default name mfclisrv.cfg is assumed and searched for in the current directory.

4. If mfclisrv.cfg is not found, the default settings for the configuration entries described earlier in this document will be used.

In each case a full path of up to 128 characters can be used to identify the location of the configuration file.

14.5 Connecting Your Client Program to mfclient

In order to create programs using the client/server binding, add code similar to that described below to your client and server programs, so they can control the connection correctly. The amount of code required is quite small. Comments have been included to help you understand what the code is doing.

WORKING-STORAGE SECTION.
COPY "mfclisrv.cpy".

LINKAGE SECTION.

COPY "DS-CNTRL.V1". 
COPY "CUSTOMER.CPB".

PROCEDURE DIVISION.
Client-Control SECTION.

*  The main loop is repeated until the connection with 
*  the server ends

    PERFORM UNTIL End-Connection

* 'lnk-client' holds the name 'mfclient'
*  The first time through we initialize the system and establish 
*  contact with the server.

    CALL lnk-client USING lnk-param-block

    EVALUATE TRUE
      WHEN start-connection

*  Make the DS control block and the customer Data Block 
*  accessible by assigning them address allocated by 'mfclient'.

            SET ADDRESS OF ds-control-block TO lnkcblock-ptr
            SET ADDRESS OF customer-data-block TO lnkdblock-ptr

*  Having successfully established contact with the server, we
*  complete local initialization and make the first call to 
*  Dialog System.

            PERFORM Setup-Scrnset
            PERFORM Call-Dialog-System 
         WHEN end-connection
            EXIT PERFORM
         WHEN OTHER
            PERFORM Call-Dialog-System
      END-EVALUATE

*  Check if the exit flag has been set by the user on the screen

      IF customer-exit-flg-true
         SET client-ending TO TRUE
      END-IF
   END-PERFORM
   STOP RUN.

Note: The client program has the Dialog System copybook in linkage and maps it to an address provided by the binding. This copybook has three other 01-level items which are not mapped. These are the Dialog System version number and the Data Block version number. The reason they are not mapped is that their values would not be picked up by mapping, and it is the values they contain that we need. You can hard code the Dialog System version number in the program, as this very rarely changes. The Data Block version number, however, does change, and putting a fixed value in your program means that you have to remember to update it whenever the screenset is modified. To make this easier, a support program used by the binding can extract the screenset version number for you and allow you to set it dynamically. To use this program, add the following items to working storage:

    01  ws-null             PIC X(4) COMP-X.
    01  ws-scrnset-ver      PIC X(4) COMP-X.
    01  ws-ret-stat         PIC X COMP-X VALUE 0.

Add the following to the Procedure Division where the screenset details are being set up. The screenset name being used must include the correct extension. You would set ds-version-no to 3 for extensions of .rs.

      MOVE "CUSTOMER.gs" TO ds-set-name
      MOVE 2 TO ds-version-no
      CALL "dsdblksz" USING
           ds-set-name
           ws-null
           ws-scrnset-ver
           ws-ret-stat
      END-CALL
      MOVE ws-scrnset-ver to ds-data-block-version-no

If you want to control the number of clients running an application, or you choose to handle error message displays yourself, add code similar to the following to your program's initial EVALUATE statement.

      WHEN TOO-MANY-CLIENTS
         PERFORM OVER-CLIENT-LIMIT
      WHEN COMMS-ERROR
         PERFORM SHOW-ERROR
...

  OVER-CLIENT-LIMIT SECTION.
      DISPLAY SPACES AT 0101 WITH BACKGROUND-COLOR 7
        "MAXIMUM NUMBER OF CLIENTS EXCEEDED - SESSION ENDED"
        AT 1012 WITH FOREGROUND-COLOR 4
        SET CUSTOMER-EXIT-FLG-TRUE
            CLIENT-ENDING TO TRUE
      EXIT.

  SHOW-ERROR SECTION.
      DISPLAY LNK-ERROR-LOC AT 2201
         LNK-ERROR-MSG AT 2301 WITH SIZE LNK-ERROR-MSG-LEN. 
  SHOW-ERROR-EXIT.
      EXIT.

If you want to handle asynchronous requests, add additional code similar to the following to the EVALUATE statement:

      WHEN START-CONNECTION
         PERFORM GET-USER-INPUT
         IF MAKE-ASYNC-REQUEST  <* USER ASYNCHRONOUS OPTION
           SET ASYNC-REQUEST TO TRUE
         END-IF
      WHEN ASYNC-OK
         SET TEST-ASYNC-RESULT TO TRUE
         PERFORM DELAY-LOOP
      WHEN ASYNC-INCOMPLETE
         DISPLAY "REQUEST STILL BEING PROCESSED " AT 1010
         PERFORM DELAY-LOOP
         SET TEST-ASYNC-RESULT TO TRUE
      WHEN RESULT-OK
         DISPLAY "REQUEST COMPLETED             " AT 1010
         PERFORM GET-USER-INPUT
      WHEN ASYNC-NOT-STARTED
      WHEN ASYNC-FAILED
         DISPLAY "ASYNCHRONOUS REQUEST FAILURE  " AT 1010
         PERFORM SHOW-ERROR
         PERFORM GET-USER-INPUT
      WHEN COMMS-ERROR
         PERFORM SHOW-ERROR

14.6 Connecting your Server Program to mfserver

WORKING-STORAGE SECTION.

LINKAGE SECTION.

    COPY "DS-CNTRL.V1".
    COPY "CUSTOMER.CPB".
    COPY "mfclisrv.cpy".

PROCEDURE DIVISION USING lnk-param-block.
Controlling SECTION.
*--------------------------------------------------------------*
*  Associate the Dialog System copy books with their location
*  within the CS binding parameter block
*--------------------------------------------------------------*

    SET ADDRESS OF ds-control-block TO lnk-cblock-ptr.
    SET ADDRESS OF customer-data-block TO lnk-dblock-ptr.
    EVALUATE TRUE
      WHEN start-connection
         PERFORM Program-Initialize
      WHEN customer-exit-flg-true
         PERFORM Program-Terminate
      WHEN OTHER
         PERFORM Program-Body
    END-EVALUATE.
    EXIT PROGRAM.

If you choose to handle error message displays yourself, add code similar to the following to your program's initial EVALUATE statement.

    WHEN COMMS-ERROR
       PERFORM SHOW-ERROR
       SHOW-ERROR SECTION.
           DISPLAY LNK-ERROR-LOC AT 2201
              LNK-ERROR-MSG AT 2301 WITH SIZE LNK-ERROR-MSG-LEN. 
       SHOW-ERROR-EXIT.
           EXIT.

14.7 Running a Client/Server Binding Application

The mfserver module is provided in .int code format so that it can be run as it is, generated into .gnt code, or linked with other programs to create executable modules (UNIX only).

The mfclient and mfserver modules are run as standard COBOL programs, with both the client and server components started manually.

When running an existing stand-alone program as a server, specify its name, in the srvtier configuration entry, as the program which the base server should run (srvtier). Communications are handled by a copy of the mfserver module renamed dsgrun created as follows:

• For non-UNIX servers, you must copy the mfserver.int file to DSGRUN.int.

• On UNIX, you can link the mfserver.int file to DSGRUN.int instead of creating a separate program. On UNIX, you must also create a cobconfig file containing the following entry:

  set program_search_order=3

  and set the COBCONFIG environment variable to point to this file. This ensures that the call to DSGRUN in the standalone application will call the renamed mfserver module.

For details on the cobconfig file and environment variable, see your UNIX COBOL documentation. For details on linking and building executable modules, see the documentation for your chosen COBOL development environment.

The main benefit of using an existing program as the server is that you can have an application which runs on a single PC or a PC network, and can be deployed as a client/server application simply by using the binding and providing a single user interface program.

To run the client/server binding, first start the server program and then start the client program.

The command line to start the server program on UNIX is:

cobrun mfserver [-b] [-p protocol] [-s server-name] [-v]

and on Windows and OS/2:

runw mfserver [-p protocol] [-s server-name] [-v]

where:

The command line to start the client program is:

runw program-name [config-filename]

where:

For full details on running COBOL programs, see your COBOL system documentation.

14.8 Animating Your Application

You can animate your client program using the standard animation facilities of Net Express.

You can animate your server program by setting a configuration file parameter, srvanim=y (see the section Possible Entries for the Configuration File).

On PC servers, the Animator is started automatically when a client connects to the server if srvanim=y is set.

On UNIX servers, the Animator is run on the terminal from which mfserver was started, and so requires mfserver to be running in foreground mode. This can cause problems as it is preferable to run mfserver as a background process. A further restriction is that only one user can animate through mfserver at any one time. These problems can be avoided by setting srvanim=x,filename where filename is a file created using the touch command. On the terminal that you want to use to display Animator output, set COBANIM_2=animator and then run the command:

anim filename

On the terminal that you want to use for your standard input and output, run your application in the normal way, having added srvanim=x,filename to your configuration file.

14.9 Managing the Server

The behavior of the server can be altered by running the program mfcsmgr and passing it the required parameters and values. These parameters can be divided into two groups:

• Location

  The parameters in this group allow you to locate the target server, and can have settings m, p, and s.

• Action.

  These parameters control how the target server will be affected. They can have settings a, c, o, r and t. Parameters o, r and t must be specified singly as they generate an error message if combined with any other parameters.

14.9.1 Shutting Down mfserver

The spawned servers are terminated by the client program when the client makes a normal exit.

You must terminate the initial server program manually as it continues to run even if it has no clients.

14.9.2 Managing Authorization Passwords

To prevent accidental shutdown of an active server, it is possible to assign a password to each server. This password must be supplied before the server can be stopped or its parameters changed.

14.9.3 Setting the Maximum Number of Clients

The default number of clients the server can support is 65535, but you can set a lower limit using one of the mfcsmgr functions. The number you select is stored in the password file and will be used each time the server is started.

14.9.4 Enabling Server Override

The server can support override options for the server-name, protocol and machine-name. As the server does not use a configuration file, the override parameters are supplied using the mfcsmgr program.

This generates a short exchange between the client and the server which processes the selected function.

The mfcsmgr command line syntax for this is:

On Windows or OS/2 enter:

run mfcsmgr [-a] [-c nnnnn] [-d] [-i filename] [-m machine-name] 

            [-p protocol] [-s server-name] [-o m,machinename]

            [-o p,protocol] [-o r] [-o s,servername] [-t] [-v]

or on UNIX enter:

cobrun mfcsmgr [-a] [-c nnnnn] [-d] [-i filename] [-m machine-name] 

               [-p protocol] [-s server-name] [-o m,machinename] 

               [-o p,protocol] [-o r] [-o s,servername] [-t] [-v]

where:

All the above flags can be specified with a - or /, and are not case sensitive.

14.10 Advanced Topics

This section covers the following advanced topics:

• Creating audit trails.

• Overriding configuration file entries.

• Using the in-line configuration facility.

• Reduced data transfer facility.

• Server controlled file management facility.

14.10.1 Creating Audit Trails

The client/server binding allows you to create an audit trail of dates and times of clients connecting to servers. To enable this feature, simply set the 'useraudit=y' entry in your configuration file. This information is created in the system log file described in the section The System Error/Message Log.

14.10.2 Overriding Configuration File Entries

In the start-up process for each client, the client/server:

1. Reads the configuration file.

2. Searches the client/server binding for a file called mfcsovrd.cfg in the same location as the system log file. If the file is found, its contents will override any parameters previously set up using the configuration file.

   The format of the override file is the same as the standard configuration file, with the addition of the entry override-cntrl. This entry is used to indicate the subject of the override and can be:

   • A servername.

     When using a servername, any clients using that server will have their parameters modified by the contents of the override file.

   • A tagname.

     If the entry is set to tagname, only clients using the selected tagname will have their parameters changed.

The client override facility can be used, for example, if a server is unavailable and applications need to be run on another machine. You can change individual configuration files, but a single override file can be used to re-route any number of applications.

The override facility can also be used on the server, but in this case the server machine needs to be up and running. As before, either servernames or tagnames can be overridden.

An entry is added to the log file whenever an override file is detected and all parameters which are subject to the override process are logged.

The following example shows how the override facility can be used to re-route clients to another server:

[OVERRIDE-CNTRL]
OVERRIDE=SERVERNAME
[OLDSERVER]
SERVERNAME=NEWSERVER

In this example, the [override-cntrl] section specifies that the subject of the override is a servername (override=servername) and then, under the old servername ([oldserver]), the new servername (servername=newserver) is specified. This results in the following log file entries:

20/04/1997 11:01:02 Using Local File: mfcsovrd.cfg
Overriding Entries for Servername:OLDSERVER
servername=newserver
20/04/1997 11:01:02 Override Completed:

The following example shows how the override facility can be used to override the server being used by all those clients which are using a specified tag:

[OVERRIDE-CNTRL]
OVERRIDE=TAGNAME
[MF-CLISRV]
SERVERNAME=NEWSERV

In this example, the [override=cntrl] section specifies that the subject of the override is a tagname (override=tagname) and then, under the tagname ([mf-clisrv]), the parameter to be overridden (in this case the servername) is specified (servername=newserv). This results in the following log file entries:

20/04/1997 11:04:02 Using Local File: mfcsovrd.cfg
Overriding Entries for Tagname:MF-CLISRV
servername=newserver
20/04/1997 11:04:02 Override Completed:

14.10.3 Using the In-line Configuration Facility

One of the most powerful features of the client/server binding is the ability to control the communications requirements from configuration files. This does however mean that end users can affect the way an application runs by changing entries in these files. This may not be desirable. It is possible to provide all the parameters to an application in the client program. This means that the end user cannot alter the way an application behaves because it no longer uses a configuration file. Flexibility is maintained in that you still have no need to get into detailed communications code: you simply supply the required parameters within your client program.

The process is started by setting load-inlinecfg and completed by setting end-inline-cfg in your mfclisrv.cpy copyfile in your client program. Each parameter entry is loaded into the lnkerror-msg field and mfclient is called to process it. The parameters have to be supplied before the main processing loop is entered. See the example below.

WORKING-STORAGE SECTION.

01  ws-null          PIC X(4) COMP-X.
01  ws-scrnset-ver   PIC X(4) COMP-X.
01  ws-ret-stat      PIC X COMP-X VALUE 0.

COPY "mfclisrv.cpy".

01  dialog-system    PIC X(48). 

LINKAGE SECTION.

COPY "DS-CNTRL.V1". 
COPY "CUSTOMER.CPB".

PROCEDURE DIVISION.
 
Client-Control SECTION.

   SET load-inline-cfg TO TRUE
   MOVE "clierrprog=same" TO lnk-error-msg 
   CALL lnk-client USING lnk-param-block 
   
   MOVE "srverrprog=same" TO lnk-error-msg 
   CALL lnk-client USING lnk-param-block

   MOVE "servername=mainserv" TO lnk-error-msg 
   CALL lnk-client USING lnk-param-block
   
   SET end-inline-cfg TO TRUE

*  The main loop is repeated until the connection with *  the server ends 

   PERFORM UNTIL End-Connection

*  'lnk-client' holds the name 'mfclient'
*  The first time through we initialize the system and 
*  establish contact with the server.

      CALL lnk-client USING lnk-param-block

      EVALUATE TRUE
         WHEN start-connection

   ........ The rest of the program is standard from this
   ........... point onwards  ............

It is also possible to combine an external configuration file with the inline configuration facility. This is ideal because the end-user can modify the system to his own requirements, but the final control remains within the client program. The configuration file is processed first, followed by the inline entries. This means that any unwanted parameters supplied in the configuration file can be overridden by the inline entry. In this case the process is started by setting use-combined-cfg and completed as before by setting end-inline-cfg.

WORKING-STORAGE SECTION.

01  ws-null          PIC X(4) COMP-X.
01  ws-scrnset-ver   PIC X(4) COMP-X.
01  ws-ret-stat      PIC X COMP-X VALUE 0.

COPY "mfclisrv.cpy".

01  dialog-system    PIC X(48). 

LINKAGE SECTION.

COPY "DS-CNTRL.V1". 
COPY "CUSTOMER.CPB".

PROCEDURE DIVISION. 
Client-Control SECTION.

   SET use-combined-cfg TO TRUE
   CALL lnk-client USING lnk-param-block
   SET load-inline-cfg TO TRUE
   MOVE "servername=mainserv" TO lnk-error-msg 
   CALL lnk-client USING lnk-param-block
   SET end-inline-cfg TO TRUE

*  The main loop is repeated until the connection with *  the server ends 

   PERFORM UNTIL End-Connection

*  'lnk-client' holds the name 'mfclient'
*  The first time through we initialize the system and
*  establish contact with the server.

      CALL lnk-client USING lnk-param-block

      EVALUATE TRUE
         WHEN start-connection

   ....... The rest of the program is standard from this
   .......... point onwards  ............

14.10.4 Reduced Data Transfer Facility

Reduced Data Transfer (RDT) provides a way for you to control the amount of data being passed across the network and for you to limit this data to the absolute minimum required to achieve the desired result.

The client/server binding assigns a buffer large enough to hold the Data Blocks defined in the configuration file. This buffer is transferred back and forth whenever control is shifted between the client and server programs. This can impose a load on the network which some users may find unacceptable. Imagine you have a buffer of 24K which contains a 22K record area. If the file which holds these records has a 10 byte key, you can see that sending the key from client to server uses 24K when only 10 bytes are actually required. In reality, you need one or two bytes more than this, but it is much less than the size of the entire buffer.

RDT requires a control flag (use-rdt) and three parameters to be set in mfclisrv.cpy in your client program:

For example, consider an application which allows you to ADD, DELETE and LOAD customer details to and from an index file. The record key for the customer details is a customer code. The application also has a CLEAR option to clear all customer information from the interface. The application is the customer example program installed with this product. The code extract below is based on this example application, and we are using the user-data-block area to hold the record key which is six bytes long. The Data Block area (dblksize) used by the application to pass the customer record details between the client and the server is called customer-data-block. The data item customer-c-code is a 6-byte data item within customer-data-block and is used to store the record key.

On the client, the code would be similar to that shown below.

EVALUATE TRUE
    WHEN customer-load-flg-true

*  User has entered customer code and selected the "LOAD"
*  option on the interface to read and display the customer
*  details relating to that code.

    MOVE customer-c-code TO user-data-block
        SET use-rdt TO TRUE
        MOVE 1 TO lnk-usr-fcode
        MOVE 4 TO lnk-usr-retcode
        MOVE 6 TO lnk-data-length
    WHEN customer-del-flg-true

*  User has entered a customer code and selected the DELETE 
*  option to delete the customer record from the file.

    MOVE customer-c-code TO user-data-block
        SET use-rdt TO TRUE
        MOVE 2 TO lnk-usr-fcode
        MOVE 4 TO lnk-usr-retcode
        MOVE 6 TO lnk-data-length
        INITIALIZE customer-data-block
    WHEN customer-clr-flg-true

*  User has selected the CLEAR option to clear the current
*  customer details from the screen.

    SET use-rdt TO TRUE
        MOVE 0 TO lnk-usr-retcode
        INITIALIZE customer-data-block
        PERFORM Set-Up-For-Refresh-Screen
END-EVALUATE

The CLEAR option uses a NULL operation because clearing the record is done locally so there is no need to contact the server. Below is an extract from the server program showing the code required to process RDT. The client/server binding sets the flag "send-via-rdt" so you can check the values of lnk-usr-fcode. On the server, the code would be similar to that shown below.

WHEN send-via-rdt
    EVALUATE lnk-usr-fcode
        WHEN 1

*  For the LOAD function, the server program reads the customer
*  details from the data file, and sends the data back to the client
*  using the data area customer-data-block rather than using
*  the RDT facility. Unless the RDT flag is set, the client/server
*  bindings will always pass the complete data area (defined by
*  dblksize in the configuration file) between the client and the
*  server.

        MOVE user-data-block TO customer-c-code
            SET customer-load-flg-true TO TRUE
            PERFORM... .rest of program... .
        WHEN 2
            MOVE user-data-block TO customer-c-code
            SET customer-del-flg-true TO TRUE
            PERFORM... .rest of program... .
    END-EVALUATE

14.10.5 Server Controlled File Management Facility

One of the problems that accompanies any client/server solution, especially as the number of clients increases, is the management of client program updates and other changes.

The override facility (see the section Overriding Configuration File Entries) enables you to re-route client applications while server maintenance is carried out without having to change each client's configuration file entries. The override can be either local or remote, but installing and removing a local override file on each client can be time-consuming.

The mfcsmgr program enables you to install and delete override files on the client using the -i and -d options respectively. See the section Managing the Server. The install/delete is carried out as the client program exits.

In fact, the -i option of the mfcsmgr program enables you to install any type of file on the client system (in the client's local directory). This means that you can use it to install new screensets or program files, enabling updates to be distributed from a central point. For security reasons, the delete option has not been similarly enhanced: it will delete an override file only; that is, a file called mfcsovrd.cfg.

Files to be installed using the -i option must be located on the server. If the file is in the directory from which mfserver was started, you need only specify the filename. If it is anywhere else, you must supply a full pathname in such a way that the filename can be extracted from the path. For example, /u/live/update/newprog.int, d:\testprog.int and $LIVE/newtest.int are all valid, but $newfile is not.

No programming changes are required to use these functions. A message is displayed informing the client that a file is being transferred and the details are recorded in the system log file.

14.11 Running the Supplied Customer Example

See the file csbind.txt in the DialogSystem\demo\csbind directory for instructions on how to run the Dialog System client/server binding demonstration.

14.12 The System Error/Message Log

Both the client and server modules of the binding maintain a log of errors and messages. All entries are date- and time-stamped and are kept in a file called mfclisrv.log, which is written to the directory in which the programs were started or to the directory named in the MFLOGDIR environment variable. Check this log from time to time to ensure that your system is performing correctly.

14.13 Client/Server Binding Limitations

The client/server binding imposes very few limitations, but you should be aware of the following issues:

• You can run the client/server binding modules in .int or .gnt format on Windows 95, Windows NT and UNIX platforms. In addition, on UNIX platforms, the client/server binding modules can be linked with a user-written application program to create an executable object.

• The number of clients that can be supported is not limited by the client/server binding but may be limited by the capabilities of the server, by the network protocol, or by the performance requirements of your end users. On UNIX, for example, the limit is set by the number of sub-processes that can be spawned by mfserver. When a user logs onto a UNIX machine, he is assigned a unique process-id which can support a limited number of sub-processes. When clients connect via the client/server binding, they all become sub-processes of the base server. Of course, you can get around this limitation by altering the number of sub-processes permitted, or by running multiple base servers. If your UNIX machine is configured to support many hundreds of direct login users, the client/server binding running on the same machine should support the same number of clients once the sub-process limit issue has been resolved.

• The client/server binding has no recovery facilities: if the network goes down, data will be lost. Both ends of the connection will be aware of the failure and the information will be logged but that is all. The same is true of any RTS errors that cause termination of the user programs at either end of a connection. The client/server binding does not provide anything more than the standard RTS in this regard.

Using Panels V2

Advanced Topics