Version 9.6
 —  EntireX Broker ACI Programming  —

Writing Applications: Publish and Subscribe

This document describes how to implement and program publish-and-subscribe applications - employing durable subscription techniques - with EntireX Broker. Publish-and-subscribe communication is used if data is to be published in order to make it available to one or more subscribers. This communication model is implemented as an independent subsystem in EntireX Broker, that is, it can be activated by setting attributes or left inactive.

For ease of use, we recommend you use the aids and techniques below in the order given.

This document covers the following topics:

See also Concepts of Persistent Messaging.


Overview of Communication Models

There are two communication models in EntireX Broker: publish and subscribe and client and server.

Top of page

Basic Concepts of Publish and Subscribe

Topic

A topic is a logical grouping of publications relating to one subject area, which is defined in the Broker Attributes. Topics reflect subject areas, for example current news, stock quotations, weather, online chat, sales systems. Data can be published to a topic only if there are current subscribers to this topic.

Note:
For EntireX Broker, the term "topic" is analogous to the term "service". Topic represents the grouping of related information flows for the publish-and-subscribe communication model, as service does for the client-and-server model.

Publication

A publication is a message or set of messages that are created atomically by one publisher and are available to all current subscribers to the topic. Messages for publication are queued to the topic on a first-in, first-out basis.

Each publication is assigned a unique PUBLICATION-ID by EntireX Broker when the publication is created. The PUBLICATION-ID is returned to the publisher on the first SEND_PUBLICATION command issued when creating a new publication. The PUBLICATION-ID is also returned to the subscriber on the first RECEIVE_PUBLICATION command used to receive each new publication. Publisher and subscriber must include the PUBLICATION-ID for all subsequent commands relating to the same publication.

Subscription

A subscription identifies a user's intention to receive publications for a specified topic. An active subscription requires the user to have issued a SUBSCRIBE command without issuing a subsequent UNSUBSCRIBE command. Only publications created after the time of subscription can be read by the subscriber. Conversely, publications created after the UNSUBSCRIBE command, or after the subscription has expired, cannot be received by the subscriber, even if the subscription is renewed at a later time. The time period of the subscription determines which publications can be delivered to the subscriber. See Durability of Subscriptions.

Publisher

A publisher is a user participating in publish and subscribe that creates publications for one or more topics. It is possible for a publisher to create publications only if there is currently at least one subscription to the topic. This prevents superfluous data from being assigned to the topic.

Subscriber

A subscriber is a user participating in publish and subscribe that can read publications from one or more topics.

Durability of Subscriptions

The behavior of a subscription when the subscriber logs off or broker shuts down is determined by an option specified in the original subscription command.

The time at which the SUBSCRIBE command is issued is significant to the user's subscription. Only publications created after this point in time can be read by the subscriber. Conversely, publications created after either the time at which the UNSUBSCRIBE command was issued or the subscription has expired cannot be received by the subscriber, even if the subscription is renewed at a later time. The time period of the subscription determines which publications are delivered.

It is possible for a publisher to create publications only if there is currently at least one subscription to the topic. This feature prevents superfluous data from being assigned to the topic.

Subscription Expiration

A topic is specified in the broker's attribute file with a characteristic of SUBSCRIPTION-EXPIRATION time. This is the time period for which the user's subscription remains in effect. After the time period has elapsed, the user's subscription is terminated and the subscription is removed by the broker.

Top of page

API-TYPE and API-VERSION

Both the API-TYPE and the API-VERSION fields must always be provided.

Value Bit Pattern Description
1 (x'01') The standard value for API-TYPE is 1 (x'01') and usable with all Broker stubs in all environments.

Note:
If any of the following conditions exist, you must install the Adabas CICS link module with the definition PARMTYP=ALL, using the ADAGSET macro.

  1. If you are using NET transport with CICSETB stub with send or receive buffers greater than 32 KB.

  2. If you are using NET transport with CICSETB stub and your application does not have a TWA.

Certain Broker functionality requires a minimum API-VERSION. Using publish and subscribe requires API-VERSION 8 or higher. For the highest available version of Broker, see API-VERSION. The send buffer and the receive buffer are passed as parameters to the EntireX Broker. Both buffers can occupy the same location.

See Broker ACI Control Block Layout for Assembler | C | COBOL | Natural | PL/I | RPG.

Both the API-TYPE and API-VERSION fields must be set correctly to ensure that Broker returns the correct value in ACI field ERROR-CODE. Otherwise, depending on your programming language and environment, a return code may not always be given.

See Call Format for Assembler | C | COBOL | Natural | PL/I | RPG.

Top of page

LOGON and LOGOFF

The LOGON broker function is required in order to use the publish-and-subscribe programming model in your application. We recommend that the application issue a LOGOFF function call for the following reasons:

Logon example for programming language Natural:

/* Logon to Broker/LOGON
MOVE #FCT-LOGON TO #ETBCB.#FUNCTION
/*
CALL 'BROKER' #ETBAPI #SEND-BUFF #RECV-BUFF #ERR-TXT

Logoff example for programming language Natural:

/* Logoff to Broker/LOGOFF
MOVE #FCT-LOGOFF TO #ETBCB.#FUNCTION
CALL 'BROKER' #ETBAPI #SEND-BUFF #RECV-BUFF #ERR-TXT

Top of page

USER-ID and TOKEN

Identifying the Caller

USER-ID identifies the caller and is required for all functions except VERSION. The USER-ID is combined with an internal ID or with the TOKEN field, if supplied, in order to guarantee uniqueness, for example where more than one application component is executing under a single USER-ID.

Brokers identify callers as follows:

Restarting after System Failure with Durable Subscription

Warning:
USER and TOKEN must be specified by all publisher and subscriber applications where publication and subscription data is held in the persistent store.

The Broker provides a reconnection feature, using the TOKEN field in the ACI. If the application supplies a token along with USER-ID, the processing is automatically transferred when a request with the same user ID and token is received, either from the same process or from a different process or thread.

Specification of USER and TOKEN is necessary for reconnection with the correct user context after Broker has been stopped and restarted. This specification is also necessary to enable effective use of publish and subscribe, including recovery from system failures.

Managing the Security Token

If you are using EntireX Security, the application must maintain the content of the SECURITY-TOKEN field and not change this field on subsequent calls.

Top of page

Control Block Fields and Verbs

Basic Functionality of Broker API

This section describes the basic functionality of the API. There are five distinct functions in the Broker ACI which are relevant to publish and subscribe:

The participants in publish-and-subscribe are identified by ACI fields USER-ID and TOKEN.

ACI Syntax

Function Fields in EntireX Broker Control Block
CONTROL_PUBLICATION
API = 8 
, BROKER-ID = BROKER-ID 
, USER-ID = user_id 
, TOKEN = token 
, OPTION = { BACKOUT | 
CANCEL | 
COMMIT | 
LAST | 
QUERY | 
SETUSTATUS } 
[, PUBLICATION-ID = pub_id ] 
[, USTATUS = user_status ]
RECEIVE_PUBLICATION
API = 8
, BROKER-ID = BROKER-ID
, USER-ID = user_id
, TOKEN = token
, WAIT = NO | YES | wait_value
, PUBLICATION-ID = pub_id | NEW | OLD | ANY
, TOPIC = topic_name
SEND_PUBLICATION
API = 8 
, BROKER-ID = BROKER-ID 
, USER-ID = user_id 
, TOKEN = token 
[, OPTION = COMMIT ] 
, PUBLICATION-ID = pub_id | NEW 
, TOPIC = topic_name 
[, USTATUS = user_status ]
SUBSCRIBE
API = 8 
, BROKER-ID = BROKER-ID 
, USER-ID = user_id 
, TOKEN = token 
, TOPIC = topic_name 
[, OPTION = DURABLE ]
UNSUBSCRIBE
API = 8 
, BROKER-ID = BROKER-ID 
, USER-ID = user_id 
, TOKEN = token 
, TOPIC = topic_name

Key ACI Field Names

The following table lists key ACI field names used to implement applications that use the publish-and-subscribe communication model. The other fields are available to identify partner programs, specify buffer lengths, convey error codes, etc.

See Broker ACI Fields for all fields.

ACI Field Name Description
FUNCTION Function code for one of the verbs (see table below).
OPTION Indication of specific broker behavior, depending on the function.
PUBLICATION-ID Identifier to obtain and specify the publication. Indicates a specific publication. The publication ID value is an internally generated identifier (containing alphanumeric characters) for the publication. We recommend that application programmers make no assumptions about the content, layout or meaning of any part of the PUBLICATION-ID field.
TOPIC Identifies the name of the publication's topic.
WAIT Value to specify blocking or non-blocking command.

Key Verbs for FUNCTION Field

The following table lists the most important verbs for the field FUNCTION.

See Broker ACI Functions for all functions.

Verb Description
CONTROL_PUBLICATION Publisher uses this to commit and subscriber uses this to acknowledge publications.
RECEIVE_PUBLICATION Retrieves publication from the broker.
SEND_PUBLICATION Sends publication to the broker.
SUBSCRIBE Informs the broker of the existence of a subscriber to a topic.
UNSUBSCRIBE Informs the broker that the subscriber wishes to unsubscribe.

Top of page

Implementation of Publisher and Subscriber Components

Single Message Publication

This example illustrates a publisher creating single-message publications that are retrieved by one or more subscriber applications. The publisher and subscriber operate asynchronously of each other. There is no reply from the subscriber in this communication model.

This example, which uses durable subscription, shows the typical structure of a subscriber application that has previously subscribed to a topic and is now retrieving the publications issued to that topic. Subscription occurs either during one-time processing provided by the subscriber application, or it is performed explicitly by an administrator. See Broker Command and Information Services.

The subscriber performs RECEIVE_PUBLICATION commands in a loop specifying WAIT=YES, which makes it possible to process publications as they occur. If none are received during the specified wait period, the server executes another iteration of the loop and repeats the wait until a publication is received.

The RECEIVE_PUBLICATION command specifies PUBLICATION-ID=NEW to receive all new publications arriving from the publisher. This example assumes single-message publications which do not require acknowledgment of receipt since AUTO-COMMIT-FOR-SUBSCRIBER=YES was specified in the topic-specific attributes for the topic NYSE in this case.

LOGON USER-ID=SB1,TOKEN=TKSB1
Repeat
    RECEIVE_PUBLICATION,PUBLICATION-ID=NEW,WAIT=YES,TOPIC=NYSE,USER-ID=SB1,TOKEN=TKSB1 
        If (Error-Class = 0 and Error-Number = 0)
        /* something received: process request*/

        End-if /* otherwise nothing received */
End-repeat
LOGOFF USER-ID=SB1,TOKEN=TKSB1

A publisher issues a SEND_PUBLICATION command to send publications containing a single message to a topic. The publisher's SEND_PUBLICATION commands are performed with WAIT=NO, and PUBLICATION-ID=NEW is assigned each time.

SEND_PUBLICATION,PUBLICATION-ID=NEW,WAIT=NO,OPTION=COMMIT,TOPIC=NYSE,USER-ID=PB1,TOKEN=TKPB1

Multiple Message Publication

This example, which uses durable subscription, shows a publisher creating multiple-message publications that are retrieved by one or more subscriber applications. The publisher and subscriber operate asynchronously of each other; there is no reply from the subscriber in this communication model. In this example, one or more publishers in a stock exchange system send current stock exchange quotations. The subscriber accesses the system at irregular intervals and receives all publications currently available.

This example illustrates the typical structure of a subscriber application that has previously subscribed to a topic and is now retrieving all available publications for a specified topic. Subscription has already occurred either during one-time processing within the subscriber application, or it is performed explicitly by an administrator. See Command-line Utilities.

The subscriber performs RECEIVE_PUBLICATION commands in the outer loop, specifying PUBLICATION-ID=NEW in order to receive the first available publication. The inner loop allows remaining messages within the same publication to be retrieved, after which CONTROL_PUBLICATION acknowledges receipt of the publication. The outer loop is then repeated to obtain the next available publication in conjunction with the inner loop until all available publications are processed.

The RECEIVE_PUBLICATION command specifies PUBLICATION-ID=NEW to receive all new publications. In this case, the subscriber explicitly acknowledges receipt of the publication, using the CONTROL_PUBLICATION function, since it is assumed AUTO-COMMIT-FOR-SUBSCRIBER was not specified in the topic-specific attributes for the topic NYSE in this case.

LOGON USER-ID=SB1,TK=TKSB1
While publications available
  RECEIVE_PUBLICATION PUBLICATION-ID=NEW,TOPIC=NYSE,WAIT=YES,USER-ID=SB1,TOKEN=TKSB1
  While data on publication
    RECEIVE_PUBLICATION PUBLICATION-ID=publication-id,TOPIC=NYSE,WAIT=NO,USER-ID=SB1,TOKEN=TKSB1
  End-while
  CONTROL_PUBLICATION OPTION=COMMIT,PUBLICATION-ID=publication-id,TOPIC=NYSE
End-while
LOGOFF USER-ID=SB1,TOKEN=TKSB1

A publisher issues a SEND_PUBLICATION command to send a publication containing multiple messages. The publisher's SEND_PUBLICATION command is performed with WAIT=NO and PUBLICATION-ID=NEW. Remaining messages belonging to this publication are sent to the broker by specifying the generated PUBLICATION-ID within each subsequent SEND_PUBLICATION command. These messages are committed by issuing the CONTROL_PUBLICATION command, which also specifies the generated PUBLICATION-ID.

LOGON USER-ID=PB1,TK=TKPB1                                              
SEND_PUBLICATION PUBLICATION-ID=NEW,TOP=NYSE,USER-ID=PB1,TOKEN=TKPB1
While data                                                          
  SEND_PUBLICATION PUBLICATION-ID=publication-id,USER-ID=PB1,TOKEN=TKPB1
End-while     
CONTROL_PUBLICATION OPTION=COMMIT,PUBLICATION-ID=publication-id,USER-ID=PB1,TOKEN=TKPB1
LOGOFF USER-ID=PB1,TOKEN=TKPB1

Top of page

Blocked and Non-blocked Broker Calls

In the publish-and-subscribe communication model, the term "blocked call" refers only to the broker RECEIVE_PUBLICATION command used by subscriber applications. The SEND_PUBLICATION command is always "non-blocking", such that WAIT=NO must be specified. A publisher application sends a publication via EntireX Broker for a specified topic without waiting for any subscribers to receive the publication.

A subscriber application component can use the control block field WAIT in the following ways to determine whether broker will automatically generate a WAIT in order for the command to be either received or satisfied by the partner application:

Non-blocked Command: WAIT=NO

RECEIVE_PUBLICATION allows a subscriber application to request a publication for a specified topic. If there are no publications currently available, an ACI response code is returned, indicating that no publications are currently available for the designated topic. See Error Messages and Codes. Similarly, a response code also indicates that there are no further messages to be received within the same publication, where PUBLICATION-ID=nnn has been specified to retrieve continuation segments of the same publication. This technique is used by subscriber applications only.

Example: Subscriber

The subscriber application component requests the next new publication, which is returned if available. If there is no publication available, the subscriber receives a return code immediately, indicating no publications are available at this time. There is no waiting, and the application performs this command periodically under control of the application logic, as shown here:

RECEIVE-PUBLICATION,PUBLICATION-ID=NEW,WAIT=NO,TOPIC=NYSE,USER-ID=SB1,TOKEN=TKSB1
... application code to process publication ....

Blocked Command: WAIT=YES or WAIT=n

Allows a subscriber application to solicit a publication to be returned for the specified topic. The calling application is automatically placed in a WAIT state until there is a publication available for the specified topic. If no publication is available during the specified waiting time, an ACI response code is returned to the application, indicating that no publications are currently available for the designated topic. See Error Messages and Codes. Similarly, a response code also indicates that there are no further messages to be received within the same publication if PUBLICATION-ID=nnn has been specified in order to retrieve continuation segments of the same publication. This technique is used by subscriber applications only.

Example: Subscriber

The subscriber application component requests the next new publication, which is returned if available. If there is no publication available, the subscriber enters a WAIT state for the specified (or default) time period, during which it is eligible to receive any new publications that arrive in this time. At the end of the specified (or default) time period, the subscriber receives a return code if no publications were available. The following example shows this process being repeated indefinitely within a loop:

Repeat
    RECEIVE-PUBLICATION,PUBLICATION-ID=NEW,WAIT=YES,TOPIC=NYSE,USER-ID=SB1,TOKEN=TKSB1
    ... application code to process publication ....
End-repeat

Top of page

Timeout Parameters

Timeout Behavior

EntireX Broker provides a number of timeout mechanisms that allow you to control wait times flexibly, optimize resource usage, and configure efficient communication.

Types of Non-activity Time

There is interplay between the non-activity times specified in the attribute file for the attributes

where an application component performs more than one of these roles. In this case the maximum non-activity time associated with the user will take precedence. This fact must be considered where an application component implements both publish and subscribe and client and server.

Recommendations

The following recommendations apply to developing publish-and-subscribe applications:

Top of page

Configuration Prerequisites for Durable Subscriptions

A subscription can be durable or non-durable. See Durability of Subscriptions. Durable subscriptions require additional configuration steps. Since subscriber information for durable subscriptions must also be present after a broker is restarted, a persistent store is required (PSTORE). See also Concepts of Persistent Messaging. This allows Adabas (all platforms), file system (UNIX and Windows) and DIV (z/OS) to be utilized for storing both publication information and, optionally, subscription information.

If you use the persistent store for subscriber information under Adabas, see Configuring and Operating the Adabas Persistent Store under z/OS | UNIX | Windows | z/VSE. If you are using persitent store type DIV or the local file system, no additional PSTORE configuration is required. See also Broker-specific Attributes under Broker Attributes for other related parameters.

NUM-TOPIC-TOTAL        = 4
NUM-SUBSCRIBER-TOTAL   = 8
SUBSCRIBER-STORE       =PSTORE

Note:
The topic attribute definitions must specify ALLOW DURABLE=YES. Otherwise durable subscription requests are rejected.

Top of page

Data Compression

Data compression within EntireX Broker allows you to exchange smaller packet sizes between senders and receivers. This helps to reduce response time during transmissions as well as improve the overall network throughput, especially with low bandwidth connections.

Compression is performed only on the buffers used to send and receive data. The application has the option of setting the level of compression/decompression for data transmission. The compression level can be set to achieve either no compression or a range of compression/decompression. See Data Compression in EntireX Broker. Application components can set compression individually to Broker.

zlib is a general-purpose software implementing data compression across a variety of platforms. The functions used within EntireX Broker represent a subset of those available within the zlib software. The compression algorithms are implemented through the open source software zlib. It may occur that the data buffer does not compress during a data transmission; if it does not compress, a logged warning message will appear in 00200450 and in the stub.

Technique

The Broker ACI control block contains a field that is used to set the compression level. This field determines for any send/receive transmission whether the data buffer will be compressed/decompressed. See ACI control block field COMPRESSLEVEL.

Top of page

Error Handling

After every broker operation, the application must check the ERROR-CODE. It consists of a combination of

While the error number describes the exact situation, the error class often determines how the program will proceed after returning from the EntireX Broker operation. From the programmer's point of view, therefore, the error class may be more important than the particular error number.

For more information, see Error Messages and Codes.

Programming Techniques

We recommend trapping the error classes in a "case" statement, for example, a DECIDE in Natural or a switch statement in C.

All error classes - for example user and configuration errors - leading to the same action (that is, reporting or logging the situation and aborting issuing broker calls), can be handled together in the NONE VALUE or default case.

Example for C Progamming Language

int   i, iErrorCode, iErrorClass, iErrorNumber, ret_val;
char  szErrorTextBuffer[S_TXT + 1];.....

/* prepare error code field and error text buffer */
memset(pETBCB->error_code,'0',sizeof(pETBCB->error_code));
memset(szErrorTextBuffer,'\0',sizeof(szErrorTextBuffer));

/* call the broker */
ret_val = broker(pETBCB,pSendBuffer,pReceiveBuffer,szErrorTextBuffer);

/* evaluate error class from error code field */
iErrorClass = 0;
for(i = 0; i < 4; ++i)
{  
    iErrorClass *= 10;
    iErrorClass += pETBCB->error_code[ i ] - '0';
}

if (iErrorClass == 0 && ret_val != 0)
{
    printf("Wrong API_TYPE and/or API_VERSION\n");
}
else
{
    /* evaluate error number from error code field */
    iErrorNumber = 0;
    for(i = 4; i < 8; ++i)
    {  
        iErrorNumber *= 10;
        iErrorNumber += pETBCB->error_code[ i ] - '0';
    }

    /* evaluate error code as integer value */
    iErrorCode = (iErrorClass * 10000) + iErrorNumber;

    /* handle error */
    switch (iErrorClass)
    {
        case 0: /* Successful Response */
            ....
            break;

        case 2: /* User does not exist */
            ....
            break;

        case 3: /* Conversation ended */
            ....
            break;

        case 7: /* Service not registered */   
            ....
            break;

        case 74: /* Wait Timeout occurred */
            ....        
            break;

        ....

        default:
            printf("EntireX Broker Error occurred.\n");
            printf("%8.8u %s",iErrorCode,szErrorTextBuffer);
            break;     
    }
}

Top of page

Using Internationalization

It is assumed that you have read the document Internationalization with EntireX and are familiar with the various internationalization approaches described there.

This section covers the following topics:

General Information

The broker stub does not convert your application data before it is sent to the broker. The application's data is shipped as given.

For the internationalization approaches ICU conversion and SAGTRPC user exit, valid locale strings are required for conversion to behave correctly.

Providing Locale Strings

Under the Windows operating system:

Under all other operating systems:

With the ACI control block field LOCALE-STRING:

The encoding in which your application gives the data to the broker stub and the locale string

otherwise, unpredictable results will occur.

Example for Assembler

MVC   S$LOCALE,=C'ECS037'                 MOVE CP
....

Examples for C

  1. Using a specific codepage

    /* prepare the locale-string with a codepage */
    memset (pETBCB->locale_string,' ',sizeof(pETBCB->locale_string));
    strncpy(pETBCB->locale_string,"ECS0819",sizeof(pETBCB->locale_string));
    ....
  2. Using the platform's default codepage (Windows only)

    /* prepare the locale-string with a codepage */
    memset (pETBCB->locale_string,' ',sizeof(pETBCB->locale_string));
    strncpy(pETBCB->locale_string,
    ETB_CODEPAGE_USE_PLATFORM_DEFAULT,sizeof(pETBCB->locale_string));
    ....

Example for COBOL

MOVE 'ECS037' TO LOCALE-STRING.
....

Examples for Natural

MOVE 'ECS037' TO #SDPA-API.#LOCALE_STRING.
....

Using the ENVIRONMENT Field with the Translation User Exit

Using the internationalization approach translation user exit, an ACI programmer can provide additional information to their translation exit through the ENVIRONMENT field, allowing flexible translation behavior in accordance with application requirements. The field cannot be used for any other internationalization approaches and must be empty if a method other than translation user exit is used. See Translation User Exit.

Example

Assume a broker service or topic has a user-written translation routine called ABCTRAN, which is capable of performing several types of data conversion, for example EBCDIC-ASCII translation, byte swapping, and mixed data types. The user translation routine may need to know the data formats used by both partners. The ENVIRONMENT field can be used to pass this information from the application to the translation routine in Broker kernel.

Technique

MOVE 'MYCODEPAGE' TO #ETBCB.#ENVIRONMENT
...
CALL 'BROKER' #ETBAPI #SEND-BUFF #RECV-BUFF #ERR-TXT

Top of page

Using Send and Receive Buffers

Introduction

The send buffer and the receive buffer are passed as parameters to the EntireX Broker. Both buffers can occupy the same location. See Call Format for Assembler | C | COBOL | Natural | PL/I | RPG.

The length of the data to be sent is given in the ACI field SEND-LENGTH. If the SEND-LENGTH is greater than the send buffer during data transmission, you could accidentally send the data that is physically located in memory behind your send buffer to the designated Broker.

The RECEIVE-LENGTH is required with the RECEIVE and RECEIVE_PUBLICATION functions and with SEND functions waiting for a reply. The length of the receive buffer is specified in the ACI field RECEIVE-LENGTH. If the RECEIVE-LENGTH is greater than the receive buffer during data reception, you can overwrite the data physically located behind the receive buffer being used.

If the data to be returned is less than RECEIVE-LENGTH, the rest of the receive buffer remains unchanged and is not padded with trailing blanks or other characters. The ACI field RETURN-LENGTH contains the length of the data actually returned. The RECEIVE-LENGTH field is not changed upon return.

Note:
With Adabas version 8, the maximum size of message data is no longer limited to approximately 32 KB. If Adabas version 8 is not used, these same limits still apply under z/OS.

Error Cases

Conversion and translation of data can increase the amount of data and thus require a buffer of a larger size than provided. It may also be impossible to determine the size required in advance. EntireX provides a feature to reread the data in such cases:

Using API version 2 and above, if the amount of data to be returned is greater than the RECEIVE-LENGTH, the exact length needed is given in the ACI field RETURN-LENGTH together with an error code, depending on the internationalization approach. See Internationalization with EntireX. Note the following:

For translation and translation user exit:

for ICU conversion and SAGTRPC user exit:

To obtain the entire message, increase the size of the receive buffer and issue an additional Broker ACI function RECEIVE or RECEIVE_PUBLICATION with the option "LAST".

Using API version 5 and above, it is also possible for a client to reread a truncated message in non-conversational mode, by issuing an additional Broker ACI function RECEIVE or RECEIVE_PUBLICATION with the option "LAST" as well as the CONV-ID returned from the ACI control block. No EOC is needed after RECEIVE.

Transport Methods

The maximum length possible for send and receive buffers is affected by the transport method used.

Transport Method Maximum Receive / Send Buffer Size If using this transport method, ...
TCP/IP 2,147,482,111 B
  • the maximum send and receive buffer size is approximately 2,147,482,111 bytes.

Entire Net-Work 30,545 B
  • the send and receive buffer sizes are affected by the setting of the Net-Work parameter IUBL for all involved platforms (see the Net-Work documentation for more information);

  • the send and receive buffer sizes are affected by the Adabas SVC/Entire Net-Work-specific attribute IUBL for Broker running under z/OS;

  • the maximum send and receive buffer size is around 30,545 bytes.

    Note:
    Under z/OS with Adabas version 8, the value for NET is the same as for TCP and SSL.

SSL 2,147,482,111 B
  • the maximum send and receive buffer size is approximately 2,147,482,111 bytes.

Top of page

Tracing

Trace information showing the commands help the application programmer debug applications and solve problems. Tracing can be obtained for the application (stub trace) and for the Broker kernel (kernel trace). The stub trace shows the Broker functions issued by your application, whereas the Broker kernel trace will contain all Broker functions issued by all applications using the Broker.

Setting the Broker attribute TRACE-LEVEL=1 provides traces containing just the Broker functions processed by the Broker kernel without additional diagnostics. It is only necessary to set the trace value higher when generating traces for Software AG support.

Stub Trace

Tracing is available for all stubs on UNIX and Windows. For the stubs for which tracing is available on z/OS, see table under Administering Broker Stubs.

To set the stub trace, see Tracing for Broker Stubs under z/OS | UNIX | Windows | z/VSE.

Kernel Trace

Tracing is available for Broker on all platforms. For z/OS, see Administering Broker Stubs.

To set the kernel trace, see Tracing webMethods EntireX under UNIX | Windows | BS2000/OSD | z/VSE.

Top of page

Transport Methods

Overview of Supported Transports

This table gives an overview of the transport methods supported by EntireX Broker stubs.

Operating System Environment Module Transport to Broker
TCP SSL NET (1) HTTP(S) (6)
z/OS (2) Batch, TSO, IMS (BMP) BROKER x x x  
Com-plete COMETB x (3) x  
CICS CICSETB x (3) x  
IMS (MPP) MPPETB x x x  
IDMS/DC (4) IDMSETB x (3)    
Natural NATETB23 x x x  
UNIX System Services Java ACI x x   x
UNIX broker.so x x    
Java ACI x x   x
Windows broker.dll (5) x x    
Java ACI x x   x
BS2000/OSD Batch, Dialog (formerly TIAM) BROKER x x x  
z/VSE Batch BKIMB x   x  
CICS BKIMC x   x  
z/VM BKIMBCMS x   x  
IBM i EXA x      
OpenVMS BROKER x x    

Notes:

  1. NET is available for transport to a broker running under mainframe platforms only; not to a broker running under UNIX or Windows.
  2. Under z/OS you can use IBM's Application Transparent Transport Layer Security (AT-TLS) as an alternative to direct SSL support inside the broker stub. Refer to the IBM documentation for more information.
  3. Use AT-TLS. See Note 2.
  4. Tracing and transport timeout are not supported in this environment.
  5. Stub broker32.dll is supported for reasons of backward compatibility. The functionality is identical to broker.dll.
  6. Via Broker HTTP(S) Agent; see Settting up and Administering the Broker HTTP(S) Agent under UNIX | Windows.

See also:

TCP/IP

TCP is not available for all Broker stubs and all environments (see table above).

See Using TCP/IP as Transport Method for the Broker Stub in Transport Methods for Broker Stubs under z/OS | UNIX | Windows | BS2000/OSD | z/VSE | z/VM, which describes how to set up TCP transport.

Application programs using TCP/IP as the transport specify the target Broker ID in terms of a host name (or IP address) together with the port number on which the Broker TCP/IP communications driver is listening. Example: An application communicating through TCP/IP would specify on each command the Broker ID

IBM1:3932:TCP

where the host on which the Broker kernel executes is known to TCP as IBM1 and is listening on port 3932.

Entire Net-Work

Communication through Entire Net-Work is available for all Broker stubs when communicating with a Broker kernel on z/OS through Entire Net-Work. Applications can also utilize Entire Net-Work communication to obtain local interprocess communication with a z/OS Broker kernel running on the same machine as the application. This can provide a considerable performance benefit. Local interprocess communication is achieved through the Adabas SVC mechanism.

Application programs using Entire Net-Work as the transport specify the target Broker ID in terms of the target Entire Net-Work ID of the Broker kernel. For example, an application communicating through Entire Net-Work would specify on each command the Broker ID:

ETB001::NET

This can be abbreviated to the following for the Assembler stubs executing on z/OS (BROKER, CICSETB, COMETB, MPPETB):

ETB001

where the Entire Net-Work ID of the Broker kernel is 001.

SSL and TLS

Application programs using Secure Sockets Layer (SSL) or Transport Layer Security (TLS) as the transport must specify the SSL settings to the broker stub before any communication with the Broker can take place. There are various methods of setting SSL or TLS transport. See SETSSLPARMS and Running Broker with SSL or TLS Transport under z/OS | UNIX | Windows.

Example: An application communicating through SSL or TLS would specify on each command the Broker ID:

MYPC:1958:SSL

where the host on which the Broker kernel executes is known to SSL or TLS as MYPC and is listening on port 1958.

Transport Examples

See table above for how SSL or TLS is supported depending on broker stub and platform.

For information on Secure Sockets Layer, see SSL or TLS and Certificates with EntireX.

Considerations for Writing Applications

Restrictions with API Versions 1 and 2

The following maximum message sizes apply to all transport methods:

Top of page

Variable-length Error Text

In previous ACI versions, Broker kernel always returned 40 bytes of error text, space-padded if necessary. For ACI version 9 and above, variable length error text can now be returned if requested. With ACI 9 and above, error text up to the requested length is returned via a new section in the ACI reply. For any previous ACI versions, ETXL is not sent, and the error text is returned by the traditional method.

Note that the error text will continue to be traced in the stub and kernel trace and kernel command log.

See Broker ACI Fields.

Top of page

Programmatically Turning on Command Logging

You can trigger command logging for EntireX components that communicate with Broker by setting the field LOG-COMMAND in the ACI control block.

All functions with LOG-COMMAND programmatically set in the ACI string field will have their commands logged, regardless of any filter settings. Because the LOG-COMMAND option will override any command-log filter settings, remember to reset the LOG-COMMAND field if subsequent requests do not need to be logged.

Top of page