Test harness control file

When you run the nzudxharness command, the command creates a control file called udfname_func.harness or udaname_agg.harness. A control file is a text file that specifies the details of the test and simulation environment.

The nzudxrunharness command writes the harness control file to the current directory. For the CustomerName UDF example in the section UDX test harness, the command created and used the following control file:

[nz@nzhost udx]$ more customername_func.harness
udxtype: udf
objectfile:/nz/data.1.0/base/2547310/udf/2928850.oh
udxname:customername
version: 2
numenvironments:0
numreturns:1
returninfo:16:-1:-1
numarguments:1
argument:1:64000:-1
classname:CCustomerName
fenced:t
deterministic:t
nullcall:t
memory:0
logmask:0
nulls:
numdependencies:0
undefined:vtable for __cxxabiv1::__class_type_info
undefined:vtable for __cxxabiv1::__si_class_type_info
undefined:operator delete[](void*)
undefined:operator delete(void*)
undefined:operator new(unsigned int)
undefined:__cxa_pure_virtual
undefined:__gxx_personality_v0
undefined:free
undefined:memcmp
undefined:sprintf
undefined:strcmp
undefined:strdup
undefined:throwError
inputdelim:,
inputquote: true
hexinput: false
printoutput: none
numrows: 100
validate: true

You can edit the control file parameters to change the test environment. You can also use the udxharness binary and specify one or more control files to test a UDX or several UDXs and their interactions in the same transaction scope. For example:

[nz@nzhost udx]$ udxharness -f customername_func.harness -f 
penmaxv2_agg.harness -k /nz/kit

This sample command runs both the customername UDF and PenMax UDA in the same test environment to evaluate the effect on the system.

The following table describes the harness control file parameters.

Table 1. Control file parameters. This table describes the options and parameters that you can specify for user-defined objects.
Parameter	Description
Options common to UDFs, UDAs, and UDTFs
udxtype: `type`	Specifies the UDX type. The `type` must be either udf, uda, or udtf. This parameter must be the first one in the control file.
numarguments: `num`	Specifies the number of arguments for the UDX. It must be immediately followed by the arguments. You must specify exactly `num` arguments.
argument: `info`	Specifies one of the arguments that are referenced by num. The format of the `info` value is `type`:`typmod`:`scale`. The `type` value is one of the DataType enums from the UdxBase C++ class. The `typmod` value is -1 or the size of a string, or the precision of a numeric. The `scale` value is -1 or the scale of a numeric.
classname: `class`	Specifies the C++ class for the UDX. This parameter is required.
datafile: `file`	Specifies the input data file.
numdependencies: `num`	Specifies the number of library dependencies for the UDX. It must be immediately followed by the dependencies. You must specify exactly `num` dependencies.
dependency: `libinfo`	Specifies a library dependency for the UDX. You must specify the libraries in correct order; that is, the libraries that depend on other libraries must be listed after the libraries that they depend on. The format of the libinfo value is `auto`,`file`,`name`. The `auto` value is t for automatic load and f for manual load. The `name` is the library name. The `file` value is the .so library object file. Spaces before or after the commas are not allowed, unless they are part of the file or name.
fenced: `value`	Specifies whether the UDX runs in fenced mode or unfenced mode. You can specify a boolean value such as true, t, on, yes, y, or 1 to run the UDX in fenced mode. Specify a value of false, f, off, no, n, or 0 to run the UDX in unfenced mode.
shaper: `value`	Specifies whether the UDX calls a sizer or shaper. The default is false (do not call a sizer/shaper). You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
hexinput: `value`	Specifies whether the data in the input file is in hex format. The default is false (not in hex format). You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
inputdelim: `delim`	Specifies the delimiter for the input file. The default is comma.
inputescape: `escape`	Specifies the escape character for the input file. The default is no escape character.
inputquote: `value`	Specifies whether string data in the input file is quoted. The default is false (not quoted). You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
logmask: `mask`	Specifies the log mask for the UDX. The valid values are 1 for TRACE, 2 for DEBUG, 3 for both DEBUG and TRACE or 0 for NONE. The default is 0.
memory: `mem`	Specifies the maximum memory for the UDX. The size value can be an empty value or a value in the form of a number and the letters b (bytes), k (kilobytes), m (megabytes), or g (gigabytes). The default is 0.
nulls: `cols`	Specifies the columns that will be null randomly when using randomly generated test data (no input data file specified). The cols value is a comma-separated list of column numbers. The column numbers start at 1.
numreturns: `num`	Specifies the number of return columns for the UDX. The value is 1 for UDFs and UDAs, but it can be 1 or more for UDTFs. It must be immediately followed by the return info. You must specify exactly `num` return values. This parameter is required.
returninfo: `info`	Specifies the return info. The info value has the form `type:typmod:scale:name`. The type value is one of the DataType enums from the UdxBase C++ class. The typmod value is -1, or the size of a string, or the precision of a numeric. The scale value is -1 or the scale of a numeric. The name value is used only for a UDTF, where it specifies the column name. For a UDTF, the return info must be specified in the correct order; that is, the same order in which the columns are declared for the table function.
numrows: `num`	Specifies the number of randomly generated rows to produce for the test. This option is only used when you do not specify an input data file. The default is 100.
objectfile: `file`	Specifies the host UDX object file. This value is required.
printoutput: `type`	Specifies how to print the output of the UDX. Possible values are normal, hex, or none. Normal prints the normally expected output; hex prints strings in their hex representation instead of string representation; none does not print any output. The default is none.
validate: `value`	Specifies whether to validate the results for buffer overruns, which adds execution time. The default is true. You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
udxname: `name`	Specifies the name of the UDX as registered in the database. This value is required.
undefined: `symbol`	Specifies an undefined symbol from the object file. There can be 0 or more symbols. This is only printed by the program to show issues such as potentially unresolved references. This parameter is not required.
version: `ver`	Specifies the UDX API version. The `ver` value can be 1 or 2. The default is 1.
Options specific to UDAs
columnorder: `column`	Specifies the column to use for grouping when executing an aggregate. This parameter triggers the calling of InitializeState when the group changes. Column is a 1-based number that specifies the position in the data file. This parameter is required if you specify a data input file.
groups: `num`	Specifies the number of groups to simulate when using random data instead of a data input file. The default is 5.
numstate: `num`	Specifies the number of state values for the UDA. It must be immediately followed by the states. You must specify exactly `num` states. This parameter is required.
state: `info`	Specifies one of the state values for the UDA. The format of the info field is `type:typmod:scale`. The `type` value is one of the DataType enums from the UdxBase C++ class. The `typmod` value is -1 or the size of a string, or the precision of a numeric. The `scale` value is -1 or the scale of a numeric.
Options specific to UDTFs
deterministic: `value`	Specifies whether the UDF is deterministic. The default is true. You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
nullcall: `value`	Specifies whether the UDF is called when one of the arguments is null. The default is false. You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
UDTF-Specific Parameters
lastcall: `value`	Specifies whether the UDTF is called after the last input row. The default is false. You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0.
UDX version 2-specific options
numenvironments: `num`	Specifies the number of environment values for the UDX. It must be immediately followed by the environment value. You must specify exactly `num` variables.
environment: `info`	Specifies an environment entry for the UDX. The format of the info value is name, value. The name value specifies the name of the environment setting. The value is the value of the environment setting.
close: `value`	Specifies whether the test harness invokes the C library function dlclose() to close references to UNIX shared libraries that were made available with dlopen(). You can specify a boolean value such as true, t, on, yes, y, or 1; or false, f, off, no, n, or 0. The default is true to call dlclose(). If you are running the test harness within a debugging tool such as valgrind or callgrind, set this value to false so that the harness does not invoke dlclose() automatically. This allows you to access symbol names and other values that can be useful for debugging, but which might not available after dlclose() is called. (For more information about the valgrind debugging environment, see http://valgrind.org.)