In the architecture of modern e-business applications (SOA), loosely coupled systems are becoming more and more important. Reliable messaging is one important technology for this type of system.
Reliable RPC is the Natural RPC implementation of a reliable messaging system. It combines the Natural RPC technology and persistence, which is implemented by means of units of work (UOWs) that are offered by the EntireX Broker. Reliable RPC is characterized by following features:
The Natural RPC client executes a CALLNAT statement without waiting for
a reply from the server (the RPC message is sent in asynchronous mode).
An RPC server needs not be active at the time the CALLNAT is
executed.
The reliable RPC message is stored in the EntireX Broker's persistent store until an RPC server is available.
The Natural RPC server executes the reliable RPC by calling the requested subprogram but does not send a reply to the RPC client.
A Natural RPC client may ask the status of the sent reliable RPC messages.
A Natural RPC client may send a reliable RPC message to an EntireX RPC server.
A Natural RPC server may receive a reliable RPC message from an EntireX RPC client.
The Natural RPC client for a reliable RPC is configured in the same way as for a normal Natural RPC. The same Natural RPC client session can send standard RPC requests and reliable RPC messages.
To enable a Natural RPC client to use reliable RPC, the Natural RPC client must use
application programming interface USR2071N for an explicit EntireX Broker logon. This implies
that the RPC/NTRPC keyword subparameter ACIVERS must be set to 2 or
higher.
Reliable RPC is used to send messages to a persistent EntireX Broker service. The messages are described by the PDA of the caller and may only contain output parameters. A parameter is defined as "output" in one of the following ways:
If a Natural interface object is used:
In the Attr field on the Interface Object
Generation screen of the SYSRPC utility, set
the attribute of the parameter to O (output).
Note
If your parameter definitions do not contain group structures, you must set the
attribute COMPAT to IDL before generating the interface
object; see Generating
Interface Objects - General Considerations in the
SYSRPC Utility documentation.
If no Natural interface object is used:
Use the AD=O session parameter in the CALLNAT statement.
Note
If you want to call an EntireX RPC server and if the corresponding IDL file
contains group structures, then you must use a Natural interface object, and the
parameter definition for the Natural interface object must correspond to the group
structure of the IDL file.
If you generate a Natural interface object from an IDL file, the attribute of the parameter is taken from the IDL file. In this case, the IDL file must only contain inbound (from the server's point of view) parameters.
Reliable RPC is enabled at runtime. The client has to set one of two different modes before issuing a reliable RPC request:
AUTO_COMMIT
CLIENT_COMMIT
While AUTO_COMMIT commits each message implicitly after sending it, a series
of RPC messages sent in a unit of work (UOW) can be committed or rolled back explicitly
using CLIENT_COMMIT mode.
For this purpose, Natural provides the two application programming interfaces
USR6304N and USR6305N. With interface USR6304N,
the mode for reliable RPC is set. With interface USR6305N, a unit of work
that has been created with CLIENT_COMMIT can be committed or
rolled back.
To make use of USR6304N
Copy the subprogram USR6304N from the library SYSEXT to
the library SYSTEM or to the steplib library or to any application in
the client 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)
|
Set the mode for reliable RPC. The mode applies to all subsequent calls. | |||
G (Get)
|
Get the previously specified mode. | |||
P-MODE |
I/O | N01 | Mode for reliable RPC: | |
0 |
No reliable RPC (standard RPC execution) | |||
1 |
Reliable RPC
AUTO_COMMIT |
|||
2 |
Reliable RPC CLIENT_COMMIT
|
|||
P-RC |
O | N04 | Return code | |
P-MESSAGE |
O | A80 | Message text | |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR6304N' P-FUNC P-MODE P-RC P-MESSAGE
Note:
The mode CLIENT_COMMIT cannot be changed if reliable RPC
messages have been sent but not yet committed or rolled back.
To make use of USR6305N
Copy the subprogram USR6305N from the library SYSEXT to
the library SYSTEM or to the steplib library or to any application in
the client environment.
Using the DEFINE DATA
statement, specify the following parameters:
| Parameter | I/O | Format | Description | |
|---|---|---|---|---|
P-FUNC |
I | A08 | Function code; possible values are: | |
COMMIT |
Commit the sent reliable RPC messages. The messages are now available for an RPC server. | |||
ROLLBACK |
Discard the already sent reliable RPC messages. | |||
P-RC |
O | N04 | Return code | |
P-MESSAGE |
O | A80 | Message text | |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR6305N' P-FUNC P-MODE P-RC P-MESSAGE
The Natural RPC server for reliable RPC is configured in the same way as for normal Natural RPC. The same Natural RPC server session can process standard RPC requests and reliable RPC messages.
To enable the processing of reliable RPC messages, the RPC/NTRPC keyword subparameter ACIVERS must be set to 2 or
higher.
To view the status of sent reliable RPC messages, Natural provides the application
programming interface USR6306N. With USR6306N you can get the
status of all reliable RPC messages that you have previously sent under your user ID.
USR6306N must not necessarily be called within the Natural session in which
the reliable RPC messages have been sent. If USR6306N is used in a different
Natural session, the application programming interface USR2071N must first be
used to log on to the EntireX Broker with the same user ID that has been used to send the
reliable RPC messages.
The reliable RPC messages are implemented by EntireX Broker unit of works (UOWs). The information about reliable RPC messages is therefore information about UOWs.
To make use of USR6306N
Copy the subprogram USR6306N from the library SYSEXT to
the library SYSTEM or to the steplib library or to any application in
the client environment.
Using the DEFINE DATA
statement, specify the following parameters:
| Parameter | I/O | Format | Description |
|---|---|---|---|
P-UOW-ID-IN |
I | A16 | ID for the UOW to be retrieved. Possible values are:
UOWID of a UOW
|
P-USER-ID |
O | A32 | User ID of the user who has created the UOWs. |
P-BROKER-ID |
O | A32 | Broker ID of the EntireX Broker that hosts the UOWs. |
P-UOW-COUNT |
O | I4 | Number of UOWs in the P-UOW-INFO
array.
|
P-UOW-INFO (/1:*) |
X-array with information about each UOW | ||
P-UOW-ID |
O | A32 | ID of the UOW |
P-UOW-STATUS |
O | A10 | Status of the UOW according to EntireX Broker
The status depends on the processing state and is assigned by the EntireX Broker. |
P-USERR-STATUS |
O | A32 | User information about the UOW.
This is typically error information that has been set by the RPC server. |
P-CREATE-TIME |
O | A32 | Creation time of the UOW according to EntireX Broker. |
P-RC |
O | N04 | Return code |
P-MESSAGE |
O | A80 | Message text |
In the calling program on the client side, specify the following statement:
CALLNAT 'USR6306N' P-UOW-ID-IN P-USER-ID P-BROKER-ID P-UOW-COUNT P-OUW-INFO(*) P-RC P-MESSAGE
