This section mainly describes the tasks required to operate a Natural RPC environment.
Some of these tasks are performed with the SYSRPC utility. For
information about the functions the SYSRPC utility provides, refer
to the Natural SYSRPC
Utility documentation.
This section covers the following topics:
To each remote CALLNAT request, a server must be
assigned (identified by servername and
nodename) on which the
CALLNAT is to be executed. Therefore, all subprograms to be
accessed remotely must be defined
in a local service directory on the client side,
or in a remote directory accessed via a remote directory server,
or by way of default server addressing with the
profile parameter DFS,
or within the client application itself by way of default server addressing.
In addition to the methods mentioned above, you can specify alternative servers.
Below is information on:
All data of a client's local service directory is stored in the
subprogram NATCLTGS. At execution time, this subprogram is used to
retrieve the target server. As a consequence, NATCLTGS must be
available in the client application or in one of the Natural steplibs defined
for the application.
If NATCLTGS has not been generated into a steplib or
resides on another machine, use the appropriate Natural utility (
SYSMAIN
or
the Natural Object Handler) to
move NATCLTGS into one of the steplibs defined for the
application.
If you are using a NATCLTGS for joint usage, you must
make it available to all client environments, for example by copying it to the
library SYSTEM, or, if an individual copy is used for a client, it
must be maintained for this client using the
Service Directory Maintenance
function of the SYSRPC utility.
To define and edit RPC service entries, see the section Service Directory Maintenance in the SYSRPC Utility documentation.
A remote directory contains service entries that can be made available to several Natural clients. The Natural clients can retrieve these service entries from remote directory servers. For information on the purpose and on the installation of remote directory servers; see Using a Remote Directory Server.
Instead of addressing a server by using a local or remote service
directory, you can preset a default server with the profile parameter DFS,
as described in the Natural Parameter Reference
documentation. This server address is used if the subprogram can be found in
neither the local nor the remote service directory.
The DFS setting determines the default
server for the whole session or until it is overwritten dynamically.
If no DFS setting exists and the server
address of a given remote procedure call could not be found in the service
directory, a Natural error message is returned.
A default server address defined within a client application remains active even if you log on to another library or if a Natural error occurs.
The client application itself may dynamically
specify a default server address at runtime. For this purpose, Natural provides
the application programming interface
USR2007N.
This interface enables you to determine a default server address that is to be
used each time a remote program cannot be addressed via the service
directory.
To make use of USR2007N
Copy the subprogram USR2007N from the library
SYSEXT to the library SYSTEM or to the steplib
library, or to any application in the server environment.
Using the DEFINE
DATA statement in structured mode or the
RESET statement in
reporting mode, specify the following parameters:
| Parameter | Format | Description | |
|---|---|---|---|
function |
A1 | Function; possible values are: | |
P (Put)
|
Determines that the server address (composed of
the parameters nodename and
servername, see below) is the
default address for all subsequent remote procedure calls not defined in the
service directory.To remove a default server address, specify a
blank for |
||
G (Get)
|
Retrieves the current default server address as set by the function P. | ||
nodename |
A192 |
Specifies/returns the name of the server node to be addressed. Note: |
|
servername |
A32 |
Specifies/returns the server name to be addressed. Note: |
|
logon |
A1 | Specifies/returns the Logon option, see Using the Logon Option. | |
protocol |
A1 | Specifies/returns
the transport protocol.
Valid value: |
|
noservdir |
A1 | Specifies/returns
the service directory option, see profile parameter
DFS.
|
|
Y |
Service directory must not be present | ||
N |
Service directory must be present | ||
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2007N' function nodename servername logon protocol [noservdir]
Note:
The Natural subprogram NATCLTPS in the library
SYSRPC is only maintained for compatibility reasons.
To avoid connection failures, you may want to define several
alternative servers for a remote CALLNAT. If you specify such
alternative servers, Natural proceeds as follows:
The client makes a first attempt to establish the connection.
If this attempt fails, instead of providing an error message, a second attempt is made, however, this time not on the same server. Instead, the service directory is searched again starting at the current entry to find out whether or not another server is available which offers the desired service.
If a second entry is found, Natural tries to establish the connection to this server. If the remote procedure call is performed successfully, the client application keeps on running. The user does not notice whether the connection to the first server or to the alternative server produced the result.
If no further entry is found or if the connections to alternative servers fail, Natural issues a corresponding error message.
To enable the use of an alternative server
Define more than one server in the service directory for the same service.
Set the profile parameter
TRYALT
to ON to give permission to use an alternative server.
This parameter can also be set dynamically for the current session with the Parameter Maintenance function (described in the SYSRPC Utility documentation).
Interface objects are no longer required if automatic Natural RPC execution is used, as described in Working with Automatic Natural RPC Execution below.
However, generating interface objects provides the advantage of
controlling the CALLNAT(s) executed remotely and facilitates error
diagnoses. Should a remote call fail due to an incorrect CALLNAT
name, the Natural error message issued then helps to immediately identify the
problem cause. Without an interface object, for an incorrect
CALLNAT you may receive follow-up errors returned from the
transport layer or the Natural server.
If you want to use a remote CALLNAT statement to
execute a subprogram on an EntireX RPC server, we strongly recommend that you
set AUTORPC=OFF and use an interface object. If the IDL (Interface
Definition Language) of the subprogram you want to call on an EntireX RPC
server contains a group structure, you must define the same group structure
during the interface object generation on the
Interface
Object Generation screen or generate the interface object from the
EntireX IDL
file (Windows only) or use the EntireX Workbench (Linux and Windows
only).
Below is information on:
With the Interface Object Generation function of the
SYSRPC utility, you can generate the Natural interface objects used to
connect the client's calling program to a subprogram on a server. The interface object
consists of a parameter data area (PDA) and the server call
logic; see Interface
Object Generation - General Considerations in the SYSRPC Utility
documentation.
The PDA contains the same parameters as used in the
CALLNAT statement of
the calling program and must be defined on the Interface Object
Generation screen of the Interface Object
Generation function. If a compiled Natural subprogram with the same
name already exists, the PDA used by this subprogram is used to preset the
screen. The server call logic is generated automatically by the
Interface Object Generation function after the PDA has
been defined.
At execution time, the Natural application program containing the
CALLNAT statement and the interface object must exist on the
client side. The Natural application subprogram must exist on the server side.
Both the interface object subprogram and the server subprogram must have the
same name.
This section applies only if you do not want to call an EntireX RPC server.
You are not required to generate Natural RPC interface objects,
but you can work with automatic Natural RPC execution (that is, without using
Natural interface objects). To work with automatic Natural RPC execution, set
the profile parameter
AUTORPC
as follows:
AUTORPC=ON
In that case, you can omit the generation of the client interface
object during your preparations for RPC usage. When the automatic Natural RPC
execution is enabled (AUTORPC=ON), Natural behaves as follows:
if a subprogram cannot be found locally, Natural tries to execute it remotely (an interface object is not needed),
the parameter data area will then be generated dynamically during runtime.
As interface objects only exist for client programs, this feature
has no effect on the CALLNAT program on the server.
If profile parameter
AUTORPC
is set to ON, and a Natural interface object exists, it will still
be used.
With the Parameter Maintenance function of the SYSRPC utility, you can dynamically modify some of the RPC profile parameters set in the Natural profile parameter module for the current session.
Caution:
These modifications are retained as long as the user session
is active; they are lost when the session is terminated.
You can use the Application Programming Interface USR2076N to dynamically
(within a session) get (function: G=Get) or set (function:
S=Set) the value of the Natural profile parameter
TIMEOUT in
the parameter file for the current session.
TIMEOUT=value specifies
the number of seconds the client should wait for an RPC server response. If
this time is exceeded, the remote procedure call is aborted with a
corresponding error message.
Caution:
This modification is retained as long as the user session is
active; it is lost when the session is terminated.
For further information, refer to the description contained in the
text object USR2076T in the library SYSEXT.
Active servers that have been defined in the service directory (see
Specifying RPC Server
Addresses) can be controlled with the SYSRPC
server command execution
function as described in the relevant section in the
SYSRPC Utility documentation.
The server library on which the CALLNAT is executed depends on
the RPC Logon
Option on the client side and a couple of parameters on
the server side.
The following table shows which the relevant parameters are and how they influence the library setting:
| Client | Server | ||||||
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | |
| *library-id | RPCLOGONflag for server entry set? |
LOGONRQset? |
Server started with STACK= |
NSC or native Natural? |
NSC: RPC Logon option in library profile |
Server *library-id |
|
| 1 | Lib1 | no | no | logon lib1 | No influence | N/-- | Lib1 |
| 2 | Lib1 | no | no | logon lib2 | No influence | N/-- | Lib2 |
| 3 | Lib1 | no | yes | (Client LOGON
flag = NO) and ( LOGONRQ=YES)is not possible. |
|||
| 4 | Lib1 | yes | No influence | No influence | NSC | AUTO |
Lib1 |
| 5 | Lib1 | yes | No influence | No influence | NSC | N | Lib1 |
| 6 | Lib1 | yes | No influence | No influence | Native Natural | -- | Lib1 |
Explanation of the table columns:
The library ID of the client application where the
CALLNAT is
initiated.
The value of the RPC LOGON flag. Can be set for a
whole node or a server.
The flag can be set by using
the Service Directory
Maintenance function of the SYSRPC utility,
or the profile parameter
DFS,
or the application programming interface
USR2007N.
The profile parameter
LOGONRQ
can be set at server startup.
The library ID to which the server is positioned at its startup.
Does the server run under Natural Security (NSC) (see Using Natural RPC with Natural Security) or not?
The setting of the Logon option in the NSC
Library Profile
Items (Session options >
Natural RPC
Restrictions) of the NSC server application. If the NSC
Logon
Option is set to A (AUTO), only
library and user ID are taken. If set to N (default), the library,
user ID and password parameters are evaluated.
The library on the server where the CALLNAT program
is finally executed.
The Logon option defines on which library the remote subprogram is to be executed. See also Logon to a Server Library.
Note:
When you do not use the Logon option, the
CALLNAT is executed
on the library to which the server is currently logged on. This server logon is
defined with the Natural profile parameter STACK=(LOGON
library). The server will search for the
CALLNATs to be executed in
library (and all associated steplibs
defined for library).
A client application can be enabled to execute a subprogram on a different library by setting the Logon option for this subprogram. This causes the client to pass the name of its current library to the server, together with this Logon option. The server will then logon to this library, searching it for the desired subprogram and, if the latter is found, it will execute it. After that, it will logoff from the previous library.
If the server should logon to a library other
than the client's current library, the client has to call the application
programming interface USR4008N before the remote
CALLNAT is executed.
With USR4008N the client specifies an alternate name of a library
to which the server will logon. The name of this library will be used for all
subsequent calls to remote subprograms for which the Logon option applies. If
blank is specified for the library name, the name of the current client library
will be used again.
To make use of USR4008N
Copy the subprogram USR4008N from the library
SYSEXT to the library SYSTEM or to the steplib
library, or to any application in the server environment.
Using the DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
P-FUNC |
I | A01 |
Function code; possible values are: |
|
P (Put)
|
Specify a new library for remote
CALLNAT execution.
|
|||
G (Get)
|
Retrieve previously specified library for remote
CALLNAT execution.
|
|||
P-LIB |
I | A8 | Library on server
for remote CALLNAT execution.
|
|
In the calling program on the client side, specify the following statement:
CALLNAT 'USR4008N' P-FUNC P-LIB
Note:
The calling program must be executed before the Natural
RPC client invokes a remote CALLNAT.
To set the Logon option, you can use either the
SYSRPC Service Directory
maintenance function (see the relevant section in the
SYSRPC Utility documentation) or - when using a default server -
the profile parameter DFS
or the application programming interface
USR2007N.
No setting is required on the server side.
Compression types may be: 0, 1 or
2. Interface objects generated with COMPR=1
or 2 can help reduce the data transfer rate.
| Compression Type | Description |
|---|---|
COMPR=0 |
All CALLNAT parameter values are sent to
and returned from the server, i.e. no compression is performed.
|
COMPR=1 |
M-type parameters are sent to and returned from the server, whereas O-type parameters are only transferred in the send buffer. A-type parameters are only included in the reply buffer. The reply buffer does not contain the Format description. This is the default setting. |
COMPR=2 |
Same as for COMP=1, except that the server
reply message still contains the format description of the CALLNAT
parameters. This might be useful if you want to use certain options for data
conversion by EntireX Broker (for more information, see the description of
Translation Services in the EntireX Broker documentation).
|
The Natural RPC supports Secure Socket Layer (SSL) for the TCP/IP communication to the EntireX Broker.
To enable the EntireX Broker to recognize that the TCP/IP communication should use SSL, you must use one of the following methods:
Append the string :SSL to the node name. If the
node name has already been postfixed by the string :TCP,
:TCP must be replaced by :SSL.
Prefix the node name with the string //SSL:
Example:
SRVNODE='157.189.160.95:1971:SSL'
Before you access an EntireX Broker using SSL,
you must first invoke the application programming interface
USR2035N to set the
required SSL parameter string.
To make use of USR2035N
Copy the subprogram USR2035N from the library
SYSEXT to the library SYSTEM or to the steplib
library, or to any application in the server environment.
Using the DEFINE
DATA statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
FUNCTION |
I | A01 | Function code; possible values are: | |
P (Put)
|
Specify a new SSL parameter string.
The SSL parameter string is internally saved and
passed to EntireX each time an EntireX Broker using SSL communication is
referenced the first time. You may use different SSL parameter strings for
several EntireX Broker connections by calling application programming interface
Example:
FUNCTION := 'P' SSLPARMS := 'TRUST_STORE=FILE://DDN:CACERT&VERIFY_SERVER=N' CALLNAT 'USR2035N' USING FUNCTION SSLPARMS To set SSL parameters in case of a Natural RPC server, put the name of the calling program onto the Natural stack when starting the server. Example:
STACK=(LOGON server-library;set-SSL-parms) Where set-SSL-parms is a
Natural program that invokes the application programming interface
|
|||
G (Get)
|
Retrieve previously specified SSL parameter
string.
The previously put SSL parameter string is returned to the caller. For more information about the SSL parameter string, refer to the EntireX documentation. |
|||
SSLPARMS |
I | A128 | SSL parameter string as required by the EntireX Broker | |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR2035N' FUNCTION SSLPARMS
This part is organized in the following sections:
You can run the RPCERR program from the Command line
or invoke it by using a FETCH statement from within a
Natural program. RPCERR displays the following information:
The last Natural error number and message if it was RPC related.
The last EntireX Broker message associated with this error.
The last EntireX RPC server error message if the Natural error number is related to the EntireX RPC server error.
In addition, the node and server name from the last EntireX Broker call can be retrieved.
Natural error number: NAT6972
Natural error text :
Directory error on Client, reason 3.
RPC error information:
No additional information available.
Server Node: Library: SYSTEM
Server Name: Program: NATCLT3
Line No: 1010
You can use the subprogram RPCINFO in your
application program to retrieve information on the state of the current RPC
session. This also enables you to handle errors more appropriately by reacting
to a specific error class.
The subprogram RPCINFO is included in the library
SYSTEM and can be called by any user application.
A sample program TESTINFO is included in the library
SYSRPC together with the parameter data area RPCINFOL
for calling RPCINFO.
DEFINE DATA LOCAL USING RPCINFOL
LOCAL
1 PARM (A1)
1 TEXT (A80)
1 REDEFINE TEXT
2 CLASS (A4)
2 REASON (A4)
END-DEFINE
...
OPEN CONVERSATION USING SUBPROGRAM 'APPLSUB1'
CALLNAT 'APPLSUB1' PARM
CLOSE CONVERSATION *CONVID
...
ON ERROR
CALLNAT 'RPCINFO' SERVER-PARMS CLIENT-PARMS
ASSIGN TEXT=C-ERROR-TEXT
DISPLAY CLASS REASON
END-ERROR
...
END
RPCINFO has the following parameters which are
provided in the parameter data area RPCINFOL:
| Parameter | Format | Description | |
|---|---|---|---|
SERVER-PARMS |
Contains information
about the Natural session when acting as a server.
The |
||
S-BIKE |
A1 |
Transport protocol used; possible value: |
|
B |
EntireX Broker | ||
S-NODE |
A32 | The node name of the server. | |
S-NAME |
A32 | The name of the server. | |
S-ERROR-TEXT |
A80 | Contains the message text returned from the transport layer. | |
S-CON-ID |
I4 | Current conversation ID.
Note that this is the physical ID from EntireX Broker, not the logical Natural
ID.
This parameter always contains a value as EntireX Broker generates IDs for both conversational and non-conversational calls. If the physical conversation ID is either non-numeric or
greater than I4, a |
|
S-CON-OPEN |
L | Indicates whether there
is an open conversation.
This parameter contains the value |
|
CLIENT-PARMS |
Contain information about the Natural session when acting as a client. | ||
C-BIKE |
A1 |
Transport protocol used; possible value: |
|
B |
EntireX Broker | ||
C-NODE |
A32 | The node name of the previously addressed server. | |
C-NAME |
A32 | The name of the previously addressed server. | |
C-ERROR-TEXT |
A80 | Contains the message text returned from the transport layer. | |
C-CON-ID |
I4 | Conversation ID of the
last server call. Note that this is the physical ID from EntireX Broker, not
the logical Natural ID.
If no conversation is open, the value of this parameter
is less than or equal to |
|
C-CON-OPEN |
L | Indicates whether there
is an open conversation.
This parameter contains the value |
|
C-ENTIREX-RPC-ERROR-MESSAGE |
A | Contains the message text returned from an EntireX RPC server. | |
Natural RPC includes a trace facility that enables you to monitor server activities and trace possible error situations.
To activate/deactivate the server trace facility, start the server with the option or set the trace level dynamically with help of the SYSRPC utility.
TRACE=n
The integer value n
represents the desired trace level; that is, the level of detail in which you
want your server to be traced. The following values are possible:
| Value | Trace Level |
|---|---|
0 |
No trace is performed (default). |
1 |
All client requests and corresponding server responses are traced and documented. |
2 |
All client requests and corresponding server responses are traced and documented; in addition, all RPC data are written to the trace file. |
The RPC trace facility writes the trace data to the Natural Report Number 10.
In case of a conversion error which is reported with Natural error number NAT6974 and reason codes 2 and 3, the position of the erroneous data in the buffer is indicated.
The following information applies to Mainframe environments only:
All messages in the Natural RPC server trace are converted into
upper case if TS=ON is specified in the Natural RPC
server session. The trace of the data from/to the client is not affected by
TS=ON and remains unchanged.
The trace file definition depends on the environment:
On the mainframe, define the trace file appropriate to your
environment, see also the
NTPRINT
macro (in the Parameter Reference documentation).
In the server start job, assign a z/OS dataset to the Natural
additional Report CMPRT10.
//NATRPC JOB CLASS=K,MSGCLASS=X //NATSTEP EXEC PGM=NATOS //STEPLIB DD DISP=SHR,DSN=SAG.NAT.LOAD // DD DISP=SHR,DSN=SAG.EXX.LOAD //CMPRMIN DD * IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1, PRINT=((10),AM=STD) /* //SYSUDUMP DD SYSOUT=X //CMPRT10 DD SYSOUT=X //CMPRINT DD SYSOUT=X /*
Set the RPC parameter
NTASKS
to a value greater than 1.
Assign
CMPRMIN to a dataset with DISP=SHR
or to *.
As each task writes on a separate
CMPRINT dataset, define the following DD card
names:
CMPRINT for the main task;
CMPRINT1 to CMPRINT9 for the
first nine subtasks;
CMPRIN10 to
CMPRINnn for the next two-digit numbers
of subtask, nn=NTASKS-1.
If the keyword subparameter
TRACE of profile parameter
RPC or parameter macro
NTRPC is set, the trace facility
writes to Printer 10.
You must define the following DD card names:
CMPRT10 for the main task;
CMPRT101 to
CMPRT1nn for all subtasks,
nn=NTASKS-1;
//NATRPC JOB CLASS=K,MSGCLASS=X //NATSTEP EXEC PGM=NATOS,REGION=8M //steplib DD DISP=SHR,DSN=SAG.NAT.LOAD // DD DISP=SHR,DSN=SAG.EXX.LOAD //CMPRMIN DD * IM=D,MADIO=0,MT=0,OBJIN=R,AUTO=OFF,MAXCL=0,ID=',',INTENS=1, PRINT=((10),AM=STD) /* //SYSUDUMP DD SYSOUT=X //CMPRT10 DD SYSOUT=X //CMPRT101 DD SYSOUT=X //CMPRT102 DD SYSOUT=X //CMPRT103 DD SYSOUT=X //CMPRINT DD SYSOUT=X //CMPRINT1 DD SYSOUT=X //CMPRINT2 DD SYSOUT=X //CMPRINT3 DD SYSOUT=X /*
Under CICS, assign Print File 10 to a CICS extra-partitioned transient data queue.
Natural dynamic profile definition:
PRINT=((10),AM=CICS,DEST=RPCT,TYPE=TD)
CICS definition:
RPCTRAC DFHDCT TYPE=SDSCI, X
BLKSIZE=136, X
BUFNO=1, X
DSCNAME=RPCTRACE, X
RECFORM=VARUNB, X
RECSIZE=132, X
TYPEFLE=OUTPUT
SPACE
RPCT DFHDCT TYPE=EXTRA, X
DSCNAME=RPCTRACE, X
DESTID=RPCT, X
OPEN=INITIAL
CICS Startup JCL:
RPCTRACE DD SYSOUT=*
It is recommended that you use a different file name (that is, a different
NATPARM parameter file) for each server so that you can trace them
individually. The trace file is defined in the NATPARM parameter file of
the Natural server:
Report Assignments
Assign the logical device LPT10 to your Report Number 10.
Device Parameter Assignments
Instead of selecting a physical printer specification for LPT10, specify a file
name that represents the name of your trace file.
/bin/sh -c cat>>/filename
where filename represents the name of the trace file.
It is recommended that you use a different file name (that is, a
different NATPARM parameter file) for each server so that you can
trace them individually. The trace file is defined in the NATPARM
parameter file of the Natural server (see
Device/Report
Assignments in the Configuration Utility):
Assign the logical device LPT10 to your Report Number 10.
Instead of selecting a physical printer specification for LPT10, specify a file name that represents the name of your trace file. As default, old trace files are deleted when a new file with the same name is created.
If you wish to append the new log to the existing one, specify:
>>filename
The Natural application programming interface
(API) USR4010N
enables you to retrieve the runtime settings of a server:
the system file assignments for FUSER,
FNAT, and FSEC,
the steplib chain.
To make use of USR4010N
Server environment:
Copy the subprogram USR4010N from the library
SYSEXT to the library SYSTEM or to the steplib
library or to any application in the server environment.
Client environment:
In a DEFINE
DATA statement, specify the following parameters as a
redefinition of USR4010-PARM (A300):
| Parameter | Format | Description |
|---|---|---|
FUSER-DBID |
N5 | Database ID of system file
FUSER.
|
FUSER-FNR |
N5 | File number of system file
FUSER.
|
FNAT-DBID |
N5 | Database ID of system file
FNAT.
|
FNAT-FNR |
N5 | File number of system file
FNAT.
|
FSEC-DBID |
N5 | Database ID of system file
FSEC.
|
FSEC-FNR |
N5 | File number of system file
FSEC.
|
STEP-NAME |
A8/15 | Name of steplib. |
STEP-DBID |
N5/15 | Database ID of steplib. |
STEP-FNR |
N5/15 | File number of steplib. |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR4010N' USR4010-PARM
See also the
Syntax
Description of the CALLNAT statement.
If the RPC parameter
AUTORPC=OFF is set, copy the interface USR4010X
to the client environment with the name USR4010N.
If the RPC parameter AUTORPC=ON is set, the API
must not be available in the client environment to avoid that the interface is
called locally.
When USR4010N is called, the values of the parameter
specified above are output in the group of fields
USR4010-PARM.
The Application Programming Interface (API) USR4009N enables you to set or to
get the EntireX parameters that are currently supported by the Natural RPC. These are:
Compression level
Encryption level
To make use of USR4009N
Copy the subprogram USR4009N from the library SYSEXT to the
library SYSTEM or to the steplib library or to any application in the
server environment.
Using a DEFINE
DATA statement, specify the following parameters:
| Parameter | Format | I/O | Description | |
|---|---|---|---|---|
FUNCTION |
A01 | I | Function; possible values are: | |
G (Get)
|
The values already set for the EntireX parameters
are returned.
If no |
|||
P (Put)
|
The values specified for the EntireX parameters are saved and used in all subsequent calls to EntireX. | |||
ENVIRONMENT |
A01 | I | Environment; possible values are: | |
S |
Server | |||
C |
Client | |||
B |
Both | |||
COMPRESSLEVEL |
A01 | I/O | Compression level. | |
ENCRYPTION-LEVEL |
I01 | I/O | Encyption level. | |
ACIVERS |
B02 | O | API version used. | |
RC |
B01 | O | Return code, unless equal to zero. Contains the API version required to set the requested parameter: | |
0 |
Function successful. | |||
6 |
Compression level requires API version 6. | |||
7 |
Compression level requires API version 7. | |||
The interface can be called in two ways:
From within a program:
CALLNAT 'USR4009N' FUNCTION ENVIRONMENT
COMPRESSLEVEL
ENCRYPTION-LEVEL
ACIVERS RC
From the command prompt or by using the statement
STACK with values for
the above parameters.
Examples:
USR4009P P,C,ENCRYPTION-LEVEL=1,COMPRESSLEVEL=6 USR4009P P,C,,6
In command mode, you may use the
keyword=value notation to set only a
subset of the EntireX parameters. The values for parameters that are not
referenced remain unchanged.
The request is rejected and no values are saved if the API version used by the current Natural session is not high enough to support the requested EntireX parameter. In this case the RC contains the required API version.
The EntireX parameters are only honored by the Natural RPC.
The Application Programming Interface (API) USR8225N enables you to maintain
message ID and correlation ID of EntireX in an RPC client or server environment.
To make use of USR8225N
Copy the subprogram USR8225N from library SYSEXT to the library SYSTEM
or to the steplib library or to any application in the server environment.
Using a DEFINE DATA
statement, specify the following parameters:
| Parameter | Format | I/O | Description |
|---|---|---|---|
FUNCTION |
A08 | I | Function code:
|
ENVIRONMENT |
A06 | I | Environment setting:
|
MESSAGE_ID |
A64 | O | Message ID |
CORRELATION_ID |
A64 | O | Correlation ID |
| RC | N04 | O | Return value:
|
Any Natural error on the server side is returned to the client as follows:
Natural RPC moves the appropriate error number to the
*ERROR-NR
system variable.
Natural reacts as if the error had occurred locally.
Note:
If theprofile parameter AUTORPC is set to ON and a
subprogram cannot be found in the local environment, Natural will interpret this as a
remote procedure call. It will then try to find this subprogram in the service
directory. If it is not found there, a NAT6972 error will be issued. As a consequence,
no NAT0082 error will be issued if a subprogram cannot be found.
See also Using the RPCERR Program.
If a server application program does not issue a database call during a longer period of time, the next database call might return a NAT3009 error message.
To avoid this problem, the optional user exit
NATRPC39 is provided. This exit is called in the following
cases:
After a Ping command;
In case of communication via the EntireX Broker: each time the
SERVER-NONACT time is exceeded.
To activate the user exit NATRPC39
Copy the sample exit NATRPC39 from library
SYSRPC to library SYSTEM on system file
FUSER.
The steplib concatenation of the library to which the server currently is logged on is not evaluated.
Adapt the database ID which is assigned to field
ACB-RSP to your needs.
Add additional CALL 'CMADA' statements, which
reference additional database IDs to your NATRPC39 if more than
one Adabas database is involved.
The user exit NATRPC01 is called when a Natural error
has occurred, actually after the error has been handled by the Natural RPC
runtime and immediately before the response is sent back to the client. This
means, the exit is called at the same logical point as an error transaction,
that is, at the end of the Natural error handling, after all ON
ERROR statement blocks have been processed.
In contrast to an error transaction, this exit is called with a
CALLNAT statement and must therefore be a subprogram which must
return to its caller.
The interface to this exit is similar to the interface of an error transaction. In addition, the exit can pass back up to 10 lines of information which will be traced by the Natural RPC runtime. Only lines which begin with a non-blank character will be traced.
A sample user exit NATRPC01 can be found in the
library SYSRPC.
NATRPC01 must be located in library SYSTEM on
FUSER.
The DEFINE DATA
PARAMETER statement block must not be changed.
To give administrators more control over the execution of services (remote CALLNATs), two optional user exits are called on the Natural RPC server side.
These exits are independent of each other and can be used separately.
For both exits, the following rules apply:
The exit must be located in library SYSTEM on the
FUSER system file.
If the exit is found during startup of the Natural RPC server, a message is written to the Natural RPC server trace to indicate the activation of the exit. The exit is afterwards called unconditionally. If the exit is removed during the lifetime of the server session, a permanent NAT0082 error will occur.
If the exit is not found during startup of the Natural RPC server, the exit is never called during the lifetime of the server session. The exit cannot be enabled dynamically.
The exit must be implemented by the user as a subprogram. The exit is called with a single dynamic variable as parameter. The content of the dynamic variable is the eight character long name of the remote subprogram.
The use of the dynamic variable allows us to implement future extensions of the passed information without causing problems with existing user written exits.
The exit is also called inside a conversation.
The Natural RPC server does not intercept unhandled errors in the exit. If an unhandled error occurs in the exit, the error is propagated to the client.
The exits may be used for auditing or tracing purposes. NATRPC02 may also be
used for additional security checks.
NATRPC02:
DEFINE DATA PARAMETER 1 SUBPROGRAM (A8) BY VALUE END-DEFINE IF *USER <> 'DBA' AND SUBPROGRAM = 'PRIVATE' *ERROR-NR := 999 END-IF END