EntireX Broker ACI for PL/I

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 and covers the following topics:


Call Format

Calls to EntireX Broker use the following arguments:

  1. The ACI control block is the first argument.

  2. The send buffer is the second argument.

  3. The receive buffer is the third argument.

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

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 for client and server | publish and subscribe.

Broker ACI Control Block Layout

The following table shows the Broker fields in order of the physical layout of the Broker ACI control block and provides a brief description of each field. 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 for client and server | publish and subscribe. 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. 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 for client and server | publish and subscribe. 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 for client and server | publish and subscribe. 1  
PASSWORD ETCB_PASSWD CHAR(32) Password. See Authentication. 1 4,5
TOKEN ETCB_TOKEN CHAR(32) Reconnection token. See USER-ID and TOKEN for client and server | publish and subscribe. 1 3, 5
SECURITY-TOKEN ETCB_SEC_TOKEN CHAR(32) Security token. See Writing Applications using EntireX Security. 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 for client and server | publish and subscribe. 1 3, 5
ERROR-CODE ETCB_ERROR_CODE PIC'99999999' Error code. See Error Handling for client and server | publish and subscribe and Error Messages and Codes. 1  
ENVIRONMENT ETCB_ENVIRONMNT CHAR(32) Environment. See Using Internationalization for client and server | publish and subscribe. 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 Authentication. 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 Writing Applications using EntireX Security 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 codepages. See Using Internationalization for client and server | publish and subscribe. 4  
DATA-ARCH ETCB_DATA_ARCH BIT(8) Data architecture. See ICU Conversion. 4 2
FORCE-LOGON ETCB_FORCE_LOGON CHAR(1) Override Broker AUTOLOGON. See Authentication. 6  
ENCRYPTION-LEVEL ETCB_ENCRYPT_LVL FIXED BINARY(7) Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX. 6 2
KERNELSECURITY ETCB_KERNEL_SEC CHAR(1) Kernel security. See Writing Applications using EntireX Security. 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 for client and server | publish and subscribe.
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  
TOPIC ETCB_TOPIC CHAR(96) Topic name for publish and subscribe. See Key ACI Field Names. 8  
PUBLICATION-ID ETCB_PUBLICATION_ID CHAR(16) Publication ID for publish and subscribe. 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 for client and server | publish and subscribe. 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  

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

The Developer's Kit 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 - 2015 Software AG, Darmstadt,
 *                  Germany and/or Software AG USA, Inc., Reston, VA,
 *                  United States of America, and/or their licensors.
 * Version        : 9.9
 * File           : PLIDEF
 * File Version   : $Revision: 1.33 $
 * 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_VERS_HIGHEST           BIT(8) INIT('10'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_SETSSLPARMS            BIT(8) INIT('10'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);

 /* - 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);

 /* - 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 Encryption Level (ETBCB_ENCRYPTIONLEVEL) ------- */
 DCL ENCLEVEL_NONE              BIT(8) INIT('00'B4);
 DCL ENCLEVEL_TO_BROKER         BIT(8) INIT('01'B4);
 DCL ENCLEVEL_TO_TARGET         BIT(8) INIT('02'B4);

 /* - 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),       /* ENCRYPTION LEVEL    */
       /* 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  */

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 in the Security documentation.

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

The following options are available under z/OS:

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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the 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, see above.

  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:

Using Broker ACI Function SETSSLPARMS

Note:
Not available under CICS.

With the Broker ACI for PL/I, the SSL parameters (e.g. certificates stored in z/OS as RACF keyrings only) are provided with the function SETSSLPARMS.

Start of instruction setTo use SSL

  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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the Security documentation.

  2. On mainframe platforms, use Transport-method-style Broker ID for the Broker ID, for example:

    ETB024:1609:SSL

    If no port number is specified, port 1958 is used as default.

  3. Specify SSL parameters in the second parameter, for example:

    'broker' etbcb "VERIFY_SERVER=N&TRUST_STORE=<racf_uid>/<racf_keyring>" 

    If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused. You can disable this check with SSL parameter verify_server=no.

    If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.

    The ampersand (&) character cannot appear in the password.

    SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for EntireX Clients and Servers.

  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 or Broker SSL Agent. See:

    • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

    • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

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 EXX990.SRCE.

Under z/VM, the Broker ACI control block is contained in member PL1DEF of the z/VM MACLIB EXX990.MACLIB.

Related Literature