This documentation supports the 21.3 version of Action Request System.

To view an earlier version, select the version from the Product version menu.

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  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 AR System server , operating system, or database management system. The AR_MAX_MESSAGE_SIZE limits the length to 255 bytes.



Operation successful — status might contain one or more informational messages.



Operation successful, but some problems encountered — status contains one or more warning messages and might also contain informational messages.



Operation failed — status contains one or more error messages and might also contain warning or informational messages.



Operation failed — status might contain one or more messages.



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. 



Status for the active link action.



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