MQ/204 data conversion and handling

Data conversion

Specify message data format attributes using one of the following WebSphere MQ fields:

WebSphere MQ field	Indicates...
MQMD.Encoding	Storage formats used for: Binary integers Packed decimal integers Floating point numbers
MQMD.CodedCharSetId	Character set used for string data

Data conversion formats

WebSphere MQ supports message data conversion through conversion exits that are invoked during MQGET processing. A conversion exit is invoked if the MQGMO_CONVERT option is specified on the MQGET call, and if the MQMD.Encoding field or the MQMD.CodedCharSetId field of the received message has a different value than was specified in the MQMD passed to MQGET. The name of the conversion exit to invoke is specified in the MQMD.Format field.

WebSphere MQ and MQ/204 can handle data conversion in the following ways.

Pass the data from the sender to the receiver

In this method, nothing is done to the data; it is simply passed from one application to the other. Data conversion is handled by the sending or receiving applications. The default value for WebSphere MQ MQMD.Format field is MQFMT_NONE (blanks), which tells WebSphere MQ not to convert data, even if there is a discrepancy in the character set or number encoding used.

Convert EBCDIC to ASCII

WebSphere MQ has built-in conversion for messages composed entirely of character string data. To send a message between z/OS and any ASCII machine and have character data automatically converted between EBCDIC and ASCII, specify the MQFMT_STRING constant in the WebSphere MQ MQMD.Format field of an MQPUT or MQPUT1 statement. This corresponds to specifying FORMAT='MQSTR' on a SOUL MQPUT or MQPUT1 statement. (MQFMT_STRING is a WebSphere MQ constant that equates to `MQSTR'.)

Convert data by calling a conversion exit

If you want to convert messages that combine character string and numeric data in a single message, you must provide a data conversion exit for any receiving machine that uses a different character set or number encoding. To call the conversion exit, set the FORMAT option in the MQPUT or MQPUT1 statement:

FORMAT=conversion_exit_name

For all MQ/204 MQGET and MQPUT calls:

Value for	Which provides...	Is specified in...
MQENC_NATIVE	Native number encoding	MQMD.Encoding field
MQCCSI_Q_MGR	Queue manager's coded character set identifier	MQMD.CodedCharSetId

On all MQGET calls, the MQGMO_CONVERT option is specified by default. This means that data conversion is controlled entirely through the FORMAT keyword of the MQPUT and MQPUT1 statements. An application program placing a message on the queue must specify:

Message format.
Name of the conversion exit required by the receiver of the message.
If suppression of conversion is desired. If so, the NO_CONVERT option must be specified on the MQGET statement. See Removing messages that do not convert for details.

Data handling

Buffers for message data areas

Buffers are automatically allocated, initially at UBUFSZ value, and then enlarged as needed. The size of a user's buffer can be reset by issuing a MODIFY BUFFER statement.

MQGET, MQPUT, and MQPUT1 statements need a buffer to hold the data area of the message:

If message data is specified as...	Then the buffer must be at least the size of...
%Variable or string constant	Variable or string constant
Image	Largest fixed (known at compile time) layout of the image: Fixed layout of an image contains no dependences or unknown items. If no layout of the image has a fixed size, then the buffer must be at least the size of the parameter UBUFSZ.

Enlarging the buffer

When the existing buffer is not large enough to hold the data area for MQPUT or MQPUT1 statements, MQ/204 makes it larger while preserving the existing buffer content. Once enlarged, the buffer remains the enlarged size until:

MODIFY BUFFER statement with SIZE option is executed.
MQPUT or MQPUT1 needs an even larger buffer.
MQGET with BUFLEN indicates a larger buffer.

Controlling message context information

WebSphere MQ collects two kinds of message context information, each a set of fields in the message description. See MQPUT statement for a greater understanding of the Descriptor field.

Identity context identifies the following:

Descriptor field

Stores...

UserIdentifier

User who originally put the message on a queue

AccountingToken

Accounting token associated with the application and/or user that originally put the message on a queue

ApplIdentityData

Information that is defined by the application suite to provide additional information about the message or its originator.

The queue manager treats this information as character data, but does not define the format of it. If the application does not define the value, the queue manager generates this information as a blank.

Origin context identifies the following:

Descriptor field	Stores...
PutApplType	Type of application that put the message on the queue.
PutApplName	Name of the application that put the message on the queue.
PutDate	Date the message was put on the queue.
PutTime	Time the message was put on the queue.
ApplOrginData	Information that is defined by the application when it puts the message. For example, ApplOrginData could be set by suitably authorized applications to indicate whether the identity data is trusted. The queue manager treats this information as character data, but does not define the format of it. If the application does not specify a value, the queue manager generates this information as a blank.

For a discussion of message context, see the WebSphere MQ Application Programming Guide. See also the discussion of the following MQOPEN options in the WebSphere MQ Application Programming Reference:

MQOO_PASS_ALL_CONTEXT MQOO_PASS_IDENTITY_CONTEXT MQOO_SAVE_ALL_CONTEXT MQOO_SET_ALL_CONTEXT MQOO_SET_IDENTITY_CONTEXT

Inheriting and passing context information

You can use the DEFINE QUEUE command and the MODIFY QUEUE, MQPUT, MQPUT1, and OPEN QUEUE statements in application programs to manage message context information.

To pass context information, specify a queue that is open for input and has the SAVE_ALL_CONTEXT option.

The MQPUT, MQPUT1, and OPEN QUEUE statements have several options that you can set to pass context information. The context queue can either be specified on the statement that is passing context or be inherited. The inheritance rules for passing context are as follows:

MQPUT1 and OPEN QUEUE statements inherit from DEFINE QUEUE command.
MQPUT statement inherits from OPEN QUEUE statement.

If a context queue is not specified or inherited, then a statement attempting to pass context fails with a nonzero $STATUS value.

Dealing with messages larger than one image

An image is the SOUL equivalent of a data structure. When using a single image for message data, you must have an image that can contain the largest possible message you expect to retrieve or place. That is, space for the largest possible message must be available in the user's server, because images are stored in either the full-screen buffer table, FSCB, or the global table, GTBL.

Image lists help manage the space required by using multiple images to hold a single message, so that you require a smaller Model 204 server.

Image lists

You can specify an image on MQGET, MQPUT, and MQPUT1 statements as a source or target for the data area of a message. You can also specify the source or target as a comma-separated list of up to ten images. For example:

MQGET image1, image2, image3 FROM queue_options MQPUT image1, image2 ON queue_options MQPUT1 image1, image2 ON queue_options

The images on the list are swapped in and processed serially. This provides server relief if the images are not global, because FSCB can be sized at the size of the largest image in the list instead of the largest message. The size of the MQ/204 message buffer is based on the sum of the lengths of all the images in the list.

On Get operations, the READLEN of each image is set. If the data runs out before filling all the images, the READLEN is set to zero for any images without data.

Alternatives to image lists

The MODIFY MQ_BUFFER, READ IMAGE, and WRITE IMAGE statements with the POSITION option provide alternatives for dealing with the server size issue; they can be used instead of image lists.

You can decide if you want to move messages out of the buffer programmatically, or have the MQ/204 statements handle messages in the buffer, so that the program never accesses the buffer. Directly manipulating the MQ_BUFFER area is programmatically more complex, but provides a finer level of access to message. For most applications, direct manipulation of the MQ_BUFFER area is not necessary.

WebSphere MQ transactions

Use MQCMIT and MQBACK statements to commit and back out WebSphere MQ transactions, called SYNCPOINT updates, to queues that belong to specific queue managers.

WebSphere MQ transactions are completely independent from Model 204 file update transactions. In addition, WebSphere MQ transactions against different queue managers are completely independent of one another.

Request cancellation and user restarts

If a cancellation or restart occurs, then all queues are closed, and any incomplete WebSphere MQ transactions are backed out.

End-of-request processing

The following table describes how end-of-request processing is handled:

If the request is...	Then...
Not part of a subsystem, or is part of an APSY AUTOCOMMIT=YES subsystem	All open queues are closed, and any uncommitted WebSphere MQ transactions against all queue managers that you are accessing are committed.
Part of an APSY AUTOCOMMIT=NO subsystem	WebSphere MQ transaction status is unchanged by end-of-request processing.

Leaving subsystems

When you leave a subsystem, end-of-request processing is done first. If WebSphere MQ transactions are active, which can happen if APSY AUTOCOMMIT=NO, those WebSphere MQ transactions are then committed. Then all MQ/204 subtasks are released.

A transfer to another subsystem is processed as a subsystem exit followed by a subsystem entry. Therefore, a transfer to another subsystem commits all active WebSphere MQ transactions and releases all MQ/204 substages. The first MQ/204 MQGET or MQPUT command in the new subsystem initiates a new WebSphere MQ transaction.

Controlling MQ subtask release

You can use the MQSUBREL parameter to control whether the MQ subtask is released at the end of request processing in subsystems with AUTOCOMMIT=N.

You can set the MQSUBREL parameter on User 0's CCAIN line to affect all users. Or, you can reset it for an individual user to affect only that specific user. At login or a user restart the MQSUBREL parameter is returned to the value specified by the User 0 CCAIN parameter line.

A setting of 0 lets you retain the subtask and preserve pre-V7R1.0 behavior. Choose this setting when you expect the same user to use MQ services soon after ending a request.
A setting of 1 lets you release the subtask for another user. Choose this setting when you expect that other users may be waiting for a free MQ subtask.