EntireX Broker ACI for C

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:

See also EntireX Broker ACI Programming for an introduction to ACI programming, a description of ACI fields and functions, and information on writing ACI applications.


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:

  • 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.

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 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. 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-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. 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. 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:

  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).

Broker ACI Control Block Definition

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 - 2021 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.8
* 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

Using the Broker ACI with SSL/TLS

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, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation. This section describes using the Broker ACI with SSL on the following platforms:

z/OS

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.

Using IBM's Application Transparent Transport Layer Security (AT-TLS)

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) graphics/no4.gif using an appropriate client graphics/no1.gif and the z/OS Management Facility (z/OSMF) graphics/no2.gif. Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by using the application graphics/no5.gif job name and remote TCP port number. If the rules match, the TCP connection is turned into an SSL connection graphics/no6.gif. 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.

graphics/adminRpc_ssl_config-c.png

graphics/no1.gif Client to interact with z/OS Management Facility (z/OSMF).
graphics/no2.gif AT-TLS rules are defined with z/OSMF policy management.
graphics/no3.gif Policy Repository with AT-TLS rules stored as z/OS files.
graphics/no4.gif Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
graphics/no5.gif Application using TCP connection.
graphics/no6.gif If AT-TLS rules match, the TCP connection is turned into an SSL connection.

Notes:

  1. The client graphics/no1.gif may vary per operating system, for example a Web browser for z/OS 2.1.
  2. z/OSMF graphics/no2.gif includes other administration and management tasks in addition to policy management.
  3. Policy Management graphics/no3.gif includes other rules, such as IP filtering, network address translation etc.

Start of instruction setTo set up SSL with AT-TLS

  1. 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.

  2. 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
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

  4. 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:

z/VSE

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.

Using BSI's Automatic Transport Layer Security (ATLS)

Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup job BSTTATLS graphics/no2.gif. If the rules match, the socket connection is turned into an SSL connection graphics/no5.gif. 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.

graphics/adminRpc_ssl_config-vse.png

graphics/no1.gif BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6).
graphics/no2.gif ATLS rules are defined manually. See Sample ATLS Daemon Configuration below.
graphics/no3.gif BSTTATLS is associated with a TCP/IP stack.
graphics/no4.gif Application using TCP connection.
graphics/no5.gif BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections.

Start of instruction setTo set up SSL with AT-TLS

  1. 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.

  2. Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:

    ETB024:1699:TCP
  3. Configure AT-TLS to turn the TCP/IP connection to an SSL connection, using a client to interact with the z/OS Management Facility (z/OSMF). The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files. This file is the configuration file for the Policy Agent, MVS task PAGENT.

  4. 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:

Sample ATLS Daemon Configuration

* 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 SSL/TLS, HTTP(S), and Certificates with EntireX.

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. 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 EXX108.SRCE. 3, 4
Broker Command and Info Services control block header file See member ETBCINF in the mainframe source library EXX108.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 EXX108.LIB.  
Broker Command and Info Services control block See element ETBCINF.H in the LMS library EXX108.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:

  1. See Installing EntireX under IBM i.
  2. For information on exxdir, see Shell Environment Settings.
  3. See Installing EntireX under z/OS.
  4. For information on vrs, see Contents of Mainframe Installation Medium.
  5. Rename file H_EXA to H before use it.
  6. By default, these CL procedures call the C-type of the client and server programs, that is, 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.
  7. See also Verifying the Installation of the Broker Stubs.

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

Reference