Status information
The last return value of almost all API functions is a status parameter. This parameter contains information about the success or failure of the call. The status variable is a pointer to a structure (see the following figure).
Structure used to return function status 
Like all list structures in BMC Remedy AR System (see Lists and structures), ARStatusList has zero or more ARStatusStruct items. Each ARStatusStruct item represents a message that the function call generates and has the following elements:
| Integer that specifies the type of message being returned (see the following table). |
| Error number associated with the message (defined in arerrno.h). |
| Message text in the language that the |
| Text that augments the message text. This text might come from the BMC Remedy AR System server, operating system, or database management system. The |
0 | AR_RETURN_OK | Operation successful — status might contain one or more informational messages. |
1 | AR_RETURN_WARNING | Operation successful, but some problems encountered — status contains one or more warning messages and might also contain informational messages. |
2 | AR_RETURN_ERROR | Operation failed — status contains one or more error messages and might also contain warning or informational messages. |
3 | AR_RETURN_FATAL | Operation failed — status might contain one or more messages. |
4 | AR_RETURN_BAD_STATUS | Invalid status parameter — operation cancelled. Important: You can use this parameter through an API in a custom program. This indicates an issue related to a bad input parameter. |
5 | AR_RETURN_PROMPT | Status for the active link action. |
6 | AR_RETURN_ACCESSIBLE | Status message for client accessibility. |
The following figure shows an example of the layout of the ARStatusList structure.
Example of ARStatusList structure 
In this example, the status parameter is defined as a stack variable of type ARStatusList and has an integer that specifies the number of messages in the list (three in this case) and a pointer to their location on the heap. Based on the size and number of the returned messages, the system dynamically allocates the memory space.
The messages themselves are stored in an array of ARStatusStruct structures, each containing the message type, message number, and pointers to the message text and any appended text. The messages are sorted in decreasing order of severity, based on the message type value (see Error checking). The return value for the function is the message type associated with the first (most recent and most serious) message in the list. In this example, the return value is 2.
To access individual elements in the list, use standard array notation. For example, status.statusList.messageText identifies the message text associated with the first message, and status.statusList.messageNum provides the message number for the second message
After a program processes a returned status list, it must call FreeARStatusList to free any allocated memory. If numItems equals zero, the call is optional.
Comments
Log in or register to comment.