4.2.3. Building and Solving Models - 5.2 English - 68552

Most of the computational functions in the AOCL-DA C API use a da_handle as their first argument. This serves several purposes.

• It is used to store internal data which can be passed between the different APIs (for example, da_pca_compute_? computes the principal components of a data matrix, which can be passed via the handle to da_pca_transform_?).

• It stores error information which may be useful if a function call does not complete as expected.

• It can be used to set additional options for customizing computations.

Using the AOCL-DA computational functions involves the following steps.

1. Initialize a da_handle using da_handle_init_? and specify the da_handle_type.

2. Pass data into the da_handle. The exact API for doing this will depend on the computation you wish to perform and will be detailed in the relevant chapter of this documentation.

3. Set any additional options for the computation. All algorithms in AOCL-DA use the same option setting APIs, but the exact choice of options will depend on the algorithm.

4. Perform the computation.

5. Extract results from the handle.

6. Destroy the handle using da_handle_destroy(). Destroying the handle will free up the internally allocated memory and avoid potential memory leaks.

Throughout this workflow, you may wish to query the handle for any additional error information by calling da_handle_print_error_message() or da_datastore_print_error_message().

Further details on the APIs for creating/destroying handles, setting options, error handling and extracting results are provided in the subsequent sections of this documentation.