Using AE to load a diagnostic or debugger tool

Using the AE runtime to load a diagnostic/debugger tool is more complex than manually attaching via GDB because AEs do not, by default, have a terminal, so you must provide one. To create a terminal:

Open a new Linux terminal on the host.
Run the Linux tty command to get its name:
```
$ tty
 /dev/pts/4
```
Run a long sleep on the terminal (like sleep 1000000) to keep the shell from interfering with AE and diagnostic tool IO.
Register the AE to use this terminal using the NZAE_TERMINAL AE environment variable:
```
--environment "'NZAE_TERMINAL'='/dev/pts/4'"
```

You must modify the registration to both run the tool and to give the tool the proper parameters to run the AE. Three system AE environment variables are used to accomplish this task:

NZAE_HOST_ONLY_NZAE_EXECUTABLE_PATH=<path of tool>
NZAE_NUMBER_PARAMETERS=<integer: number of parameters>
NZAE_PARAMETER1=<tool specific> 
NZAE_PARAMETER2=<tool specific>

Note that in the above pseudo-code, the number of parameters is tool- and application-specific.

AE functionality has a built-in mechanism to run GDB (see Working with GDB for more information). This example is a model for using GDB and other debuggers and tools. The example uses terminal /dev/pts/7, which is running sleep 1000000.

$NZ_EXPORT_DIR/ae/utilities/bin/compile_ae --language system --version 3
--template compile \
--compargs "-g -Wall" --linkargs "-g" --exe testcapi 
/home/nz/src/cpp/ae/testcae/testcapi.c

Note in the compilation above that --compargs and --linkargs are used to set compile and link to produce debugging symbols.

$NZ_EXPORT_DIR/ae/utilities/bin/register_ae --language system --version 3
--template udtf 
     --sig "testcapi_debug(int, double, varchar(30))" \
     --return "table(a int, b int, c double, d double, e varchar(255), \
     f varchar(255))" \
     --exe testcapi --noparallel --level 1 \
     --environment "'NZAE_TERMINAL'='/dev/pts/7'" \
     --environment
"'NZAE_HOST_ONLY_NZAE_EXECUTABLE_PATH'='/nz/kit/sbin/gcc/bin/gdb'" \
     --environment "'NZAE_NUMBER_PARAMETERS'='2'" \
     --environment "'NZAE_PARAMETER1'='--args'" \
     --environment \
"'NZAE_PARAMETER2'='/nz/export/ae/applications/mydb/myusr/host/testcapi'"

In this example, the executable run by the AE runtime is the debugger itself. The AE application is specified as an argument to the debugger. The --args option is a GDB option, not an AE option.