MQPUT1 (Put one message) on IBM i

The MQPUT1 call puts one message on a queue or distribution list, or to a topic. The queue, distribution list, or topic does not need to be open.


Syntax

MQPUT1 (HCONN, OBJDSC, MSGDSC, PMO, BUFLEN, BUFFER, CMPCOD, REASON)


Usage notes

  1. Both the MQPUT and MQPUT1 calls can be used to put messages on a queue; which call to use depends on the circumstances:

    • The MQPUT call should be used when multiple messages are to be placed on the same queue.

      An MQOPEN call specifying the OOOUT option is issued first, followed by one or more MQPUT requests to add messages to the queue; finally the queue is closed with an MQCLOSE call. This gives better performance than repeated use of the MQPUT1 call.

    • The MQPUT1 call should be used when only one message is to be put on a queue.

      This call encapsulates the MQOPEN, MQPUT, and MQCLOSE calls into a single call, minimizing the number of calls that must be issued.

  2. If an application puts a sequence of messages on the same queue without using message groups, the order of those messages is preserved if certain conditions are satisfied. However, in most environments the MQPUT1 call does not satisfy these conditions, and so does not preserve message order. The MQPUT call must be used instead in these environments. See the usage notes in the description of the MQPUT call for details.
  3. The MQPUT1 call can be used to put messages to distribution lists. For general information about this, see the usage notes for the MQOPEN and MQPUT calls. The following differences apply when using the MQPUT1 call:
    1. If MQRR response records are provided by the application, they must be provided using the MQOD structure; they cannot be provided using the MQPMO structure.
    2. The reason code RC2137 is never returned by MQPUT1 in the response records; if a queue fails to open, the response record for that queue contains the actual reason code resulting from the open operation.

      If an open operation for a queue succeeds with a completion code of CCWARN, the completion code and reason code in the response record for that queue are replaced by the completion and reason codes resulting from the put operation.

      As with the MQOPEN and MQPUT calls, the queue manager sets the response records (if provided) only when the outcome of the call is not the same for all queues in the distribution list; this is indicated by the call completing with reason code RC2136.

  4. If the MQPUT1 call is used to put a message on a cluster queue, the call behaves as though OOBNDN had been specified on the MQOPEN call.
  5. If a message is put with one or more IBM MQ header structures at the beginning of the application message data, the queue manager performs certain checks on the header structures to verify that they are valid. For more information about this, see the usage notes for the MQPUT call.
  6. If more than one of the warning situations arise (see the CMPCOD parameter), the reason code returned is the first one in the following list that applies:
    1. RC2136
    2. RC2242
    3. RC2241
    4. RC2049 or RC2104

  7. The BUFFER parameter shown in the RPG programming example is declared as a string; this restricts the maximum length of the parameter to 256 bytes. If a larger buffer is required, the parameter should be declared instead as a structure, or as a field in a physical file. This will increase the maximum length possible to approximately 32 KB.


Parameters

The MQPUT1 call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

    This handle represents the connection to the queue manager. The value of HCONN was returned by a previous MQCONN or MQCONNX call.

    OBJDSC (MQOD) - input/output

    Object descriptor.

    This is a structure which identifies the queue to which the message is added. See MQOD (Object descriptor) on IBM i for details.

    The user must be authorized to open the queue for output. The queue must not be a model queue.

    MSGDSC (MQMD) - input/output

    Message descriptor.

    This structure describes the attributes of the message being sent, and receives feedback information after the put request is complete. See MQMD (Message descriptor) on IBM i for details.

    If the application provides a version-1 MQMD, the message data can be prefixed with an MQMDE structure in order to specify values for the fields that exist in the version-2 MQMD but not the version-1. The MDFMT field in the MQMD must be set to FMMDE to indicate that an MQMDE is present. See MQMDE (Message descriptor extension) on IBM i for more details.

    PMO (MQPMO) - input/output

    Options that control the action of MQPUT1.

    See MQPMO (Put-message options) on IBM i for details.

    BUFLEN (10-digit signed integer) - input

    Length of the message in BUFFER.

    Zero is valid, and indicates that the message contains no application data. The upper limit depends on various factors; see the description of the BUFLEN parameter of the MQPUT call for further details.

    BUFFER (1-byte bit string x BUFLEN) - input

    Message data.

    This is a buffer containing the application message data to be sent. The buffer should be aligned on a boundary appropriate to the nature of the data in the message. 4-byte alignment should be suitable for most messages (including messages containing IBM MQ header structures), but some messages may require more stringent alignment. For example, a message containing a 64-bit binary integer might require 8-byte alignment.

    If BUFFER contains character data, numeric data, or both, the MDCSI and MDENC fields in the MSGDSC parameter should be set to the values appropriate to the data; this will enable the receiver of the message to convert the data (if necessary) to the character set and encoding used by the receiver.

    Note: All of the other parameters on the MQPUT1 call must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT.

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

      RCNONE
      (0, X'000') No reason to report.

    If CMPCOD is CCWARN:

      RC2104
      (2104, X'838') Report option in message descriptor not recognized.

      RC2136
      (2136, X'858') Multiple reason codes returned.

      RC2049
      (2049, X'801') Message Priority exceeds maximum value supported.

      RC2241
      (2241, X'8C1') Message group not complete.

      RC2242
      (2242, X'8C2') Logical message not complete.

    If CMPCOD is CCFAIL:

      RC2001
      (2001, X'7D1') Alias base queue not a valid type.

      RC2004
      (2004, X'7D4') Buffer parameter not valid.

      RC2005
      (2005, X'7D5') Buffer length parameter not valid.

      RC2009
      (2009, X'7D9') Connection to queue manager lost.

      RC2013
      (2013, X'7DD') Expiry time not valid.

      RC2014
      (2014, X'7DE') Feedback code not valid.

      RC2017
      (2017, X'7E1') No more handles available.

      RC2018
      (2018, X'7E2') Connection handle not valid.

      RC2024
      (2024, X'7E8') No more messages can be handled within current unit of work.

      RC2026
      (2026, X'7EA') Message descriptor not valid.

      RC2027
      (2027, X'7EB') Missing reply-to queue.

      RC2029
      (2029, X'7ED') Message type in message descriptor not valid.

      RC2030
      (2030, X'7EE') Message length greater than maximum for queue.

      RC2031
      (2031, X'7EF') Message length greater than maximum for queue manager.

      RC2035
      (2035, X'7F3') Not authorized for access.

      RC2042
      (2042, X'7FA') Object already open with conflicting options.

      RC2043
      (2043, X'7FB') Object type not valid.

      RC2044
      (2044, X'7FC') Object descriptor structure not valid.

      RC2046
      (2046, X'7FE') Options not valid or not consistent.

      RC2047
      (2047, X'7FF') Persistence not valid.

      RC2048
      (2048, X'800') Queue does not support persistent messages.

      RC2050
      (2050, X'802') Message priority not valid.

      RC2051
      (2051, X'803') Put calls inhibited for the queue.

      RC2052
      (2052, X'804') Queue has been deleted.

      RC2053
      (2053, X'805') Queue already contains maximum number of messages.

      RC2056
      (2056, X'808') No space available on disk for queue.

      RC2057
      (2057, X'809') Queue type not valid.

      RC2058
      (2058, X'80A') Queue manager name not valid or not known.

      RC2059
      (2059, X'80B') Queue manager not available for connection.

      RC2061
      (2061, X'80D') Report options in message descriptor not valid.

      RC2063
      (2063, X'80F') Security error occurred.

      RC2071
      (2071, X'817') Insufficient storage available.

      RC2072
      (2072, X'818') Syncpoint support not available.

      RC2082
      (2082, X'822') Unknown alias base queue.

      RC2085
      (2085, X'825') Unknown object name.

      RC2086
      (2086, X'826') Unknown object queue manager.

      RC2087
      (2087, X'827') Unknown remote queue manager.

      RC2091
      (2091, X'82B') Transmission queue not local.

      RC2092
      (2092, X'82C') Transmission queue with wrong usage.

      RC2097
      (2097, X'831') Queue handle referred to does not save context.

      RC2098
      (2098, X'832') Context not available for queue handle referred to.

      RC2101
      (2101, X'835') Object damaged.

      RC2102
      (2102, X'836') Insufficient system resources available.

      RC2135
      (2135, X'857') Distribution header structure not valid.

      RC2136
      (2136, X'858') Multiple reason codes returned.

      RC2149
      (2149, X'865') PCF structures not valid.

      RC2154
      (2154, X'86A') Number of records present not valid.

      RC2155
      (2155, X'86B') Object records not valid.

      RC2156
      (2156, X'86C') Response records not valid.

      RC2158
      (2158, X'86E') Put message record flags not valid.

      RC2159
      (2159, X'86F') Put message records not valid.

      RC2161
      (2161, X'871') Queue manager quiescing.

      RC2162
      (2162, X'872') Queue manager shutting down.

      RC2173
      (2173, X'87D') Put-message options structure not valid.

      RC2184
      (2184, X'888') Remote queue name not valid.

      RC2188
      (2188, X'88C') Call rejected by cluster workload exit.

      RC2189
      (2189, X'88D') Cluster name resolution failed.

      RC2195
      (2195, X'893') Unexpected error occurred.

      RC2196
      (2196, X'894') Unknown transmission queue.

      RC2197
      (2197, X'895') Unknown default transmission queue.

      RC2198
      (2198, X'896') Default transmission queue not local.

      RC2199
      (2199, X'897') Default transmission queue usage error.

      RC2258
      (2258, X'8D2') Group identifier not valid.

      RC2248
      (2248, X'8C8') Message descriptor extension not valid.

      RC2219
      (2219, X'8AB') MQI call reentered before previous call complete.

      RC2249
      (2249, X'8C9') Message flags not valid.

      RC2250
      (2250, X'8CA') Message sequence number not valid.

      RC2251
      (2251, X'8CB') Message segment offset not valid.

      RC2252
      (2252, X'8CC') Original length not valid.

      RC2253
      (2253, X'8CD') Length of data in message segment is zero.

      RC2255
      (2255, X'8CF') Unit of work not available for the queue manager to use.

      RC2257
      (2257, X'8D1') Wrong version of MQMD supplied.

      RC2266
      (2266, X'8DA') Cluster workload exit failed.

      RC2269
      (2269, X'8DD') Cluster resource error.

      RC2270
      (2270, X'8DE') No destination queues available.

      RC2420
      (2420) An MQPUT1 call was issued, but the message data contains an MQEPH structure that is not valid.

      RC2551
      (2551, X'9F7') Specified selection string is not available.

      RC2554
      (2554, X'9FA') Message content could not be parsed to determine whether the message should be delivered to a subscriber with an extended message selector.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQPUT1(HCONN : OBJDSC : MSGDSC :
     C                                      PMO : BUFLEN : BUFFER :
     C                                      CMPCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQPUT1           PR                  EXTPROC('MQPUT1')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Object descriptor
     D OBJDSC                       468A
     D* Message descriptor
     D MSGDSC                       364A
     D* Options that control the action of MQPUT1
     D PMO                          200A
     D* Length of the message in BUFFER
     D BUFLEN                        10I 0 VALUE
     D* Message data
     D BUFFER                          *   VALUE
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i