Get Opaque Byte Sequence

Convenience Method

Declaration

TibrvStatus getOpaque(
    const char*    fieldName,
    void*&         value,
    tibrv_u32&     length,
    tibrv_u16      fieldId=0);

Purpose

Get the value of a field as an opaque byte sequence.

Remarks

This convenience method retrieves a field and extracts its data.

Since it is not possible to convert any other datatype to an opaque byte sequence, the field must already contain an opaque byte sequence. Otherwise, the method returns TIBRV_CONVERSION_FAILED.

Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data.

This method produces values that are read-only snapshots of the field data (see Pointer Snapshot). Programs must not modify the value sequence.

Parameter	Description
fieldName	Get a field with this name.
length	The program supplies a variable in this parameter, and the method stores the length of the opaque byte sequence in that variable.
value	The program supplies a variable in this parameter, and the method stores a pointer to the field value in that variable.
fieldId	Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.

See Also

Validity of Data Extracted From Message Fields

Field Names and Field Identifiers