Additional information on dynamic AE environment variables

The NZAE_DYNAMIC_ENVIRONMENT variable activates arguments based on dynamic AE environment variables. (It can also be set with the --dynamic option of register_ae.) If set to 0, the default, dynamic AE environment variables are not supported. If set to 2, they system uses the last argument of the AE (string) for specifying the values.

NZAE_DYNAMIC_ENVIRONMENT={0 | 2} (feature disabled, default)
NZAE_DYNAMIC_ENVIRONMENT=2 (environment variables from last argument)

When NZAE_DYNAMIC_ENVIRONMENT is set to 2, the function must be defined to accept a string type argument as an additional, final parameter that can be used to pass one or more additional environment variables. If an AE-ENV key name matches a variable already defined through registration, then the dynamic variable overrides the registered variable.

The environment variables are specified as name1=value1, name2=value2, and so on. Apply the following syntax for environment variables:

Use a comma as variable separator.
Use double quotes as the quoting character.
Values that include white space and/or commas must be enclosed with double quotes; otherwise, white space is ignored.
If a value is quoted, the double quotes are removed after parsing.
If the double quote character is required as part of a value, use the backslash (“\”) character to escape.

Example

NZAE_EXECUTBLE_PATH=/bin/ae, data1="1,2,3,4,5,6", data2=wx\"b\"yz,data3="I am
an \"IBMer\""

With NZAE_DYNAMIC_ENV enabled, this would be part of the SQL invocation as the last argument, that is:

Select func(arg1,'NZAE_EXECUTABLE=/bin/ae...');

After parsing, this becomes:

NZAE_EXECUTBLE_PATH=/bin/ae
data1=1,2,3,4,5,6
data2=wx"b"yz
data3=I am an "IBMer"

After parsing, the dynamic environment variables are treated exactly as registration environment variables. This includes the use of prefixes such a NZAE_APPEND_, NZAE_PREPEND_, NZAE_HOST_ONLY_, and NZAE_SPU_ONLY_ processing.

The following is an example of SQL using dynamic AE environment variables to call a Java AE with main class DataMatrix:

SELECT * FROM demo, TABLE WITH FINAL(aedemo_varchar_dyn(f1,f2,f3,f4,
'NZAE_EXECUTABLE_PATH=%
{AEDEV_JAVA_JVM},NZAE_NUMBER_PARAMETERS=1,NZAE_PARAMETER1=DataMatrix'));

The string %{AEDEV_JAVA_JVM} from the code snippet above is an AE environment variable substitution, which is covered in greater detail in the section AE Environment Variable Substitution.

Variable substitution can be controlled if the AE sees this last argument as a function single-string argument, as it always sees the result in the AE environment variables (in other words, if the AE sees this function as taking 4 or 5 arguments). The fifth argument, which is the string containing the ENV variables may or may not be passed, depending on the setting of NZAE_DYNAMIC_ENVIRONMENT_PASS_LAST_ARGUMENT.

By default, NZAE_DYNAMIC_ENVIRONMENT_PASS_LAST_ARGUMENT is set to 0, specifying that the last argument should not be passed to the AE, which is the recommended setting. In the example above, when set to 0 the AE sees 4 arguments, when set to 1 it sees 5 arguments.

NZAE_DYNAMIC_ENVIRONMENT_PASS_LAST_ARGUMENT={0 | 1}

When NZAE_DYNAMIC_ENVIRONMENT is not zero, the AE runtime system expects the last string argument to be specified, and returns an error if one is not found. This includes the case where a data slice has no data. To suppress an error in the empty data slice case, specify the following:

NZAE_DYNAMIC_ENVIRONMENT_INGORE_LAST_RUN_ERROR
(value 0 or 1, default is 1)

If a data slice produces no data for a query, then it is not possible for the AE runtime to receive the dynamic AE environment variables. By default, AEs are not launched for empty data slices. This is typically the correct behavior due to the absence of data; however there may be situations where it should be flagged as an error. The following setting results in an error:

NZAE_DYNAMIC_ENVIRONMENT_INGORE_LAST_RUN_ERROR=0