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 COBOL and 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 PIC X(1) fields.
The API is called with a statement such as the following:
Under all platforms (except under IBM i) with all Broker stubs:
CALL 'BROKER'USING ETBCB G-SEND-BUFF G-RECV-BUFF ERROR-TEXT
additionally, under z/OS you can invoke
CICSETB, using
the following EXEC CICS LINK command. See CICSETB. The length of the COMMAREA is always 24.
For example:
EXEC CICS LINK PROGRAM('CICSETB') COMMAREA(commarea) 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 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
under IBM i:
CALL LINKAGE TYPE IS PROCEDURE "broker" USING
ETBCB G-SEND-BUFF G-RECV-BUFF ERROR-TEXT
or
CALL "broker" USING
ETBCB G-SEND-BUFF G-RECV-BUFF ERROR-TEXT
with compiler option LINKLIT(*PRC)
If 00000000 (zeros) are returned in the ERROR-CODE field in the EntireX
Broker control block, the operation has been performed successfully. However,
function results other than 00000000 (zeros) do not necessarily indicate an
error. See Error Handling for client and server | publish and subscribe.
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 copybook for COBOL in Broker ACI Control Block Copybook below.
Note:
Header files and examples are provided as models if you want to write your own ACI applications (see ACI Examples and Copybooks 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.
| Broker ACI Field | COBOL Definition | Description / Related Information |
API Vers. |
Notes | |
|---|---|---|---|---|---|
API-TYPE |
ETBCB-TYPE PIC X |
API type. | See API-TYPE and API-VERSION for client and server | publish and subscribe.
|
1 | |
API-VERSION |
ETBCB-VERSION PIC X |
API version. | 1 | ||
FUNCTION |
ETBCB-FUNCTION PIC X |
See Broker ACI Functions to perform Broker function. | 1 | ||
OPTION |
ETBCB-OPTION PIC X |
See OPTION.
|
1 | ||
RESERVED PIC X(16) |
Reserved for future use. | 1 | 1 | ||
SEND-LENGTH |
SEND-LENGTH PIC 9(9) COMP |
Send length. | See Using Send and Receive Buffers for client and server | publish and subscribe. | 1 | |
RECEIVE-LENGTH |
RECEIVE-LENGTH PIC 9(9) COMP |
Receive length. | 1 | ||
RETURN-LENGTH |
RETURN-LENGTH PIC 9(9) COMP |
Return length. | 1 | ||
ERRTEXT-LENGTH |
ERRTEXT-LENGTH PIC 9(9) COMP |
Error text length. | 1 | ||
BROKER-ID |
BROKER-ID PIC X(32) |
Broker ID. See Using the Broker ID in Applications. | 1 | ||
SERVER-CLASSSERVER-NAMESERVICE |
SERVER-CLASS PIC X(32)SERVER-NAME PIC X(32)SERVICE-NAME PIC X(32) |
Service. See Control Block Fields and Verbs. | 1 | 3, 5 | |
USER-ID |
USER-ID PIC X(32) |
User ID. See USER-ID and TOKEN for client and server | publish and subscribe.
|
1 | ||
PASSWORD |
PASSWD PIC X(32) |
Password. See Authentication. | 1 | 4,5 | |
TOKEN |
TOKEN PIC X(32) |
Reconnection token. See USER-ID and TOKEN for client and server | publish and subscribe.
|
1 | 3, 5 | |
SECURITY-TOKEN |
SECURITY-TOKEN PIC X(32) |
Security token. See Writing Applications using EntireX Security. | 1 | 4, 5 | |
CONV-ID |
CONV-ID PIC X(16) |
Conversation ID. See Conversational and Non-conversational Mode. | 1 | 3, 5 | |
WAIT |
WAIT-TIMEOUT PIC X(8) |
Wait value. See Blocked and Non-blocked Broker Calls for client and server | publish and subscribe. | 1 | 3, 5 | |
ERROR-CODE |
ERROR-CODE PIC X(8) |
Error code. See Error Handling for client and server | publish and subscribe. | 1 | ||
ENVIRONMENT |
ENVIRONMNT PIC X(32) |
Environment. See Using Internationalization for client and server | publish and subscribe. | 1 | 3, 5 | |
ADCOUNT |
ADCOUNT PIC 9(9) COMP |
Attempted delivery count. See Writing Applications: Units of Work. | 2 | ||
USER-DATA |
USER-DATA PIC X(16) |
Conversation User Data. See Managing Conversation Contexts. | 2 | 3, 5 | |
| Not used. | MESSAGE-ID PIC X(32) |
Message ID. | 2 | 4, 5 | |
| Not used. | MESSAGE-TYPE PIC X(16) |
Message type. | 2 | 3, 5 | |
LIFE-TIME PIC X(8) |
Reserved for future use. | 2 | 1, 3, 5 | ||
NEWPASSWORD |
NEW-PASSWD PIC X(32) |
New password. See Authentication. | 2 | 4, 5 | |
| Not used. | ADAPTER-ERROR PIC X(8) |
Adapter error. | 2 | ||
CLIENT-UID |
CLIENT-USER-ID PIC X(32) |
Client User ID. See Client User ID. | 2 | ||
CONV-STAT |
CONVSTAT PIC X(1) |
Conversation status. See Conversational and Non-conversational Mode. | 2 | ||
STORE |
STORE PIC X(1) |
Persistence or non-persistence of a UOW. See Writing Applications: Units of Work. | 2 | ||
STATUS PIC X(1) |
Reserved for future use. | 2 | 1 | ||
UOWSTATUS |
UOWSTATUS PIC X(1) |
UOW Status. | See Writing Applications: Units of Work. | 3 | 3, 5 |
UWTIME |
UOWTIME PIC X(8) |
UOW lifetime. | 3 | 3, 5 | |
UOWID |
UOWID PIC X(16) |
UOW unique identifier. | 3 | 3, 5 | |
USTATUS |
USERSTATUS PIC X(32) |
User status. | 3 | ||
UOW-STATUS-PERSIST |
UOWSTATUSPER PIC X(1) |
Multiplier for persistent status lifetime. See Writing Applications: Units of Work. | 3 | 2 | |
RESVD2 PIC X(3) |
Reserved for future use. | 3 | 1 | ||
LOCALE-STRING |
LOCALE-STR PIC X(40) |
Locale string. To be used to override or provide codepages. See Using Internationalization for client and server | publish and subscribe. | 4 | ||
DATA-ARCH |
DATA-ARCH PIC X(1) |
Data architecture. See ICU Conversion. | 4 | 2 | |
FORCE-LOGON |
FORCE-LOGON PIC X(1) |
Override Broke
AUTOLOGON. See Authentication.
|
6 | ||
ENCRYPTION-LEVEL |
ENC-LEVEL PIC X(1) |
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 |
KERSEC PIC X(1) |
Kernel security. See Writing Applications using EntireX Security | 7 | ||
COMMITTIME |
COMMTIME PIC X(17) |
Commit time. See Writing Applications: Units of Work. | 7 | ||
COMPRESSLEVEL |
COMPLVL PIC X(1) |
Compression level. See Data Compression for client and server | publish and subscribe. |
7 | ||
RESVD3 PIC X(2) |
Reserved for future use. | 7 | 1 | ||
RESVD4 PIC 9(9) COMP |
Reserved for future use. | 7 | 1 | ||
UWSTAT-LIFETIME |
UWSTAT-LIFETIME PIC X(8) |
Add value for persistent status
lifetime. See UWSTAT-LIFETIME.
|
8 | ||
TOPIC |
TOPIC PIC X(96) |
Topic name for publish and subscribe. | See Key ACI Field Names. | 8 | |
PUBLICATION-ID |
PUBLICATION-ID PIC X(16) |
Publication ID for publish and subscribe. | 8 | ||
CLIENT-ID |
CLIENT-ID PIC 9(9) |
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 |
LOG-COMMAND PIC X(1) |
Log the current command. See also Programmatically Turning on Command Logging for client and server | publish and subscribe. | 9 | ||
CREDENTIALS-TYPE |
CRED-TYPE PIC X(1) |
Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. | 9 | ||
VARLIST-OFFSET |
VAR-LIST-OFF PIC 9(9) |
Internal Software AG field. | 10 | ||
LONG-BROKER-ID-LENGTH |
LONG-BID-LEN PIC 9(9) |
See LONG-BROKER-ID-LENGTH.
|
10 | ||
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').
The Developer's Kit provides a copybook with the ACI control block definition. See ACI Examples and Copybooks for where it is provided on your platform:
******************************************************************
* Product : EntireX Broker
* Copyright : Copyright (c) 1997 - 2015 Software AG,
* Darmstadt, Germany and/or Software AG USA,
* Inc., Reston, VA, United States of America,
* and/or their licensors.
* Version : 9.9
* File Version : $Revision: 1.48 $
* File : COBDEF
* Description : COBOL ACI control block definitions.
******************************************************************
* Note: When an option value is used it must be added to the
* previous assigned function value.
******************************************************************
*
* --- ENTIRE BROKER API Type Constants ---------------------------
*
01 TYPE-1 PIC 9(4) BINARY VALUE 256.
*
* --- ENTIRE BROKER API Version Constants ------------------------
*
01 VERSION-1 PIC 9(4) BINARY VALUE 1.
01 VERSION-2 PIC 9(4) BINARY VALUE 2.
01 VERSION-3 PIC 9(4) BINARY VALUE 3.
01 VERSION-4 PIC 9(4) BINARY VALUE 4.
01 VERSION-5 PIC 9(4) BINARY VALUE 5.
01 VERSION-6 PIC 9(4) BINARY VALUE 6.
01 VERSION-7 PIC 9(4) BINARY VALUE 7.
01 VERSION-8 PIC 9(4) BINARY VALUE 8.
01 VERSION-9 PIC 9(4) BINARY VALUE 9.
01 VERSION-10 PIC 9(4) BINARY VALUE 10.
*
* --- ENTIRE BROKER API Function Constants -----------------------
*
01 FCT-SEND PIC 9(4) BINARY VALUE 256.
01 FCT-RECEIVE PIC 9(4) BINARY VALUE 512.
01 FCT-UNDO PIC 9(4) BINARY VALUE 1024.
01 FCT-EOC PIC 9(4) BINARY VALUE 1280.
01 FCT-REGISTER PIC 9(4) BINARY VALUE 1536.
01 FCT-DEREGISTER PIC 9(4) BINARY VALUE 1792.
01 FCT-VERSION PIC 9(4) BINARY VALUE 2048.
01 FCT-LOGON PIC 9(4) BINARY VALUE 2304.
01 FCT-LOGOFF PIC 9(4) BINARY VALUE 2560.
01 FCT-SET PIC 9(4) BINARY VALUE 2816.
01 FCT-GET PIC 9(4) BINARY VALUE 3072.
01 FCT-SYNC PIC 9(4) BINARY VALUE 3328.
01 FCT-KERNELVERS PIC 9(4) BINARY VALUE 3584.
01 FCT-LOCTRANS PIC 9(4) BINARY VALUE 3840.
01 FCT-SETSSLPARMS PIC 9(4) BINARY VALUE 4096.
01 FCT-SEND-PUBLICATION PIC 9(4) BINARY VALUE 4352.
01 FCT-RECEIVE-PUBLICATION PIC 9(4) BINARY VALUE 4608.
01 FCT-SUBSCRIBE PIC 9(4) BINARY VALUE 4864.
01 FCT-UNSUBSCRIBE PIC 9(4) BINARY VALUE 5120.
01 FCT-CONTROL-PUBLICATION PIC 9(4) BINARY VALUE 5376.
01 FCT-REPLY-ERROR PIC 9(4) BINARY VALUE 5632.
*
* --- ENTIRE BROKER API Option Constants -------------------------
*
01 OPT-MSG PIC 9(4) BINARY VALUE 1.
01 OPT-HOLD PIC 9(4) BINARY VALUE 2.
01 OPT-IMMED PIC 9(4) BINARY VALUE 3.
01 OPT-QUIESCE PIC 9(4) BINARY VALUE 4.
01 OPT-EOC PIC 9(4) BINARY VALUE 5.
01 OPT-CANCEL PIC 9(4) BINARY VALUE 6.
01 OPT-LAST PIC 9(4) BINARY VALUE 7.
01 OPT-NEXT PIC 9(4) BINARY VALUE 8.
01 OPT-PREVIEW PIC 9(4) BINARY VALUE 9.
01 OPT-COMMIT PIC 9(4) BINARY VALUE 10.
01 OPT-BACKOUT PIC 9(4) BINARY VALUE 11.
01 OPT-SYNCPOINT PIC 9(4) BINARY VALUE 12.
01 OPT-ATTACH PIC 9(4) BINARY VALUE 13.
01 OPT-DELETE PIC 9(4) BINARY VALUE 14.
01 OPT-EOCCANCEL PIC 9(4) BINARY VALUE 15.
01 OPT-QUERY PIC 9(4) BINARY VALUE 16.
01 OPT-SETUSTATUS PIC 9(4) BINARY VALUE 17.
01 OPT-ANY PIC 9(4) BINARY VALUE 18.
01 OPT-TERMINATE PIC 9(4) BINARY VALUE 19.
01 OPT-DURABLE PIC 9(4) BINARY VALUE 20.
01 OPT-CHECKSERVICE PIC 9(4) BINARY VALUE 21.
*
* --- ENTIRE BROKER API Conversation Status Constants ------------
*
01 CNV-NEW PIC 9(4) BINARY VALUE 256.
01 CNV-OLD PIC 9(4) BINARY VALUE 512.
01 CNV-NONE PIC 9(4) BINARY VALUE 768.
*
* --- ENTIRE BROKER API Store Constants --------------------------
*
01 STORE-OFF PIC 9(4) BINARY VALUE 1.
01 STORE-BROKER PIC 9(4) BINARY VALUE 2.
*
* --- ENTIRE BROKER API Status Constants -------------------------
*
01 STATUS-OFF PIC 9(4) BINARY VALUE 256.
01 STATUS-STORED PIC 9(4) BINARY VALUE 512.
01 STATUS-DEL-ATTEMPT PIC 9(4) BINARY VALUE 768.
01 STATUS-DELIVERED PIC 9(4) BINARY VALUE 1024.
01 STATUS-PROCESSED PIC 9(4) BINARY VALUE 1280.
01 STATUS-DEAD PIC 9(4) BINARY VALUE 1536.
*
* --- ENTIRE BROKER API Control Block Definition -----------------
*
01 ETBCB.
02 TYPE-VERSION PIC 9(4) BINARY VALUE 0.
02 FILLER REDEFINES TYPE-VERSION.
04 ETBCB-TYPE PIC X.
04 ETBCB-VERSION PIC X.
02 FCT-OPT PIC 9(4) BINARY VALUE 0.
02 FILLER REDEFINES FCT-OPT.
04 ETBCB-FUNCTION PIC X.
04 ETBCB-OPTION PIC X.
02 RESERVED PIC X(16) VALUE SPACES.
02 SEND-LENGTH PIC 9(9) BINARY VALUE 0.
02 RECEIVE-LENGTH PIC 9(9) BINARY VALUE 0.
02 RETURN-LENGTH PIC 9(9) BINARY VALUE 0.
02 ERRTEXT-LENGTH PIC 9(9) BINARY VALUE 0.
02 BROKER-ID PIC X(32) VALUE SPACES.
02 SERVER-CLASS PIC X(32) VALUE SPACES.
02 SERVER-NAME PIC X(32) VALUE SPACES.
02 SERVICE-NAME PIC X(32) VALUE SPACES.
* SERVICE
02 USER-ID PIC X(32) VALUE SPACES.
02 PASSWD PIC X(32) VALUE SPACES.
* PASSWORD
02 TOKEN PIC X(32) VALUE SPACES.
02 SECURITY-TOKEN PIC X(32) VALUE SPACES.
02 CONV-ID PIC X(16) VALUE SPACES.
02 WAIT-TIMEOUT PIC X(8) VALUE SPACES.
02 ERROR-CODE PIC X(8) VALUE SPACES.
02 ERROR-CODE-X REDEFINES ERROR-CODE.
03 ERROR-CLASS PIC X(4).
03 ERROR-NUMBER PIC X(4).
02 ENVIRONMNT PIC X(32) VALUE SPACES.
* ENVIRONMENT
* V2 additions
02 ADCOUNT PIC 9(9) BINARY VALUE 0.
* ATTEMPTED DELIVERY COUNT
02 USER-DATA PIC X(16) VALUE SPACES.
02 MESSAGE-ID PIC X(32) VALUE SPACES.
02 MESSAGE-TYPE PIC X(16) VALUE SPACES.
02 LIFE-TIME PIC X(8) VALUE SPACES.
02 NEW-PASSWD PIC X(32) VALUE SPACES.
02 ADAPTER-ERROR PIC X(8) VALUE SPACES.
02 CLIENT-USER-ID PIC X(32) VALUE SPACES.
02 CONVSTAT-STORE PIC 9(4) BINARY VALUE 0.
02 FILLER REDEFINES CONVSTAT-STORE.
03 ETBCB-CONVSTAT PIC X.
03 ETBCB-STORE PIC X.
02 STATUS-UOWSTATUS PIC 9(4) BINARY VALUE 0.
02 FILLER REDEFINES STATUS-UOWSTATUS.
03 ETBCB-STATUS PIC X.
03 ETBCB-UOWSTATUS PIC X.
* V3 additions
02 UOWTIME PIC X(8) VALUE SPACES.
02 UOWID PIC X(16) VALUE SPACES.
02 USERSTATUS PIC X(32) VALUE SPACES.
02 UOWSTATUSPER PIC X(1).
02 RESVD2 PIC X(3) VALUE SPACES.
* V4 additions
02 LOCALE-STR PIC X(40) VALUE SPACES.
02 DATA-ARCH PIC X(1).
* V6 additions
02 FORCE-LOGON PIC X(1) VALUE SPACES.
02 ENC-LEVEL PIC X(1).
* V7 additions
02 KERSEC PIC X(1) VALUE SPACES.
02 COMMTIME PIC X(17) VALUE SPACES.
02 COMPLVL PIC X(1) VALUE SPACES.
02 RESVD3 PIC X(2) VALUE SPACES.
02 RESVD4 PIC 9(9) BINARY VALUE 0.
* V8 additions
02 UWSTAT-LIFETIME PIC X(8) VALUE SPACES.
02 TOPIC PIC X(96) VALUE SPACES.
02 PUBLICATION-ID PIC X(16) VALUE SPACES.
* V9 additions
02 RESVD-V99-1 PIC X(32) VALUE SPACE.
02 RESVD-V73-1 PIC 9(9) BINARY VALUE 0.
02 RESVD-V73-2 PIC 9(9) BINARY VALUE 0.
02 RESVD-V73-3 PIC 9(9) BINARY VALUE 0.
02 CLIENT-ID PIC 9(9) BINARY VALUE 0.
02 RESVD-V73-4 PIC X(32) VALUE SPACES.
02 LOG-COMMAND PIC X(1) VALUE SPACES.
02 CRED-TYPE PIC X(1).
02 RESVD-V73-5 PIC X(32) VALUE SPACES.
02 RESVD5 PIC X(2) VALUE SPACES.
* V10 additions
02 VAR-LIST-OFF PIC 9(9) BINARY VALUE 0.
02 LONG-BID-LEN PIC 9(9) BINARY VALUE 0.
*
* --- ENTIRE BROKER Attach Manager Control Block -----------------
*
01 ETBATMCB.
02 A-VERSION PIC 9(4) BINARY VALUE 0.
02 A-NOT-USED PIC 9(4) BINARY VALUE 0.
02 A-N-ATTACH PIC 9(9) BINARY VALUE 0.
* NUMBER OF FAILED SERVER LOOKUPS
02 A-N-SERVER PIC 9(9) BINARY VALUE 0.
* NUMBER OF REGISTERED SERVERS
02 A-N-PEND-CONV PIC 9(9) BINARY VALUE 0.
02 A-N-ACT-CONV PIC 9(9) BINARY VALUE 0.
02 A-SERVER-CLASS PIC X(32) VALUE SPACES.
02 A-SERVER-NAME PIC X(32) VALUE SPACES.
02 A-SERVICE-NAME PIC X(32) VALUE SPACES.
*
* *END*
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 COBOL 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 COBOL, 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 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 client example BCOCCBL and server example BCOSCBL as a model for your own implementation. If the examples are not available on your platform, transfer them (for example using FTP) from a platform where they are delivered.
Depending on your platform for COBOL, you will find the files with the examples, copybooks, etc., at the following locations:
| Platform | Copybooks / Examples | Location | Notes |
|---|---|---|---|
| z/OS | Broker ACI Control Block copybook | See member COBDEF in the mainframe source library
EXX990.SRCE.
|
2, 3 |
| Broker Command and Info Services Control Block copybook | See member COBINF in the mainframe source library
EXX990.SRCE.
|
2, 3, 6 | |
COMMAREA example (used with EXEC LINK)
|
See member ETBCOMM in the mainframe source library
EXX811.SRCE.
|
2, 3 | |
| CIS example to perform INFO server, psf and publication calls | See member BRKCNTL in the mainframe source library
EXX811.SRCE.
|
2, 3, 6 | |
| BS2000/OSD | Broker ACI Control Block copybook | See element COBDEF in the LMS library EXX811.LIB.
|
|
| Broker Command and Info Services Control Block copybook | See element COBINFF in the LMS library EXX811.LIB.
|
||
| IBM i | Broker ACI Control Block copybook | See member COBDEF in include source file QCBLLESRC.
|
1 |
| Broker Command and Info Services Control Block copybook | See member COBINF in include source file QCBLLESRC.
|
1 | |
| Sample procedure for compiling | See member CRT_CBLMOD in source file EXASRC.
|
1 | |
| Sample procedure for binding | See member EXABNDPGM in source file EXASRC.
|
1 | |
| Client example | See member BCOCCBL of type CBLLE in source file EXASRC.
|
1, 5 | |
| Procedure to call client example | See the CL member EXABCOC in source file EXASRC.
|
1, 4 | |
| Procedure to call client example with Security parameters | See the CL member EXABCOCSEC in source file EXASRC.
|
1, 4 | |
| Server example | See member BCOSCBL of type CBLLE in source file EXASRC.
|
1, 5 | |
| Procedure to call server example | See the CL member EXABCOS in source file EXASRC.
|
1, 4 | |
| Procedure to call server example with Security parameters | See the CL member EXABCOSSEC in source file EXASRC.
|
1, 4 | |
| z/VM | Broker ACI Control Block copybook | See member COBDEF in MACLIB EXX990.MACLIB.
|
7 |
| Broker Command and Info Services Control Block copybook | See member COBINF in MACLIB EXX990.MACLIB.
|
7 |
Notes:
Note:
Initializing these fields with spaces is not
recommended.
On the IBM i system, the broker stub is implemented as an object of
type *SRVPGM (Service Program). This object type has the advantage that its
program code can be shared by several programs. It exists as an object on its
own and can therefore be easily replaced without rebinding the user's
application, when a newer version becomes available.
The service program EXA supplied by Software AG contains all the functions necessary for controlling and communicating with the remote broker. To create an executable Broker application on IBM i, you need to develop, in any ILE-enabled programming language, at least one main module to which the EXA service program is bound.
For compilation use the command
CRTCBLMOD with the options:
...OPTION(*NOMONOPRC ...) ...EXTDSPOPT(*NODFRWRT) ...LINKLIT(*PRC)
For binding use the command CRTPGM with
the option:
...BNDSRVPGM(*LIBL/EXA)...
Example:
The following steps show how to create a server application using the program BCOSCBL. See ACI Examples and Copybooks.
The library EXX must be located in the *LIBL list.
To set the library list, you can use the command:
CHGCURLIB CURLIB(EXX)
To compile BCOSCBL, use the command
CRTCBLMOD with options similar to the following:
MODULE(BCOSCBL) SRCFILE(*CURLIB/EXASRC) OUTPUT(*PRINT) OPTION(*NOMONOPRC *MAP *UNREF) EXTDSPOPT(*NODFRWRT) LINKLIT(*PGM)
Or, use the sample procedure CRT_CBLMOD.
If the program has been successfully compiled, the module BCOSCBL will be created.
To produce an executable program, bind the user program BCOSCBL to the
service program EXA supplied by Software AG. Use the command
CRTPGM similar to the following:
CRTPGM PGM(EXX/BCOSCBL) MODULE(*PGM) ENTMOD(*PGM) BNDSRVPGM(EXX/EXA) BNDDIR(*NONE) OPTION(*GEN *WARN *DUPVAR) DETAIL(*EXTENDED)
Or, use the sample program EXABNDPGM.
If the programs have been bound successfully, the object BCOSCBL with type *PGM will be created.
To test the program, you can modify/use the sample procedure EXABCOS as described in the package delivered.
Writing ACI Servers for the RPC-ACI Bridge in COBOL - Overview of tasks and supported data types when writing server applications in COBOL.
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.