OSA(3) User Contributed Perl Documentation OSA(3)NAME
Mac::OSA - Provide interface to Open Scripting Architecture
SYNOPSIS
use Mac::OSA;
use Mac::OSA qw(OSALoad OSAStore OSAExecute);
DESCRIPTION
Access to Inside Macintosh is essential for proper use of these
functions. Explanations of terms, processes and procedures are
provided there. Any attempt to use these functions without guidance
can cause severe errors in your machine, including corruption of data.
You have been warned.
Constants
kOSAComponentType
kOSAGenericScriptingComponentSubtype
kOSAFileType
kOSASuite
kOSARecordedText
kOSAScriptIsModified
kOSAScriptIsTypeCompiledScript
kOSAScriptIsTypeScriptValue
kOSAScriptIsTypeScriptContext
kOSAScriptBestType
kOSACanGetSource
typeOSADialectInfo
keyOSADialectName
keyOSADialectCode
keyOSADialectLangCode
keyOSADialectScriptCode
kOSAScriptResourceType
typeOSAGenericStorage
Types and keywords.
kOSANullScript
kOSANullMode
kOSAModeNull
Default values.
kOSASupportsCompiling
kOSASupportsGetSource
kOSASupportsAECoercion
kOSASupportsAESending
kOSASupportsRecording
kOSASupportsConvenience
kOSASupportsDialects
kOSASupportsEventHandling
Feature flags.
kOSAModePreventGetSource
kOSAModeNeverInteract
kOSAModeCanInteract
kOSAModeAlwaysInteract
kOSAModeDontReconnect
kOSAModeCantSwitchLayer
kOSAModeDoRecord
kOSAModeCompileIntoContext
kOSAModeAugmentContext
kOSAModeDisplayForHumans
kOSAModeDontStoreParent
kOSAModeDispatchToDirectObject
kOSAModeDontGetDataForArguments
kOSAModeDontDefine
Mode flags.
kOSAErrorNumber
kOSAErrorMessage
kOSAErrorBriefMessage
kOSAErrorApp
kOSAErrorPartialResult
kOSAErrorOffendingObject
kOSAErrorExpectedType
kOSAErrorRange
typeOSAErrorRange
keyOSASourceStart
keyOSASourceEnd
Error handling.
kOSAUseStandardDispatch
kOSANoDispatch
kOSADontUsePhac
kGenericComponentVersion
Dispatching flags
Functions
OSALoad SCRIPTINGCOMPONENT, SCRIPTDATA, MODEFLAGS
The OSALoad function loads script data and returns a script ID. The
generic scripting component uses the descriptor record in the
SCRIPTDATA parameter to determine which scripting component should
load the script. If the descriptor record is of type
typeOSAGenericStorage, the generic scripting component uses the
trailer at the end of the SCRIPTDATA to identify the scripting
component. If the descriptor record's type is the subtype value for
another scripting component, the generic scripting component uses
the descriptor type to identify the scripting component. Return
"undef" if an error was detected.
OSAStore SCRIPTINGCOMPONENT, SCRIPTID, DESIREDTYPE, MODEFLAGS
The OSAStore function returns script data in a descriptor record so
that the data can later be saved in a resource or written to the
data fork of a document. You can then reload the data for the
descriptor record as a compiled script (although possibly with a
different script ID) by passing the descriptor record to OSALoad().
Return "undef" if an error was detected.
OSAExecute SCRIPTINGCOMPONENT, COMPILEDSCRIPTID, CONTEXTID, MODEFLAGS
The OSAExecute function executes the compiled script identified by
the COMPILEDSCRIPTID parameter, using the script context identified
by the CONTEXTID parameter to maintain state information, such as
the binding of variables, for the compiled script. After
successfully executing a script, OSAExecute returns the script ID
for a resulting script value, or, if execution does not result in a
value, "undef".
OSADisplay SCRIPTINGCOMPONENT, SCRIPTVALUEID, DESIREDTYPE, MODEFLAGS
The OSADisplay function coerces the script value identified by
SCRIPTVALUEID to a descriptor record of the text type specified by
the DESIREDTYPE parameter, if possible. Valid types include all the
standard text descriptor types defined in the Apple Event Registry:
Standard Suites, plus any special types supported by the scripting
component. Return "undef" if an error was detected.
OSAScriptError SCRIPTINGCOMPONENT, SELECTOR, DESIREDTYPE
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.
Return "undef" if an error was detected.
OSADispose SCRIPTINGCOMPONENT, SCRIPTID
The OSADispose function releases the memory assigned to the script
data identified by the SCRIPTID parameter. The SCRIPTID passed to
the OSADispose function is no longer valid if the function returns
successfully. A scripting component can then reuse that SCRIPTID
for other script data. Return zero if no error was detected.
OSASetScriptInfo SCRIPTINGCOMPONENT, SCRIPTID, SELECTOR, VALUE
The OSASetScriptInfo function sets script information according to
the value you pass in the selector parameter. If you use the
kOSAScriptIsModified constant, OSASetScriptInfo sets a value that
indicates how many times the script data has been modified since it
was created or passed to OSALoad. Some scripting components may
provide additional constants. Return zero if no error was
detected.
OSAGetScriptInfo SCRIPTINGCOMPONENT, SCRIPTID, SELECTOR
The OSAGetScriptInfo function returns various results according to
the value you pass in the SELECTOR parameter. Returns an integer
value which may need to be recast as the desired type.
OSASetProperty SCRIPTINGCOMPONENT, MODEFLAGS, SCRIPTID, VARIABLENAME,
SCRIPTVALUEID
The OSASetProperty function sets the value of a script property in
a specified script. VARIABLENAME is an AEDesc.
OSAGetProperty SCRIPTINGCOMPONENT, MODEFLAGS, SCRIPTID, VARIABLENAME
The OSAGetProperty function gets the value of a script property in
a specified script. VARIABLENAME is an AEDesc. Returns an AEDesc.
OSAGetAppTerminology SCRIPTINGCOMPONENT, MODEFLAGS, FILE, TERMINOLOGYID
OSAGetAppTerminology gets one or more scripting terminology
resources from the specified file. Returns an AEDesc.
OSAScriptingComponentName SCRIPTINGCOMPONENT
The OSAScriptingComponentName function returns a descriptor record
that you can coerce to a text descriptor type such as typeChar.
This can be useful if you want to display the name of the scripting
language in which the user should write a new script. Return
"undef" if an error was detected.
OSACompile SCRIPTINGCOMPONENT, SOURCEDATA, MODEFLAGS,
[PREVIOUSSCRIPTID]
You can pass a descriptor record containing source data suitable
for a specific scripting component (usually text) to the OSACompile
function to obtain a script ID for the equivalent compiled script
or script context. To compile the source data as a script context
for use with OSAExecuteEvent() or OSADoEvent(), you must set the
kOSAModeCompileIntoContext flag, and the source data should include
appropriate handlers. Return zero if no error was detected.
OSACopyID SCRIPTINGCOMPONENT, FROMID, [TOID]
The OSACopyID function replaces the script data identified by the
script ID in the TOID parameter with the script data identified by
the script ID in the FROMID parameter. Return "undef" if an error
was detected.
OSAGetSource SCRIPTINGCOMPONENT, SCRIPTID, [DESIREDTYPE]
The OSAGetSource function decompiles the script data identified by
the specified script ID and returns a descriptor record containing
the equivalent source data. Return "undef" if an error was
detected.
OSACoerceFromDesc SCRIPTINGCOMPONENT, SCRIPTDATA, MODEFLAGS
The OSACoerceFromDesc function coerces the descriptor record in the
SCRIPTDATA parameter to the equivalent script value and returns a
script ID for that value. Return "undef" if an error was detected.
OSACoerceToDesc SCRIPTINGCOMPONENT, SCRIPTID, DESIREDTYPE, MODEFLAGS
The OSACoerceToDesc function coerces the script value identified by
SCRIPTID to a descriptor record of the type specified by the
DESIREDTYPE parameter, if possible. Return "undef" if an error was
detected.
OSASetDefaultTarget SCRIPTINGCOMPONENT, TARGET
The OSASetDefaultTarget function establishes the default target
application for Apple event sending and the default application
from which the scripting component should obtain terminology
information. For example, AppleScript statements that refer to the
default application do not need to be enclosed in "tell/end tell"
statements. Return zero if no error was detected.
OSAStartRecording SCRIPTINGCOMPONENT, [COMPILEDSCRIPTTOMODIFYID]
The OSAStartRecording routine turns on Apple event recording.
Subsequent Apple events are recorded (that is, appended to any
existing statements) in the compiled script specified by the
COMPILEDSCRIPTTOMODIFYID parameter. Return "undef" if an error was
detected.
OSAStopRecording SCRIPTINGCOMPONENT, COMPILEDSCRIPTID
The OSAStopRecording function turns off recording. If the script is
not currently open in a script editor window, the
COMPILEDSCRIPTTOMODIFYID parameter supplied to OSAStartRecording()
is then augmented to contain the newly recorded statements. If the
script is currently open in a script editor window, the script data
that corresponds to the compiledScriptToModifyID parameter supplied
to OSAStartRecording() is updated continuously until the client
application calls OSAStopRecording. Return zero if no error was
detected.
OSALoadExecute SCRIPTINGCOMPONENT, SCRIPTDATA, CONTEXTID, MODEFLAGS
The OSALoadExecute function loads script data and executes the
resulting compiled script, using the script context identified by
the CONTEXTID parameter to maintain state information such as the
binding of variables. After successfully executing the script,
OSALoadExecute disposes of the compiled script and returns either
the script ID for the resulting script value or, if execution does
not result in a value, the constant kOSANullScript. Return "undef"
if an error was detected.
OSACompileExecute SCRIPTINGCOMPONENT, SOURCEDATA, CONTEXTID, MODEFLAGS
The OSACompileExecute function compiles source data and executes
the resulting compiled script, using the script context identified
by the CONTEXTID parameter to maintain state information such as
the binding of variables. After successfully executing the script,
OSACompileExecute disposes of the compiled script and returns
either the script ID for the resulting script value or, if
execution does not result in a value, the constant kOSANullScript.
Return "undef" if an error was detected.
OSADoScript SCRIPTINGCOMPONENT, SOURCEDATA, CONTEXTID, DESIREDTYPE,
MODEFLAGS
Calling the OSADoScript function is equivalent to calling
OSACompile() followed by OSAExecute() and OSADisplay(). After
compiling the source data, executing the compiled script using the
script context identified by the CONTEXTID parameter, and returning
the text equivalent of the resulting script value, OSADoScript
disposes of both the compiled script and the resulting script
value. Return "undef" if an error was detected.
OSASetCurrentDialect SCRIPTINGCOMPONENT, DIALECTCODE
Set the current dialect for a scripting component. Return zero if
no error was detected.
OSAGetCurrentDialect SCRIPTINGCOMPONENT
Get the dialect code for the dialect currently being used by a
scripting component. Returns the code for the current dialect of
the specified scripting component.
OSAAvailableDialects SCRIPTINGCOMPONENT
Obtain a descriptor list containing information about each of the
currently available dialects for a scripting component. Return
"undef" if an error was detected.
OSAGetDialectInfo SCRIPTINGCOMPONENT, DIALECTCODE, SELECTOR
After you obtain a list of dialect codes by calling
OSAAvailableDialectCodeList(), you can pass any of those codes to
OSAGetDialectInfo to get information about the corresponding
dialect. The descriptor type of the descriptor record returned by
OSAGetDialectInfo depends on the constant specified in the SELECTOR
parameter. Return "undef" if an error was detected.
OSAAvailableDialectCodeList SCRIPTINGCOMPONENT
Obtain a descriptor list containing dialect codes for each of a
scripting component's currently available dialects. Return "undef"
if an error was detected.
OSAExecuteEvent SCRIPTINGCOMPONENT, THEAPPLEEVENT, CONTEXTID, MODEFLAGS
The OSAExecuteEvent function attempts to use the script context
specified by the contextID parameter to handle the Apple event
specified by the THEAPPLEEVENT parameter. Return "undef" if an
error was detected.
OSADoEvent SCRIPTINGCOMPONENT, THEAPPLEEVENT, CONTEXTID, MODEFLAGS
The OSADoEvent function resembles both OSADoScript() and
OSAExecuteEvent(). However, unlike OSADoScript(), the script
OSADoEvent executes must be in the form of a script context, and
execution is initiated by an Apple event. Unlike OSAExecuteEvent(),
OSADoEvent returns a reply Apple event rather than the script ID of
the resulting script value. Return "undef" if an error was
detected.
OSAMakeContext SCRIPTINGCOMPONENT, CONTEXTNAME, [PARENTCONTEXT]
The OSAMakeContext function creates a new script context that you
may pass to OSAExecute() or OSAExecuteEvent(). The new script
context inherits the bindings of the script context specified in
the PARENTCONTEXT parameter. Return "undef" if an error was
detected.
OSAGetDefaultScriptingComponent GENERICSCRIPTINGCOMPONENT
The OSAGetDefaultScriptingComponent function returns the subtype
code for the default scripting component. This is the scripting
component that will be used by OSAStartRecording(), OSACompile(),
or OSACompileExecute() if no existing script ID is specified. From
the user's point of view, the default scripting component
corresponds to the scripting language selected in the Script Editor
application when the user first creates a new script. Return
"undef" if an error was detected.
OSASetDefaultScriptingComponent GENERICSCRIPTINGCOMPONENT,
SCRIPTINGSUBTYPE
The OSASetDefaultScriptingComponent function sets the default
scripting component for the specified instance of the generic
scripting component to the scripting component identified by the
SCRIPTINGSUBTYPE parameter. Return zero if no error was detected.
OSAGetScriptingComponent GENERICSCRIPTINGCOMPONENT, SCRIPTINGSUBTYPE
The OSAGetScriptingComponent function returns an instance of the
scripting component identified by the SCRIPTINGSUBTYPE parameter.
Each instance of the generic scripting component keeps track of a
single instance of each component subtype, so
OSAGetScriptingComponent always returns the same instance of a
specified scripting component that the generic scripting component
uses for standard scripting component routines. Return "undef" if
an error was detected.
OSAGetScriptingComponentFromStored GENERICSCRIPTINGCOMPONENT,
SCRIPTDATA
The OSAGetScriptingComponentFromStored function returns the subtype
code for the scripting component that created the script data
specified by the SCRIPTDATA parameter. Return "undef" if an error
was detected.
OSAGenericToRealID GENERICSCRIPTINGCOMPONENT, GENERICSCRIPTID
Given a GENERICSCRIPTID (that is, a script ID returned by a call to
a standard component routine via the generic scripting component),
the OSAGenericToRealID function returns the equivalent component-
specific script ID and the component instance that created that
script ID as an array.
OSARealToGenericID GENERICSCRIPTINGCOMPONENT, THESCRIPTID,
THEEXACTCOMPONENT
The OSARealToGenericID function performs the reverse of the task
performed by OSAGenericToRealID(). Given a component-specific
SCRIPTID and an exact scripting component instance (that is, the
component instance that created the component-specific script ID),
the OSARealToGenericID function returns the corresponding generic
script ID. Return "undef" if an error was detected.
AUTHOR
Written by Matthias Ulrich Neeracher <neeracher@mac.com>, documentation
by Bob Dalgleish <bob.dalgleish@sasknet.sk.ca>. Currently maintained
by Chris Nandor <pudge@pobox.com>.
perl v5.12.5 2013-08-25 OSA(3)
