Retrieving health recommendations using a client application

Recommendations can be queried using the db2GetRecommendations API in a C or C++ application.

Before you begin

You must have an instance attachment to capture a health snapshot. If there is not an attachment to an instance, then a default instance attachment is created. To query recommendations on a remote instance, you must first attach to that instance.

About this task

When using the db2GetRecommendations API, recommendations are returned in an XML document that is:

Formatted according to the health recommendations XML schema DB2RecommendationSchema.xsd located in the MISC subdirectory within the SQLLIB directory.
Encoded in UTF-8 and contains text in the client language.
Organized as a collection of recommendation sets, where each recommendation set describes a problem (health indicator) being resolved and contains one or more recommendations to resolve that health indicator. Refer to the schema definition for specific details about what information that can be retrieved from the document.

All information available through the CLP is also available in the XML recommendation document that is returned.

To retrieve health recommendations using a client application:

Procedure

Include the sqlmon.h and db2ApiDf.h header files. These are located in the sqllib\include directory.
```
#include <db2ApiDf.h>
#include <sqlmon.h>
```

Declare the sqlca, and the db2GetRecommendationsData structure.

struct sqlca sqlca ;
db2GetRecommendationsData recData ; 

memset( &sqlca, '\0', sizeof( struct sqlca ) ) ;
memset( &recData, '\0', sizeof( db2GetRecommendationsData ) ) ;

Populate the db2GetRecommendationsData structure with information about the alert for which you want to retrieve recommendations. In the code excerpt that follows, recommendations are being queried for the db2.db_heap_util health indicator on the Sample database.
```
recData.iSchemaVersion = DB2HEALTH_RECSCHEMA_VERSION8_2 ;
recData.iNodeNumber = SQLM_CURRENT_NODE ;
recData.iIndicatorID = SQLM_HI_DATABASE_HEAP_UTILIZATION  ; 
recData.iObjType = DB2HEALTH_OBJTYPE_DATABASE ; 
recData.piDbName = "SAMPLE" ;
```
Invoke the db2GetRecommendations API to retrieve recommendations for an alert on this health indicator on the specified database.
```
db2GetRecommendations(  db2Version820, &recData, &sqlca ) ; 
```
Check the sqlcode returned in the sqlca for any errors that occurred. If the API call was successful, process the recommendation XML document that is returned in the poRecommendation field of the db2GetRecommendationsData structure. Use your choice of XML parser to extract the required elements or attributes. Refer to the DB2RecommendationSchema.xsd XML schema in the sqllib\misc directory for details about the information that can be retrieved from the XML document.
Free any memory allocated by the db2GetRecommendations API. This will free the recommendation document returned in the poRecommendation field of the db2GetRecommendationsData structure.
```
db2GetRecommendationsFree( db2Version820, &recData, &sqlca ); 
```

Results

Typically you would combine the preceding code with a call to the snapshot APIs to take a health snapshot because recommendations are generally queried when you detect a health indicator has entered an alert state.