SQLJ Tutorial

Tutorial
10/16/98 Copyright 1998, Sybase, Inc. All Rights Reserved Page 19

The class Routines6 has a static variable jobs, which is set by the static method setJobs
and
referenced by the static method job3. A class such as Routines6 that dynamically
modifies the
values of static variables is well-defined in Java, and can be useful. However, when such
a class is
installed in an SQL system, and the methods setJobs and job3 are defined as SQL
procedures and
functions (create procedure/function), the scope of the assignments to the static variable
jobs is
implementor-defined. I.e. the scope of that variable is not specified, and is likely to differ
across
implementations (and possibly across the releases of a given implementation).
For example:
create procedure set_jobs (js varchar(100))
external name 'routines6_jar:Routines6.setJobs'
language java parameter style java;
create function job_of3(jc integer) returns varchar(20)
return null on null input
external name 'routines6_jar:Routines6.job3'
call set_jobs('AdminSalesClerk');
select name, job_of3 (jobcode)
from emps
where job_of3(jobcode) <> 'Admin';
This appears to be a straightforward use of the Routines6 class in SQL. The call of
set_jobs
specifies a list of job code values, which the instance "caches" and uses in subsequent
calls of
job_of3. However, since the scope of the static variable jobs in the SQL environment is
implementor-defined, the following questions regarding the values passed to the set_jobs
procedure
are likely to differ across implementation:
Is the set_jobs value visible only to the current session? Or also to concurrent sessions
and to
later non-concurrent sessions?
Does the set_jobs value persist across a commit? Is it reset by a rollback?
The implication of this uncertainty is that you should not use classes that assign to static
variables
in SQL. Note, nowever, that such assignments will not (necessarily) be detected by the
SQL
implementation, either when you create procedure/function or when you call a routine.
You can prevent assignments to static variables in Java by declaring them with the final
property.
2.16 Dropping SQL names of Java methods

After you have created SQL procedure or function names for Java methods, you can drop
those
SQL names with a normal SQL drop st
-SQLJ: SQL Routines using the Java
Programming
Language
Page 20 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98
drop function region restrict;
A drop statement has no effect on the Java method (or class) on which the SQL name
was defined.
Dropping an SQL procedure or function implicitly revokes any granted privileges for that
routine.
2.17 Removing Java classes from SQL

You can completely uninstall a jar file with the sqlj.remove_jar procedure. For example:
sqlj.remove_jar ('routines_jar');
When you call the sqlj.remove_jar procedure, there must be no SQL procedure or
function name
that references any method of any class in the specified jar file. You must explicitly
perform SQL
drop statements to delete any such SQL names before you call the sqlj.remove_jar
procedure.
2.18 Replacing Java classes in SQL

Assume that you have installed a Java jar file in SQL, and you want to replace some or
all of the
contained classes, e.g. to correct or improve them. You can do this by using the
sqlj.remove_jar
procedure to remove the current jar file, and then using the sqlj.install_jar procedure to
install the
new version. However, you will probably have executed one or more SQL DDL
statements that
depend on the methods of the classes that you want to replace. I.e. you may have
executed one or
more of the following DDL operations:
create procedure/function statements referencing the classes.
grant statements referencing those SQL procedures and functions.
create procedure/function statements for SQL procedures and functions that invoke
those
SQL procedures and functions.
create view/table statements for SQL views and tables that invoke those SQL
procedures and
functions.
The rules for the sqlj.remove_jar procedure require that you drop all SQL
procedure/functions that
directly reference methods of a class before you can remove the jar file containing the
class. And,
SQL rules for restrict require that you drop all SQL objects (tables, views, and routines)
that
invoke a procedure/function before you drop the procedure/function.
Thus, if you use the sqlj.remove_jar and sqlj.install_jar procedures to replace a jar file,
you will
have to drop the SQL objects that directly or indirectly depend on the methods of the
classes in the
jar file, and then re-create those items.
The sqlj.replace_jar procedure avoids this requirement, by performing an instantaneous
remove
and install, with suitable validity checks. You can therefore call the sqlj.replace_jar
procedure
without first dropping the dependent SQL objects.
For example, in the section Installing region and correcStates in SQL we installed the
class of
"Routines1" with the following statement:
sqlj.install_jar ( 'file:~/classes/Routines1.jar', 'routines1_jar')
You can replace that jar file with a statement such as:
sqlj.replace_jar ( 'file:~/revised_classes/Routines1.jar', 'routines1_jar')
Tutorial
Note that the jar name must be the same. It identifies the existing jar, and will
subsequently
identify the replacement jar. The URL of the replacement jar file can be the same as or
different
from the URL of the original jar file.
In the general case, there will be classes in the old jar file that are not in the new jar file,
classes
that are in both jar files, and classes that are in the new jar file and not in the old jar file.
These are
referred to respectively as unmatched old classes, matching old/new classes, and
unmatched new
classes.
The validity requirements on the replacement jar file are:
There must be no SQL procedure or function name that references any method of any
unmatched old class (since all unmatched old classes will be removed).
Any create procedure/function statement that references a method of a matching class
must be a
valid statement for the new class.
If these requirements are satisfied, the sqlj.replace_jar procedure deletes the old classes
(both
unmatched and matching) and installs the new classes (both unmatched and matching).
2.19 Visibility
The sqlj.install_jar procedure will install any Java classes into the SQL system.
However, not all
methods of all classes can be referenced in SQL. Only visible methods of visible classes
can be
referenced in SQL. The notion of visible classes and methods is based on the concept of
mappable
datatypes. The detailed definitions of mappable and visible are specified in the section
CREATE
PROCEDURE/FUNCTION statement. They may be summarized as follows:
A Java datatype is mappable to SQL (and vice versa) iff it has a corresponding SQL
datatype,
or it is an array that is used for out parameters, or it is an array that is used for result sets.
A Java method is mappable (to SQL) iff the datatype of each parameter is mappable,
and the
result type is either a mappable datatype or is void.
A Java method is visible in SQL iff it is public, static, and mappable.
Only the visible installed methods can be referenced in SQL. Other methods simply don't
exist in
SQL: attempts to reference them will be raise implementation-dependent syntax errors
such as
"unknown name".
Non-visible classes and methods can, however, be used by the visible methods.
2.20 Exceptions
SQL exceptions are defined for the SQLJ procedures. For example, if the URL argument
specified
in calls to sqlj.install_jar or sqlj.replace_jar (etc) is invalid, an SQL exception with a
specified
SQLSTATE will be raised. These exceptions are specified in the definitions of the
procedures, and
are listed in SQLSTATE class and subclass values.
Java exceptions that are thrown during execution of a Java method in SQL can be caught
within
Java, and if this is done, then those exceptions do not affect SQL processing.
SQLJ: SQL Routines using the Java

Language
Programming

Any Java exceptions that are uncaught when a Java method called from SQL completes
will be
returned in SQL as SQL exceptions. When a Java exception E is uncaught within Java,
the
character string returned by the Java method call "E.toString( )" will be provided as the
SQL
message text associated with the SQL exception. The Java toString method returns a
value that is
the Java name of the exception concatenated with the string argument (if any) specified
when the
exception was thrown in Java. The SQLSTATE code for an uncaught Java exception can
be
specified by the Java method that raises the exception, using a convention defined for the
toString
value (see the section Status Codes).
2.21 Deployment descriptors

When you install a jar file containing a set of Java classes into SQL, you must execute
one or more
create procedure/function statements before you can call the static methods of those
classes as
SQL procedures and functions. And, you may also want to perform various grant
statements for
the SQL names created by those create procedure function statements. When you later
remove a
jar file, you will want to execute corresponding drop procedure/function statements and
revoke
statements.
If you plan to install a jar file in several SQL systems, the various create, grant, drop,
and revoke
statements will often be the same for each such SQL system. One way that you could
simplify the
install and remove actions would be as follows:
1) Incorporate the create and grant statements that you want to associate with install into
one
Java method, which you might call the afterInstall method.
2) Incorporate the drop and revoke statements that you want to associate with remove
into
another Java method, which you might call the beforeRemove method. I.e. the afterInstall
and
beforeRemove methods would use SQLJ Embedded SQL or JDBC to invoke SQL for the
desired create, grant, drop, and revoke statements.
3) Include the afterInstall and beforeRemove methods in a class, which you might call the
deploy
class.
4) Include the deploy class in the jar file that you plan to distribute.
1) Instruct recipients of the jar file to do the following to install the jar file:
a) Call the sqlj.install_jar procedure for the jar file.
b) Execute a create procedure statement for the afterInstall method, giving it an SQL
name such as after_install. Note that this "bootstrap" action cannot be included in the
afterInstall method itself.
c) Call the after_install procedure. Note: We can assume that the after_install procedure
will include a create procedure statement to give the beforeRemove method an SQL
name such as before_remove.
2) Instruct recipients of the jar file to proceed as follows to remove the jar file:
a) Call the before_remove procedure.
b) Drop the after_install and before_remove procedures.
c) Call the sqlj.remove_jar procedure,
Tutorial
d) Execute a drop procedure statement for the before_remove procedure. Note that this
"cleanup" action cannot be included in the beforeRemove method itself.
Note that this simplification of the install and remove actions still requires several manual
steps.
You could, then, go further and incorporate the above steps into an SQL procedure.
However, the
SQL procedure languages are all currently somewhat vendor-specific.
SQLJ therefore provides a mechanism, called deployment descriptors, with which you
can specify
the SQL statements that you want to be executed implicitly by the sqlj.install_jar and
sqlj.remove_jar procedures.
If you want the deployment descriptors in a jar file to be interpreted when you install the
jar file,
then you use the sqlj.install_jar version of the install procedure. If a jar file contains a
deployment descriptor, then the sqlj.install_jar procedure will use that deployment
descriptor to
determine the create and grant statements to execute after it has installed the classes of
the jar file.
The corresponding sqlj.remove_jar procedure uses the deployment descriptor to
determine the
drop and revoke statements to execute before it removes the jar file and its classes.
A deployment descriptor is a text file containing a list of SQL create and grant statements
to be
executed when the jar file is installed, and a list of SQL drop and revoke statements to be
executed
when the jar file is removed.
For example, suppose that you have incorporated the above classes Routines1, Routines2,
and
Routines3 into a single jar file. The following is a possible deployment descriptor that
you might
want to include in that jar file.
Notes:
i) Within a deployment descriptor file, you use the jar name thisjar as a placeholder jar
name in the external name clauses of create statements.
ii) The various user names in this example are of course hypothetical.
SQLActions[ ] = {
BEGIN INSTALL
create procedure correct_states (old char(20), new char(20))
modifies sql data
external name thisjar:Routines1.correctStates
grant execute on correct_states to Baker;
create function region_of(state char(20)) returns integer
no sql
external name thisjar:Routines1.region

grant execute on region_of to public;
create procedure best2

Language
Programming

(out n1 varchar(50), out id1 char(5), out region1 integer, out s1
dec(6,2),
out n2 varchar(50), out id2 char(5), out region2 integer, out s2
dec(6,2),
region integer)
reads sql data
external name thisjar:Routines2.bestTwoEmps
grant execute on best2 to Baker, Cook, Farmer;
create procedure ordered_emps (region integer)
reads sql data
dynamic result sets 1
external name thisjar:Routines3.rankedEmps
grant execute on ordered_emps to public;
END INSTALL ,
BEGIN REMOVE
revoke execute on correct_states from Baker;
drop procedure correct_states restrict;
revoke execute on region_of from public;
drop function region_of;
revoke execute on best2 from Baker, Cook, Farmer;
drop procedure best2;
revoke execute on ordered_emps from public;
drop procedure ordered_emps;
END REMOVE
}
Assume that deploy_routines.txt is the name of a text file containing the above
deployment
descriptor. You would build a jar file containing the following:
1) The text file deploy_routines.txt.
2) The class files for Routines1, Routines2, and Routines3.
3) A manifest file with the following manifest entry:
Name: deploy_routines.txt
SQLJDeploymentDescriptor: TRUE
Tutorial
This manifest entry identifies the file deploy_routines.txt as a deployment descriptor in
the jar, for
the sqlj.install_jar_deploy and sqlj.remove_jar_undeploy procedures to interpret.
Deployment descriptor files can contain errors. For example:
Syntax errors in the statements.
Multiple create statements specifying the same procedure names.
In general, any error that can arise in a create or grant statement can occur in a
deployment
descriptor file.
You may want to install a jar file that contains a deployment file without performing the
deployment actions. For example, those actions may be inappropriate for some SQL
system. You
can do this the the sqlj.install_jar_no_deploy version of the install statement.
2.22 Paths
In the preceding sections, the example jar files and their Java classes referenced other
Java classes
in the packages java.lang and java.sql. The jar files and their Java classes that you install
can also
reference Java classes in other jar files that you have installed or will install. For
example, suppose
that you have three jar files, containing Java classes relating to administration, project
management,
and property management.
sqlj.install_jar (file:~/classes/admin.jar, admin_jar);
At this point, you can execute create procedure/function statements referencing the
methods of
classes in the admin_jar. And, you can call those procedures and functions. If, at runtime,
the Java
methods of admin_jar reference the system classes listed in the section Java facilities
supported
by SQLJ, or other Java classes that are contained in the admin_jar, then those references
will be
resolved implicitly. If the admin_jar methods reference Java classes that are contained in
the
property_jar (which we will install below), then an exception will be raised for an
unresolved
class refernce.
sqlj.install_jar (file:~/classes/property.jar, property_jar);
sqlj.install_jar (file:~/classes/project.jar, project_jar);
These calls of sqlj.install_jar install the property_jar and project_jar However,
references to the
property_jar classes by classes in the admin_jar will still not be resolved. Similarly,
references
within the property_jar to classes in the project_jar will not be resolved, and vice versa.
To summarize:
When you install a jar file, any references within the classes of that jar file to system
classes, or to classes that are contained in the same jar file, will be implicitly resolved.
References to any other classes, installed or not, are unresolved.
You can install jar files that have unresolved class references, and you can use create
procedure/function statements to define SQL routines on the methods of those classes.
When you call SQL routines defined on Java methods, exceptions for unresolved class
references may occur at any time allowed by the Java language specification.

Language
Programming

Invoking classes that contain unresolved references can be useful:
To use or to test partially-written applications.
To use classes that have some methods that are not appropriate for use in an SQL
environment. E.g. a class that has display-oriented or interactive methods that are used
in other Java-enabled environments, but not within an SQL system.
To resolve references to classes in other jar files, you use the sqlj.alter_java_path
procedure.
sqlj.alter_java_path (admin_jar, (property/*, property_jar) (project/*, project_jar)
);
sqlj.alter_java_path (property_jar, (project/*, project_jar ));
sqlj.alter_java_path (project_jar, (*, property_jar) (*, admin_jar) );
The sqlj.alter_java_path procedure has two arguments, both of which are character
strings. In a
call sqlj.alter_java_path(JX, PX):
JX is the name of the jar for which you want to specify a path. This is the jar name that
you specified in the install_jar procedure.
PX is the path of jar files in which you want unresolved class names that are referenced
by
classes contained in JX to be resolved. The path argument is a character string containing
a list of path elements (not comma-separated). Each path element is a parenthesized pair
(comma-separated), in which the first item is a pattern, and the second item is a jar name.
Suppose that at runtime, some method of a class C that is contained in jar JX is being
evaluated.
And, suppose that within the execution of class C, a reference to some other class named
XC is
encountered, such that no class named XC is defined in jar JX. The path PX specified for
jar JX in
the sqlj.alter_java_path call determines the resolution, if any, of class name XC:
Each path element (PATi, Ji) is examined.
If PATi is a fully qualified class name that is equal to XC, then XC must be defined in
jar
Ji. If it is not, then the reference to XC is unresolved.
If PATi is a sequence of package name qualifiers followed by an *, and XC begins
with
the same package name qualifiers, then XC must be defined in jar Ji. If it is not, then the
reference to is unresolved.
If PATi is a single *, then if XC is defined in jar Ji, that resolution is used; otherwise,
subsequent path elements are tested.
The paths that we specified above for the admin_jar, property_jar, and project_jar
therefore have
the following effect:
When executing within the admin_jar, classes that are in the property or project
packages, will be resolved in the property_jar and project_jar, respectively.

When executing within the property_jar, classes that are in the project package will
be
resolved in the project_jar.
When executing within the project_jar, all classes will first be resolved in the
property_jar, and then in the admin_jar.
Tutorial
Note that if a class C contained in the property_jar directly contains a reference to a class
AC
contained in the admin_jar, then that reference to AC will be unresolved, since the
admin_jar is not
specified in the path for the property_jar. But, if that class C invokes a method
project.C2.M of a
class contained in the project_jar, and project.C2.M references class AC, then that
reference to AC
will be resolved in the admin_jar, since the admin_jar is specified in the path for the
project_jar.
I.e. while class C is being executed, the path specified for the property_jar is used, and
while class
C2 is being executed, the path specified for the project_jar is used. Thus, as execution
transfers to
classes contained in different jar files, the current path changes to the path specified for
each such
jar file. In other words, the path specified for a jar file J1 applies only to class references
that occur
directly within the classes of J1, not to class references that occur in some class contained
in
another jar file that is invoked from a class of J1.
The path that you specify in a call of the sqlj.alter_java_path procedure becomes a
property of the
specified jar. A given jar has at most one path. The path (if any) for a jar applies to all
users of the
classes and methods in the jar.
When you call the sqlj.alter_java_path procedure, the path you specify replaces the
current path
(if any) for the specified jar. The effect of this replacement on currently running classes
and
methods is implementor-defined.
When you execute the sqlj.alter_java_path procedure, you must be the owner of the jar
file that
you specify as the first argument, and you must have the usage privilege on each jar file
that you
specify in the path argument.
The path facility is an optional feature.
2.23 SQL Privileges

The SQL privileges for SQLJ facilities are as follows:
sqlj.install_jar, sqlj.replace_jar, and sqlj.remove_jar procedures:
The privileges required to invoke these procedures is implementor-defined. This is
similar to
the implementor-defined privileges required for e.g. creating a schema.
sqlj.grant_java_usage and sqlj.revoke_java_usage procedures:
You must be the owner of the specified jar.

sqlj.alter_java_path procedure:
You must be the owner of the specified jar, and also have the usage privilege on each jar
in the
path argument.
create procedure/function and drop procedure/function:
These are governed by the normal SQL privileges for create and drop.
execute privilege on Java methods referenced by SQL names:
This is governed by the normal SQL execute privilege on SQL routine names.
It is implementation defined whether a Java method called by an SQL name executes
with
"definer's rights" or creators rights. I.e. whether it executes with the user-name of the
user
who performed the create procedure/function or the user-name of the current user.
Common elements
3. COMMON ELEMENTS
3.1 Jar names
Function
Specify the syntax and rules for jar names.
Syntax
jar_name ::= [[catalog_id.]schema_id.]jar_id
catalog_id ::= sql_identifier
schema_id ::= sql_identifier
jar_id ::= sql_identifier
Definitions and Rules

1) The sql_identifiers that are the constituents of the jar_name are case insensitive, and
may be
delimited identifiers.
2) If the catalog_id is not specified, then it defaults to the name of the current catalog. If
the
schema_id is not specified, then it defaults to the name of the current schema.
3) Equality of jar names is determined by the SQL rules for equivalence of identifiers.

Language
Programming
3.2 SQL-Java paths

Function
Specify the syntax and rules for SQL-Java paths
Syntax
sql_java_path ::= [path_element...]
path_element ::= (referenced_class, resolution_jar)
referenced_class ::= [packages.]* | [packages.]class_name
packages ::= package_name[.package_name]...
package_name ::= java_identifier
class_name ::= java_identifier
resolution_jar::= jar_name
Rules
1) When a Java class CJ in a jar J is being executed in an SQL system, let P be the path (if
any)
associated with jar J by a call of the sqlj.alter_java_path procedure.
2) Any reference in CJ to a class name CN that is not a system class listed in the section
Java
facilities supported by SQLJ, and is not contained in jar J is resolved as follows:
For each path element PE (if any) in P:
a) Let RC and RJ be the referenced_class and resolution_jar of PE.
b) If RJ is not the name of a retained jar, then an exception is raised: Java execution-invalid
jar in path.
c) If RC does not terminate with an "*", and RC is equal to CN, then:
i) If CN is the name of a class C in the jar RJ, then CN resolves to class C.
ii) If CN is not the name of a class in the jar RJ, then an exception is raised: Java
execution: unresolved class name.
d) If RC terminates with an "*" and includes one or more package names P1, P2,...,PK,
then:
i) If the name CN begins with the K package names P1, P2,...,PK, and CN is the name of
a
class C in the jar RJ, then CN resolves to class C.
ii) If CN is not the name of a class in a jar in the schema RSN, then an exception is
raised:
Java execution--unresolved class name.
e) If RC is an "*" with no package names, then:
i) If the name CN is the name of a class C in the jar RJ, then CN resolves to class C.
Common elements
ii) If CN is not the name of a class in a jar in the schema RSN, then continue the above
"For each path element" loop.
3) If the above For each path element loop terminates without having resolved CN,
then an
exception is raised: Java execution--unresolved class name.
Optional Features
1) The SQL-Java path facility is an optional feature.
SQLJ procedures
4. SQLJ PROCEDURES
This section defines the SQLJ built-in procedures.
If, at some time, the ANSI/ISO SQL standards are extended with the SQLJ facilities, the
capabilities of these built-in procedures may be specified as new SQL statements, rather
than as
built-in procedures. This document specifies built-in procedures rather than statements, in
order to
avoid differences with whatever detailed statement syntax may be specified in the SQL
standards.
4.1 SQLJ.INSTALL_JAR procedure

Function
Install a set of Java classes into the current SQL catalog and schema.
Syntax
sqlj.install_jar (
url IN VARCHAR(*),
jar IN VARCHAR(*)
)
sqlj.install_jar_no_deploy (
url IN VARCHAR(*),
jar IN VARCHAR(*)
)

url A character string value having the format of a URL.
The URLs that are valid are implementor-defined, and may include URLs whose format
is
implementor-defined.
The URL must identify a jar file.
jar A character string value having the format specified by the BNF for jar_name in the
section
Jar names.
Description
1) The sqlj.install_jar and sqlj.install_jar_no_deploy procedures are DDL operations,
and
subject to the implementation's rules for performing DDL operations within transactions.
If an
invocation of sqlj.install_jar or sqlj.install_jar_nodeploy raises an exception, then the
effect
on the install actions is implementor-defined.

Language
Programming

2) The maximum lengths of the VARCHAR parameters is implementor-defined.
3) If the value of the url parameter does not identify a valid jar file, then an exception is
raised:
Java DDL--invalid URL.
4) If the value of the jar parameter after removal of leading and trailing space characters,
does not
have the format defined by the jar_name BNF, then an exception is raised: Java DDL-invalid
jar name.
If the catalog_id (if specified) is not the name of the current catalog, or the schema_id (if
specified is not the name of the current schema, then an exception is raised: Java DDL-invalid
jar name.
Let JN be the explicitly or implicitly qualified name catalog_id.schema_id.jar_id.
5) If there is a retained jar in the current catalog and schema whose name is JN, then an
exception
is raised: Java DDL--invalid jar name.
6) The jar is installed with the name JN. All contents of the jar are installed, including
both visible
and non-visible Java classes, and other items contained in the jar. The non-visible Java
classes
and other items can be referenced by other Java methods within the jar.
7) Both visible and non-visible classes are installed. Note: Non-visible classes can be
referenced
by other visible and non-visible Java classes.
8) If the sqlj.install_jar version of the procedure is called (rather than the
sqlj.install_jar_no_deploy version), then if the jar file contains one or more deployment
descriptor files, the install actions implied by those instances are performed. Note:
deployment descriptor files and their install actions are specified in the section
Deployment
Descriptor files.
Privileges
1) The privileges required to invoke the install and install_deploy procedures are
implementation
defined.
2) The current user becomes the owner of the jar.
3) The current user has a grantable usage privilege on the jar.
Optional Features
1) The sqlj.install_jar procedure (as opposed to the sqlj.install_jar_no_deploy
procedure) is an
optional feature. If an implementation does not support sqlj.install_jar, then the
implementation must support the SQLJ extensions of create procedure and create
function.
SQLJ procedures
4.2 SQLJ.REPLACE_JAR procedure

Function
Replace a previously installed jar.
Syntax
sqlj.replace_jar (
url IN VARCHAR(*)
jar IN VARCHAR(*),
)
Rules
url A character string value having the format of a URL.
The URLs that are valid are implementor-defined, and may include URLs whose format
is
The URL must identify a jar file.
section
Jar names.
Description
1) The sqlj.replace_jar procedure is a DDL operation, and subject to the
implementation's rules
for performing DDL operations within transactions. . If an invocation of sqlj.replace_jar
raises an exception, then the effect on the install actions is implementor-defined.
3) If the value of the url parameter identifies a valid jar file, then refer to the classes in
that new jar
file as the new classes. If the value of the url parameter does not identify a valid jar file,
then
an exception is raised: Java DDL--invalid URL.
does not
jar name.
5) If the catalog_id (if specified) is not the name of the current catalog, or the schema_id
(if
jar name.
6) Let JN be the explicitly or implicitly qualified name catalog_id.schema_id.jar_id.

Language
Programming

7) If there is a retained jar with jar name JN, then refer to that jar as the old jar file. Refer
to the
classes in the old jar file as the old classes. If there is not a retained jar with jar_name JN,
then
an exception is raised: Java DDL--invalid jar name
8) Let the matching old (new) classes be the old (new) classes whose fully qualified class
names
are the names of new (old) classes. Let the unmatched old (new) classes be the old (new)
classes that are not matching old (new) classes.
9) Let the dependent SQL names of a jar file be the sql_procedure_names or
sql_function_names
whose create procedure/function statements specify an external_java_reference clause
that
references any method in any class contained in that jar file.
10) If any dependent SQL names of the old jar file reference a method in an unmatched
old class,
then an exception is raised: Java DDL--invalid class deletion.
11) Note: This rule prohibits deleting classes that are referenced by an SQL create
external
statement. This prohibition does not, however, prevent deletion of classes that are
referenced
only indirectly by other Java classes.
12) For each dependent SQL name of the old jar file that references a method in a
matching old
class, let CS be the SQL create statement that created the SQL name. If CS is not a valid
create statement for the corresponding new class, then an exception is raised: Java DDL
invalid replacement.
13) The old jar file and all visible and non-visible old classes are deleted from the current
catalog.
14) Any privilege granted for a dependent SQL name of the old jar file that is referenced
in an
unmatched old class is revoked.
15) The new jar file and all visible and non-visible new classes are installed in the current
catalog
and associated with the specified jar_name. That jar becomes the associated jar of each
new
class. All contents of the new jar are installed, including both visible and non-visible Java
classes, and other items contained in the jar. The non-visible Java classes and other items
can
be referenced by other Java methods within the jar.
Privileges
1) The privileges required to invoke the sqlj.replace_jar procedure are implementation

defined.
2) The current user must be the owner of the specified jar.
SQLJ procedures
4.3 SQLJ.REMOVE_JAR procedure

Function
Remove a Java jar file and its classes from a specified catalog.
Syntax
sqlj.remove_jar( jar IN VARCHAR(*))
sqlj.remove_jar_undeploy( jar IN VARCHAR(*)

section Jar names.
Description
1) The sqlj.remove_jar and sqlj.remove_jar_undeploy procedures are DDL operations,
and
subject to the implementation's rules for performing DDL operations within transaction. .
If an
invocation of sqlj.remove_jar or sqlj.remove_jar_undeploy raises an exception, then
the
effect on the install actions is implementor-defined.
does not
jar name.
jar name.
to the
then
an exception is raised: Java DDL--invalid jar name. Equality of jar names is determined
by
the SQL rules for equivalence of identifiers.
5) If the sqlj.remove_jar_undeploy version of the procedure is called, then if the jar file
contains
one or more instances of the DeploymentDescriptor class, then the remove actions
implied by
those instances are performed. Those actions are specified in the section Deployment
descriptor files. Note that these actions are performed prior to examining the condition
specified in the following step.

Language
Programming

6) Let the dependent SQL names of a jar file be as defined in the sqlj.replace_jar
procedure. I.e.
the sql_procedure_names or sql_function_names whose create procedure/function
statements
specify an external_java_reference clause that references any method in any class
contained in
that jar file.
7) If there are any dependent SQL names of the specified jar file, then an exception is
raised: Java
DDL--invalid class deletion.
Note: This rule prohibits deleting classes that are referenced by an SQL create
external
statement. This prohibition does not, however, prevent deletion of classes that are
referenced
only indirectly by other Java classes.
8) Any privilege granted against a dependent SQL name of the old jar file is revoked.
9) The specified jar file and all visible and non-visible classes contained in it are deleted.
10) The usage privilege on the specified jar file is revoked from all users that have it.
Privileges
1) The privileges required to invoke the sqlj.remove_jar and sqlj.remove_jar_undeploy
procedures are implementation defined.
2) The current user must be the owner of the specified jar.
Optional Features
3) The privileges required to invoke the sqlj.remove_jar and sqlj.remove_jar_undeploy
procedures are implementation defined.
4) It is implementor-defined whether an implementation supports the
sqlj.remove_jar_undeploy
procedure (as opposed to the sqlj.remove_jar procedure). If an implementation does not
support sqlj.remove_jar_undeploy, then the implementation must support the SQLJ
extensions of drop procedure and drop function.
SQLJ procedures
4.4 SQLJ.ALTER_JAVA_PATH procedure

Syntax
sqlj.alter_java_path(jar varchar(*), path varchar(*))
Definitions
jar A character string value having the format for jar_name specified by the section Jar
names.
path A character string value having the format defined for sql_java_path by the section
SQL-Java
paths.
Rules
does not
jar name.
jar name.
3) When the SQLJ.alter_java_path procedure is called, the current catalog and schema
at the
time of the call are the default for each omitted catalog_id and schema_id in the
resolution_jars
of the path parameter. Those defaults apply to any subsequent use of the path as specified
below.
4) If the value of the path parameter does not have the format for sql_java_path defined
by the
section SQL-Java paths, then an exception is raised: Java DDL--invalid path name.
Note that the path parameter can be an empty or all-blank string.
5) The value of the path parameter becomes the path associated with the jar denoted by
JN,
replacing the current path (if any) associated with that jar.
6) If an invocation of the sqlj.alter_java_path procedure raises an exception , then effect
on the
path actions is implementation defined.

Language
Programming
Privileges
1) The privileges required to invoke the sqlj.alter_java_path procedure are
implementation
defined.
2) The current user must be the owner of the jar named JN in the current catalog and
schema.
3) The current user must have the usage privilege on each jar referenced in the path
parameter.
Optional Features
5) The SQLJ.alter_java_path procedure is an optional feature.
SQL extensions
5. SQL EXTENSIONS
5.1 CREATE PROCEDURE/FUNCTION statement
Function
Specify an SQL name for a Java method.
Syntax
create_procedure_statement ::=
create procedure sql_procedure_name sql_procedure_signature
sql_properties
[ deterministic | not deterministic ]
external_java_reference
create_function_statement ::=
create function sql_function_name sql_function_signature
sql_properties
[ deterministic | not deterministic ]
[ return null on null input | call on null input]
external_java_reference
sql_procedure_name ::= [[identifier1.]identifier2.]identifier3
sql_function_name ::= [[identifier1.]identifier2.]identifier3
sql_procedure_signature ::= ( [sql_parameters])
sql_function_signature ::= ( [sql_parameters]) returns sql_datatype
sql_parameters ::= sql_parameter [{, sql_parameter}]
sql_parameter ::= [parameter_mode] sql_identifier sql_datatype
parameter_mode ::= in | out | inout
sql_properties ::= [data_access_indication] [dynamic result sets integer]
data_access_indication ::=
no sql
| contains sql
| reads sql data
| modifies sql data
external_java_reference ::=
external name 'method_name [java_signature]'
language java
parameter style java

Language
Programming

method_name ::= jar_name : java_method_name
jar_name ::= see the section Jar names.
java_method_name ::= java_class_name.method_identifier
java_class_name ::= [packages.]class_identifier
packages ::= package_identifier[.package_identifier]
package_identifier ::= java_identifier
class_identifier ::= java_identifier
method_identifier ::= java_identifier
java_signature ::= ( [ java_parameters ]) returns java_datatype
java_parameters ::= java_datatype [{, java_datatype}]
java_datatype ::= --See below.
Rules
create procedure A form of the create procedure statement that specifies an SQL
procedure
name and signature for a Java method.
create function A form of the create function statement that specifies an SQL function
name
and signature for a Java method.
sql_procedure_name, sql_function_name The qualified SQL name of the procedure or
function.
The identifiers identifier1, identifier2, and identifier3 are the three elements of an SQL 3part name. The defaults for identifier1 and identifier2 are determined by normal SQL
rules.
sql_properties Specifies the kind of SQL actions that the Java method can perform, and
indicates
whether the Java method returns SQL result sets.
The sql_properties clause is also used in the method declarations in the SQL create type
statements of SQLJ Part 2.
data_access_indication Specifies the SQL facilities that the Java method is allowed to
perform.
The restrictions apply directly to the specified method itself and to any methods that it
invokes, directly or indirectly.
If you don't specify a data_access_indication, then contains sql is the default.
no sql The method cannot invoke SQL operations.
contains sql The method can invoke SQL operations, but cannot read or modify SQL
data. I.e.
the method cannot perform SQL open, close, fetch, select, insert, update, or delete
operations.
reads sql data The method can invoke SQL operations, and can read SQL data, but
cannot
modify SQL data. I.e. the method cannot perform SQL insert, update, or delete
operations.
SQL extensions
modifies sql data The method is allowed invoke SQL operations and to read and
modify SQL
data.
dynamic result sets Specifies that the Java method may return SQL result sets.
dynamic result sets can only be specified in a create procedure statement, not in a
create
function statement.
The specified integer value is the maximum number of result sets that the method will
return. The maximum value of that integer is implementor-defined.
Further rules for the dynamic result sets clause are specified in the Description below.
deterministic Specifies that for a given set of argument values, the procedure or
function always
returns the same values for out and inout parameters and function result. The
implementation is therefore permitted to retain lists of argument and result values from an
invocation of the procedure or function, and to return those result values for subsequent
invocations that specify the same argument values without executing the procedure or
function on those subsequent invocations.
not deterministic Specifies that the procedure or function does not have the
deterministic
property. This is the default, if neither deterministic nor not deterministic is specified.
return null on null input and call on null input Specify the action to be taken when
an
argument of a function call is null.
If you specify return null on null input, then at runtime if the value of any argument is
null, then the result of the function is set to null, and the function body is not invoked.
If you specify call on null input, then at runtime normal actions are taken for null
arguments, as specified in the section SQLJ function call.
If you don't specify either return null on null input or call on null input, then call on
null
input is the default.
external Specifies that the create statement defines an SQL name for a routine written
in a
programming language other than SQL.
parameter style java Specifies that the runtime conventions for arguments passed to
the external
routine are those of the Java programming language.
language java Specifies that the external routine is written in Java.
name - Specifies the name of a Java method. A reference to the SQL routine_name is
effectively
a synonym for the specified Java method.
The external name is specified in a character string literal. The surrounding single-quotes
are the delimiters of that literal. The format shown within those quotes in the above BNF
is
BNF symbols and punctuation. I.e. square brackets are BNF optionality markers, names
are
BNF symbols, and round parentheses are literal characters.
The character set supported for the method_name is implementor-defined.

Language
Programming

java_method_name The name of one or more Java methods in the specified jar. The
java_method_name must be a fully qualified Java class name and method name.
sql_procedure_signature Specifies the SQL parameter datatypes for a procedure.
The rules for the signature are specified in the Description below.
The sql_procedure_signature clause is also used in the method declarations in the SQL
create type statements of SQLJ Part 2.
sql_function_signature Specifies the SQL parameter and result datatypes for a function.
The sql_function_signature clause is also used in the method declarations in the SQL
create
type statements of SQLJ Part 2.
SQL_parameter Specifies a parameter of the routine.
SQL_parameter_name The name of an SQL parameter.
parameter_mode Specifies whether the SQL parameter is input only (in), output-only
(out) or
both input and output (inout).
The parameter_mode may only be specified in an sql_procedure_signature.
If you do not specify the parameter_mode, parameter_mode in is the default.
sql_datatype An SQL datatype. Constraints on the sql_datatype are specified in the
Description
below.
returns Specifies the result datatype of the function.
java_signature Specifies the signature of the referenced Java method. Rules for the
java_signature are specified in the Description below.
java_datatype Either void or a mappable Java datatype, as specified in the Definitions
below.
The java_datatype names are case sensitive. Other rules for the java_datatype are
specified
in the Description below.
Definitions
1) A Java datatype JT is simply mappable to an SQL datatype ST iff JT and ST are
specified
respectively in column 1 and column 2 of a row of Standard mapping from Java types
to
SQL types or Extended mapping from Java classes to SQL types.
2) A Java datatype JT is output mappable to an SQL datatype ST iff JT is a one
dimensional array
of a datatype JT2 that is simply mappable to ST. I.e. JT is "JT2[ ]".
3) A Java datatype JT is mappable to an SQL datatype ST iff JT is simply mappable to ST
or JT is
output mappable to ST.
4) A Java class is result set oriented iff it is either:
SQL extensions
a) The Java ResultSet class or of a subclass of that class.
b) A class that implements the Java interface sqlj.runtime.ResultSetIterator, or a subclass
of
such a class. Note: these classes are generated by SQLJ Embedded SQL iterator
declarations ("#sql iterator").
5) A Java datatype is result set mappable iff it is an array of a result set oriented class.
6) A Java method is mappable (to SQL) iff the datatype of each parameter is either
mappable or
result set mappable and the result type is either a mappable datatype, or is void.
7) A Java method is visible in SQL iff it is public, static, and mappable.
Description
1) Determination and validation of the Java signature:
The following steps determine and validate the explicit or implicit java_signature, JS. If
any of
the requirements specified in these steps do not hold, then an exception is raised: Java
DDL-invalid signature.
Case
a) If the unqualified identifier of the java_method_name is main, then:
i) The statement must be a create procedure.

ii) If a java_signature JS is specified, then it must be the following:
public static void main(String[ ]);
iii) If a java_signature is not specified, then JS is the following signature:
iv) The sql_procedure_signature must be either:
(1) A single parameter, which is an SQL array of CHAR or VARCHAR. At runtime,
this parameter is passed as a Java array of String. Note: This signature can only be
specified if the SQL system supports array datatypes in SQL.
(2) Zero or more parameters, each of which is CHAR or VARCHAR. At runtime, these
parameters are passed as a Java array of String (with possibly zero elements).
b) If a java_signature is not specified, then a java_signature, JS, is determined from the
specified sql_procedure_signature or sql_function_signature, SS, as follows:
i) For any SQL datatype ST, let the corresponding Java datatype JT be the datatype
determined by the SQL Java datatype mappings defined by Standard mapping from
SQL types to Java types .
ii) For each parameter P of SS whose parameter_mode is in, or that does not specify an
explicit parameter_mode, let the corresponding Java parameter datatype of P be the
corresponding Java datatype of the parameter_datatype of P.
iii) For each parameter P of SS whose parameter mode is inout or out, let JT be the
corresponding Java datatype of the parameter_datatype of P, and let the corresponding
Java parameter datatype of P be an array of JT, i.e. be JT[ ].atement:
SQL extensions
Optional Features
1) The drop procedure and drop function statements can be specified either within
deployment
descriptor files or as SQL DDL statements. It is implementor-defined whether an
implementation supports these statements only in deployment descriptor files, only as
SQL
DDL statements outside of deployment descriptors, or both.

Language
Programming
5.3 GRANT statement

Function
Extend the SQL grant statement for the usage privilege on Java jars.
Format
grant_statement ::=
grant usage on jar_name to grantee [with grant option];
grantee ::= sql_identifier
Rules
1) Let JN be the jar_name. JN must be the name of an installed jar.
2) The grantee receives the usage privilege on the jar denoted by JN in the current
catalog and
schema. If with grant option is specified, then the privilege is grantable.
Privileges
schema.
Optional features
1) The grant statement for jars is optional.
2) The with grant option clause for jars is optional.
SQL extensions
5.4 REVOKE statement

Function
Extend the SQL revoke statement for the usage privilege on Java jars.
Format
Revoke_statement ::=
revoke usage on jar_name from grantee restrict;
Rules
to the
then
an exception is raised: Java DDL--invalid jar name.
3) If any jar owned by the grantee specifies a path in which JN is listed as a
resolution_jar, then an
exception is raised: Invalid REVOKE.
4) If the create procedure/function statement for any existing SQL procedure or
function was
executed by the grantee and specified an external name clause that references JN, then
an
5) If the grantee had the usage privilege on the jar denoted by JN, then that privilege is
revoked.
Note: There is no exception if the grantee did not have the usage privilege on jar JN.
6) After the above actions for revoke are performed there must be no abandoned SQLJava paths
or SQL routines.
Privileges
schema.
Optional features
1) The revoke statement for jars is optional.

Language
Programming
5.5 SQLJ function call

Function
Call an SQLJ method as an SQL function.
Syntax
sqlj_function_call ::= sql_routine_name ([arguments])
arguments ::= expression [{,expression}]

sql_function_call The syntax of an SQL function call.
Sql_routine_name A 3-part SQL name, with normal rules for defaulting the first two
parts.
Description
1) The sql_routine_name must be an sql_routine_name specified in one or more create
function
statements.
2) SQL overloading rules are applied to the sql_routine_name and the datatypes of the
arguments
to identify a particular SQL create function statement, CF. Let JF be the Java method
identified by CF.
Common Actions
The following actions are referenced in the section SQLJ method calls in SQLJ Part 2.
3) If CF specifies return null on null input, then if the runtime value of any argument is
null,
return a null value as the result of the function. In this case the following steps of this
Description do not apply to this call of the function.
4) If CF specifies call on null input, or specifies neither return null on null input nor
call on
null input, then for each parameter of JF whose Java datatype is boolean, byte, short,
int,
long, float, or double, if the runtime value of the corresponding argument is an SQL null,
then
an exception is raised: Java DDL--invalid null.
5) Execute the Java method JF.
a) Whether this execution is performed with the user-name of the user who created the
create function statement CF, or with the user-name of the current user is
implementation defined.
b) The scope and persistence of any modifications of static variables that are made during
the execution is implementor-defined.
SQL extensions
6) If the method execution completes with an uncaught Java exception, E, then:
a) An SQL exception is raised with the SQLSTATE value specified in SQLSTATE class
and subclass values.
b) Perform no further actions for the function call.
7) Return the value of the method execution as the value of the sqlj_function_call.

Language
Programming
5.6 SQLJ procedure call

Function
Call an SQLJ method as an SQL stored procedure.
SQL procedure calls are specified in SQL/PSM, in proprietary SQL procedural
languages, and in
remote procedure call facilities of CLI, ODBC, and JDBC.
Syntax
sqlj_procedure_call ::= call sql_routine_name ([arguments])

sql_procedure_call The syntax of an SQL procedure call.
parts.
Description
procedure
statements.
2) SQL overloading rules are applied to the sql_routine_name and the number of
arguments to
identify a particular SQL create procedure statement, SP. Let JSP be the Java method
identified by SP.
Common Actions
3) For each parameter of JF whose Java datatype is boolean, byte, short, int, long, float,
or
double, or is an array of such a datatype, if the parameter mode of the corresponding
parameter of SP is in or inout and the runtime value of the corresponding argument is an
SQL
null, then an exception is raised: Java executioninvalid null value.
4) For each parameter P of SP whose parameter mode is out or inout:
a) Let TP be the SQL parameter_datatype of P, and let JTP be the Java datatype of the
corresponding parameter of JSP.
b) Let A be the value of the argument of the procedure call that corresponds with P.
c) Let PA be a Java array of length 1 and datatype JTP. I.e. a Java object new JTP[1].
d) If the parameter mode is inout, then set PA[0] to A.
SQL extensions
e) Replace A with PA in the arguments passed to JSP.
5) For each parameter P of SP whose Java datatype is result set mappable, generate a oneelement
array of the specified type containing a single null element, and supply that array as an
implicit
argument.
6) Execute JSP.
a) Let A and PA be as defined above.
b) Set the value of A to the contents of PA[0].
8) If SP specifies dynamic result sets, then:
a) Let RSN be a set containing the first element of each of the arrays generated above for
the result set mappable parameters. Let RS be the non-null elements of RSN.
b) If RS contains more result sets than the integer specified in the dynamic result sets
clause of SP, then an exception is raised: Java executiontoo many result sets.
c) Process the elements of RS as SQL result sets in the order in which they were opened
in
SQL.

Language
Programming

create
(out) or
Description
below.
below.
specified
Definitions
specified
to
dimensional array
or JT is
4) A Java class is result set oriented iff it is either: SQLJ: SQL Routines using
the Java
Programming Language

create
(out) or
Description
below.
below.
specified
Definitions
specified
to
dimensional array
or JT is
4) A Java class is result set oriented iff it is either:
SQL extensions
a) The Java ResultSet class or of a subclass of that class.
b) A class that implements the Java interface sqlj.runtime.ResultSetIterator, or a subclass
of
such a class. Note: these classes are generated by SQLJ Embedded SQL iterator
declarations ("#sql iterator").
5) A Java datatype is result set mappable iff it is an array of a result set oriented class.
6) A Java method is mappable (to SQL) iff the datatype of each parameter is either
mappable or
result set mappable and the result type is either a mappable datatype, or is void.
7) A Java method is visible in SQL iff it is public, static, and mappable.
Description
1) Determination and validation of the Java signature:
The following steps determine and validate the explicit or implicit java_signature, JS. If
any of
the requirements specified in these steps do not hold, then an exception is raised: Java
DDL-invalid signature.
Case
a) If the unqualified identifier of the java_method_name is main, then:
i) The statement must be a create procedure.
ii) If a java_signature JS is specified, then it must be the following:
iii) If a java_signature is not specified, then JS is the following signature:
iv) The sql_procedure_signature must be either:
(1) A single parameter, which is an SQL array of CHAR or VARCHAR. At runtime,
this parameter is passed as a Java array of String. Note: This signature can only be
specified if the SQL system supports array datatypes in SQL.
(2) Zero or more parameters, each of which is CHAR or VARCHAR. At runtime, these
parameters are passed as a Java array of String (with possibly zero elements).
b) If a java_signature is not specified, then a java_signature, JS, is determined from the
specified sql_procedure_signature or sql_function_signature, SS, as follows:
i) For any SQL datatype ST, let the corresponding Java datatype JT be the datatype
determined by the SQL Java datatype mappings defined by Standard mapping from
SQL types to Java types .
ii) For each parameter P of SS whose parameter_mode is in, or that does not specify an
explicit parameter_mode, let the corresponding Java parameter datatype of P be the
corresponding Java datatype of the parameter_datatype of P.
iii) For each parameter P of SS whose parameter mode is inout or out, let JT be the
corresponding Java datatype of the parameter_datatype of P, and let the corresponding
Java parameter datatype of P be an array of JT, i.e. be JT[ ].

Language
Programming

iv) The java_parameters of JS is a list of the corresponding Java parameter datatypes of
SS.
Note that JS does not specify parameter names. I.e. the parameter names of the Java
method do not have to match the SQL parameter names.
v) If the create statement is a create procedure that specifies dynamic result sets N, for
some integer N, then the java_parameters of JS include N additional right-most
parameters, each of which has the following type:
ResultSet[ ].
vi) The java_datatype, JRT, specified after returns in JS is determined as follows:
Case:
If the create statement is a create procedure, then JRT is void.
If the create statement is a create function whose returns datatype is SRT, then
JRT is the corresponding Java datatype of SRT.
c) If a java_signature, JS, is specified, then:
i) Let SS be the sql_procedure_signature or sql_function_signature.
ii) Let JPN be the number of java_datatypes in JS, and SPN be the number of
sql_parameters in SS.
iii) If the create statement is not a create procedure that specifies dynamic result sets,
then JPN must be equal to SPN.. If the create statement is a create procedure that
specifies dynamic result sets, then JPN must be greater than SPN, and each
java_datatype in JS whose ordinal position is greater than SPN must be result set
mappable.
iv) For each sql_parameter SP in SS, let JT be the corresponding java_datatype in JS.:
(1) If SP specifies in, or inout, or does not specify a parameter_mode, then JT must be
simply mappable to SRT.
(2) If SP specifies out or inout, then JT must be output mappable to SRT.
v) Let JRT be the java_datatype specified in the java_signature after returns.
vi) Case:
(1) If the create statement is a create procedure, then JRT must be void.
(2) If the create statement is a create function, then let SRT be the sql_datatype
specified in the create function after returns. JRT must be simply mappable to
SRT.
2) Let JN be the jar_name specified in the method_name of the external name clause. JN
must
be the name of an installed jar.
3) If there is exactly one visible Java method in JN with the specified java_method_name
and
signature JS, then the create procedure or create function statement is associated with
that
Java method. Otherwise, an exception is raised: Java DDL--invalid method specification
Privileges
SQL extensions
1) The current user must have the usage privilege on the jar referenced in the external
name
clause.
2) The privilege rules of a normal SQL create procedure/function statement apply.
Optional Features
1) The create procedure and create function statements can be specified either within
deployment descriptor files or as SQL DDL statements. It is implementor-defined
whether an
SQL
2) Overloading external Java SQL procedure and function names is an optional feature.
If the implementation does not support overloading, then the sql_procedure_name
(sql_function_name) must not be the same as an existing sql_procedure_name or
sql_function_name.
3) The SQL array datatype is an optional feature.
If the implementation does not support array datatypes in SQL, then the
sql_procedure_signature must not specify an sql_datatype that is an array datatype. Note:
This
applies in particular to the sql_procedure_signature for a java_method_name of main.

Language
Programming
5.2 DROP PROCEDURE/FUNCTION statement

Function
Drop an SQL name for a Java method.
Syntax
drop_routine_statement ::=
drop [procedure | function] sql_routine_name [(sql_datatype [{,sql_datatype}
])]
restrict

sql_routine_name The SQL name that is the name of one or more SQL procedures or
functions.
Sql_datatype A list of parameter datatypes.
Description
1) If the list of sql_datatypes is omitted, then there must be exactly one SQL procedure or
function, SR, with the specified sql_routine_name. Otherwise, an exception is raised:
Java
DDL--invalid routine name.
2) If a list of N sql_datatypes is specified, then there must be exactly one SQL procedure
or
function, SR, with the specified sql_routine_name and with N parameters whose
parameter_datatypes are the same as the sql_datatypes. Otherwise, an exception is raised:
Java DDL--invalid routine name.
3) The restrict clause is as defined in SQL.
4) The definition of SR is deleted from the SQL system catalogs.
4) Any privileges granted against SR are revoked.
5) Note: A drop statement that specifies an sql_routine_name that designates an SQLJ
method:
a) Has no effect on that SQLJ method.
b) Has no effect on any procedure calls or function calls that reference the
sql_routine_name. Execution of any such procedure call or function call will generate
an exception: Java executionunresolved name.
Privileges
1) The privilege rules are those of the SQL create procedure statement.
SQL extensions
Optional Features
1) The drop procedure and drop function statements can be specified either within
deployment
descriptor files or as SQL DDL statements. It is implementor-defined whether an
SQL

Language
Programming
5.3 GRANT statement

Function
Extend the SQL grant statement for the usage privilege on Java jars.
Format
grant_statement ::=
grant usage on jar_name to grantee [with grant option];
Rules
2) The grantee receives the usage privilege on the jar denoted by JN in the current
catalog and
schema. If with grant option is specified, then the privilege is grantable.
Privileges
schema.
Optional features
1) The grant statement for jars is optional.
2) The with grant option clause for jars is optional.
SQL extensions
5.4 REVOKE statement

Function
Extend the SQL revoke statement for the usage privilege on Java jars.
Format
Revoke_statement ::=
revoke usage on jar_name from grantee restrict;
Rules
to the
then
an exception is raised: Java DDL--invalid jar name.
3) If any jar owned by the grantee specifies a path in which JN is listed as a
resolution_jar, then an
4) If the create procedure/function statement for any existing SQL procedure or
function was
executed by the grantee and specified an external name clause that references JN, then
an
5) If the grantee had the usage privilege on the jar denoted by JN, then that privilege is
revoked.
Note: There is no exception if the grantee did not have the usage privilege on jar JN.
6) After the above actions for revoke are performed there must be no abandoned SQLJava paths
or SQL routines.
Privileges
schema.
Optional features
1) The revoke statement for jars is optional.

Language
Programming
5.5 SQLJ function call

Function
Call an SQLJ method as an SQL function.
Syntax
sqlj_function_call ::= sql_routine_name ([arguments])

sql_function_call The syntax of an SQL function call.
parts.
Description
function
statements.
2) SQL overloading rules are applied to the sql_routine_name and the datatypes of the
arguments
to identify a particular SQL create function statement, CF. Let JF be the Java method
identified by CF.
Common Actions
3) If CF specifies return null on null input, then if the runtime value of any argument is
null,
return a null value as the result of the function. In this case the following steps of this
Description do not apply to this call of the function.
4) If CF specifies call on null input, or specifies neither return null on null input nor
call on
null input, then for each parameter of JF whose Java datatype is boolean, byte, short,
int,
long, float, or double, if the runtime value of the corresponding argument is an SQL null,
then
an exception is raised: Java DDL--invalid null.
5) Execute the Java method JF.
SQL extensions
7) Return the value of the method execution as the value of the sqlj_function_call.

Language
Programming
5.6 SQLJ procedure call

Function
Call an SQLJ method as an SQL stored procedure.
SQL procedure calls are specified in SQL/PSM, in proprietary SQL procedural
languages, and in
remote procedure call facilities of CLI, ODBC, and JDBC.
Syntax
sqlj_procedure_call ::= call sql_routine_name ([arguments])

sql_procedure_call The syntax of an SQL procedure call.
parts.
Description
procedure
statements.
2) SQL overloading rules are applied to the sql_routine_name and the number of
arguments to
identify a particular SQL create procedure statement, SP. Let JSP be the Java method
identified by SP.
Common Actions
3) For each parameter of JF whose Java datatype is boolean, byte, short, int, long, float,
or
double, or is an array of such a datatype, if the parameter mode of the corresponding
parameter of SP is in or inout and the runtime value of the corresponding argument is an
SQL
null, then an exception is raised: Java executioninvalid null value.
a) Let TP be the SQL parameter_datatype of P, and let JTP be the Java datatype of the
corresponding parameter of JSP.
b) Let A be the value of the argument of the procedure call that corresponds with P.
c) Let PA be a Java array of length 1 and datatype JTP. I.e. a Java object new JTP[1].
d) If the parameter mode is inout, then set PA[0] to A.
SQL extensions
e) Replace A with PA in the arguments passed to JSP.
5) For each parameter P of SP whose Java datatype is result set mappable, generate a oneelement
array of the specified type containing a single null element, and supply that array as an
implicit
argument.
6) Execute JSP.
a) Let A and PA be as defined above.
b) Set the value of A to the contents of PA[0].
8) If SP specifies dynamic result sets, then:
a) Let RSN be a set containing the first element of each of the arrays generated above for
the result set mappable parameters. Let RS be the non-null elements of RSN.
b) If RS contains more result sets than the integer specified in the dynamic result sets
clause of SP, then an exception is raised: Java executiontoo many result sets.
c) Process the elements of RS as SQL result sets in the order in which they were opened
in
SQL.
Java topics
6. JAVA TOPICS
6.1 Datatype mapping
Error! Reference source not found. and Error! Reference source not found. are taken from
the cited
sections of JDBC. Error! Reference source not found. specifies additional type
correspondences
that are used by SQLJ.
The correspondence specified by a given row of any of these tables applies iff an
implementation
supports the SQL type specified in that row.
SQL type Java type
CHAR String
VARCHAR String
NUMERIC java.math.BigDecimal
DECIMAL java.math.BigDecimal
BIT Boolean
TINYINT Byte
SMALLINT Short
INTEGER Int
BIGINT Long
REAL Float
FLOAT Double
DOUBLE Double
BINARY byte[]
VARBINARY byte[]
LONG VARBINARY byte[]
DATE java.sql.Date
TIME java.sql.Time
TIMESTAMP java.sql.Timestamp
Standard mapping from SQL types to Java types

Language
Programming

Java type SQL type
String VARCHAR
String VARCHAR or LONGVARCHAR
Java.math.BigDecimal NUMERIC
boolean BIT
byte TINYINT
short SMALLINT
int INTEGER
long INTEGER
float REAL
double DOUBLE
byte[] VARBINARY
java.sql.Date DATE
java.sql.Time TIME
java.sql.Timestamp TIMESTAMP
Standard mapping from Java types to SQL types
Java class SQL type
java.lang.Double DOUBLE
java.lang.Float REAL
java.lang.Integer INTEGER
java.lang.Long INTEGER
Extended mapping from Java classes to SQL types
Java topics
6.2 Java facilities supported by SQLJ

SQL systems that implement SQLJ will support the package java.sql, which is the JDBC
driver.
The other Java packages supplied by SQL systems that implement SQLJ are
In an SQL system that implements SQLJ, the package java.sql supports the following
data source
URL for obtaining a connection to the current SQL system, SQL session, and SQL
transaction:
jdbc:default:connection
A connection established with this URL is referred to as the default connection. The
default
connection has the following characteristics:
The default connection is pre-allocated to provide efficient access to the database.
The default connection is included in the current session and transaction.

The authorization ID of the default connection is the current authorization ID.
The JDBC AUTOCOMMIT setting of the default connection is false.
Other data source URLs that are supported by java.sql are implementor-defined.

Language
Programming
6.3 Deployment descriptor files

Function
Supply information for actions to be taken by the sqlj.install_jar and sqlj.remove_jar
procedures.
Model
A deployment descriptor file is a text file contained in a jar file, which is specified with
the
following property in the manifest for the jar file:
Name: file_name
SQLJDeploymentDescriptor: TRUE
Properties
The text contained in a deployment descriptor file must have the following form:
descriptor_file ::=
SQLActions [ ] = { [ action_group [ , action_group ] ] }
action_group ::= install_actions | remove_actions
install_actions ::=
BEGIN INSTALL [ command ; ]END INSTALL
remove_actions ::=
BEGIN REMOVE [ command ; ]END REMOVE
command ::= sql_statement | implementor_block
sql_statement ::= --See below
implementor_block ::=
BEGIN implementor_name sql_token END implementor_name
implementor_name ::= sql_identifier
sql_token ::= --See below
1) The SQLActions must contain at most one install_actions and at most one
remove_actions.
2) The commands specified in the install_actions (if any) and remove_actions (if any)
specify the
install actions and remove actions of the deployment descriptor file.
3) An sql_statement specified in an install_actions must be either:
a) A create procedure or create function statement that specifies externallanguage
java.
The procedures and functions created by those statements are called the deployed
routines
of the deployment descriptor file.
b) A grant statement that specifies the execute privilege for a deployed routine.
Java topics
4) When a deployment descriptor file is executed by a call of sqlj.install_jar_deploy, if
the
jar_name of any external name clause of a create procedure/function statement in an
install_actions is the jar_name thisjar, then thisjar is replaced with the jar_name
parameter
of the sqlj.install_jar_deploy.
5) An sql_statement specified in a remove_actions must be either:
a) A drop procedure or drop function statement for a deployed routine.
b) A revoke statement for the execute privilege on a deployed routine.
6) An implementor_block specifies implementation-specific install actions and remove
actions.
a) An sql_token is an SQL lexical unit specified by the term <token> in the SQL
standard.
I.e. the comments, quotes, and double-quotes in an implementor_block must follow SQL
token conventions.
b) An implementor_name is an implementor-defined SQL identifier. The
implementor_names
specified following the BEGIN and END keywords must be the same.
c) Whether an implementor_block with a given implementor_name contained in an
install_actions (remove_actions) is interpreted as an install action (remove action) is
implementor-defined. I.e. an implementation may or may not perform install or remove
actions specified by some other implementation.
7) The deployment descriptor file format corresponds to the more general notion of a
properties
file supporting indexed properties. Therefore the deployment descriptor file can be used
by the
SQL system to instantiate a Java Bean having an indexed property, SQLRoutines. You
can
then customize the resulting Java Bean instance with ordinary Java Bean tools. For
example,
you can change the SQL procedures or permissions by changing the routine descriptors
stored
in the SQLRoutines property. The SQL system can then use the customized Java Bean
instance to generate a modified version of the deployment descriptor file to use in a
revised
version of the jar file.
Open Issues
7. STATUS CODES
7.1 Class and subclass values for uncaught Java
exceptions
When the execution of a Java method completes with an uncaught Java exception, E,
then:
1) Let ES be the result of the following Java method call:
E.toString( )
2) The format of ES is defined in JAVA [20.22.4] to be the concatenation of three strings,
S1, S2,
and S3. S1 is the name of the class of the exception object E, S2 is : (a colon and
space), and
S3 is the possibly empty string specified as an argument when the object E was created.
3) Case:
a) If the first 15 characters of S3 are SUBSTRING(nnmmm), where SUBSTRING is
not
case sensitive, and nn and mmm are either digits or upper case Latin letters, then let C be
nn
and SC be mmm.
b) If the first 13 characters of S3 are SUBSTRING(mmm), where SUBSTRING is not
case
sensitive, and mmm is either digits or upper case Latin letters, then let C be 46 and SC
be
mmm.
c) Otherwise, let C be 46 and SC be 000.
d) The class and subclass of the SQLSTATE for the exception are C and SC.
e) The message text associated with the exception is ES.

Language
Programming
7.2 SQLSTATE
The SQLSTATE class and subclass values for SQLJ Part 1 facilities are as follows:
Condition Class Subcondition Subclass
Java DDL 46 Invalid URL 001
Java DDL 46 Invalid jar name 002
Java DDL 46 Invalid class deletion 003
Java DDL 46 Invalid jar name 004
Java DDL 46 Invalid replacement 005
Java DDL 46 Invalid grantee 006
Java DDL 46 Invalid signature 007
Java DDL 46 Invalid method specification 008
Java DDL 46 Invalid REVOKE 009
Java execution 46 Invalid null value 101
Java execution 46 Invalid jar name in path 102
Java execution 46 Unresolved class name 103
Java execution 46 Too many result sets 104
Uncaught Java exception 46 (no subclass) 200
Uncaught Java exception 46 User-defined (see above) mmm
User-defined (see above) nn User-defined (see above) mmm
SQLSTATE class and subclass values

Language
Programming

iv) The java_parameters of JS is a list of the corresponding Java parameter datatypes of
SS.
Note that JS does not specify parameter names. I.e. the parameter names of the Java
method do not have to match the SQL parameter names.
v) If the create statement is a create procedure that specifies dynamic result sets N, for
some integer N, then the java_parameters of JS include N additional right-most
parameters, each of which has the following type:
ResultSet[ ].
vi) The java_datatype, JRT, specified after returns in JS is determined as follows:
Case:
If the create statement is a create procedure, then JRT is void.
If the create statement is a create function whose returns datatype is SRT, then
JRT is the corresponding Java datatype of SRT.
c) If a java_signature, JS, is specified, then:
i) Let SS be the sql_procedure_signature or sql_function_signature.
ii) Let JPN be the number of java_datatypes in JS, and SPN be the number of
sql_parameters in SS.
iii) If the create statement is not a create procedure that specifies dynamic result sets,
then JPN must be equal to SPN.. If the create statement is a create procedure that
specifies dynamic result sets, then JPN must be greater than SPN, and each
java_datatype in JS whose ordinal position is greater than SPN must be result set
mappable.
iv) For each sql_parameter SP in SS, let JT be the corresponding java_datatype in JS.:
(1) If SP specifies in, or inout, or does not specify a parameter_mode, then JT must be
simply mappable to SRT.
(2) If SP specifies out or inout, then JT must be output mappable to SRT.
v) Let JRT be the java_datatype specified in the java_signature after returns.
vi) Case:
(1) If the create statement is a create procedure, then JRT must be void.
(2) If the create statement is a create function, then let SRT be the sql_datatype
specified in the create function after returns. JRT must be simply mappable to
SRT.
2) Let JN be the jar_name specified in the method_name of the external name clause. JN
must
be the name of an installed jar.
3) If there is exactly one visible Java method in JN with the specified java_method_name
and
signature JS, then the create procedure or create function statement is associated with
that
Java method. Otherwise, an exception is raised: Java DDL--invalid method specification
Privileges
SQL extensions
1) The current user must have the usage privilege on the jar referenced in the external
name
clause.
2) The privilege rules of a normal SQL create procedure/function statement apply.
Optional Features
1) The create procedure and create function statements can be specified either within
deployment descriptor files or as SQL DDL statements. It is implementor-defined
whether an
SQL
2) Overloading external Java SQL procedure and function names is an optional feature.
If the implementation does not support overloading, then the sql_procedure_name
(sql_function_name) must not be the same as an existing sql_procedure_name or
sql_function_name.
3) The SQL array datatype is an optional feature.
If the implementation does not support array datatypes in SQL, then the
sql_procedure_signature must not specify an sql_datatype that is an array datatype. Note:
This
applies in particular to the sql_procedure_signature for a java_method_name of main.

Language
Programming
5.2 DROP PROCEDURE/FUNCTION statement

Function
Drop an SQL name for a Java method.
Syntax
drop_routine_statement ::=
drop [procedure | function] sql_routine_name [(sql_datatype [{,sql_datatype}
])]
restrict

sql_routine_name The SQL name that is the name of one or more SQL procedures or
functions.
Sql_datatype A list of parameter datatypes.
Description
1) If the list of sql_datatypes is omitted, then there must be exactly one SQL procedure or
function, SR, with the specified sql_routine_name. Otherwise, an exception is raised:
Java
DDL--invalid routine name.
2) If a list of N sql_datatypes is specified, then there must be exactly one SQL procedure
or
function, SR, with the specified sql_routine_name and with N parameters whose
parameter_datatypes are the same as the sql_datatypes. Otherwise, an exception is raised:
Java DDL--invalid routine name.
3) The restrict clause is as defined in SQL.
4) The definition of SR is deleted from the SQL system catalogs.
4) Any privileges granted against SR are revoked.
5) Note: A drop statement that specifies an sql_routine_name that designates an SQLJ
method:
a) Has no effect on that SQLJ method.
b) Has no effect on any procedure calls or function calls that reference the
sql_routine_name. Execution of any such procedure call or function call will generate
an exception: Java executionunresolved name.
Privileges
1) The privilege rules are those of the SQL create procedure statement.

SQLJ Tutorial

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SQLJ Tutorial

Uploaded by

Copyright:

Available Formats

Tutorial

10/16/98 Copyright 1998, Sybase, Inc. All Rights Reserved Page 19

2.16 Dropping SQL names of Java methods

-SQLJ: SQL Routines using the Java

2.17 Removing Java classes from SQL

2.18 Replacing Java classes in SQL

SQLJ: SQL Routines using the Java

Page 22 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

2.21 Deployment descriptors

external name thisjar:Routines1.region

SQLJ: SQL Routines using the Java

Page 24 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

SQLJ: SQL Routines using the Java

Page 26 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

packages, will be resolved in the property_jar and project_jar, respectively.

2.23 SQL Privileges

You must be the owner of the specified jar.

Definitions and Rules

SQLJ: SQL Routines using the Java

Page 30 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

3.2 SQL-Java paths

4.1 SQLJ.INSTALL_JAR procedure

Definitions and Rules

SQLJ: SQL Routines using the Java

Page 34 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

4.2 SQLJ.REPLACE_JAR procedure

SQLJ: SQL Routines using the Java

Page 36 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

1) The privileges required to invoke the sqlj.replace_jar procedure are implementation

4.3 SQLJ.REMOVE_JAR procedure

Definitions and Rules

SQLJ: SQL Routines using the Java

Page 38 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

4.4 SQLJ.ALTER_JAVA_PATH procedure

SQLJ: SQL Routines using the Java

Page 40 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

SQLJ: SQL Routines using the Java

Page 42 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

SQLJ: SQL Routines using the Java

Page 44 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

i) The statement must be a create procedure.

SQLJ: SQL Routines using the Java

Page 50 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

5.3 GRANT statement

5.4 REVOKE statement

SQLJ: SQL Routines using the Java

Page 52 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

5.5 SQLJ function call

Definitions and Rules

SQLJ: SQL Routines using the Java

Page 54 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

5.6 SQLJ procedure call

Definitions and Rules

SQLJ: SQL Routines using the Java

Page 44 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

Page 44 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

SQLJ: SQL Routines using the Java

Page 46 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

SQLJ: SQL Routines using the Java

Page 48 Copyright 1998, Sybase, Inc. All Rights Reserved 10/16/98

5.2 DROP PROCEDURE/FUNCTION statement

Definitions and Rules

SQLJ: SQL Routines using the Java