Calling EMS

The following shareable tools are used to interface with the TIBCO EMS Client API:


S6BCALL	Used by a rule when the EMS function does not return a value.
S6BFUNCTION	Used by a rule when a value is returned.

The types of arguments and the return value are determined by the EMS C routine being invoked. Most calls return a tibems_status value. It is possible for S6BFUNCTION to return strings or integers that are not status codes for some EMS functions.

The following is an example of a call to S6BFUNCTION:

STATUS = S6BFUNCTION(’tibemnsMsgProducer_Send’,PRODUCER,MESSAGE);

See Also

TIBCO Object Service Broker Shareable Tools for details on the S6BCALL and S6BFUNCTION tools.

TIBCO Enterprise Message Service: C and COBOL Reference for the definition of the EMS API as implemented by S6BCALL and S6BFUNCTION

Argument Mapping

Mapping Data Types

C data types, as described in TIBCO Enterprise Message Service: C and COBOL Reference, are mapped to S6BCALL and S6BFUNCTION. Simple data types are passed as shown in the following table:


EMS C data type	S6BCALL type
tibems_byte;	Binary of length 1
tibems_short;	Binary of length 2
tibems_wchar;	Binary of length 2
tibems_int;	Binary of length 4
tibems_long;	Binary of length 8
tibems_float;	Float Point of length 4
tibems_double;	Floating Point of length 8
tibems_uint;	Binary of length 4

Handles to EMS Structures

Handles to EMS structures are passed and returned as binary values of length 4. Examples of handle types include tibemsConnection, tibemsSession, and tibemsTextMsg.

Handle Management

The TIBCO Object Service Broker system is designed to handle high transaction volumes. The system therefore tracks the usage of some resources to ensure that these are not exhausted needlessly. The resources tracked include EMS connection structures, message structures, and SSL parameter structures. Whenever one of these structures has been allocated through an invocation of an EMS API function through S6BCALL or S6BFUNCTION in an TIBCO Object Service Broker transaction, terminating the transaction will implicitly release the structure, as if the TIBCO Object Service Broker application had invoked the proper EMS API function to release the structure itself. Handles to such structures may thus be used within a transaction and its child transactions, but not passed back to be used in a parent transaction.

Text Strings

In general text strings are passed as a variable character strings. In the EMS C interfaces, text strings are null terminated.


	If a variable length syntax field contains a null character then the EMS interface considers that the string is terminated at that null character. Any data following will be ignored. This also holds true for UNICODE strings.

Some functions in the EMS API for C return text data using two arguments: a text area and a maximum length for the area. A rule can pass a field or a local variable for the text area. The functions are:

•

tibemsDestination_GetName

•

tibemsQueue_GetQueueName

Byte Oriented Data

Byte oriented data, which is typically unstructured and does not depend on an encoding, can be sent and returned through EMS using the tibemsBytes C type. S6BCALL or S6BFUNCTION arguments that refer to byte areas are defined as binary values of length 4.

Rules extract data from such areas through MAP tables. MAP areas are restricted only by job memory limits. When an EMS functions returns a tibemsBytes area then a rules program must register the area with the @MAP table before using it with a MAP table. After registering the area a rule uses the binary value for the area as a parameter for a MAP table. The parameter identifies the start of the area to be mapped by the table.

The following functions get or write tibemsBytes areas:

•

tibemsBytesMsg_GetBytes

•

tibemsBytesMsg_WriteBytes

•

tibemsMapMsg_GetBytes

•

tibemsObjectMsg_GetObjectBytes

•

tibemsStreamMsg_ReadBytes

•

tibemsStreamMsg_WriteBytes