MQI GET

IMFEXEC MQI GET

HCONN(hconn)

HOBJ(hobj)

GOPTS(options)

BUFFLEN(bufferlength)

BUFFER(buffer)

DATALEN(datalength)

HCONN

Provides the connection handle that represents the connection to the queue manager.

This parameter:

• Specifies a variable created in an earlier CONN command

• Is not required

If omitted, the connection handle value is the default variable IMFHCONN. The connection handle is returned by a previous IMFEXEC MQI CONN request and stored in the IMFHCONN variable or a user-specified variable. Either this parameter, specifying an existing variable that contains the connection handle, or a previously created IMFHCONN variable containing the connection handle is required.

HOBJ

Provides the object handle that represents the queue from which the message is returned.

This parameter:

• Specifies a variable created in an earlier OPEN command

• Is not required

If omitted:

• The object handle value is taken from the default variable IMFHOBJ.

• The object handle is returned by a previous IMFEXEC MQI OPEN request and stored in the IMFHOBJ variable or a user-specified variable.

Either this parameter, specifying an existing variable that contains the object handle, or a previously created IMFHOBJ variable containing the object handle is required.

GOPTS

Specifies the options that control the action of GET.

This parameter is not required.

If omitted, the GET options value is taken from the default variable IMFMQI_GMO_OPTIONS. The variable IMFMQI_GMO_OPTIONS is not required.

If GET options are not specified, IBM MQ will use the default, MQGMO_NO_WAIT.

More than one of the following valid GET options can be specified in any valid combination:

• MQGMO_WAIT

• MQGMO_NO_WAIT

• MQGMO_SYNCPOINT

• MQGMO_SYNCPOINT_IF_PERSISTENT

• MQGMO_NO_SYNCPOINT

• MQGMO_MARK_SKIP_BACKOUT

• MQGMO_BROWSE_FIRST

• MQGMO_BROWSE_NEXT

• MQGMO_MSG_UNDER_CURSOR

• MQGMO_ACCEPT_TRUNCATED_MSG

• MQGMO_SET_SIGNAL

• MQGMO_FAIL_IF_QUIESCING

• MQGMO_CONVERT

• MQGMO_NONE

• MQGMO_LOCK

• MQGMO_UNLOCK

• MQGMO_LOGICAL_ORDER

• MQGMO_COMPLETE_MSG

• MQGMO_ALL_MSGS_AVAILABLE

• MQGMO_ALL_SEGMENTS_AVAILABLE

• MQGMO_MARK_BROWSE_HANDLE

• MQGMO_MARK_BROWSE_CO_OP

• MQGMO_UNMARK_BROWSE_CO_OP

• MQGMO_UNMARK_BROWSE_HANDLE

• MQGMO_UNMARKED_BROWSE_MSG

• MQGMO_PROPERTIES_FORCE_MQRFH2

GOPTS

(continued)

Specifies the options that control the action of GET.

• MQGMO_NO_PROPERTIES

• MQGMO_PROPERTIES_IN_HANDLE

• MQGMO_PROPERTIES_COMPATIBILITY

• MQGMO_PROPERTIES_AS_Q_DEF

• MQGMO_BROWSE_HANDLE

• MQGMO_BROWSE_CO_OP

See note at the beginning of this table.

In addition to these options, another MainView AutoOPERATOR option is REMOVE_DLH.

Using the REMOVE_DLH option, you can retrieve messages from a Dead Letter queue, process them and forward them to an application queue without the Dead Letter Header. The REMOVE_DLH option is added to the GOPTS() keyword parameter of the IMFEXEC MQI GET statement.

This option causes the IMFMQI_MD_ENCODING, IMFMQI_MD_CODEDCHARSETID and I MFMQI_MD_FORMAT variables to be set from the Dead Letter Header instead of the message descriptor.

The returned buffer is without the DLH. This action occurs before control is returned to the EXEC following the IMFEXEC MQI GET command. The message can optionally be placed directly onto another queue.

BUFFER

Specifies the variable that contains the message buffer data following a successful GET.

This parameter is not required. If omitted, the variable IMFMQI_BUFFER will contain the Message Buffer data upon successful completion of the GET.

BUFFLEN

Specifies the length of the data used to create the variable containing the message buffer data.

This parameter:

• Is not required

• Can specify a numeric value or the name of a variable that contains a numeric value

• Can specify a value in the range of 0 - 32767 when using CLIST or 0 to 16777169 (when using REXX EXECs), either specifically citing a numeric value, or you can use a variable.

If this parameter is omitted, the variable IMFMQI_BUFFLEN is used to obtain the BUFFER length. If the variable is not set, the message length is used. The recommendation is that you do not set the variable so that the message length is used.

DATALEN

Specifies the variable to be set to the message length following a successful GET.

This parameter is not required.

If omitted, the variable IMFMQI_DATALEN is set with the length of the message data returned from the GET. If the value is greater than the buffer length value, only buffer length bytes are returned in the buffer variable. If the value is zero, it means that the message contains no application data.

IMFMQI_STRUCTURES

Output

This variable contains a blank-delimited list of the IBM MQ structures contained in the message. For example, in the case of a Dead Letter message, the contents would contain at least:

‘MD DLH’

IMFMQI_OFFSETS

Output

This variable contains a blank-delimited list of the offsets of the structures contained in the message (as well as the offset of the application data) from the beginning of the message buffer. Using this variable, you can access application data beyond the structures in the message buffer. The number of entries in the list is always one more than the number of structures participating in the operation (IMFMQI_STRUCTURES) because an entry for the offset of the application data is included in the list. A ‘NONE’ is always used for a structure that does not exist in the buffer, such as ‘MD’. For example, if the message was a dead letter message and contained some application data, the variable might look like this:

‘NONE 0 172’

In the above example, NONE is specified for the MD, 0 for the offset of the Dead Letter Header and 172 is the offset of the application data.

IMFMQI_MD_STRUCID

Input

(optional) The EXEC may or may not set this variable. If the EXEC does not set this value, the IBM MQ default will be used, unmodified by the EXEC Manager.

IMFMQI_MD_VERSION

Input

(optional) The EXEC may or may not set this variable. If the EXEC does not set this value, the IBM MQ default will be used unmodified by the EXEC Manager.

IMFMQI_MD_REPORT

Output

This variable contains one or more of the following values delimited by blanks:

• MQRO_EXCEPTION

• MQRO_EXCEPTION_WITH_DATA

• MQRO_EXCEPTION_WITH_FULL_DATA

• MQRO_EXPIRATION

• MQRO_EXPIRATION_WITH_DATA

• MQRO_EXPIRATION_WITH_FULL_DATA

• MQRO_COA

• MQRO_COA_WITH_DATA

• MQRO_COA_WITH_FULL_DATA

• MQRO_COD

• MQRO_COD_WITH_DATA

• MQRO_COD_WITH_FULL_DATA

• MQRO_PAN

• MQRO_NAN

• MQRO_NEW_MSG_ID

• MQRO_PASS_MSG_ID

• MQRO_COPY_MSG_ID_TO_CORREL_ID

• MQRO_PASS_CORREL_ID

• MQRO_DEAD_LETTER_Q

• MQRO_DISCARD_MSG

• MQRO_NONE

See note at the beginning of this table.

IMFMQI_MD_MSGTYPE

Output

This variable contains one of the following values:

• MQMT_DATAGRAM

• MQMT_REQUEST

• MQMT_REPLY

• MQMT_REPORT

See note at the beginning of this table.

IMFMQI_MD_EXPIRY

Output

This variable contains a decimal number, in the range 1 to 999999999, or MQEI_UNLIMITED.

IMFMQI_MD_FEEDBACK

Output

This variable contains one of the following values for report messages:

• MQFB_NONE

• MQFB_COA

• MQFB_COD

• MQFB_EXPIRATION

• MQFB_PAN

• MQFB_NAN

• MQFB_QUIT

In addition, this field can contain any reason code from the following sources:

• IMS-bridge feedback codes

• CICS-bridge feedback codes

• MQ reason codes

See note at the beginning of this table.

IMFMQI_MD_ENCODING

Output

This variable contains MQENC_NATIVE or any decimal number up to 999999999.

IMFMQI_MD_CODEDCHARSETID

Input or Output

This variable contains:

• MQCCSI_Q_MGR

• MQCCSI_EMBEDDED

Or any decimal number up to 999999999. See the IBM manual MQ Application Programming Reference or the IBM Knowledge Center for details on how to use the CodedCharSetId field as input.

IMFMQI_MD_FORMAT

Output

This variable contains one of the following formats:

• MQFMT_NONE

• MQFMT_ADMIN

• MQFMT_CHANNEL_COMPLETED

• MQFMT_CICS

• MQFMT_COMMAND_1

• MQFMT_COMMAND_2

• MQFMT_DEAD_LETTER_HEADER

• MQFMT_EVENT

• MQFMT_IMS

• MQFMT_IMS_VAR_STRING

• MQFMT_MD_EXTENSION

• MQFMT_PCF

• MQFMT_REF_MSG_HEADER

• MQFMT_STRING

• MQFMT_TRIGGER

• MQFMT_WORK_INFO_HEADER

• MQFMT_XMIT_Q_HEADER

• MQFMT_RF_HEADER

• MQFMT_RF_HEADER_2

See note at the beginning of this table.

IMFMQI_MD_PRIORITY

Output

This variable contains a decimal number in the range 0 to 999999999.

IMFMQI_MD_PERSISTENCE

Output

This variable contains one of the following:

• MQPER_PERSISTENT

• MQPER_NOT_PERSISTENT

IMFMQI_MD_MSGID

Input or Output

This variable processes or receives up to a 32-byte MsgId that is processed exactly as received for input to, and as Output from, the GET command. No conversion of hexadecimal data is performed in either case.

For input, the value MQMI_NONE is valid.

IMFMQI_MD_CORRELID

Input or Output

This variable processes or receives up to a 32-byte CORRELID that is processed exactly as received for input to and as Output from the GET command. No conversion of hexadecimal data is performed in either case. For input, the following constant values is recognized and converted to their corresponding hexadecimal equivalent:

• MQCI_NONE

• MQCI_NEW_SESSION

IMFMQI_MD_BACKOUTCOUNT

Output

This variable contains a decimal value in the range 0 to 255.

IMFMQI_MD_REPLYTOQ

Output

This variable contains up to a 48-character name of the ReplyToQ.

IMFMQI_MD_REPLYTOQMGR

Output

This variable contains up to a 48-character name of the ReplyToQMgr.

IMFMQI_MD_USERIDENTIFIER

Output

This variable contains up to a 12-character UserIdentifier.

IMFMQI_MD_ACCOUNTINGTOK

Output

This variable contains MQACT_NONE or up to a 32-byte AccountingToken. Processed exactly as received from the GET. No conversion of hexadecimal data is done.

IMFMQI_MD_APPLIDENTITYDATA

Output

This variable contains up to a 32-character value for ApplIdentityData.

IMFMQI_MD_PUTAPPLTYPE

Output

This variable contains a user-defined type or one of the following standard types:

• MQAT_AIX

• MQAT_BROKER

• MQAT_CICS

• MQAT_CICS_BRIDGE

• MQAT_CICS_VSE

• MQAT_DEFAULT

• MQAT_DOS

• MQAT_DQM

• MQAT_GUARDIAN

• MQAT_IMS

• MQAT_IMS_BRIDGE

• MQAT_JAVA

• MQAT_MVS

• MQAT_NOTES_AGENT

• MQAT_NSK

• MQAT_OS2

• MQAT_OS390

• MQAT_OS400

• MQAT_QMGR

• MQAT_UNKNOWN

• MQAT_UNIX

IMFMQI_MD_PUTAPPLTYPE

(continued)

Output

• MQAT_VMS

• MQAT_VOS

• MQAT_WINDOWS

• MQAT_WINDOWS_NT

• MQAT_XCF

See note at the beginning of this table.

IMFMQI_MD_PUTAPPLNAME

Output

This variable contains up to a 28-character value for PutApplName.

IMFMQI_MD_PUTDATE

Output

This variable contains an 8-character date stamp.

IMFMQI_MD_PUTTIME

Output

This variable contains an 8-character time stamp.

IMFMQI_MD_APPLORIGINDATA

Output

This variable contains a 4-character value for ApplOriginData.

IMFMQI_MD_GROUPID

Output

If a MQMD_VERSION_2 MD is present, this variable may contain a 24-byte GROUPID. Processed exactly as received from the GET. No conversion of hexadecimal data is done.

IMFMQI_MD_MSGSEQNUMBER

Output

If a MQMD_VERSION_2 MD is present, this variable may contain a decimal number in the range 1 to 999999999.

IMFMQI_MD_OFFSET

Output

If a MQMD_VERSION_2 MD is present, this variable may contain a decimal number in the range 0 to 999999999.

IMFMQI_MD_MSGFLAGS

Output

If a MQMD_VERSION_2 MD is present, this variable may contain one or more of the following character strings delimited by blanks:

• MQMF_SEGMENTATION_INHIBITED

• MQMF_SEGMENTATION_ALLOWED

• MQMF_MSG_IN_GROUP

• MQMF_LAST_MSG_IN_GROUP

• MQMF_SEGMENT

• MQMF_LAST_SEGMENT

• MQMF_NONE

See note at the beginning of this table.

IMFMQI_MD_ORIGINALLENGTH

Output

This variable contains a decimal number, in the range 1 to 999999999, or MQOL_UNDEFINED.

See note at the beginning of this table.