15.00 - External String Literal - Teradata Database

Teradata Database SQL Data Definition Language Detailed Topics

Product
Teradata Database
Release Number
15.00
Content Type
Programming Reference
Publication ID
B035-1184-015K
Language
English (United States)

External String Literal

The external string literal specifies an encoded list of the components required to create an external procedure. When decoded, the string specifies what each component is and where it is located.

Depending on the requirements of the specific external procedure, you can specify the following components.

  • Include file (C or C++ header file) paths (see “Include Name Clause” on page 279)
  • System library paths (see “Library Name Clause” on page 280)
  • Object code paths (see “Object File Name Clause” on page 281)
  • Package (user‑created library) paths (see “Package Name Clause” on page 282)
  • Source code paths (see “Source File Name Clause” on page 283)
  • External Java reference paths (see “External Java Reference Strings” on page 444)
  • Teradata Database uses the code path to access the file it specifies, then adds an appropriate extension as it transfers that file to the external procedure compile directory on the Teradata platform.

    It is good programming practice not to use any of the following characters as the delimiter because they might be interpreted as a component of a path string rather than as a delimiter.

  • /  (SOLIDUS)
  • \  (REVERSE SOLIDUS)
  • :  (COLON)
  • The only restriction enforced on the arbitrary delimiter character is that you must use the same delimiter character throughout the specified path string.

    Teradata Database retrieves the source component from the specified client or server when it requests the source or object code.

    You should name any include files (C or C++ header files) with the same name as specified in the include directive of the source file (see SQL External Routine Programming).

    For example for a z/OS client,

        'CI¡udfdefs¡UDFDEFS¡CS¡myudf¡UDFSRC¡F¡theudf' 

    where UDFDEFS and UDFSRC are the DDNAMEs for the files on the z/OS client system. Whenever you refer to an IBM client file in a code path, you must identify it by its client DDNAME.

    This clause causes the system to do the following things.

  • Retrieve the file UDFDEFS and rename it to udfdefs.h in the UDF compile directory for the server.
  • Retrieve UDFSRC and rename it to myudf.c in the UDF compile directory for the server.
  • The C source myudf.c should contain the following code.

        #include <udfdefs.h> 

    or

        #include "udfdefs.h"

    Suppose you specify the following skeletal CREATE PROCEDURE (External Form) statement, where the omitted details are denoted by an ELLIPSIS (...) character.

        CREATE PROCEDURE abc(…)
         …
        EXTERNAL NAME 'CS!matrix!matrix.c';

    The name of the C source file in this example is matrix.c and the C procedure name, based on the procedure name abc, must have the following skeletal code.

        void abc(…)
         {
          …
         }

    Suppose you specify the following skeletal CREATE PROCEDURE (External Form) statement, where, again, the omitted details are denoted by an ellipsis (...).

        CREATE PROCEDURE abc(…)
         …
        EXTERNAL NAME 'CO!matrix!matrix.o';

    There is no source file for this procedure; instead, the code is an object file named matrix.o.

    For this CREATE PROCEDURE (External Form) statement to compile successfully, there must be a procedure in the specified object file named abc.

    See the table at the end of the “External String Literal Examples” topic for more information about procedure name usage.

    You can specify the various options as many times as needed except for the package option, which cannot be used in combination with any of the other options.

    The maximum length for the external name string is 1,999 characters.