Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 12 Using the Interface to TIBCO Enterprise Message Service : Calling EMS

Calling EMS
Shareable Tools Available
Two shareable tools are provided to interface with the TIBCO EMS Client API. These tools are:
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:
Some EMS routines require that the name of a data set or data set member containing encoded data to be used in SSL based message exchanges to be passed as an argument. For example:
 
tibems_status tibemsSSLParams_AddTrustedCertFile(
tibemsSSLParams SSLParams,
const char* filename,
tibems_int encoding );
 
In such cases, add a DD name statement declaration to the JCL that invokes the TIBCO Object Service Broker Execution Environment for each such data set or data set member required by the application, such as the following:
 
//SSLSCERT DD DISP=SHR,DSN=TIBCO.SXJ.V5R0M0.Z16.CNTL(SSLSCERT)
//SSLCCERT DD DISP=SHR,DSN=TIBCO.SXJ.V5R0M0.Z16.CNTL(SSLCCERT)
//SSLCKEY  DD DISP=SHR,DSN=TIBCO.SXJ.V5R0M0.Z16.CNTL(SSLCKEY)
and pass a string such as the following:
 
DD:SSLSCERT
 
in which the 3 characters "DD:" are prepended to the DD name, as an argument to the EMS routines; in this case, as the filename argument to the routine tibemsSSLParams_AddTrustedCertFile.
Furthermore, EMS routines that accept such encoded data must have the encoding type explicitly stated, as automatic recognition of the encoding does not occur when using EMS under z/OS. This means that a value of 0 (zero, corresponding to the EMS C constant TIBEMS_SSL_ENCODING_AUTO) cannot be passed as the encoding argument above; one of the other numeric values corresponding to a certificate encoding must be used instead.
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:
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:
See Also
TIBCO Object Service Broker Shareable Tools for more information about the @MAP table and registering MAP areas.
Error Handling
Most EMS functions return a tibems_status code if EMS detects an error. The explanation of the each of the status codes can be found in an appendix of TIBCO Enterprise Message Service: C and COBOL Reference.
If an abnormal termination occurs during rules processing TIBCO Object Service Broker creates an IBM LE formatted dump to report the problem. The dump appears as a SYSOUT file for the Execution Environment job. The call to S6BCALL or S6BFUNCTION is terminated and the ROUTINEFAIL exception raised. A rules traceback is produced if the exception is not handled by the rules.
See Also
TIBCO Object Service Broker Programming in Rules for more information about rules processing and exceptions.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved