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 Natural. 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 with 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 set them as short A1 fields.
The API is called with a statement such as the following for all platforms:
CALL 'BROKER' #ETBCB #SEND-AREA #RECEIVE-AREA #ERROR-TEXT
Natural applications can access the last four bytes of the error code through the RET function.
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.
On UNIX and Windows, the length of fields #SEND-AREA and #RECEIVE-AREA cannot exceed 65535. If you want to send and/or receive more data,
redefine #SEND-AREA and/or #RECEIVE-AREA with a value of, say, A1 and use these fields in the CALL statement. For example:
01 #SEND-AREA (A65536) 01 REDEFINE #SEND-AREA 02 #SEND-AREA-R (A1) 01 #RECEIVE-AREA (A65536) 01 REDEFINE #RECEIVE-AREA 02 #RECEIVE-AREA-R (A1) . CALL 'BROKER' #ETB-CB #SEND-AREA-R #RECEIVE-AREA-R #ERROR-TEXT
The following table shows the Broker fields in the order of the physical layout of the Broker ACI control block and provides a brief description of each field. See the actual copycode for Natural below in Broker ACI Control Block Data Area.
See Broker ACI Fields for more information.
| Broker ACI Field | Natural Definition | Description / Related Information |
API Vers. |
Notes | |
|---|---|---|---|---|---|
API-TYPE |
#TYPE (I1) |
API type. | See API-TYPE and API-VERSION.
|
1 | |
API-VERSION |
#VERSION (I1) |
API version. | 1 | ||
FUNCTION |
#FUNCTION (I1) |
See Broker ACI Functions to perform Broker function. | 1 | ||
OPTION |
#OPTION (I1) |
See OPTION.
|
1 | ||
#RESERVED (I4/4) |
Reserved for future use. | 1 | 1 | ||
SEND-LENGTH |
#SEND-LEN (I4) |
Send length. | See Using Send and Receive Buffers. | 1 | |
RECEIVE-LENGTH |
#RECEIVE-LEN (I4) |
Receive length. | 1 | ||
RETURN-LENGTH |
#RETURN-LEN (I4) |
Return length. | 1 | ||
ERRTEXT-LENGTH |
#ERRTEXT-LEN (I4) |
Error text length. | 1 | ||
BROKER-ID |
#BROKER-ID (A32) |
Broker ID. See Using the Broker ID in Applications. | 1 | ||
SERVER-CLASSSERVER-NAMESERVICE |
#SERVER-CLASS (A32)#SERVER-NAME (A32)#SERVICE (A32) |
Service. See Control Block Fields and Verbs. | 1 | 3,5 | |
USER-ID |
#USER-ID (A32) |
User ID. See USER-ID and TOKEN.
|
1 | ||
PASSWORD |
#PASSWORD (A32) |
Password. See Authentication. | 1 | 4,5 | |
TOKEN |
#TOKEN (A32) |
Reconnection token. See USER-ID and TOKEN.
|
1 | 3,5 | |
SECURITY-TOKEN |
#SECURITY-TOKEN (B32) |
Security token. See Writing Applications using EntireX Security. | 1 | 4,5 | |
CONV-ID |
#CONV-ID (A16) |
Conversation ID. See Conversational and Non-conversational Mode. | 1 | 3,5 | |
WAIT |
#WAIT (A8) |
Wait value. See Blocked and Non-blocked Broker Calls. | 1 | 3,5 | |
ERROR-CODE |
#ERROR-CODE (A8) |
Error code. See Error Handling and Error Messages and Codes. | 1 | ||
ENVIRONMENT |
#ENVIRONMENT (A32) |
Pass additional information to Translation User Exit. For more information see ACI field ENVIRONMENT.
|
1 | 3,5 | |
ADCOUNT |
#ADCOUNT (I4) |
Attempted delivery count. See Writing Applications: Units of Work. | 2 | ||
USER-DATA |
#USER-DATA (B16) |
Conversation User Data. See Managing Conversation Contexts. | 2 | 3,5 | |
| Not used. | #MSG-ID (B32) |
Message ID. | 2 | 4,5 | |
| Not used. | #MSG-TYPE (A16) |
Message type. | 2 | 3,5 | |
NEWPASSWORD |
#NEWPASSWORD (B32) |
New password. See Authentication. | 2 | 4,5 | |
| Not used. | #ADAPTER-ERROR (A8) |
Adapter error. | 2 | ||
CLIENT-UID |
#CLIENT-UID (A32) |
Client User ID. See Writing Applications using EntireX Security | 2 | ||
CONV-STAT |
#CONV-STAT (I1) |
Conversation status. See Conversational and Non-conversational Mode. | 2 | ||
STORE |
#STORE (I1) |
Persistence or non-persistence of a UOW. | See Writing Applications: Units of Work. | 2 | |
UOWSTATUS |
#UOWSTATUS (I1) |
UOW Status. | 3 | 3,5 | |
UWTIME |
#UOWTIME (A8) |
UOW lifetime. | 3 | 3,5 | |
UOWID |
#UOWID (A16) |
UOW unique identifier. | 3 | 3,5 | |
USTATUS |
#USERSTATUS (A32) |
User status. | 3 | ||
UOW-STATUS-PERSIST |
#UOWSTATUSPERSIST (I1) |
Multiplier for persistent status lifetime. | 3 | 2 | |
LOCALE-STRING |
#LOCS (A40) |
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 | ||
FORCE-LOGON |
#FLOG (A1) |
Override Broker AUTOLOGON. See Authentication.
|
See Writing Applications using EntireX Security. | 6 | |
#ENCL (I1) |
Encryption level. 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 |
#KERNELSECURITY (A1) |
Kernel security. | 7 | ||
COMMITTIME |
#COMMITTIME (A17) |
Commit time. See Writing Applications: Units of Work. | 7 | ||
COMPRESSLEVEL |
#COMPRESSLEVEL (A1) |
Compression level. See Data Compression. | 7 | ||
UWSTAT-LIFETIME |
#UWSTATUSLIFE (A8) |
Add value for persistent status
lifetime. See UWSTAT-LIFETIME.
|
8 | ||
CLIENT-ID |
#CLIENT-ID (I4) |
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). See also
Tracing.
|
9 | ||
LOG-COMMAND |
#LOG-COMMAND (A1) |
Log the current command. See also Programmatically Turning on Command Logging. | 9 | ||
CREDENTIALS-TYPE |
#CREDENTIALS-TYPE (A1) |
Indicates the credentials type to be used to authenticate a user. The default is to use user ID and password. | 9 | ||
VARLIST-OFFSET |
#VARLIST-OFFSET (I4) |
Internal Software AG field. | 10 | ||
LONG-BROKER-ID-LENGTH |
#LONG-BROKER-ID-LENGTH (I4) |
See LONG-BROKER-ID-LENGTH.
|
10 | ||
MESSAGE-ID |
#MESSAGE-ID (A64) |
See Unique Message ID under Broker ACI Functions in the EntireX Broker ACI Programming documentation. | 11 | ||
CORRELATION-ID |
#CORRELATION-ID (A64) |
CORRELATION-ID. |
11 | ||
USE-SPECIFIED-MESSAGE-ID |
#USE-SPECIFIED-MESSAGE-ID (I1) |
Use supplied MESSAGE-ID for SEND.
|
11 | ||
USE-SPECIFIED-CORRELATION-ID |
#USE-SPECIFIED-CORRELATION-ID (I1) |
Send supplied CORRELATION-ID to Broker.
|
11 | ||
#RESERVED6 (A3) |
Reserved for future use. | 11 | |||
#RESERVED7 (I4) |
Reserved for future use. | 11 | |||
Notes:
To produce a Natural LDA object
Cut and paste the data area below into a Natural program source.
Append it with an END statement and STOW the module.
Open the LDA editor and incorporate the data area using line command .i(program source-name).
* ---------------------------------------------------------------------
* Product .....: EntireX Broker
* Copyright : Copyright (c) 1997 - 2017 Software AG, Darmstadt,
* Germany and/or Software AG USA, Inc., Reston, VA,
* United States of America, and/or their licensors.
*
* Use, reproduction, transfer, publication or disclosure
* is prohibited except as specifically provided for in
* your License Agreement with Software AG.
* Version : 10.1
* Description : Natural language ACI control block definitions
*
* To call broker use CALL 'BROKER' #ETBCB
* To set CB fields use ASSIGN #SDPA-CB.#xxxx = .
*
* * * * * * * * * * * * * * * * * * Attention* * * * * * * * * * * * *
* These statements do not work to CALL 'BROKER' #SDPA-CB(*)
* call the broker CALL 'BROKER' #SDPA-API .
* ---------------------------------------------------------------------
* EntireX Broker API Function Constants ---------------
DEFINE DATA LOCAL
1 #FCT-SEND(I1) INIT <1>
1 #FCT-RECEIVE(I1) INIT <2>
1 #FCT-UNDO(I1) INIT <4>
1 #FCT-EOC(I1) INIT <5>
1 #FCT-REGISTER(I1) INIT <6>
1 #FCT-DEREGISTER(I1) INIT <7>
1 #FCT-VERSION(I1) INIT <8>
1 #FCT-LOGON(I1) INIT <9>
1 #FCT-LOGOFF(I1) INIT <10>
1 #FCT-SET(I1) INIT <11>
1 #FCT-GET(I1) INIT <12>
1 #FCT-SYNCPOINT(I1) INIT <13>
1 #FCT-KVER(I1) INIT <14>
1 #FCT-LOCT(I1) INIT <15>
1 #FCT-SSLP(I1) INIT <16>
1 #FCT-SEND-P(I1) INIT <17>
1 #FCT-RCVE-P(I1) INIT <18>
1 #FCT-SUBS-P(I1) INIT <19>
1 #FCT-USUB-P(I1) INIT <20>
1 #FCT-CNTL-P(I1) INIT <21>
1 #FCT-RPLY-E(I1) INIT <22>
*
* EntireX Broker API Option Constants ---------------
1 #OPT-MSG(I1) INIT <1>
1 #OPT-HOLD(I1) INIT <2>
1 #OPT-IMMED(I1) INIT <3>
1 #OPT-QUIESCE(I1) INIT <4>
1 #OPT-EOC(I1) INIT <5>
1 #OPT-CANCEL(I1) INIT <6>
1 #OPT-LAST(I1) INIT <7>
1 #OPT-NEXT(I1) INIT <8>
1 #OPT-PREVIEW(I1) INIT <9>
1 #OPT-COMMIT(I1) INIT <10>
1 #OPT-BACKOUT(I1) INIT <11>
1 #OPT-SYNC(I1) INIT <12>
1 #OPT-ATTACH(I1) INIT <13>
1 #OPT-DELETE(I1) INIT <14>
1 #OPT-EOCCANCEL(I1) INIT <15>
1 #OPT-QUERY(I1) INIT <16>
1 #OPT-SETSTATUS(I1) INIT <17>
1 #OPT-ANY(I1) INIT <18>
1 #OPT-TERMINATE(I1) INIT <18>
1 #OPT-DURABLE(I1) INIT <20>
1 #OPT-CHECKSVC(I1) INIT <21>
*
* EntireX Broker Conversation Status Constants --------
1 #CONVSTAT-NEW(I1) INIT <1>
1 #CONVSTAT-OLD(I1) INIT <2>
1 #CONVSTAT-NONE(I1) INIT <3>
*
* EntireX Broker Store Constants ---------------
1 #STORE-OFF(I1) INIT <1>
1 #STORE-BROKER(I1) INIT <2>
1 #STORE-ON(I1) INIT <2>
*
* EntireX Broker Status Constants ---------------
1 #STAT_OFF(I1) INIT <1>
1 #STAT_STORED(I1) INIT <2>
1 #STAT_DELIVERY-ATTEMP(INIT <3>
1 #STAT_DELIVERED(I1) INIT <4>
1 #STAT_PROCESSED(I1) INIT <5>
1 #STAT_DEAD(I1) INIT <6>
*
* EntireX Broker UOW Status Constants ---------------
1 #RECV-NONE(I1) INIT <0>
1 #RECEIVED(I1) INIT <1>
1 #ACCEPTED(I1) INIT <2>
1 #DELIVERED(I1) INIT <3>
1 #BACKEDOUT(I1) INIT <4>
1 #PROCESSED(I1) INIT <5>
1 #CANCELLED(I1) INIT <6>
1 #TIMEOUT(I1) INIT <7>
1 #DISCARDED(I1) INIT <8>
1 #RECV-FIRST(I1) INIT <9>
1 #RECV-MIDDLE(I1) INIT <10>
1 #RECV-LAST(I1) INIT <11>
1 #RECV-ONLY(I1) INIT <12>
*
* EntireX Broker Locale String Constants ---------------
1 #ETB-CODEPAGE-USE-DEFAULT(A5) INIT<'LOCAL'>
*
* EntireX Broker Force Logon Constants ---------------
1 #FLOG-YES(A1) INIT <'Y'>
1 #FLOG-NO(A1) INIT <'N'>
1 #FLOG-S(A1) INIT <'S'>
*
* EntireX Broker Encryption Level Constants ---------------
1 #ENCLEVEL-NONE(I1) INIT<0>
1 #ENCLEVEL-TO-BROKER(I1) INIT<1>
1 #ENCLEVEL-TO-TARGET(I1) INIT<2>
*
* EntireX Broker KernelSecurity Constants ---------------
1 #KERNEL-SECURITY-NO(A1) INIT<'N'>
1 #KERNEL-SECURITY-YES(A1) INIT<'Y'>
1 #KERNEL-SECURITY-USER(A1) INIT<'U'>
1 #KERNEL-SECURITY-LIGHT(A1) INIT<'L'>
*
* EntireX Broker Compression Level Constants ---------------
1 #COMPRESS-LEVEL-0(A1) INIT<'0'>
1 #COMPRESS-LEVEL-1(A1) INIT<'1'>
1 #COMPRESS-LEVEL-2(A1) INIT<'2'>
1 #COMPRESS-LEVEL-3(A1) INIT<'3'>
1 #COMPRESS-LEVEL-4(A1) INIT<'4'>
1 #COMPRESS-LEVEL-5(A1) INIT<'5'>
1 #COMPRESS-LEVEL-6(A1) INIT<'6'>
1 #COMPRESS-LEVEL-7(A1) INIT<'7'>
1 #COMPRESS-LEVEL-8(A1) INIT<'8'>
1 #COMPRESS-LEVEL-9(A1) INIT<'9'>
1 #COMPRESS-LEVEL-NO(A1) INIT<'N'>
1 #COMPRESS-LEVEL-YES(A1) INIT<'Y'>
*
* EntireX Broker Credential Type Constants ---------------
1 #CREDENTIAL-TYPE-UID-PWD(I1) INIT<0>
1 #CREDENTIAL-TYPE-IAF(I1) INIT<1>
*
* EntireX Broker API Control Block Definition --------------
*
1 #SDPA-CB (B110/8)
1 REDEFINE #SDPA-CB
2 #ETBCB (A1) /* V1 to pass CB to stub
1 REDEFINE #SDPA-CB
2 #ETBAPI (A1) /* V1 don't use/deprecated
1 REDEFINE #SDPA-CB
2 #SDPA-API /* V1 don't use/deprecated
3 #TYPE (I1) /* V1 type of ETBCB
3 REDEFINE #TYPE
4 #API-TYPE (I1) /* V1 alternative name
3 #VERSION (I1) /* V1 version of ETBCB
3 REDEFINE #VERSION
4 #API-VERSION (I1) /* V1 alternative name
3 #FUNCTION (I1) /* V1 function
3 #OPTION (I1) /* V1 option
3 #RESERVED (I4/4) /* V1 reserved
3 #SEND-LEN (I4) /* V1 length of send data
3 REDEFINE #SEND-LEN
4 #SEND-LENGTH (I4) /* V1 alternative name
3 #RECEIVE-LEN (I4) /* V1 max. len. rec. data
3 REDEFINE #RECEIVE-LEN
4 #RECEIVE-LENGTH (I4) /* V1 alternative name
3 #RETURN-LEN (I4) /* V1 length of rec.data
3 REDEFINE #RETURN-LEN
4 #RETURN-LENGTH (I4) /* V1 alternative name
3 #ERRTEXT-LEN (I4) /* V1 max. len. error text
3 REDEFINE #ERRTEXT-LEN
4 #ERRTEXT-LENGTH (I4) /* V1 alternative name
3 #BROKER-ID (A32) /* V1 target broker ID
3 #SERVER-CLASS (A32) /* V1 part of service name
3 #SERVER-NAME (A32) /* V1 part of service name
3 #SERVICE (A32) /* V1 part of service name
3 #USER-ID (A32) /* V1 user ID of caller
3 #PASSWORD (B32) /* V1 password of caller
3 REDEFINE #PASSWORD
4 #PASSWORD-C (A1/32)
3 #TOKEN (A32) /* V1 special purposes
3 #SECURITY-TOKEN (B32) /* V1 security purposes
3 REDEFINE #SECURITY-TOKN
4 #SECURITY-TOKEN-C (A1/32)
3 #CONV-ID (A16) /* V1 conv./non-conv.
3 #WAIT (A8) /* V1 blocked/non-blocked
3 #ERROR-CODE (A8) /* V1 error class/number
3 REDEFINE #ERROR-CODE
4 #ERROR-CLASS (N4) /* V1 error class
4 #ERROR-NR (N4) /* V1 error number
3 REDEFINE #ERROR-CODE
4 #ERROR-CODE-CLASS (N4) /* V1 alternative name
4 #ERROR-CODE-NR (N4) /* V1 alternative name
3 #ENVIRONMENT (A32) /* V1 translation purposes
3 #ADCOUNT (I4) /* V2 attempt deliv. count
3 #USER-DATA (B16) /* V2 user data field
3 REDEFINE #USER-DATA
4 #USER-DATA-C (A1/16)
3 #MSG-ID (B32) /* V2 not used by broker
3 REDEFINE #MSG-ID
4 #MSG-ID-C (A1/32)
3 #MSG-TYPE (A16) /* V2 not used by broker
3 #PTIME (A8) /* V2 not used by broker
3 #NEWPASSWORD (B32) /* V2 new passwd of caller
3 REDEFINE #NEWPASSWORD
4 #NEWPASSWORD-C (A1/32)
3 #ADAPTER-ERROR (A8) /* V2 not used by broker
3 #CLIENT-UID (A32) /* V2 userid for security
3 #CONV-STAT (I1) /* V2 conversation status
3 #STORE (I1) /* V2 flag for saving data
3 #STATUS (I1) /* V2 not used by broker
3 #UOWSTATUS (I1) /* V3 UOW's status
3 REDEFINE #UOWSTATUS
4 #UOWSTA (I1) /* V3 do'nt use/deprecated
3 #UOWTIME (A8) /* V3 UOW lifetime in sec.
3 REDEFINE #UOWTIME
4 #UOWTIM (A8) /* V3 don't use/deprecated
3 #UOWID (A16) /* V3 UOW ID
3 #USERSTATUS (A32) /* V3 user status
3 REDEFINE #USERSTATUS
4 #USRSTA (A32) /* V3 don't use/deprecated
3 #UOWSTATUSPERSIST (I1) /* V3 UOW st. persist flag
3 REDEFINE #UOWSTATUSPERSIST
4 #UOWSTP (I1) /* V3 don't use/deprecated
3 #UOWFILLER (A3) /* V3 alignment
3 REDEFINE #UOWFILLER
4 #FILL (A3) /* V3 don't use/deprecated
3 #LOCS (A40) /* V4 callers set locale
3 #DARCH (I1) /* V4 for future use
3 #FLOG (A1) /* V6 force logon
3 #ENCL (I1) /* V6 end-to-end encryptn.
3 #KERNELSECURITY (A1) /* V7 security indicator
3 #COMMITTIME (A17) /* V7 UOW commit time
3 #COMPRESSLEVEL (A1) /* V7 compression level
3 #RESERVED3 (B2) /* V7 alignment
3 #RESERVED4 (B4) /* V7 reserved for future
3 #UWSTATUSLIFE (A8) /* V8 UOWStLifeTime:adder
3 #TOPIC (A96) /* V8 topic name
3 #PUBLICATION-ID (A16) /* V8 publication ID
3 #RESERVED-V99-1 (A32) /* V9 reserved for future
3 #RESERVED-V73-1 (I4) /* V9 reserved for future
3 REDEFINE #RESERVED-V73-1
4 #EXTENSION-SEND-LENGTH (I4) /* V9 don't use/deprecated
3 #RESERVED-V73-2 (I4) /* V9 reserved for future
3 REDEFINE #RESERVED-V73-2
4 #EXTENSION-RECEIVE-LENGTH (I4) /* V9 don't use/deprecated
3 #RESERVED-V73-3 (I4) /* V9 reserved for future
3 REDEFINE #RESERVED-V73-3
4 #EXTENSION-RETURN-LENGTH (I4) /* V9 don't use/deprecated
3 #CLIENT-ID (I4) /* V9 unique client ID
3 #RESERVED-V73-4 (A32) /* V9 reserved for future
3 REDEFINE #RESERVED-V73-4
4 #SERVER-REPLICATION-GROUP (A32) /* V9 don't use/deprecated
3 #LOG-COMMAND (A1) /* V9 broker cmd logging
3 #CREDENTIALS-TYPE (A1) /* V9 credential type
3 #RESERVED-V73-5 (A32) /* V9 reserved for future
3 REDEFINE #RESERVED-V73-5
4 #VERIFIED-USERID (A32) /* V9 don't use/deprecated
3 #RESERVED5 (B2) /* V9 alignment
3 #VARLIST-OFFSET (I4) /* V10 variable list offset
3 #LONG-BROKER-ID-LENGTH (I4) /* V10 Len long broker id
3 #MESSAGE-ID (A64) /* V11 MSG ID SENT/RCVD MSG
3 #CORRELATION-ID (A64) /* V11 MSG ID SENT MSG
3 #USE-SPECIFIED-MESSAGE-ID (I1) /* V11 No new MSG ID 4 SEND
3 #USE-SPECIFIED-CORRELATION-ID (I1) /* V11 Send COR ID 2 Broker
3 #RESERVED6 (A2) /* V11 reserved for future
3 #RESERVED7 (I4) /* V11 reserved for future
END-DEFINE