MQSETMP (Set message handle property) on IBM i

The MQSETMP call sets or modifies a property of a message handle.


Syntax

MQSETMP (Hconn, Hmsg, SetPropOpts, Name, PropDesc, Type, ValueLength, Value, CompCode, Reason)


Usage notes

  • We can use this call only when the queue manager itself coordinates the unit of work. This can be:

    • A local unit of work, where the changes affect only IBM MQ resources.
    • A global unit of work, where the changes can affect resources belonging to other resource managers, as well as affecting IBM MQ resources.

    For further details about local and global units of work, see MQBEGIN (Begin unit of work) on IBM i.

  • In environments where the queue manager does not coordinate the unit of work, use the appropriate back-out call instead of MQBACK. The environment might also support an implicit back out caused by the application terminating abnormally.

    • On z/OS, use the following calls:

      • Batch programs (including IMS batch DL/I programs) can use the MQBACK call if the unit of work affects only IBM MQ resources. However, if the unit of work affects both IBM MQ resources and resources belonging to other resource managers (for example, Db2 ), use the SRRBACK call provided by the z/OS Recoverable Resource Service (RRS). The SRRBACK call backs out changes to resources belonging to the resource managers that have been enabled for RRS coordination.
      • CICS applications must use the EXEC CICS SYNCPOINT ROLLBACK command to back out the unit of work. Do not use the MQBACK call for CICS applications.
      • IMS applications (other than batch DL/I programs) must use IMS calls such as ROLB to back out the unit of work. Do not use the MQBACK call for IMS applications (other than batch DL/I programs).

    • On IBM i, use this call for local units of work coordinated by the queue manager. This means that a commitment definition must not exist at job level, that is, the STRCMTCTL command with the CMTSCOPE(*JOB) parameter must not have been issued for the job.

  • If an application ends with uncommitted changes in a unit of work, the disposition of those changes depends on whether the application ends normally or abnormally. See the usage notes in MQDISC (Disconnect queue manager) on IBM i for further details.
  • When an application puts or gets messages in groups or segments of logical messages, the queue manager retains information relating to the message group and logical message for the last successful MQPUT and MQGET calls. This information is associated with the queue handle, and includes such things as:

    • The values of the GroupId, MsgSeqNumber, Offset, and MsgFlags fields in MQMD.
    • Whether the message is part of a unit of work.
    • For the MQPUT call: whether the message is persistent or nonpersistent.

    The queue manager keeps three sets of group and segment information, one set for each of the following:

    • The last successful MQPUT call (this can be part of a unit of work).
    • The last successful MQGET call that removed a message from the queue (this can be part of a unit of work).
    • The last successful MQGET call that browsed a message on the queue (this cannot be part of a unit of work).

    If the application puts or gets the messages as part of a unit of work, and the application then decides to back out the unit of work, the group and segment information is restored to the value that it had previously:

    • The information associated with the MQPUT call is restored to the value that it had before the first successful MQPUT call for that queue handle in the current unit of work.
    • The information associated with the MQGET call is restored to the value that it had before the first successful MQGET call for that queue handle in the current unit of work.

    Queues that were updated by the application after the unit of work started, but outside the scope of the unit of work, do not have their group and segment information restored if the unit of work is backed out.

    Restoring the group and segment information to its previous value when a unit of work is backed out allows the application to spread a large message group or large logical message consisting of many segments across several units of work, and to restart at the correct point in the message group or logical message if one of the units of work fails.

    Use several units of work might be advantageous if the local queue manager has only limited queue storage. However, the application must maintain sufficient information to be able to restart putting or getting messages at the correct point if a system failure occurs.

    For details of how to restart at the correct point after a system failure, see the PMLOGO option described in PMOPT (10 digit signed integer), and the GMLOGO option described in GMOPT (10 digit signed integer).

    The remaining usage notes apply only when the queue manager coordinates the units of work:

  • A unit of work has the same scope as a connection handle. All IBM MQ calls that affect a particular unit of work must be performed using the same connection handle. Calls issued using a different connection handle (for example, calls issued by another application) affect a different unit of work. See HCONN (10-digit signed integer) - output for information about the scope of connection handles.
  • Only messages that were put or retrieved as part of the current unit of work are affected by this call.
  • A long-running application that issues MQGET, MQPUT, or MQPUT1 calls within a unit of work, but that never issues a commit or backout call, can fill queues with messages that are not available to other applications. To guard against this possibility, the administrator must set the MaxUncommittedMsgs queue manager attribute to a value that is low enough to prevent runaway applications filling the queues, but high enough to allow the expected messaging applications to work correctly.


Parameters

The MQSETMP call has the following parameters:

    HCONN (10-digit signed integer) - input

    This handle represents the connection to the queue manager.

    The value must match the connection handle that was used to create the message handle specified in the HMSG parameter.

    If the message handle was created using HCUNAS, a valid connection must be established on the thread setting a property of the message handle, otherwise the call fails with reason code RC2009 .

    HMSG (20-digit signed integer) - input

    This is the message handle to be modified. The value was returned by a previous MQCRTMH call.

    SETOPT (MQSMPO) - input

    Control how message properties are set.

    This structure allows applications to specify options that control how message properties are set. The structure is an input parameter on the MQSETMP call. See MQSMPO for further information.

    PRNAME (MQCHARV) - input

    This is the name of the property to set.

    See Property names and Property name restrictions for further information about the use of property names.

    PRPDSC (MQPD) - input/output
    This structure is used to define the attributes of a property, including:

    • what happens if the property is not supported
    • what message context the property belongs to
    • what messages the property is copied into as it flows

    See MQPD for further information about this structure.

    TYPE (10 digit signed integer) - input

    The data type of the property being set. It can be one of the following:

      TYPBOL
      A boolean. ValueLength must be 4.

      TYPBST
      A byte string. ValueLength must be zero or greater.

      TYPI8
      An 8 bit signed integer. ValueLength must be 1.

      TYPI16
      A 16 bit signed integer. ValueLength must be 2.

      TYPI32
      A 32 bit signed integer. ValueLength must be 4.

      TYPI64
      A 64 bit signed integer. ValueLength must be 8.

      TYPF32
      A 32 bit floating-point number. ValueLength must be 4.

      TYPF64
      A 64 bit floating-point number. ValueLength must be 8.

      TYPSTR
      A character string. ValueLength must be zero or greater, or the special value VLNULL.

      TYPNUL
      The property exists but has a null value. ValueLength must be zero.

    VALLEN (10-digit signed integer) - input

    The length in bytes of the property value in the Value parameter.

    Zero is valid only for null values or for strings or byte strings. Zero indicates that the property exists but that the value contains no characters or bytes.

    The value must be greater than or equal to zero or the following special value if the Type parameter has TYPSTR set:

      VLNULL
      The value is delimited by the first null encountered in the string. The null is not included as part of the string. This value is invalid if TYPSTR is not also set.
      Note: The null character used to terminate a string if VLNULL is set is a null from the character set of the Value.

    VALUE (1-byte bit string x VALLEN) - input

    The value of the property to be set. The buffer must be aligned on a boundary appropriate to the nature of the data in the value.

    In the C programming language, the parameter is declared as a pointer-to-void; the address of any type of data can be specified as the parameter.

    If ValueLength is zero, Value is not referred to. In this case, the parameter address passed by programs written in C or System/390 assembler can be null.

    CMPCOD (10-digit signed integer) - output
    The completion code; it is one of the following:

      CCOK
      Successful completion.

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    The reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

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

    If CMPCOD is CCWARN:

      RC2421
      (2421, X'0975') An MQRFH2 folder containing properties could not be parsed.

    If CMPCOD is CCFAIL:

      RC2204
      (2204, X'089C') Adapter not available.

      RC2130
      (2130, X'852') Unable to load adapter service module.

      RC2157
      (2157, X'86D') Primary and home ASIDs differ.

      RC2004
      (2004, X'07D4') Value parameter not valid.

      RC2005
      (2005, X'07D5') Value length parameter not valid.

      RC2219
      (2219, X'08AB') MQI call entered before previous call completed.

      RC2460
      (2460, X'099C') Message handle pointer not valid.

      RC2499
      (2499, X'09C3') Message handle already in use.

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

      RC2482
      (2482, X'09B2') Property descriptor structure not valid.

      RC2442
      (2442, X'098A') Invalid property name.

      RC2473
      (2473, X'09A9') Invalid property data type.

      RC2472
      (2472, X'09A8') Number format error encountered in value data.

      RC2463
      (2463, X'099F') Set message property options structure not valid.

      RC2111
      (2111, X'083F') Property name coded character set identifier not valid.

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

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

    See Return codes for IBM i (ILE RPG) for more details.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQSETMP(HCONN : HMSG : SETOPT :
                                             PRNAME : PRPDSC : 
                                             TYPE : VALLEN : VALUE :
                                             CMPCOD : REASON)
The prototype definition for the call is: 
     DMQSETMP          PR                  EXTPROC('MQSETMP')
     D* Connection handle 
     D HCONN                         10I 0 VALUE
     D* Message handle 
     D HMSG                          10I 0 VALUE
     D* Options that control the action of MQSETMP 
     D SETOPT                        20A   
     D* Property name 
     D PRNAME                        32A
     D* Property descriptor 
     D PRPDSC                        24A   
     D* Property data type 
     D TYPE                          10I 0 VALUE
     D* Length of the Value area 
     D VALLEN                        10I 0 VALUE
     D* Property value 
     D VALUE                           *   VALUE
     D* Completion code 
     D CMPCOD                        10I 0 
     D* Reason code qualifying CompCode 
     D REASON                        10I 0
Parent topic: Function calls on IBM i