Product SiteDocumentation Site

3.7.3. PMAPI Error Handling

Where error conditions may arise, the functions that compose the PMAPI conform to a single, simple error notification scheme, as follows:
  • The function returns an int. Values greater than or equal to zero indicate no error, and perhaps some positive status: for example, the number of items processed.
  • Values less than zero indicate an error, as determined by a global table of error conditions and messages.
A PMAPI library function along the lines of strerror is provided to translate error conditions into error messages; see the pmErrStr(3) and pmErrStr_r(3) man pages. The error condition is returned as the function value from a previous PMAPI call; there is no global error indicator (unlike errno). This is to accommodate multi-threaded performance tools.
The available error codes may be displayed with the following command:
          pmerr -l
Where possible, PMAPI routines are made as tolerant to failure as possible. In particular, routines which deal with compound data structures - results structures, multiple name lookups in one call and so on, will attempt to return all data that can be returned successfully, and errors embedded in the result where there were (partial) failures. In such cases a negative failure return code from the routine indicates catastrophic failure, otherwise success is returned and indicators for the partial failures are returned embedded in the results.