mqInquireString

The mqInquireString call requests the value of a character data item that is present in the bag. The data item can be a user item or a system item.

Syntax for mqInquireString

mqInquireString (Bag, Selector, ItemIndex, Bufferlength, Buffer, StringLength, CodedCharSetId, CompCode, Reason)

Parameters for mqInquireString

Bag (MQHBAG) - input

Handle of the bag to which the inquiry relates. The bag can be a user bag or a system bag.

Selector (MQLONG) - input

Selector of the item to which the inquiry relates.

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.

The specified selector must be present in the bag; MQRC_SELECTOR_NOT_PRESENT results if it is not.

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.

The following special values can be specified for Selector:

MQSEL_ANY_SELECTOR

The item to be inquired about is a user or system item identified by ItemIndex.

MQSEL_ANY_USER_SELECTOR

The item to be inquired about is a user item identified by ItemIndex.

MQSEL_ANY_SYSTEM_SELECTOR

The item to be inquired about is a system item identified by ItemIndex.

ItemIndex (MQLONG) - input

Index of the data item to which the inquiry relates. The value must be zero or greater, or the special value MQIND_NONE. If the value is less than zero and not MQIND_NONE, MQRC_INDEX_ERROR results. If the item is not already present in the bag, MQRC_INDEX_NOT_PRESENT results. The following special value can be specified:

MQIND_NONE

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

If MQSEL_ANY_SELECTOR is specified for the Selector parameter, ItemIndex is the index relative to the set of items that contains both user items and system items, and must be zero or greater.

If MQSEL_ANY_USER_SELECTOR is specified for the Selector parameter, ItemIndex is the index relative to the set of user items, and must be zero or greater.

If MQSEL_ANY_SYSTEM_SELECTOR is specified for Selector, ItemIndex is the index relative to the set of system items, and must be zero or greater.

If an explicit selector value is specified, ItemIndex is the index relative to the set of items that have that selector value, and can be MQIND_NONE, zero, or greater.

BufferLength (MQLONG) - input

Length in bytes of the buffer to receive the string. Zero is a valid value.

Buffer (MQCHAR x BufferLength) - output

Buffer to receive 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 (non-null) address must be specified for the Buffer parameter.

The string is padded with blanks to the length of the buffer; the string is not null-terminated. If the string is longer than the buffer, the string is truncated to fit; in this case StringLength indicates the size of the buffer needed to accommodate the string without truncation.

StringLength (MQLONG) - output

The length in bytes of the string contained in the bag. If the Buffer parameter is too small, the length of the string returned is less than StringLength.

CodedCharSetId (MQLONG) - output

The coded character set identifier for the character data in the string. This parameter can be set to a null pointer if not required.

CompCode (MQLONG) - output

Completion code.

Reason (MQLONG) - output

Reason code qualifying CompCode. The following reason codes indicating error and warning conditions can be returned from the mqInquireString 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_NONE specified with one of the MQSEL_ANY_xxx_SELECTOR values).

MQRC_INDEX_NOT_PRESENT

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

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_STRING_LENGTH_ERROR

StringLength parameter not valid (invalid parameter address).

MQRC_STRING_TRUNCATED

Data too long for output buffer and has been truncated.

C language invocation for mqInquireString

mqInquireString (Bag, Selector, ItemIndex,
BufferLength, Buffer, &StringLength, &CodedCharSetId,
&CompCode, &Reason);

MQHBAG   Bag;           /* Bag handle */
MQLONG   Selector;      /* Selector */
MQLONG   ItemIndex;     /* Item index */
MQLONG   BufferLength;  /* Buffer length */
PMQCHAR  Buffer;        /* Buffer to contain string */
MQLONG   StringLength;  /* Length of string returned */
MQLONG   CodedCharSetId /* Coded Character Set ID */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

Visual Basic invocation for mqInquireString

(Supported on Windows only.)

mqInquireString Bag, Selector, ItemIndex,
BufferLength, Buffer, StringLength, CodedCharSetId,
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 to contain string'
Dim StringLength    As Long   'Length of string returned'
Dim CodedCharSetId  As Long   'Coded Character Set ID'
Dim CompCode        As Long   'Completion code'
Dim Reason          As Long   'Reason code qualifying CompCode'