Home

 

Parameters

 

Options (MQLONG) – input

Options for creation of the bag.

The following are valid:

MQCBO_ADMIN_BAG

Specifies that the bag is for administering WebSphere MQ objects. MQCBO_ADMIN_BAG automatically implies the MQCBO_LIST_FORM_ALLOWED, MQCBO_REORDER_AS_REQUIRED, and MQCBO_CHECK_SELECTORS options.

Administration bags are created with the MQIASY_TYPE system item set to MQCFT_COMMAND.

MQCBO_COMMAND_BAG

Specifies that the bag is a command bag. This is an alternative to the administration bag (MQCBO_ADMIN_BAG) and MQRC_OPTIONS_ERROR results if both are specified.

A command bag is processed in the same way as a user bag except that the value of the MQIASY_TYPE system item is set to MQCFT_COMMAND when the bag is created.

The command bag is also created for administering objects but they are not used to send administration messages to a command server as an administration bag is. The bag options assume the following default values:

• MQCBO_LIST_FORM_INHIBITIED

• MQCBO_DO_NOT_REORDER

• MQCBO_DO_NOT_CHECK_SELECTORS

Therefore, the MQAI will not change the order of data items or create lists within a message as with administration bags.

MQCBO_GROUP_BAG

Specifies that the bag is a group bag. This means that the bag is used to hold a set of grouped items. Group bags cannot be used for the administration of WebSphere MQ objects. The bag options assume the following default values:

• MQCBO_LIST_FORM_ALLOWED

• MQCBO_REORDER_AS_REQUIRED

• MQCBO_DO_NOT_CHECK_SELECTORS

Therefore, the MQAI may change the order of data items or create lists within a bag of grouped items.

Group bags are created with two system selectors: MQIASY_BAG_OPTIONS and MQIASY_CODED_CHAR_SET_ID.

If a group bag is nested in a bag in which MQCBO_CHECK_SELECTORS was specified, the group bag to be nested has its selectors checked at that point whether or not MQCBO_CHECK_SELECTORS was specified when the group bag was created.

MQCBO_USER_BAG

Specifies that the bag is a user bag. This is the default bag-type option. User bags can also be used for the administration of WebSphere MQ objects, but the MQCBO_LIST_FORM_ALLOWED and MQCBO_REORDER_AS_REQUIRED options should be specified to ensure correct generation of the administration messages.

User bags are created with the MQIASY_TYPE system item set to MQCFT_USER.

For user bags, one or more of the following options can be specified:

MQCBO_LIST_FORM_ALLOWED

Specifies that the MQAI is allowed to use the more compact list form in the message sent whenever there are two or more adjacent occurrences of the same selector in the bag. However, this option does not allow the items to be reordered. Therefore, if the occurrences of the selector are not adjacent in the bag, and MQCBO_REORDER_AS_REQUIRED is not specified, the MQAI cannot use the list form for that particular selector.

If the data items are character strings, these strings must have the same Character Set ID as well as the same selector, in order to be compacted into list form. If the list form is used, the shorter strings are padded with blanks to the length of the longest string.

This option should be specified if the message to be sent is an administration message but MQCBO_ADMIN_BAG is not specified.

MQCBO_LIST_FORM_ALLOWED does not imply that the MQAI will definitely use the list form. The MQAI considers various factors in deciding whether to use the list form.

MQCBO_LIST_FORM_INHIBITED

Specifies that the MQAI is not allowed to use the list form in the message sent, even if there are adjacent occurrences of the same selector in the bag. This is the default list-form option.

MQCBO_REORDER_AS_REQUIRED

Specifies that the MQAI is allowed to change the order of the data items in the message sent. This option does not affect the order of the items in the sending bag.

This means that we can insert items into a data bag in any order; that is, the items do not need to be inserted in the way that they must appear in the PCF message, because the MQAI can reorder these items as required.

If the message is a user message, the order of the items in the receiving bag will be the same as the order of the items in the message; this may be different from the order of the items in the sending bag.

If the message is an administration message, the order of the items in the receiving bag will be determined by the message received.

This option should be specified if the message to be sent is an administration message but MQCBO_ADMIN is not specified.

MQCBO_DO_NOT_REORDER

Specifies that the MQAI is not allowed to change the order of data items in the message sent. Both the message sent and the receiving bag contain the items in the same order as they occur in the sending bag. This is the default ordering option.

MQCBO_CHECK_SELECTORS

Specifies that user selectors (selectors that are zero or greater) should be checked to ensure that the selector is consistent with the datatype implied by the mqAddInteger, mqAddInteger64, mqAddIntegerFilter, mqAddString, mqAddStringFilter, mqAddByteString, mqAddByteStringFilter, mqSetInteger, mqSetInteger64, mqSetIntegerFilter, mqSetString, mqSetStringFilter, mqSetByteString, or mqSetByteStringFilter call:

• For the integer, 64-bit integer, and integer filter calls, the selector must be in the range MQIA_FIRST through MQIA_LAST.

• For the string and string filter calls, the selector must be in the range MQCA_FIRST through MQCA_LAST.

• For byte string and byte string filter calls, the selector must be in the range MQBA_FIRST through MQBA_LAST

• For group bag calls, the selector must be in the range MQGA_FIRST through MQGA_LAST

• For the handle calls, the selector must be in the range MQHA_FIRST through MQHA_LAST.

The call fails if the selector is outside the valid range. Note that system selectors (selectors less than zero) are always checked, and if a system selector is specified, it must be one that is supported by the MQAI.

MQCBO_DO_NOT_CHECK_SELECTORS

Specifies that user selectors (selectors that are zero or greater) should not be checked. This option allows any selector that is zero or positive to be used with any call. This is the default selectors option. Note that system selectors (selectors less than zero) are always checked.

MQCBO_NONE

Specifies that all options should have their default values. This is provided to aid program documentation, and should not be specified with any of the options that has a nonzero value.

The following list summarizes the default option values:

• MQCBO_USER_BAG

  • MQCBO_LIST_FORM_INHIBITIED

  • MQCBO_DO_NOT_REORDER

  • MQCBO_DO_NOT_CHECK_SELECTORS

Bag (MQHBAG) – output

The handle of the bag created by the call.

CompCode (MQLONG) – output

Completion code.

Reason (MQLONG) – output

Reason code qualifying CompCode.

The following reason codes indicating error conditions can be returned from the mqCreateBag call:

MQRC_HBAG_ERROR

Bag handle not valid (invalid parameter address or the parameter location is read-only).

MQRC_OPTIONS_ERROR

Options not valid or not consistent.

MQRC_STORAGE_NOT_AVAILABLE

Insufficient storage available.

 

Parent topic:

mqCreateBag

pc16580_

 

Home