Controlling context information
When you use the MQPUT or MQPUT1 call to put a message on a queue, you can specify that the queue manager is to add some default context information to the message descriptor. Applications that have the appropriate level of authority can add extra context information. You can use the options field in the MQPMO structure to control context information.
To control context information, use the Options
field in the MQPMO structure.
If you do not, the queue manager overwrites context information that might already be in the message descriptor with the identity and context information that it has generated for your message. This is the same as specifying the MQPMO_DEFAULT_CONTEXT option. You might want this default context information when you create a new message (for example, when processing user input from an inquiry screen).
If you want no context information associated with your message,
use the MQPMO_NO_CONTEXT option. When putting a message with no context,
any authority checks made by IBM® WebSphere® MQ are made using
a blank user ID. A blank user ID cannot be assigned explicit authority
to IBM WebSphere MQ resources
but is treated as a member of the special group 'nobody'. For more
details on the special group nobody
, see Installable
services interface reference information.
If you want no context information associated with your message, use the MQPMO_NO_CONTEXT option.
The following sections of this topic explain the use of identity context, user context, and all context.
Passing identity context
In general, programs should pass identity context information from message to message around an application until the data reaches its final destination.
Programs should change the origin context information each time that they change the data. However, applications that want to change or set any context information must have the appropriate level of authority. The queue manager checks this authority when the applications open the queues; they must have authority to use the appropriate context options for the MQOPEN call.
If your application gets a message, processes the data from the message, then puts the changed data into another message (possibly for processing by another application), the application must pass the identity context information from the original message to the new message. You can allow the queue manager to create the origin context information.
To save the context information from the original message, use the MQOO_SAVE_ALL_CONTEXT option when you open the queue for getting the message. This is in addition to any other options you use with the MQOPEN call. Note, however, that you cannot save context information if you only browse the message.
- Open the queue using the MQOO_PASS_IDENTITY_CONTEXT option (in addition to the MQOO_OUTPUT option).
- In the
Context
field of the put-message options structure, give the handle of the queue from which you saved the context information. - In the
Options
field of the put-message options structure, specify the MQPMO_PASS_IDENTITY_CONTEXT option.
Passing user context
You cannot choose to pass only user context. To pass user context when putting a message, specify MQPMO_PASS_ALL_CONTEXT. Any properties in the user context are passed in the same way as the origin context.
When an MQPUT or MQPUT1 takes place and the context is being passed, all properties in the user context are passed from the retrieved message to the put message. Any user context properties that the putting application has altered are put with their original values. Any user context properties that the putting application has deleted are restored in the put message. Any user context properties that the putting application has added to the message are retained.
Passing all context
If your application gets a message, and puts the message data (unchanged) into another message, the application must pass all (identity, origin, and user) context information from the original message to the new message. An example of an application that might do this is a message mover, which moves messages from one queue to another.
Follow the same procedure as for passing identity context, except that you use the MQOPEN option MQOO_PASS_ALL_CONTEXT and the put-message option MQPMO_PASS_ALL_CONTEXT.
Setting identity context
- Open the queue using the MQOO_SET_IDENTITY_CONTEXT option.
- Put the message on the queue, specifying the MQPMO_SET_IDENTITY_CONTEXT option. In the message descriptor, specify whatever identity context information you require.
In order to modify any of
the message context options, you must have the appropriate authorizations
to issue the call. For example, in order to use MQOO_SET_IDENTITY_CONTEXT
or MQPMO_SET_IDENTITY_CONTEXT, you must have +setid
permission.
Setting user context
To set a property in the user context, set the Context field of the message property descriptor (MQPD) to MQPD_USER_CONTEXT when you make the MQSETMP call.
You do not need any special authority to set a property in the user context. User context has no MQOO_SET_* or MQPMO_SET_* context options.
Setting all context
- Open the queue using the MQOO_SET_ALL_CONTEXT option.
- Put the message on the queue, specifying the MQPMO_SET_ALL_CONTEXT option. In the message descriptor, specify whatever identity and origin context information you require.