UDX environment

UDX API version 2 includes support for the UDX environment. The UDX environment consists of a list of one or more variable name and value pairs that you can specify for a UDF, UDA, or UDTF when you register it. Using environment variables, you can conditionalize the UDX behavior in the UDX definition.

The environment variables simplify the process for changing the behavior of the UDX when necessary. To change a variable, you alter the UDX to specify new variables, new values, or to clear the variables. Although you can define the variable values within the source code for the UDX, changing the values would require you to edit the source code, recompile, and reregister the UDX to implement the new behavior. Similarly, if you defined variables as an argument to the UDX when you invoke it, changing the variable would require changes to the SQL query that invokes the UDX.

For example, assume that you have a UDF that converts currency values from US dollars to Euros. If you hardcode an exchange rate variable within the UDF source code, you would need to update the source code whenever the exchange rate changes, then recompile and reregister the UDF. Instead, you can use an environment variable to define the exchange rate for the UDF when you register it, as in the following example:

CREATE OR REPLACE FUNCTION usdToEurosFunc(int) RETURNS int4 LANGUAGE 
CPP PARAMETER STYLE NPSGENERIC ENVIRONMENT 'USD_EURO'='0.7268' 
EXTERNAL CLASS NAME 'CusdToEuros' EXTERNAL HOST OBJECT 
'/home/nz/udx_files/usdEuroFunc.o_x86' EXTERNAL SPU OBJECT 
'/home/nz/udx_files/usdEuroFunc.o_spu';

When you update the exchange rate, you can reregister the UDX, as shown in bold:

CREATE OR REPLACE FUNCTION usdToEurosFunc(int) RETURNS int4 LANGUAGE 
CPP PARAMETER STYLE NPSGENERIC ENVIRONMENT 'USD_EURO'='0.8241' 
EXTERNAL CLASS NAME 'CusdToEuros' EXTERNAL HOST OBJECT 
'/home/nz/udx_files/usdEuroFunc.o_x86' EXTERNAL SPU OBJECT 
'/home/nz/udx_files/usdEuroFunc.o_spu';

You can specify and alter the environment variables by using the CREATE OR REPLACE commands for functions and aggregates. You can use the ALTER command to alter variable values and to clear the environment of all variable settings by using the NO ENVIRONMENT syntax. To alter an existing set of one or more environment pairs, you must specify all the environment settings; the ALTER command replaces the current list with the list specified in the ALTER command.

Within the UDF, you can retrieve the UdxEnvironment class to obtain and use the environment variables:

UdxEnvironment* getEnvironment()

The UDX environment is a structure of UdxEnvironmentEntry values that store each name-value pair that you specify when you register the UDX. The environment variables are available to the UDX constructor. You can use the following methods to obtain information about the entries in the environment and to obtain a specific entry in the environment by its name, its position (key), or its value:

The getNumEntries() method returns the number of environment variables in the UdxEnvironment object. For example:
```
   int numEntries = env->getNumEntries();
```
The findEntry() method takes an input string and matches it against the variable names. It returns the key number of the first matching entry in the environment structure, or -1 if the string is not found.
The getEntry() method takes an input index or variable name value and returns the matching UdxEnvironmentEntry or a null value if not found.
The getKey() method returns the matching environment variable name from a UdxEnvironmentEntry.
The getValue() method returns the matching environment variable value from a UdxEnvironmentEntry.