APIs for Providing an RPC Context from the Natural Client Side

This document gives an overview on application programming interfaces (APIs) to provide the context for an RPC call, for example passwords or a default server. The following topics are covered:

RPC-CNTX

The API RPC-CNTX can be used for providing a context for RPC calls as it is done in test programs generated by the webMethods EntireX Natural Wrapper.

RPC-CNTX combines the functionality of several APIs and is available in library SYSTEM. There is no need for extra preparations such as setting a STEPLIB or to copy APIs from SYSEXT to user libraries.

Start of instruction setTo make use of RPC-CNTX

  1. Specify a DEFINE DATA statement

    where level 01 is defined by 01 RPC-CNTX-AREA, and specify the following parameters on level 02:

    Parameter Format I/O Description
    FUNCTION A02 I
    'SL' Set the RPC context depending on the parameters given and log on to EntireX Broker.
    'SC' Set the RPC context depending on the parameters given.
    'GC' Get RPC context. By default, the required information relates to the default server.
    'LO' Log on to EntireX Broker
    'LF' Log off from EntireX Broker
    BROKERID A dynamic I/O Specify the broker name.

    See the keyword subparameter SRVNODE of the RPC profile parameter.

    CLASS A32 I Specify the server class. For Natural RPC servers, this is RPC. See the keyword subparameter SRVNAME of the RPC profile parameter.
    SERVER A32 I/O Specify the server name. See the keyword subparameter SRVNAME of the RPC profile parameter.
    SERVICE A32 I Specify the type of RPC. For Natural RPC servers, this is CALLNAT.
    COMPRESSLEVEL A01 I/O Compression level requires API version 7.
    RESERVED I01 I/O Reserved for future use.
    RPC-LIBRARY A08 I  
    RPC-RELIABLE-STATE N01 I/O
    0 No reliable RPC (standard RPC execution)
    1 Reliable RPC (AUTO_COMMIT)
    2 Reliable RPC (Client_COMMIT)
    NAT-LOGON A011 I/O  
    EXX-USERID A32 I  
    EXX-PASSWORD A32 I  
    RPC-USERID A32 I  
    RPC-PASSWORD A32 I  
    ERR-CODE I04 O The origin of some error code can be detected by the following identifiers:
    USR1071N,(USR4371N) 1nnnn
    USR6304N 2nnnn
    USR2007N 3nnnn
    USR4008N 5nnnn
    USR4009N 8nnnn
    USR2071N 9nnnn
    ERR-TEXT A dynamic O  
    RPC-ETID A08 I Allow impersonation without password verification (optional).

    Note:
    The most important function codes are 'SL' and 'LF'. Function code 'SL' is a combination of setting the RPC context ('SC') and a logon to EntireX Broker ('LO').

  2. In the calling program on the client side, specify the following statement: 

    CALLNAT 'RPC-CNTX' RPC-CNTX-AREA

    For further information refer to Syntax Description in CALLNAT in the Statements documentation.

The setting of the RPC context is processed as follows:

  1. Set the credentials for RPC server by specifying RPC-USERID and RPC-PASSWORD (API USR1071N).

  2. Set the mode for reliable RPC by specifying RPC-RELIABLE-STATE (API USR6304N).

  3. Set the data for the RPC default server including the logon option with a specification for BROKERID, SERVER and NAT-LOGON (API USR2007N).

  4. Change the library name on the RPC server for the logon by specifying RPC-LIBRARY (API USR4008N). If the name is left blank, the API is not called.

  5. Set parameters for EntireX COMPRESSLEVEL by using API USR4009N. If no values are specified, the API is not called.

  6. Optionally, set an ETID by specifying RPC-ETID (API USR4371N) if impersonation without password check is active for the Natural RPC server.

  7. For logging on to the EntireX Broker, specify BROKERID, EXX-USERID, and EXX-PASSWORD, which are then passed to USR2071N.

After you have finished your work with the RPC connection, you need to log off from the EntireX Broker using RPC-CNTX with function code 'LF'.

Table of APIs related to RPC in Library SYSEXT

Entries with a hyperlink correspond to APIs that are documented in the Natural documentation. You can also find a description of an API in library SYSEXT under the name USRnnnnT. The raw content of the table was generated by running SYSEXT with keyword RPC:

API name Description
USR1071N Set credentials for RPC server. Send logon data to the Natural RPC server if the client has no NSC, or if the client has NSC: for using a different user ID and password on server side.
USR2007N Get or set data for RPC default server, including the logon option.
USR2032N Support commit for CLOSE CONVERSATION.
USR2035N Get or set parameters for SSL support.
USR2071N Support EntireX Security on client side. Logon to EntireX Broker.
USR2072N Support EntireX Security on server side. Specify a password which is used for the LOGON in conjunction with keyword subparameter SRVUSER.
USR2073N Ping or terminate a Natural RPC server.
USR2074N Change the Natural Security password on the Natural RPC server.
USR2075N Terminate an EntireX Broker Service.
USR2076N Get or set RPC TIMEOUT value.
USR4008N Pass another library name to the Natural RPC server to log on to.
USR4009N Set parameters for EntireX.
USR4010N Get runtime settings of RPC server.
USR4012N Set application error on RPC server.
USR4371N If impersonation without password verification is active for the Natural RPC server, the client can optionally pass an ETID to the Natural RPC server.
USR6304N Set/Get the mode for reliable RPC.
USR6305N Commit or roll back a unit of work that has been created with CLIENT_COMMIT.
USR6306N Get the status of all reliable RPC messages that you have previously sent under your user ID.
USR8208N Terminate EntireX Broker service. Pings or terminates an RPC server or terminates an EntireX Broker service. Displays the EntireX Broker version and other information from the EntireX Broker Command and Information Service (CIS).