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.
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
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
- Takes the JSON payload from the HTTP request.
- 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.
- Takes the result of the data transformation and sends it to the queue manager in the form of a
CodedCharSetIdfield 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. 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
properties are set for the target back-end application.
Receiving messages from IBM MQ
- Gets the message from the queue.
- Checks that the message is either a JMS
BytesMessageor a JMS
TextMessage. If the message is neither, an error is generated and returned to the caller.
- If a
TextMessageis received, then any text in the contained data structure is automatically converted into the CCSID that is configured on the service.
- If a
BytesMessageis 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
receiveConversionattribute is set to QMGR and the
receiveCCSIDattribute is set to the same value as the CCSID configured on the service. An example of this is shown in Figure 1.
- If a
- Passes the message payload to the IBM z/OS Connect server for data transformation from a byte array to JSON.
- Takes the result of the data transformation and returns it as the response of the HTTP request.