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.
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 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.
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 in the ACI Programming documentation. | 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-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.
|
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 in the EntireX Broker ACI Programming documentation. | 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:
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 - 2019 Software AG, Darmstadt,
* Germany and/or Software AG USA, Inc., Reston, VA,
* United States of America, and/or their licensors.
* Version : 10.5
* File 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
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 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 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,
using a client to interact with the z/OS Management Facility (z/OSMF).
The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files.
This file is the configuration file for the Policy Agent, MVS task PAGENT.
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 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
EXX105.SRCE.
|
1 |
| Broker Command and Info Services control block DSECT | See member ASMINF in the mainframe source library
EXX105.SRCE.
|
||
| BS2000 | Broker ACI control block DSECT | See element ASMDEF in the LMS library EXX105.LIB.
|
|
| Broker Command and Info Services control block DSECT | See element ASMINF in the LMS library EXX105.LIB.
|
Notes:
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.