Reliable RPC


General Information

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 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.

Reliable RPC diagram

Reliable RPC on the Natural RPC Client Side

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 profile parameter 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 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 client's point of view) parameters.

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 client's point of view) parameters.

Reliable RPC is enabled at runtime. The client has to set the 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.

Start of instruction setTo make use of USR6304N

  1. 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.

  2. 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
  3. 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.

Start of instruction setTo make use of USR6305N

  1. 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.

  2. 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
  3. In the calling program on the client side, specify the following statement:

    CALLNAT 'USR6305N' P-FUNC P-MODE P-RC P-MESSAGE

Reliable RPC on the Natural RPC Server Side

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 profile parameter ACIVERS must be set to 2 or higher.

Viewing the Status of Reliable RPC Messages

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.

Start of instruction setTo make use of USR6306N

  1. 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.

  2. 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

    LAST: the UOW for the last reliable RPC message in the current Natural session

    ALL or blank: all UOWs for the logged on EntireX Broker user

    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
  3. 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