sqlj tutorial

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 JavaProgramming 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 JavaProgramming Language


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



(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.



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.



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.



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

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.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.



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.



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 createexternal

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(*)


jar A character string value having the format specified by the BNF for jar_name in the

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.




jar name.



jar name.




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.



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 createexternal

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



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.



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



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 3-

part 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.



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.



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


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




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 SQL-Java paths

or SQL routines.

Privileges


Optional features

1) The revoke statement for jars is optional.



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.



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.


Description

1) The sql_routine_name must be an sql_routine_name specified in one or more create 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 one-element

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.




















below.







Definitions








4) A Java class is result set oriented iff it is either: SQLJ: SQL Routines using the JavaProgramming Language



















below.







Definitions








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[ ].



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



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.



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





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


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




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 SQL-Java paths

or SQL routines.

Privileges


Optional features

1) The revoke statement for jars is optional.



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.


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


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.



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.


Description

1) The sql_routine_name must be an sql_routine_name specified in one or more create 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 one-element

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



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 S

sqlj tutorial

Documents