mqSetString

The mqSetString call either modifies a character data item that is already present in the bag, or deletes all existing occurrences of the specified selector and adds a new occurrence at the end of the bag. The data item is usually a user item, but certain system-data items can also be modified.

Syntax for mqSetString

mqSetString (Bag, Selector, ItemIndex, Bufferlength, Buffer, CompCode, Reason)

Parameters for mqSetString

Bag (MQHBAG) - input

Handle of the bag to be set. 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.

Selector (MQLONG) - input

Selector of the item to be modified.

If the selector is less than zero (that is, a system selector), the selector must be one that is supported by the MQAI; MQRC_SELECTOR_NOT_SUPPORTED results if it is not.

If the selector is a supported system selector, but is one that is read only, MQRC_SYSTEM_ITEM_NOT_ALTERABLE results.

If the selector is an alterable system selector, but is always a single-instance selector and the application attempts to create a second instance in the bag, MQRC_MULTIPLE_INSTANCE_ERROR 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. If MQCBO_CHECK_SELECTORS was not specified, the selector can be any value zero or greater.

If MQIND_ALL is not specified for the ItemIndex parameter, the specified selector must already be present in the bag; MQRC_SELECTOR_NOT_PRESENT results if it is not.

If MQIND_ALL is not specified for the ItemIndex parameter, the data type of the item must be the same as the data type implied by the call; MQRC_SELECTOR_WRONG_TYPE results if it is not.

ItemIndex (MQLONG) - input

This identifies which occurrence of the item with the specified selector is to be modified. The value must be zero or greater, or one of the special values described in this topic; if it is none of these, MQRC_INDEX_ERROR results.

Zero or greater

The item with the specified index must already be present in the bag; MQRC_INDEX_NOT_PRESENT results if it is not. The index is counted relative to the items in the bag that have the specified selector. For example, if there are five items in the bag with the specified selector, the valid values for ItemIndex are 0 through 4.

MQIND_NONE

This specifies that there must be only one occurrence of the specified selector in the bag. If there is more than one occurrence, MQRC_SELECTOR_NOT_UNIQUE results.

MQIND_ALL

This specifies that all existing occurrences of the specified selector (if any) are to be deleted from the bag, and a new occurrence of the selector created at the end of the bag.

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.

If MQBL_NULL_TERMINATED is not specified, BufferLength characters are inserted into the bag, even if null characters are present; the 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 mqSetString 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_HBAG_ERROR

Bag handle not valid.

MQRC_INDEX_ERROR

Index not valid (index negative and not MQIND_NONE or MQIND_ALL).

MQRC_INDEX_NOT_PRESENT

No item with the specified index is present within the bag for the selector given.

MQRC_MULTIPLE_INSTANCE_ERROR

Multiple instances of system selector not valid.

MQRC_SELECTOR_NOT_PRESENT

No item with the specified selector is present within the bag.

MQRC_SELECTOR_NOT_SUPPORTED

Specified system selector not supported by the MQAI.

MQRC_SELECTOR_NOT_UNIQUE

MQIND_NONE specified when more than one occurrence of the specified selector is present in the bag.

MQRC_SELECTOR_OUT_OF_RANGE

Selector not within valid range for call.

MQRC_SELECTOR_WRONG_TYPE

Data item has wrong data type for call.

MQRC_STORAGE_NOT_AVAILABLE

Insufficient storage available.

MQRC_SYSTEM_BAG_NOT_ALTERABLE

System bag cannot be altered or deleted.

MQRC_SYSTEM_ITEM_NOT_ALTERABLE

System item is read-only and cannot be altered.

Usage notes for mqSetString

The Coded Character Set ID (CCSID) associated with this string is copied from the current CCSID of the bag.

C language invocation for mqSetString

mqSetString (Bag, Selector, ItemIndex, BufferLength, Buffer,
&CompCode, &Reason);

MQHBAG   Bag;           /* Bag handle */
MQLONG   Selector;      /* Selector */
MQLONG   ItemIndex;     /* Item index */
MQLONG   BufferLength;  /* Buffer length */
PMQCHAR  Buffer;        /* Buffer containing string */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

Visual Basic invocation for mqSetString

(Supported on Windows only.)

mqSetString Bag, Selector, ItemIndex, BufferLength, Buffer,
CompCode, Reason

Dim Bag          As Long   'Bag handle'
Dim Selector     As Long   'Selector'
Dim ItemIndex    As Long   'Item index'
Dim BufferLength As Long   'Buffer length'
Dim Buffer       As String 'Buffer containing string'
Dim CompCode     As Long   'Completion code'
Dim Reason       As Long   'Reason code qualifying CompCode'