EntireX Broker ACI for PL/I

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 PL/I. 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.

The send buffer and the receive buffer must always be provided. If they are not required by the selected EntireX Broker function, you can define them as CHAR(1) fields.

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

  • Under all platforms with all Broker stubs:

    CALL 'BROKER' USING
       (ETCB,SEND_BUFFER,RECV_BUFFER,ERROR_TEXT);
  • additionally, under z/OS, you can invoke Broker stub CICSETB, using the following EXEC CICS LINK command. The length of the COMMAREA is always 24. For example:

    EXEC CICS LINK PROGRAM('CICSETB') COMMAREA(MYCOMM) 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 00000000 (zeros) are returned in the ERROR-CODE field in the EntireX Broker control block, the operation has been performed successfully. However, function results other than 00000000 (zeros) 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. See the actual copybook for PL/I below in Broker ACI Control Block Copybook.

See Broker ACI Fields for more information.

Broker ACI Field PL/I Definition Description /
Related Information
API
Vers.
Notes
API-TYPE ETCB_TYPE BIT(8) API type. See API-TYPE and API-VERSION. 1  
API-VERSION ETCB_VERSION FIXED BIN(7) API version. 1  
FUNCTION ETCB_FUNCTION FIXED BIN(7) See Broker ACI Functions to perform Broker function. 1  
OPTION ETCB_OPTION FIXED BIN(7) See Option Descriptions in the ACI Programming documentation. 1  
  ETCB_RESERVED CHAR(16) Reserved for future use. 1 1
SEND-LENGTH ETCB_SEND_LEN FIXED BINARY(31) Send length. See Using Send and Receive Buffers. 1  
RECEIVE-LENGTH ETCB_REC_LEN FIXED BINARY(31) Receive length. 1  
RETURN-LENGTH ETCB_RETURN_LEN FIXED BINARY(31) Return length. 1  
ERRTEXT-LENGTH ETCB_ERRTEXT_LEN FIXED BINARY(31) Error text length. 1  
BROKER-ID ETCB_BROKER_ID CHAR(32) Broker ID. See Using the Broker ID in Applications. 1  
SERVER-CLASS
SERVER-NAME
SERVICE
ETCB_SERVER_CL CHAR(32)
ETCB_SERV_NAME CHAR(32)
ETCB_SERVICE_NM CHAR(32)
Service. See Control Block Fields and Verbs. 1 3,5
USER-ID ETCB_USER_ID CHAR(32) User ID. See USER-ID and TOKEN. 1  
PASSWORD ETCB_PASSWD CHAR(32) Password. See Authentication. 1 4,5
TOKEN ETCB_TOKEN CHAR(32) Reconnection token. See USER-ID and TOKEN. 1 3,5
SECURITY-TOKEN ETCB_SEC_TOKEN CHAR(32) Security token. See Role of Security Token (STOKEN) during Authentication. 1 4,5
CONV-ID ETCB_CONV_ID CHAR(16) Conversation ID. See Conversational and Non-conversational Mode. 1 3,5
WAIT ETCB_WAIT CHAR(8) Wait value. See Blocked and Non-blocked Broker Calls. 1 3,5
ERROR-CODE ETCB_ERROR_CODE PIC'99999999' Error code. See Error Handling and Error Messages and Codes. 1  
ENVIRONMENT ETCB_ENVIRONMNT CHAR(32) Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT. 1 3,5
ADCOUNT ETCB_ADCOUNT FIXED BINARY(31) Attempted delivery count. See Writing Applications: Units of Work. 2  
USER-DATA ETCB_USER_DATA CHAR(16) Conversation User Data. See Managing Conversation Contexts. 2 3,5
not used ETCB_MESSAGE_ID CHAR(32) Message ID. 2 4,5
not used ETCB_MESS_TYPE CHAR(16) Message type. 2 3,5
  ETCB_LIFE_TIME CHAR(8) Reserved for future use. 2 1,3,5
NEWPASSWORD ETCB_NEW_PASSWD CHAR(32) New password. See Changing your Password. 2 4,5
not used ETCB_ADAPTER_ERR CHAR(8) Adapter error. 2  
CLIENT-UID ETCB_CL_USER_ID CHAR(32) Client user ID. See Client User ID. 2  
CONV-STAT ETCB_CONVSTAT BIT(8) Conversation status. See Conversational and Non-conversational Mode. 2  
STORE ETCB_STORE BIT(8) Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. 2  
  ETCB_STATUS BIT(8) Reserved for future use. 2 1
UOWSTATUS ETCB_UOWSTATUS BIT(8) UOW Status. See Writing Applications: Units of Work. 3 3,5
UWTIME ETCB_UOW_TIME CHAR(8) UOW lifetime. 3 3,5
UOWID ETCB_UOW_ID CHAR(16) UOW unique identifier. 3 3,5
USTATUS ETCB_USER_STATUS CHAR(32) User status. 3  
UOW-STATUS-PERSIST ETCB_UOW_STATUSP BIT(8) Multiplier for persistent status lifetime. 3 2
  ETCB_RESERVED3 CHAR(3) Reserved for future use. 3 1
LOCALE-STRING ETCB_LOCALE_STR CHAR(40) 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 ETCB_DATA_ARCH BIT(8) Data architecture. 4 2
FORCE-LOGON ETCB_FORCE_LOGON CHAR(1) Override Broker AUTOLOGON. See FORCE-LOGON. See Writing Applications using EntireX Security. 6  
  ETCB_ENCRYPT_LVL FIXED BINARY(7) 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 ETCB_KERNEL_SEC CHAR(1) Kernel security. See Is Broker Kernel Secure?. 7  
COMMITTIME ETCB_COMMIT_TIME CHAR(17) Commit time. See Writing Applications: Units of Work. 7  
COMPRESSLEVEL ETCB_COMPRESS CHAR(1) Compression level.
See Data Compression.
7  
  ETCB_RESERVED3 CHAR(2) Reserved for future use. 7 1
  ETCB_RESERVED4 CHAR(4) Reserved for future use. 7 1
UWSTAT-LIFETIME ETCB_UOW_STAT_LIFETIME CHAR(8) Add value for persistent status lifetime. See UWSTAT-LIFETIME. 8  
CLIENT-ID ETCB_CLIENT_ID FIXED BIN(31) 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 ETCB_LOG_COMMAND CHAR(1) Log the current command. See also Programmatically Turning on Command Logging. 9  
CREDENTIALS-TYPE ETCB_CRED_TYPE CHAR(1) Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. 9  
VARLIST-OFFSET ETCB_VAR_LIST_OFF FIXED BIN(31) Internal Software AG field. 10  
LONG-BROKER-ID-LENGTH ETCB_LONG_BID_LEN FIXED BIN(31) See LONG-BROKER-ID-LENGTH. 10  
MESSAGE-ID ETCB_NEW_MSG_ID CHAR(64) See Unique Message ID in the EntireX Broker ACI Programming documentation. 11  
CORRELATION-ID ETCB_COR_ID CHAR(64) CORRELATION-ID. 11  
USE-SPECIFIED-MESSAGE-ID ETCB_USE_MSG_ID CHAR(1) Use supplied MESSAGE-ID for SEND. 11  
USE-SPECIFIED-CORRELATION-ID ETCB_USE_COR_ID CHAR(1) Send supplied CORRELATION-ID to Broker. 11  
  ETCB_RESERVED6 CHAR(3) Reserved for future use. 11  
  ETCB_RESERVED7 FIXED BIN(31) Reserved for future use. 11  
LONG-PASSWORD-LENGTH ETCB_LONG_PSWD_LEN FIXED BIN(31) Length of long password. See Authentication. 12  
LONG-NEWPASSWORD-LENGTH ETCB_LONG_NEW_PSWD_LEN FIXED BIN(31) 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 (X'00') if you do not intend to use it.
  3. The field is transmitted up to the first blank or LOW-VALUE (X'00'). It is not transmitted if the first character is a blank or a LOW-VALUE (X'00').
  4. All trailing LOW-VALUES (X'00') are truncated. The field is not transmitted if the entire field is a LOW-VALUE (X'00').
  5. If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or LOW-VALUE (X'00').

Broker ACI Control Block Copybook

EntireX provides a copybook with the ACI control block definition. See ACI Examples and Copybooks for where it is provided on your platform:

 /*
 ***********************************************************************
 * Product        : EntireX Broker
 * Copyright      : Copyright (c) 1997 - 2019 Software AG, Darmstadt,
 *                  Germany and/or Software AG USA, Inc., Reston, VA,
 *                  United States of America, and/or their licensors.
 * Version        : 10.5
 * File           : PLIDEF
 * File Version   : $Revision: 1.45 $
 * Description    : PL/I language ACI control block definitions.
 *
 */

 /* %OPTION LANGLVL(SAA2) */

 /* - EntireX Broker API Type Constants (ETBCB_TYPE)----------------- */
 DCL API_TYPE1                  BIT(8) INIT('01'B4);
 DCL API_TYPE2                  BIT(8) INIT('02'B4);
 DCL API_TYPE4                  BIT(8) INIT('04'B4);
 DCL API_TYPE8                  BIT(8) INIT('08'B4);

 /* - EntireX Broker API Version Constants (ETBCB_VERSION) ---------- */
 DCL API_VERS1                  BIT(8) INIT('01'B4);
 DCL API_VERS2                  BIT(8) INIT('02'B4);
 DCL API_VERS3                  BIT(8) INIT('03'B4);
 DCL API_VERS4                  BIT(8) INIT('04'B4);
 DCL API_VERS5                  BIT(8) INIT('05'B4);
 DCL API_VERS6                  BIT(8) INIT('06'B4);
 DCL API_VERS7                  BIT(8) INIT('07'B4);
 DCL API_VERS8                  BIT(8) INIT('08'B4);
 DCL API_VERS9                  BIT(8) INIT('09'B4);
 DCL API_VERS10                 BIT(8) INIT('10'B4);
 DCL API_VERS11                 BIT(8) INIT('11'B4);
 DCL API_VERS12                 BIT(8) INIT('12'B4);
 DCL API_VERS_HIGHEST           BIT(8) INIT('11'B4);

 /* - EntireX Broker API API Function Constants (ETBCB_FUNCTION) ---- */
 DCL FCT_SEND                   BIT(8) INIT('01'B4);
 DCL FCT_RECEIVE                BIT(8) INIT('02'B4);
 DCL FCT_UNDO                   BIT(8) INIT('04'B4);
 DCL FCT_EOC                    BIT(8) INIT('05'B4);
 DCL FCT_REGISTER               BIT(8) INIT('06'B4);
 DCL FCT_DEREGISTER             BIT(8) INIT('07'B4);
 DCL FCT_VERSION                BIT(8) INIT('08'B4);
 DCL FCT_LOGON                  BIT(8) INIT('09'B4);
 DCL FCT_LOGOFF                 BIT(8) INIT('0A'B4);
 DCL FCT_SET                    BIT(8) INIT('0B'B4);
 DCL FCT_GET                    BIT(8) INIT('0C'B4);
 DCL FCT_SYNCPOINT              BIT(8) INIT('0D'B4);
 DCL FCT_KERNELVERS             BIT(8) INIT('0E'B4);
 DCL FCT_LOCTRANS               BIT(8) INIT('0F'B4);
 DCL FCT_SEND_PUBLICATION       BIT(8) INIT('11'B4);
 DCL FCT_RECEIVE_PUBLICATION    BIT(8) INIT('12'B4);
 DCL FCT_SUBSCRIBE              BIT(8) INIT('13'B4);
 DCL FCT_UNSUBSCRIBE            BIT(8) INIT('14'B4);
 DCL FCT_CONTROL_PUBLICATION    BIT(8) INIT('15'B4);
 DCL FCT_REPLY_ERROR            BIT(8) INIT('16'B4);
 DCL FCT_GET_MESSAGE_ID         BIT(8) INIT('1A'B4);

 /* - EntireX Broker API Option Constants (ETBCB_OPTION) ------------ */
 DCL OPT_OFF                    BIT(8) INIT('00'B4);
 DCL OPT_MSG                    BIT(8) INIT('01'B4);
 DCL OPT_HOLD                   BIT(8) INIT('02'B4);
 DCL OPT_IMMED                  BIT(8) INIT('03'B4);
 DCL OPT_QUIESCE                BIT(8) INIT('04'B4);
 DCL OPT_EOC                    BIT(8) INIT('05'B4);
 DCL OPT_CANCEL                 BIT(8) INIT('06'B4);
 DCL OPT_LAST                   BIT(8) INIT('07'B4);
 DCL OPT_NEXT                   BIT(8) INIT('08'B4);
 DCL OPT_PREVIEW                BIT(8) INIT('09'B4);
 DCL OPT_COMMIT                 BIT(8) INIT('0A'B4);
 DCL OPT_BACKOUT                BIT(8) INIT('0B'B4);
 DCL OPT_SYNC                   BIT(8) INIT('0C'B4);
 DCL OPT_ATTACH                 BIT(8) INIT('0D'B4);
 DCL OPT_DELETE                 BIT(8) INIT('0E'B4);
 DCL OPT_EOCCANCEL              BIT(8) INIT('0F'B4);
 DCL OPT_QUERY                  BIT(8) INIT('11'B4);
 DCL OPT_SETUSTATUS             BIT(8) INIT('12'B4);
 DCL OPT_ANY                    BIT(8) INIT('13'B4);
 DCL OPT_TERMINATE              BIT(8) INIT('14'B4);
 DCL OPT_DURABLE                BIT(8) INIT('15'B4);
 DCL OPT_CHECKSERVICE           BIT(8) INIT('16'B4);

 /* - EntireX Broker Conversation Status Constants (ETBCB_CONVSTAT) - */
 DCL CONVSTAT_NEW               BIT(8) INIT('01'B4);
 DCL CONVSTAT_OLD               BIT(8) INIT('02'B4);
 DCL CONVSTAT_NONE              BIT(8) INIT('03'B4);

 /* - EntireX Broker Store Constants (ETBCB_STORE) ------------------ */
 DCL STORE_OFF                  BIT(8) INIT('01'B4);
 DCL STORE_BROKER               BIT(8) INIT('02'B4);

 /* - EntireX Broker Status Constants (ETBCB_STATUS) ---------------- */
 DCL STAT_OFF                   BIT(8) INIT('01'B4);
 DCL STAT_STORED                BIT(8) INIT('02'B4);
 DCL STAT_DELIVERY_ATTEMP       BIT(8) INIT('03'B4);
 DCL STAT_DELIVERED             BIT(8) INIT('04'B4);
 DCL STAT_PROCESSED             BIT(8) INIT('05'B4);
 DCL STAT_DEAD                  BIT(8) INIT('06'B4);

 /* - EntireX Broker UOW Status Constants (ETBCB_UOW_STATUS) -------- */
 DCL RECV_NONE                  BIT(8) INIT('00'B4);
 DCL RECEIVED                   BIT(8) INIT('01'B4);
 DCL ACCEPTED                   BIT(8) INIT('02'B4);
 DCL DELIVERED                  BIT(8) INIT('03'B4);
 DCL BACKEDOUT                  BIT(8) INIT('04'B4);
 DCL PROCESSED                  BIT(8) INIT('05'B4);
 DCL CANCELLED                  BIT(8) INIT('06'B4);
 DCL TIMEOUT                    BIT(8) INIT('07'B4);
 DCL DISCARDED                  BIT(8) INIT('08'B4);
 DCL RECV_FIRST                 BIT(8) INIT('09'B4);
 DCL RECV_MIDDLE                BIT(8) INIT('0A'B4);
 DCL RECV_LAST                  BIT(8) INIT('0B'B4);
 DCL RECV_ONLY                  BIT(8) INIT('0C'B4);
 DCL POSTPONED                  BIT(8) INIT('0D'B4);

 /* - EntireX Broker Force Logon Constants (ETBCB_FORCE_LOGON) ------ */
 DCL FORCE_LOGON_NO             CHAR(1) INIT('N');
 DCL FORCE_LOGON_YES            CHAR(1) INIT('Y');

 /* - EntireX Broker ------------------------------------------------ */
 DCL ENCLEVEL_NONE              BIT(8) INIT('00'B4);
 DCL ENCLEVEL_TO_BROKER         BIT(8) INIT('01'B4);    /* DEPRECATED */
 DCL ENCLEVEL_TO_TARGET         BIT(8) INIT('02'B4);    /* DEPRECATED */

 /* - EntireX Broker Kernel Security Constants (ETBCB_KERNEL_SEC) --- */
 DCL KERNEL_SECURITY_NO         CHAR(1) INIT('N');
 DCL KERNEL_SECURITY_YES        CHAR(1) INIT('Y');
 DCL KERNEL_SECURITY_USER       CHAR(1) INIT('U');

 /* - EntireX Broker Compression Level (ETBCB_COMPRESSLEVEL) -------- */
 DCL COMPRESS_LEVEL_0           CHAR(1) INIT('0');
 DCL COMPRESS_LEVEL_1           CHAR(1) INIT('1');
 DCL COMPRESS_LEVEL_2           CHAR(1) INIT('2');
 DCL COMPRESS_LEVEL_3           CHAR(1) INIT('3');
 DCL COMPRESS_LEVEL_4           CHAR(1) INIT('4');
 DCL COMPRESS_LEVEL_5           CHAR(1) INIT('5');
 DCL COMPRESS_LEVEL_6           CHAR(1) INIT('6');
 DCL COMPRESS_LEVEL_7           CHAR(1) INIT('7');
 DCL COMPRESS_LEVEL_8           CHAR(1) INIT('8');
 DCL COMPRESS_LEVEL_9           CHAR(1) INIT('9');
 DCL COMPRESS_LEVEL_NO          CHAR(1) INIT('N');
 DCL COMPRESS_LEVEL_YES         CHAR(1) INIT('Y');

 /*-------------------------------------------------------------------*/
 /* ETBCB: EntireX Broker API Control Block Definition                */
 /*-------------------------------------------------------------------*/
 DCL 1 ETBCB ALIGNED,
       3 ETCB_TYPE              BIT(8),
       3 ETCB_VERSION           BIT(8),
       3 ETCB_FUNCTION          BIT(8),
       3 ETCB_OPTION            BIT(8),
       3 ETCB_RESERVED          CHAR(16),
       3 ETCB_SEND_LEN          FIXED BIN(31),
       3 ETCB_RECEIVE_LEN       FIXED BIN(31),
       3 ETCB_RETURN_LEN        FIXED BIN(31),
       3 ETCB_ERRTEXT_LEN       FIXED BIN(31),
       3 ETCB_BROKER_ID         CHAR(32),     /* BROKER ID = ETB018  */
       3 ETCB_SERVER_CLASS      CHAR(32),     /* SERVER CLASS        */
       3 ETCB_SERVER_NAME       CHAR(32),     /* SERVER NAME         */
       3 ETCB_SERVICE           CHAR(32),     /* SERVICE             */
       3 ETCB_USER_ID           CHAR(32),     /* USER ID             */
       3 ETCB_PASSWD            CHAR(32),     /* PASSWORD            */
       3 ETCB_TOKEN             CHAR(32),     /* RECONNECTION TOKEN  */
       3 ETCB_SEC_TOKEN         CHAR(32),     /* SECURITY TOKEN      */
       3 ETCB_CONV_ID           CHAR(16),     /* CONV/NON CONV       */
       3 ETCB_WAIT_TIMEOUT      CHAR(8),      /* BLOCKED/NON BLOCKED */
       3 ETCB_ERROR_CODE        CHAR(8),      /* ERROR CLASS/NUMBER  */
       3 ETCB_ENVIRONMNT        CHAR(32),     /*                     */
       /* V2 ADDITIONS */
       3 ETCB_ADCOUNT           FIXED BIN(31),/* ATTEMPT DELIVERY    */
       3 ETCB_USER_DATA         CHAR(16),     /* USER DATA FIELD     */
       3 ETCB_MESSAGE_ID        CHAR(32),     /* NOT USED BY BROKER  */
       3 ETCB_MESSAGE_TYPE      CHAR(16),     /* NOT USED BY BROKER  */
       3 ETCB_LIFE_TIME         CHAR(8),      /* NOT USED BY BROKER  */
       3 ETCB_NEW_PASSWD        CHAR(32),     /* NEW PASSWORD        */
       3 ETCB_ADAPTER_ERROR     CHAR(8),      /* ADAPTER ERROR       */
       3 ETCB_CLIENT_USER_ID    CHAR(32),     /* USER-ID FROM CLIENT */
       3 ETCB_CONVSTAT          BIT(8),       /* CONVERSATION STATUS */
       3 ETCB_STORE             BIT(8),       /* STORE               */
       3 ETCB_STATUS            BIT(8),       /* NOT USED BY BROKER  */
       3 ETCB_UOW_STATUS        BIT(8),       /* STATUS OF UOW       */
       /* V3 ADDITIONS */
       3 ETCB_UOW_TIME          CHAR(8),      /* UOW LIFE TIME       */
       3 ETCB_UOW_ID            CHAR(16),     /* UNIT OF WORK IDENT  */
       3 ETCB_USER_STATUS       CHAR(32),     /* USER STATUS IN UOW  */
       3 ETCB_UOW_STATUSP       BIT(8),       /* UOW STATUS PERSIST  */
       3 ETCB_RESERVED2         CHAR(3),      /* ALIGNMENT           */
       /* V4 ADDITIONS */
       3 ETCB_LOCALE_STR        CHAR(40),     /* LOCALES             */
       3 ETCB_DATA_ARCH         BIT(8),       /* FOR FUTURE USE      */
       /* V6 ADDITIONS */
       3 ETCB_FORCE_LOGON       CHAR(1),      /* FORCE LOGON         */
       3 ETCB_ENCRYPTIONLEVEL   BIT(8),       /* DEPRECATED.         */
                                              /* USE AT-TLS.         */
       /* V7 ADDITIONS */
       3 ETCB_KERNEL_SEC        CHAR(1),      /* KERNEL SECURITY     */
       3 ETCB_COMMIT_TIME       CHAR(17),     /* COMMIT TIME OF UOW  */
       3 ETCB_COMPRESSLEVEL     CHAR(1),      /* COMPRESSION LEVEL   */
       3 ETCB_RESERVED3         CHAR(2),      /* ALIGNMENT           */
       3 ETCB_RESERVED4         CHAR(4),      /* ALIGNMENT           */
       /* V8 ADDITIONS */
       3 ETCB_UOW_STAT_LIFETIME CHAR(8),      /* UOWSTATUS LIFE: ADD */
       3 ETCB_TOPIC             CHAR(96),     /* TOPIC NAME          */
       3 ETCB_PUBLICATION_ID    CHAR(16),     /* PUBLICATION ID      */
       /* V9 ADDITIONS */
       3 ETCB_RESVD_V99_1       CHAR(32),     /* RESERVED FOR FUTURE */
       3 ETCB_RESVD_V73_1       FIXED BIN(31),/* RESERVED FOR FUTURE */
       3 ETCB_RESVD_V73_2       FIXED BIN(31),/* RESERVED FOR FUTURE */
       3 ETCB_RESVD_V73_3       FIXED BIN(31),/* RESERVED FOR FUTURE */
       3 ETCB_CLIENT_ID         FIXED BIN(31),/* CLIENT IDENTIFIER   */
       3 ETCB_RESVD_V73_4       CHAR(32),     /* RESERVED FOR FUTURE */
       3 ETCB_LOG_COMMAND       CHAR(1),      /* LOG THIS COMMAND    */
       3 ETCB_CRED_TYPE         CHAR(1),      /* CREDENTIALS TYPE    */
       3 ETCB_RESVD_V73_5       CHAR(32),     /* RESERVED FOR FUTURE */
       3 ETCB_RESERVED5         CHAR(2),      /* ALIGNMENT           */
       /* V10 ADDITIONS */
       3 ETCB_VAR_LIST_OFF      FIXED BIN(31),/* VARIABLE LIST OFFSET*/
       3 ETCB_LONG_BID_LEN      FIXED BIN(31),/* LEN LONG BROKER-ID  */
       /* V11 ADDITIONS */
       3 ETCB_NEW_MSG_ID        CHAR(64),     /* MSG ID SENT/RCVD MSG*/
       3 ETCB_COR_ID            CHAR(64),     /* MSG ID SENT MSG     */
       3 ETCB_USE_MSG_ID        CHAR(1),      /* USE MSG ID FOR SEND */
       3 ETCB_USE_COR_ID        CHAR(1),      /* SEND COR ID TO BROK */
       3 ETCB_RESERVED6         CHAR(2),      /* ALIGNMENT           */
       3 ETCB_RESERVED7         FIXED BIN(31);/* RESERVED FOR FUTURE */
       /* V12 ADDITIONS */
       3 ETCB_LONG_PSWD_LEN     FIXED BIN(31),/* LEN LONG PASSWORD   */
       3 ETCB_LONG_NEW_PSWD_LEN FIXED BIN(31),/* LEN LONG NEW PASSWD */

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 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 PL/I 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-pli.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 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.

ACI Examples and Copybooks

When you begin to write your first Broker ACI program, you can use the example PLIIVP as a model for your own implementation.

Under z/OS, the Broker ACI control block copybook is contained in member PL1DEF in the mainframe source library EXX105.SRCE.

Related Literature

Writing Applications

Reference