Quick Reference

API Data Descriptions for the C Wrapper

This document describes the client API data structures available for the C Wrapper and covers the following topics:

Conventions Used for API Data Descriptions

The following naming conventions are used to describe the EntireX RPC API data structures:

Naming Convention Data Type
ulXXXXX unsigned long
usXXXXX unsigned short
uXXXXX unsigned ... (predefined types such as ptrdiff_t)
szXXXXX zero terminated string
pXXXXX pointer to ...

API Data Descriptions

ERX_CLIENT_IDENTIFICATION

typedef  struct                 tagERX_CLIENT_IDENTIFICATION
{
   const char    * pUserId;           /* string, required max [32 + 1] bytes */
   const char    * pPassword;         /* string, any length */
   const char    * pToken;            /* string, max [32 + 1] bytes */
   const char    * pNewPassword;      /* string, any length */
   const char    * pRpcUserId;        /* string, any length */
   const char    * pRpcPassword;      /* string, any length */
   const char    * pSSLParameter;     /* string, any length */
   char            szSecurityToken     [ ERX_MAX_SECURITY_TOKEN_LENGTH + 1 ];
   char            cForceLogon;
   unsigned char   uEncryptionLevel;  /* Deprecated. Use AT-TLS on z/OS
                                         ATLS on z/VSE or SSL/TLS on
                                         other platforms. */
   unsigned char   uCompressionLevel;
}  ERX_CLIENT_IDENTIFICATION;
Field Description More Information
*pUserId Mandatory. The user ID for access to the broker. Using the Broker and RPC User ID/Password
*pPassword Optional. The password for secured access to the broker.
*pToken Optional. Token used by the EntireX Broker to identify the caller. USER-ID and TOKEN under Writing Client and Server Applications in the ACI Programming documentation
*pNewPassword Optional. For changing the password to a new password. Changing your Password under Writing Applications using EntireX Security
*pRpcUserId Optional. The RPC user ID sent to the RPC server. Using the Broker and RPC User ID/Password
*pRpcPassword Optional. The RPC password sent to the RPC server.
*pSSLParameter Secure Sockets Layer settings are provided here as a null-terminated string. Using SSL/TLS
szSecurityToken Security token generated by EntireX Security and EntireX Broker after successful security validation. Role of Security Token (STOKEN) during Authentication under Writing Applications using EntireX Security
cForceLogon Mandatory. Determines whether explicit logon or autologon is used by the caller. FORCE-LOGON under Writing Applications using EntireX Security
uEncryptionLevel Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.  
uCompressionLevel Optional. Data Compression under Writing Client and Server Applications in the ACI Programming documentation

ERX_SERVER_ADDRESS

typedef  struct              tagERX_SERVER_ADDRESS
{
   ERXeMedium Medium;
   unsigned long             ulTimeOut;
   union 
   {
  
     ERX_SA_BROKER           BROKER;
     ERX_SA_BROKER_LIBRARY   BROKER_Library;
     ERX_SA_CONNECTION       Connection;

   }  Address;
}  ERX_SERVER_ADDRESS;
Field Description
Medium Mandatory.
Selects an RPC server.
The following types are supported:
ERX_TM_BROKER ( for backward compatibility)
ERX_TM_BROKER_LIBRARY
ERX_TM_CONNECTION
This type of medium is used for the connection-oriented (conversational) RPC. After successful ERXConnect (that is, after opening the conversation), the RPCs are invoked using ERX_TM_CONNECTION. Any open conversation must be closed with ERXDisconnectCommit or aborted with ERXDisconnect.
ulTimeOut Mandatory.
Gives the timeout value for the transport system in seconds.
Corresponds to the WAIT field of the ACI control block.

Note:
Zero is not a valid value.

Address

Depending on the Medium field, the Address union holds the necessary information to address a server:

BROKER
szEtbidName Mandatory.
Broker ID used. Corresponds to the BROKER-ID field of the ACI control block.
szClassName Mandatory.
Class Name of the EntireX/Natural RPC server. Use RPC for Natural RPC Server. Corresponds to the SERVER-CLASS field of the ACI control block.
szServerName Mandatory.
Server Name of the EntireX/Natural RPC server. Corresponds to the SERVER-NAME field of the ACI control block.
szServiceName Mandatory.
Service Name of the EntireX/Natural RPC server. Use CALLNAT for Natural RPC Server. Corresponds to the SERVICE field of the ACI control block.
BROKER_LIBRARY
szEtbidName Mandatory.
Broker ID used. Corresponds to the BROKER-ID field of the ACI control block.
szClassName Mandatory.
Class Name of the EntireX/Natural RPC server. Use RPC for Natural RPC Server. Corresponds to the SERVER-CLASS field of the ACI control block.
szServerName Mandatory.
Server Name of the EntireX/Natural RPC server. Corresponds to the SERVER-NAME field of the ACI control block.
szServiceName Mandatory.
Service Name of the EntireX/Natural RPC server. Use CALLNAT for Natural RPC Server. Corresponds to the SERVICE field of the ACI control block.
szLibraryName Mandatory.
Library sent to the target RPC server by the client.

The library specified here overrides any library information specified in the IDL file, see library-definition. Usage depends on the target RPC server type:

  • Natural RPC server
    Set cNaturalLogon (see below) to Y for library usage, that is, log on to the library.

  • EntireX RPC server
    The library given here is used.

cNaturalLogon Enable to send the RPC user ID/password pair. For more information see Using the Broker and RPC User ID/Password. Valid values: Y,N. Use the macro definition ERX_NATURAL LOGON_YES and ERX_NATURAL LOGON_NO from erx.h to set the values.
cCompression Mandatory. Specify ERX_COMPRESSION_YES always.

Note:
Data Compression in EntireX Broker is something different and is controlled by field uCompressionLevel in API structure ERX_CLIENT_IDENTIFICATION.

Connection
Contains internal information for EntireX runtime.
Warning:
Do not modify

ERX_CALL_IDENTIFICATION

typedef     struct         tagERX_CALL_IDENTIFICATION
{
   char     szLibraryName  [ ERX_MAX_LIBRARY_NAME_LENGTH + 1 ];
   char     szProgramName  [ ERX_MAX_PROGRAM_NAME_LENGTH + 1 ];
   unsigned long           ulVersion;
}  ERX_CALL_IDENTIFICATION;
Field Description
szLibraryName The name of the library where the program to be called resides. The format depends on the environment. For a mainframe Natural server, for example, the name of the library must be uppercase.
szProgramName The name of the program to be called. The format depends on the environment. For a mainframe Natural server, for example, the name of the program must be uppercase.
ulVersion Reserved for future use, should be set to zero.

ERX_PARAMETER_DEFINITION_V3

typedef                     struct             tagERX_PARAMETER_DEFINITION
{
   char                     szParameterName    [ ERX_MAX_PARAMETER_NAME_LENGTH + 1 ];
   ERXeTypeCode             usType;
   ERXeAttributes           usAttributes;
   size_t                   uElementLength;
   ERX_OBJECT_SIZE          uSize
   unsigned long            uParent;
   unsigned long            uOccurrence        [ ERX_MAX_INDICES ];
   ERX_POINTER_DIFFERENCE   uBase;
   ERX_POINTER_DIFFERENCE   uDelta             [ ERX_MAX_INDICES ];
   void                     *pCallInfoBlock;
}  ERX_PARAMETER_DEFINITION_V3;
Field Description
szParameterName The name of the parameter.
usType The data type including parameter type direction and index count. See IDL Data Types.
Bits: 
FEDCBA9876543210
UUUUUUTTTTTTDDNN

U: Unused
T: Type Code
ERX_TYPE_A, STRING FIXED LENGTH
ERX_TYPE_AV, STRING VARIABLE LENGTH
ERX_TYPE_K, KANJI FIXED LENGTH
ERX_TYPE_KV, KANJI VARIABLE LENGTH
ERX_TYPE_L, LOGICAL
ERX_TYPE_I, INTEGER
ERX_TYPE_N, UNPACKED DECIMAL
ERX_TYPE_NU, UNPACKED DECIMAL UNSIGNED
ERX_TYPE_P, PACKED DECIMAL
ERX_TYPE_PU, PACKED DECIMAL UNSIGNED
ERX_TYPE_F, FLOAT
ERX_TYPE_T, DATE & TIME
ERX_TYPE_D, DATE
ERX_TYPE_B, BINARY FIXED LENGTH
ERX_TYPE_BV, BINARY VARIABLE LENGTH
ERX_TYPE_G, GROUP
ERX_TYPE_S, STRUCTURES
ERX_TYPE_U, UNICODE FIXED LENGTH
ERX_TYPE_UV, UNICODE VARIABLE LENGTH
D: Parameter Direction
ERX_IN_PARM
ERX_OUT_PARM
ERX_INOUT_PARM
N: Index Count ( 0 .. 3 ) All other bits must be zero.

usAttributes Attributes can be combined by OR when they are not exclusive, such as ERX_ATTR_STRING and ERX_ATTR_MF_ALPHA. For a list of Attributes see the following table.
uElementLength Information on the logical length of the parameter. For ERX_TYPE_A, for example, A10 in the IDL file has a uElementLength of 11 when mapped to string with ERX_ATTR_STRING. It has a uElementLength of 10 when mapped with ERX_ATTR_MF_ALPHA.
uSize The physical size of the parameter in bytes.
uOccurrence The count of elements in each dimension in ascending order.

For unbounded arrays: when set presents a possible maximum. Unbounded arrays with value zero have no maximum.

uBase The address of the base of the parameter.
uDelta The difference for each dimension between following elements in ascending order.
uCallInfoBlock Pointer to CallInfoBlock for structures ERX_TYPE_S.

Attributes

Attribute Description
ERX_ATTR_ARRAY_V1 First dimension of array is unbounded. Attribute evaluated by Software AG IDL Compiler.
ERX_ATTR_ARRAY_V2 Second dimension of array is unbounded. Attribute evaluated by Software AG IDL Compiler.
ERX_ATTR_ARRAY_V3 Third dimension of array is unbounded. Attribute evaluated by Software AG IDL Compiler.
ERX_ATTR_ALIGNED The parameter is aligned on the server side. The attribute is evaluated by the Software AG IDL Compiler. Used by EntireX RPC server on CICS.
ERX_ATTR_DOUBLE The parameter is mapped to C data type double. Valid for:

  • ERX_TYPE_P

  • ERX_TYPE_PU

  • ERX_TYPE_N

  • ERX_TYPE_NU

The mapping can be forced by a template by adding 32768 to the %TypeAttribute macro of the Software AG IDL Compiler.

ERX_ATTR_PACKED The parameter is mapped to C data type char[...] contained in IBM mainframe packed format. Valid for:

  • ERX_TYPE_P

  • ERX_TYPE_PU

Default mapping for P and PU data types; used when nothing is added to the %TypeAttribute.

ERX_ATTR_UNPACKED The parameter is mapped to C data type char[...] contained in IBM mainframe packed format. Valid for:

  • ERX_TYPE_N

  • ERX_TYPE_NU

Default mapping for N and NU data types; used when nothing is added to the %TypeAttribute.

ERX_ATTR_STRING The parameter is mapped to a null terminated string. Valid for

  • ERX_TYPE_A

The mapping can be forced by a template by adding 16384 to the %TypeAttribute macro of the Software AG IDL Compiler.
ERX_ATTR_MF_ALPHA The parameter is mapped to C data type char[...] - but without a NULL terminator. Valid for:

  • ERX_TYPE_A

Default attribute for A data types; is used when nothing is added to the %TypeAttribute.

ERX_ATTR_NOTHING Use when none of the mappings described above apply.

ERX_CALL_INFORMATION_BLOCK

typedef  struct                        tagERX_CALL_INFORMATION_BLOCK
{
   ERX_CALL_IDENTIFICATION             Callee;
   unsigned short                      uParameterCount;
   ERX_PARAMETER_DEFINITION_V3         *pParmDef;
}  ERX_CALL_INFORMATION_BLOCK;
Field Description
Callee The identification of the program to be called, see ERX_CALL_IDENTIFICATION
uParameterCount The total count of the parameters (the number of entries in the parameter definition array).
pParmDef A pointer to the parameter definition array. See ERX_PARAMETER_DEFINITION_V3_V3

ERX_ERROR_INFORMATION

typedef  struct          tagERX_ERROR_INFO
{
   ERXeReturnCode        rc;
   char                  szMessage[ 256 ];
}  ERX_ERROR_INFO;
Field Description
rc The last return code returned. See Error Messages and Codes.
szMessage Error message. Text associated with the last return code issued.

ERX_IS_SERVING

typedef struct          tagERX_IS_SERVING
{
   char                 *pMessage;
   int                  uMessageLength;
}  ERX_IS_SERVING;
Field Description
pMessage Pointer to the provided buffer for server's "alive" message.
uMessageLength Length of the provided buffer.

ERX_TERMINATE_SERVER

typedef  enum
{
   ERX_SHUTDOWN_IMMED_ALL = 1,
   ERX_SHUTDOWN_ANYONE = 2 
}  ERXeShutdownCommand;

typedef struct tagERX_TERMINATE_SERVER
{
   ERXeShutdownCommand       eShutdownCommand;
   char                      *pMessage;
   int                       uMessageLength;
}  ERX_TERMINATE_SERVER;
Field Description
eShutdownCommand The shutdown method to be used.

  • ERX_SHUTDOWN_IMMED_ALL
    Using EntireX Broker Command Service. Using this method forces all instances of RPC servers (Java, Natural, UNIX, Windows, CICS, etc.) to be shut down.

  • ERX_SHUTDOWN_ANYONE
    Directly to EntireX RPC Server. If multiple instances of RPC servers (Java, Natural, UNIX, Windows, CICS, etc.) are registered under the same class/server/service name at the broker, only one single RPC server instance is shut down. There is no control over which instance is shut down. To shut down all RPC server instances, you have to repeat the function until no more RPC server instances are registered. This method is compatible with the method from versions of EntireX RPC prior to EntireX 5.3.1.

pMessage Pointer to the provided buffer for server's "completion" message.
uMessageLength Length of the provided buffer.

ERX_CONTEXT_BLOCK

typedef struct tagERX_CONTEXT_BLOCK
{
   ERXCallId                   ERXCallId;
   ERXeReturnCode              ERXrc;
   ERX_ERROR_INFO              ERXErrorInfo;
   ERX_SERVER_ADDRESS          ERXServer;
   ERX_CLIENT_IDENTIFICATION   ERXClient;
}  ERX_CONTEXT_BLOCK;
Field Description
ERXCallId The CallId returned by a caller.
ERXrc EntireX RPC Error Code. See Error Messages and Codes.
ERXErrorInfo EntireX RPC Error information, see ERX_ERROR_INFORMATION.
ERXServer The server address, see ERX_SERVER_ADDRESS.
ERXClient The client identification, see ERX_CLIENT_IDENTIFICATION.

ERX_SVM_VERSION_1

#define ERX_SVM_VERSION_1 (unsigned long) 1
typedef struct tagERX_SVM_V1
{
   unsigned long  version;
   char          *pProtocol; 
   char          *pSM;
   char          *pFA;
   char          *pVA;
   char          * pSA;
}  ERX_SVM_V1;
Field Description
version Version of this control block. Initialitze with ERX_SVM_VERSION_1.
pProtocol RPC protocol version from the related server mapping file (Designer file with extension .cvm) evaluated by the Software AG IDL Compiler and provided in the output_substitution_sequence %SVMRpcProtocol.
pSM Pointer to the meta data part of the related server mapping file evaluated by the IDL Compiler and provided in the output_substitution_sequence %SVMMetaData.
pFA Pointer to the format area of the related server mapping file evaluated by the IDL Compiler and provided in the output_substitution_sequence %SVMFormatArea.
pSA Pointer to the string area of the related server mapping file evaluated by the IDL Compiler and provided in the output_substitution_sequence %SVMStringArea.