EntireX Broker ACI for Natural

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:


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 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 for client and server | publish and subscribe.

Note for UNIX and Windows

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

Broker ACI Control Block Layout

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

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 for client and server | publish and subscribe. 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 for client and server | publish and subscribe. 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-CLASS
SERVER-NAME
SERVICE
#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 for client and server | publish and subscribe. 1  
PASSWORD #PASSWORD (A32) Password. See Authentication. 1 4,5
TOKEN #TOKEN (A32) Reconnection token. See USER-ID and TOKEN for client and server | publish and subscribe. 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 for client and server | publish and subscribe. 1 3, 5
ERROR-CODE #ERROR-CODE (A8) Error code. See Error Handling for client and server | publish and subscribe and Error Messages and Codes. 1  
ENVIRONMENT #ENVIRONMENT (A32) Environment. See Using Internationalization for client and server | publish and subscribe. 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 codepages. See Using Internationalization for client and server | publish and subscribe. 4  
FORCE-LOGON #FLOG (A1) Override Broker AUTOLOGON. See Authentication. 6  
ENCRYPTION-LEVEL #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 for client and server | publish and subscribe. 7  
UWSTAT-LIFETIME #UWSTATUSLIFE (A8) Add value for persistent status lifetime. See UWSTAT-LIFETIME. 8  
TOPIC #TOPIC (A96) Topic name for publish and subscribe. See Key ACI Field Names. 8  
PUBLICATION-ID #PUBLICATION-ID (A16) Publication ID for publish and subscribe. 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 for client and server | publish and subscribe. 9  
LOG-COMMAND #LOG-COMMAND (A1) Log the current command. See also Programmatically Turning on Command Logging for client and server | publish and subscribe. 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  

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 Copycode

The ACI control block definition is located in file NATDEF of the supplied application (SYSETB). See ACI Examples and LDAs for where it is provided on your platform:

*    -------------------------------- - ---------- --------------------------------*
*    Product .....: EntireX Broker
*    Copyright ...: (c) Software AG      1997-2015 All rights reserved.
*    Version .....: ACI VERSION 10
*    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 .......
*    * * * * * * * * * * * * * * * *  *  Attention * * * * * * * * * * * * * !!!!!
*                                                                            .....
*    -------------------------------- - ---------- --------------------------------*
*    EntireX Broker API Function                   Constants ---------------------
   1 #FCT-SEND                        I          1
   1 #FCT-RECEIVE                     I          1
   1 #FCT-UNDO                        I          1
   1 #FCT-EOC                         I          1
   1 #FCT-REGISTER                    I          1
   1 #FCT-DEREGISTER                  I          1
   1 #FCT-VERSION                     I          1
   1 #FCT-LOGON                       I          1
   1 #FCT-LOGOFF                      I          1
   1 #FCT-SET                         I          1
   1 #FCT-GET                         I          1
   1 #FCT-SYNCPOINT                   I          1
   1 #FCT-KVER                        I          1
   1 #FCT-LOCT                        I          1
   1 #FCT-SSLP                        I          1
   1 #FCT-SEND-P                      I          1
   1 #FCT-RCVE-P                      I          1
   1 #FCT-SUBS-P                      I          1
   1 #FCT-USUB-P                      I          1
   1 #FCT-CNTL-P                      I          1
   1 #FCT-RPLY-E                      I          1
*
*    EntireX Broker API Option                     Constants ---------------------
   1 #OPT-MSG                         I          1
   1 #OPT-HOLD                        I          1
   1 #OPT-IMMED                       I          1
   1 #OPT-QUIESCE                     I          1
   1 #OPT-EOC                         I          1
   1 #OPT-CANCEL                      I          1
   1 #OPT-LAST                        I          1
   1 #OPT-NEXT                        I          1
   1 #OPT-PREVIEW                     I          1
   1 #OPT-COMMIT                      I          1
   1 #OPT-BACKOUT                     I          1
   1 #OPT-SYNC                        I          1
   1 #OPT-ATTACH                      I          1
   1 #OPT-DELETE                      I          1
   1 #OPT-EOCCANCEL                   I          1
   1 #OPT-QUERY                       I          1
   1 #OPT-SETSTATUS                   I          1
   1 #OPT-ANY                         I          1
   1 #OPT-TERMINATE                   I          1
   1 #OPT-DURABLE                     I          1
   1 #OPT-CHECKSVC                    I          1
*
*    EntireX Broker Conversation                   Status Constants --------------
   1 #CONVSTAT-NEW                    I          1
   1 #CONVSTAT-OLD                    I          1
   1 #CONVSTAT-NONE                   I          1
*
*    EntireX Broker Store                          Constants ---------------------
   1 #STORE-OFF                       I          1
   1 #STORE-BROKER                    I          1
   1 #STORE-ON                        I          1
*
*    EntireX Broker Status                         Constants ---------------------
   1 #STAT_OFF                        I          1
   1 #STAT_STORED                     I          1
   1 #STAT_DELIVERY-ATTEMP            I          1
   1 #STAT_DELIVERED                  I          1
   1 #STAT_PROCESSED                  I          1
   1 #STAT_DEAD                       I          1
*
*    EntireX Broker UOW Status                     Constants ---------------------
   1 #RECV-NONE                       I          1
   1 #RECEIVED                        I          1
   1 #ACCEPTED                        I          1
   1 #DELIVERED                       I          1
   1 #BACKEDOUT                       I          1
   1 #PROCESSED                       I          1
   1 #CANCELLED                       I          1
   1 #TIMEOUT                         I          1
   1 #DISCARDED                       I          1
   1 #RECV-FIRST                      I          1
   1 #RECV-MIDDLE                     I          1
   1 #RECV-LAST                       I          1
   1 #RECV-ONLY                       I          1
*
*    EntireX Broker Locale String                  Constants ---------------------
   1 #ETB-CODEPAGE-USE-DEFAULT        A          5
*
*    EntireX Broker Force Logon                    Constants ---------------------
   1 #FLOG-YES                        A          1
   1 #FLOG-NO                         A          1
   1 #FLOG-S                          A          1
*
*    EntireX Broker Encryption Level               Constants ---------------------
   1 #ENCLEVEL-NONE                   I          1
   1 #ENCLEVEL-TO-BROKER              I          1
   1 #ENCLEVEL-TO-TARGET              I          1
*
*    EntireX Broker KernelSecurity                 Constants ---------------------
   1 #KERNEL-SECURITY-NO              A          1
   1 #KERNEL-SECURITY-YES             A          1
   1 #KERNEL-SECURITY-USER            A          1
   1 #KERNEL-SECURITY-LIGHT           A          1
*
*    EntireX Broker Compression Level              Constants ---------------------
   1 #COMPRESS-LEVEL-0                A          1
   1 #COMPRESS-LEVEL-1                A          1
   1 #COMPRESS-LEVEL-2                A          1
   1 #COMPRESS-LEVEL-3                A          1
   1 #COMPRESS-LEVEL-4                A          1
   1 #COMPRESS-LEVEL-5                A          1
   1 #COMPRESS-LEVEL-6                A          1
   1 #COMPRESS-LEVEL-7                A          1
   1 #COMPRESS-LEVEL-8                A          1
   1 #COMPRESS-LEVEL-9                A          1
   1 #COMPRESS-LEVEL-NO               A          1
   1 #COMPRESS-LEVEL-YES              A          1
*
*    EntireX Broker Credential Type                Constants ---------------------
   1 #CREDENTIAL-TYPE-UID-PWD         I          1
*
*    EntireX Broker API Control Block              Definition --------------------
*
   1 #SDPA-CB                         B        110 (8)
R  1 #SDPA-CB                                      /* V1
   2 #ETBCB                           A          1 /* V1 to pass CB to stub
R  1 #SDPA-CB
   2 #ETBAPI                          A          1 /* V1 don't use/deprecated
R  1 #SDPA-CB
   2 #SDPA-API                                     /* V1 don't use/deprecated
   3 #TYPE                            I          1 /* V1 type of ETBCB
R  3 #TYPE
   4 #API-TYPE                        I          1 /* V1 alternative name
   3 #VERSION                         I          1 /* V1 version of ETBCB
R  3 #VERSION
   4 #API-VERSION                     I          1 /* V1 alternative name
   3 #FUNCTION                        I          1 /* V1 function
   3 #OPTION                          I          1 /* V1 option
   3 #RESERVED                        I          4 (4) /* V1 reserved
   3 #SEND-LEN                        I          4 /* V1 length of send data
R  3 #SEND-LEN
   4 #SEND-LENGTH                     I          4 /* V1 alternative name
   3 #RECEIVE-LEN                     I          4 /* V1 max. len. rec. data
R  3 #RECEIVE-LEN
   4 #RECEIVE-LENGTH                  I          4 /* V1 alternative name
   3 #RETURN-LEN                      I          4 /* V1 length of rec.data
R  3 #RETURN-LEN
   4 #RETURN-LENGTH                   I          4 /* V1 alternative name
   3 #ERRTEXT-LEN                     I          4 /* V1 max. len. error text
R  3 #ERRTEXT-LEN
   4 #ERRTEXT-LENGTH                  I          4 /* V1 alternative name
   3 #BROKER-ID                       A         32 /* V1 target broker ID
   3 #SERVER-CLASS                    A         32 /* V1 part of service name
   3 #SERVER-NAME                     A         32 /* V1 part of service name
   3 #SERVICE                         A         32 /* V1 part of service name
   3 #USER-ID                         A         32 /* V1 user ID of caller
   3 #PASSWORD                        B         32 /* V1 password of caller
R  3 #PASSWORD
   4 #PASSWORD-C                      A          1 (32)
   3 #TOKEN                           A         32 /* V1 special purposes
   3 #SECURITY-TOKEN                  B         32 /* V1 security purposes
R  3 #SECURITY-TOKEN
   4 #SECURITY-TOKEN-C                A          1 (32)
   3 #CONV-ID                         A         16 /* V1 conv./non-conv.
   3 #WAIT                            A          8 /* V1 blocked/non-blocked
   3 #ERROR-CODE                      A          8 /* V1 error class/number
R  3 #ERROR-CODE
   4 #ERROR-CLASS                     N          4 /* V1 error class
   4 #ERROR-NR                        N          4 /* V1 error number
R  3 #ERROR-CODE
   4 #ERROR-CODE-CLASS                N          4 /* V1 alternative name
   4 #ERROR-CODE-NR                   N          4 /* V1 alternative name
   3 #ENVIRONMENT                     A         32 /* V1 translation purposes
   3 #ADCOUNT                         I          4 /* V2 attempt deliv. count
   3 #USER-DATA                       B         16 /* V2 user data field
R  3 #USER-DATA
   4 #USER-DATA-C                     A          1 (16)
   3 #MSG-ID                          B         32 /* V2 not used by broker
R  3 #MSG-ID
   4 #MSG-ID-C                        A          1 (32)
   3 #MSG-TYPE                        A         16 /* V2 not used by broker
   3 #PTIME                           A          8 /* V2 not used by broker
   3 #NEWPASSWORD                     B         32 /* V2 new passwd of caller
R  3 #NEWPASSWORD
   4 #NEWPASSWORD-C                   A          1 (32)
   3 #ADAPTER-ERROR                   A          8 /* V2 not used by broker
   3 #CLIENT-UID                      A         32 /* V2 userid for security
   3 #CONV-STAT                       I          1 /* V2 conversation status
   3 #STORE                           I          1 /* V2 flag for saving data
   3 #STATUS                          I          1 /* V2 not used by broker
   3 #UOWSTATUS                       I          1 /* V3 UOW's status
R  3 #UOWSTATUS
   4 #UOWSTA                          I          1 /* V3 don't use/deprecated
   3 #UOWTIME                         A          8 /* V3 UOW lifetime in sec.
R  3 #UOWTIME
   4 #UOWTIM                          A          8 /* V3 don't use/deprecated
   3 #UOWID                           A         16 /* V3 UOW ID
   3 #USERSTATUS                      A         32 /* V3 user status
R  3 #USERSTATUS
   4 #USRSTA                          A         32 /* V3 don't use/deprecated
   3 #UOWSTATUSPERSIST                I          1 /* V3 UOW st. persist flag
R  3 #UOWSTATUSPERSIST
   4 #UOWSTP                          I          1 /* V3 don't use/deprecated
   3 #UOWFILLER                       A          3 /* V3 alignment
R  3 #UOWFILLER
   4 #FILL                            A          3 /* V3 don't use/deprecated
   3 #LOCS                            A         40 /* V4 callers set locale
   3 #DARCH                           I          1 /* V4 for future use
   3 #FLOG                            A          1 /* V6 force logon
   3 #ENCL                            I          1 /* V6 end-to-end encryptn.
   3 #KERNELSECURITY                  A          1 /* V7 security indicator
   3 #COMMITTIME                      A         17 /* V7 UOW commit time
   3 #COMPRESSLEVEL                   A          1 /* V7 compression level
   3 #RESERVED3                       B          2 /* V7 alignment
   3 #RESERVED4                       B          4 /* V7 reserved for future
   3 #UWSTATUSLIFE                    A          8 /* V8 UOWStLifeTime:adder
   3 #TOPIC                           A         96 /* V8 topic name
   3 #PUBLICATION-ID                  A         16 /* V8 publication ID
   3 #RESERVED-V99-1                  A         32 /* V9 reserved for future
   3 #RESERVED-V73-1                  I          4 /* V9 reserved for future
R  3 #RESERVED-V73-1
   4 #EXTENSION-SEND-LENGTH           I          4 /* V9 don't use/deprecated
   3 #RESERVED-V73-2                  I          4 /* V9 reserved for future
R  3 #RESERVED-V73-2
   4 #EXTENSION-RECEIVE-LENGTH        I          4 /* V9 don't use/deprecated
   3 #RESERVED-V73-3                  I          4 /* V9 reserved for future
R  3 #RESERVED-V73-3
   4 #EXTENSION-RETURN-LENGTH         I          4 /* V9 don't use/deprecated
   3 #CLIENT-ID                       I          4 /* V9 unique client ID
   3 #RESERVED-V73-4                  A         32 /* V9 reserved for future
R  3 #RESERVED-V73-4
   4 #SERVER-REPLICATION-GROUP        A         32 /* V9 don't use/deprecated
   3 #LOG-COMMAND                     A          1 /* V9 broker cmd logging
   3 #CREDENTIALS-TYPE                A          1 /* V9 credential type
   3 #RESERVED-V73-5                  A         32 /* V9 reserved for future
R  3 #RESERVED-V73-5
   4 #VERIFIED-USERID                 A         32 /* V9 don't use/deprecated
   3 #RESERVED5                       B          2 /* V9 alignment
   3 #VARLIST-OFFSET                  I          4 /*V10 variable list offset
   3 #LONG-BROKER-ID-LENGTH           I          4 /*V10 Len long broker id


ACI Examples and LDAs

When you begin to write your first EntireX Broker ACI program, you can use Example 11: Model to write Client/Server Programs API Version 1 or Example 12: Model to write Client/Server programs API Version 2 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.

For Natural you will find the files with the examples, copybooks, etc. at the following locations:

LDAs / Examples Category Location Notes
EntireX Broker ACI Control Block LDA LDA for customer use. See member NATDEF in the Broker Natural Tutorials libraries SYSETB. 1, 2
Control Block LDA for EntireX Broker Command and Info Services See members ETBCISL1, ETBCISL2, ETBCISL3, and ETBCISL4 in the Broker Natural Tutorial library SYSETB.
Example 1: Single Request without Reply Non-conversational Examples See EntireX Broker Tutorial. 1, 2
Example 2: Single Request with Reply
Example 3: Long Running Service - Non-blocked Client Conversational Examples
Example 4: Transfer Messages from Server to Client
Example 5: Transfer Messages from Client to Server
Example 6: Server with Multiple Parallel Conversations
Example 7: Send Messages with HOLD - Delayed Delivery Special Features
Example 8: Remove Service while Conversations Exist
Example 9: Server for Multiple Services
Example 10: ACI Test Tool: Single Broker Requests (Does not apply.) Getting Started
Example 11: Model to write Client/Server Programs API Version 1  
Example 12: Model to write Client/Server programs API Version 2  
Example 13: Demonstration of the Attach Manager Interface Attach Manager Interface
Example 14: Single Requests without Reply - A Polling Server Non-blocked Server
Example 15: Single Requests with Reply - A Polling Server

Notes:

  1. Natural is required for installation of the Broker Natural Tutorial.
  2. See Installing the EntireX Broker Tutorial under z/OS | UNIX | Windows.

Related Literature