Value Binding Run Time: Before Stored Procedure Invocation

Oracle JCA Adapter for Database 9-101 X A100A C xsi:nil=true X The value 100 is assigned to attribute A, and null is assigned to attributes B and C. Because there is no element in the instance XML for attribute B, a null value is assigned. The second case, X, behaves differently if the type of X is user-defined. Rather than assigning null to X, an initialized instance of the user-defined type is created and bound instead. In the preceding VARRAY example, if X or XX is specified, then the value bound to X is an empty instance of the VARRAY. In PLSQL, this is equivalent to calling the type constructor and assigning the value to X. For example, X := ARRAY; Similarly, in the preceding OBJECT example, an initialized instance of OBJ, whose attribute values have all been null assigned, is bound to X. Similar to the VARRAY case, this is equivalent to calling the type constructor. For example, X := OBJNULL, NULL, NULL; To specifically assign a null value to X when the type of X is user-defined, add the xsi:nil attribute to the element in the XML file, as in X xsi:nil=true

9.7.4.2 Data Type Conversions

This section describes the conversion of data types such as CLOB, DATE, TIMESTAMP, and binary data types including RAW, LONG RAW and BLOB, as well as similar data types supported by third-party databases. Microsoft SQL Server, IBM DB2, AS400, and MySQL support binding various forms of binary and date data types to parameters of a stored procedure, as summarized in Table 9–19 . For a CLOB parameter, if the length of the CLOB parameter is less than 4 kilobytes, then the text extracted from the XML file is bound to the parameter as a String type with Table 9–19 Third-Party Database: Binding Binary and Date Values to Parameters of a Stored Procedure XML Schema Type IBM DB2 Data Type AS400 Data Type Microsoft SQL Server Data Type MySQL Data Type base64Binary BLOB CHAR FOR BIT DATA VARCHAR FOR BIT DATA BINARY BINARY LARGE OBJECT BINARY VARYING BINARY IMAGE TIMESTAMP VARBINARY BINARY TINYBLOB BLOB MEDIUMBLOB LONGBLOB VARBINARY dateTime DATE TIME TIMESTAMP DATE TIME TIMESTAMP DATETIME SMALLDATETIME DATE DATETIME TIMESTAMP 9-102 Oracle Fusion Middleware Users Guide for Technology Adapters no further processing. If the length of the CLOB parameter is greater than 4 kilobytes or if the mode of the parameter is INOUT then a temporary CLOB parameter is created. The XML file data is then written to the temporary CLOB before the CLOB is bound to its corresponding parameter. The temporary CLOB parameter is freed when the interaction completes. For other character types, such as CHAR and VARCHAR2, the data is simply extracted and bound as necessary. Note that it is possible to bind an XML document to a CLOB parameter or VARCHAR2 if it is large enough. However, appropriate substitutions for , , and so on, must first be made for example, lt; for and gt; for . A few data types require special processing before their values are bound to their corresponding parameters. These include data types represented by the XML Schema types base64Binary and dateTime. Note that the XML schema type, dateTime, represents TIME, DATE, and TIMESTAMP. This means that the XML values for these data types must adhere to the XML schema representation for dateTime. Therefore, a simple DATE string, 01-JAN-05, is invalid. XML schema defines dateTime as YYYY-MM-DDTHH:mm:ss. Therefore, the correct DATE value is 2005-01-01T00:00:00. Values for these parameters must be specified using this format in the instance XML. Data for binary data types must be represented in a human readable manner. The chosen XML schema representation for binary data is base64Binary. The type converter uses the javax.mail.internet.MimeUtility encode and decode APIs to process binary data. The encode API must be used to encode all binary data into base64Binary form so that it can be used in an XML file. The type converter uses the decode API to decode the XML data into a byte array. The decode API is used to convert the base64Binary data into a byte array. For a BLOB parameter, if the length of a byte array containing the decoded value is less than 2 kilobytes, then the byte array is bound to its parameter with no further processing. If the length of the byte array is greater than 2 kilobytes or if the mode of the parameter is INOUT, then a temporary BLOB is created. The byte array is then written to the BLOB before it is bound to its corresponding parameter. The temporary BLOB is freed when the interaction completes. For other binary data types, such as RAW and LONG RAW, the base64Binary data is decoded into a byte array and bound as necessary. Conversions for the remaining data types are straightforward and require no additional information.

9.7.5 Run Time: After Stored Procedure Invocation

After the procedure or function executes, the values for any INOUT and OUT parameters are retrieved. These correspond to the values of the elements in the OutputParameters root element in the generated XSD. This section includes the following topics: ■ Section 9.7.5.1, Data Type Conversions ■ Section 9.7.5.2, Null Values ■ Section 9.7.5.3, Function Return Values

9.7.5.1 Data Type Conversions

Conversions of data retrieved are straightforward. However, CLOB and other character data, RAW, LONG RAW, and BLOB conversions, as well as conversions for similar data types supported by third-party databases, require special attention. Oracle JCA Adapter for Database 9-103 When a CLOB is retrieved, the entire contents of that CLOB are written to the corresponding element in the generated XML. Standard DOM APIs are used to construct the XML file. This means that character data, as for types such as CLOB, CHAR, and VARCHAR2, is messaged as needed to make any required substitutions so that the value is valid and can be placed in the XML file for subsequent processing. Therefore, substitutions for and, for example, in an XML document stored in a CLOB are made so that the value placed in the element within the generated XML for the associated parameter is valid. Raw data, such as for RAW and LONG RAW data types, is retrieved as a byte array. For BLOBs, the BLOB is first retrieved, and then its contents are obtained, also as a byte array. The byte array is then encoded using the javax.mail.internet.MimeUtility encode API into base64Binary form. The encoded value is then placed in its entirety in the XML file for the corresponding element. The MimeUtility decode API must be used to decode this value back into a byte array. Conversions for the remaining data types are straightforward and require no additional information.

9.7.5.2 Null Values

Elements whose values are null appear as empty elements in the generated XML and are annotated with the xsi:nil attribute. This means that the xsi namespace is declared in the XML file that is generated. Generated XML for a procedure PROC, which has a single OUT parameter, X, whose value is null, looks as follows: OutputParameters … xmlns:xsi= http:www.w3.org2001XMLSchema-instance X xsi:nil=true OutputParameters Note that XML elements for parameters of any type including user-defined types appear this way if their value is null.

9.7.5.3 Function Return Values

The return value of a function is treated as an OUT parameter at position 0 whose name is the name of the function itself. For example, CREATE FUNCTION FACTORIAL X IN INTEGER RETURN INTEGER AS BEGIN IF X = 0 THEN RETURN 1; ELSE RETURN FACTORIAL X - 1; END IF; END; An invocation of this function with a value of 5, for example, results in a value of 120 and appears as FACTORIAL120FACTORIAL in the OutputParameters root element in the generated XML.

9.7.6 Run Time: Common Third-Party Database Functionality

The common third-party database functionality at run time includes the following: ■ Section 9.7.6.1, Processing ResultSets ■ Section 9.7.6.2, Returning an INTEGER Status Value