Data Type Conversions Run Time: Before Stored Procedure Invocation

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 9-104 Oracle Fusion Middleware Users Guide for Technology Adapters

9.7.6.1 Processing ResultSets

All third-party databases share the same functionality for handling ResultSets. The following is a SQL Server example of an API that returns a ResultSet: 1 create procedure foo ... as select ... from ...; 2 go A RowSet defined in the generated XSD represents a ResultSet. A RowSet consists of zero or more rows, each having one or more columns. A row corresponds with a row returned by the query. A column corresponds with a column item in the query. The generated XML for the API shown in the preceding example after it executes is shown in the following example: RowSet Row Column name=column name sqltype=sql datatypevalueColumn ... Row ... RowSet … The name attribute stores the name of the column appearing in the query while the sqltype attribute stores the SQL datatype of that column, for example INT. The value is whatever the value is for that column. Note that it is possible for an API to return multiple ResultSets. In such cases, there is one RowSet for each ResultSet in the generated XML. All RowSets always appear first in the generated XML.

9.7.6.2 Returning an INTEGER Status Value

Some databases support returning an INTEGER status value using a RETURN statement in a stored procedure. Microsoft SQL Server and AS400 both support this feature. In both cases, the Adapter Configuration Wizard is unable to determine whether a stored procedure returns a status value. Therefore, you must specify that the stored procedure is returning a value. You can use a check box to make this indication. After choosing a stored procedure in the Stored Procedures dialog, the Specify Stored Procedure page appears, as shown in Figure 9–49 . The check box appears at the bottom of the page. Select the box to indicate that the procedure contains a RETURN statement. You can view the source code of the procedure to determine whether a RETURN statement exists. Note that the check box appears only for stored procedures on databases that support this feature. The check box is not displayed for functions. The value returned by the stored procedure appears as an element in the OutputParameters root element in the generated XSD. The name of the element is the name of the stored procedure. The value of a return statement is lost after the execution of the stored procedure if the check box is not selected.