ACI stands for Advanced Communication Interface. 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:
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.
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 applications (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.
|
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 Descriptions under Broker ACI Functions in the ACI Programming documentation. | 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. | 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-CLASSSERVER-NAMESERVICE |
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.
|
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.
|
1 | 3,5 | |
SECURITY-TOKEN |
ETB_CHAR security_token[S_securityToken] |
Security token. See Role of Security Token (STOKEN) during Authentication. | 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. | 1 | 3,5 | |
ERROR-CODE |
ETB_CHAR error_code[S_ERROR_CODE] |
Error code. See Error Handling. | 1 | ||
ENVIRONMENT |
ETB_CHAR environment[S_ENVIRONMENT] |
Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT.
|
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 Client and Server Applications. | 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 Changing your Password. | 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 a codepage name to tell the broker the encoding of the data. For more information
see ACI field LOCALE-STRING.
|
4 | ||
DATA-ARCH |
ETB_BYTE data_arch |
Data architecture. | 4 | 2 | |
FORCE-LOGON |
ETB_CHAR forceLogon |
Override Broker AUTOLOGON. See FORCE-LOGON.
|
See Writing Applications using EntireX Security | 6 | |
ETB_BYTE encryptionLevel |
Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See Using the Broker ACI with SSL/TLS. | 6 | 2 | ||
KERNELSECURITY |
ETB_CHAR kernelsecurity |
Kernel security. See Is Broker Kernel Secure?. | 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. | 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 | ||
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 | 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. | 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 | ||
MESSAGE-ID |
ETB_CHAR message_id[S_MESSAGE_ID]; |
See Unique Message ID under Broker ACI Functions in the EntireX Broker ACI Programming documentation. | 11 | ||
CORRELATION-ID |
ETB_CHAR correlation_id[S_MESSAGE_ID]; |
CORRELATION-ID. |
11 | ||
USE-SPECIFIED-MESSAGE-ID |
ETB_CHAR use_specified_message_id; |
Use supplied MESSAGE-ID for SEND.
|
11 | ||
USE-SPECIFIED-CORRELATION-ID |
ETB_CHAR use_specified_CORRELATION_id; |
Use supplied CORRELATION-ID for SEND.
|
11 | ||
ETB_CHAR reserved6[3]; |
Reserved for future use. | 11 | |||
ETB_LONG reserved7; |
Reserved for future use. | 11 | |||
LONG-PASSWORD-LENGTH |
ETB_LONG long_password_length; |
Length of long password. See Authentication. | 12 | ||
LONG-NEWPASSWORD-LENGTH |
ETB_LONG long_newpassword_length; |
Length of long new password. See Changing your Password. | 12 | ||
Notes:
EntireX 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 : Copyright (c) 1997 - 2018 Software AG, Darmstadt,
* Germany and/or Software AG USA, Inc., Reston, VA,
* United States of America, and/or their licensors.
*
* Use, reproduction, transfer, publication or disclosure
* is prohibited except as specifically provided for in your
* License Agreement with Software AG.
* Version : 10.3
* File : ETBCDEF.H
* File Version : $Revision: 1.126 $
* 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 */
#if( __VSE__ )
# define ETB_INT8 double /* 8 byte double */
#else
# define ETB_INT8 long long /* 8 byte signed integer */
#endif
/* --- 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_VERS11 ((ETB_BYTE) 11)
#define API_VERS12 ((ETB_BYTE) 12)
#define API_VERS_HIGHEST API_VERS12
/* --- 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_SETSSLPARMS ((ETB_BYTE) 16)
#define FCT_REPLY_ERROR ((ETB_BYTE) 22)
#define FCT_GET_MESSAGE_ID ((ETB_BYTE) 26)
/* --- 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_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)
#define POSTPONED ((ETB_BYTE) 13)
/* --- 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 ----------------------------------------------- */
#define ENCLEVEL_NONE ((ETB_BYTE) 0)
#define ENCLEVEL_TO_BROKER ((ETB_BYTE) 1) /* DEPRECATED */
#define ENCLEVEL_TO_TARGET ((ETB_BYTE) 2) /* DEPRECATED */
/* --- 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)
/*--------------------------------------------------------------------*/
/* 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_MESSAGE_ID ((ETB_CHAR) 64)
#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_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_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) 16)
#define S_WAIT ((ETB_CHAR) 8)
#define S_BROKER_URL ((ETB_SHORT) 512)
/*--------------------------------------------------------------------*/
/* ETBCB: EntireX Broker API Control Block Definition */
/*--------------------------------------------------------------------*/
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: DEPRECATED. Use AT-TLS */
/* v6: on z/OS or ATLS on z/VSE */
/* v6: or SSL on other platforms*/
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 reserved_etbcb_v910_1[96]; /* v8: Reserved for future use */
ETB_CHAR reserved_etbcb_v910_2[16]; /* v8: Reserved for future use */
ETB_CHAR reserved_etbcb_v99_1[32]; /* v9: Reserved for future use */
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 */
ETB_CHAR message_id[S_MESSAGE_ID]; /*v11: If message sent but no */
/*v11: message received: */
/*v11: - MSG ID of sent message */
/*v11: If message received: */
/*v11: - MSG ID of received MSG */
ETB_CHAR correlation_id[S_MESSAGE_ID]; /*v11: - MSG ID of sent message */
ETB_CHAR use_specified_message_id; /*v11: No new MSG ID for SEND */
ETB_CHAR use_specified_correlation_id; /*v11: Send COR ID to Broker */
ETB_CHAR reserved6[2]; /*v11: Alignment */
ETB_LONG reserved7; /*v11: Reserved for future use */
ETB_LONG long_password_length; /*v12: Length long password */
ETB_LONG long_newpassword_length; /*v12: Length long new password */
} 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 applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. ACI-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the Broker SSL Agent. For an introduction see SSL/TLS and Certificates with EntireX in the Platform-independent Administration documentation. This section describes using the Broker ACI with SSL on the following platforms:
SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).
For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.
With the Broker ACI for C you can use IBM's Application Transparent Transport Layer Security, where the establishment of the SSL connection is pushed down the stack into the TCP layer.
Configure the AT-TLS rules for the policy agent (PAGENT) 
using an appropriate client 
and the z/OS Management Facility (z/OSMF) 
.
Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by
using the application 
job name and remote TCP port number.
If the rules match, the TCP connection is turned into an SSL connection 
.
Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.
|
Client to interact with z/OS Management Facility (z/OSMF). |
|
AT-TLS rules are defined with z/OSMF policy management. |
 |
Policy Repository with AT-TLS rules stored as z/OS files. |
|
Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack. |
|
Application using TCP connection. |
|
If AT-TLS rules match, the TCP connection is turned into an SSL connection. |
Notes:
may vary per operating system, for example a Web browser for z/OS 2.1.
includes other administration and management tasks in addition to policy management.
includes other rules, such as IP filtering, network address translation etc.
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the ACI application (client or server) for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection, see above.
Make sure the SSL server to which the ACI application (client or server) connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in Integration Server (IS inbound). See:
Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.
Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup
job BSTTATLS .
If the rules match, the socket connection is turned into an SSL connection .
Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.
|
BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6). |
|
ATLS rules are defined manually. See Sample ATLS Daemon Configuration below. |
|
BSTTATLS is associated with a TCP/IP stack. |
|
Application using TCP connection. |
|
BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections. |
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection, see above.
Make sure the SSL server to which the RPC component connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:
* Converting inbound EntireX Broker connection * Converts listen port 1971 to SSL listen port 1972 OPTION SERVER ATTLS 1971 AS 2071 SSL * * Converting outbound client connection * Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL OPTION CLIENT ATTLS 1972 TO 192.168.2.100 AS 2072 SSL
Note:
We recommend setting SETPARM value SUBTASK to a value greater than 0 in the ATLS daemon startup job (valid values 0-16, default=0). For example:
// SETPARM SUBTASK=8
See also BSI SSL Installation, Programming and User's Guide.
For additional information see also Using the BSI TCP/IP Stack under Hints for Setting up Broker JCL in z/VSE in the z/VSE Installation documentation and SSL/TLS and Certificates with EntireX.
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. at 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 EXX103.SRCE.
|
3, 4 |
| Broker Command and Info Services control block header file | See member ETBCINF in the mainframe source
library EXX103.SRCE.
|
3, 4 | |
| UNIX | 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 | |
| Windows | Broker ACI control block header file | See etbcdef.h in: include.
|
|
| Broker Command and Info Services control block header file | See etbcinf.h in: include.
|
||
| BS2000/OSD | Broker ACI control block header file | See element ETBCDEF.H in the LMS library EXX103.LIB.
|
|
| Broker Command and Info Services control block | See element ETBCINF.H in the LMS library EXX103.LIB.
|
||
| IBM i | Broker ACI control block header file | See member ETBCDEF in include source file
H_EXA.
|
1, 5 |
| Broker Command and Info Services control block | See member ETBCINF in include source file
H_EXA.
|
1, 5 | |
| 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, 7 | |
| Procedure to call client example | See the CL member EXABCOC in source file
EXASRC.
|
1, 6 | |
| Procedure to call Client example with Security parameters | See the CL member EXABCOCSEC in source file
EXASRC.
|
1, 6 | |
| Server example | See member BCOS of type C in source file
EXASRC.
|
1, 7 | |
| Procedure to call server example | See the CL member EXABCOS in source file
EXASRC.
|
1, 6 | |
| Procedure to call server example with Security parameters | See the CL member EXABCOSSEC in source file
EXASRC.
|
1, 6 |
Notes:
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.
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.
The library EXX must be located in the *LIBL list.
To set the library list, you can use the command:
CHGCURLIB CURLIB(EXX)
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.
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.
Writing Client and Server Applications - 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.
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.
Broker CIS Data Structures - Describes the data structures of the Command and Information Services.
Using the Broker ID in Applications - Describes the URL-style broker ID and transport-method-style broker ID.