MQI PUT1
This statement puts a message to a queue without the need for an OPEN and CLOSE.
Command | Parameters |
|---|---|
IMFEXEC MQI PUT1 | HCONN(hconn) POPTS(options) BUFFLEN(bufferlength) BUFFER(buffer) |
The following table describes the IMFEXEC MQI PUT1 parameters.
Parameter | Function | Notes |
|---|---|---|
HCONN | Provides the connection handle that represents the connection to the queue manager. | This parameter:
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. |
POPTS | Specifies the options that control the PUT1 action. | This parameter is not required. If omitted, the PUT1 options are taken from the default variable IMFMQI_PMO_OPTIONS. The variable IMFMQI_PMO_OPTIONS is not required. Valid PUT1 options:
See note at the beginning of this table. |
POPTS (continued) | Specifies the options that control the PUT1 action. | When specifying multiple options, they must be enclosed within single quotation marks, for example: POPTS(‘MQPMO_NO_SYNCPOINT MQPMO_SET_ALL _CONTEXT’) In addition to the above options, another MainView AutoOPERATOR-provided option (REMOVE_DLH) is available. Using the REMOVE_DLH option, you can remove the Dead Letter Header from a message before PUTting it to another queue. REMOVE_DLH is added to the POPTS() keyword parameter of the IMFEXEC MQI PUT1 statement. This option causes the message being PUT1 to be rebuilt by reloading the Encoding, CodedCharSetId and Format fields from the Dead Letter Header (DLH) into the Message Descriptor. This reloading occurs before the PUT1 statement executes. The DLH, if present, is removed from the buffer containing the data. |
BUFFER | Specifies the variable that contains the message buffer data prior to issuing a PUT1. | This parameter is not required. If omitted, the variable IMFMQI_BUFFER must contain the message buffer data in order to complete the PUT1. Be aware that upon successful completion of the PUT1 statement, the original buffer variable may be different if you have specified structure variables prior to the PUT1. 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 PUT1 (see the section entitled Creating-a-message-from-variables to learn how MainView AutoOPERATOR creates message out of variables). The Dead Letter header is prefixed in front of the data that is currently 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 message buffer data. | This parameter:
If this parameter is omitted, the variable IMFMQI_BUFFLEN is used to obtain the BUFFER length. If neither is set, the length of the data in the message buffer variable is used. |
The following table describes the most common Input and Output variables for the IMFEXEC MQI PUT1 statement. Any required variables must be set prior to the PUT. For structures other than the MD (message descriptor) and the OD (object descriptor), please refer to EXECs-variables. Variables used begin with 'IMFMQI_', followed by the 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 derived from IBM MQ structure field names and used in this table, see the IBM manual MQ Application Programming Reference.
Variable name | Source | Notes |
|---|---|---|
IMFMQI_OD_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_OD_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_OD_OBJECTTYPE | 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_OD_OBJECTNAME | Input | This variables contains the queue name to be opened. Up to 48 characters can be specified. |
IMFMQI_OD_OBJECTQMGRNAME | Input | (optional) This variables contains the 48-character object queue manager name. The EXEC Manager does not specify any default value when this variable is not set. |
IMFMQI_OD_DYNAMICQNAME | Input | (optional) This variables contains the 48-character dynamic queue name when using a model queue. The EXEC Manager does not specify any default value when this variable is not set. |
IMFMQI_OD_ALTERNATEUSERID | Input | (optional) This variables contains the 12-character alternate user identifier. The EXEC Manager does not specify any default value when this variable is not set. |
IMFMQI_OD_RECSPRESENT | 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_OD_KNOWNDESTCOUNT | Output | This variable contains 0. |
IMFMQI_OD_UNKNOWNDESTCOUNT | Output | This variable contains 0. |
IMFMQI_OD_INVALIDDESTCOUNT | Output | This variable contains 0. |
IMFMQI_OD_OBJECTRECOFFSET | Input | This variable contains 0. |
IMFMQI_OD_RESPONSERECOFFSET | Input | This variable contains 0. |
IMFMQI_OD_OBJECTRECPTR | Input | This variable contains 0. |
IMFMQI_OD_RESPONSERECPTR | Input | This variable contains 0. |
IMFMQI_OD_ALTERNATESECURITYID | Input | This variable exists but is null. |
IMFMQI_OD_RESOLVEDQNAME | Output | This variable contains blanks. |
IMFMQI_OD_RESOLVEDQMGRNAME | Output | This variable contains blanks. |
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 | Input | (optional) Specify one or more of the following delimited by blanks:
See note at the beginning of this table. |
IMFMQI_MD_MSGTYPE | Input | (optional) Specify one of the following:
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:
|
IMFMQI_MD_ENCODING | Input | (optional) Specify one of the following: MQENC_NATIVE (IBM default) or any decimal number up to 999999999. |
IMFMQI_MD_CODEDCHARSETID | Input | (optional) This variables contains one of the following:
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_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 | (optional) Specify one of the following standard types or a numeric user-defined type:
See note at the beginning of this table. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the PutApplType field is used as Input and Output. |
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 the IBM 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 I 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 an MQMD_VERSION_2 MD, this variable may be set to a 24-byte GROUPID. Processed exactly as received from the PUT1. No conversion of hexadecimal data is done. See the IBM manual MQ Application Programming Reference to determine the circumstances under which the Grouped 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. |
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 OD 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. |
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.