mqAddString

The mqAddString call adds a character data item identified by a user selector to the end of a specified bag.

Syntax for mqAddString

mqAddString (Bag, Selector, BufferLength, Buffer, CompCode, Reason)

Parameters for mqAddString

Bag (MQHBAG) - input

Handle of the bag to be modified.

This value 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 the value you specify relates to a system bag.

Selector (MQLONG) - input

Selector identifying the item to be added to the bag.

If the selector is less than zero (that is, a system selector), MQRC_SELECTOR_OUT_OF_RANGE results.

If the selector is zero or greater (that is, a user selector), and the bag was created with the MQCBO_CHECK_SELECTORS option or as an administration bag (MQCBO_ADMIN_BAG), the selector must be in the range MQCA_FIRST through MQCA_LAST. MQRC_SELECTOR_OUT_OF_RANGE results if it is not in the correct range.

If MQCBO_CHECK_SELECTORS was not specified, the selector can be any value zero or greater.

If the call is creating a second or later occurrence of a selector that is already in the bag, the data type of this occurrence must be the same as the data type of the first occurrence; MQRC_INCONSISTENT_ITEM_TYPE results if it is not.

BufferLength (MQLONG) - input

The length in bytes of the string contained in the Buffer parameter. The value must be zero or greater, or the special value MQBL_NULL_TERMINATED:

• If MQBL_NULL_TERMINATED is specified, the string is delimited by the first null encountered in the string. The null is not added to the bag as part of the string.
• If MQBL_NULL_TERMINATED is not specified, BufferLength characters are inserted into the bag, even if null characters are present. Nulls do not delimit the string.

Buffer (MQCHAR x BufferLength) - input

Buffer containing the character string.

The length is given by the BufferLength parameter. If zero is specified for BufferLength, the null pointer can be specified for the address of the Buffer parameter. In all other cases, a valid (nonnull) address must be specified for the Buffer parameter.

CompCode (MQLONG) - output

Completion code.

Reason (MQLONG) - output

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

MQRC_BUFFER_ERROR

Buffer parameter not valid (invalid parameter address or buffer not completely accessible).

MQRC_BUFFER_LENGTH_ERROR

Buffer length not valid.

MQRC_CODED_CHAR_SET_ID_ERROR

Bag CCSID is MQCCSI_EMBEDDED.

MQRC_HBAG_ERROR

Bag handle not valid.

MQRC_INCONSISTENT_ITEM_TYPE

Data type of this occurrence of selector differs from data type of first occurrence.

MQRC_SELECTOR_OUT_OF_RANGE

Selector not within valid range for call.

MQRC_STORAGE_NOT_AVAILABLE

Insufficient storage available.

MQRC_SYSTEM_BAG_NOT_ALTERABLE

System bag cannot be altered or deleted.

Usage notes for mqAddString

1. If a data item with the specified selector is already present in the bag, an additional instance of that selector is added to the end of the bag. The new instance is not necessarily adjacent to the existing instance.
2. This call cannot be used to add a system selector to a bag.
3. The Coded Character Set ID associated with this string is copied from the current CCSID of the bag.

C language invocation for mqAddString

mqAddString (hBag, Selector, BufferLength, Buffer, &CompCode, &Reason);

MQHBAG   hBag;           /* Bag handle */
MQLONG   Selector;       /* Selector */
MQLONG   BufferLength;   /* Buffer length */
PMQCHAR  Buffer          /* Buffer containing item value */
MQLONG   CompCode;       /* Completion code */
MQLONG   Reason;         /* Reason code qualifying CompCode */

Visual Basic invocation for mqAddString

(Supported on Windows only.)

mqAddString Bag, Selector, BufferLength, Buffer, CompCode, Reason

Dim Bag          As Long 'Bag handle'
Dim Selector     As Long 'Selector'
Dim BufferLength As Long 'Buffer length'
Dim Buffer       As String 'Buffer containing item value'
Dim CompCode     As Long 'Completion code'
Dim Reason       As Long 'Reason code qualifying CompCode'