Considerations for services using the API or build toolkits

This topic describes data transformation considerations for IBM® MQ service provider services created with either the API toolkit or the build toolkit.

Data structure size

If you used the API Toolkit to generate the service, or the build toolkit to generate a service project originally from the API toolkit, the maximum COBOL or PL/I data structure size is 100 MB.

If you used the build toolkit and a manually created properties file to generate the service, the maximum COBOL or PL/I data structure size is 32 KB.

CCSID

To use data transformations, a coded character set ID (CCSID) must be configured on the service.

For services generated by the API Toolkit the CCSID is set in the configuration page of the service. For services generated by the build toolkit, the CCSID value is set by using the ccsid property. For more information, see Creating an IBM MQ service by using a properties file.

In most cases the value of CCSID should be 37. The following sections describe when the CCSID value is used.

Sending messages to IBM MQ

When an IBM MQ service provider service is configured with a data transformation, and sends a message to a queue manager (such as a one-way service for sending messages, or sending a request from a two-way service), the IBM MQ service provider performs the following steps:
  1. Takes the JSON payload from the HTTP request.
  2. Passes the payload to the IBM z/OS® Connect server for data transformation from JSON to a byte array. Text from the JSON payload is converted into text in the target data structure in the CCSID specified on the service.
  3. Takes the result of the data transformation and sends it to the queue manager in the form of a JMS BytesMessage. The CodedCharSetId field in the message’s MQMD is set to the CCSID that is configured on the service.

By default, the message that is sent has the MQMD Format field set to MQSTR, indicating that the message is a string message. Optionally, you can set the MQMD Format field to an alternative value using the API Toolkit configuration page. To use the MQMD Format MQFMT_NONE, the API toolkit needs to use the MQNONE value, which will get translated in the server to MQFMT_NONE. For more information, see Configuring service properties.

For services that are generated by the build toolkit you can set the value in the mqmdFormat property. For more information, see Creating an IBM MQ service by using a properties file.

When the back-end IBM MQ application receives the message from the IBM MQ destination, it might use the contents of both the MQMD Format and CodedCharSetId field for data transformation or other purposes. Therefore, you must ensure that the ccsid and mqmdFormat properties are set for the target back-end application.

Receiving messages from IBM MQ

When an IBM MQ service provider service is configured with a data transformation, and is going to receive a message from a queue manager (such as a one-way service for getting messages, or receiving a reply for a two-way service), the IBM MQ service provider performs the following steps:
  1. Gets the message from the queue.
  2. Checks that the message is either a JMS BytesMessage or a JMS TextMessage. If the message is neither, an error is generated and returned to the caller.
    • If a TextMessage is received, then any text in the contained data structure is automatically converted into the CCSID that is configured on the service.
    • If a BytesMessage is received it is assumed that any text in the data structure is in the same CCSID as is configured on the service.
      If it is not the same CCSID, data transformation will not generate the correct data. In this case, it is possible to configure IBM MQ to do data transformation by setting the JMS destination in the server.xml so that the receiveConversion attribute is set to QMGR and the receiveCCSID attribute is set to the same value as the CCSID configured on the service. An example of this is shown in Figure 1.
      Figure 1. Sample configuration using IBM MQ data transformation
      <jmsQueue jndiName="jms/sampleQ2Receive">
  <properties.wmqJms 
    baseQueueName="SampleQ2Receive"
    receiveCCSID="37"
    receiveConversion="QMGR"/>
</jmsQueue>
  3. Passes the message payload to the IBM z/OS Connect server for data transformation from a byte array to JSON.
  4. Takes the result of the data transformation and returns it as the response of the HTTP request.