6
DBMS_MGWMSG

DBMS_MGWMSG provides object types--used by the canonical message types to convert message bodies--and helper methods, constants, and subprograms for working with the Messaging Gateway message types. The package and object types are owned by SYS.

The following topics are discussed in this chapter:

• Summary of DBMS_MGWMSG Object Types and Methods

• DBMS_MGWMSG Constants

• Summary of DBMS_MGWMSG Subprograms

---

Summary of DBMS_MGWMSG Object Types and Methods

Table 6-1 DBMS_MGWMSG Object Types and Methods

Object Type	Description
MGW_NAME_VALUE_T Type	Specifies a named value.
MGW_NAME_VALUE_T.CONSTRUCT Method	Constructs a new MGW_NAME_VALUE_T instance.
MGW_NAME_VALUE_T.CONSTRUCT_<TYPE> Methods	Constructs a new MGW_NAME_VALUE_T instance initialized with the value of a specific type.
MGW_NAME_TYPE_ARRAY_T Type	Specifies an array of name-value pairs.
MGW_TEXT_VALUE_T Type	Specifies a TEXT value.
MGW_TEXT_VALUE_T.CONSTRUCT Method	Constructs a new MGW_TEXT_VALUE_T instance.
MGW_RAW_VALUE_T Type	Specifies a RAW value.
MGW_RAW_VALUE_T.CONSTRUCT Method	Constructs a new MGW_RAW_VALUE_T instance.
MGW_BASIC_MSG_T Type	A canonical type for a basic TEXT or RAW message.
MGW_BASIC_MSG_T.CONSTRUCT Method	Constructs a new MGW_BASIC_MSG_T instance.

---

MGW_NAME_VALUE_T Type

This type specifies a named value. The name and type attributes and one of the < >_value attributes are typically nonnull.

Syntax

TYPE SYS.MGW_NAME_VALUE_T IS OBJECT
   name               VARCHAR2(250),
   type               INTEGER,
   integer_value      INTEGER,
   number_value       NUMBER,
   text_value         VARCHAR2(4000),
   raw_value          RAW(2000),
   date_value         DATE);

Attributes

Table 6-2 MGW_NAME_VALUE_T Attributes

Attribute	Description
name	Name associated with the value.
type	Value type. Refer to the DBMS_MGWMSG.< >_VALUE constants in Table 6-7. This indicates which Java datatype and class are associated with the value. It also indicates which attribute stores the value.
integer_value	Stores a numeric integer value.
number_value	Stores a numeric float or large integer value.
text_value	Stores a TEXT value.
raw_value	Stores a RAW (bytes) value.
date_value	Stores a date value.

Type-Attribute Mapping

Table 6-3 shows the mapping between the value type and the attribute used to store the value.

Table 6-3 Type-Attribute Mapping

Type	Value Stored in Attribute
DBMS_MGWMSG.TEXT_VALUE	text_value
DBMS_MGWMSG.RAW_VALUE	raw_value
DBMS_MGWMSG.BOOLEAN_VALUE	integer_value
DBMS_MGWMSG.BYTE_VALUE	integer_value
DBMS_MGWMSG.SHORT_VALUE	integer_value
DBMS_MGWMSG.INTEGER_VALUE	integer_value
DBMS_MGWMSG.LONG_VALUE	number_value
DBMS_MGWMSG.FLOAT_VALUE	number_value
DBMS_MGWMSG.DOUBLE_VALUE	number_value
DBMS_MGWMSG.DATE_VALUE	date_value

---

MGW_NAME_VALUE_T.CONSTRUCT Method

This method constructs a new MGW_NAME_VALUE_T instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_NAME_VALUE_T;

---

MGW_NAME_VALUE_T.CONSTRUCT_<TYPE> Methods

These methods construct a new MGW_NAME_VALUE_T instance initialized with the value of a specific type. Each method sets the name and type attributes and one of the < >_value attributes, as shown in the mappings in Table 6-3.

Syntax

STATIC FUNCTION CONSTRUCT_BOOLEAN (
   name   IN VARCHAR2,
   value  IN INTEGER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_BYTE (
   name   IN VARCHAR2,
   value  IN INTEGER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_SHORT (
   name   IN VARCHAR2,
   value  IN INTEGER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_INTEGER (
   name   IN VARCHAR2,
   value  IN INTEGER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_LONG (
   name   IN VARCHAR2,
   value  IN NUMBER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_FLOAT (
   name   IN VARCHAR2,
   value  IN NUMBER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_DOUBLE (
   name   IN VARCHAR2,
   value  IN NUMBER )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_TEXT (
   name   IN VARCHAR2,
   value  IN VARCHAR2 )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_RAW (
   name  IN VARCHAR2,
   alue  IN RAW )
RETURN SYS.MGW_NAME_VALUE_T,

STATIC FUNCTION CONSTRUCT_DATE (
   name   IN VARCHAR2,
   value  IN DATE )
RETURN SYS.MGW_NAME_VALUE_T );

Usage Notes

The construct_boolean method sets the value to either DBMS_MGWMSG.BOOLEAN_TRUE or DBMS_MGWMSG.BOOLEAN_FALSE.

---

MGW_NAME_TYPE_ARRAY_T Type

This type specifies an array of name-value pairs. An object of MGW_NAME_VALUE_ARRAY_T type can have up to 1024 elements.

Syntax

TYPE SYS.MGW_NAME_VALUE_ARRAY_T AS VARRAY (1024) OF SYS.MGW_NAME_VALUE_T;

---

MGW_TEXT_VALUE_T Type

This type specifies a TEXT value. It can store a large value as a CLOB or a smaller value (size <= 4000) as VARCHAR2. Only one of the < >_ value attributes should be set.

Syntax

TYPE SYS.MGW_TEXT_VALUE_T IS OBJECT
   small_value VARCHAR2(4000),
   large_value CLOB);

Attributes

Table 6-4 MGW_TEXT_VALUE_T Attributes

Attribute	Description
small_value	Small TEXT value. Used for values <= 4000.
large_value	Large TEXT value. Used when the value is too large for the small_value attribute.

---

MGW_TEXT_VALUE_T.CONSTRUCT Method

This method constructs a new MGW_TEXT_VALUE_T instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_TEXT_VALUE_T;

---

MGW_RAW_VALUE_T Type

This type specifies a RAW value. This type can store a large value as a BLOB or a smaller value (size <= 2000) as RAW. Only one of the < >_value attributes should be set.

Syntax

TYPE SYS.MGW_RAW_VALUE_T IS OBJECT(
   small_value RAW(2000),
   large_value BLOB);

Attributes

Table 6-5 MGW_RAW_VALUE_T Attributes

Attribute	Description
small_value	Small RAW (bytes) value <= 2000.
large_value	Large RAW value. Used when the value is too large for the small_value attribute.

---

MGW_RAW_VALUE_T.CONSTRUCT Method

This method constructs a new MGW_RAW_VALUE_T instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_RAW_VALUE_T;

---

MGW_BASIC_MSG_T Type

This is a canonical type for a basic TEXT or RAW message. Only a single TEXT or RAW value is typically set. An object of this type should not have both TEXT and RAW set to a nonnull value at the same time.

Syntax

TYPE SYS.MGW_BASIC_MSG_T IS OBJECT
   header     SYS.MGW_NAME_VALUE_ARRAY_T,
   text_body  SYS.MGW_TEXT_VALUE_T,
   raw_body   SYS.MGW_RAW_VALUE_T);

Attributes

Table 6-6 MGW_BASIC_MSG_T Attributes

Attribute	Description
header	Message header information as an array of name-value pairs.
text_body	Message body for a TEXT message.
raw_body	Message body for a RAW (bytes) message.

---

MGW_BASIC_MSG_T.CONSTRUCT Method

This method constructs a new MGW_BASIC_MSG_T instance. All attributes are assigned a value of NULL.

Syntax

STATIC FUNCTION CONSTRUCT
RETURN SYS.MGW_BASIC_MSG_T;

---

DBMS_MGWMSG Constants

Table 6-7 DBMS_MGWMSG Constants

Value Types--Constants representing the type of value for a SYS.MGW_NAME_VALUE_T object
TEXT_VALUE	CONSTANT BINARY_INTEGER := 1;
RAW_VALUE	CONSTANT BINARY_INTEGER := 2;
BOOLEAN_VALUE	CONSTANT BINARY_INTEGER := 3;
BYTE_VALUE	CONSTANT BINARY_INTEGER := 4;
SHORT_VALUE	CONSTANT BINARY_INTEGER := 5;
INTEGER_VALUE	CONSTANT BINARY_INTEGER := 6;
LONG_VALUE	CONSTANT BINARY_INTEGER := 7;
FLOAT_VALUE	CONSTANT BINARY_INTEGER := 8;
DOUBLE_VALUE	CONSTANT BINARY_INTEGER := 9;
DATE_VALUE	CONSTANT BINARY_INTEGER := 10;
Boolean Value--Constants representing a Boolean (TRUE/FALSE) as a numeric value
BOOLEAN_FALSE	CONSTANT BINARY_INTEGER := 0;
BOOLEAN_TRUE	CONSTANT BINARY_INTEGER := 1;
Case comparisons
CASE_SENSITIVE	CONSTANT BINARY_INTEGER := 0;
CASE_INSENSITIVE	CONSTANT BINARY_INTEGER := 1;

---

Summary of DBMS_MGWMSG Subprograms

Table 6-8 DBMS_MGWMSG Subprograms

Subprogram	Description
NVARRAY_ADD Procedure	Appends a name-value element to the end of a name-value array.
NVARRAY_GET Function	Gets the name-value element of the name you specify in p_name from a name-value array.
NVARRAY_GET_BOOLEAN Function	Gets the value of the name-value array element that you specify in p_name and with the BOOLEAN_VALUE value type.
NVARRAY_GET_BYTE Function	Gets the value of the name-value array element that you specify in p_name and with the BYTE_VALUE value type.
NVARRAY_GET_SHORT Function	Gets the value of the name-value array element that you specify in p_name and with the SHORT_VALUE value type.
NVARRAY_GET_INTEGER Function	Gets the value of the name-value array element that you specify in p_name and with the INTEGER_VALUE value type.
NVARRAY_GET_LONG Function	Gets the value of the name-value array element that you specify in p_name and with the LONG_VALUE value type.
NVARRAY_GET_FLOAT Function	Gets the value of the name-value array element that you specify in p_name and with the FLOAT_VALUE value type.
NVARRAY_GET_DOUBLE Function	Gets the value of the name-value array element that you specify in p_name and with the DOUBLE_VALUE value type.
NVARRAY_GET_TEXT Function	Gets the value of the name-value array element that you specify in p_name and with the TEXT_VALUE value type.
NVARRAY_GET_RAW Function	Gets the value of the name-value array element that you specify in p_name and with the RAW_VALUE value type.
NVARRAY_GET_DATE Function	Gets the value of the name-value array element that you specify in p_name and with the DATE_VALUE value type.
NVARRAY_FIND_NAME Function	Searches a name-value array for the element with the name you specify in p_name.
NVARRAY_FIND_NAME_TYPE Function	Searches a name-value array for an element with the name and value type you specify.

---

NVARRAY_ADD Procedure

This procedure appends a name-value element to the end of a name-value array.

Syntax

DBMS_MGWMSG.NVARRAY_ADD (
   p_array  IN OUT SYS.MGW_NAME_VALUE_ARRAY_T,
   p_value  IN     SYS.MGW_NAME_VALUE_T );

Parameters

Table 6-9 NVARRAY_ADD Procedure Parameters

Parameter	Description
p_array	The name-value array instance. On input, the array to modify. If NULL, a new array is created. On output, the modified array.
p_value	The value to add. If NULL, p_array is not changed.

---

NVARRAY_GET Function

This function gets the name-value element of the name you specify in p_name from a name-value array.

Syntax

DBMS_MGWMSG.NVARRAY_GET (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN SYS.MGW_NAME_VALUE_T;

Parameters

Table 6-10 NVARAAY_GET Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The matching element, or NULL if the specified name is not found.

---

NVARRAY_GET_BOOLEAN Function

This function gets the value of the name-value array element that you specify in p_name and with the BOOLEAN_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_BOOLEAN (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN INTEGER;

Parameters

Table 6-11 NVARRAY_GET_BOOLEAN Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_BYTE Function

This function gets the value of the name-value array element that you specify in p_name and with the BYTE_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_BYTE (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN INTEGER;

Parameters

Table 6-12 NVARRAY_GET_BYTE Function

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_SHORT Function

This function gets the value of the name-value array element that you specify in p_name and with the SHORT_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_SHORT (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN INTEGER;

Parameters

Table 6-13 NVARRAY_GET_SHORT Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_INTEGER Function

This function gets the value of the name-value array element that you specify in p_name and with the INTEGER_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_INTEGER (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T, 
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )  
RETURN INTEGER;

Parameters

Table 6-14 NVARRAY_GET_INTEGER Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_LONG Function

This function gets the value of the name-value array element that you specify in p_name and with the LONG_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_LONG (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN NUMBER;

Parameters

Table 6-15 NVARRAY_GET_LONG Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_FLOAT Function

This function gets the value of the name-value array element that you specify in p_name and with the FLOAT_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_FLOAT (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN NUMBER;

Parameters

Table 6-16 NVARRAY_GET_FLOAT Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_DOUBLE Function

This function gets the value of the name-value array element that you specify in p_name and with the DOUBLE_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_DOUBLE (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN NUMBER;

Parameters

Table 6-17 NVARRAY_GET_DOUBLE Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_TEXT Function

This function gets the value of the name-value array element that you specify in p_name and with the TEXT_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_TEXT (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN VARCHAR2;

Parameters

Table 6-18 NVARRAY_GET_TEXT Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_RAW Function

This function gets the value of the name-value array element that you specify in p_name and with the RAW_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_RAW (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN RAW;

Parameters

Table 6-19 NVARRAY_GET_RAW Function Parameters

Parameter	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_GET_DATE Function

This function gets the value of the name-value array element that you specify in p_name and with the DATE_VALUE value type.

Syntax

DBMS_MGWMSG.NVARRAY_GET_DATE (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN DATE;

Parameters

Table 6-20 NVARRAY_GET_DATE Function Parameters

Parameters	Description
p_array	The name-value array.
p_name	The value name.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

The value, or NULL if the specified name is not found or if a type mismatch exists.

---

NVARRAY_FIND_NAME Function

This function searches a name-value array for the element with the name you specify in p_name.

Syntax

DBMS_MGWMSG.NVARRAY_FIND_NAME (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN BINARY_INTEGER;

Parameters

Table 6-21 NVARRAY_FIND_NAME Function Parameters

Parameters	Description
p_array	The name-value array to search.
p_name	The name to find.
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

• A positive integer that is the array index of the matching element

• 0 if the specified name is not found

---

NVARRAY_FIND_NAME_TYPE Function

This function searches a name-value array for an element with the name and value type you specify.

Syntax

DBMS_MGWMSG.NVARRAY_FIND_NAME_TYPE (
   p_array    IN SYS.MGW_NAME_VALUE_ARRAY_T,
   p_name     IN VARCHAR2,
   p_type     IN BINARY_INTEGER
   p_compare  IN BINARY_INTEGER DEFAULT CASE_SENSITIVE )
RETURN BINARY_INTEGER;

Parameters

Table 6-22 NVARRAY_FIND_NAME_TYPE Function Parameters

Parameter	Description
p_array	The name-value array to search.
p_name	The name to find.
p_type	The value type. Refer to the value type constants in Table 6-7 .
p_compare	Name comparison method. Valid values: CASE_SENSITIVE, CASE_INSENSITIVE

Returns

• A positive integer that is the array index of the matching element

• 0 if the specified name is not found

• -1 if the specified name is found but a type mismatch exists