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:
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 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.
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 for client and server | publish and subscribe.
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 for client and server | publish and subscribe |
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.
|
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 for client and server | publish and subscribe | 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-CLASSSERVER-NAMESERVICE |
S$CLASS DS CL32S$SERVER DS CL32S$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 for client and server | publish and subscribe.
|
1 | ||
PASSWORD |
S$PASSWD DS CL32 |
Password. See Authentication. | 1 | 4,5 | |
TOKEN |
S$TOKEN DS CL32 |
Reconnection token. See USER-ID and TOKEN for client and server | publish and subscribe.
|
1 | 3, 5 | |
SECURITY-TOKEN |
S$STOKEN DS CL32 |
Security token. See Writing Applications using EntireX Security. | 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 for client and server | publish and subscribe. | 1 | 3, 5 | |
ERROR-CODE |
S$ERROR DS CL8 |
Error code. See Error Handling for client and server | publish and subscribe and Error Messages and Codes. | 1 | ||
ENVIRONMENT |
S$ENV DS CL32 |
Environment. See Using Internationalization for client and server | publish and subscribe. | 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 Authentication. | 2 | 4, 5 | |
| Not used. | S$ADERR DS CL8 |
Adapter error. | 2 | ||
CLIENT-UID |
S$CLUID DS CL32 |
Client User ID. See Writing Applications using EntireX Security | 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. See Writing Applications: Units of Work. | 3 | 2 | |
S$RESVD2 |
Reserved for future use. | 3 | Length must be 3 bytes. | ||
LOCALE-STRING |
S$LOCS DS CL40 |
Locale string. To be used to override or provide codepages. See Using Internationalization for client and server | publish and subscribe. | 4 | ||
DATA-ARCH |
S$DARCH DS XL1 |
Data architecture. See ICU Conversion. | 4 | 2 | |
FORCE-LOGON |
S$FLOG DS CL1 |
Override Broker AUTOLOGON. See Authentication.
|
See Writing Applications using EntireX Security. | 6 | |
ENCRYPTION-LEVEL |
S$ENCL DS XL1 |
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 |
S$KERSEC DS CL1 |
Kernel security. | 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 for client and server | publish and subscribe. |
7 | ||
S$RESVD3 |
Reserved for future use. | 7 | Length must be 114 bytes. | ||
S$RESVD4 |
Reserved for future use. | 8 | Length must be 6 bytes. | ||
UWSTAT-LIFETIME |
S$UWSTAL DS CL8 |
Add value for persistent status
lifetime. See UWSTAT-LIFETIME.
|
8 | ||
TOPIC |
S$TOPIC DS CL96 |
Topic name for publish and subscribe. | See Key ACI Field Names. | 8 | |
PUBLICATION-ID |
S$PUBID DS CL16 |
Publication ID for publish and subscribe. | 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 for client and server | publish and subscribe. | 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 | ||
Notes:
The EntireX Developer's Kit 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 - 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 Version : $Revision: 1.77 $
* 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
$VERMIN EQU $VERS1
$VERAMAX EQU $VERS10 Maximum Asm Stub Version
$VERMAX EQU $VERS10 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
$FCTLOCT EQU 15 LOCATION TRANSPARENCY
$FCTSSLP EQU 16 SET SSL PARMS
$FCTSNDP EQU 17 SEND PUBLICATION
$FCTRECP EQU 18 RECEIVE PUBLICATION
$FCTSUBS EQU 19 SUBSCRIBE
$FCTUSUB EQU 20 UNSUBSCRIBE
$FCTCTLP EQU 21 CONTROL PUBLICATION
$FCTRPLY EQU 22 REPLY ERROR
*
* --- 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
$OPTDURA EQU 20 DURABLE
$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
*
* --- 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 Encryption Levels -----------------------------
*
ENCNONE EQU 0 ENCRYPTION LEVEL = 0
ENCBROK EQU 1 ENCRYPTION LEVEL = 1
ENCTRGT EQU 2 ENCRYPTION LEVEL = 2
*
* --- 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
LTOPIC EQU 96 L'Pubsub Topic
LPUBID EQU 16 L'Pubsub ID
*
* --- 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 ENCRYPTION LEVEL
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$TOPIC DS CL(LTOPIC) PUBSUB TOPIC
S$PUBID DS CL(LPUBID) PUBSUB PUBLICATION ID
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
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
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
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. 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).
The following options are available under z/OS:
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) 
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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the 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:
Note:
Not available under CICS.
With the Broker ACI for Assembler, the SSL parameters (e.g. certificates stored in z/OS as RACF keyrings only) are provided
with the function SETSSLPARMS.
To use SSL
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.
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.
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.
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:
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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the 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 ATLS 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.
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
EXX990.SRCE.
|
1 |
| Broker Command and Info Services control block DSECT | See member ASMINF in the mainframe source library
EXX990.SRCE.
|
||
| BS2000/OSD | Broker ACI control block DSECT | See element ASMDEF in the LMS library EXX990.LIB.
|
|
| Broker Command and Info Services control block DSECT | See element ASMINF in the LMS library EXX990.LIB.
|
||
| z/VM | Broker ACI control block DSECT | See member ASMDEF in the z/VM MACLIB library
EXX990.MACLIB.
|
|
| Broker Command and Info Services control block DSECT | See member ASMINF in the z/VM MACLIB library
EXX990.MACLIB.
|
Notes:
Writing Applications: Publish and Subscribe - How to implement and program publish-and-subscribe applications, employing durable subscription techniques, with EntireX Broker.
Writing Applications: Client and Server - 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.
Broker CIS Data Structures - Describes the data structures of the Command and Information 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.
Using the Broker ID in Applications - Describes the URL-style broker ID and transport-method-style broker ID.