Installing and configuring the Optim data privacy user-defined functions for Teradata in SUSE Linux

Use these instructions to install and configure the Optim™ user-defined functions (UDFs) and user-defined table functions (UDTFs) for Teradata in a SUSE Linux® environment. After the UDFs are installed, you can use them to dynamically mask Teradata data.

Before you install the UDFs, consult your Teradata database administrator (DBA). Prior experience with UDFs can help ensure a smooth installation.

You must have an Optim license that includes data privacy to use the data privacy UDFs. If you need a license, contact your IBM® representative for information about how to obtain a license key that includes data privacy. Your license key identifies the Optim features you are entitled to use, such as the data privacy UDFs. For more information on this subject, see Licensing requirements for the Optim data privacy components.

The Optim UDFs and data privacy provider library must be installed on the Teradata server, not the Teradata client.

The following steps apply to installing the data privacy UDFs on single-node and multi-node Teradata servers.

Multi-node server installation: If you are installing the UDFs on a multi-node server, perform steps 3 through 11 on all nodes, and steps 12 through 15 on the primary node only.

In the data privacy UDF installation media, locate and download the Optim-DPP-v.v.v.v_yyyymmdd-BUILDnnnn.zip file, where v.v.v.v is the version number for the Optim data privacy solution, yyyy is the four-digit year, mm is the two-digit month, dd is the two-digit day, and nnnn is the four-digit build number.
Extract the zip file into a temporary location on a Microsoft Windows machine (for example, C:\Software\IBM\Optim\DP). After you extract the zip file, the location includes the following directories:
```
Bldnnnn
Doc
Images31
Images32
Images64
Replacement Data
Samples
Scripts
```
Create a target directory for the data privacy UDF software on the Teradata server node. For example, you can use the following command:
```
mkdir -p /opt/IBM/InfoSphere/Optim/dp
```
Note: If you are installing on a multi-node Teradata server, you must use the same target directory path on each node.
From the Images64\suse_udf_tera directory, transfer to the target directory, in binary mode, the suse_udf_tera_64.tar.gz file.
In the target directory, unpack the tar.gz file. For example, enter the following command:
```
tar xvf suse_udf_tera_64.tar.gz
```
The target directory will contain the following directories:
```
bin
icufiles
include
src
```
In the target directory, create the following new directories, udftrc and license, for the UDF trace and license files.
Before you can use the UDFs, you must license them. If you have an Optim license key that includes data privacy, use the Optim license program, ODPPLicp, to license the UDFs. The license program is located in the bin folder for the UDFs. For more information about using the license program, see Optim Data Privacy solution licensing information.
Create an environment file for Teradata named ODPPenv.txt. This file is used to set the necessary environment variables in the root dp directory, as shown in the following examples. If your directory structure differs from what is shown in the examples, adjust the settings to reflect your environment.
```
ODPPERRL=/opt/IBM/InfoSphere/Optim/dp/include
ODPPICUDIR=/opt/IBM/InfoSphere/Optim/dp/icufiles
ODPPLIBL=/opt/IBM/InfoSphere/Optim/dp/bin
ODPPLL=/opt/IBM/InfoSphere/Optim/dp/license
```
Optionally, you can set the ODPPINSTMGR variable to specify the Instance Manager usage mode. The Instance Manager can be used to improve performance.

Note: For more information about these variables, see Specifying environment variables for data privacy. For Optim release 11.3.0.6 and higher, environment variable ODPPERRL is not required because ODPP messages are no longer contained in file ODPPErrMsgs_EN.xml; these messages are now contained internally in the ODPP software. Therefore, the ODPPERRL environment variable, which was formerly used to point to this file, is no longer needed. For reference, ODPP return codes and messages are stored in file ODPPMessages.txt in the Doc directory.
Create a settings file for Teradata named ODPPsettings.txt with the following contents in the root data privacy directory (for example, /opt/IBM/InfoSphere/Optim/dp). If your directory structure differs from what is shown in the following example, adjust the settings to reflect your environment.
```
UDFEnvFile:/opt/IBM/InfoSphere/Optim/dp/ODPPenv.txt
UDFLibPath:/opt/IBM/InfoSphere/Optim/dp/bin
```
For releases of Optim lower than 11.3.0.5, run the following script in the bin directory (such as /opt/IBM/InfoSphere/Optim/dp/bin) to create symbolic links:
```
./createODPPTeraUDFsymlinks.sh
```
For Optim release 11.3.0.5 and higher, run the following script in the bin directory (such as /opt/IBM/InfoSphere/Optim/dp/bin) to create symbolic links:
```
createODPPsymboliclinks.sh <path> <major_version> <full_version> <hybrid_version>
```
where:

<path> is the path to the directory containing the ODPP binaries.

<major_ver> is the two-position version (for example, 11.3).

<full_ver> is the full version (for example, 11.3.0.7).

<hybrid_ver> is the hybrid two-position version (for example, 113).

To run this script on SunOS, you must use the standards-compliant shell utility /usr/xpg4/bin/sh:

/usr/xpg4/bin/sh createODPPsymboliclinks.sh <path> <major_version> <full_version> <hybrid_version>

Use the following commands to secure the directories and files. (Note that the paths are examples only.)

chmod a+rx /opt
chmod a+rx /opt/IBM
chmod a+rx /opt/IBM/InfoSphere
chmod a+rx /opt/IBM/InfoSphere/Optim
chmod a+rx /opt/IBM/InfoSphere/Optim/dp
chmod -R a+r /opt/IBM/InfoSphere/Optim/dp/*

(Primary node) Run the Teradata cufconfig utility to install the new settings:
```
tdatcmd
cufconfig –f ODPPsettings.txt
```
Then check that the values are set correctly, using the following command:
```
cufconfig -o | grep UDF*
```
When the utility is finished, restart the Teradata server to effect the setting within the server environment and propagate these settings to the other nodes.
(For SUSE only) Add bin directory ODPP to ldconfig:
To add bin directory ODPP to the system’s ldconfig, complete these operations:
1. Create file /etc/ld.so.conf.d/optim-odpp.conf, and then write the bin directory ODPP in it as follows: /opt/IBM/InfoSphere/Optim/ODPP/bin
2. Execute /sbin/ldconfig
(Primary node) The Teradata UDF installation requires the use of a C compiler to compile and link the UDFs. See the Teradata installation manuals for your version of Teradata for information about the appropriate C compiler. After you install the UDF software, you must configure your Teradata server with the registration of the UDFs. In the bin folder where you installed the UDF software, run the Teradata UDF installation program, ODPPTeraUDFInstaller.
Execute the following commands from a host command prompt in the directory where you installed the UDF for Teradata software. (Use the script command to save the installer script output to a log file.)
```
script installlog.txt
./ODPPTeraUDFInstaller
exit
```
When you are asked whether you want to install, uninstall, or quit, type the number 1 to install the UDFs.
A series of prompts are then displayed. When prompted for
- the Teradata server, specify the name of your Data Base Computer (DBC).
- a User, specify the Teradata user name under which the functions will be created.
- a Password, specify the password for the Teradata user.
- a Database, specify the database name in which the functions are to be created. (The default is SYSLIB.)
- an ODPP installation directory, specify the path to the directory where the UDF software was installed.
- an ODPP version, specify the Optim data privacy solution version. (The default version number is included in the prompt.)
The UDFs are then installed, created, and registered with Teradata.

(Primary node) Execute the following Teradata SQL queries to verify that the UDFs and UDTFs are properly installed and configured.

SELECT OptimMaskStrLatin('180027485132398', 'PRO=CCN,
FLDDEF1=(NAME=COL1, DT=CHAR)');

SELECT OptimMaskInt64(180027485132398, 'PRO=CCN,
FLDDEF1=(NAME=COL1, DT=U_LONG_LONG)');

CREATE TABLE ODPP_US_PERSON
( SEQ INTEGER NOT NULL
, FIRSTNAME VARCHAR(60) CHARACTER SET LATIN NOT NULL
, LASTNAME VARCHAR(60) CHARACTER SET LATIN NOT NULL
, EMAIL_ADDRESS VARCHAR(100) CHARACTER SET LATIN NOT NULL
) UNIQUE PRIMARY INDEX ( SEQ );

INSERT INTO ODPP_US_PERSON VALUES (1, 'Andrew', 'Duke',
'Andrew.S.Duke@pookmail.com'); INSERT INTO ODPP_US_PERSON VALUES (2,
'John', 'Johnson', 'John.J.Johnson@spamit.com');

INSERT INTO ODPP_US_PERSON VALUES (3, 'David', 'Eaton',
'David.S.Eaton@spamit.com');

When you use a provider that requires multiple arguments, group the arguments in a dynamic user-defined type (UDT) by using the NEW VARIANT_TYPE function. Here is an example:

SELECT
SEQ,
EMAIL_ADDRESS,
FIRSTNAME,
LASTNAME,
               OptimMaskStrLatin(NEW VARIANT_TYPE(EMAIL_ADDRESS,
                                 FIRSTNAME, LASTNAME),'PROVIDER=EML,
                                 PARTS="(2,3)",
                                 FLDDEF1=(NAME=EMAIL_ADDRESS,
                                 DT=VARCHAR_SZ),
                                 FLDDEF2=(NAME=FIRSTNAME,
                                 DT=VARCHAR_SZ),
                                 FLDDEF3=(NAME=LASTNAME,
                                 DT=VARCHAR_SZ)')
FROM ODPP_US_PERSON;

When you use a table-type function (UDTF), the first argument is a dynamic UDT containing the set of keys to be returned for use in the join predicate. The second argument is a dynamic UDT containing the set of columns to be masked. Here is an example:

SELECT
SEQ,
EMAIL_ADDRESS,
MASKVALUE
FROM ODPP_US_PERSON t1,
                   TABLE (OptimMaskTable(NEW
                   VARIANT_TYPE(ODPP_US_PERSON.SEQ),
                   NEW VARIANT_TYPE(ODPP_US_PERSON.EMAIL_ADDRESS),
                   'PROVIDER=EML, FLDDEF1=(NAME=EMAIL_ADDRESS, DT=CHAR)' )
RETURNS (KEYVALUE INT, MASKVALUE VARCHAR(100)) )
AS t2
         WHERE t1.SEQ = t2.KEYVALUE;