

How to Set up a UDF / XSP Debugging Environment
An integrated development environment is crucial to software developers for editing, building and debugging their program all within one environment. Therefore, setting up the right development environment is an important first task.
Here we set up a User-defined Functions (UDFs) / External Stored Procedures (XSPs) debugging environment used to debug typical UDF/XSPs. Eclipse Indigo is used as the IDE. A Teradata Express (TDExpress) VM is used as the running DBS.
Prerequisite for this Article
We use a TDExpress VM as the running DBS; hence a VMware Workstation or a VMware Player is needed. If you don't have either of these on your PC, please download the free VMware Player from the following link: https://my.vmware.com/web/vmware/free#desktop_end_user_computing/vmware_player/4_0
If you have not worked through the guide Teradata Express 14.0 for VMware User Guide, please do it now before you continue.
Article Outline
In this article, we will do the following things to setup the UDF/XSP debugging environment.
- Get an Official TDExpress VM
- Install Eclipse for Java Developer
- Install CDT Eclipse Plug-in for C/C++ Developer
- Create a Teradata Database User
- View & Change Teradata UDF/XSP Settings
- Set up for C/C++ Remote Debugging
There are 2 typical UDF/XSP debugging scenarios depending on the location of the running DBS.
A. Local debugging
DBS and the Eclipse IDE are running on the same machine.
Please execute sections 1-5 in this machine.
B. Remote debugging
DBS and the Eclipse IDE are running on separate machines. We will refer to the machine running Eclipse as client, and the remote DBS machine as DBS.
Please execute sections 1-3 and part of section 6 in client, and sections 4-6 in DBS.
1. Get an Official TDExpress VM
1.1. Register for DevX Account
Before you login to the DevX network, please register for a free account.
Open the DevX website, and click the Register link in the top right corner.
http://developer.teradata.com/
The Create Account window is displayed. Please input all the information and check the checkbox I agree to the Terms of Use.
After that, click Create Account. If there is no error in the input, your account will be created.
Please click Update Profile to fill in other user information.
1.2. Login to DevX
If you just created an account in section [1.1. Register], you will be logged in automatically.
Otherwise, please click the Sign In link in the top right corner.
Input your username and password, and click the Sign in button to log in.
1.3. Download TDExpress VM
Open the Teradata Express VM for VMware Player download page.
http://downloads.teradata.com/download/database/teradata-express/vmware
If you have not filled in enough contact information in your DevX account, you will not be able to download.
Download TDE 14.00.00.01 for VMware(40GB) by clicking the link Teradata Express - 40GB capacity (.7z, 3.0GB). The download will start automatically.
1.4. Start up TDExpress VM
When the download finishes, unzip the file td-express-14.00.00.01-vm-40gb.7z to a folder, and then double click the TDExpress14.0_Sles10.vmx file to power on the VM.
The VMware Player will start up the VM automatically.
If this is your first time starting up this VM, the following window will appear:
Click the I copied it button to continue. This will get a new IP address for your VM.
1.6. Login to VM
When the login screen is displayed, input default username/password as root/root, and press Enter.
We have started the Teradata Express VM successfully. The following activities are all in the TDExpress VM.
Note: When the system has started, execute Viewpoint Stop in the desktop to stop Viewpoint services. This will save memory since we don’t use Viewpoint.
1.7. Setup ceud Directory in VM
In the TDExpress VM, the / filesystem is very small but /var/opt/teradata has a lot of free disk space. So we will create a ceud folder in /var/opt/teradata to be used for our debugging.
Open a console window, and submit the following commands:
TDExpress14.0_Sles10:~ #
md /var/opt/teradata/ceud
Create a soft link /ceud to /var/opt/teradata/ceud folder.
TDExpress14.0_Sles10:~ # ln -s /var/opt/teradata/ceud/ /ceud
2. Install Eclipse for Java Developer
2.1. Download Eclipse
Open the Eclipse Indigo SR2 download page in your VM.
http://eclipse.org/downloads/packages/release/indigo/sr2
Select Eclipse IDE for Java Developers for Linux 64 bit version.
Alternately, we can download the package directly through the following link.
2.2. Unpack
Unpack the package to /ceud folder using File Roller.
2.3. Make a Link
For convenience, make a soft link for eclipse folder.
TDExpress14.0_Sles10:~ #
ln -s /ceud/eclipse/ /usr/eclipse
2.4. Create EclipseStart Launcher
For convenience, we create a launcher in the Desktop.
Right-click in the Desktop, and click Create Launcher....
Fill in the Create Launcher window. Input the following items:
Name: EclipseStart
Command: /usr/eclipse/eclipse
And click the OK button.
An EclipseStart launcher is created in the Desktop.
2.5. Change Eclipse Default Setting
Edit the Eclipse configuration file /usr/eclipse/eclipse.ini before starting up Eclipse.
Add the following 2 lines after -Dosgi.requiredJavaVersion=1.5
-Dorg.eclipse.swt.browser.UseWebKitGTK=true -Dorg.eclipse.swt.browser.XULRunnerPath==/usr/lib/xulrunner-1.8.1.21
This will prevent you from getting the below error when running Eclipse.
2.6. Start up Eclipse
Double-click the EclipseStart launcher to start up Eclipse.
If this is the first time starting Eclipse, a Workspace Launcher setting window will appear.
Enter the Workspace /usr/eclipse/workspace, and check the Use this as the default and do not ask again check box. Click OK to continue.
Note: The default workspace /root/workspace might be used by another application in the VM. So we use another workspace /usr/eclipse/workspace to avoid possible conflicts.
A welcome window will be displayed. Just click the close icon in the welcome window title bar.
Eclipse has been started successfully.
3. Install CDT Eclipse Plug-in for C/C++ Developer
If you are a C/C++ developer and need to work on a UDF/XSP written in C/C++, please install the CDT Eclipse plug-in.
3.1. Open Install Window
Open Help -> Install New Software....
An Install window comes up. Type the following CDT update site address in the Work with: input box, and press Enter.
http://download.eclipse.org/tools/cdt/releases/indigo
3.2. Install CDT Features
Click the triangle of the first line CDT Main Features, and check the first C/C++ Development Tools check-box.
Click the triangle of the second line CDT Optional Features, and check the Eclipse Debugger for C/C++ check-box.
Click Next, and Next button again.
In the Review Licenses window, check the radio button I accept the terms of the license agreement, and click the Finish button.
An Installing Software progress window will display. It can take several minutes to install.
3.3. Restart Eclipse
When the installation is finished, a restart is needed. Click Restart Now to restart Eclipse.
After the restart, the welcome window will be displayed, with the C/C++ Development feature added to the Overview. Just click the close icon in the welcome window title bar.
The Eclipse CDT plugin has been installed successfully.
4. Create a Teradata Database User
In DBS, we now create a DEBUGGER user and give this user permissions to create and execute UDF/XSPs.
Note: As stated previously, this section will be done in your DBS.
4.0. Change DBS Prompt
To avoid confusion from client, we change the DBS prompt temporarily.
TDExpress14.0_Sles10:~ # export PS1="TDExpress14.0_DBS:\w # "
TDExpress14.0_DBS:~ #
Note: This will only change the current terminal window's prompt. If you open a new terminal window, please run this command first before running any other command.
4.1. Start Teradata Database
At the command prompt, enter the following:
TDExpress14.0_DBS:~ #
/etc/init.d/tpa start
After a few moments, the system reports:
Teradata Database Initiator service is starting...
Teradata Database Initiator service started successfully.
If the database is already running, then a message will show:
PDE( PdeMain ) already running:
Then give the database some time to initialize.
To verify the database is fully up and operational, enter the following command:
TDExpress14.0_DBS:~ #
pdestate -a
The result should show:
PDE state is RUN/STARTED.
DBS state is 5: Logons are enabled - The system is quiescent
4.2. Create the DEBUGGER user
Login to bteq as dbc user, and create a DEBUGGER user.
From the command prompt, enter the following:
TDExpress14.0_DBS:~ #
bteq .logon 127.0.0.1/dbc,dbc
BTEQ -- Enter your SQL request or BTEQ command:
CREATE USER DEBUGGER AS PERMANENT=50E6, SPOOL=100E6, TEMPORARY=50E6, PASSWORD=debugger;
*** User has been created.
*** Total elapsed time was 2 seconds.
4.3. Grant Privileges
For UDF/XSP debugging, necessary privileges must be given to the DEBUGGER user. Please submit the following commands.
BTEQ -- Enter your SQL request or BTEQ command:
GRANT CREATE FUNCTION ON DEBUGGER TO DEBUGGER WITH GRANT OPTION; GRANT CREATE EXTERNAL PROCEDURE ON DEBUGGER TO DEBUGGER WITH GRANT OPTION; GRANT EXECUTE PROCEDURE ON SQLJ TO DEBUGGER WITH GRANT OPTION;
After execution, the result messages will display.
*** Grant accepted.
*** Total elapsed time was 1 second.
4.4. Logout
Submit the following command to logout.
BTEQ -- Enter your SQL request or BTEQ command:
.quit
After execution, the result messages will display.
*** You are now logged off from the DBC.
*** Exiting BTEQ...
*** RC (return code) = 0
5. View & Change UDF/XSP Settings
Teradata DBS has a cufconfig utility which allows you to view and change configuration settings for the UDF and XSP subsystem.
Note: As stated previously, this section will be done in your DBS.
We will change the UDFServerTasks and JavaBaseDebugPort values to make the debugging easier.
UDFServerTasks
The UDFServerTasks is the number of protected mode UDFs, XSPs, or UDMs (User-defined Method) that can be run simultaneously per vproc. The default value is 2. We will change the value to 1.
JavaBaseDebugPort
The JavaBaseDebugPort is the base number used to determine the debug port for Java UDF and Java XSP. Its default value is 0, meaning the JVM debug port is disabled. We will change the value to 8000.
The actual port number to use for attaching a debugger to a Java UDF or XSP is the value of JavaBaseDebugPort plus an offset.
- For Java UDF running on a hybrid server, the offset is always 2000, so the Java UDF remote debug port is 8000 + 2000 = 10000.
- For Java XSP running on secure servers, the offset depends on which instance of the server is executing the routine (there can be up to 10 secure servers per vproc), and on the type and ID of the vproc that is executing the routine.
The logic to calculate the debug port is complicated. Another way to find the port will be shown in How to Create and Debug a Java XSP using Eclipse article.
5.1. Establish the Teradata Database Environment
In DBS, enter the following command in a terminal window. It will add the Teradata utilities (e.g. cufconfig) path into the system path.
TDExpress14.0_DBS:~ #
tdatcmd
Note: This will change the prompt back to the original value, so please execute [4.0. Change DBS Prompt] section again to avoid confusion.
TDExpress14.0_DBS:~ #
export PS1="TDExpress14.0_DBS:\w # "
5.2. Show Settings
We will use the command cufconfig -o to show the current UDF and XSP subsystem settings, and use cufconfig -f filename to change the settings.
Enter the following command in the terminal window to show the current UDF/XSP configuration settings.
TDExpress14.0_DBS:~ #
cufconfig -o
5.3. Change Settings
Use the following procedure to change UDFServerTasks to 1, and JavaBaseDebugPort to 8000.
5.3.1. Create a New Settings File
Create a new settings file named newsetting.cuf in /tmp. Input the content as below, and click the Save button.
JavaBaseDebugPort: 8000 UDFServerTasks: 1
5.3.2. Import the New Settings File
Enter the following command in the terminal window to import the new settings file.
TDExpress14.0_DBS:~ #
cufconfig -f /tmp/newsetting.cuf
5.3.3. Restart the Database
For the changes to take effect, restart the database via the following command:
TDExpress14.0_DBS:~ #
tpareset -f change cufconfig setting
A confirmation message will come up. Type y, and hit Enter.
6. Set up for C/C++ Remote Debugging
If you want to debug a CUDF or CXSP in a remote DBS, some additional settings should be made in both client machine and DBS.
In our example, we are doing remote CUDF / CXSP debugging from a Linux client machine to a remote DBS. The client machine is our TDExpress VM, and the remote DBS's IP address is 192.168.85.128.
We have not successfully tested out the case of using a Windows machine as a client machine to remote debug CUDF/CXSP.
6.1. Upgrade Gdb in Linux Client
Download a new version of gdb in the client because we cannot use the default gdb6.8 in our Linux client VM to debug the remote CUDF/CXSPs in DBS. We need gdb version 7.0 or higher to do remote debugging.
Note: This section [6.1. Upgrade Gdb In Client] should be done in the Linux client.
Please use the link gdb-7.0.1a.tar.gz to download gdb7.0.1.
Unzip the file to /ceud folder using File Roller. A /ceud/gdb-7.0.1 folder is created.
Open a terminal window, and submit the following commands to compile and install the gdb7.0.1 from source.
TDExpress14.0_Sles10:~ #
cd /ceud/gdb-7.0.1
TDExpress14.0_Sles10:/ceud/gdb-7.0.1 #
./configure
TDExpress14.0_Sles10:/ceud/gdb-7.0.1 #
make
TDExpress14.0_Sles10:/ceud/gdb-7.0.1 #
make install
Submit the follwing command to verify the installed gdb version.
TDExpress14.0_Sles10:/ceud/gdb-7.0.1 #
gdb -version
6.2. Gdbserver in DBS
Before remote debugging, confirm there is an available gdbserver program in the remote DBS. The gdbserver version must be equal to or greater than the client gdb version.
Submit the follwing command to verify the installed gdb version.
TDExpress14.0_DBS:~ # gdbserver --version
If there is no gdbserver installed in DBS or the installed gdbserver version in DBS is less than the gdb in client, please install an equal or higher version gdbserver in DBS. In our case, we should install a gdbserver with a version equal to or greater than 7.0.1.
We can install gdb7.0.1 which is used in the [6.1. Upgrade Gdb in Linux Client] section because the gdbserver is also included in the gdb package. The gdbserver is installed with gdb installation at the same time.
Download gdb7.0.1 using the link gdb-7.0.1a.tar.gz.
Unzip the file to /root folder. A /root/gdb-7.0.1 folder is created.
Open a terminal window, and submit the following commands to compile and install the gdb7.0.1 from source.
TDExpress14.0_DBS:~ # cd /root/gdb-7.0.1
TDExpress14.0_DBS:/root/gdb-7.0.1# ./configure
TDExpress14.0_DBS:/root/gdb-7.0.1# make
TDExpress14.0_DBS:/root/gdb-7.0.1# make install
6.3. Samba Setup
To share the DBS udf library files to the client VM, we set up a shared folder using the Samba service.
6.3.1. Samba Setup in DBS
This section should be executed in the remote DBS, which has IP Address 192.168.85.128 in our case.
6.3.1.1. Establish the Teradata Database environment
In DBS, enter the following command in a terminal window. It will add the Teradata utilities (e.g. cufconfig) path into the system path.
TDExpress14.0_DBS:~ #
tdatcmd
Note: This will change prompt back to the original value, so please execute [4.0. Change DBS Prompt] section again to avoid confusion.
TDExpress14.0_DBS:~ #
export PS1="TDExpress14.0_DBS:\w # "
6.3.1.2. Get the UDF Library Path
In DBS, enter the following command in the terminal window to show the current UDF library path.
TDExpress14.0_DBS:~ #
cufconfig -o | grep UDFLibrary
We should get the following default path.
UDFLibraryPath: /etc/opt/teradata/tdconfig/udflib/
6.3.1.3. Edit the Samba Configuration File
In DBS, edit the Samba configuration file /etc/samba/smb.conf and add the following content at the end of the file.
[sharedUDFLibPath] comment = for UDF remote debugging path = /etc/opt/teradata/tdconfig/udflib browseable = Yes read only = Yes directory mask = 0775 guest on = ok [usrtdbmsPath] comment = for UDF remote compilation path = /usr/tdbms browseable = Yes read only = Yes directory mask = 0775 guest on = ok
6.3.1.4. Set the Samba User Password
We need to setup a new password for the Samba service.
TDExpress14.0_DBS:~ #
smbpasswd -a root
You will be prompted for a new SMB password.
6.3.1.5. Restart the Samba Service
For the changes to take effect, restart the Samba service via the following command in DBS:
TDExpress14.0_DBS:~ #
/etc/init.d/smb restart
6.3.2. Mount the Remote Samba Folder in the Linux Client
Switch to the client machine, open a terminal window and submit the following command to set up a mapping folder using [6.3.1.2. Get UDF Library Path] UDF library path. Before submitting the command please make sure the folder /etc/opt/teradata/tdconfig/udflib and /usr/tdbms exists; otherwise a mount error will be returned.
In our case, the DBS IP address is 192.168.85.128, and the shared folder path is sharedUDFLibPath and usrtdbmsPath which we just set in section [6.3.1.3. Edit Samba Configuration File].
TDExpress14.0_Sles10:~ # mount -t cifs //192.168.85.128/sharedUDFLibPath /etc/opt/teradata/tdconfig/udflib
TDExpress14.0_Sles10:~ # mount -t cifs //192.168.85.128/usrtdbmsPath /usr/tdbms
We will be prompted for a password. Use the SMB password set earlier in [6.3.1.4. Set Samba User Password].
We can now access the folders /etc/opt/teradata/tdconfig/udflib and /usr/tdbms to see the mapping files in DBS.
The setup for the UDF/XSP debugging environment is completed. You are now ready to debug your UDF/XSPs. Next step is to view the articles written for debugging specific types of UDF/XSPs.