</EMPLOYEES_ROW> </EMPLOYEES> </ROW> </ROWSET> Oracle objects and collections also appear as nested structures in the canonical rep- resentation. The following example shows a single row with an object and a collection: <ROWSET> <ROW num=”1”> <YOUR_OBJECT_COLUMN_NAME> <ATTRIBUTE1>Value1</ATTRIBUTE1> <ATTRIBUTE2>Value2</ATTRIBUTE2> </YOUR_OBJECT_COLUMN_NAME> <YOUR_COLLECTION_NAME> <YOUR_COLLECTION_NAME_ITEM> <ATTRIBUTE1>Value1</ATTRIBUTE1> <ATTRIBUTE2>Value2</ATTRIBUTE2> </YOUR_COLLECTION_NAME_ITEM> <YOUR_COLLECTION_NAME_ITEM> <ATTRIBUTE1>Value1</ATTRIBUTE1> <ATTRIBUTE2>Value2</ATTRIBUTE2> </YOUR_COLLECTION_NAME_ITEM> </YOUR_COLLECTION_NAME> </ROW> </ROWSET> Formatting Dates Because most applications use dates at some point, it is very important to understand how XSQL works with dates. XSQL uses date formats that act as masks. A date format is a combination of different symbols that represent different parts of the date-time stamp. XSQL uses date formats both when retrieving information from the database and when putting information into it. When retrieving information, XSQL writes the date to output in accordance with the date format. When inputting information, it assumes that dates are in the format specified by the date format. The characters that represent different parts of the date format are listed in Table 5.5. Padding for variable-length data can be supplied by repeating the symbol. For exam- ple, if you want 08 to represent 8 A.M., you put hh in the format string. Table 5.5 Date Format Symbols SYMBOL MEANING EXAMPLE G Era designator AD y Year 1996 MM Month in year as number 07 80 Chapter 5 Table 5.5 Date Format Symbols (Continued) SYMBOL MEANING EXAMPLE MMM Month in year as word July D Day in month 10 h Hour in A.M./P.M. (1-12) 12 H Hour in day (0-23) 0 m Minute in hour 30 s Second in minute 55 S Millisecond 978 E Day in week Tuesday D Day in year 189 F Day of week in month 2 (2nd Wed in July) W Week in year 27 W Week in month 2 a A.M./P.M. marker PM k Hour in day (1~24) 24 K Hour in A.M./P.M. (0~11) 0 z Time zone Pacific Standard Time ‘ Escape for text ‘’ Single quote ‘ Table 5.6 shows a couple of examples of formatting dates. Table 5.6 Example Date Formats FORMAT EXAMPLE “MM.dd.yyyy G ‘at’ hh:mm:ss z” 05/02/2002 AD at 15:08:56 PDT “EEE, MMM d, ‘’yy” Sun, Apr 10, ‘02 “hh ‘o’’clock’ a, zzzz” 12 o’clock PM, Pacific Daylight Time “yyyyy.MM.dd HH:mm” 2002.July.10 23:08 Writing XSQL Pages 81 Several of the XSQL built-in actions use date formats. All of them use the same format. Other Built-in Actions This section exposes the details of the rest of the XSQL actions. The next two chapters will look more deeply in to several of these actions as you learn about modifying the database and passing parameters. All of these actions work in the same manner as the xsql:query action with which you are already familiar. You specify attributes and a value for the action element. xsql:dml DML stands for Data Manipulation Language. It means that you are going to change something in the database. The xsql:dml element is used for statements of change, including insertions, updates, deletions, and even creation and deletion of database objects. Though you should heed the warning against actually deleting whole tables, the xsql:dml element is very useful for processing input to your database. You can also use it to execute PL/SQL blocks. The following example uses a PL/SQL block to insert two records into the database and commit them. As you will learn in Chapter 9, PL/SQL can be used to do a great variety of tasks. You can call a wide variety of procedures, use conditional logic, and even process results. The example here is very pedestrian, but you will see more com- plex examples in Chapter 9. <page connection=”demo” xmlns:xsql=”urn:oracle-xsql”> <dml> <xsql:dml> begin insert into emp (empno, ename) values (8000,’Joe Schmoe’); insert into emp (empno, ename) values (8001,’Billy Blue’); commit; end; </xsql:dml> </dml> <query> <xsql:query> select * from emp </xsql:query> </query> </page> When you look at the results of the example, you will see that there is little result that comes back from the xsql:dml tag. All that you can expect is either an error message if something goes wrong or an element that tells you the number of rows that are affected. You will learn in Chapter 14 how best to return to the user the status of a DML request There are a couple of attributes that you can use to configure the behavior of the xsql:dml element. They are described in Table 5.7. 82 Chapter 5 Table 5.7 xsql:dml Attributes ATTRIBUTE NAME DESCRIPTION commit=”boolean” If yes, a commitment is issued on the connection after a successful execution of the DML statement. Default is no. bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. error-statement=”boolean” If set to no, the SQL statement that generated the error won’t be included in the output. This keeps your users (and possibly hackers) from being able to reverse engineer your database schema. Default is yes. xsql:ref-cursor-function This action interacts with a PL/SQL function. A PL/SQL function returns a value at the end of execution. Some PL/SQL functions return cursors, acting essentially like a result set. The difference is that the PL/SQL function can assemble the cursor by using condi- tional logic and several SQL statements across a variety of tables. Only PL/SQL functions that return the type REF CURSOR can be called from a xsql:ref-cursor-function action. Assume that you have a function whose name is MyPackage.MyFunction and that it returns a REF CURSOR. You would call it as follows: <?xml version=”1.0”?> <page connection=”demo” xmlns:xsql=”urn:oracle-xsql”> <ref-cursor> <xsql:ref-cursor-function> MyPackage.MyFunction(1) </xsql:ref-cursor-function> </ref-cursor> </page> This action works very similarly to the xsql:query action, except that it calls a PL/SQL function instead of issuing SQL statements directly. It is little surprise, then, that almost all of the attributes for xsql:query work for xsql:ref-cursor -function. There is only one exception—the fetch-size attribute can’t be applied here. You will learn more about using PL/SQL in Chapter 9. xsql:include-owa It may be the case that you have stored procedures in the database that generate XML. It’s quite reasonable that you might want to reuse that logic and have that XML included in your XSQL page. This is the purpose of the xsql:include-owa action. There are two standard Oracle Web Agent (OWA) packages (HTP and HTF) that will Writing XSQL Pages 83 write to the server-side page buffer. When this action is used, the XSQL page processor executes the PL/SQL block included in the action, assuming that the functions and pro- cedures of the HTP and HTF are being used to write XML to the server-side page buffer. The XSQL page processor then grabs the output out of the page buffer and inserts it in to the outgoing XSQL page. It is the responsibility of the PL/SQL programmer to ensure that the XML is well formed. Here is an example of how to use this action: <xsql:include-owa> PL/SQL Block using HTP and/or HTF packages to write to server-side page buffer </xsql:include-owa> There are a couple of attributes that can be used with the xsql:include-owa action. They are described in Table 5.8. xsql:include-request-params This action is a utility action designed to make it easier to write XSLT stylesheets. It formats every parameter and its value to XML, including not only form- and URL- based parameters but also session parameters and cookies. The usage is very simple, and there are no optional attributes. Just put the following into your XSQL document: <xsql:include-request-params/> In its place you will get XML back in the following form. If there are no session variables or cookies, those elements will not occur. <request> <parameters> <ParamName1>value1</ParamName1> <ParamName2>value2</ParamName2> </parameters> <session> <SessionVarName1>value1</SessionVarName1> <SessionVarName2>value2</SessionVarName2> </session> <cookies> <cookieName1>value1</cookieName1> <cookieName2>value2</cookeName2> </cookies> </request> When you look at XSLT in depth in Chapter 13, you will learn more about the use- fulness of this action. 84 Chapter 5 Table 5.8 xsql:include-owa Attributes ATTRIBUTE DESCRIPTION bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. error-statement=”boolean” If set to no, the SQL statement that generated the error won’t be included in the output. This keeps your users (and possibly hackers) from being able to reverse engineer your database schema. Default is yes. xsql:include-param This action allows you to include a single parameter in to your XML datagram. It is essentially a scaled back, specific version of the xsql:include-request-params action. It gives you an easy way to make your parameters and their values available to your XSLT stylesheets. Here is the syntax: <xsql:include-param name=”paramname”/> The name attribute is required, and there are no optional attributes. xsql:include-xml This action allows you to include XML in your datagram from any URL. Relative URLs will point to files in your local Web space, whereas absolute URLs can grab the resource from anywhere on the Web. The XML retrieved must be well formed. Here is how you use it: <xsql:include-xml href=”URL”/> The href attribute is required, and there are no optional attributes. xsql:set-page-param The xsql:set-page-param action allows you to set a page-private parameter for the XSQL page. You can set the parameter either as text, as text and other parameter values, or as the result of a SQL statement. There are two different syntaxes for this attribute. The first syntax covers the first two cases: <xsql:set-page-param name=”paramname” value=”value”/> Writing XSQL Pages 85 This will set paramname=value. You may be wondering how you would use this syntax to assign the value of another parameter. You will learn more about this later in the chapter, when you read about passing parameters. For now, here is one example: <xsql:set-page-param name=”new-param” value=”{@org-param}”/> This will set the value of org-param as the value of new-param. The other syntax is quite a bit more interesting. With it you can set parameters based on SQL statements. An example follows. The value assigned is that of the first column of the first row. For clarity, it is best to structure your SQL statements so that only one row and one column will be returned. <xsql:set-page-param name=”sql-based-param”> SQL statement </xsql:set-page-param> This action has a couple of attributes, detailed in Table 5.9. The name attribute is required. xsql:set-session-param The xsql:set-session-param action allows you to set a parameter on the current browser user’s HTTP session. This session is controlled by the Web server, but it gen- erally ends after a time out or when the browser is closed. This action has an effect only when you are using XSQL in conjunction with Java servlets. Nothing happens if the XSQL request object or XSQL command line encounters this action in a page that it is processing. The syntax behaves very much like the syntax for the xsql:set-page-param action. You can set a parameter’s value in two ways. You can set it directly, as follows: <xsql:set-session-param name=”paramname” value=”value”/> You can also set the parameter’s value by issuing a SQL statement. The value assigned is that of the first column of the first row. For clarity, it is best to structure your SQL statements so that only one row and one column will be returned. Table 5.9 xsql:set-page-param Attributes ATTRIBUTE NAME DESCRIPTION name=”string” Name of the page-private parameter to set. bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. ignore-empty-value=”boolean” If yes, the parameter won’t be set if the value that would be assigned is an empty string. Default is no. 86 Chapter 5 <xsql:set-session-param name=”sql-based-param”> SQL statement </xsql:set-session-param> The xsql:set-session-param action has several attributes, listed in Table 5.10. The name attribute is required. xsql:set-cookie This action sets an HTTP cookie to a specified value. This action has an effect only when you are using XSQL in conjunction with Java servlets. Nothing happens if the XSQL request object or XSQL command line encounters this action in a page that it is processing. The syntax behaves very much like the syntax for the xsql:set-page-param action. You can set a parameter’s value in two ways. You can set it directly, as follows: <xsql:set-cookie name=”paramname” value=”value”/> You can also set the parameter’s value by issuing a SQL statement. The value assigned is that of the first column of the first row. For clarity, it is best to structure your SQL statements so that only one row and one column will be returned. <xsql:set-cookie name=”sql-based-param”> SQL statement </xsql:set-cookie> The xsql:set-cookie action has several attributes, listed in Table 5.11. The name attribute is required. Table 5.10 xsql:set-session-param Attributes ATTRIBUTE NAME DESCRIPTION name=”string” Name of the session parameter to set. bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. ignore-empty-value=”boolean” If yes, the parameter won’t be set if the value that would be assigned is an empty string. Default is no. only-if-unset=”Boolean” If yes, this parameter will be set only if the parameter doesn’t exist in the session. Default is no. Writing XSQL Pages 87 Table 5.11 xsql:set-cookie Attributes ATTRIBUTE NAME DESCRIPTION name=”string” Name of the session parameter to set. bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. ignore-empty-value=”boolean” If yes, the parameter won’t be set if the value that would be assigned is an empty string. Default is no. only-if-unset=”Boolean” If yes, this parameter will be set only if the parameter doesn’t exist in the session. Default is no. max-age=”integer” Sets the maximum age of the cookie in seconds. By default, the cookie will expire when the browser session ends. path=”string” The relative URL path where the cookie value is valid. By default, this is set to the path of the XSQL document. For the cookie to be readable by all pages on your Web server, set path=”/”. xsql:set-stylesheet-param This action allows you to dynamically set a top-level stylesheet parameter that the XSQL page processor should pass on to the XSLT stylesheet. You will learn more about XSLT stylesheet parameters in Chapter 13. The syntax is similar to that of the xsql:set-page-param, xsql:set -session-param, and xsql:set-cookie actions. To set the stylesheet to a particu- lar value, including possibly another parameter, use: <xsql:set-stylesheet-param name=”paramname” value=”value”/> You can also set the parameter’s value by issuing a SQL statement. The value assigned is that of the first column of the first row. For clarity, it is best to structure your SQL statements so that only one row and one column will be returned. <xsql:set-stylesheet-param name=”sql-based-param”> SQL statement </xsql:set-stylesheet-param> The xsql:set-stylesheet-param action has several attributes, listed in Table 5.12. The name attribute is required. 88 Chapter 5 Table 5.12 xsql:set-session-param Attributes ATTRIBUTE NAME DESCRIPTION name=”string” Name of the session parameter to set. bind-params=”string” Ordered list of XSQL parameter names that will bind to JDBC bind variables. More on this later in the chapter. ignore-empty-value=”boolean” If yes, the parameter won’t be set if the value that would be assigned is an empty string. Default is no. xsql:action The xsql:action element is used to enable custom action handlers. When this action is processed, a custom action handler of your choosing is invoked. You will learn more about how to write custom action handlers in Chapter 17. The only requirement is that the xsql:action element have a handler attribute. Beyond that, it is restricted only by the XML syntax for all elements and the requirements of the custom action handler. <xsql:action handler=”somepackage.SomeCustomHandler” param1=”value1” param2=”value2”> <SomeElement>blah</SomeElement> <SomeOtherElement>foo</SomeOtherElement> </xsql:action> The custom action handler will consume the containing elements and parameters. As you will learn in Chapter 17, it is very important that custom action handler devel- opers thoroughly document what their action handlers require and can optionally use. xsql:include-xsql The xsql:include-xsql action can be used to include the results of other XSQL pages in the current XSQL page. This can make your XSQL pages more reusable. The xsql:include-xsql action is used as follows: <xsql:include-xsql href=”other.xsql”/> The results of the other XSQL page will be included wherever this element is placed in the XSQL document. If the XSQL document is tied to a stylesheet, the stylesheet will be applied before inclusion. The results can also be reparsed. All of the request and ses- sion parameters available to the including page will be available to the included page. Table 5.13 lists the optional attributes. Writing XSQL Pages 89 [...]... type attribute is also required when using XSLT; it must be set to the mime type text/xsl SELECT * FROM EMP . </EMPLOYEES_ROW> </EMPLOYEES> </ROW> </ROWSET> Oracle objects and collections also appear as nested structures in the canonical rep- resentation but you will see more com- plex examples in Chapter 9. <page connection=”demo” xmlns:xsql=”urn :oracle- xsql”> <dml> <xsql:dml> begin insert into emp (empno, ename) values (8000,’Joe. would call it as follows: <?xml version=”1.0”?> <page connection=”demo” xmlns:xsql=”urn :oracle- xsql”> <ref-cursor> <xsql:ref-cursor-function> MyPackage.MyFunction(1) </xsql:ref-cursor-function> </ref-cursor> </page> This