MQI PUT
This statement puts a message to a previously opened queue.
Command | Parameters |
|---|---|
IMFEXEC MQI PUT | HCONN(hconn) HOBJ(hobj) POPTS(options) BUFFLEN(bufferlength) BUFFER(buffer) |
The following table describes the IMFEXEC MQI PUT parameters.
Parameter | Function | Notes |
|---|---|---|
HCONN | Provides the connection handle that represents the connection to the queue manager. | This parameter:
If omitted:
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 to which the message is being PUT. | This parameter:
If omitted:
Either this parameter, specifying an existing variable that contains the object handle, or a previously created IMFHOBJ variable containing the object handle is required. |
POPTS | Specifies the options that control the PUT action. | This parameter is not required. If omitted, the PUT options value is taken from the default variable IMFMQI_PMO_OPTIONS. The variable IMFMQI_PMO_OPTIONS is not required. Options can be specified as any valid combination of the following choices:
See note at the beginning of this table. |
POPTS (continued) | Specifies the options that control the PUT action. | MainView AutoOPERATOR provides you with another option, REMOVE_DLH, in addition to the above options. With the REMOVE_DLH option, you can remove the Dead Letter Header from a message before putting it to another queue. The REMOVE_DLH is added to the POPTS() keyword parameter of the IMFEXEC MQI PUT statement. This MainView AutoOPERATOR option causes the PUT message to be rebuilt by reloading the Encoding, CodedCharSetId and Format fields from the Dead Letter Header (DLH) into the Message Descriptor. The reloading occurs before the PUT statement executes. The DLH, if present, is removed from the buffer containing the data. |
BUFFER | Specifies the variable that contains the message buffer data before issuing the PUT. | This parameter is not required. If omitted, the variable IMFMQI_BUFFER must contain the message buffer data in order to complete the PUT. Be aware that upon successful completion of the PUT statement, the original buffer variable may be different if you have specified structure variables prior to the PUT. For example, you may want to build a Dead Letter message by changing the format variable IMFMQI_MD_FORMAT to MQFMT_DEAD_LETTER_HEADER and by setting variables starting with IMFMQI_DLH_ and ending with Dead Letter (DLH) field names (see Appendix D for lists of structure variables). In this example, MainView AutoOPERATOR updates the buffer from the variables set before issuing the IBM MQ PUT (see the section entitled Creating-a-message-from-variables to learn how MainView AutoOPERATOR creates messages out of variables). The Dead Letter header is prefixed in front of the data that is in the buffer. MainView AutoOPERATOR updates the variable specified for the buffer so that it contains the DLH structure before control is returned to the EXEC. |
BUFFLEN | Specifies the length of the data used to create the variable containing the message buffer data. | This parameter:
You can specify a value in the range of 0 - 32767 when using a CLIST or 0 to 16777169 when using a REXX EXEC, either by specifically citing a numeric value, or by using a variable. If this parameter is omitted, the variable IMFMQI_BUFFLEN will be used to obtain the BUFFER length. If neither is set, the length of the data in the message buffer variable is used. |
Table 1 describes the most common input and output variables for the IMFEXEC MQI PUT statement. Any required variables must be set prior to the PUT. For structures other than the MD (message descriptor), refer to EXECs-variables.
Variables used begin with 'IMFMQI_', followed by the IBM MQ structure, followed by the field name within the IBM MQ structure, with each node delimited by an underscore.
For definitions of field names and constants used in this table that are derived from IBM MQ structure field names, see the IBM manual MQ Application Programming Reference.
Table 1. Common input and output variables for the IMFEXEC MQI PUT statement
Variable name | Source | Notes |
|---|---|---|
IMFMQI_MD_STRUCID | Input | (optional) The EXEC may or may not set this variable. If the EXEC does not set this variable, the IBM MQ default value 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 variable, the IBM MQ default value will be used, unmodified by the EXEC Manager. |
IMFMQI_MD_REPORT | Input | (optional) Specify one or more of the following values delimited by blanks:
See note at the beginning of this table. |
IMFMQI_MD_MSGTYPE | Input | (optional) Specify one of the following values:
See note at the beginning of this table. |
IMFMQI_MD_EXPIRY | Input | (optional) Specify a decimal number, in the range 1 to 999999999, or MQEI_UNLIMITED (IBM default). |
IMFMQI_MD_FEEDBACK | Input | (optional) Specify one of the following values for report messages:
See note at the beginning of this table. In addition, this variable can contain any reason code from the following sources:IMS-bridge feedback codes:
|
IMFMQI_MD_ENCODING | Input | (optional) Specify MQENC_NATIVE (IBM default) or any decimal number up to 999999999. |
IMFMQI_MD_CODEDCHARSETID | Input | (optional) Specify one of the following values:
See note at the beginning of this table. |
IMFMQI_MD_FORMAT | Input | (optional) Specify one of the following:
See note at the beginning of this table. |
IMFMQI_MD_PRIORITY | Input | (optional) Specify a decimal number in the range 0 to 999999999 or MQPRI_PRIORITY_AS_Q_DEF (IBM default). |
IMFMQI_MD_PERSISTENCE | Input | (optional) Specify one of the following:
See note at the beginning of this table. |
IMFMQI_MD_MSGID | Input or Output | (optional) Specify up to a 32-byte MsgId. Processed exactly as received. No conversion of hexadecimal data is done. For input, the value MQMI_NONE is valid. After a successful PUT, the variable is set from the field in the message descriptor. |
IMFMQI_MD_CORRELID | Input or Output | (optional) Specify up to a 32-byte CORRELID. Processed exactly as received. No conversion of hexadecimal data is done. After a successful PUT, the variable is set from the field in the message descriptor. For input, the following values are valid:
|
IMFMQI_MD_BACKOUTCOUNT | NA | This variable is not used for PUT. |
IMFMQI_MD_REPLYTOQ | Input | (optional) Specify up to a 48-character name of the ReplyToQ. The IBM default value is 48 blanks. |
IMFMQI_MD_REPLYTOQMGR | Input | (optional) Specify up to a 48-character name of the ReplyToQMgr. The IBM default value is 48 blanks. |
IMFMQI_MD_ USERIDENTIFIER | Input or Output | (optional) Specify up to a 12-character UserIdentifier. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the UserIdentifier field is used as input and output. |
IMFMQI_MD_ ACCOUNTINGTOKEN | Output | (optional) This variables contains MQACT_NONE (IBM default) or up to a 32-byte AccountingToken. Processed exactly as received. No conversion of hexadecimal data is done. |
IMFMQI_MD_ APPLIDENTITYDATA | Input or Output | (optional) This variables contains up to a 32-character value for ApplIdentityData. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the ApplIdentityData field is used as input and output. |
IMFMQI_STRUCTURES | Output | This variables contains a blank-delimited list of the IBM MQ structures used in the creation of the message. For example, in the case of a Dead Letter message, the contents would contain at least, ‘MD DLH’. |
IMFMQI_OFFSETS | Output | This variables contains a blank-delimited list of the offsets of the structures used in the creation of 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 after issuing the PUT. The number of entries in the list is always one more than the number of structures participating in the operation, including MD, which participates in the operation but is not part of the message buffer. This is because an entry for the offset of the application data is included in the list. The value ‘NONE’ is always used for a structure that does not exist in the buffer but is used in creating the message for PUT, such as ‘MD’. For example, if the message was a dead letter message and contained application data, the variable may 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_PUTAPPLTYPE | Input or output | (optional) Specify one of the following standard types or a numeric user-defined type:
|
IMFMQI_MD_PUTAPPLTYPE (continued) | Input or output |
See note at the beginning of this table. To determine the circumstances under which the PutApplType field is used as input and output see the IBM manual MQ Application Programming Reference. |
IMFMQI_MD_PUTAPPLNAME | Input or output | (optional) Specify up to a 28-character value for PutApplName. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the PutApplName field is used as input and output. |
IMFMQI_MD_PUTDATE | Input or output | (optional) Specify an 8-character date stamp. See theIBM manual MQ Application Programming Reference to determine the circumstances under which the PutDate field is used as input and output. |
IMFMQI_MD_PUTTIME | Input or output | (optional) Specify an 8-character time stamp. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the PutTime field is used as input and output. |
IMFMQI_MD_APPLORIGINDATA | Input or output | (optional) Specify a 4-character value for ApplOriginData. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the ApplOriginData field is used as input and output. |
IMFMQI_MD_GROUPID | Input or output | (optional) If the current MD is a MQMD_VERSION_2 MD, this variable may be set to a 24-byte GROUPID. Processed exactly as received from the PUT. No conversion of hexadecimal data is done. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the GROUPID field is used as input and output. |
IMFMQI_MD_ MSGSEQNUMBER | Input or output | (optional) If a MQMD_VERSION_2 MD is present, this variable may contain a decimal number in the range 1 to 999999999 (IBM default 1). See the IBM manual MQ Application Programming Reference to determine the circumstances under which the MsgSeqNumber field is used as input and output. |
IMFMQI_MD_OFFSET | Input or output | (optional) If a MQMD_VERSION_2 MD is present, this variable may contain a decimal number in the range 0 to 999999999 (IBM default 0). See the IBM manual MQ Application Programming Reference to determine the circumstances under which the Offset field is used as input and output. |
IMFMQI_MD_MSGFLAGS | Input | (optional) If a MQMD_VERSION_2 MD is present, this variable may contain one or more of the following character strings delimited by blanks:
See note at the beginning of this table. |
IMFMQI_MD_ ORIGINALLENGTH | Input | (optional) This variables contains a decimal number, in the range 1 to 999999999, or MQOL_UNDEFINED. |
The completion code is returned in the IMFMQCC and IMFCC variables. For additional information, see How-completion-and-reason-codes-are-returned.
The reason code is returned in the IMFMQRC and IMFRC variables; contents of both variables are the same. Refer to the IBM manual MQ Application Programming Reference for the reason code description.