This document informs you about some restrictions and limitations that you should observe when you are using the Natural RPC (Remote Procedure Call) facility.
Excepting the user identification, no user context is transferred to the server session, for example:
all client session parameters remain unchanged and do not affect the execution on the server side;
open transactions on the client side cannot be closed by the server and vice versa;
client report handling and work file processing cannot be continued on the server side and vice versa;
the handling of the Natural stack cannot be continued either.
No system variables except *USER
can
be transferred from the client to the server side.
In an RPC server, application-independent variables (AIVs) are not
deallocated implicitly, but stay active across RPC requests, because different
clients may have access to the same variables on the RPC server. This means
they must be deallocated explicitly using the
RELEASE
VARIABLES
statement.
If you want to release AIVs at the end of an RPC request, you may
use the Natural RPC user exit NATRPC03
for this
purpose.
Parameter handling in error situations is different:
If an error occurs during local execution, all parameter modifications performed so far are in effect, because parameters are passed via "call by reference".
If an error occurs during remote execution, however, all parameters remain unchanged.
If the parameter data area of the subprogram contains a variable
number of occurrences (1:V
notation), you should not use an
interface object to call this subprogram. As an interface object only supports
array definitions with a fixed number of occurrences, you cannot vary the
number of occurrences from call to call.
If you have to use an interface object, for example, because you want to call an EntireX RPC server with the same program, you should use an X-array on the Natural client side. With X-arrays, it is possible to vary the number of occurrences from call to call even when using an interface object. In this case, the X-array on the client side is passed to the (fixed) variable array on the server side. The variable array is fixed because the server program may receive a varying number of occurrences from call to call but cannot change the number of occurrences.
X-arrays are supported in the parameter list of a remote
CALLNAT
statement
execution. The server may increase or decrease the number of occurrences.
In case of a multidimensional array, all dimensions of the array must be extensible.
The lower bound must not be extensible, that is, only extensible upper bounds are allowed.
If you want to use an X-group array that contains an array with constant bounds or a group array that contains an X-array, you must use an interface object. When generating the interface object, you must define the group structure in the Interface Object Generation screen.
Examples:
01 X-Group-Array (/1:*) 02 Array (A10/1:10) * 01 Group-Array (/1:10) 02 X-Array (A10/1:*)
If group arrays or X-group arrays are present in the parameter list
of a remote CALLNAT
statement execution and an interface object is used, the following restrictions
exist.
You must not use the
AD=O
or
AD=A
session parameter settings (attribute definition) in the
CALLNAT
statement.
Group arrays and X-group arrays passed from a client Natural object to an interface object must be contiguous. We therefore strongly recommend that you always pass a complete array to the interface object by using asterisk (*) notation for all dimensions. We also strongly recommend that you use identical data definitions in the client Natural program, in the interface object, and in the server program.
The storage layout of group arrays in the DEFINE DATA
PARAMETER
area of subprograms on the RPC server side is not necessarily
identical with respect to the syntax. Do not redefine fields within a group
array or pass the group array to a 3GL program. If you need to do so, copy the
group array to a group array with the same layout in the DEFINE DATA
LOCAL
area and use this local group array in the call to the 3GL
program.
The Natural data formats C (attribute control) and Handle are not
allowed in the parameter list of a remote CALLNAT
statement
execution.
If you want to call an EntireX RPC server with a remote
CALLNAT
statement
execution, it is strongly recommended to use an interface object. There are two
ways to generate such an interface object:
Generate the interface object from the EntireX IDL (Interface Definition Language) file. This is only supported with Natural Studio (Windows only) or the EntireX Workbench (Linux and Windows only).
Define the parameters of the IDL definition of the subprogram
you want to call on an EntireX RPC server manually using the
Interface
Object Generation screen of the
SYSRPC
utility.
If the IDL (Interface Definition Language) contains a group structure, you have
to define the same group structure on the Interface Object Generation screen.
If you access a VSAM dataset in a subtasking environment or if you
share a VSAM dataset across regions, you must consider the required share
options. For example, you may have to set cross-region SHAREOPTIONS
4
instead of SHAREOPTIONS 2
to enforce buffer invalidation
if records are inserted in a VSAM dataset in one address space and the same
VSAM dataset is read in another address space. Otherwise, records recently
inserted may not be found.
You should also consider using record level sharing (RLS).
For further information, refer to the relevant VSAM documentation of IBM.
Several Natural statements may react in a different way when used in a Natural RPC context, for example:
Statement | Description |
---|---|
OPEN CONVERSATION CLOSE
CONVERSATION |
If executed on a server, these statements do not affect the client session. When the server itself acts as a client for another server (as agent), these statements only affect the conversations on the second server. |
PASSW |
The password setting remains active on the server side only, also for subsequent executions by other users. |
SET
CONTROL SET
GLOBALS SET
KEY SET
TIME SET
WINDOW |
No settings are returned to the caller. |
STACK |
All stack data are released after execution. |
STOP TERMINATE |
These statements do not stop the client
session.
For information on how to terminate a Natural RPC server, see Terminating a Natural RPC Server. |
The use of the following statements on an Natural RPC is theoretically possible, but not recommended, as it causes undesired effects:
Statement | Description |
---|---|
TERMINATE |
Using this statement causes the server to be terminated, regardless of conversations that may still be open. |
FETCH RUN STOP |
Using these statements causes the
CALLNAT context to be
lost.
Upon a Exception: This does not apply to
|
INPUT |
Input values are unpredictable when the input data are read from a file (and not from the stack). |