EntireX Broker ACI for Assembler

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 Assembler. 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 addresses must always be provided. If they are not required by the selected EntireX Broker function, you can provide an address to a dummy CL1 field.

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

  • Under z/OS and with all broker stubs, use standard IBM z/OS calling conventions. For example:

    BALR R14,R15

    R1 must point to the parameter list to be passed to broker stub. R13 must point to a 72-byte standard save area.

  • Additionally, under z/OS, you can invoke broker stub CICS, using the following EXEC CICS LINK command. The length of the COMMAREA is always 24.

    EXEC CICS LINK PROGRAM('CICSETB') COMMAREA(MYCOMM) LENGTH(24)

    See CICSETB under Administering Broker Stubs in the z/OS Administration documentation.

    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 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 using z/OS: in REGISTER15, the broker stub returns the last four bytes of the ERROR-CODE field in the Broker ACI control block, that is, the error number.

If CL8'00000000' (zeros) are returned in the ERROR-CODE field, the operation has been performed successfully. However, function results other than CL8'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. The fields are described in more detail under Broker ACI Fields. See the actual layout for Assembler in Broker ACI Control Block DSECT below.

Note:
Header files and examples are provided as models if you want to write your own ACI applications (see ACI Examples and DSECTs 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.

See Broker ACI Fields for more information.

Broker ACI Field Assembler Definition Description /
Related Information
API
Vers.
Notes
API-TYPE S$TYPE DS X API type. See API-TYPE and API-VERSION 1  
API-VERSION S$VERS DS X API version. 1  
FUNCTION S$FCT DS X See Broker ACI Functions to perform the Broker function. 1  
OPTION S$OPT DS X See Option Descriptions. 1  
  S$RESERV DS CL16 Reserved for future use. 1 1
SEND-LENGTH S$LSEND DS F Send length. See Using Send and Receive Buffers 1  
RECEIVE-LENGTH S$LREC DS F Receive length. 1  
RETURN-LENGTH S$LRET DS F Return length. 1  
ERRTEXT-LENGTH S$LETXT DS F Error text length. 1  
BROKER-ID S$BID DS CL32 Broker ID. See Using the Broker ID in Applications. 1  
SERVER-CLASS
SERVER-NAME
SERVICE
S$CLASS DS CL32
S$SERVER DS CL32
S$SERVIC DS CL32
Service. See Control Block Fields and Verbs. 1 3,5
USER-ID S$USERID DS CL32 User ID. See USER-ID and TOKEN. 1  
PASSWORD S$PASSWD DS CL32 Password. See Authentication. 1 4,5
TOKEN S$TOKEN DS CL32 Reconnection token. See USER-ID and TOKEN. 1 3,5
SECURITY-TOKEN S$STOKEN DS CL32 Security token. See Role of Security Token (STOKEN) during Authentication. 1 4,5
CONV-ID S$CONVID DS CL16 Conversation ID. See Conversational and Non-conversational Mode. 1 3,5
WAIT S$WAIT DS CL8 Wait value. See Blocked and Non-blocked Broker Calls. 1 3,5
ERROR-CODE S$ERROR DS CL8 Error code. See Error Handling and Error Messages and Codes. 1  
ENVIRONMENT S$ENV DS CL32 Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT. 1 3,5
ADCOUNT S$ADCNT DS F Attempted delivery count. See Writing Applications: Units of Work. 2  
USER-DATA S$UDATA DS CL16 Conversation User Data. See Managing Conversation Contexts. 2 3,5
Not used. S$MSGID DS CL32 Message ID. 2 4,5
Not used. S$MSGTYP DS CL16 Message type. 2 3,5
  S$PTIME DS CL8 Reserved for future use. 2 1,3,5
NEWPASSWORD S$NPSWD DS CL32 New password. See Changing your Password. 2 4,5
Not used. S$ADERR DS CL8 Adapter error. 2  
CLIENT-UID S$CLUID DS CL32 Client user ID. See Client User ID. 2  
CONV-STAT S$CNVST DS X Conversation status. See Conversational and Non-conversational Mode. 2  
STORE S$STORE DS X Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. 2  
  S$STATUS DS X Reserved for future use. 2 1
UOWSTATUS S$UOWSTA DS X UOW Status. See Writing Applications: Units of Work. 3 3,5
UWTIME S$UOWTIM DS CL8 UOW lifetime. 3 3,5
UOWID S$UOWID DS CL16 UOW unique identifier. 3 3,5
USTATUS S$USRSTA DS CL32 User status 3  
UOW-STATUS-PERSIST S$UOWSTP DS X Multiplier for persistent status lifetime. 3 2
  S$RESVD2 Reserved for future use. Length must be 3 bytes. 3  
LOCALE-STRING S$LOCS DS CL40 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 S$DARCH DS XL1 Data architecture. 4 2
FORCE-LOGON S$FLOG DS CL1 Override Broker AUTOLOGON. See FORCE-LOGON. See Writing Applications using EntireX Security. 6  
  S$ENCL DS XL1 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 S$KERSEC DS CL1 Kernel security. See Is Broker Kernel Secure?. 7  
COMMITTIME S$COMTIM DS CL(LCOMTIM) Commit time. See Writing Applications: Units of Work. 7  
COMPRESSLEVEL S$COMP DS CL1 Compression level.
See Data Compression.
7  
  S$RESVD3 Reserved for future use. Length must be 114 bytes. 7  
  S$RESVD4 Reserved for future use. Length must be 6 bytes. 8  
UWSTAT-LIFETIME S$UWSTAL DS CL8 Add value for persistent status lifetime. See UWSTAT-LIFETIME. 8  
  S$RES731 DS F Reserved for future use. 9  
  S$RES732 DS F Reserved for future use. 9  
  S$RES733 DS F Reserved for future use. 9  
CLIENT-ID S$CLID DS F 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 S$LOGCMD DS CL1 Log the current command. See also Programmatically Turning on Command Logging. 9  
CREDENTIALS-TYPE S$CRDTYP DS CL1 Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. 9  
VARLIST-OFFSET S$OVARLS DS F Internal Software AG field. 10  
LONG-BROKER-ID-LENGTH S$LLBID DS F See LONG-BROKER-ID-LENGTH. 10  
MESSAGE-ID S$NMSGID DS CL64 See Unique Message ID under Broker ACI Functions. 11  
CORRELATION-ID S$CORID DS CL64 CORRELATION-ID. 11  
USE-SPECIFIED-MESSAGE-ID S$USEMID DS X Use supplied MESSAGE-ID for SEND. 11  
USE-SPECIFIED-CORRELATION-ID S$USECID DS X Send supplied CORRELATION-ID to Broker. 11  
  S$RES11 DS F Reserved for future use. 11  
LONG-PASSWORD-LENGTH S$LLPSWD DS F Length of long password. See Authentication. 12  
LONG-NEWPASSWORD-LENGTH S$LLNPWD DS F 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 DSECT

EntireX provides a DSECT with the ACI control block definition. See under ACI Examples and DSECTs where it is provided on your platform.

***********************************************************************
* ENTIRE BROKER API Control Block Definition for use with
* IBM/370 or SIEMENS Assembler Language.
***********************************************************************
* Product        : EntireX Broker
* Copyright      : Copyright (c) 1997 - 2022 Software AG, Darmstadt,
*                  Germany and/or Software AG USA, Inc., Reston, VA,
*                  United States of America, and/or their licensors.
* Version        : 10.9
* File Version   : $Revision: 1.91 $
* File           : ASMDEF
* Description    : Assembler control block definitions.
***********************************************************************
*
* --- ENTIRE BROKER API Type Constants --------------------------------
*
* Please note, these are bit settings
*
$TYPE1   EQU   1                       Normal call type
$TYPE2   EQU   2                       Not used
$TYPE4   EQU   4                       Not used
$TYPE8   EQU   8                       Call could be ReplyError
*
* --- ENTIRE BROKER API Version Constants -----------------------------
*     For a new API version add in a new equate and increase $VERMAX
*
$VERS1   EQU   1
$VERS2   EQU   2
$VERS3   EQU   3
$VERS4   EQU   4
$VERS5   EQU   5
$VERS6   EQU   6
$VERS7   EQU   7
$VERS8   EQU   8
$VERS9   EQU   9
$VERS10  EQU   10
$VERS11  EQU   11
$VERS12  EQU   12
$VERMIN  EQU   $VERS1
$VERAMAX EQU   $VERS12                 Maximum Asm Stub Version
$VERMAX  EQU   $VERS12                 Maximum Kernel Version
*
* --- ENTIRE BROKER API Function Constants ----------------------------
*
$FCTSEND EQU   1                       SEND
$FCTREC  EQU   2                       RECEIVE
$FCTUNDO EQU   4                       UNDO
$FCTEOC  EQU   5                       EOC
$FCTREG  EQU   6                       REGISTER
$FCTDREG EQU   7                       DEREGISTER
$FCTVERS EQU   8                       VERSION
$FCTLOGN EQU   9                       LOGON
$FCTLOGF EQU   10                      LOGOFF
$FCTSET  EQU   11                      SET
$FCTGET  EQU   12                      GET
$FCTSYNC EQU   13                      SYNCPOINT
$FCTKVER EQU   14                      KERNELVERS
$FCTRPLY EQU   22                      REPLY ERROR
$FCTGMID EQU   26                      GET MESSAGE ID
*
* --- ENTIRE BROKER API Option Constants ------------------------------
*
$OPTOFF  EQU   0                       OFF
$OPTMSG  EQU   1                       MSG
$OPTHOLD EQU   2                       HOLD
$OPTIMME EQU   3                       IMMED
$OPTQUIE EQU   4                       QUIESCE
$OPTEOC  EQU   5                       EOC
$OPTCANC EQU   6                       CANCEL
$OPTLAST EQU   7                       LAST
$OPTNEXT EQU   8                       NEXT
$OPTPREV EQU   9                       PREVIEW
$OPTCOMM EQU   10                      COMMIT
$OPTBACK EQU   11                      BACKOUT
$OPTSYNC EQU   12                      SYNCPOINT
$OPTATT  EQU   13                      ATTACH
$OPTDEL  EQU   14                      DELETE
$OPTEOCC EQU   15                      EOC CANCEL
$OPTQRY  EQU   16                      QUERY
$OPTSETS EQU   17                      SET STATUS
$OPTANY  EQU   18                      ANY
$OPTTERM EQU   19                      TERMINATE
$OPTCSCV EQU   21                      CHECK SERVICE
*
* --- ENTIRE BROKER API Conversation Status Constants -----------------
*
$CNVNEW  EQU   1                       NEW
$CNVOLD  EQU   2                       OLD
$CNVNONE EQU   3                       NONE
*
* --- ENTIRE BROKER API Store Constants -------------------------------
*
$STROFF  EQU   1                       OFF
$STRBROK EQU   2                       BROKER
*
* --- ENTIRE BROKER API Status Constants ------------------------------
*
$STAOFF  EQU   1                       OFF
$STASTOR EQU   2                       STORED
$STADELA EQU   3                       DELIVERY ATTEMPTED
$STADELD EQU   4                       DELIVERED
$STAPROC EQU   5                       PROCESSED
$STADEAD EQU   6                       DEAD
*
* --- ENTIRE BROKER API UWSTATUS Options ------------------------------
*
$UWSNONE EQU   0                       RECEIVE NONE
$UWSRCVD EQU   1                       RECEIVED
$UWSACCP EQU   2                       ACCEPTED
$UWSDELV EQU   3                       DELIVERED
$UWSBOUT EQU   4                       BACKEDOUT
$UWSPROC EQU   5                       PROCESSED
$UWSCANC EQU   6                       CANCELLED
$UWSTOUT EQU   7                       TIMEOUT
$UWSDISC EQU   8                       DISCARDED
$UWSRCVF EQU   9                       RECV_FIRST
$UWSRCVM EQU   10                      RECV_MIDDLE
$UWSRCVL EQU   11                      RECV_LAST
$UWSRCVO EQU   12                      RECV_ONLY
$UWSPPON EQU   13                      POSTPONED
*
* --- ENTIRE BROKER API Architecture Constants ------------------------
*
$ACOHAI  EQU   1                       HIGH ASCII IBM
$ACOLAI  EQU   2                       LOW ASCII IBM
$ACOHEI  EQU   3                       HIGH EBCDIC IBM
$ACOLEI  EQU   4                       LOW EBCDIC IBM
$ACOHAV  EQU   5                       HIGH ASCII VAX
$ACOLAV  EQU   6                       LOW ASCII VAX
$ACOHEV  EQU   7                       HIGH EBCDIC VAX
$ACOLEV  EQU   8                       LOW EBCDIC VAX
$ACOHAE  EQU   9                       HIGH ASCII IEEE
$ACOLAE  EQU   10                      LOW ASCII IEEE
$ACOHEE  EQU   11                      HIGH EBCDIC IEEE
$ACOLEE  EQU   12                      LOW EBCDIC IEEE
*
* --- ENTIRE BROKER API Force Logon values ----------------------------
*
FLOGYES  EQU   C'Y'                    FORCE LOGON YES
FLOGNO   EQU   C'N'                    FORCE LOGON NO
FLOGS    EQU   C'S'                    FORCE LOGON S
*
* --- ENTIRE BROKER API -----------------------------------------------
*
ENCNONE  EQU   0                       
ENCBROK  EQU   1                       DEPRECATED
ENCTRGT  EQU   2                       DEPRECATED
*
* --- ENTIRE BROKER API Kernel Security -------------------------------
*
KSECNO   EQU   C'N'                    INDICATES NO KERNEL SECURITY
KSECYES  EQU   C'Y'                    INDICATES KERNEL SECURITY ON
KSECUSER EQU   C'U'                    INDICATES KERNEL SECURITY USER
KSECLITE EQU   C'L'                    INDICATES KERNEL SECURITY LIGHT
*
* --- ENTIRE BROKER API Compression Level -----------------------------
*
$COMP0   EQU   C'0'                    COMPRESSION LEVEL = 0
$COMP1   EQU   C'1'                    COMPRESSION LEVEL = 1
$COMP2   EQU   C'2'                    COMPRESSION LEVEL = 2
$COMP3   EQU   C'3'                    COMPRESSION LEVEL = 3
$COMP4   EQU   C'4'                    COMPRESSION LEVEL = 4
$COMP5   EQU   C'5'                    COMPRESSION LEVEL = 5
$COMP6   EQU   C'6'                    COMPRESSION LEVEL = 6
$COMP7   EQU   C'7'                    COMPRESSION LEVEL = 7
$COMP8   EQU   C'8'                    COMPRESSION LEVEL = 8
$COMP9   EQU   C'9'                    COMPRESSION LEVEL = 9
$COMPY   EQU   C'Y'                    COMPRESSION LEVEL = Y
$COMPN   EQU   C'N'                    COMPRESSION LEVEL = N
*
* --- ENTIRE BROKER API Size Of Fields --------------------------------
*
LPUID    EQU   28                      L'ADABAS Extended UserID
LPLTFRM  EQU   8                       L'PLATFORM String
LTRNAME  EQU   8                       L'Translation Module Name
LTXTOK   EQU   64                      L'TxToken
LTXCLTOK EQU   64                      L'TxClientToken
LCOMTIM  EQU   17                      L'Commit Time
LMSGID   EQU   64                      L'MessageID
*
* --- ENTIRE BROKER API Control Block ---------------------------------
*
*     For a new version of the ETBCB, add an equate to the end to
*     indicate the length of the previous version, then add to the
*     end. The length field for a version is LETBCBx where "x"
*     is the version name.  The current version length is LETBCB.
*
ETBCB    DSECT ,
S$TYPE   DS    X                       API-TYPE
S$VERS   DS    X                       API-VERSION
S$FCT    DS    X                       FUNCTION
S$OPT    DS    X                       OPTION
S$RESERV DS    CL16                    RESERVED
S$LSEND  DS    F                       SEND-LENGTH
S$LREC   DS    F                       RECEIVE-LENGTH
S$LRET   DS    F                       RETURN-LENGTH
S$LETXT  DS    F                       ERRTEXT-LENGTH
S$BID    DS    CL32                    BROKER-ID
S$CLASS  DS    CL32                    SERVER-CLASS
S$SERVER DS    CL32                    SERVER-NAME
S$SERVIC DS    CL32                    SERVICE
S$USERID DS    CL32                    USER-ID
S$PASSWD DS    CL32                    PASSWORD
S$TOKEN  DS    CL32                    TOKEN
S$STOKEN DS    CL32                    SECURITY-TOKEN
S$CONVID DS    CL16                    CONV-ID
S$WAIT   DS    CL8                     WAIT
S$ERROR  DS   0CL8                     ERROR-CODE
S$ERRCL  DS    CL4                     ERROR-CLASS
S$ERRNR  DS    CL4                     ERROR-NUMBER
S$ENV    DS    CL32                    ENVIRONMENT
LETBCB1  EQU   *-ETBCB             --- VERSION 1 LENGTH
S$ADCNT  DS    F                       ATTEMPTED DELIVERY COUNT
S$UDATA  DS    CL16                    USER DATA FIELD
S$MSGID  DS    CL32                    NOT USED BY BROKER
S$MSGTYP DS    CL16                    NOT USED BY BROKER
S$PTIME  DS    CL8                     NOT USED BY BROKER
S$NPSWD  DS    CL32                    NEW PASSWORD OF CALLER
S$ADERR  DS    CL8                     ADAPTER ERROR
S$CLUID  DS    CL32                    CLIENT USER-ID
S$CNVST  DS    X                       CONVERSATION STATUS
S$STORE  DS    X                       STORE MESSAGE
S$STATUS DS    X                       NOT USED BY BROKER
S$UOWSTA DS    X                       STATUS OF UNIT-OF-WORK
LETBCB2  EQU   *-ETBCB             --- VERSION 2 LENGTH
S$UOWTIM DS    CL8                     LIFETIME OF UOW
S$UOWID  DS    CL16                    UNIT-OF-WORK ID
S$USRSTA DS    CL32                    USER STATUS
S$UOWSTP DS    X                       UOW STATUS PERSIST FLAG
S$RESVD2 DS    XL3                     RESERVED
         DS    0F                      ALIGNMENT
LETBCB3  EQU   *-ETBCB             --- VERSION 3 LENGTH
S$LOCS   DS    CL40                    LOCALE STRING
S$DARCH  DS    XL1                     FOR FUTURE USE
S$FLOG   DS    CL1                     FORCE LOGON
S$ENCL   DS    XL1                     DEPRECATED - USE AT-TLS
S$KERSEC DS    CL1                     KERNEL SECURITY
LETBCB4  EQU   *-ETBCB             --- VERSION 4 LENGTH
S$COMTIM DS    CL(LCOMTIM)             COMMIT_TIME
S$COMP   DS    CL1                     COMPRESSION LEVEL
S$RESVD3 DS    CL114
LETBCB6  EQU   *-ETBCB             --- VERSION 6 LENGTH
LETBCB7  EQU   *-ETBCB             --- VERSION 7 LENGTH
         ORG   S$RESVD3
S$RESVD4 DS    CL6
S$UWSTAL DS    CL8                     UOW STATUS LIFE TIME (V8)
S$RES911 DS    CL96                    RESERVED FOR FUTURE USE
S$RES912 DS    CL16                    RESERVED FOR FUTURE USE
LETBCB8  EQU   *-ETBCB             --- VERSION 8 LENGTH
S$RES991 DS    CL32                    RESERVED FOR FUTURE USE
S$RES731 DS    F                       RESERVED FOR FUTURE USE
S$RES732 DS    F                       RESERVED FOR FUTURE USE
S$RES733 DS    F                       RESERVED FOR FUTURE USE
S$CLID   DS    F                       CLIENT_ID
S$RES734 DS    CL32                    RESERVED FOR FUTURE USE
S$LOGCMD DS    CL1                     LOG THIS COMMAND
S$CRDTYP DS    CL1                     CREDENTIALS TYPE
S$RES735 DS    CL32                    RESERVED FOR FUTURE USE
         DS    CL2                     ALIGNMENT
LETBCB9  EQU   *-ETBCB             --- VERSION 9 LENGTH
S$OVARLS DS    F                       VARIABLE LIST OFFSET
S$LLBID  DS    F                       LENGTH LONG BROKER-ID
LETBCB10 EQU   *-ETBCB             --- VERSION 10 LENGTH
S$NMSGID DS    CL(LMSGID)              MSG ID OF SENT/RCVD MSG
S$CORID  DS    CL(LMSGID)              MSG ID OF SENT MSG
S$USEMID DS    X                       No new MSG ID for SEND
S$USECID DS    X                       Send COR ID to Broker
         DS    CL2                     ALIGNMENT
S$RES11  DS    F                       RESERVED FOR FUTURE USE
LETBCB11 EQU   *-ETBCB             --- VERSION 11 LENGTH
S$LLPSWD DS    F                       LENGTH LONG PASSWORD
S$LLNPWD DS    F                       LENGTH LONG NEW PASSWORD
LETBCB12 EQU   *-ETBCB             --- VERSION 12 LENGTH
         ORG   ,
LETBCB   EQU   *-ETBCB                 ETBCB LENGTH
*
* --- ENTIRE BROKER Attach Manager Control Block ----------------------
*
ETBATMCB DSECT ,
A$VERS   DS    H                       VERSION OF STRUCTURE
         DS    H                       ALIGNMENT
A$NATTCH DS    F                       NO. FAILED SERVER LOOKUPS
A$NSERVR DS    F                       NO. REGISTERED SERVER
A$NCPEND DS    F                       NO. PENDING CONVERSATIONS
A$NCACT  DS    F                       NO. ACTIVE CONVERSATIONS
A$CLASS  DS    CL(L'S$CLASS)           CLASS NAME TO ATTACH
A$SERVER DS    CL(L'S$SERVER)          SERVER NAME TO ATTACH
A$SERVIC DS    CL(L'S$SERVIC)          SERVICE NAME TO ATTACH
         DS    0H                      ALIGNMENT
LETBATMC EQU   *-ETBATMCB              ETBATMCB LENGTH
*
* --- End of definitions

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 Assembler 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-asm.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 sample 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) See z/OSMF Considerations in the z/OS Administration documentation. 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 sample 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 ATLS to turn the TCP/IP connection to an SSL connection, see above.

  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 DSECTs

Depending on your platform for Assembler, you will find the files with the examples, DSECTs, etc., at the following locations:

Platform DSECTs / Examples Location Note
z/OS Broker ACI control block DSECT See member ASMDEF in the mainframe source library EXX109.SRCE. 1
Broker Command and Info Services control block DSECT See member ASMINF in the mainframe source library EXX109.SRCE.
BS2000 Broker ACI control block DSECT See element ASMDEF in the LMS library EXX109.LIB.  
Broker Command and Info Services control block DSECT See element ASMINF in the LMS library EXX109.LIB.

Notes:

  1. See Installing EntireX under z/OS.

Related Literature

Writing Applications

Reference