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.
- MQTYPE_FLOAT64
- A 64-bit floating-point number. ValueLength must be 8.
- 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.
- 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 Messages and reason codes.
C invocation
MQSETMP (Hconn, Hmsg, &SetPropOpts, &Name, &PropDesc, Type,
ValueLength, &Value, &CompCode, &Reason);
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.
** 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);
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)
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