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-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 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. | 6 | |
ENCRYPTION-LEVEL |
S$ENCL DS XL1 |
Encryption level. | 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. Enter "1" to specify IAF authentication. | 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 : (c) Copyright Software AG 1997 - 2012. * All rights reserved. * Version : 9.0 * File Version : $Revision: 1.1 $ * 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 ------------------------------ * $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$SBID DS CL32 PARTNER BROKER ID 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
Depending on your platform for Assembler, you will find the files with the examples, DSECTs, etc., in the following locations:
Platform | DSECTs / Examples | Location | Note |
---|---|---|---|
z/OS | Broker ACI control block DSECT | See member ASMDEF in the mainframe source library
EXX970.SRCE.
|
1 |
Broker Command and Info Services control block DSECT | See member ASMINF in the mainframe source library
EXX970.SRCE.
|
||
BS2000/OSD | Broker ACI control block DSECT | See element ASMDEF in the LMS library EXX970.LIB.
|
|
Broker Command and Info Services control block DSECT | See element ASMINF in the LMS library EXX970.LIB.
|
||
z/VM | Broker ACI control block DSECT | See member ASMDEF in the z/VM MACLIB library
EXX970.MACLIB.
|
|
Broker Command and Info Services control block DSECT | See member ASMINF in the z/VM MACLIB library
EXX970.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.