MQSETMP - Set message property

Use the MQSETMP call to set or modify a property of a message handle.


Syntax

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


Parameters

    Hconn
    Type: MQHCONN - 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 MQHC_UNASSOCIATED_HCONN, a valid connection must be established on the thread setting a property of the message handle, otherwise the call fails with reason code MQRC_CONNECTION_BROKEN.

    Hmsg
    Type: MQHMSG - input

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

    SetPropOpts
    Type: 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.

    Name
    Type: 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.

    PropDesc
    Type: 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
    Type: MQLONG - input

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

      MQTYPE_BOOLEAN
      A Boolean. ValueLength must be 4.

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

      MQTYPE_INT8
      An 8-bit signed integer. ValueLength must be 1.

      MQTYPE_INT16
      A 16-bit signed integer. ValueLength must be 2.

      MQTYPE_INT32
      A 32-bit signed integer. ValueLength must be 4.

      MQTYPE_INT64
      A 64-bit signed integer. ValueLength must be 8.

      MQTYPE_FLOAT32
      A 32-bit floating-point number. ValueLength must be 4.
      Note: this type is not supported with applications using IBM® COBOL for z/OS®.

      MQTYPE_FLOAT64
      A 64-bit floating-point number. ValueLength must be 8.
      Note: this type is not supported with applications using IBM COBOL for z/OS.

      MQTYPE_STRING
      A character string. ValueLength must be zero or greater, or the special value MQVL_NULL_TERMINATED.

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

    ValueLength
    Type: MQLONG - 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 MQTYPE_STRING set:

      MQVL_NULL_TERMINATED
      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 MQTYPE_STRING is not also set.
      Note: The null character used to terminate a string if MQVL_NULL_TERMINATED is set is a null from the character set of the Value.

    Value
    Type: MQBYTExValueLength - 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.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following:

      MQCC_OK
      Successful completion.

      MQCC_FAILED
      Call failed.

    Reason
    Type: MQLONG - output

    The reason code qualifying CompCode.

    If CompCode is MQCC_OK:

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

    If CompCode is MQCC_WARNING:

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

    If CompCode is MQCC_FAILED:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    For detailed information about these codes, see Reason codes.


C invocation

MQSETMP (Hconn, Hmsg, &SetPropOpts, &Name, &PropDesc, Type,
ValueLength, &Value, &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;       /* Connection handle */
MQHMSG   Hmsg;        /* Message handle */
MQSMPO   SetPropOpts; /* Options that control the action of MQSETMP */
MQCHARV  Name;        /* Property name */
MQPD     PropDesc;    /* Property descriptor */
MQLONG   Type;        /* Property data type */
MQLONG   ValueLength; /* Length of property value in Value */
MQBYTE   Value[n];    /* Property value */
MQLONG   CompCode;    /* Completion code */
MQLONG   Reason;      /* Reason code qualifying CompCode */


COBOL invocation

     CALL 'MQSETMP' USING HCONN, HMSG, SETMSGOPTS, NAME, PROPDESC, TYPE, 
                          VALUELENGTH, VALUE, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Message handle
 01  HMSG    PIC S9(18) BINARY.
**   Options that control the action of MQSETMP
 01  SETMSGOPTS.
     COPY CMQSMPOV.
**   Property name
 01  NAME
    COPY CMQCHRVV.
**   Property descriptor
 01  PROPDESC.
     COPY CMQPDV.
**   Property data type
 01  TYPE          PIC S9(9) BINARY.
**   Length of property value in VALUE
 01  VALUELENGTH   PIC S9(9) BINARY.
**   Property value
 01  VALUE         PIC X(n).
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.


PL/I invocation

call MQSETMP (Hconn, Hmsg, SetPropOpts, Name, PropDesc, Type, ValueLength,
              Value, CompCode, Reason);
Declare the parameters as follows: 
dcl Hconn       fixed bin(31);  /* Connection handle */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl SetPropOpts like MQSMPO;    /* Options that control the action of MQSETMP */
dcl Name        like MQCHARV;   /* Property name */
dcl PropDesc    like MQPD;      /* Property descriptor */
dcl Type        fixed bin(31);  /* Property data type */
dcl ValueLength fixed bin(31);  /* Length of property value in Value */
dcl Value       char(n);        /* Property value */
dcl CompCode    fixed bin(31);  /* Completion code */
dcl Reason      fixed bin(31);  /* Reason code qualifying CompCode */


High Level Assembler invocation

         CALL MQSETMP,(HCONN,HMSG,SETMSGHOPTS,NAME,PROPDESC,TYPE,VALUELENGTH,
                VALUE,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN        DS         F     Connection handle
HMSG         DS         D     Message handle
SETMSGOPTS   CMQSMPOA   ,     Options that control the action of MQSETMP
NAME         CMQCHRVA   ,     Property name
PROPDESC     CMQPDA     ,     Property descriptor
TYPE         DS         F     Property data type
VALUELENGTH  DS         F     Length of property value in VALUE
VALUE        DS         CL(n) Property value
COMPCODE     DS         F     Completion code
REASON       DS         F     Reason code qualifying COMPCODE