Cobol-RPC adds a new dimension to Cobol programming. You can choose where your programs should execute, on the client or a server. While this flexibility requires little or no additional coding, client and server programs have different purposes and these should be considered in determining how to redeploy an existing application or how to create a new one.
When a server program is called by a client it will usually be passed data to operate on. With Cobol-RPC the server program receives that data in the most natural location possible, the Linkage Section.
A server program should declare parameters passed by the calling program in the Linkage Section just as if the server program were being called through a normal CALL statement.
Cobol-RPC lets client programs call remote programs as if they were local. It is important to remember that these programs do execute on the server. When a client program opens a file it opens that file on the client, since that is where the client program is running. When a server program opens a file it opens that file on the server, since that is where the server program is running. Similarly, if a client program executes a system call or changes the working directory it effects the client system. If a server program executes a system call or changes the working directory it effects the server system.
The ACCEPT statement, as a general rule, should not be used in server programs. Server programs are designed to run as invisible "services" that should not require user interaction. You do not want your server program to pause and require user input since it would halt processing and freeze the client program.
Let's take the example of a report program. Most report programs use ACCEPT to enter report parameters, then print the report. If you want to move this type of program to a client/server architecture, you should split the program into two programs. The first should allow entry of the parameters, then call the second and pass it the parameters. The second program creates the report. The first program becomes a client program, the second a server program. The client program has the ACCEPT, the server program does not.
However, in some circumstances you may want to place an ACCEPT statement in a server program during development for debugging purposes. This can be done under the following circumstances.
Under Windows, if the Cobol runtime is configured to display the Cobol window created for each runtime, the ACCEPT statement may be used. When the ACCEPT statement is encountered the server program will stop and wait for user input in its window.
Under Unix, the server Cobol runtime must be started from the command line, not by inetd, in order to use ACCEPT statements. See your release notes for details on starting the server runtime from the command line.
The DISPLAY statement, as a general rule, should not be used in server programs. Server programs are designed to run as invisible "services" and have no need to display information. There is no sense in requiring the server computer to display this information since it is just extra processing overhead.
However, placing DISPLAY statements in server programs will not cause any problems, and may be desirable for debugging purposes.
Under Windows, DISPLAY statements will update the window created for the server runtime. Depending on the Cobol configuration settings this window may or may not be visible.
Under UNIX, DISPLAY statements will have no effect if the runtime was started by inetd. When the Cobol runtime is started by inetd it is not attached to a tty device and cannot display information. However, if the runtime is started from the command line, as described in the release notes, the runtime is attached to a tty device and the DISPLAY statement will update the terminal.
Server programs can call other programs located on the server by using the standard Cobol CALL statement. These calls are not effected in any way by Cobol-RPC.
Server programs can also function as clients and call remote programs located on other servers. The programs must be listed in the [RemotePrograms] section of the cobolrpc.ini file. The calls to other servers are made just the way all clients make them, with the REMOTEPROGRAM function or through a redirected CALL statement.
The difference between a Cobol-RPC client program and a traditional Cobol program is that Cobol-RPC clients have to call remote programs located on the server. Client programs are not restricted in any way.
So how does a client program call a remote program? There are two ways, one that is supported on all implementations, and another that is only available on certain implementations.
Because of the flexibility of some Cobol runtime systems, Cobol-RPC can actually cause standard Cobol CALL statements to function as remote program calls. Cobol-RPC describes this approach as a redirected CALL statement.
Let's look at an example.
In standard Cobol programming, if a Cobol program needs to call another Cobol program called SAMPLE2, it uses the following statement:
CALL "SAMPLE2" USING ...
This statement causes the Cobol runtime system to load and execute SAMPLE2.
On some implementations Cobol-RPC can intercept this CALL statement before the runtime system executes it, and execute it instead as a remote program call. Cobol-RPC will do this because SAMPLE2 is identified as a remote program in the [RemotePrograms] section of COBOLRPC.INI.
When this approach is available it is the easiest method of implementing remote program calls. It eliminates the need for any Cobol-RPC specific coding and makes the migration of legacy code effortless.
Cobol runtime systems vary dramatically in their internal implementation of CALL statements. This impacts the features Cobol-RPC can provide. In order to provide a remote program calling mechanism that is available on all implementations of Cobol-RPC, the REMOTEPROGRAM function is provided. If you desire maximum portability for your application, you should use this function for remote program calls, even if your current implementation supports redirected CALL statements.
The Cobol-RPC REMOTEPROGRAM function will also be enhanced in future versions to provide additional functionality not possible with redirected CALL statements.
When using the Cobol-RPC REMOTEPROGRAM function, the copy file, COBOLRPC.WS, should be included in your program. It includes the declaration of a parameter block that contains all the variables needed by this function.
To see how the REMOTEPROGRAM function works let's look at the code required to call the program SAMPLE3 using the REMOTEPROGRAM function:
MOVE "SAMPLE3" TO RPC-PROGRAM. MOVE 0 TO RPC-ARG-COUNT. CALL "REMOTEPROGRAM" USING RPC-CONTROL.
All the RPC- variables are declared in COBOLRPC.WS. RPC-PROGRAM-NAME indicates the name of the remote program to be called. RPC-ARGUMENT-COUNT indicates the number of data items to be passed, in this case, zero.
Usually you will want to pass data to the server program. Since some Cobols do not pass descriptions of the parameters to CALL statements, you have to provide this information. The simplified version of REMOTEPROGRAM described in the next section and available on some implementations eliminates these requirements.
Let's examine the code required to call the program SAMPLE4 and pass it the following three data items:
01 DATA-1 PIC X(10). 01 DATA-2 PIC 9(5) 01 DATA-3. 03 ITEM-1 PIC X(10). 03 ITEM-2 PIC 9(5). MOVE "SAMPLE4" TO RPC-PROGRAM. MOVE 3 TO RPC-ARG-COUNT. MOVE 10 TO RPC-ARG-SIZE (1). MOVE 5 TO RPC-ARG-SIZE (2). MOVE 15 TO RPC-ARG-SIZE (3). CALL "REMOTEPROGRAM" USING RPC-CONTROL DATA-1 DATA-2 DATA-3.
This time RPC-ARG-COUNT is set to 3, the number of arguments to be passed. Each entry in the array, RPC-ARG-SIZE, is loaded with the size of the corresponding argument. The size of the first argument is loaded in RPC-ARG-SIZE (1), the second in RPC-ARG-SIZE (2).
It is strongly recommended that when using the "REMOTEPROGRAM" function the copy file COBOLRPC.WS be used to declare the RPC- variables. Future versions of Cobol-RPC will expand this parameter block and using the copy file will make migration to new versions easier.
Please refer to the release notes for limitations on the number and size of parameters which can be passed on your implementation.
Some Cobols provided extensive information describing the number and types of parameters passed with CALL statements. With these Cobols you do not need to describe the data to be passed to server programs using the RPC- variables contained in COBOLRPC.WS. All that is required is the name of the program to be called and the data items.
Let's look at how the example in the previous section can be coded using the simplified REMOTEPROGRAM function. We need to call the program SAMPLE4 and pass it the following data items:
01 DATA-1 PIC X(10). 01 DATA-2 PIC 9(5). 01 DATA-3. 03 ITEM-1 PIC X(10). 03 ITEM-2 PIC 9(5).
All that is required is the following statement:
CALL "REMOTEPROGRAM" USING "SAMPLE4" DATA-1 DATA-2 DATA-3.
Since the Cobol will provide us with descriptions of the data items, we supply just the program name as the first parameter, not RPC-CONTROL.
Remember, if you want your code to be portable to all platforms you should use the version of REMOTEPROGRAM described in the previous section. Please see the release notes to determine if your implementation supports the simplified REMOTEPROGRAM function.
In order to free system resources as quickly as possible and make them available to other processes, a client program should execute the SHUTDOWNRPC function before exiting. Failure to do this will delay the release of system resources until the Cobol-RPC client DLL is freed from memory. If other client processes are using Cobol-RPC the DLL is not freed from memory until all client processes are terminated.
The SHUTDOWNRPC function is executed as follows:
Distributors | Library | Register
Copyright 1996 by England Technical Services, Inc.