Configuration


Introduction
Client Configuration
[ClientConfig]DefaultServer=
[ClientConfig]DefaultExtension=
[ServerConfig]Port=
[RemotePrograms]
Server Configuration
All Servers
[ServerConfig]LogActivity=
[ServerConfig]ProgramPaths=
[ServerConfig]WorkingDir=
[ServerConfig]Port=
Windows Servers
[ServerConfig]StartupCommand=
[ServerConfig]CobolType=
Unix Servers
[ServerConfig]LogFileName=
[ServerConfig]ProgramCase=

Introduction

Since Cobol-RPC involves little or no coding, configuration of the client and server are the primary issues in its use. Configuration information for both the client and server are stored in the COBOLRPC.INI file. Configuration information can be changed by editing this file. On Windows servers, server configuration can also be modified by using the Configure option in the Cobol-RPC Server program.

Client Configuration

The Cobol-RPC client must be configured to ensure that remote program calls can be executed properly. To do this the client configuration must include the following information:

1. A list of programs that should be executed remotely

2. The name or address of the server each program resides on

3. The port number used to connect to servers

This information is contained in the COBOLRPC.INI file. This file is a standard Windows configuration file containing the following sections:

Section Name Contents
ClientConfig Configuration information that applies only to the client.
ServerConfig Server configuration information, some of which may be relevant to the client.
RemotePrograms A list of programs that are to be executed remotely.

Just in case you have not worked with INI files, here's a quick explanation.

INI files are ASCII text files. They can be edited directly with a text editor. They also are maintained automatically by many Windows programs such as the Cobol-RPC Server for Windows.

INI files are organized into sections, each section beginning with a header delimited by []. The COBOLRPC.INI file contains the following sections.

[ClientConfig]
[ServerConfig]
[RemotePrograms]

Each section can contain one or more entries that specify configuration values. These generally consist of a name and a value with an "=" in between. The COBOLRPC.INI contains a line like this in the [ServerConfig] section:

Port=5000

Other types of entries are also possible.

The following sections describe each of the client configuration options in detail.

[ClientConfig]
DefaultServer=

The DefaultServer entry in the [ClientConfig] section of the COBOLRPC.INI file specifies the server to be used for all remote programs that do not specify a server. The entry could look like this:

[ClientConfig]
DefaultServer=127.0.0.1

The value to the right of the equal sign is the address or name of the default server. Specifying a DefaultServer value eliminates the need to specify a server name or address for every program listed in the RemotePrograms section of the COBOLRPC.INI file.

In a simple client/server approach, the client may call many programs located on one server. By eliminating the need to specify the server name or address for each program it becomes easier to reconfigure the system to use a different server.

Note that if a server name or address is specified for a remote program it overrides the DefaultServer value. The default server is only used for programs that do not specify a server.

[ClientConfig]
DefaultExtension=

The DefaultExtension entry in the [ClientConfig] section of the COBOLRPC.INI file specifies the default extension to be used for CobolCobol programs. The entry could look like this:

[ClientConfig]
DefaultExtension=COB

The value to the right of the equal sign is the default extension to be used for Cobol programs. Specifying a DefaultExtension value eliminates the need to specify an extension for every program listed in the [RemotePrograms] section of the COBOLRPC.INI file. When Cobol-RPC loads the program names from the [RemotePrograms] section it will append the extension specified by DefaultExtension to any program names without an extension.

If the REMOTEPROGRAM function is used by a client to call a server program and no extension is included in the program name, the default extension will be added to the program name.

[ServerConfig]
Port=

The Port entry in the [ServerConfig] section of the COBOLRPC.INI file specifies the port number to be used when connecting to a server. The entry could look like this:

[ServerConfig]
Port=5000

The value to the right of the equal sign is the port number to use when connecting to a server.

Port numbers are logical values, not physical. Each service provided by a server has a unique port number associated with it. The Port value specified in the COBOLRPC.INI file on the client must match the Port value specified for any server to which it will connect.

[RemotePrograms]

The [RemotePrograms] section of the COBOLRPC.INI file specifies the names of programs that should be executed remotely. The entries can look like any of these:

[RemotePrograms]
PROGRAM1.COB=
PROGRAM2=
PROGRAM3=127.0.0.1
PROGRAM4=myserver

The first item in each entry is the name of the program to be executed remotely. The optional second item on the line is the name or address of the server the program should be executed on.

The first line, PROGRAM1.COB=, specifies the complete name of the program to be executed. Since no server is specified the default server will be used for this program.

The second example, PROGRAM2=, specifies a program name with no extension. If the COBOLRPC.INI file contains a DefaultExtension entry, the specified extension will be added to PROGRAM2 to form the complete program name. Again, since no server is specified the default server will be used for this program.

The third example, PROGRAM3=127.0.0.1, specifies a server address to be used for the program.

The fourth example, PROGRAM4=myserver, specifies a server name to be used for the program. The network must provide a name service so that Cobol-RPC can resolve this name to an address.

Server Configuration

The Cobol-RPC Cobol server must be configured to ensure that connections can be made by clients and the requested programs can be found and executed. To do this, the server configuration must include the following information:

All Servers

A flag indicating whether or not an activity log should be kept
The locations to search for Cobol programs
The working directory to execute programs from
The port number used to connect to clients

Windows Servers

The command to be used when starting Cobol runtimes
The type of Cobol being used

Unix Servers

The name of the activity log file to write to
The case to use for called program names

This information is contained in the COBOLRPC.INI file. This file is a standard Windows configuration file containing several sections.

A windows format configuration file is also used on Unix systems for consistency and simplicity. On Unix systems the full path for this file is /etc/cobolrpc.ini.

If a server does not make any remote program calls to other servers then the only section that is needed is the [ServerConfig] section. If a server does make remote program calls then the [ClientConfig] and [RemotePrograms] sections are also needed. The following sections describe each of the server configuration options in detail.

All Servers

[ServerConfig]
LogActivity=

The LogActivity entry in the [ServerConfig] section of the COBOLRPC.INI file determines whether or not a log of activity is kept by the server. The entry could look like this:

[ServerConfig]
LogActivity=1

If the value to the right of the equal sign is a 1 the log is created. If the value is 0 or blank, no log is created.

The activity log keeps track of when the server is started and stopped, what portPort is used, and what clients connect to and disconnect from the server. Each activity is accompanied by a date and time stamp. Clients are identified by their network address.

Here's a sample of what the activity log looks like:


Server started at 04:44:58 PM Thursday, February 29, 1996 at port number 5000

Initialization complete -- waiting for remote program calls

Remote program call received at 04:45:10 PM Thursday, February 29, 1996

Starting new runtime for 167.142.104.244 using command:
C:\CobolRPC\wruncbls.exe C:\CobolRPC\cobolrpc.cob 124 C:\CobolRPC\
New runtime instance is 83

Remote program call received at 04:47:28 PM Thursday, February 29, 1996

Starting new runtime for 167.142.104.245 using command:
C:\CobolRPC\wruncbls.exe C:\CobolRPC\cobolrpc.cob 88 C:\CobolRPC\
New runtime instance is 77

Instance 77 exited normally at 04:47:56 PM Thursday, February 29, 1996

Instance 83 exited normally at 04:48:07 PM Thursday, February 29, 1996


Under Windows the activity log is displayed in the server window and can be saved to disk as desired. Under Unix the activity log is written directly to the file indicated by the LogFileNameEntry in the /etc/cobolrpc.ini file.

[ServerConfig]
ProgramPaths=

The ProgramPaths entry in the [ServerConfig] section of the COBOLRPC.INI file specifies one or more locations for the Cobol programs that the server will execute. The entry looks something like this:

[ServerConfig]
ProgramPaths=c:\cobolprg;c:\moreprgs

The value to the right of the equal sign is a list of full or partial paths separated by semicolons. The server will look for remote programs in these directories.

The directories specified in ProgramPaths are used only for the server programs called by clients. If server programs make additional Cobol calls the location of the programs will be controlled by the working directory and the normal behavior of the Cobol runtime. Cobol environment variables or the PATH variable can be used to ensure that these programs are found.

The ProgramPaths entry is not used by all implementations. Some implementations use the standard Cobol CALL search logic for remote program calls. Please see the release notes for details on your implementation.

[ServerConfig]
WorkingDir=

The WorkingDir entry in the [ServerConfig] section of the COBOLRPC.INI file specifies the working directory from which server programs should be executed. The entry looks something like this:

[ServerConfig]
WorkingDir=c:\home

The value to the right of the equal sign is the working directory that should be used for executing server programs. The working directory has implications for locating both Cobol programs and data files and should be carefully established.

Windows Default

If no value is specified for WorkingDir, the working directory will be the working directory specified in the icon for the Cobol-RPC Server.

Unix Default

If no value is specified for WorkingDir, the working directory will be the home directory of the username listed in the inetd.conf file entry for Cobol-RPC.

[ServerConfig]
Port=

The Port entry in the [ServerConfig] section of the COBOLRPC.INI file specifies the port number the server will use to connect to clients. The entry could look like this:

[ServerConfig]
Port=5000

The value to the right of the equal sign is the port number to use when connecting to clients.

Port numbers are logical values, not physical. Each service provided by a server has a unique port number associated with it. The Port value specified in the COBOLRPC.INI for the server must match the Port value specified for any clients that will connect to it.

Windows Servers

[ServerConfig]
StartupCommand=

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

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.

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 suggested contents of this configuration option are included in the release notes for your implementation.

[ServerConfig]
CobolType=

The CobolType entry in the [ServerConfig] section of the COBOLRPC.INI file specifies the type of Cobol being used on the server. The entry could look like this:

[ServerConfig]
CobolType=acucobol

The different versions of Cobol have different techniques for passing command line parameters. If this option is not configured for the Cobol being used on the server, the server program will not execute properly.

Value Effect
acucobol Acucobol compiler
rmcobol RM/Cobol compiler
mfcobol Micro Focus compiler

Unix Servers

[ServerConfig]
LogFileName=

The LogFileName entry in the [ServerConfig] section of the /etc/cobolrpc.ini file indicates the file to which Cobol-RPC should write a record of activity. The entry could look something like this:

[ServerConfig]
LogFileName=/cobolrpc/cobolrpc.log

The file will be created if it does not exist. If the file exists, activity will be appended to the end of the file.

This option has an effect only under Unix. Windows servers display the activity log in the server window and allow the log to be saved to a file.

[ServerConfig]
ProgramCase=

The ProgramCase entry in the [ServerConfig] section of the /etc/cobolrpc.ini file indicates what case translation should be applied to the names of remote programs when they are called. The entry could look like this:

[ServerConfig]
ProgramCase=1

Since some client operating systems are not case sensitive and UNIX is, this option gives the ability to map remote program names to upper or lower case on a Unix server. The following options are available:

Value Effect
0 No conversion
1 Names converted to upper case
2 Names converted to lower case

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

Copyright 1996 by England Technical Services, Inc.