16.20 - SQLJ.INSTALL_JAR External Stored Procedure - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL External Routine Programming

Product
Advanced SQL Engine
Teradata Database
Release Number
16.20
Release Date
April 2020
Content Type
Programming Reference
Publication ID
B035-1147-162K
Language
English (United States)

Purpose

Use the SQLJ.INSTALL_JAR external stored procedure to register an archive file (a file with a .jar or .zip file extension) with Teradata Database and distribute the archive file to all nodes of a database system.

Definition

REPLACE PROCEDURE SQLJ.INSTALL_JAR
   (IN locspec VARCHAR(1000),
    IN jarname VARCHAR(128)CHARACTER SET UNICODE,
    IN deploy  INTEGER)
LANGUAGE C
NO SQL
PARAMETER STYLE SQL
EXTERNAL NAME 'SL!xsplib';

where:

locspec
Location of the archive file to register.
The first two characters of the locspec string specify whether the archive file is on the client or on the database server. If the first two characters are...
  • CJ, then the .jar or .zip file is on the client.
  • SJ, then the .jar or .zip file is on the database server.

The third character of the locspec string is a delimiter that you choose to separate the first two characters from the remaining characters in the locspec string.

The remaining characters in the locspec string specify the archive file path.

If the archive file is on the...
  • client, then the file path is a client-interpreted path that specifies the location and name of the file, including the .jar or .zip file extension.
  • database server, then the file path can be a full or relative path that specifies the location and name of the file, including the .jar or .zip file extension.

    If the file path is relative, the full path to the archive file is formed by appending the relative path to the default path for source code on the server.

    To determine the default path for source code, use the -o option of the cufconfig utility and find the setting for the SourceDirectoryPath field:
    cufconfig -o

    For more information on cufconfig , see Teradata Vantage™ - Database Utilities , B035-1102 .

jarname
an SQL identifier for the archive file, enclosed in apostrophes ( ' ).

The identifier that you use here to register the archive file is the same name that you specify later in the CREATE/REPLACE PROCEDURE or CREATE/REPLACE FUNCTION statement that you use to define the Java external routine.

The identifier must follow the rules for naming Teradata Database objects without enclosing the names in double quotation marks:
  • They may only include the following characters:
    • Uppercase or lowercase letters (A to Z and a to z)
    • Digits (0 through 9)
    • The special characters HYPHEN-MINUS (-), FULL STOP (.), DOLLAR SIGN ($), NUMBER SIGN (#), and LOW LINE (_)
    • (Using the - and . special characters is an extension to the rules for naming Teradata Database objects without enclosing the names in double quotation marks, and is only allowed for this type of identifier.)
  • They must not begin with a digit.
  • They must not be a Teradata reserved word.

    For details on Teradata reserved words, see Teradata Vantage™ - SQL Fundamentals, B035-1141.

  • The maximum length for jarname is 128 characters.
Additionally, the identifier cannot be a name that is reserved for JAR files that are part of the Teradata installation, where the restriction applies to any combination of uppercase and lowercase letters:
  • javFnc
  • terajdbc4
  • tdgssjava
  • tdgssconfig

For details on Teradata Database object names, see Teradata Vantage™ - SQL Fundamentals, B035-1141.

deploy
An integer value that is reserved for future use.

For now, the value of deploy must be zero.

Example: SQLJ.INSTALL_JAR External Stored Procedure

Suppose the default path for source code on a Linux server is set to /etc/opt/teradata/tdconfig/Teradata/tdbs_udf/usr/ and you have a file called accounts.jar in /etc/opt/teradata/tdconfig/Teradata/tdbs_udf/usr/java_xsp.

The following statements register the accounts.jar file with the JXSP database, create an SQL identifier called Accounts_JAR for the file, and distribute the file to all nodes:

DATABASE JXSP;
CALL SQLJ.INSTALL_JAR('SJ!java_xsp/accounts.jar', 'Accounts_JAR', 0);

Consider a ZIP file called reports.zip on a Linux client in the directory /tmp/java_xsp.

The following statements register the file with the JXSP database, create an SQL identifier called Reports-ZIP for the file, and distribute the file to all nodes:

DATABASE JXSP;
CALL SQLJ.INSTALL_JAR('CJ?/tmp/java_xsp/reports.zip', 'Reports-ZIP', 0);

Related Topics

For details on how you use the jarname SQL identifier when you define a Java external routine, see CREATE PROCEDURE, REPLACE PROCEDURE, CREATE FUNCTION, and REPLACE FUNCTION in Teradata Vantage™ - SQL Data Definition Language Detailed Topics , B035-1184 .