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:
Calls to EntireX Broker use the following arguments:
The ACI control block is the first argument.
The send buffer is the second argument.
The receive buffer is the third argument.
The error text buffer is the last argument. It can provide a short
text of the error code, if desired. Sufficient buffer length must be supplied
to allow the standard 40-byte long message to be returned by EntireX Broker.
For ACI version 9 and above, the error text buffer can be greater than 40 bytes as
specified in the ACI field ERRTEXT-LENGTH.
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.
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-CLASSSERVER-NAMESERVICE |
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 under Broker ACI Functions 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:
LOW-VALUE (X'00') if you do not intend to use it.
LOW-VALUE (X'00'). It is not transmitted if the first character is a blank or a LOW-VALUE (X'00').
LOW-VALUES (X'00') are truncated. The field is not transmitted if the entire field is a LOW-VALUE (X'00').
LOW-VALUE (X'00').
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 - 2018 Software AG, Darmstadt,
* Germany and/or Software AG USA, Inc., Reston, VA,
* United States of America, and/or their licensors.
* Version : 10.3
* 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 */
ACI applications can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. ACI-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the Broker SSL Agent. For an introduction see SSL/TLS and Certificates with EntireX in the Platform-independent Administration documentation. This section describes using the Broker ACI with SSL on the following platforms:
SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).
For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.
With the Broker ACI for 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) 
using an appropriate client 
and the z/OS Management Facility (z/OSMF) 
.
Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by
using the application 
job name and remote TCP port number.
If the rules match, the TCP connection is turned into an SSL connection 
.
Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.
|
Client to interact with z/OS Management Facility (z/OSMF). |
|
AT-TLS rules are defined with z/OSMF policy management. |
 |
Policy Repository with AT-TLS rules stored as z/OS files. |
|
Policy Agent, MVS task PAGENT, provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack. |
|
Application using TCP connection. |
|
If AT-TLS rules match, the TCP connection is turned into an SSL connection. |
Notes:
may vary per operating system, for example a Web browser for z/OS 2.1.
includes other administration and management tasks in addition to policy management.
includes other rules, such as IP filtering, network address translation etc.
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the ACI application (client or server) for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection, see above.
Make sure the SSL server to which the ACI application (client or server) connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in Integration Server (IS inbound). See:
Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.
Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup
job BSTTATLS .
If the rules match, the socket connection is turned into an SSL connection .
Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.
|
BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6). |
|
ATLS rules are defined manually. See Sample ATLS Daemon Configuration below. |
|
BSTTATLS is associated with a TCP/IP stack. |
|
Application using TCP connection. |
|
BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections. |
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC component for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection, see above.
Make sure the SSL server to which the RPC component connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:
* Converting inbound EntireX Broker connection * Converts listen port 1971 to SSL listen port 1972 OPTION SERVER ATTLS 1971 AS 2071 SSL * * Converting outbound client connection * Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL OPTION CLIENT ATTLS 1972 TO 192.168.2.100 AS 2072 SSL
Note:
We recommend setting SETPARM value SUBTASK to a value greater than 0 in the ATLS daemon startup job (valid values 0-16, default=0). For example:
// SETPARM SUBTASK=8
See also BSI SSL Installation, Programming and User's Guide.
For additional information see also Using the BSI TCP/IP Stack under Hints for Setting up Broker JCL in z/VSE in the z/VSE Installation documentation and SSL/TLS and Certificates with EntireX.
When you begin to write your first 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 EXX103.SRCE.
Writing Client and Server Applications - How to implement and program client-and-server applications with EntireX Broker.
Writing Applications: Units of Work - Describes the concept of units-of-work programming for EntireX Broker.
Writing Applications: Attach Server - Describes the programming of Attach Server for EntireX Broker. It assumes you are familiar with the basics of EntireX Broker ACI programming.
Writing Applications: Command and Information Services - EntireX Broker provides an API for Command and Information Services (CIS) that include the following: shutting down servers; switching trace on and off; retrieving information on clients; registered servers and services.
Writing Applications using EntireX Security - Programming aids relevant to EntireX Security programming.
Broker ACI Fields - Describes the fields in the EntireX Advanced Communication Interface (ACI) that define Broker functions to be performed.
Broker ACI Functions - Describes the EntireX Broker ACI functions.
Broker UOW Status Transition - Contains the UOW Status transition tables for EntireX Broker.
Broker CIS Data Structures - Describes the data structures of the Command and Information Services.
Using the Broker ID in Applications - Describes the URL-style broker ID and transport-method-style broker ID.