MicroFocus Release Notes

MicroFocus Windows Client

MicroFocus Windows Server

MicroFocus SCO UNIX Server

MicroFocus Visual Basic Client

MicroFocus Windows Client

Version 1.1

Installation

Windows 3.1

Follow these steps to install Cobol-RPC on a client under Windows 3.1 or Windows NT:

• Insert the appropriate distribution disk into a floppy disk drive (A:drive).
• Open either the Program Manager or the File Manager.
• If you opened the Program Manager, choose Run from the File menu and type the following command line:

  A:\SETUP

• If you opened the File Manager, open the drive containing the disk and double-click on the file SETUP.EXE.
• Follow the installation prompts that appear.

Windows 95

Use one of the following methods to install Cobol-RPC on a client under Windows 95:

• Insert the appropriate distribution disk into a floppy disk drive. Click on the Add/Remove Programs icon in the Control Panel window. Follow the installation prompts that appear.
• From a DOS prompt, type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Start menu, choose Run and type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Windows Explorer, open the drive containing the disk and double-click on the file SETUP.EXE.

When installation of the client software is complete, a Cobol-RPC folder will be created which contains the following icons:

The file readmecl.txt lists and describes each of the files that are installed.

Running the Sample Programs

A sample client program named CLIENT.CBL is installed with the client software. The source and executable files for three sample server programs are installed with the Cobol-RPC server software. These programs are called SERVER1.CBL, SERVER2.CBL, and SERVER3.CBL. These programs demonstrate how Cobol-RPC executes remote program calls. The source code for these programs is also installed.

To execute the sample program follow these steps:

1. Make sure TCP/IP is installed and configured as described above.
2. Make sure the IP address of the server is contained in the DefaultServer item of the ClientConfig section of the COBOLRPC.INI file on the client.
3. Follow the instructions for preparing the server in the Cobol-RPC server release notes.
4. Double click the Sample Client icon in the Cobol-RPC folder on the client to start the sample program.
5. Follow the on-screen prompts.

Redirected CALL Statements

The MicroFocus version of Cobol-RPC supports redirected CALL statements as described in the Cobol-RPC User's Guide. This means ordinary CALL statements can be configured to function as remote program calls. This usage is demonstrated in the sample program CLIENT.CBL.

There are some special techniques that must be employed with MicroFocus COBOL to support this. These techniques are described here.

Compiler Directives

The MicroFocus compiler supports a compiler directive called CALLMAP. This directive causes all CALL statements to be routed through a specified CALL handler. Cobol-RPC uses this feature to intercept CALL's and determine whether or not they should be executed remotely. The CALLMAP directive must be added to the compilation of any program that will make remote program calls with redirected CALL statements.

The CALLMAP directive is an Early Release feature. This means that the EARLY-RELEASE directive must also be used.

The CALLMAP and EARLY-RELEASE directives can be specified by placing the following lines of code at the start of your program. Note that the $ character must appear in column 7 of the source.

$SET EARLY-RELEASE
$set CALLMAP "RPCCTRL"

RPCCTRL is the Cobol-RPC program that determines whether or not a call is to be executed remotely. When using redirected CALL statements this program must be available to your application by linking into your .EXE program or including the .INT or .GNT version of the code with your application.

Additional Configuration Information

Some additional configuration information is also required when using redirected CALL statements with MicroFocus COBOL. The MicroFocus COBOL runtime system does not supply the size of parameters passed in a CALL statement, so this information must be included in the COBOLRPC.INI file for each program that is going to be called with a redirected CALL statement. Programs called with the REMOTEPROGRAM function do not need to specify this information as it is included in the parameter block passed with the call.

The [RemotePrograms] section of the COBOLRPC.INI file normally contains entries such as these:

SAMPLE1.INT=
SAMPLE2.INT=SERVERNAME
SAMPLE3.INT=167.132.123.146

In the first example the program SAMPLE1.INT is to be called on the default server. In the second example, SAMPLE2.INT is to be called on the server named SERVERNAME. In the third example, SAMPLE3.INT is to be called on the server with the address 167.132.123.146.

When using redirected CALL statements with MicroFocus COBOL the sizes of the parameters passed to the program must be included on the line with the program name. The parameter sizes are separated from the server name, and from each other, by a comma. A size must be specified for each parameter that will be passed. If no parameters are passed to a program then no sizes are needed.

If the program SAMPLE1.INT is passed three parameters the entry should look like this:

SAMPLE1.INT=,40,120,350

The first parameter is 40 bytes, the second 120, and the third 350. Since there is no server name specified a comma is placed immediately after the equals sign.

If the program SAMPLE2.INT is passed the same three parameters the entry should look like this:

SAMPLE2.INT=SERVERNAME,40,120,350

If the program SAMPLE3.INT is passed no parameters the entry should be unchanged:

SAMPLE3.INT=167.132.123.146

REMOTEPROGRAM Function

MicroFocus clients can not use the simplified version of the REMOTEPROGRAM function as described in Chapter 4 of the Cobol-RPC User's Guide.

Non-Portable Data Types

The following data types may not be portable between all types of clients and servers. No data items of these types should be used in making remote program calls.

COMP-1
COMP-2
POINTER
PROCEDURE-POINTER

Special Programming Considerations

Linking into an .EXE file

If you decide to link your application into an .EXE file you must include the following lines in your .DEF file.

IMPORTS MFRPCCL.REMOTEPROGRAM
IMPORTS MFRPCCL.SHUTDOWNRPC

They include references to import Cobol-RPC routines that are contained in MFRPCCL.DLL.

Using Cobol-RPC functions

Since the MicroFocus version of Cobol-RPC supports redirected CALL statements, it is possible to use Cobol-RPC without writing any special code. However, if you decide to explicitly use the REMOTEPROGRAM or SHUTDOWNRPC functions, you will have to follow these guidelines. Note that these guidelines will allow your code to execute as an .INT, .GNT, or .EXE file.

1. The following code should be included in the ENVIRONMENT DIVISION. These lines define the call convention used to call Cobol-RPC functions.

   SPECIAL-NAMES.
CALL-CONVENTION 8 IS RPC.

2. The following code should be included in the WORKING-STORAGE SECTION. It declares a data item used to load MFRPCCL.DLL.

   RPC-PRC USAGE PROCEDURE-POINTER.

3. The following statement must be executed in the Procedure Division before any calls to Cobol-RPC functions are made. This code will cause the Cobol-RPC .DLL to be loaded and will let the runtime system resolve calls to Cobol-RPCfunctions.

   SET RPC-PRC TO ENTRY "MFRPCCL".

4. Calls to the REMOTEPROGRAM or SHUTDOWNRPC functions should include the CALL-CONVENTION value immediately after the CALL verb as follows:

   CALL RPC "REMOTEPROGRAM" USING RPC-CONTROL ...
CALL RPC "SHUTDOWNRPC".

Remember, all these considerations can be ignored if you are only using redirected call statements.

MicroFocus Windows Server

Version 1.1

Installation

Windows 3.1

Follow these steps to install Cobol-RPC on a server under Windows 3.1:

• Insert the appropriate distribution disk into a floppy disk drive (A:drive).
• Open either the Program Manager or the File Manager.
• If you opened the Program Manager, choose Run from the File menu and type the following command line:

  A:\SETUP

• If you opened the File Manager, open the drive containing the disk and double-click on the file SETUP.EXE.
• Follow the installation prompts that appear.

Windows 95

Use one of the following methods to install Cobol-RPC on a server under Windows 95:

• Insert the appropriate distribution disk into a floppy disk drive. Click on the Add/Remove Programs icon in the Control Panel window. Follow the installation prompts that appear.
• From a DOS prompt, type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Start menu, choose Run and type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Windows Explorer, open the drive containing the disk and double-click on the file SETUP.EXE.

When installation of the server software is complete, a Cobol-RPC folder will be created which contains the following icons:

The file readmesv.txt lists and describes each of the files that are installed.

Running the Sample Programs

The source and executable files for three server programs are installed with the Cobol-RPC server software. These programs are named SERVER1.CBL, SERVER2.CBL, and SERVER3.CBL. These programs demonstrate how Cobol-RPC executes remote program calls

The sample programs are executed from the client, not the server. Before the client can execute these programs perform the following steps.

1. Make sure TCP/IP is installed and configured as described above.
2. Make sure the IP address of the server is contained in the DefaultServer item of the ClientConfig section of the COBOLRPC.INI file on the client.
3. Follow the instructions in the client release notes to run the sample programs.

[ServerConfig]
StartupCommand=

The StartupCommand entry in the [ServerConfig] section of the COBOLRPC.INI file specifies the command that will be used to start the COBOL runtimes that respond to service requests. Everything to the right of the equal sign is the beginning of the command which will be used for handling service requests. The server will append information to this command specific to the request.

The first time a client connects to a server, the server will use this command to start a COBOL runtime on the server. This runtime will remain dedicated to the client until the client terminates, and will execute all remote programs called by the client.

In practice, complete path names should be included for all files. This makes them insensitive to the working directory the server is initiated from. A configuration file and other COBOL runtime parameters can be included in this entry. The entry should look like this:

[ServerConfig]
StartupCommand=runw rpcinit.int

runw is the MicroFocus runtime startup program. rpcinit.int is a small Cobol program that initializes the runtime to work with the client.

REMOTEPROGRAM Function

MicroFocus clients can not use the simplified version of the REMOTEPROGRAM function as described in Chapter 4 of the Cobol-RPC User's Guide.

Redirected CALL Statements

The MicroFocus version of Cobol-RPC supports redirected CALL statements as described in the Cobol-RPC User's Guide. This means ordinary CALL statements can be configured to function as remote program calls. This usage is demonstrated in the sample program CLIENT.CBL.

There are some special techniques that must be employed with MicroFocus COBOL to support this. These techniques are described here.

Compiler Directives

The MicroFocus compiler supports a compiler directive called CALLMAP. This directive causes all CALL statements to be routed through a specified CALL handler. Cobol-RPC uses this feature to intercept CALL's and determine whether or not they should be executed remotely. The CALLMAP directive must be added to the compilation of any program that will make remote program calls with redirected CALL statements.

The CALLMAP directive is an Early Release feature. This means that the EARLY-RELEASE directive must also be used.

The CALLMAP and EARLY-RELEASE directives can be specified by placing the following lines of code at the start of your program. Note that the $ character must appear in column 7 of the source.

$SET EARLY-RELEASE
$set CALLMAP "RPCCTRL"

RPCCTRL is the Cobol-RPC program that determines whether or not a call is to be executed remotely. When using redirected CALL statements this program must be available to your application by linking into your .EXE program or including the .INT or .GNT version of the code with your application.

Additional Configuration Information

Some additional configuration information is also required when using redirected CALL statements with MicroFocus COBOL. The MicroFocus COBOL runtime system does not supply the size of parameters passed in a CALL statement, so this information must be included in the COBOLRPC.INI file for each program that is going to be called with a redirected CALL statement. Programs called with the REMOTEPROGRAM function do not need to specify this information as it is included in the parameter block passed with the call.

The [RemotePrograms] section of the COBOLRPC.INI file normally contains entries such as these:

SAMPLE1.INT=
SAMPLE2.INT=SERVERNAME
SAMPLE3.INT=167.132.123.146

In the first example the program SAMPLE1.INT is to be called on the default server. In the second example, SAMPLE2.INT is to be called on the server named SERVERNAME. In the third example, SAMPLE3.INT is to be called on the server with the address 167.132.123.146.

When using redirected CALL statements with MicroFocus COBOL the sizes of the parameters passed to the program must be included on the line with the program name. The parameter sizes are separated from the server name, and from each other, by a comma. A size must be specified for each parameter that will be passed. If no parameters are passed to a program then no sizes are needed.

If the program SAMPLE1.INT is passed three parameters the entry should look like this:

SAMPLE1.INT=,40,120,350

The first parameter is 40 bytes, the second 120, and the third 350. Since there is no server name specified a comma is placed immediately after the equals sign.

If the program SAMPLE2.INT is passed the same three parameters the entry should look like this:

SAMPLE2.INT=SERVERNAME,40,120,350

If the program SAMPLE3.INT is passed no parameters the entry should be unchanged:

SAMPLE3.INT=167.132.123.146

Non-Portable Data Types

The following data types may not be portable between all types of clients and servers. No data items of these types should be passed when making remote program calls.

COMP-1
COMP-2
POINTER
PROCEDURE-POINTER

Debugging

To debug a server program, change the StartupCommand to execute the program using the animator instead of the normal runtime. The command should look like this, but with complete path names:

animatew rpcinit.int

When the server program starts the animator may be used normally. Note that if multiple users connect to the system each will get a separate animator session.

Supressing the Termination Prompt

By default, the MicroFocus runtime system displays a message box with a termination message when the runtime terminates. This message box requires the operator to click the button to complete runtime termination.

This behavior is not compatible with the unattended operation of a server, so when the server software installs it adds the following entries to the win.ini file:

[RPCINIT]
COBTERMPROMPT=OFF

[RUNW]

COBTERMPROMPT=OFF

This entry will suppress the display of the termination message and allow proper unattended operation of the server.

Special Programming Considerations

Linking into an .EXE file

If you decide to link your application into an .EXE file you must include the following lines in your .DEF file.

IMPORTS MFRPCSV.REMOTEPROGRAM
IMPORTS MFRPCSV.SHUTDOWNRPC
IMPORTS MFRPCSV.GETREQUEST
IMPORTS MFRPCSV.RETURNDATATOCLIENT
IMPORTS MFRPCSV.STARTSERVER

They include references to import Cobol-RPC routines that are contained in MFRPCSV.DLL.

Using Cobol-RPC functions

Since the MicroFocus version of Cobol-RPC supports redirected CALL statements, it is possible to use Cobol-RPC without writing any special code. However, if you decide to explicitly use the REMOTEPROGRAM or SHUTDOWNRPC functions, you will have to follow these guidelines. Note that these guidelines will allow your code to execute as an .INT, .GNT, or .EXE file.

1. The following code should be included in the ENVIRONMENT DIVISION. These lines define the call convention used to call Cobol-RPCfunctions.

   SPECIAL-NAMES.
CALL-CONVENTION 8 IS RPC.

2. Calls to the REMOTEPROGRAM or SHUTDOWNRPC functions should include the CALL-CONVENTION value immediately after the CALL verb as follows:

   CALL RPC "REMOTEPROGRAM" USING RPC-CONTROL ...

   CALL RPC "SHUTDOWNRPC".

Remember, all these considerations can be ignored if you are only using redirected call statements

MicroFocus SCO Unix Server

Version 1.1

Installation

Installing Files

To install Cobol-RPC on a server computer under Unix:

• Create the directory into which you want to install Cobol-RPC
• Change the working directory to that directory
• Insert the distribution disk into the floppy disk drive. Type the install command printed on the diskette label
• After all the files have been extracted from the floppy, type the following command:

  ./rpcinstall

The file readmesv.txt lists and describes each of the files that are installed.

Relinking the COBOL runtime

After installing the Cobol-RPC software, it must be linked with the Cobol runtime. The process for doing this is quite straightforward. Just follow these steps:

• Change the working directory to the Cobol-RPC directory
• Rebuild the MicroFocus runtime with the following command:

  mkrts common.o server.o unixwin.o mfserver.o

• Set the execute permissions on rts32 with the following command:

  chmod 111 rts32

Running the Sample Programs

The source and executable file for three sample server programs are installed with the Cobol-RPC server software. These programs are called SERVER1.CBL, SERVER2.CBL, and SERVER3.CBL. These programs demonstrate how Cobol-RPC executes remote program calls. The sample programs are run from the client not the server, so follow the instructions in the client release notes to execute these programs.

Starting the Runtime from the Command Line

In order to see the effect of the DISPLAY statement or use any ACCEPT statements in server programs the runtime must be started from the command line as follows:

/cobolrpc/rpcdirect

After typing this command and pressing RETURN the terminal will freeze until a client connects. Then the remote program called by the client will be executed and the display will be updated.

REMOTEPROGRAM Function

MicroFocus clients can not use the simplified version of the REMOTEPROGRAM function as described in Chapter 4 of the Cobol-RPC User's Guide.

Redirected CALL Statements

The MicroFocus version of Cobol-RPC supports redirected CALL statements as described in the Cobol-RPC User's Guide. This means ordinary CALL statements can be configured to function as remote program calls. This usage is demonstrated in the sample program CLIENT.CBL.

There are some special techniques that must be employed with MicroFocus COBOL to support this. These techniques are described here.

Compiler Directives

The MicroFocus compiler supports a compiler directive called CALLMAP. This directive causes all CALL statements to be routed through a specified CALL handler. Cobol-RPC uses this feature to intercept CALL's and determine whether or not they should be executed remotely. The CALLMAP directive must be added to the compilation of any program that will make remote program calls with redirected CALL statements.

The CALLMAP directive is an Early Release feature. This means that the EARLY-RELEASE directive must also be used.

The CALLMAP and EARLY-RELEASE directives can be specified by placing the following lines of code at the start of your program. Note that the $ character must appear in column 7 of the source.

$SET EARLY-RELEASE
$set CALLMAP "RPCCTRL"

RPCCTRL is the Cobol-RPC program that determines whether or not a call is to be executed remotely. When using redirected CALL statements this program must be available to your application by linking into your .EXE program or including the .INT or .GNT version of the code with your application.

Additional Configuration Information

Some additional configuration information is also required when using redirected CALL statements with MicroFocus COBOL. The MicroFocus COBOL runtime system does not supply the size of parameters passed in a CALL statement, so this information must be included in the COBOLRPC.INI file for each program that is going to be called with a redirected CALL statement. Programs called with the REMOTEPROGRAM function do not need to specify this information as it is included in the parameter block passed with the call.

The [RemotePrograms] section of the COBOLRPC.INI file normally contains entries such as these:

SAMPLE1.INT=
SAMPLE2.INT=SERVERNAME
SAMPLE3.INT=167.132.123.146

In the first example the program SAMPLE1.INT is to be called on the default server. In the second example, SAMPLE2.INT is to be called on the server named SERVERNAME. In the third example, SAMPLE3.INT is to be called on the server with the address 167.132.123.146.

When using redirected CALL statements with MicroFocus COBOL the sizes of the parameters passed to the program must be included on the line with the program name. The parameter sizes are separated from the server name, and from each other, by a comma. A size must be specified for each parameter that will be passed. If no parameters are passed to a program then no sizes are needed.

If the program SAMPLE1.INT is passed three parameters the entry should look like this:

SAMPLE1.INT=,40,120,350

The first parameter is 40 bytes, the second 120, and the third 350. Since there is no server name specified a comma is placed immediately after the equals sign.

If the program SAMPLE2.INT is passed the same three parameters the entry should look like this:

SAMPLE2.INT=SERVERNAME,40,120,350

If the program SAMPLE3.INT is passed no parameters the entry should be unchanged:

SAMPLE3.INT=167.132.123.146

Non-Portable Data Types

The following data types may not be portable between all types of clients and servers. No data items of these types should be passed when making remote program calls.

COMP-1
COMP-2
POINTER
PROCEDURE-POINTER

MicroFocus Visual Basic Client

Version 1.1

Installation

Windows 3.1

Follow these steps to install Cobol-RPC on a client under Windows 3.1:

• Insert the appropriate distribution disk into a floppy disk drive (A:drive).
• Open either the Program Manager or the File Manager.
• If you opened the Program Manager, choose Run from the File menu and type the following command line:

  A:\SETUP

• If you opened the File Manager, open the drive containing the disk and double-click on the file SETUP.EXE.
• Follow the installation prompts that appear.

Windows 95

Use one of the following methods to install Cobol-RPC on a client under Windows 95:

• Insert the appropriate distribution disk into a floppy disk drive. Click on the Add/Remove Programs icon in the Control Panel window. Follow the installation prompts that appear.
• From a DOS prompt, type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Start menu, choose Run and type the line shown below, assuming that the disk is in the A:drive:

  A:\SETUP

• From the Windows Explorer, open the drive containing the disk and double-click on the file SETUP.EXE.

When installation of the client software is complete, a Cobol-RPC folder will be created which contains the following icons:

The file readmevb.txt lists and describes each of the files that are installed.

Components

There are two components whose names are unique to this version of Cobol-RPC. The first is the Visual Basic module that contains the Cobol-RPC functions and declarations. It is called MFCBRPC.BAS and is installed in the Cobol-RPC directory. The other is the DLL that interfaces between Visual Basic and Cobol. It is called MFRPCVB.DLL and is installed in the Windows directory.

Running the Sample Programs

A sample project vbclient is installed in the Cobol-RPC directory. It includes the source and executable files for a sample program. This sample project calls sample programs installed with the server version of Cobol-RPC. The server version of Cobol-RPC must be installed before the project is executed.

To execute the sample project follow these steps:

1. Make sure TCP/IP is installed and configured.
2. Make sure the IP address of the server is contained in the DefaultServer entry of the ClientConfig section of the COBOLRPC.INI file on the client.
3. Follow the instructions for preparing the server in the Cobol-RPC server release notes.
4. Double click the Visual Basic Sample Client icon in the Cobol-RPC folder on the client to start the sample program.
5. Follow the on-screen prompts.

Home | About | Products | Contact
Distributors | Library | Register

Copyright 1996 by England Technical Services, Inc.