Error: Invalid spaceKey on retrieving a related space config.

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:

Message Type

Integer that specifies the type of message being returned (see the following table).

Message Number

Error number associated with the message (defined in arerrno.h).

Message Text

Message text in the language that the ARControlStruct specifies (if possible). To get the text of the message in the local language, call ARGetTextForErrorMessage.

Appended Text

Text that augments the message text. This text might come from the BMC Remedy AR System server, operating system, or database management system. The AR_MAX_MESSAGE_SIZE limits the length to 255 bytes.


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.

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.

Was this page helpful? Yes No Submitting... Thank you

Comments