This documentation applies to the 8.0 version of Remedy Action Request System, which is in "End of Version Support." You will not be able to leave comments.

To view the latest version, select the version from the Product version menu.

Error checking

All the C API functions (except FreeAR) return a status parameter (ARStatusList) that consists of zero or more notes, warnings, or errors generated from the function call (see Status information).

Each message consists of a value that indicates the type of message, the message number, and the message text (in the language specified in the control structure). More serious errors are listed first with lesser warnings and informational messages following. Within each category, messages are listed in reverse chronological order, with the most recent message first.

The return of the function itself is an integer value that indicates the success or failure of the call (see the following table). This value represents the status associated with the first (most recent and most serious) message in the list.

0

AR_RETURN_OK

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

1

AR_RETURN_WARNING

Operation successful, but a problem was 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 canceled.

You can ignore warnings and informational messages, although reporting warnings is often helpful. Because the C API returns all errors in a common structure, you can perform all error handling by using a single, generic routine. The following example provides a sample routine for checking return values.


ARStatusListstatus;
char			apicall[ar_MAX_APICALL_SIZE]; /* function name*/
int			rtn; /* function return value*/

rtn = ARGetEntry(&control, ..., &status);
strcpy(apicall,"ARGetEntry");
switch( rtn ){
	case AR_RETURN_OK:
		printf("\t%s: Successful\n", apicall);
		PrintARStatusList( &status );
		break;
	case AR_RETURN_WARNING:
		printf("\t%s: Warning\n", apicall);
		PrintARStatusList( &status );
		break;
	case AR_RETURN_ERROR:
		printf("\t%s: Error\n", apicall);
		PrintARStatusList( &status );
		exit(3);
		break;
	case AR_RETURN_FATAL:
		printf("\t%s: Fatal\n", apicall);
		exit(3);
		break;
	case AR_RETURN_BAD_STATUS:
		printf("\t%s: Bad Status\n", apicall);
		exit(3);
		break;
	default:
		printf("\t%s: Invalid return value: %d\n", apicall, rtn);
		exit(3);
}



Because the status structure uses allocated memory, you must free that memory after every C API call by using FreeARStatusList. You can call these functions regardless of whether the status structure contains any messages, because they perform no action if there are no messages to free (for more information, see Freeing allocated memory).

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

Comments