Building an Exit Module - Basic Teradata Query

Basic Teradata Query Reference

Product
Basic Teradata Query
Release Number
16.10
Published
May 2017
Language
English (United States)
Last Update
2018-06-28
dita:mapPath
wmy1488824663431.ditamap
dita:ditavalPath
Audience_PDF_include.ditaval
dita:id
psp1479308573013
Product Category
Teradata Tools and Utilities
When building an exit module, consider the following general procedures that are constant across all operating systems:
  • The exit must be named _dynamn
  • Success is indicated by the return of a 0 (32-bit signed integer format)
  • Failure is indicated by the return of a nonzero value (32-bit signed integer format). Use different integers to indicate different errors.
  • The only parameter to the procedure is a pointer to a variable record structure.
  • A C prototype example for an exit procedure might be as follows:
    Int32 _dynamn(BTNotifyExitParm *P)
  • The C structure that is passed to user exits by BTEQ for NOTIFY can be obtained from the notify header file btnfyext.h which is included in the BTEQ package. This header file is an API which must be used as-is by employing a preprocessor include directive to include its contents in site specific Notify Exit source files.

    Since the data structures defined in this file are also used by BTEQ code, any mismatch in the definitions could lead to unexpected behavior. Make sure to use the same version of this header file which is distributed with the target BTEQ version.

  • z/OS BTEQ can use both SAS/C compiled and IBM/C compiled Notify EXIT modules.

The following table summarizes how to build exit modules using different operating systems.

Building Exit Modules Using Different Operating Systems
Operating System Procedure
Sun Solaris Compile the module with the following options: -K PIC -G.

The resulting module is in shared library format.

The exit must be specified using a filesystem path descriptor unless the environment variable LD_LIBRARY_PATH is set to point to the module at run time.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:
  • * /opt/teradata/client/<version>/sample/btnfyext.c
  • * /opt/teradata/client/<version>/include/btnfyext.h
  • * /opt/teradata/client/<version>/sample/mkbtnfyext.unx

To run the sample makefile, enter the following command:

make -f mkbtnfyext.unx

Red Hat Enterprise Linux Compile the module with the following options: -m32 -fPIC -shared.

The resulting module is in shared library format.

The exit must be specified using a filesystem path descriptor unless the environment variable LD_LIBRARY_PATH is set to point to the module at run time.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:
  • * /opt/teradata/client/<version>/sample/btnfyext.c
  • * /opt/teradata/client/<version>/include/btnfyext.h
  • * /opt/teradata/client/<version>/sample/mkbtnfyext.linux

To run the sample makefile, enter the following command:

make -f mkbtnfyext.linux

z/Linux Compile the module using the following options: -m31 -fPIC -shared

The resulting module is in shared library format.

The exit must be specified using a filesystem path descriptor unless the environment variable LD_LIBRARY_PATH is set to point to the module at runtime.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:
  • C source file

    /opt/teradata/client/<version>/sample/btnfyext.c

  • Header (include) file

    /opt/teradata/client/<version>/include/btnfyext.h

  • Makefile

    /opt/teradata/client/<version>/sample/mkbtnfyext.suselinuz-390.32

To run the sample makefile, enter the following command:

make -f mkbtnfyext.suselinux-390.32

IBM AIX Compile the module with the following option: -G

The resulting module is in shared library format. The exit must be specified using a file system path descriptor unless the environment variable LD_LIBRARY_PATH is set to point to the module at run time.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:
  • * /opt/teradata/client/<version>/sample/btnfyext.c
  • * /opt/teradata/client/<version>/include/btnfyext.h
  • * /opt/teradata/client/<version>/sample/mkbtnfyext.aix

To run the sample makefile, enter the following command:

make -f mkbtnfyext.aix

(ia64) Hewlett-Packard HP-UX Compile the module with the following options: +u1 -D_REENTRANT +DD64

The resulting module is in shared library format.

The exit must be specified using a file system path descriptor unless the environment variable LD_LIBRARY_PATH/SHLIB_PATH is set to point to the module at run time.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:
  • * /opt/teradata/client/<version>/sample/btnfyext.c
  • * /opt/teradata/client/<version>/include/btnfyext.h
  • * /opt/teradata/client/<version>/sample/mkbtnfyext.hpux-ia64

To run the sample makefile, enter the following command:

make-f mkbtnfyext.hpux-ia64

IBM z/OS z/OS BTEQ installs two Notify EXIT files in the SAMPLIB PDS:
  • BTNFYXTC – sample Notify Exit C file
  • BTNFYEXT – the Notify Exit Header file required by the C file

User-loadable Notify EXIT modules must exist in a load library whose location is identified in one of the DD names specified by the JOBLIB or STEPLIB in the JCL.

Using the SAS/C compiler:
  1. Compile and linkedit the Notify sample file with SAS/C using LC370B and LINKEDIT in a JCL script.
  2. The C and Header files should be accessed from SAMPLIB PDS.
  3. The Notify Exit module should be created in a load library.
  4. The resulting module is loadable by the IBM/C runtime.
  5. For a sample JCL to build SAS/C Notify Exit load module, see z/OS Examples for NOTIFY.

Using the IBM/C compiler:

Compile the Notify sample file using IBM/C (from USS) as follows:

cc -o “//’<load_library>(<module_name>)’” -W c,dll,expo -W l,dll <filename>

The resulting module is created as a DLL in the specified load library and is loadable by the IBM/C runtime.

Example:

cp “//’USER.SAMPLIB(BTNFYEXT)‘” btnfyext.h
cp “//’USER.SAMPLIB(BTNFYXTC)‘” btnfyext.c
cc -o “//’USER.LOAD(BTNFYEXT)’” -W c,dll,expo -W l,dll btnfyext.c

For a sample JCL to build IBM/C Notify Exit load module using JCL, see z/OS Examples for NOTIFY.

Microsoft Windows A sample exit module makefile (btnfyext.mak) is included. Modify btnfyext.c as necessary and compile by issuing:

nmake -f btnfyext.mak

This produces btnfyext.dll. Copy the DLL to where bteq.exe resides c:\Program Files\Teradata\Client\<version>\Bin (by default).

Apple OS X Compile the module with the following options: -arch x86_64 -fPIC -shared

The resulting module is in shared library format.

The exit must be specified using a file system path descriptor unless the environment variable DYLD_LIBRARY_PATH is set to point to the module at run time.

BTEQ installs three files: a sample C file, the header file required by the sample C file, and a makefile. The respective files are located in the following locations:

The respective files are located in:
  • * %dest_root%/sample/btnfyext.c
  • * %dest_root%/include/btnfyext.h
  • * %dest_root%/sample/mkbtnfyext.macosx-x86_64

where: %dest_root% is Library/Application Support/Teradata/Client/<version>

To run the sample makefile, specify:

make -f mkbtnfyext.macosx-x86_64