The nzudxcompile command syntax

Use the nzudxcompile command to compile source C++ files for UDXs into the object files that run on the host and the SPUs. The command is in the /nz/kit/bin/adm directory.

For UDFs and UDAs, you can use the command to compile and register the files in one step, or you can also register UDF and UDA object files that were compiled previously. For user-defined shared libraries, you can use the command only to compile the source files for a library; you cannot register shared libraries by using this command. You must use the CREATE [OR REPLACE] LIBRARY command to register them.

Syntax

The nzudxcompile command has the following syntax:

nzudxcompile [OPTIONS]... srcfile

Inputs

The nzudxcompile command takes the following input options. Some of the options are general options, while some apply only when you are compiling UDXs, or when you are registering UDFs or UDAs.

Table 1. The nzudxcompile general options
Option	Description
--base `base`	Specifies the base or home directory for the Netezza Performance Server software. The default is /nz/kit.
--user `username`	Specifies the Netezza Performance Server user account to use if you are registering a UDF or UDA with the command. The account must have Create Function privilege (for UDXs) or Create Aggregate privilege (for UDAs) and List privilege to the target database. The account must also have List privilege to the target schema unless the schema is the default schema for the database. The default is the NZ_USER environment variable value.
--pw `password`	Specifies the password for the Netezza Performance Server user account. The default is the NZ_PASSWORD environment variable value.
--schema `schema`	Specifies the schema in the database where you want to register the object. This option is used for systems that support multiple schemas. If you do not specify a schema, the command uses the default schema for the database, unless the system is configured with enable_user_schema = TRUE, which will place the UDX in a schema that matches user account name. The default is the NZ_SCHEMA environment variable value.
--db `database`	Specifies the database in which to register the UDF or UDA. The default is the NZ_DATABASE environment variable value.
-h or --help	Displays the usage for the command and exits.

The following table describes the nzudxcompile options that are used for compiling UDX source files.

Table 2. The nzudxcompile compile options
Option	Description
`srcfile`	Required argument that specifies the path name of the input C or C++ file that you want to compile.
--dynamic	Create a shared library for SPUs. You must specify --objs with this argument.
-g	Generates/compiles the debug objects.
--host	Creates a compiled object file for the Linux® host only. Used when you are combining multiple .o files by using the --objs option.
--spu	Compiles the input .o files for the local SPU environment. Used when you are combining multiple .o files by using the --objs option.
--sputype `type`	Compiles for the specified SPU type. Valid values are spu7 for z-series SPUs and spu10 for IBM® Netezza® 1000 and Netezza 100 model SPUs.
--print-compiler	Displays the path name of the compiler that is used by nzudxcompile.
--print-spu-file	Displays the SPU output file.
-o `outputobjectfile`	Specifies the name of the output object file name. If you do not specify an output object file name, the command uses the input source file name (without the .c or .cpp suffix) and appends the suffixes .o_x86, .o_spu7, and .o_spu10.
--args `args`	Specifies more optional arguments to pass to the compiler, as is.
--objs `inputobjectfile`	Specifies input object file or files that linked into one shared object file. If you specify this option, you must also specify either --spu, --sputype, or --host.

The following table describes the options that you can use when you are registering either a UDF or UDA.

Table 3. The nzudxcompile general registration options
Option	Description
[ --spufile `file` ]	Specifies the SPU object file for registration-only operations. This option bypasses the step to create the compiled object file for the SPU and just registers the specified object file.
[ --hostfile `file` ]	Specifies the host object file for registration-only operations. This option bypasses the step to create the compiled object file for the host and registers the specified object file.
[ --sig `args [, ...]` ]	Specifies the argument signature for the function or aggregate, and must be enclosed in double quotation marks. For example: "UDXname(arg1, arg2, ...) "
--return `return`	Specifies the return type for the function or aggregate. You must specify a valid Netezza Performance Server data type for the return type.
--class `class`	Specifies the class name for the function or aggregate.
--deps `libs`	Specifies the library dependencies for this UDX. The libraries can be a single library name or a comma-separated list of libraries.
--mask `args`	Specifies the debugging mask. The valid values are DEBUG or TRACE. You can specify the argument multiple times to specify multiple values.
--mem `mem`	Specifies an indication of the potential memory use of the function. The mem value can be an empty value or a value in the form of a number, or a number with the letters b (bytes), k (kilobytes), m (megabytes), or g (gigabytes).
--fenced	Specifies that the UDX runs in fenced mode. This mode is the default.
--unfenced	Specifies that the UDX runs in unfenced mode. The default is fenced mode. The database user who owns the UDX must have Unfence admin privileges.
--varargs	Specifies that the UDX is a variable argument UDX.

The following table describes the registration options that are available for UDX API version 2 objects.

Table 4. The nzudxcompile API version 2 registration options
Option	Description
--environment `val`	Specifies one or more environment settings, where `val` is a string in the form of 'name' = 'value' pairs.
--version `ver`	Specifies which version of the object files to compile/create. The default is 1 for API version 1. Specify 2 to create objects that can use the API version 2 features.

The following table describes the options that are used only when you are registering a UDF, in addition to those options described in Table 3.

Table 5. The nzudxcompile UDF registration options
Option	Description
--nondet	For a user-defined function, specifies that the function is non-deterministic. A deterministic function, which is the default, indicates that the UDF is a pure function, one which always returns the same value given the same argument values and which has no side effects. A non-deterministic function can return different results that are based on the code where it is called on or other situations; therefore, the function is always called even if it has multiple instances in your query. If Netezza Performance Server observes multiple instances of a deterministic function in a query, it can reduce all the calls to one call (a common subexpression elimination) to improve the query performance.
--nullcall	For a user-defined function, specifies that the function is CALLED ON NULL INPUT, which means that the function is called normally when some of its arguments are NULL. The default is RETURNS NULL ON NULL INPUT indicates that the function always returns NULL whenever any of its arguments are NULL.

The following table describes the options that are used only when you are registering user-defined table functions.

Table 6. The nzudxcompile table function registration options
Option	Description
--noparallel	Specifies that the table function is created with parallel not allowed. The default is parallel allowed.
--lastcall `args`	Specifies that the table function is created with `args` ALLOWED. The valid values follow: TABLE TABLE FINAL TABLE, TABLE FINAL The default is TABLE, TABLE FINAL

The following table describes the options that are used only when you are registering a UDA, in addition to those options described in Table 3.

Table 7. The nzudxcompile UDA registration options
Option	Description
--state `state`	Specifies the state signature for a user-defined aggregate, and must be enclosed in double quotation marks. For example: "(state1, state2, ...)"
--type `aggtype`	For a user-defined aggregate, specifies whether the aggregate can be invoked only in a windowed aggregate (ANALYTIC) or a grouped aggregate (GROUPED) or both (ANY). The default is ANY.

Description

The nzudxcompile command has these additional descriptions:

Privileges required: To run nzudxcompile, you must be logged in to the Netezza Performance Server system as the nz user account. If you use the command to also register the user-defined function or aggregate in one step, you must specify a SQL user such as admin or one who has Create Function | Aggregate and List privileges to the target database and schema.
Common tasks: Use the command to compile C++ code files for a user-defined function or aggregate into object files that can be used in SQL queries on the Netezza Performance Server system. If you use this command only to compile the object files, you need to register the functions and aggregates by using the CREATE FUNCTION or CREATE AGGREGATE Netezza Performance Server SQL commands. You can also create the compiled objects and register them at the same time by using the nzudxcompile command; you must specify the --sig, --return, --class, and --state arguments, which then cause the Netezza Performance Server system to call the related CREATE OR REPLACE function, as applicable.

Usage

The following are examples of nzudxcompile command usage:

To compile a sample C++ file for a function named cube and create the output object files:
```
   nzudxcompile /home/nz/udx_files/cube.cpp
```
To compile the cube C++ file and save it as mycube object files:
```
   nzudxcompile /home/nz/udx_files/cube.cpp -o mycube
```

To compile the cube C++ file and also register it in the mydb database:

   nzudxcompile /home/nz/udx_files/cube.cpp --sig "Cube(int4)"
--return INT8 --class Cube --user myuser --pw password --db mydb

To create a shared library that is called mylib from the mylib.cpp file, run the following two commands:

   nzudxcompile /home/nz/udx_files/mylib.cpp --sputype spu10 -o
mylib.so
   nzudxcompile --objs /home/nz/libs/mylib.o_spu10 --dynamic --sputype
spu10 -o mylib.so