Version 9.5 SP1
 —  ACI for C  —

EntireX Broker ACI for C

ACI-based programming is the base technology of EntireX. It uses a traditional Application Programming Interface (API) approach for conducting client/server and peer-to-peer dialog between distributed processes.

This document describes the EntireX Broker ACI from the perspective of the programming language C. It covers the following topics:


Call Format

Calls to EntireX Broker use the following arguments:

  1. The ACI control block is the first argument.

  2. The send buffer is the second argument.

  3. The receive buffer is the third argument.

  4. The error text buffer is the last argument. It can provide a short text of the error code, if desired. Sufficient buffer length must be supplied to allow the standard 40-byte long message to be returned by EntireX Broker. For ACI version 9 and above, the error text buffer can be greater than 40 bytes as specified in the ACI field ERRTEXT-LENGTH.

You can set the send buffer and the receive buffer to null if they are not required by the selected EntireX Broker function.

The API is called with a statement such as the following:

If the Broker stub is used as a function, the stub returns the last four bytes of the ERROR-CODE field in the EntireX Broker control block, i.e. the error number.

If 0 (zeros) are returned in the ERROR-CODE field in all positions of the character array, the operation has been performed successfully. However, function results other than 0 (zeros) in all positions do not necessarily indicate an error. See Error Handling for client and server | publish and subscribe.

Top of page

Broker ACI Control Block Layout

The following table shows the Broker fields in order of the physical layout of the Broker ACI control block and provides a brief description of each field. The fields are described in more detail under Broker ACI Fields. See the actual layout for C in Broker ACI Control Block Definition below.

Note:
Header files and examples are provided as models if you want to write your own ACI appliations (see ACI Examples and Header Files for location). The list below does not include unused fields that are for internal purposes only. Check the included header files for the full layout.

Broker ACI Field C Definition Description /
Related Information
API
Vers.
Notes
API-TYPE ETB_BYTE api_type API type See API-TYPE and API-VERSION for client and server | publish and subscribe. 1  
API-VERSION ETB_BYTE api_version API version. 1  
FUNCTION ETB_BYTE function See Broker ACI Fields. 1  
OPTION ETB_BYTE option See OPTION under Broker ACI Fields. 1  
  ETB_CHAR reserved1[16] Reserved for future use. 1 1
SEND-LENGTH ETB_LONG send_length Send length See Using Send and Receive Buffers for client and server | publish and subscribe. 1  
RECEIVE-LENGTH ETB_LONG receive_length Receive length. 1  
RETURN-LENGTH ETB_LONG return_length Return length. 1  
ERRTEXT-LENGTH ETB_LONG errtext_length Error text length. 1  
BROKER-ID ETB_CHAR broker_id[S_BROKER_ID] Broker ID. See Using the Broker ID in Applications. 1  
SERVER-CLASS
SERVER-NAME
SERVICE
ETB_CHAR server_class[S_SERVER-CLASS]
ETB_CHAR server_name[S_SERVER-NAME]
ETB_CHAR service[S_SERVICE]
Service. See Control Block Fields and Verbs. 1 3, 5
USER-ID ETB_CHAR user_id[S_USER_ID] User ID. See USER-ID and TOKEN for client and server | publish and subscribe. 1  
PASSWORD ETB_CHAR password[S_PASSWORD] Password. See Authentication. 1 4,5
TOKEN ETB_CHAR token[S_TOKEN] Reconnection token. See USER-ID and TOKEN for client and server | publish and subscribe. 1 3, 5
SECURITY-TOKEN ETB_CHAR security_token[S_securityToken] Security token. See Writing Applications using EntireX Security. 1 4, 5
CONV-ID ETB_CHAR conv_id[S_CONV_ID] Conversation ID. See Conversational and Non-conversational Mode. 1 3, 5
WAIT ETB_CHAR wait[S_WAIT] Wait value. See Blocked and Non-blocked Broker Calls for client and server | publish and subscribe. 1 3, 5
ERROR-CODE ETB_CHAR error_code[S_ERROR_CODE] Error code. See Error Handling for client and server | publish and subscribe. 1  
ENVIRONMENT ETB_CHAR environment[S_ENVIRONMENT] Environment. See Using Internationalization for client and server | publish and subscribe. 1 3, 5
ADCOUNT ETB_LONG adcount Attempted delivery count. See Writing Applications: Units of Work. 2  
USER-DATA ETB_CHAR user_data[S_USERDATA] Conversation User Data. See Writing Applications: Client and Server. 2 3, 5
  ETB_CHAR ptime[S_PTIME] Reserved for future use. 2 1, 3, 5
NEWPASSWORD ETB_CHAR newpassword[S_PASSWORD] New password. See Writing Applications using EntireX Security. 2 4, 5
CLIENT-UID ETB_CHAR client_uid[S_CLIENTUID] Client User ID. See Client User ID. 2  
CONV-STAT ETB_BYTE conv_stat Conversation status. See Conversational and Non-conversational Mode. 2  
STORE ETB_BYTE store Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. 2  
  ETB_BYTE status Reserved for future use. 2 1
UOWSTATUS ETB_BYTE uowStatus UOW Status. See Writing Applications: Units of Work. 3 3, 5
UWTIME ETB_CHAR uowTime[S_WAIT] UOW lifetime. 3 3, 5
UOWID ETB_CHAR uowID[S_UOW_ID] UOW unique identifier. 3 3, 5
USTATUS ETB_CHAR userStatus[S_U_STATUS] User status. 3  
UOW-STATUS-PERSIST ETB_BYTE uowStatusPersist Multiplier for persistent status lifetime. 3 2
  ETB_CHAR reserved2[3] Reserved for future use. 3 1
LOCALE-STRING ETB_CHAR locale_string[S_LOCALE] Locale string. To be used to override or provide codepages. See Using Internationalization for client and server | publish and subscribe. 4  
DATA-ARCH ETB_BYTE data_arch Data architecture. See ICU Conversion. 4 2
FORCE-LOGON ETB_CHAR forceLogon Override Broker attribute AUTOLOGON. See Writing Applications using EntireX Security 6  
ENCRYPTION-LEVEL ETB_BYTE encryptionLevel Encryption level. 6 2
KERNELSECURITY ETB_CHAR kernelsecurity Kernel security. 7  
COMMITTIME ETB_CHAR commitTime[S_COMMIT_TIME] Commit time. See Writing Applications: Units of Work. 7  
COMPRESSLEVEL ETB_CHAR compress
Compression level. See Data Compression for client and server | publish and subscribe. 7  
  ETB_BYTE reserved3[2]
Reserved for future use. 8 1
  ETB_LONG reserved4
Reserved for future use. 8 1
UWSTAT-LIFETIME ETB_CHAR uwStatLifeTime[S_WAIT] Add value for persistent status lifetime. See broker attribute UWSTAT-LIFETIME. 8  
TOPIC ETB_CHAR topic[S_TOPIC] Topic name for publish and subscribe. See Writing Applications: Publish and Subscribe. 8  
PUBLICATION-ID ETB_CHAR publicationID[S_PUBLICATION_ID] Publication ID for publish and subscribe. 8  
CLIENT-ID ETB_LONG client_id Returns to a server application the unique instance number of a client application. It is returned on receipt of a message (RECEIVE or SEND with WAIT). 9  
LOG-COMMAND ETB_BYTE logCommand Log the current command. See also Programmatically Turning on Command Logging for client and server | publish and subscribe 9  
CREDENTIALS-TYPE ETB_BYTE credentialsType Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. Enter "1" to specify IAF authentication. See also IAF Authentication for client and server | publish and subscribe. 9  
VARLIST-OFFSET ETB_LONG varlist_offset Internal Software AG field. 10  
LONG-BROKER-ID-LENGTH ETB_LONG LONG-BROKER-ID-LENGTH See LONG-BROKER-ID-LENGTH. 10  

Notes:

  1. Reserved for future use.
  2. You must set this field to a low value (0x00) if you do not intend to use it.
  3. The field is transmitted up to the first blank or low value (0x00). It is not transmitted if the first character is a blank or a low value (0x00).
  4. All trailing low values (0x00) are truncated. The field is not transmitted if the entire field is a low value (0x00).
  5. If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or low value (0x00).

Top of page

Broker ACI Control Block Definition

The Developer's Kit provides a header file with the ACI control block definition. See ACI Examples and Header Files for where it is provided on your platform.

/*
***************************************************************************
* Product        : EntireX Broker
* Copyright      : (c) Copyright Software AG 1997 - 2012. All rights reserved.
* Version        : 9.0
* File           : ETBCDEF.H
* File Version   : $Revision: 1.2 $
* Description    : C language ACI control block definitions.
*
*/

#ifndef ETBCDEF__H_
#define ETBCDEF__H_

#ifdef __cplusplus
extern "C" {
#endif

/* --- Type Definitions --------------------------------------------- */

#define ETB_BYTE  unsigned char  /* 1 byte unsigned integer           */
#define ETB_CHAR  char           /* 1 byte character                  */
#define ETB_LONG  int            /* 4 byte signed integer             */
#define ETB_SHORT short          /* 2 byte signed integer             */

/* --- EntireX Broker API Type Constants (api_type) ----------------- */

#define API_TYPE1                      ((ETB_BYTE) 0x01)
#define API_TYPE2                      ((ETB_BYTE) 0x02)
#define API_TYPE4                      ((ETB_BYTE) 0x04)
#define API_TYPE8                      ((ETB_BYTE) 0x08)

/* --- EntireX Broker API Version Constants (api_version) ----------- */

#define API_VERS1                      ((ETB_BYTE) 1)
#define API_VERS2                      ((ETB_BYTE) 2)
#define API_VERS3                      ((ETB_BYTE) 3)
#define API_VERS4                      ((ETB_BYTE) 4)
#define API_VERS5                      ((ETB_BYTE) 5)
#define API_VERS6                      ((ETB_BYTE) 6)
#define API_VERS7                      ((ETB_BYTE) 7)
#define API_VERS8                      ((ETB_BYTE) 8)
#define API_VERS9                      ((ETB_BYTE) 9)
#define API_VERS10                     ((ETB_BYTE) 10)
#define API_VERS_HIGHEST               API_VERS10

/* --- EntireX Broker API API Function Constants (function) --------- */

#define FCT_SEND                       ((ETB_BYTE) 1)
#define FCT_RECEIVE                    ((ETB_BYTE) 2)
#define FCT_UNDO                       ((ETB_BYTE) 4)
#define FCT_EOC                        ((ETB_BYTE) 5)
#define FCT_REGISTER                   ((ETB_BYTE) 6)
#define FCT_DEREGISTER                 ((ETB_BYTE) 7)
#define FCT_VERSION                    ((ETB_BYTE) 8)
#define FCT_LOGON                      ((ETB_BYTE) 9)
#define FCT_LOGOFF                     ((ETB_BYTE) 10)
#define FCT_SET                        ((ETB_BYTE) 11)
#define FCT_GET                        ((ETB_BYTE) 12)
#define FCT_SYNCPOINT                  ((ETB_BYTE) 13)
#define FCT_KERNELVERS                 ((ETB_BYTE) 14)
#define FCT_LOCTRANS                   ((ETB_BYTE) 15)
#define FCT_SETSSLPARMS                ((ETB_BYTE) 16)
#define FCT_SEND_PUBLICATION           ((ETB_BYTE) 17)
#define FCT_RECEIVE_PUBLICATION        ((ETB_BYTE) 18)
#define FCT_SUBSCRIBE                  ((ETB_BYTE) 19)
#define FCT_UNSUBSCRIBE                ((ETB_BYTE) 20)
#define FCT_CONTROL_PUBLICATION        ((ETB_BYTE) 21)
#define FCT_REPLY_ERROR                ((ETB_BYTE) 22)

/* --- EntireX Broker API Option Constants (option) ----------------- */

#define OPT_OFF                        ((ETB_BYTE) 0)
#define OPT_MSG                        ((ETB_BYTE) 1)
#define OPT_HOLD                       ((ETB_BYTE) 2)
#define OPT_IMMED                      ((ETB_BYTE) 3)
#define OPT_QUIESCE                    ((ETB_BYTE) 4)
#define OPT_EOC                        ((ETB_BYTE) 5)
#define OPT_CANCEL                     ((ETB_BYTE) 6)
#define OPT_LAST                       ((ETB_BYTE) 7)
#define OPT_NEXT                       ((ETB_BYTE) 8)
#define OPT_PREVIEW                    ((ETB_BYTE) 9)
#define OPT_COMMIT                     ((ETB_BYTE) 10)
#define OPT_BACKOUT                    ((ETB_BYTE) 11)
#define OPT_SYNC                       ((ETB_BYTE) 12)
#define OPT_ATTACH                     ((ETB_BYTE) 13)
#define OPT_DELETE                     ((ETB_BYTE) 14)
#define OPT_EOCCANCEL                  ((ETB_BYTE) 15)
#define OPT_QUERY                      ((ETB_BYTE) 16)
#define OPT_SETUSTATUS                 ((ETB_BYTE) 17)
#define OPT_ANY                        ((ETB_BYTE) 18)
#define OPT_TERMINATE                  ((ETB_BYTE) 19)
#define OPT_DURABLE                    ((ETB_BYTE) 20)
#define OPT_CHECKSERVICE               ((ETB_BYTE) 21)

/* --- EntireX Broker Environment Constants (environment) ----------- */

#define ETB_ENVIRONMENT_NO_CONVERSION  "NONE"

/* --- EntireX Broker Conversation Status Constants (conv_stat) ----- */

#define CONVSTAT_NEW                   ((ETB_BYTE) 1)
#define CONVSTAT_OLD                   ((ETB_BYTE) 2)
#define CONVSTAT_NONE                  ((ETB_BYTE) 3)

/* --- EntireX Broker Store Constants (store) ----------------------- */

#define STORE_OFF                      ((ETB_BYTE) 1)
#define STORE_BROKER                   ((ETB_BYTE) 2)

/* --- EntireX Broker Status Constants (status) --------------------- */

#define STAT_OFF                       ((ETB_BYTE) 1)
#define STAT_STORED                    ((ETB_BYTE) 2)
#define STAT_DELIVERY_ATTEMP           ((ETB_BYTE) 3)
#define STAT_DELIVERED                 ((ETB_BYTE) 4)
#define STAT_PROCESSED                 ((ETB_BYTE) 5)
#define STAT_DEAD                      ((ETB_BYTE) 6)

/* --- EntireX Broker UOW Status Constants (uowStatus) -------------- */

#define RECV_NONE                      ((ETB_BYTE) 0)
#define RECEIVED                       ((ETB_BYTE) 1)
#define ACCEPTED                       ((ETB_BYTE) 2)
#define DELIVERED                      ((ETB_BYTE) 3)
#define BACKEDOUT                      ((ETB_BYTE) 4)
#define PROCESSED                      ((ETB_BYTE) 5)
#define CANCELLED                      ((ETB_BYTE) 6)
#define TIMEOUT                        ((ETB_BYTE) 7)
#define DISCARDED                      ((ETB_BYTE) 8)
#define RECV_FIRST                     ((ETB_BYTE) 9)
#define RECV_MIDDLE                    ((ETB_BYTE) 10)
#define RECV_LAST                      ((ETB_BYTE) 11)
#define RECV_ONLY                      ((ETB_BYTE) 12)

/* --- EntireX Broker Locale String Constants (locale_string) ------- */

#define ETB_CODEPAGE_USE_PLATFORM_DEFAULT "LOCAL"

/* --- EntireX Broker Architecture Constants (data_arch) ------------ */

#define ACODE_HIGH_ASCII_IBM           ((ETB_BYTE) 1)
#define ACODE_LOW__ASCII_IBM           ((ETB_BYTE) 2)
#define ACODE_HIGH_EBCDIC_IBM          ((ETB_BYTE) 3)
#define ACODE_LOW__EBCDIC_IBM          ((ETB_BYTE) 4)
#define ACODE_HIGH_ASCII_VAX           ((ETB_BYTE) 5)
#define ACODE_LOW__ASCII_VAX           ((ETB_BYTE) 6)
#define ACODE_HIGH_EBCDIC_VAX          ((ETB_BYTE) 7)
#define ACODE_LOW__EBCDIC_VAX          ((ETB_BYTE) 8)
#define ACODE_HIGH_ASCII_IEEE          ((ETB_BYTE) 9)
#define ACODE_LOW__ASCII_IEEE          ((ETB_BYTE) 10)
#define ACODE_HIGH_EBCDIC_IEEE         ((ETB_BYTE) 11)
#define ACODE_LOW__EBCDIC_IEEE         ((ETB_BYTE) 12)
#define ACODE_HIGHEST_VALUE            ((ETB_BYTE) 12)

/* --- EntireX Broker Force Logon Constants (forceLogon) ------------ */

#define FORCE_LOGON_NO                 ((ETB_CHAR) 'N')
#define FORCE_LOGON_YES                ((ETB_CHAR) 'Y')
#define FORCE_LOGON_S                  ((ETB_CHAR) 'S')

/* --- EntireX Broker Encryption Level Constants (encryptionLevel) -- */

#define ENCLEVEL_NONE                  ((ETB_BYTE) 0)
#define ENCLEVEL_TO_BROKER             ((ETB_BYTE) 1)
#define ENCLEVEL_TO_TARGET             ((ETB_BYTE) 2)

/* --- EntireX Broker Kernel Security Constants (kernelSecurity) ---- */

#define KERNEL_SECURITY_NO             ((ETB_CHAR) 'N')
#define KERNEL_SECURITY_YES            ((ETB_CHAR) 'Y')
#define KERNEL_SECURITY_USER           ((ETB_CHAR) 'U')
#define KERNEL_SECURITY_LIGHT          ((ETB_CHAR) 'L')

/* --- EntireX Broker Compression Level Constants (compress) -------- */

#define COMPRESS_LEVEL_0               ((ETB_CHAR) '0')
#define COMPRESS_LEVEL_1               ((ETB_CHAR) '1')
#define COMPRESS_LEVEL_2               ((ETB_CHAR) '2')
#define COMPRESS_LEVEL_3               ((ETB_CHAR) '3')
#define COMPRESS_LEVEL_4               ((ETB_CHAR) '4')
#define COMPRESS_LEVEL_5               ((ETB_CHAR) '5')
#define COMPRESS_LEVEL_6               ((ETB_CHAR) '6')
#define COMPRESS_LEVEL_7               ((ETB_CHAR) '7')
#define COMPRESS_LEVEL_8               ((ETB_CHAR) '8')
#define COMPRESS_LEVEL_9               ((ETB_CHAR) '9')
#define COMPRESS_LEVEL_NO              ((ETB_CHAR) 'N')
#define COMPRESS_LEVEL_YES             ((ETB_CHAR) 'Y')

/* --- EntireX Broker Credentials Type Constants (credentialsType) -- */

#define CREDENTIALS_TYPE_UID_PWD       ((ETB_BYTE) 0)
#define CREDENTIALS_TYPE_IAF           ((ETB_BYTE) 1)

/*--------------------------------------------------------------------*/
/* The first 4 bytes of the first reserved field (reserved) can be    */
/* used to specify a stub trace level                                 */
/*--------------------------------------------------------------------*/

#define STUBLOG_EYECATCHER_ARRAY    'T', 'L', '='
#define STUBLOG_OFF                 '0'
#define STUBLOG_LEVEL0              STUBLOG_OFF
#define STUBLOG_LEVEL1              '1'
#define STUBLOG_LEVEL2              '2'
#define STUBLOG_LEVEL3              '3'
#define STUBLOG_LEVEL4              '4'

/* --- EntireX Broker API Size of fields ---------------------------- */

#define S_ADAPTERR                     ((ETB_CHAR) 8)
#define S_APPLICATION_NAME             ((ETB_CHAR) 64)
#define S_APPLICATION_TYPE             ((ETB_CHAR) 8)
#define S_BROKER_ID                    ((ETB_CHAR) 32)
#define S_CLIENTUID                    ((ETB_CHAR) 32)
#define S_COMMIT_TIME                  ((ETB_CHAR) 17)
#define S_CONV_ID                      ((ETB_CHAR) 16)
#define S_ENVIRONMENT                  ((ETB_CHAR) 32)
#define S_ERROR_CODE                   ((ETB_CHAR) 8)
#define S_ERROR_CLASS                  ((ETB_CHAR) 4)
#define S_ERROR_NUMBER                 ((ETB_CHAR) 4)
#define S_LOCALE                       ((ETB_CHAR) 40)
#define S_MSGID                        ((ETB_CHAR) 32)
#define S_MSGTYPE                      ((ETB_CHAR) 16)
#define S_NODENAME                     ((ETB_CHAR) 32)
#define S_PASSWORD                     ((ETB_CHAR) 32)
#define S_PLATFORM                     ((ETB_CHAR) 8)
#define S_PRODUCT_VERSION              ((ETB_CHAR) 16)
#define S_PTIME                        ((ETB_CHAR) 8)
#define S_PUBLICATION_ID               ((ETB_CHAR) 16)
#define S_PUID                         ((ETB_CHAR) 28)
#define S_SECURITY_TOKEN               ((ETB_CHAR) 32)
#define S_SERVER_CLASS                 ((ETB_CHAR) 32)
#define S_SERVER_NAME                  ((ETB_CHAR) 32)
#define S_SERVICE                      ((ETB_CHAR) 32)
#define S_T_NAME                       ((ETB_CHAR) 8)
#define S_TOKEN                        ((ETB_CHAR) 32)
#define S_TOPIC                        ((ETB_CHAR) 96)
#define S_TXT                          ((ETB_CHAR) 40)
#define S_U_STATUS                     ((ETB_CHAR) 32)
#define S_UOW_ID                       ((ETB_CHAR) 16)
#define S_USER_ID                      ((ETB_CHAR) 32)
#define S_USRDATA                      ((ETB_CHAR) 16)
#define S_VERS                         ((ETB_CHAR) 8)
#define S_WAIT                         ((ETB_CHAR) 8)
#define S_BROKER_URL                   ((ETB_SHORT) 512)

/*--------------------------------------------------------------------*/
/* ETBCB: EntireX Broker API Control Block Definition                 */
/* (The current size is 880 bytes)                                    */
/*--------------------------------------------------------------------*/

typedef struct
{
  ETB_BYTE  api_type;                        /* v1: Type of ETBCB            */
  ETB_BYTE  api_version;                     /* v1: For compatibility        */
  ETB_BYTE  function;                        /* v1: Function                 */
  ETB_BYTE  option;                          /* v1: Option                   */
  ETB_CHAR  reserved[16];                    /* v1: Reserved for future use  */
  ETB_LONG  send_length;                     /* v1: Length of data to send   */
  ETB_LONG  receive_length;                  /* v1: Maximum receive length   */
  ETB_LONG  return_length;                   /* v1: Length of received data  */
  ETB_LONG  errtext_length;                  /* v1: Errortext buffer length  */
  ETB_CHAR  broker_id[S_BROKER_ID];          /* v1: Target broker id         */
  ETB_CHAR  server_class[S_SERVER_CLASS];    /* v1: Part of service name     */
  ETB_CHAR  server_name[S_SERVER_NAME];      /* v1: Part of service name     */
  ETB_CHAR  service[S_SERVICE];              /* v1: Part of service name     */
  ETB_CHAR  user_id[S_USER_ID];              /* v1: User id of caller        */
  ETB_CHAR  password[S_PASSWORD];            /* v1: Password of caller       */
  ETB_CHAR  token[S_TOKEN];                  /* v1: Special purposes         */
  ETB_CHAR  security_token[S_SECURITY_TOKEN];/* v1: Security purposes        */
  ETB_CHAR  conv_id[S_CONV_ID];              /* v1: Conversational/non-conv. */
  ETB_CHAR  wait[S_WAIT];                    /* v1: Blocked/non-blocked      */
  ETB_CHAR  error_code[S_ERROR_CODE];        /* v1: Error class/number       */
  ETB_CHAR  environment[S_ENVIRONMENT];      /* v1: Translation purposes     */
  ETB_LONG  adcount;                         /* v2: Attempted deliv. count   */
  ETB_CHAR  user_data[S_USRDATA];            /* v2: User data field          */
  ETB_CHAR  msg_id[S_MSGID];                 /* v2: Not used by Broker       */
  ETB_CHAR  msg_type[S_MSGTYPE];             /* v2: Not used by Broker       */
  ETB_CHAR  ptime[S_PTIME];                  /* v2: Not used by Broker       */
  ETB_CHAR  newpassword[S_PASSWORD];         /* v2: New password of caller   */
  ETB_CHAR  adapt_err[S_ADAPTERR];           /* v2: Adapter error            */
  ETB_CHAR  client_uid[S_CLIENTUID];         /* v2: Userid for security      */
  ETB_BYTE  conv_stat;                       /* v2: Conversation status      */
  ETB_BYTE  store;                           /* v2: Flag for saving data     */
  ETB_BYTE  status;                          /* v2: Not used by Broker       */
  ETB_BYTE  uowStatus;                       /* v2: UOW's status             */
  ETB_CHAR  uowTime[S_WAIT];                 /* v3: Lifetime of UOW in secs  */
  ETB_CHAR  uowID[S_UOW_ID];                 /* v3: UOW ID                   */
  ETB_CHAR  userStatus[S_U_STATUS];          /* v3: User Status              */
  ETB_BYTE  uowStatusPersist;                /* v3: UOW Status persist flag  */
  ETB_CHAR  reserved2[3];                    /* v3: Alignment                */
  ETB_CHAR  locale_string[S_LOCALE];         /* v4: Callers set_locale (ECS) */
  ETB_BYTE  data_arch;                       /* v4: For future use           */
  ETB_CHAR  forceLogon;                      /* v6: Force logon              */
  ETB_BYTE  encryptionLevel;                 /* v6: End-to-end encryption    */
  ETB_CHAR  kernelsecurity;                  /* v7: Security indicator       */
  ETB_CHAR  commitTime[S_COMMIT_TIME];       /* v7: UOW commit time          */
  ETB_CHAR  compress;                        /* v7: Compression level        */
  ETB_BYTE  reserved3[2];                    /* v7: Alignment                */
  ETB_LONG  reserved4;                       /* v7: Reserved for future use  */
  ETB_CHAR  uwStatLifeTime[S_WAIT];          /* v8: UowStatusLifetime:adder  */
  ETB_CHAR  topic[S_TOPIC];                  /* v8: Topic name               */
  ETB_CHAR  publicationID[S_PUBLICATION_ID]; /* v8: Publication ID           */
  ETB_CHAR  partner_broker_id[S_BROKER_ID];  /* v9: Partner broker id        */
  ETB_LONG  reserved_etbcb_v73_1;            /* v9: Reserved for future use  */
  ETB_LONG  reserved_etbcb_v73_2;            /* v9: Reserved for future use  */
  ETB_LONG  reserved_etbcb_v73_3;            /* v9: Reserved for future use  */
  ETB_LONG  client_id;                       /* v9: Unique client identifier */
  ETB_CHAR  reserved_etbcb_v73_4[32];        /* v9: Reserved for future use  */
  ETB_BYTE  logCommand;                      /* v9: Broker command logging   */
  ETB_BYTE  credentialsType;                 /* v9: Credentials type         */
  ETB_CHAR  reserved_etbcb_v73_5[32];        /* v9: Reserved for future use  */
  ETB_BYTE  reserved5[2];                    /* v9: Alignment                */
  ETB_LONG  varlist_offset;                  /*v10: Variable list offset     */
  ETB_LONG  long_broker_id_length;           /*v10: Length long broker id    */
} ETBCB;

/*--------------------------------------------------------------------*/
/* ATMCB: Attach Manager Control Block                                */
/*--------------------------------------------------------------------*/

typedef struct
{
  ETB_SHORT atm_version;                     /* Version of structure         */
  ETB_SHORT atm_NotUsed;                     /* Alignment                    */
  ETB_LONG  atm_nAttach;                     /* # of failed Server lookups   */
  ETB_LONG  atm_nServer;                     /* # of Registered Servers      */
  ETB_LONG  atm_nPendConv;                   /* # of Pending Conversations   */
  ETB_LONG  atm_nActvConv;                   /* # of Active  Conversations   */
  ETB_CHAR  atm_server_class[S_SERVER_CLASS];/* Class to attach              */
  ETB_CHAR  atm_server_name[S_SERVER_NAME];  /* Server name to attach        */
  ETB_CHAR  atm_service[S_SERVICE];          /* Service name to attach       */
} ETB_ATMCB;

/* --------------- EntireX Broker API ------------------------------- */

#if(( __MVS__ && ( defined( __IBMC__ ) || defined( __IBMCPP__ ))) || __VSE__ )
#pragma map( broker, "BROKER" )
#endif

#if defined( __SNI )
# define broker BROKER
extern ETB_LONG BROKER( ETBCB*, ETB_CHAR*, ETB_CHAR*, ETB_CHAR* );

#elif defined( _WIN32 )
extern ETB_LONG __cdecl broker( ETBCB*, ETB_CHAR*, ETB_CHAR*, ETB_CHAR* );

#else
extern ETB_LONG broker( ETBCB*, ETB_CHAR*, ETB_CHAR*, ETB_CHAR* );
#endif

typedef ETB_LONG
#if defined( _WIN32 )
(__cdecl *PFBROKER)
#else
(*PFBROKER)
#endif
( ETBCB*, ETB_CHAR*, ETB_CHAR*, ETB_CHAR* );

#if defined( _WIN32 )
# define ETB_SHARED_LIBRARY_A "broker.dll"
# define ETB_SHARED_LIBRARY_W L"broker.dll"
# if defined( UNICODE )
#  define ETB_SHARED_LIBRARY ETB_SHARED_LIBRARY_W
# else
#  define ETB_SHARED_LIBRARY ETB_SHARED_LIBRARY_A
# endif

#elif( defined( __hpux ) && !defined( __ia64 ))
# define ETB_SHARED_LIBRARY "broker.sl"

#elif defined( __SNI )
# define ETB_SHARED_LIBRARY "BROKER2 "
# define ETB_BATCH_LOAD_MODULE "BROKER  "

#elif( __MVS__ )
# define ETB_SHARED_LIBRARY "BROKER2 "
# define ETB_BATCH_LOAD_MODULE "BROKER  "
# define ETB_CICS_LOAD_MODULE "CICSETB "

#elif( __VSE__ )
# define ETB_BATCH_LOAD_MODULE "BKIMB   "
# define ETB_CICS_LOAD_MODULE "BKIMC   "

#elif( __VMS )
# define ETB_SHARED_LIBRARY "broker.exe"

#else
# define ETB_SHARED_LIBRARY "broker.so"
#endif

#if( defined( __SNI ) || __MVS__ || __VSE__ )
# define ETB_ENTRY_POINT "BROKER"
#else
# define ETB_ENTRY_POINT "broker"
#endif

#ifdef __cplusplus
}
#endif

#endif

Top of page

ACI Examples and Header Files

When you begin to write your first EntireX Broker ACI program, you can use the client and server examples listed below as models for your own implementation. If the examples are not available on your platform, transfer them - using FTP, for example - from a platform where they are delivered.

Depending on your platform for C, you will find the files with the examples, include files, etc. in the following locations:

Platform Header Files / Examples Location Notes
z/OS Broker ACI control block header file See member ETBCDEF in the mainframe source library EXX951.SRCE. 5, 6
Broker Command and Info Services control block header file See member ETBCINF in the mainframe source library EXX951.SRCE. 5, 6
Client example
See member BCOC in the mainframe source library ETBvrs.SRCE. 5, 6
Server example See member BCOS in the mainframe source library ETBvrs.SRCE. 5, 6
UNIX Broker ACI control block header file See etbcdef.h in: include 3, 4
Broker Command and Info Services control block header file See etbcinf.h in: include 3, 4
Client example See convClt.c in examples/ACI/conversational/C/ and nconvClt.c in examples/ACI/nonConversational/C/. 3, 4
Server example See convSrv.c in examples/ACI/conversational/C/ and nconvSrv.c in examples/ACI/nonConversational/C/. 3, 4
Windows Broker ACI control block header file See etbcdef.h in: include. 2
Broker Command and Info Services
control block header file
See etbcinf.h in: include. 2
Client example
See convClt.c in examples\ACI\conversational\C\ and nconvClt.c in examples\ACI\nonConversational\C\. 2
Server example See convSrv.c in examples\ACI\conversational\C and nconvSrv.c in examples\ACI\nonConversational\C. 2
BS2000/OSD Broker ACI control block header file See element ETBCDEF.H in the LMS library EXX951.LIB.  
Broker Command and Info Services control block See element ETBCINF.H in the LMS library EXX951.LIB.  
z/VM Broker ACI control block header file See member PL1DEF of the z/VM MACLIB EXX951.MACLIB. 10
Broker Command and Info Services control block See member PL1DEF of the z/VM MACLIB EXX951.MACLIB. 10
IBM i Broker ACI control block header file See member ETBCDEF in include source file H_EXA. 1, 7
Broker Command and Info Services control block See member ETBCINF in include source file H_EXA. 1, 7
Sample procedure for compiling See member CRT_CMOD in source file EXASRC. 1
Client example See member BCOC of type C in source file EXASRC. 1, 9
Procedure to call client example See the CL member EXABCOC in source file EXASRC. 1, 8
Procedure to call Client example with Security parameters See the CL member EXABCOCSEC in source file EXASRC. 1, 8
Server example See member BCOS of type C in source file EXASRC. 1, 9
Procedure to call server example See the CL member EXABCOS in source file EXASRC. 1, 8
Procedure to call server example with Security parameters See the CL member EXABCOSSEC in source file EXASRC. 1, 8

Notes:

  1. See Installing EntireX under IBM i.
  2. See Post-installation Steps under Windows.
  3. For information on exxdir, see Shell Environment Settings.
  4. See Post-installation Steps under UNIX.
  5. See Installing EntireX under z/OS.
  6. For information on vrs, see Contents of Mainframe Installation Medium.
  7. Rename file H_EXA to H before use it.
  8. By default, these CL procedures call the C-type of the client and server programs - i.e, BCOC and BCOS. Modify the procedures to adjust the Broker ID, Broker Version and Security parameters. Compile the sources and bind the created modules to executable *PGM programs. For compilation, use the procedure CRT_CMOD. For binding, use the procedure EXABNDPGM. All sample programs include the ACI Broker control block definitions ETBCDEF during compilation.
  9. See also Verifying the Installation of the Broker Stubs.
  10. See Installing Broker Stubs under z/VM.

Top of page

Creating a C User Application under IBM i

On the IBM i system, the broker stub is implemented as an object of type *SRVPGM (Service Program). This object type has the advantage that its program code can be shared by several programs. It exists as an object on its own and can therefore be easily replaced without rebinding the user's application, when a newer version becomes available.

The service program EXA supplied by Software AG contains all the functions necessary for controlling and communicating with the remote broker. To create an executable Broker application on IBM i, you need to develop, in any ILE-enabled programming language, at least one main module to which the EXA service program is bound.

Example:

The following steps show how to create a server application using the program BCOS. See ACI Examples and Header Files.

Step 1: Set the Environment

The library EXX must be located in the *LIBL list.

To set the library list, you can use the command:

CHGCURLIB CURLIB(EXX)

Step 2: Compile the User Program

To compile BCOS, use the command CRTCMOD with options similar to the following:

MODULE(BCOS) SRCFILE(*CURLIB/EXASRC) OUTPUT(*PRINT) DEFINE(CE_TAS400
TCP_IP '_MULTI_THREADED') SYSIFCOPT(*NOIFSIO)

Or, use the sample procedure CRT_CMOD

If the program has been successfully compiled, the module BCOS will be created.

Step 3: Bind EXA to the User Program

To produce an executable program, bind the user program BCOS to the service program EXA supplied by Software AG. Use the command CRTPGM similar to the following:

CRTPGM PGM(EXX/BCOS) MODULE(*PGM) ENTMOD(*PGM)
BNDSRVPGM(EXX/EXA) BNDDIR(*NONE) OPTION(*GEN *WARN *DUPVAR)
DETAIL(*EXTENDED)

Or, use the sample procedure EXABNDPGM.

If the programs have been bound successfully, the object BCOS with type *PGM will be created.

Top of page

Related Literature

Top of page