Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components

Summary of Scripting Components

Pascal Summary

Constants

CONST
   {Component Manager type and subtype codes}
   kOSAComponentType                      = 'osa ';   
   kOSAGenericScriptingComponentSubtype   = 'scpt';

   {null script ID passed to OSAExecute, OSAGetSource, or OSAStartRecording} 
   kOSANullScript                         = 0;     {empty script}

   {mode flag that indicates a routine's default mode settings are to be }
   { used}
   kOSAModeNull                           = 0;
   kOSANullMode                           = 0;

   {mode flag used with OSAStore to store a script context without storing }
   { its parent context}
   kOSAModeDontStoreParent                = $00004000;

   {mode flag used with OSAStore, OSALoad, or OSACompile to request } 
   { minimum script data}
   kOSAModePreventGetSource               = $00000001;
   
   {mode flags used with OSACompile, OSAExecute, OSALoadExecute, }
   { OSACompileExecute, OSADoScript, OSAExecuteEvent, and OSADoEvent}

   {these mode flags cause the scripting component to set the corresponding }
   { sendMode flags when it sends the event}
   kOSAModeNeverInteract                  = kAENeverInteract;        
   kOSAModeCanInteract                    = kAECanInteract;       
   kOSAModeAlwaysInteract                 = kAEAlwaysInteract;       
   kOSAModeDontReconnect                  = kAEDontReconnect;


   {this mode flag causes the scripting component not to set the } 
   { kAECanSwitchLayer sendMode flag when it sends the event}
   kOSAModeCantSwitchLayer                = $00000040;
               

   {this mode flag causes the scripting component not to set the } 
   { kAEDontRecord sendMode flag when it sends the event}
   kOSAModeDoRecord                       = $00001000;

   {mode flags used with OSACompile}

   {this mode flag causes OSACompile to compile the source data as a script } 
   { context}
   kOSAModeCompileIntoContext             = $00000002;

   {this mode flag causes OSACompile to augment the script data for a } 
   { script context rather than replacing it}
   kOSAModeAugmentContext                 = $00000004;

   {mode flags used with OSADisplay or OSADoScript to indicate that output }
   { needs to be readable by humans only and does not have to be recompiled }
   { by OSACompile} 
   kOSAModeDisplayForHumans               = $00000008;

   {suite and event code for the Recorded Text event}
   kOSASuite                              = 'ascr';
   kOSARecordedText                       = 'recd';

   {resource type for stored script data}
   kOSAScriptResourceType = kOSAGenericScriptingComponentSubtype;

   {descriptor type for generic storage descriptor records}
   typeOSAGenericStorage                  = kOSAScriptResourceType;

   {descriptor types and error range keywords for OSAScriptError}
   kOSAErrorNumber                        = 'errn'; {returns error number}
   kOSAErrorMessage                       = 'errs'; {returns error message}
   kOSAErrorBriefMessage                  = 'errb'; {returns brief error }
                                                    { message}
   kOSAErrorApp                           = 'erap'; {returns PSN or name of }
                                                    { errant application}
   kOSAErrorPartialResult                 = 'ptlr'; {returns partial }
                                                    { result, if any}
   kOSAErrorOffendingObject               = 'erob'; {returns info about }
                                                    { offending object, if }
                                                    { any}
   kOSAErrorRange                         = 'erng'; {returns error range}

   typeOSAErrorRange                      = 'erng'; {descriptor type for }
                                                    { error range}
   keyOSASourceStart                      = 'srcs'; {start of error range}
   keyOSASourceEnd                        = 'srce'; {end of error range}

   {if selector parameter of kOSAScriptError is kOSAErrorNumber, scripting }
   { components may return any of these error codes}

   {dynamic errors}
   errOSACantCoerce                       = errAECoercionFail;
   errOSACantAccess                       = errAENoSuchObject;
   errOSAGeneralError                     = -2700;
   errOSADivideByZero                     = -2701;
   errOSANumericOverflow                  = -2702;
   errOSACantLaunch                       = -2703;
   errOSAAppNotHighLevelEventAware        = -2704;
   errOSACorruptTerminology               = -2705;
   errOSAStackOverflow                    = -2706;
   errOSAInternalTableOverflow            = -2707;
   errOSADataBlockTooLarge                = -2708;

   {component-specific dynamic script errors: -2720 through -2739}

   {static errors}
   errTypeError                           = errAEWrongDataType;
   errOSAMessageNotUnderstood             = errAEEventNotHandled;
   errOSAUndefinedMessage                 = errAEHandlerNotFound;
   errOSAIllegalIndex                     = errAEIllegalIndex;
   errOASIllegalRange                     = errAEImpossibleRange;
   errOSASyntaxError                      = -2740;
   errOSASyntaxTypeError                  = -2741;
   errOSATokenTooLong                     = -2742;
   errOSAMissingParameter                 = errAEDescNotFound;
   errOSAParameterMismatch                = errAEWrongNumberArgs;
   errOSADuplicateParameter               = -2750;
   errOSADuplicateProperty                = -2751;
   errOSADuplicateHandler                 = -2752;
   errOSAUndefinedVariable                = -2753;
   errOSAInconsistentDeclarations         = -2754;
   errOSAControlFlowError                 = -2755;

   {component-specific static script errors: -2760 through -2779}

   {dialect-specific script errors: -2780 through -2799}

   {descriptor type for each item in list returned by OSAAvailableDialects}
   typeOSADialectInfo                     = 'difo'; 

   {keywords for descriptor record of descriptor type typeOSADialectInfo; }
   { these can also be used in selector parameter of OSAGetDialectInfo}
   keyOSADialectName                      = 'dnam'; {used with descriptor }
                                                    { record of any text }
                                                    { type, such as typeChar}
   keyOSADialectCode                      = 'dcod'; {used with descriptor }
                                                    { record of type }
                                                    { typeShortInteger}
   keyOSADialectLangCode                  = 'dlcd'; {used with descriptor }
                                                    { record of type }
                                                    { typeShortInteger}
   keyOSADialectScriptCode                = 'dscd'; {used with descriptor }
                                                    { record of type }
                                                    { typeShortInteger}

   {constants for use with OSASetResumeDispatchProc}
   kOSAUseStandardDispatch                = kAEUseStandardDispatch;
   kOSANoDispatch                         = kAENoDispatch;
   kOSADontUsePhac                        = $0001;

   {selectors for use with OSAGetScriptInfo}
   kOSAScriptIsModified                   = 'modi';
   kOSAScriptIsTypeCompiledScript         = 'cscr';
   kOSAScriptIsTypeScriptValue            = 'valu';
   kOSAScriptIsTypeScriptContext          = 'cntx';
   kOSAScriptBestType                     = 'best';
   kOSACanGetSource                       = 'gsrc';

   {OSA component flags}
   kOSASupportsCompiling                  = $0002;
   kOSASupportsGetSource                  = $0004;
   kOSASupportsAECoercion                 = $0008;
   kOSASupportsAESending                  = $0010;
   kOSASupportsRecording                  = $0020;
   kOSASupportsConvenience                = $0040;
   kOSASupportsDialects                   = $0080;
   kOSASupportsEventHandling              = $0100;

   {component selectors}

   {basic scripting}
   kOSASelectLoad                      = $0001;
   kOSASelectStore                     = $0002;
   kOSASelectExecute                   = $0003;
   kOSASelectDisplay                   = $0004;
   kOSASelectScriptError               = $0005;
   kOSASelectDispose                   = $0006;
   kOSASelectSetScriptInfo             = $0007;
   kOSASelectGetScriptInfo             = $0008;
   kOSASelectSetActiveProc             = $0009;
   kOSASelectGetActiveProc             = $000A;

   {compiling}
   kOSASelectScriptingComponentName    = $0102;
   kOSASelectCompile                   = $0103;
   kOSASelectCopyID                    = $0104;

   {getting source data}
   kOSASelectGetSource                 = $0201;

   {coercing script values}
   kOSASelectCoerceFromDesc            = $0301;
   kOSASelectCoerceToDesc              = $0302;

   {manipulating send and create functions}
   kOSASelectSetSendProc               = $0401;
   kOSASelectGetSendProc               = $0402;
   kOSASelectSetCreateProc             = $0403;
   kOSASelectGetCreateProc             = $0404;
   kOSASelectSetDefaultTarget          = $0405;

   {recording}
   kOSASelectStartRecording            = $0501;
   kOSASelectStopRecording             = $0502;


   {convenience}
   kOSASelectLoadExecute               = $0601;
   kOSASelectCompileExecute            = $0602;
   kOSASelectDoScript                  = $0603;
   {manipulating dialects}
   kOSASelectSetCurrentDialect         = $0701;
   kOSASelectGetCurrentDialect         = $0702;
   kOSASelectAvailableDialects         = $0703;
   kOSASelectGetDialectInfo            = $0704;
   kOSASelectAvailableDialectCodeList  = $0705;

   {executing Apple event handlers in script contexts}
   kOSASelectSetResumeDispatchProc     = $0801;
   kOSASelectGetResumeDispatchProc     = $0802;
   kOSASelectExecuteEvent              = $0803;
   kOSASelectDoEvent                   = $0804;
   kOSASelectMakeContext               = $0805;

   {scripting-component-specific selectors begin with this value}
   kOSASelectComponentSpecificStart    = $1001;

{*******AppleScript component constants*******}
   typeAppleScript                     = 'ascr';

   {Component Manager subtype for AppleScript component}
   kAppleScriptSubtype                 = typeAppleScript;

   {AppleScript constant for storage descriptor records}
   typeASStorage                       = typeAppleScript;

   {AppleScript constant for the selector parameter of OSAGetScriptInfo}
   kASHasOpenHandler                   = 'hsod';

   {AppleScript component selectors}
   kASSelectInit                       = $1001;
   kASSelectSetSourceStyles            = $1002;
   kASSelectGetSourceStyles            = $1003;
   kASSelectGetSourceStyleNames        = $1004;

   {default initialization parameters for AppleScript}
   kASDefaultMinStackSize              = 1 * 1024;
   kASDefaultPreferredStackSize        = 4 * 1024;
   kASDefaultMaxStackSize              = 16 * 1024;
   kASDefaultMinHeapSize               = 4 * 1024;
   kASDefaultPreferredHeapSize         = 64 * 1024;
   kASDefaultMaxHeapSize               = 32 * 1024 * 1024;

   {AppleScript source style flags}
   kASSourceStyleUncompiledText            = 0;
   kASSourceStyleNormalText                = 1;
   kASSourceStyleLanguageKeyword           = 2;
   kASSourceStyleApplicationKeyword        = 3;
   kASSourceStyleComment                   = 4;
   kASSourceStyleLiteral                   = 5;
   kASSourceStyleUserSymbol                = 6;
   kASSourceStyleObjectSpecifier           = 7;
   kASNumberOfSourceStyles                 = 8;

   {if selector parameter of kOSAScriptError is kOSAErrorNumber, }
   { AppleScript component may return any of these error codes}

   errASCantConsiderAndIgnore              = -2720;
   errASCantCompareMoreThan32k             = -2721;
   errASCantCompareMixedScripts            = -2722;
   errASTerminologyNestingTooDeep          = -2760;
   errASInconsistentNames                  = -2780; {English dialect}

{*******generic scripting component constants*******}

   {component version this header file describes}
   kGenericComponentVersion                = $0100;

   {generic scripting component selectors}
   kGSSSelectGetDefaultScriptingComponent  = $1001;
   kGSSSelectSetDefaultScriptingComponent  = $1002;
   kGSSSelectGetScriptingComponent         = $1003;
   kGSSSelectGetScriptingComponentFromStored = $1004;
   kGSSSelectGenericToRealID               = $1005;
   kGSSSelectRealToGenericID               = $1006;

Data Types

TYPE
   OSAID                         = LongInt;         {script ID}
   OSAError                      = ComponentResult; {type for result codes}

   {pointers for application-defined functions}
   OSAActiveProcPtr              = ProcPtr;
   AESendProcPtr                 = ProcPtr; 
   AECreateAppleEventProcPtr     = ProcPtr;
   AEHandlerProcPtr              = EventHandlerProcPtr;

   {generic scripting component data types}
   ScriptingComponentSelector = OSType;
   GenericID                  = OSAID;

Required Scripting Component Routines

Saving and Loading Script Data

FUNCTION OSAStore(scriptingComponent: ComponentInstance; 
scriptID: OSAID; 
desiredType: DescType;
modeFlags: LongInt;
VAR resultingScriptData: AEDesc): OSAError;
FUNCTION OSALoad(scriptingComponent: ComponentInstance; 
scriptData: AEDesc;
modeFlags: LongInt;
VAR resultingScriptID: OSAID): OSAError;

Executing and Disposing of Scripts

FUNCTION OSAExecute(scriptingComponent: ComponentInstance;
compiledScriptID: OSAID;
contextID: OSAID;
modeFlags: LongInt;
VAR resultingScriptValueID: OSAID): OSAError;
FUNCTION OSADisplay(scriptingComponent: ComponentInstance;
scriptValueID: OSAID; 
desiredType: DescType;
modeFlags: LongInt;
VAR resultingText: AEDesc): OSAError;
FUNCTION OSAScriptError(scriptingComponent: ComponentInstance;
selector: OSType;
desiredType: DescType;
VAR resultingErrorDescription: AEDesc)
: OSAError;
FUNCTION OSADispose(scriptingComponent: ComponentInstance; 
scriptID: OSAID): OSAError;

Setting and Getting Script Information

FUNCTION OSASetScriptInfo(scriptingComponent: ComponentInstance;
scriptID: OSAID; selector: OSType;
value: LongInt): OSAError;
FUNCTION OSAGetScriptInfo(scriptingComponent: ComponentInstance;
scriptID: OSAID; selector: OSType;
VAR result: LongInt): OSAError;

Manipulating the Active Function

FUNCTION OSASetActiveProc(scriptingComponent: ComponentInstance;
activeProc: OSAActiveProcPtr;
refCon: LongInt): OSAError;
FUNCTION OSAGetActiveProc(scriptingComponent: ComponentInstance;
VAR activeProc: OSAActiveProcPtr;
VAR refCon: LongInt): OSAError;

Optional Scripting Component Routines

Compiling Scripts

FUNCTION OSAScriptingComponentName
(scriptingComponent: ComponentInstance;
VAR resultingScriptingComponentName: AEDesc)
: OSAError;
FUNCTION OSACompile(scriptingComponent: ComponentInstance; 
sourceData: AEDesc; modeFlags: LongInt;
VAR previousAndResultingScriptID: OSAID)
: OSAError;
FUNCTION OSACopyID(scriptingComponent: ComponentInstance;
fromID: OSAID; VAR toID: OSAID): OSAError;

Getting Source Data

FUNCTION OSAGetSource(scriptingComponent: ComponentInstance;
scriptID: OSAID; desiredType: DescType;
VAR resultingSourceData: AEDesc): OSAError;

Coercing Script Values

FUNCTION OSACoerceFromDesc(scriptingComponent: ComponentInstance;
scriptData: AEDesc; modeFlags: LongInt;
VAR resultingScriptValueID: OSAID): OSAError;
FUNCTION OSACoerceToDesc(scriptingComponent: ComponentInstance;
scriptValueID: OSAID; 
desiredType: DescType; modeFlags: LongInt;
VAR result: AEDesc): OSAError;

Manipulating the Create and Send Functions

FUNCTION OSASetCreateProc(scriptingComponent: ComponentInstance;
createProc: AECreateAppleEventProcPtr;
refCon: LongInt): OSAError;
FUNCTION OSAGetCreateProc(scriptingComponent: ComponentInstance;
VAR createProc: AECreateAppleEventProcPtr;
VAR refCon: LongInt): OSAError;
FUNCTION OSASetSendProc(scriptingComponent: ComponentInstance;
sendProc: AESendProcPtr; 
refCon: LongInt): OSAError;
FUNCTION OSAGetSendProc(scriptingComponent: ComponentInstance;
VAR sendProc: AESendProcPtr;
VAR refCon: LongInt): OSAError;
FUNCTION OSASetDefaultTarget
(scriptingComponent: ComponentInstance;
target: AEAddressDesc): OSAError;

Recording Scripts

FUNCTION OSAStartRecording(scriptingComponent: ComponentInstance;
VAR compiledScriptToModifyID: OSAID): OSAError;
FUNCTION OSAStopRecording(scriptingComponent: ComponentInstance; 
compiledScriptID: OSAID): OSAError;

Executing Scripts in One Step

FUNCTION OSALoadExecute(scriptingComponent: ComponentInstance; 
scriptData: AEDesc;
contextID: OSAID; modeFlags: LongInt;
VAR resultingScriptValueID: OSAID): OSAError;
FUNCTION OSACompileExecute(scriptingComponent: ComponentInstance; 
sourceData: AEDesc;
contextID: OSAID; modeFlags: LongInt;
VAR resultingScriptValueID: OSAID): OSAError;
FUNCTION OSADoScript(scriptingComponent: ComponentInstance; 
sourceData: AEDesc;
contextID: OSAID;
desiredType: DescType; modeFlags: LongInt;
VAR resultingText: AEDesc): OSAError;

Manipulating Dialects

FUNCTION OSASetCurrentDialect
(scriptingComponent: ComponentInstance;
dialectCode		: Integer): OSAError;
FUNCTION OSAGetCurrentDialect
(scriptingComponent			: ComponentInstance;
VAR resultingDialectCode	: Integer): OSAError;
FUNCTION OSAAvailableDialectCodeList
(scriptingComponent				: ComponentInstance;
VAR resultingDialectCodeList	: AEDesc)
: OSAError;
FUNCTION OSAGetDialectInfo(scriptingComponent: ComponentInstance;
dialectCode: Integer; selector: OSType;
VAR resultingDialectInfo: AEDesc): OSAError;
FUNCTION OSAAvailableDialects
(scriptingComponent				: ComponentInstance;
VAR resultingDialectCodeList	: AEDesc)
: OSAError;

Using Script Contexts to Handle Apple Events

FUNCTION OSASetResumeDispatchProc
(scriptingComponent: ComponentInstance;
resumeDispatchProc: AEHandlerProcPtr;
refCon: LongInt): OSAError;
FUNCTION OSAGetResumeDispatchProc
(scriptingComponent: ComponentInstance;
VAR resumeDispatchProc: AEHandlerProcPtr;
VAR refCon: LongInt): OSAError;
FUNCTION OSAExecuteEvent(scriptingComponent: ComponentInstance;
theAppleEvent: AppleEvent;
contextID: OSAID; modeFlags: LongInt;
VAR resultingScriptValueID: OSAID): OSAError;
FUNCTION OSADoEvent(scriptingComponent: ComponentInstance;
theAppleEvent: AppleEvent;
contextID: OSAID; modeFlags: LongInt;
VAR reply: AppleEvent): OSAError;
FUNCTION OSAMakeContext(scriptingComponent: ComponentInstance;
contextName: AEDesc;
parentContext: OSAID;
VAR resultingContextID: OSAID): OSAError;

AppleScript Component Routines

Initializing AppleScript

FUNCTION ASInit(scriptingComponent: ComponentInstance;
modeFlags: LongInt;
minStackSize: LongInt;
preferredStackSize: LongInt;
maxStackSize: LongInt;
minHeapSize: LongInt;
preferredHeapSize: LongInt;
maxHeapSize: LongInt): OSAError;

Getting and Setting Styles for Source Data

FUNCTION ASGetSourceStyles(scriptingComponent: ComponentInstance;
VAR resultingSourceStyles: STHandle): OSAError;
FUNCTION ASSetSourceStyles(scriptingComponent: ComponentInstance;
sourceStyles: STHandle): OSAError;
FUNCTION ASGetSourceStyleNames
(scriptingComponent: ComponentInstance;
modeFlags: LongInt;
VAR resultingSourceStyleNamesList: AEDescList)
: OSAError;

Generic Scripting Component Routines

Getting and Setting the Default Scripting Component

FUNCTION OSAGetDefaultScriptingComponent
(genericScriptingComponent: ComponentInstance;
VAR scriptingSubType: ScriptingComponentSelector): OSAError;
FUNCTION OSASetDefaultScriptingComponent
(genericScriptingComponent: ComponentInstance;
scriptingSubType: ScriptingComponentSelector): OSAError;

Using Component-Specific Routines

FUNCTION OSAGetScriptingComponentFromStored
(genericScriptingComponent: ComponentInstance;
scriptData: AEDesc; 
VAR scriptingSubType: ScriptingComponentSelector): OSAError;
FUNCTION OSAGetScriptingComponent
(genericScriptingComponent: ComponentInstance;
scriptingSubType: ScriptingComponentSelector;
VAR scriptingInstance: ComponentInstance)
: OSAError;
FUNCTION OSAGenericToRealID(genericScriptingComponent: ComponentInstance;
VAR theScriptID: OSAID; 
VAR theExactComponent: ComponentInstance)
: OSAError;
FUNCTION OSARealToGenericID(genericScriptingComponent: ComponentInstance;
VAR theScriptID: OSAID; 
theExactComponent: ComponentInstance)
: OSAError;

Routines Used by Scripting Components

Manipulating Trailers for Generic Storage Descriptor Records

FUNCTION OSAGetStorageType(scriptData: Handle; VAR type: DescType): OSErr;
FUNCTION OSAAddStorageType(scriptData: Handle; type: DescType): OSErr;
FUNCTION OSARemoveStorageType
(scriptData: Handle): OSErr;

Application-Defined Routines

FUNCTION MyActiveProc(refCon: LongInt): OSErr;
FUNCTION MyAECreateProc (theAEEventClass: AEEventClass; 
theAEEventID: AEEventID; target: AEAddressDesc; 
returnID: Integer; transactionID: LongInt; 
VAR result: AppleEvent; 
refCon: LongInt): OSErr;
FUNCTION MyAESendProc (theAppleEvent: AppleEvent; 
VAR reply: AppleEvent; sendMode: AESendMode; 
sendPriority: AESendPriority; 
timeOutInTicks: LongInt; 
idleProc: IdleProcPtr; 
filterProc: EventFilterProcPtr;
refCon: LongInt): OSErr;
FUNCTION MyResumeDispatch(theAppleEvent: AppleEvent; reply: AppleEvent; 
refCon: LongInt): OSErr;

C Summary

Constants

/*Component Manager type and subtype codes*/
#define kOSAComponentType              'osa '      
#define kOSAGenericScriptingComponentSubtype 'scpt'

/*null script ID passed to OSAExecute, OSAGetSource, or OSAStartRecording*/ 
#define kOSANullScript                 ((OSAID) 0)

/*mode flag that indicates a routine's default mode settings are to be used*/
#define kOSAModeNull                   0        
#define kOSANullMode                   0

/*mode flag used with OSAStore to store a script context without storing */
/* its parent context*/
#define kOSAModeDontStoreParent        0x00004000

/*mode flag used with OSAStore, OSALoad, or OSACompile to request */ 
/* minimum script data*/
#define kOSAModePreventGetSource       0x00000001

/*mode flags used with OSACompile, OSAExecute, OSALoadExecute, */
/* OSACompileExecute, OSADoScript, OSAExecuteEvent, and OSADoEvent*/

/*these mode flags cause the scripting component to set the corresponding */
/* sendMode flags when it sends the event*/
#define kOSAModeNeverInteract          kAENeverInteract           
#define kOSAModeCanInteract            kAECanInteract             
#define kOSAModeAlwaysInteract         kAEAlwaysInteract          
#define kOSAModeDontReconnect          kAEDontReconnect

/*this mode flag causes the scripting component not to set the */ 
/* kAECanSwitchLayer sendMode flag when it sends the event*/
#define kOSAModeCantSwitchLayer        0x00000040

/*this mode flag causes the scripting component not to set the */ 
/* kAEDontRecord sendMode flag when it sends the event*/
#define kOSAModeDoRecord               0x00001000


/*mode flags used with OSACompile*/

/*this mode flag causes OSACompile to compile the source data as a script */ 
/* context*/
#define kOSAModeCompileIntoContext     0x00000002

/*this mode flag causes OSACompile to augment the script data for a script */ 
/* context rather than replacing it*/
#define kOSAModeAugmentContext         0x00000004

/*mode flags used with OSADisplay or OSADoScript to indicate that output */
/* needs to be readable by humans only and does not have to be recompiled */
/* by OSACompile*/ 
#define kOSAModeDisplayForHumans       0x00000008

/*suite and event code for the Recorded Text event*/
#define kOSASuite                      'ascr'
#define kOSARecordedText               'recd'

/*resource type for stored script data*/
#define kOSAScriptResourceType         kOSAGenericScriptingComponentSubtype

/*descriptor type for generic storage descriptor records*/
#define typeOSAGenericStorage          kOSAScriptResourceType

/*descriptor types and error range keywords for OSAScriptError*/
#define kOSAErrorNumber                'errn'   /*returns error number*/
#define kOSAErrorMessage               'errs'   /*returns error message*/
#define kOSAErrorBriefMessage          'errb'   /*returns brief error */
                                                /* message*/
#define kOSAErrorApp                   'erap'   /*returns PSN or name of */
                                                /* errant application*/

#define kOSAErrorPartialResult         'ptlr'   /*returns partial result, */
                                                /* if any*/
#define kOSAErrorOffendingObject       'erob'   /*returns info about */
                                                /* offending object, if any*/
#define kOSAErrorRange                 'erng'   /*returns error range*/
#define typeOSAErrorRange              'erng'   /*descriptor type for */
                                                /* error range*/
#define keyOSASourceStart              'srcs'   /*start of error range*/
#define keyOSASourceEnd                'srce'   /*end of error range*/

/*if selector parameter of kOSAScriptError is kOSAErrorNumber, scripting */
/* components may return any of these error codes*/ 

/*dynamic errors*/
#define errOSACantCoerce                        errAECoercionFail
#define errOSACantAccess                        errAENoSuchObject
#define errOSAGeneralError                      -2700
#define errOSADivideByZero                      -2701
#define errOSANumericOverflow                   -2702
#define errOSACantLaunch                        -2703
#define errOSAAppNotHighLevelEventAware         -2704
#define errOSACorruptTerminology                -2705
#define errOSAStackOverflow                     -2706
#define errOSAInternalTableOverflow             -2707
#define errOSADataBlockTooLarge                 -2708

/*component-specific dynamic script errors: -2720 through -2739*/

/*static errors*/
#define errTypeError                            errAEWrongDataType
#define errOSAMessageNotUnderstood              errAEEventNotHandled
#define errOSAUndefinedMessage                  errAEHandlerNotFound
#define errOSAIllegalIndex                      errAEIllegalIndex
#define errOASIllegalRange                      errAEImpossibleRange
#define errOSASyntaxError                       -2740
#define errOSASyntaxTypeError                   -2741
#define errOSATokenTooLong                      -2742
#define errOSAMissingParameter                  errAEDescNotFound
#define errOSAParameterMismatch                 errAEWrongNumberArgs
#define errOSADuplicateParameter                -2750
#define errOSADuplicateProperty                 -2751
#define errOSADuplicateHandler                  -2752
#define errOSAUndefinedVariable                 -2753
#define errOSAInconsistentDeclarations          -2754
#define errOSAControlFlowError                  -2755

/*component-specific static script errors: -2760 through -2779*/

/*dialect-specific script errors: -2780 through -2799*/

/*descriptor type for each item in list returned by OSAAvailableDialects*/
#define typeOSADialectInfo             'difo'   

/*keywords for descriptor record of descriptor type typeOSADialectInfo; */
/* these can also be used in selector parameter of OSAGetDialectInfo*/
#define keyOSADialectName              'dnam'   /*used with descriptor */
                                                /* record of any text */
                                                /* type, such as typeChar*/
#define keyOSADialectCode              'dcod'   /*used with descriptor */
                                                /* record of type */
                                                /* typeShortInteger*/
#define keyOSADialectLangCode          'dlcd'   /*used with descriptor */
                                                /* record of type */
                                                /* typeShortInteger*/
#define keyOSADialectScriptCode        'dscd'   /*used with descriptor */
                                                /* record of type */
                                                /* typeShortInteger*/

/*constants for use with OSASetResumeDispatchProc*/
#define kOSAUseStandardDispatch        kAEUseStandardDispatch
#define kOSANoDispatch                 kAENoDispatch
#define kOSADontUsePhac                $0001

/*selectors for use with OSAGetScriptInfo*/
#define kOSAScriptIsModified           'modi'
#define kOSAScriptIsTypeCompiledScript 'cscr'
#define kOSAScriptIsTypeScriptValue    'valu'
#define kOSAScriptIsTypeScriptContext  'cntx'
#define kOSAScriptBestType             'best'
#define kOSACanGetSource               'gsrc'

/*OSA component flags*/
#define kOSASupportsCompiling          0x0002
#define kOSASupportsGetSource          0x0004
#define kOSASupportsAECoercion         0x0008
#define kOSASupportsAESending          0x0010
#define kOSASupportsRecording          0x0020
#define kOSASupportsConvenience        0x0040
#define kOSASupportsDialects           0x0080
#define kOSASupportsEventHandling      0x0100


/*component selectors*/

/*basic scripting*/
#define kOSASelectLoad                 0x0001
#define kOSASelectStore                0x0002
#define kOSASelectExecute              0x0003
#define kOSASelectDisplay              0x0004
#define kOSASelectScriptError          0x0005
#define kOSASelectDispose              0x0006
#define kOSASelectSetScriptInfo        0x0007
#define kOSASelectGetScriptInfo        0x0008
#define kOSASelectSetActiveProc        0x0009
#define kOSASelectGetActiveProc        0x000A

/*compiling*/
#define kOSASelectScriptingComponentName 0x0102
#define kOSASelectCompile              0x0103
#define kOSASelectCopyID               0x0104

/*getting source data*/
#define kOSASelectGetSource            0x0201

/*coercing script values*/
#define kOSASelectCoerceFromDesc       0x0301
#define kOSASelectCoerceToDesc         0x0302

/*manipulating send and create functions*/
#define kOSASelectSetSendProc          0x0401
#define kOSASelectGetSendProc          0x0402
#define kOSASelectSetCreateProc        0x0403
#define kOSASelectGetCreateProc        0x0404
#define kOSASelectSetDefaultTarget     0x0405

/*recording*/
#define kOSASelectStartRecording       0x0501
#define kOSASelectStopRecording        0x0502

/*convenience*/
#define kOSASelectLoadExecute          0x0601
#define kOSASelectCompileExecute       0x0602
#define kOSASelectDoScript             0x0603

/*manipulating dialects*/
#define kOSASelectSetCurrentDialect    0x0701
#define kOSASelectGetCurrentDialect    0x0702
#define kOSASelectAvailableDialects    0x0703
#define kOSASelectGetDialectInfo       0x0704
#define kOSASelectAvailableDialectCodeList 0x0705

/*executing Apple event handlers in script contexts*/
#define kOSASelectSetResumeDispatchProc   0x0801
#define kOSASelectGetResumeDispatchProc   0x0802
#define kOSASelectExecuteEvent            0x0803
#define kOSASelectDoEvent                 0x0804
#define kOSASelectMakeContext             0x0805

/*scripting-component-specific selectors are added beginning with this */
/* value*/
#define kOSASelectComponentSpecificStart  0x1001

/********AppleScript component constants********/
#define typeAppleScript                      'ascr'

/*Component Manager subtype for AppleScript component*/
#define kAppleScriptSubtype                  typeAppleScript

/*AppleScript constant for storage descriptor records*/
#define typeASStorage                        typeAppleScript

/*AppleScript constant for the selector parameter of OSAGetScriptInfo*/
#define kASHasOpenHandler                    'hsod'

/*AppleScript component selectors*/
#define kASSelectInit                        0x1001
#define kASSelectSetSourceStyles             0x1002
#define kASSelectGetSourceStyles             0x1003
#define kASSelectGetSourceStyleNames         0x1004

/*default initialization parameters for AppleScript*/
#define kASDefaultMinStackSize               1 * 1024
#define kASDefaultPreferredStackSize         4 * 1024
#define kASDefaultMaxStackSize               16 * 1024
#define kASDefaultMinHeapSize                4 * 1024
#define kASDefaultPreferredHeapSize          64 * 1024
#define kASDefaultMaxHeapSize                32 * 1024 * 1024

/*AppleScript source style flags*/
#define kASSourceStyleUncompiledText         0
#define kASSourceStyleNormalText             1
#define kASSourceStyleLanguageKeyword        2
#define kASSourceStyleApplicationKeyword     3
#define kASSourceStyleComment                4
#define kASSourceStyleLiteral                5
#define kASSourceStyleUserSymbol             6
#define kASSourceStyleObjectSpecifier        7
#define kASNumberOfSourceStyles              8

/*if selector parameter of kOSAScriptError is kOSAErrorNumber, AppleScript */
/* component may return any of these error codes*/ 

#define errASCantConsiderAndIgnore              -2720
#define errASCantCompareMoreThan32k             -2721
#define errASCantCompareMixedScripts            -2722
#define errASTerminologyNestingTooDeep          -2760
#define errASInconsistentNames                  -2780 /*English dialect*/

/*******generic scripting component constants*******/

/*component version this header file describes*/
kGenericComponentVersion                        0x0100

/*generic scripting component selectors*/
#define kGSSSelectGetDefaultScriptingComponent  0x1001
#define kGSSSelectSetDefaultScriptingComponent  0x1002
#define kGSSSelectGetScriptingComponent         0x1003
#define kGSSSelectGetScriptingSystemFromStored  0x1004
#define kGSSSelectGenericToRealID               0x1005
#define kGSSSelectRealToGenericID               0x1006

Data Types

typedef unsigned long            OSAID;            /*script ID*/
typedef ComponentResult          OSAError;         /*type for result codes*/

/*pointers for application-defined functions*/
typedef pascal OSErr (*OSAActiveProcPtr) (long refCon);
typedef pascal OSErr (*AESendProcPtr)
                             (const AppleEvent* theAppleEvent,
                              AppleEvent* reply, AESendMode sendMode,
                              AESendPriority sendPriority,
                              long timeOutInTicks, IdleProcPtr idleProc,
                              EventFilterProcPtr filterProc, long refCon);

typedef pascal OSErr (*AECreateAppleEventProcPtr)
                             (AEEventClass theAEEventClass,
                              AEEventID theAEEventID,
                              const AEAddressDesc* target, short returnID,
                              long transactionID, AppleEvent* result,
                              long refCon);
typedef pascal OSErr (*AEHandlerProcPtr)
                             (const AppleEvent* the AppleEvent,
                              AppleEvent* reply, long refCon);

/*generic scripting component data types*/
typedef OSType ScriptingComponentSelector;
typedef OSAID GenericID;

Required Scripting Component Routines

Saving and Loading Script Data

pascal OSAError OSAStore(ComponentInstance scriptingComponent, 
OSAID scriptID, DescType desiredType,
long modeFlags, AEDesc* resultingScriptData);
pascal OSAError OSALoad(ComponentInstance scriptingComponent, 
const AEDesc* scriptData, long modeFlags,
OSAID* resultingScriptID);

Executing and Disposing of Scripts

pascal OSAError OSAExecute(ComponentInstance scriptingComponent,
OSAID compiledScriptID, OSAID contextID,
long modeFlags, OSAID* resultingScriptValueID);
pascal OSAError OSADisplay(ComponentInstance scriptingComponent,
OSAID scriptValueID, DescType desiredType,
long modeFlags, AEDesc* resultingText);
pascal OSAError OSAScriptError
(ComponentInstance scriptingComponent,
OSType selector, DescType desiredType,
AEDesc* resultingErrorDescription);
pascal OSAError OSADispose(ComponentInstance scriptingComponent, 
OSAID scriptID);

Setting and Getting Script Information

pascal OSAError OSASetScriptInfo
(ComponentInstance scriptingComponent,
OSAID scriptID, OSType selector, long value);
pascal OSAError OSAGetScriptInfo
(ComponentInstance scriptingComponent,
OSAID scriptID, OSType selector, long* result);

Manipulating the Active Function

pascal OSAError OSASetActiveProc
(ComponentInstance scriptingComponent,
OSAActiveProcPtr activeProc, long refCon);
pascal OSAError OSAGetActiveProc
(ComponentInstance scriptingComponent,
OSAActiveProcPtr* activeProc, long* refCon);

Optional Scripting Component Routines

Compiling Scripts

pascal OSAError OSAScriptingComponentName
(ComponentInstance scriptingComponent,
AEDesc* resultingScriptingComponentName);
pascal OSAError OSACompile(ComponentInstance scriptingComponent, 
const AEDesc* sourceData,
long modeFlags,
OSAID* previousAndResultingScriptID);
pascal OSAError OSACopyID(ComponentInstance scriptingComponent,
OSAID fromID, OSAID* toID);

Getting Source Data

pascal OSAError OSAGetSource
(ComponentInstance scriptingComponent,
OSAID scriptID, DescType desiredType,
AEDesc* resultingSourceData);

Coercing Script Values

pascal OSAError OSACoerceFromDesc
(ComponentInstance scriptingComponent,
const AEDesc* scriptData, long modeFlags,
OSAID* resultingScriptValueID);
pascal OSAError OSACoerceToDesc
(ComponentInstance scriptingComponent,
OSAID scriptValueID, DescType desiredType,
long modeFlags, AEDesc* result);

Manipulating the Create and Send Functions

pascal OSAError OSASetCreateProc
(ComponentInstance scriptingComponent,
AECreateAppleEventProcPtr createProc,
long refCon);
pascal OSAError OSAGetCreateProc
(ComponentInstance scriptingComponent,
AECreateAppleEventProcPtr* createProc,
long* refCon);
pascal OSAError OSASetSendProc
(ComponentInstance scriptingComponent,
AESendProcPtr sendProc, long refCon);
pascal OSAError OSAGetSendProc
(ComponentInstance scriptingComponent,
AESendProcPtr* sendProc, long* refCon);
pascal OSAError OSASetDefaultTarget
(ComponentInstance scriptingComponent,
const AEAddressDesc* target);

Recording Scripts

pascal OSAError OSAStartRecording
(ComponentInstance scriptingComponent,
OSAID* compiledScriptToModifyID);
pascal OSAError OSAStopRecording
(ComponentInstance scriptingComponent, 
OSAID compiledScriptID);

Executing Scripts in One Step

pascal OSAError OSALoadExecute
(ComponentInstance scriptingComponent,
const AEDesc* scriptData, OSAID contextID,
long modeFlags, OSAID* resultingScriptValueID);
pascal OSAError OSACompileExecute
(ComponentInstance scriptingComponent,
const AEDesc* sourceData, OSAID contextID,
long modeFlags, OSAID* resultingScriptValueID);
pascal OSAError OSADoScript(ComponentInstance scriptingComponent,
const AEDesc* sourceData, OSAID contextID,
DescType desiredType, long modeFlags,
AEDesc* resultingText);

Manipulating Dialects

pascal OSAError OSASetCurrentDialect
(ComponentInstance scriptingComponent,
short dialectCode);
pascal OSAError OSAGetCurrentDialect
(ComponentInstance scriptingComponent,
short* resultingDialectCode);
pascal OSAError OSAAvailableDialectCodeList
(ComponentInstance scriptingComponent				,
AEDesc* resultingDialectCodeList);
pascal OSAError OSAGetDialectInfo
(ComponentInstance scriptingComponent,
short dialectCode, OSType selector,
AEDesc* resultingDialectInfo);
pascal OSAError OSAAvailableDialects
(ComponentInstance scriptingComponent				,
AEDesc* resultingDialectInfoList	);

Using Script Contexts to Handle Apple Events

pascal OSAError OSASetResumeDispatchProc
(ComponentInstance scriptingComponent	,
AEHandlerProcPtr resumeDispatchProc,
long refCon);
pascal OSAError OSAGetResumeDispatchProc
(ComponentInstance scriptingComponent	,
AEHandlerProcPtr* resumeDispatchProc,
long* refCon);
pascal OSAError OSAExecuteEvent
(ComponentInstance scriptingComponent	,
const AppleEvent* theAppleEvent,
OSAID contextID, long modeFlags,
OSAID* resultingScriptValueID);
pascal OSAError OSADoEvent(ComponentInstance scriptingComponent,
const AppleEvent* theAppleEvent,
OSAID contextID, long modeFlags,
AppleEvent* reply);
pascal OSAError OSAMakeContext
(ComponentInstance scriptingComponent,
const AEDesc* contextName,
OSAID parentContext, 
OSAID* resultingContextID);

AppleScript Component Routines

Initializing AppleScript

pascal OSAError ASInit(ComponentInstance scriptingComponent,
long modeFlags, long minStackSize,
long preferredStackSize, long maxStackSize,
long minHeapSize, long preferredHeapSize,
long maxHeapSize);

Getting and Setting Styles for Source Data

pascal OSAError ASGetSourceStyles
(ComponentInstance scriptingComponent,
STHandle* resultingSourceStyles);
pascal OSAError ASSetSourceStyles
(ComponentInstance scriptingComponent,
STHandle sourceStyles);
pascal OSAError ASGetSourceStyleNames
(ComponentInstance scriptingComponent,
long modeFlags,
AEDescList* resultingSourceStyleNamesList);

Generic Scripting Component Routines

Getting and Setting the Default Scripting Component

pascal OSAError OSAGetDefaultScriptingComponent
(ComponentInstance genericScriptingComponent, ScriptingComponentSelector* scriptingSubType);
pascal OSAError OSASetDefaultScriptingComponent
(ComponentInstance genericScriptingComponent,
ScriptingComponentSelector scriptingSubType);

Using Component-Specific Routines

pascal OSAError OSAGetScriptingComponentFromStored
(ComponentInstance genericScriptingComponent,
const AEDesc *scriptData, 
ScriptingComponentSelector scriptingSubType);
pascal OSAError OSAGetScriptingComponent
(ComponentInstance genericScriptingComponent,
ScriptingComponentSelector scriptingSubType,
ComponentInstance* scriptingInstance);
pascal OSAError OSAGenericToRealID
(ComponentInstance genericScriptingComponent,
OSAID *theScriptID, 
ComponentInstance *theExactComponent);
pascal OSAError OSARealToGenericID
(ComponentInstance genericScriptingComponent,
OSAID *theScriptID, 
ComponentInstance theExactComponent);

Routines Used by Scripting Components

Manipulating Trailers for Generic Storage Descriptor Records

pascal OSErr OSAGetStorageType
(Handle scriptData, DescType* type);
pascal OSErr OSAAddStorageType
(Handle scriptData, DescType type);
pascal OSErr OSARemoveStorageType
(Handle scriptData);

Application-Defined Routines

pascal OSErr MyActiveProc(long refCon);
pascal OSErr MyAECreateProc
(AEEventClass theAEEventClass,
AEEventID theAEEventID, AEAddressDesc target,
short returnID, long transactionID,
AppleEvent* result, long refCon);
pascal OSErr MyAESendProc(AppleEvent theAppleEvent, AppleEvent* reply,
AESendMode sendMode,
AESendPriority sendPriority,
long timeOutInTicks, IdleProcPtr idleProc,
EventFilterProcPtr filterProc, long refCon);
pascal OSErr MyResumeDispatch
(const AppleEvent* theAppleEvent,
AppleEvent* reply, long refCon);

Result Codes

noErr	0	No error
errOSACantCoerce	-1700	Same as errAECoercionFail; data could not be coerced to the requested data type
errOSACorruptData	-1702	Same as errAECorruptData
errAEEventNotHandled	-1708	Event wasn't handled by an Apple event handler
errAERecordingIsAlreadyOn	-1732	Attempt to turn recording on when it is already on for a recording process
errOSASystemError	-1750	General scripting system error
errOSAInvalidID	-1751	Invalid script ID
errOSABadStorageType	-1752	Illegal storage type
errOSAScriptError	-1753	Error occurred during compilation or execution
errOSABadSelector	-1754	Selector not supported by scripting component
errOSASourceNotAvailable	-1756	Source data not available
errOSANoSuchDialect	-1757	Invalid dialect code
errOSADataFormatObsolete	-1758	Data format is obsolete
errOSADataFormatTooNew	-1759	Data format is too new
errOSAComponentMismatch	-1761	Generic scripting component error; parameters are for two different scripting components instead of the same one
errOSACantOpenComponent	-1762	Generic scripting component error; can't connect to scripting component
badComponentInstance	$80008001	Invalid component instance