MQOD (Object descriptor) on IBM i

The MQOD structure is used to specify an object by name.

Overview

Purpose: The following types of object are valid:

Queue or distribution list
Namelist
Process definition
Queue manager
Topic

The structure is an input/output parameter on the MQOPEN and MQPUT1 calls.

Version: The current version of MQOD is ODVER4. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.

The COPY file provided contains the most recent version of MQOD that is supported by the environment, but with the initial value of the ODVER field set to ODVER1. To use fields that are not present in the version-1 structure, the application must set the ODVER field to the version number of the version required.

To open a distribution list, ODVER must be ODVER2 or greater.

Character set and encoding: Data in MQOD must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT. However, if the application is running as an IBM® MQ client, the structure must be in the character set and encoding of the client.

Fields
Initial values
RPG declaration

Fields

The MQOD structure contains the following fields; the fields are described in alphabetical order:

ODASI (40-byte bit string)

Alternate security identifier.

This is a security identifier that is passed with the ODAU to the authorization service to allow appropriate authorization checks to be performed. ODASI is used only if:

OOALTU is specified on the MQOPEN call, or
PMALTU is specified on the MQPUT1 call,

and the ODAU field is not entirely blank up to the first null character or the end of the field.

The ODASI field has the following structure:

The first byte is a binary integer containing the length of the significant data that follows; the value excludes the length byte itself. If no security identifier is present, the length is zero.
The second byte indicates the type of security identifier that is present; the following values are possible:

SITWNT

Windows security identifier.

SITNON

No security identifier.
The third and subsequent bytes up to the length defined by the first byte contain the security identifier itself.
Remaining bytes in the field are set to binary zero.

The following special value may be used:

SINONE: No security identifier specified.
The value is binary zero for the length of the field.

This is an input field. The length of this field is given by LNSCID. The initial value of this field is SINONE. This field is ignored if ODVER is less than ODVER3.

ODAU (12-byte character string)

Alternate user identifier.

If OOALTU is specified for the MQOPEN call, or PMALTU for the MQPUT1 call, this field contains an alternate user identifier that is to be used to check the authorization for the open, in place of the user identifier that the application is currently running under. Some checks, however, are still carried out with the current user identifier (for example, context checks).

If OOALTU and PMALTU are not specified and this field is entirely blank up to the first null character or the end of the field, the open can succeed only if no user authorization is needed to open this object with the options specified.

If neither OOALTU nor PMALTU is specified, this field is ignored.

This is an input field. The length of this field is given by LNUID. The initial value of this field is 12 blank characters.

ODDN (48-byte character string)

Dynamic queue name.

This is the name of a dynamic queue that is to be created by the MQOPEN call. This is of relevance only when ODON specifies the name of a model queue; in all other cases ODDN is ignored.

The characters that are valid in the name are the same as those for ODON, except that an asterisk is also valid. A name that is blank (or one in which only blanks are shown before the first null character) is not valid if ODON is the name of a model queue.

If the last nonblank character in the name is an asterisk ( *), the queue manager replaces the asterisk with a string of characters that guarantees that the name generated for the queue is unique at the local queue manager. To allow a sufficient number of characters for this, the asterisk is valid only in positions 1 through 33. There must be no characters other than blanks or a null character following the asterisk.

It is valid for the asterisk to occur in the first character position, in which case the name consists solely of the characters generated by the queue manager.

This is an input field. The length of this field is given by LNQN. The initial value of this field is 'AMQ.*', padded with blanks.

ODIDC (10-digit signed integer)

Number of queues that failed to open.

This is the number of queues in the distribution list that failed to open successfully. If present, this field is also set when opening a single queue which is not in a distribution list.

Note: If present, this field is set only if the CMPCOD parameter on the MQOPEN or MQPUT1 call is CCOK or CCWARN; it is not set if the CMPCOD parameter is CCFAIL.

This is an output field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODKDC (10-digit signed integer)

Number of local queues opened successfully.

This is the number of queues in the distribution list that resolve to local queues and that were opened successfully. The count does not include queues that resolve to remote queues (even though a local transmission queue is used initially to store the message). If present, this field is also set when opening a single queue which is not in a distribution list.

This is an output field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODMN (48-byte character string)

Object queue manager name.

This is the name of the queue manager on which the ODON object is defined. The characters that are valid in the name are the same as those for ODON (see previously). A name that is entirely blank up to the first null character or the end of the field denotes the queue manager to which the application is connected (the local queue manager).

The following points apply to the types of object indicated:

If ODOT is OTTOP, OTNLST, OTPRO, or OTQM, ODMN must be blank or the name of the local queue manager.
If ODON is the name of a model queue, the queue manager creates a dynamic queue with the attributes of the model queue, and returns in the ODMN field the name of the queue manager on which the queue is created; this is the name of the local queue manager. A model queue can be specified only on the MQOPEN call; a model queue is not valid on the MQPUT1 call.
If ODON is the name of a cluster queue, and ODMN is blank, the actual destination of messages sent using the queue handle returned by the MQOPEN call is chosen by the queue manager (or cluster workload exit, if one is installed) as follows:
- If OOBNDO is specified, the queue manager selects an instance of the cluster queue during the processing of the MQOPEN call, and all messages put using this queue handle are sent to that instance.
- If OOBNDN is specified, the queue manager may choose a different instance of the destination queue (residing on a different queue manager in the cluster) for each successive MQPUT call that uses this queue handle.
If the application needs to send a message to a specific instance of a cluster queue (that is, a queue instance that resides on a particular queue manager in the cluster), the application should specify the name of that queue manager in the ODMN field. This forces the local queue manager to send the message to the specified destination queue manager.
If the object being opened is a distribution list (that is, ODREC is greater than zero), ODMN must be blank or the null string. If this condition is not satisfied, the call fails with reason code RC2153.

This is an input/output field for the MQOPEN call when ODON is the name of a model queue, and an input-only field in all other cases. The length of this field is given by LNQMN. The initial value of this field is 48 blank characters.

ODON (48-byte character string)

Object name.

This is the local name of the object as defined on the queue manager identified by ODMN. The name can contain the following characters:

Uppercase alphabetic characters (A - Z)
Lowercase alphabetic characters (a - z)
Numeric digits (0 - 9)
Period (.), forward slash (/), underscore (_), percent (%)

The name must not contain leading or embedded blanks, but may contain trailing blanks. A null character can be used to indicate the end of significant data in the name; the null and any characters following it are treated as blanks. The following restrictions apply in the environments indicated:

On systems that use EBCDIC Katakana, lowercase characters cannot be used.
On IBM i, names containing lowercase characters, forward slash, or percent, must be enclosed in quotation marks when specified on commands. These quotation marks must not be specified for names that occur as fields in structures or as parameters on calls.

The following points apply to the types of object indicated:

If ODON is the name of a model queue, the queue manager creates a dynamic queue with the attributes of the model queue, and returns in the ODON field the name of the queue created. A model queue can be specified only on the MQOPEN call; a model queue is not valid on the MQPUT1 call.
If the object being opened is a distribution list (that is, ODREC is present and greater than zero), ODON must be blank or the null string. If this condition is not satisfied, the call fails with reason code RC2152.
If ODOT is OTQM, special rules apply; in this case the name must be entirely blank up to the first null character or the end of the field.
If ODON is the name of an alias queue with TARGTYPE(TOPIC), a security check is first made on the named alias queue, as is normal for the use of alias queues. If this security check is successful, this MQOPEN call will continue and behaves like an MQOPEN of an OTTOP, including making a security check against the administrative topic object.

This is an input/output field for the MQOPEN call when ODON is the name of a model queue, and an input-only field in all other cases. The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

The full topic name can be built from two different fields: ODON and ODOS. For details of how these two fields are used, see Combining topic strings.

ODORO (10-digit signed integer)

Offset of first object record from start of MQOD.

This is the offset in bytes of the first MQOR object record from the start of the MQOD structure. The offset can be positive or negative. ODORO is used only when a distribution list is being opened. The field is ignored if ODREC is zero.

When a distribution list is being opened, an array of one or more MQOR object records must be provided in order to specify the names of the destination queues in the distribution list. This can be done in one of two ways:

By using the offset field ODORO
In this case, the application should declare its own structure containing an MQOD followed by the array of MQOR records (with as many array elements as are needed), and set ODORO to the offset of the first element in the array from the start of the MQOD. Care must be taken to ensure that this offset is correct.
By using the pointer field ODORP
In this case, the application can declare the array of MQOR structures separately from the MQOD structure, and set ODORP to the address of the array.

Whichever technique is chosen, one of ODORO and ODORP must be used; the call fails with reason code RC2155 if both are zero, or both are nonzero.

This is an input field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODORP (pointer)

Address of first object record.

This is the address of the first MQOR object record. ODORP is used only when a distribution list is being opened. The field is ignored if ODREC is zero.

This is an input field. The initial value of this field is the null pointer. Either ODORP or ODORO can be used to specify the object records, but not both; see the description of the ODORO field previously for details. If ODORP is not used, it must be set to the null pointer or null bytes. This field is ignored if ODVER is less than ODVER2.

ODOS (MQCHARV)

ODOS specifies the long object name to be used.

This field is referenced only for certain values of ODOT. See the description of ODOT for details of which values indicate that this field is used.

If ODOS is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2441.

This is an input field. The initial values of the fields in this structure are the same as those in the MQCHARV structure.

The full topic name can be built from two different fields: ODON and ODOS. For details of how these two fields are used, see Combining topic strings. This field is ignored if ODVER is less than ODVER4.

ODOT (10-digit signed integer)

Object type.

Type of object being named in ODON. Possible values are:

OTQ: Queue. The name of the object is found in ODON.
OTNLST: Namelist. The name of the object is found in ODON.
OTPRO: Process definition. The name of the object is found in ODON.
OTQM: Queue manager. The name of the object is found in ODON.
OTTOP: Topic. The full topic name can be built from two different fields: ODON and ODOS.; For details of how those two fields are used, see Combining topic strings.; If the object identified by the ODON field cannot be found, the call will fail with reason code RC2425 even if there is a string specified in ODOS.

This is always an input field. The initial value of this field is OTQ.

ODREC (10-digit signed integer)

Number of object records present.

This is the number of MQOR object records that have been provided by the application. If this number is greater than zero, it indicates that a distribution list is being opened, with ODREC being the number of destination queues in the list. It is valid for a distribution list to contain only one destination.

The value of ODREC must not be less than zero, and if it is greater than zero ODOT must be OTQ; the call fails with reason code RC2154 if these conditions are not satisfied.

This is an input field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODRMN (48-byte character string)

Resolved queue manager name.

This is the name of the destination queue manager after name resolution has been performed by the local queue manager. The name returned is the name of the queue manager that owns the queue identified by ODRQN. ODRMN can be the name of the local queue manager.

If ODRQN is a shared queue that is owned by the queue sharing group to which the local queue manager belongs, ODRMN is the name of the queue sharing group. If the queue is owned by some other queue sharing group, ODRQN can be the name of the queue sharing group or the name of a queue manager that is a member of the queue sharing group (the nature of the value returned is determined by the queue definitions that exist at the local queue manager).

A nonblank value is returned only if the object is a single queue opened for browse, input, or output (or any combination). If the object opened is any of the following, ODRMN is set to blanks:

Not a queue
A queue, but not opened for browse, input, or output
A cluster queue with OOBNDN specified (or with OOBNDQ in effect when the DefBind queue attribute has the value BNDNOT)
A distribution list

This is an output field. The length of this field is given by LNQN. The initial value of this field is the null string in C, and 48 blank characters in other programming languages. This field is ignored if ODVER is less than ODVER3.

ODRO (MQCHARV)

ODRO is the long object name after the queue manager resolves the name provided in ODON.

This field is returned only for certain types of objects, topics, and queue aliases which reference a topic object.

If the long object name is provided in ODOS and nothing is provided in ODON, the value returned in this field is the same as provided in ODOS.

If this field is omitted (that is ODRO.VSBufSize is zero), the ODRO is not returned, but the length is returned in ODRO.VSLength. If the length is shorter than the full ODRO then it is truncated and returns as many of the rightmost characters as can fit in the provided length.

If ODRO is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2520. This field is ignored if ODVER is less than ODVER4.

ODRQN (48-byte character string)

Resolved queue name.

This is the name of the destination queue after name resolution has been performed by the local queue manager. The name returned is the name of a queue that exists on the queue manager identified by ODRMN.

A nonblank value is returned only if the object is a single queue opened for browse, input, or output (or any combination). If the object opened is any of the following, ODRQN is set to blanks:

Not a queue
A queue, but not opened for browse, input, or output
A distribution list
An alias queue that references a topic object (refer to ODRO (MQCHARV) instead)

ODRRO (10-digit signed integer)

Offset of first response record from start of MQOD.

This is the offset in bytes of the first MQRR response record from the start of the MQOD structure. The offset can be positive or negative. ODRRO is used only when a distribution list is being opened. The field is ignored if ODREC is zero.

When a distribution list is being opened, an array of one or more MQRR response records can be provided in order to identify the queues that failed to open (RRCC field in MQRR), and the reason for each failure (RRREA field in MQRR). The data is returned in the array of response records in the same order as the queue names occur in the array of object records. The queue manager sets the response records only when the outcome of the call is mixed (that is, some queues were opened successfully while others failed, or all failed but for differing reasons); reason code RC2136 from the call indicates this case. If the same reason code applies to all queues, that reason is returned in the REASON parameter of the MQOPEN or MQPUT1 call, and the response records are not set. Response records are optional, but if they are supplied there must be ODREC of them.

The response records can be provided in the same way as the object records, either by specifying an offset in ODRRO, or by specifying an address in ODRRP ; see the description of ODORO previously for details of how to do this. However, no more than one of ODRRO and ODRRP can be used; the call fails with reason code RC2156 if both are nonzero.

For the MQPUT1 call, these response records are used to return information about errors that occur when the message is sent to the queues in the distribution list, as well as errors that occur when the queues are opened. The completion code and reason code from the put operation for a queue replace those from the open operation for that queue only if the completion code from the latter was CCOK or CCWARN.

This is an input field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODRRP (pointer)

Address of first response record.

This is the address of the first MQRR response record. ODRRP is used only when a distribution list is being opened. The field is ignored if ODREC is zero.

Either ODRRP or ODRRO can be used to specify the response records, but not both; see the previous description of the ODRRO field for details. If ODRRP is not used, it must be set to the null pointer or null bytes.

This is an input field. The initial value of this field is the null pointer. This field is ignored if ODVER is less than ODVER2.

ODSID (4-byte character string)

Structure identifier.

The value must be:

ODSIDV: Identifier for object descriptor structure.

This is always an input field. The initial value of this field is ODSIDV.

ODSS (MQCHARV)

ODSS contains the string used to provide the selection criteria used when retrieving messages off a queue.

ODSS must not be provided in the following cases:

If ODOT is not OTQ
If the queue being opened is not being opened using one of the input options, OOINP*

If ODSS is provided in these cases, the call fails with reason code RC2516.

If ODSS is specified incorrectly, according to the description of how to use the MQCHARV structure, or if it exceeds the maximum length, the call fails with reason code RC2519. This field is ignored if ODVER is less than ODVER4.

ODUDC (10-digit signed integer)

Number of remote queues opened successfully

This is the number of queues in the distribution list that resolve to remote queues and that were opened successfully. If present, this field is also set when opening a single queue which is not in a distribution list.

This is an output field. The initial value of this field is 0. This field is ignored if ODVER is less than ODVER2.

ODVER (10-digit signed integer)

Structure version number.

The value must be one of the following:

ODVER1: Version-1 object descriptor structure.
ODVER2: Version-2 object descriptor structure.
ODVER3: Version-3 object descriptor structure.
ODVER4: Version-4 object descriptor structure.

Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions of the fields. The following constant specifies the version number of the current version:

ODVERC: Current version of object descriptor structure.

This is always an input field. The initial value of this field is ODVER1.

Initial values

Table 1. Initial values of fields in MQOD
Field name	Name of constant	Value of constant
`ODSID`	ODSIDV	`'OD¬¬'`
`ODVER`	ODVER1	`1`
`ODOT`	OTQ	`1`
`ODON`	None	Blanks
`ODMN`	None	Blanks
`ODDN`	None	`'AMQ.*'`
`ODAU`	None	Blanks
`ODREC`	None	`0`
`ODKDC`	None	`0`
`ODUDC`	None	`0`
`ODIDC`	None	`0`
`ODORO`	None	`0`
`ODRRO`	None	`0`
`ODORP`	None	Null pointer or null bytes
`ODRRP`	None	Null pointer or null bytes
`ODASI`	SINONE	Nulls
`ODRQN`	None	Blanks
`ODRMN`	None	Blanks
`ODOS`	As defined for MQCHARV	As defined for MQCHARV
`ODRO`	As provided in `ODOS`	As provided in `ODOS`
`ODSS`	None	Blanks
Notes: The symbol `¬` represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQOD Structure
     D*
     D*
     D* Structure identifier 
     D  ODSID                  1      4    INZ('OD  ')
     D*
     D* Structure version number 
     D  ODVER                  5      8I 0 INZ(1)
     D*
     D* Object type 
     D  ODOT                   9     12I 0 INZ(1)
     D*
     D* Object name 
     D  ODON                  13     60    INZ
     D*
     D* Object queue manager name 
     D  ODMN                  61    108    INZ
     D*
     D* Dynamic queue name 
     D  ODDN                 109    156    INZ('AMQ.*')
     D*
     D* Alternate user identifier 
     D  ODAU                 157    168    INZ
     D*
     ** Number of object records
     D* present 
     D  ODREC                169    172I 0 INZ(0)
     D*
     ** Number of local queues opened
     D* successfully 
     D  ODKDC                173    176I 0 INZ(0)
     D*
     ** Number of remote queues opened
     D* successfully 
     D  ODUDC                177    180I 0 INZ(0)
     D*
     ** Number of queues that failed to
     D* open 
     D  ODIDC                181    184I 0 INZ(0)
     D*
     ** Offset of first object record
     D* from start of MQOD 
     D  ODORO                185    188I 0 INZ(0)
     D*
     ** Offset of first response record
     D* from start of MQOD 
     D  ODRRO                189    192I 0 INZ(0)
     D*
     D* Address of first object record 
     D  ODORP                193    208*   INZ(*NULL)
     D*
     ** Address of first response
     D* record 
     D  ODRRP                209    224*   INZ(*NULL)
     D*
     D* Alternate security identifier 
     D  ODASI                225    264    INZ(X'00000000000000000-
     D                                     0000000000000000000000000-
     D                                     0000000000000000000000000-
     D                                     0000000000000')
     D*
     D* Resolved queue name 
     D  ODRQN                265    312    INZ
     D*
     D* Resolved queue manager name 
     D  ODRMN                313    360    INZ
     D*
     D* reserved field 
     D  ODRE1                361    364I 0 INZ(0)
     D*
     D* reserved field 
     D  ODRS2                365    368I 0 INZ(0)
     D*
     D* Object long name 
     D* Address of variable length string 
     D  ODOSCHRP             369    384*   INZ(*NULL)
     D* Offset of variable length string 
     D  ODOSCHRO             385    388I 0 INZ(0)
     D* Size of buffer 
     D  ODOSVSBS             389    392I 0 INZ(-1)
     D* Length of variable length string 
     D  ODOSCHRL             393    396I 0 INZ(0)
     D* CCSID of variable length string 
     D  ODOSCHRC             397    400I 0 INZ(-3)
     D*
     D* Message Selector 
     D* Address of variable length string 
     D  ODSSCHRP             401    416*   INZ(*NULL)
     D* Offset of variable length string 
     D  ODSSCHRO             417    420I 0 INZ(0)
     D* Size of buffer 
     D  ODSSVSBS             421    424I 0 INZ(-1)
     D* Length of variable length string 
     D  ODSSCHRL             425    428I 0 INZ(0)
     D* CCSID of variable length string 
     D  ODSSCHRC             429    432I 0 INZ(-3)
     D*
     D* Resolved long object name
     D* Address of variable length string 
     D  ODRSOCHRP            433    448*   INZ(*NULL)
     D* Offset of variable length string 
     D  ODRSOCHRO            449    452I 0 INZ(0)
     D* Size of buffer 
     D  ODRSOVSBS            453    456I 0 INZ(-1)
     D* Length of variable length string 
     D  ODRSOCHRL            457    460I 0 INZ(0)
     D* CCSID of variable length string 
     D  ODRSOCHRC            461    464I 0 INZ(-3)
     D*
     D* Alias queue resolved object type 
     D  ODRT                 465    468I 0 INZ(0)