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
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
If you want to release AIVs at the end of an RPC request, you may use
the Natural RPC user exit
NATRPC03 for this
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
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.
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
statement execution and an interface object is used, the following restrictions
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
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
LOCAL area and use this local group array in the call to the 3GL
The Natural data formats C (attribute control) and Handle are not
allowed in the parameter list of a remote
If you want to call an EntireX RPC server with a remote
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
Object Generation screen of the
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 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 to use record level sharing (RLS).
For furthur 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:
||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.|
||The password setting remains active on the server side only, also for subsequent executions by other users.|
||No settings are returned to the caller.|
||All stack data are released after execution.|
||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:
||Using this statement causes the server to be terminated, regardless of conversations that may still be open.|
||Using these statements causes the
Exception: This does not apply to
||Input values are unpredictable when the input data are read from a file (and not from the stack).|