
	Version 9.5 SP1	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— 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
Broker ACI Control Block Layout
Broker ACI Control Block Definition
ACI Examples and Header Files
Creating a C User Application under IBM i
Related Literature

Call Format

Calls to EntireX Broker use the following arguments:

The ACI control block is the first argument.
The send buffer is the second argument.
The receive buffer is the third argument.
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:

Under all platforms and with all Broker stubs see the prototype. For example:
```
int broker (ETBCB *, char *, char *, char *);
rc = broker( pCb, pSBuf, pRBuf, pEBuf );
```
additionally, under z/OS, you can invoke CICSETB, using the following EXEC CICS LINK command. The length of the COMMAREA is always 24. For example:
```
EXEC CICS LINK PROGRAM('CICSETB') COMMAREA(commarea) LENGTH(24)
```
The COMMAREA must specify an area in working storage with the following information:
- 8-byte character field "ETBCOMM*"
- one full word containing the address of the EntireX Broker control block
- one full word containing the address of send buffer
- one full word containing the address of receive buffer
- one full word containing the address of error text buffer

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.

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.	See Writing Applications: 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:

Reserved for future use.
You must set this field to a low value (0x00) if you do not intend to use it.
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).
All trailing low values (0x00) are truncated. The field is not transmitted if the entire field is a low value (0x00).
If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or low value (0x00).

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

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 ETB`vrs`.SRCE.	5, 6
	Server example	See member `BCOS` in the mainframe source library ETB`vrs`.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.
BS2000/OSD	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
z/VM	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:

See Installing EntireX under IBM i.
See Post-installation Steps under Windows.
For information on exxdir, see Shell Environment Settings.
See Post-installation Steps under UNIX.
See Installing EntireX under z/OS.
For information on vrs, see Contents of Mainframe Installation Medium.
Rename file H_EXA to H before use it.
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.
See also Verifying the Installation of the Broker Stubs.
See Installing Broker Stubs under z/VM.

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.

For compilation, use the command CRTCMOD with the options:

...DEFINE (CE_TAS400 TCP_IP '_MULTI_THREADED')
...SYSIFCOPT (*NOIFSIO)...

For binding, use the command CRTPGM with the option:
```
...BNDSRVPGM(*LIBL/EXA) ...
```

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.

Related Literature

Writing Applications: Publish and Subscribe - How to implement and program publish-and-subscribe applications, employing durable subscription techniques, with EntireX Broker.
Writing Applications: Client and Server - How to implement and program client-and-server applications with EntireX Broker.
Writing Applications: Units of Work - Describes the concept of units-of-work programming for EntireX Broker.
Writing Applications: Attach Server - Describes the programming of Attach Server for EntireX Broker. It assumes you are familiar with the basics of EntireX Broker ACI programming.
Writing Applications: Command and Information Services - EntireX Broker provides an API for Command and Information Services (CIS) that include the following: shutting down servers; switching trace on and off; retrieving information on clients; registered servers and services.
Broker CIS Data Structures - Describes the data structures of the Command and Information Services.
Writing Applications using EntireX Security - Programming aids relevant to EntireX Security programming.
Broker ACI Fields - Describes the fields in the EntireX Advanced Communication Interface (ACI) that define Broker functions to be performed.
Broker ACI Functions - Describes the EntireX Broker ACI functions.
Broker UOW Status Transition - Contains the UOW Status transition tables for EntireX Broker.
Using the Broker ID in Applications - Describes the URL-style broker ID and transport-method-style broker ID.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT