Version 9.6	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

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:

• Call Format

• Broker ACI Control Block Layout

• Broker ACI Control Block DSECT

• ACI Examples and DSECTs

• Related Literature

Call Format

Calls to EntireX Broker use the following arguments:

1. The ACI control block is the first argument.

2. The send buffer is the second argument.

3. The receive buffer is the third argument.

4. The error text buffer is the last argument. It can provide a short text of the error code, if desired. Sufficient buffer length must be supplied to allow the standard 40-byte long message to be returned by EntireX Broker. For ACI version 9 and above, the error text buffer can be greater than 40 bytes as specified in the ACI field ERRTEXT-LENGTH.

The send buffer and the receive buffer addresses must always be provided. If they are not required by the selected EntireX Broker function, you can provide an address to a dummy CL1 field.

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

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

  BALR R14,R15

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

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

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

  See CICSETB.

  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 EntireX Broker control block, i.e. 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.

Broker ACI Control Block Layout

The following table shows the broker fields in order of the physical layout of the broker ACI control block and provides a brief description of each field. The fields are described in more detail under Broker ACI Fields. See the actual layout for Assembler in Broker ACI Control Block DSECT below.

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

Notes:

1. Reserved for future use.
2. You must set this field to a low value (X'00') if you do not intend to use it.
3. The field is transmitted up to the first blank or low value (X'00'). It is not transmitted if the first character is a blank or a low value (X'00').
4. All trailing low values (X'00') are truncated. The field is not transmitted if the entire field is a low value (X'00').
5. If fields are not needed for a specific command function, suppress their transmission by initializing them to blanks or low value (X'00').

Broker ACI Control Block DSECT

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

ACI Examples and DSECTs

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

Notes:

1. See Installing EntireX under z/OS.

Related Literature

• 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.

www.softwareag.com

Copyright © 1997-2014 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT