mqTruncateBag

The mqTruncateBag call reduces the number of user items in a user bag to the specified value, by deleting user items from the end of the bag.

Syntax for mqTruncateBag

mqTruncateBag (Bag, ItemCount, CompCode, Reason)

Parameters for mqTruncateBag

Bag (MQHBAG) - input

Handle of the bag to be truncated. This must be the handle of a bag created by the user, not the handle of a system bag; MQRC_SYSTEM_BAG_NOT_ALTERABLE results if we specify the handle of a system bag.

ItemCount (MQLONG) - input

The number of user items to remain in the bag after truncation. Zero is a valid value. Note: The ItemCount parameter is the number of data items, not the number of unique selectors. (If there are one or more selectors that occur multiple times in the bag, there will be fewer selectors than data items before truncation.) Data items are deleted from the end of the bag, in the opposite order to which they were added to the bag.

If the number specified exceeds the number of user items currently in the bag, MQRC_ITEM_COUNT_ERROR results.

CompCode (MQLONG) - output

Completion code.

Reason (MQLONG) - output

Reason code qualifying CompCode. The following reason codes indicating error conditions can be returned from the mqTruncateBag call:

MQRC_HBAG_ERROR

Bag handle not valid.

MQRC_ITEM_COUNT_ERROR

ItemCount parameter not valid (value exceeds the number of user data items in the bag).

MQRC_SYSTEM_BAG_NOT_ALTERABLE

System bag cannot be altered or deleted.

Usage notes for mqTruncateBag

1. System items in a bag are not affected by mqTruncateBag; the call cannot be used to truncate system bags.
2. mqTruncateBag with an ItemCount of zero is not the same as the mqClearBag call. The former deletes all of the user items but leaves the system items intact, and the latter deletes all of the user items and resets the system items to their initial values.

C language invocation for mqTruncateBag

mqTruncateBag (Bag, ItemCount, &CompCode, &Reason);

MQHBAG   hBag;          /* Bag handle */
MQLONG   ItemCount;     /* Number of items to remain in bag */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

Visual Basic invocation for mqTruncateBag

(Supported on Windows only.)

mqTruncateBag Bag, ItemCount, CompCode, Reason

Dim Bag       As Long 'Bag handle'
Dim ItemCount As Long 'Number of items to remain in bag'
Dim CompCode  As Long 'Completion code'
Dim Reason    As Long 'Reason code qualifying CompCode'