Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Scripting Components Reference

Required Scripting Component Routines / Executing and Disposing of Scripts

OSAScriptError

You can use the OSAScriptError function to get information about errors that occur during script execution.

FUNCTION OSAScriptError(scriptingComponent: ComponentInstance;
                        selector: OSType;
                        desiredType: DescType;
                        VAR resultingErrorDescription: AEDesc)
                        : OSAError;

scriptingComponent

A component instance created by a prior call to the Component Manager function OpenDefaultComponent or OpenComponent (see page 10-4).

selector

A value that determines what OSAScriptError returns. The value can be one of these constants:

            CONST
               kOSAErrorNumber            = 'errn';
               kOSAErrorMessage           = 'errs';
               kOSAErrorBriefMessage      = 'errb';
               kOSAErrorApp               = 'erap';
               kOSAErrorPartialResult     = 'ptlr';
               kOSAErrorOffendingObject   = 'erob';
               kOSAErrorRange             = 'erng';

desiredType

The desired descriptor type of the resulting descriptor record. The description that follows explains how this is determined by the value passed in the selector parameter.

resultingErrorDescription

The resulting descriptor record.

DESCRIPTION

Whenever the OSAExecute function returns the error errOSAScriptError, you can use the OSAScriptError function to get more specific information about the error from the scripting component that encountered it. (This information remains available only until the next call to the same scripting component.) The information returned by OSAScriptError depends on the value passed in the selector parameter, which also determines the descriptor type you should specify in the desiredType parameter.

Constant	Information returned in resultingErrorDescription parameter
kOSAErrorNumber	Error number for either system error or scripting component error. The value of desiredType must be typeShortInteger.
kOSAErrorMessage	Error message associated with error number, including both the name of the application and a description of the error. This constant is sufficient for simple error reporting. The value of desiredType must be typeChar or another text descriptor type.
kOSAErrorBriefMessage	Brief error message associated with error number, excluding the name of the application, any partial result, and the offending object. The value of desiredType must be typeChar or another text descriptor type.
kOSAErrorApp	Either the name or the process serial number (PSN) of the application that received the error, if it was the result of sending an Apple event. The value of desiredType must be typeProcessSerialNumber (for the PSN) or a text descriptor type such as typeChar (for the name).
kOSAErrorPartialResult	Partial result returned after a call to AESend that failed. This consists of a reply parameter that contains some but not all of the information requested.The value of desiredType must be typeBest (for the best type) or typeWildCard (for the default type).
kOSAErrorOffendingObject	An object specifier record for the object that caused the error. The value of desiredType must be typeObjectSpecifier, typeBest, or typeWildCard. For some scripting components, including AppleScript, these three values are equivalent.
kOSAErrorRange	Range of source data in which error occurred. The value of desiredType must be typeOSAErrorRange.

Every scripting component should support calls to OSAScriptError that pass kOSAErrorNumber, kOSAErrorMessage, or kOSAErrorPartialResult in the selector parameter.

Some scripting components may also support calls that pass other values in the selector parameter, including kOSAErrorRange, which provides start and end positions delimiting the errant expression in the source data. If the value of the selector parameter is kOSAErrorRange, the value of desiredType must be typeOSAErrorRange.

CONST typeOSAErrorRange          = 'erng';

A descriptor record of type typeOSAErrorRange is an AE record that consists of two descriptor records of typeShortInteger specified by these keywords:

CONST
   keyOSASourceStart    = 'srcs'; {start of error range}
   keyOSASourceEnd      = 'srce'; {end of error range}

If the value of the selector parameter is kOSAErrorNumber, scripting components may return, in the resultingErrorDescription parameter, one of these general error codes:

errOSACantCoerce	-1700	Same as errAECoercionFail; can't coerce data to requested descriptor type
errOSACantAccess	-1728	Same as errAENoSuchObject; runtime error in resolution of object specifier record
errOSAGeneralError	-2700	General runtime error
errOSADivideByZero	-2701	Attempt to divide by zero
errOSANumericOverflow	-2702	Numeric overflow
errOSACantLaunch	-2703	Can't launch specified file because it isn't an application
errOSAAppNotHighLevelEventAware	-2704	Doesn't respond to Apple events
errOSACorruptTerminology	-2705	The application has a corrupted 'aete' resource
errOSAStackOverflow	-2706	Stack overflow
errOSAInternalTableOverflow	-2707	Internal table overflow
errASDataBlockTooLarge	-2708	Attempt to create a value larger than the allowable size
errOSATypeError	-1703	Same as errAEWrongDataType; wrong descriptor type
errOSAMessageNotUnderstood	-1708	Same as errAEEventNotHandled; event not handled or message not understood
errOSAUndefinedMessage	-1717	Same as errAEHandlerNotFound; handler not found for message
errOSAIllegalIndex	-1728	Same as errAEIllegalIndex; not a valid index
errOSAIllegalRange	-2720	Same as errAEImpossibleRange; range of specified objects not possible
errOSASyntaxError	-2740	General syntax error
errOSASyntaxTypeError	-2741	Syntax error; parser expected one type but found another
errOSATokenTooLong	-2742	Identifier too long
errOSAMissingParameter	-1701	Same as errAEDescNotFound; descriptor record not found
errOSAParameterMismatch	-1721	Same as errAEWrongNumberArgs; wrong number of arguments
errOSADuplicateParameter	-2750	Parameter specified more than once
errOSADuplicateProperty	-2751	Property specified more than once
errOSADuplicateHandler	-2752	Handler defined more than once
errOSAUndefinedVariable	-2753	Undefined variable
errOSAInconsistentDeclarations	-2754	Inconsistent declarations
errOSAControlFlowError	-2755	Control flow error

Although scripting components are not required to support these error codes, their use simplifies error handling for applications that run scripts created by multiple components.

If the value of the selector parameter is kOSAErrorNumber, the AppleScript component may return, in the resultingErrorDescription parameter, one of these error codes:

errAECantConsiderAndIgnore	-2720	Can't both consider and ignore a parameter
errASCantCompareMoreThan32k	-2721	Can't compare text larger than 32K
errASCantCompareMixedScripts	-2722	Can't compare text from different script systems
errASTerminologyNestingTooDeep	-2760	Tell statements nested too deeply
errASInconsistentNames	-2780	Syntax error; names at beginning and end of handler are inconsistent (AppleScript English dialect only)

SPECIAL CONSIDERATIONS

If you call OSAScriptError using an instance of the generic scripting component, the generic scripting component uses the same instance of a scripting component that it used for the previous call.

RESULT CODES

noErr	0	No error
errOSACantCoerce	-1700	Desired type not supported by scripting component
errOSASystemError	-1750	General scripting system error
errOSABadSelector	-1754	Selector value not supported by scripting component
badComponentInstance	$80008001	Invalid component instance

SEE ALSO

For an example of the use of OSAScriptError, see Listing 10-3 on page 10-11.