This directory contains two sample XML applications: domsample and xslsample
which show how to use the Oracle XML parser for PL/SQL.

To run these sample programs:

1) Load the PL/SQL parser into the database

   To do this, follow the instructions given in the README file under the 
   lib directory.

2) It is necessary for the user running these samples to have been granted the
   appropriate java security privileges to read and write from a file on the 
   file system. To this, first startup SQL*Plus (located typically under 
   $ORACLE_HOME/bin) and connect as a user with admin privileges 
   (for example, 'internal'):

   % sqlplus
   SQL> connect internal
   
   A password might be required to be supplied for 'internal' or the 
   appropriate user with admin privileges. Contact your system admin or 
   Oracle support, if you cannot login with admin privileges.

   You then need to give special privileges to the user running this sample 
   (must be the same one under which you loaded the jar files and plsql files 
   in step 1).

   For example, for user 'scott':

   SQL> grant javauserpriv to scott;
   SQL> grant javasyspriv to scott;

   You should see two messages that say "Grant succeeded." Contact your system
   admin or Oracle support, if this does not occur.

   Now, connect again as the user under which the PL/SQL parser was loaded in
   step 1).

   For example, for user 'scott' with password 'tiger':

   SQL> connect scott/tiger

3) To run domsample
   Load the domsample.sql script under SQL*Plus (if SQL*Plus is not up, first 
   start it up, connecting as the user running this sample):

   SQL>@domsample

   The domsample.sql script defines a procedure domsample with the following
   syntax:

   domsample(dir varchar2, inpfile varchar2, errfile varchar2)

   'dir'      - must point to a valid directory on the external file system
                and should be specified as a complete path name

   'inpfile'  - must point to the file located under 'dir', containing the 
                XML document to be parsed

   'errfile'  - must point to a file you wish to use to record errors; this 
                file will be created under 'dir'

   Execute the domsample procedure inside SQL*Plus by supplying appropriate 
   arguments for 'dir', 'inpfile', and 'errfile'. For example, 

   on Unix, one could do:

     SQL>execute domsample('/private/scott', 'family.xml', 'errors.txt');

   and, on NT, one could do:

     SQL>execute domsample('c:\xml\sample', 'family.xml', 'errors.txt');

   family.xml is provided as a test case

   You should see the following output:

   The elements are: family member member member member 
   The attributes of each element are: 
   family:
    lastname = Smith
   member:
    memberid = m1
   member:
    memberid = m2
   member:
    memberid = m3 mom = m1 dad = m2
   member:
    memberid = m4 mom = m1 dad = m2

4) To run xslsample
   Load the xslsample.sql script under SQL*Plus (if SQL*Plus is not up, first 
   start it up, connecting as the user running this sample):

   SQL>@xslsample

   The xslsample.sql script defines a procedure xslsample with the following
   syntax:

   xslsample(dir varchar2, xmlfile varchar2, xslfile varchar2, 
             resfile varchar2, errfile varchar2)

   'dir'     - must point to a valid directory on the external file system
                and should be specified as a complete path name

   'xmlfile' - must point to the file located under 'dir', containing the 
               XML document to be parsed

   'xskfile' - must point to the file located under 'dir', containing the 
                XSL stylesheet to be applied

   'resfile' - must point to the file located under 'dir' where the 
               transformed document is to be placed

   'errfile' - must point to a file you wish to use to record errors; this 
               file will be created under 'dir'

   Execute the xslsample procedure inside SQL*Plus by supplying appropriate 
   arguments for 'dir', 'xmlfile', 'xslfile', and 'errfile'. For example, 

   on Unix, one could do:

     SQL>execute xslsample('/private/scott', 'family.xml', 'iden.xsl', 
                           'family.out', 'errors.txt');

   and, on NT, one could do:

     SQL>execute xslsample('c:\xml\sample', 'family.xml', 'iden.xsl', 
                           'family.out', 'errors.txt');

   family.xml and iden.xsl are provided as test cases

   You should see the following output:

   Parsing XML document c:\/family.xml
   Parsing XSL document c:\/iden.xsl
   XSL Root element information
   Qualified Name: xsl:stylesheet
   Local Name: stylesheet
   Namespace: http://www.w3.org/XSL/Transform/1.0
   Expanded Name: http://www.w3.org/XSL/Transform/1.0:stylesheet
   A total of 1 XSL instructions were found in the stylesheet
   Processing XSL stylesheet
   Writing transformed document

   Also, family.out should contain the following:
   
   <family lastname="Smith">
   <member memberid="m1">Sarah</member>
   <member memberid="m2">Bob</member>
   <member memberid="m3" mom="m1" dad="m2">Joanne</member>
   <member memberid="m4" mom="m1" dad="m2">Jim</member>
   </family>

   You might see a delay in getting the output when executing the procedure 
   for the first time. This is because the JServer needs to perform various
   initialization tasks before it can execute a Java stored procedure. 
   Subsequent invocations should run quickly.

   If you get any errors, please make sure that the directory name is specified
   as a complete path on the file system (sql directory aliases and shared 
   directory syntax '\\' are not supported at this time). Otherwise, please 
   report the problem on the XML discussion forum in http://technet.oracle.com.
