Tcl® Glossary

- Tcl® arguments
  - aeclass
  - aeeventID
  - anAddress
  - coercionHandlerProc
  - data
  - eventHandlerProc
  - fromType
  - desiredType
  - index
  - keyIfAnyPtr
  - resultDesc
  - toType
  - theAEDescList
  - theAEKeyword
  - typeCode
  - theReplyAE
  - typeCodePtr
- Tcl® types
  - AEAddress
  - AEDesc
  - AEDescList
  - AERecord
  - AEGizmo
  - DescType
  - four-character code
  - TargetID

This page describes arguments and types used in Tcl® calls. For information on the associated ToolBox data types, see INSIDE MACINTOSH: Interapplication Communication: Glossary.

# Tcl® arguments

## `aeclass`

An `four-character code` attribute that identifies a group of related Apple events. The event class and the event ID identify the action an Apple event performs. See also `aeeventID`.

## `aeeventID`

An `four-character code` attribute that identifies a particular Apple event within a group of related Apple events. The event ID and the event class identify the action an Apple event performs. See also `aeclass`.

## `anAddress`

An `AEAddress`, an application name, an application creator code, or `TargetID`.

## `coercionHandlerProc`

The name of a Tcl proc that will handle the specified `AEDesc` coercion. The proc must have the following format:

>     proc coercionHandlerProc {typeCode data toType resultDesc} {
>     	# convert $data from $typeCode to $toType
>     	# and return in $resultDesc
>     }

Note! You must not dispose of `resultDesc`.

## `data`

Raw ASCII or binary data.

Tcl's "everything is a string" mentality presents complications for conversion to and from the heavily typed world of AppleEvents. After experimenting with a number of different (and unsatisfactory) attempts at automagic conversion, I have settled on the following limited conversions. If you desire anything more elaborate, you can always apply `[binary format]` and `[binary scan]` to achieve the desired effect.

### input

As an input parameter, `data` is ASCII unless it was explicitly created as `[binary]`. As a result, numeric values of `data` will be sent as a string of ASCII characters. For example, `"24.5"` will be sent as `0x32342E35`. If you desire to send the number itself, use `[binary format]`.

Binary data is sent exactly as is. ASCII data undergoes UTF-to-External encoding conversion.

### output

The data returned depends on the final type of the `AEDesc`:

`'TEXT'`
  the data undergoes External-to-UTF encoding conversion and is returned as a Tcl string object.
`'bool'`
  the data is returned as a Tcl boolean object.
`'shor'`
  the data is returned as a Tcl integer object.
`'long'`
  the data is returned as a Tcl long integer object.
`'sing'`, `'doub'`
  the data is returned as a Tcl double precision float object.
`'list'`
  the data from `AEDescList` items are recursively extracted and concatenated in a Tcl list.
all others
  the data is returned as raw binary, regardless of type. If the original type is `'reco'`, expect the return value to be particularly meaningless.

## `eventHandlerProc`

The name of a Tcl `proc` that will handle the specified AppleEvent. The `proc` must have the following format:

>     proc eventHandlerProc {theAppleEvent theReplyAE}
>     	# Extract any pertinent parameters from $theAppleEvent,
>     	# take appropriate action, and return appropriate results
>     	# in $theReplyAE
>     }

In addition to manually adding parameters to `theReplyAE`, the return result of the `proc` will be added as its '`----`' direct object. If a direct object has already been added, the `proc` result is ignored. If no direct object parameter is desired, pass `return` with no argument to avoid the implicit return value.

If `proc` throws an error, the error message and code will be entered in the `'errs'` and `'errn'` parameters of `theReplyAE`. The `'errs'` parameter is taken from the Tcl result as text.

The `'errn'` parameter is set from an integer value extracted from

1. the Tcl `errorCode`, or
2. the second element of a three-element `errorCode` list, consisting of `{{error type} {error number} {error message}}`, or
3. the Tcl result.

If no integer error code is found, `'errn'` is omitted.

Note! You must not dispose of `theReplyAE`.

## `fromType`

The `DescType` to coerce the `AEDesc` or `data` from.

## `desiredType`

An optional parameter that holds the `DescType` to coerce the `AEDesc`. Omit or pass `'****'` for no coercion.

## `index`

Numerical index of item in an `AEDescList` or `AERecord`.

In the ToolBox, `AEDescList`s are `1`-based, but Tcl® treats them as `0`-based for consistency with Tcl lists. When putting into a list, if `index` is `-1` it specifies the end of the list. Negative values of `index` are an error when getting from a list.

## `keyIfAnyPtr`

An optional parameter that holds the name of a variable which will be set to the keyword of the specified descriptor record if the `AEDescList` it was obtained from is an `AERecord` or `'****'` otherwise.

## `resultDesc`

The `AEDesc` to hold the coerced `data` from a `coercionHandlerProc`. This `AEDesc` will already exist when your coercion handler `proc` is called and must not be disposed of by your code.

## `toType`

The `DescType` to coerce the `AEDesc` or `data` to.

## `theAEDescList`

An `AEDescList` or `AERecord`.

## `theAEKeyword`

The `four-character code` keyword of an item in an `AERecord`.

## `typeCode`

Original `DescType` associated with `data`.

## `theReplyAE`

The `AEDesc` for the reply AppleEvent from an `eventHandlerProc`. This `AEDesc` will already exist when your AppleEvent handler `proc` is called and must not be disposed of by your code.

## `typeCodePtr`

An optional parameter that holds the name of a variable which will be set to the final `typeCode` of the `AEDesc` in question.

# Tcl® types

## `AEAddress`

An AEDesc that describes another process. An AEAddress can be one of:

A Macintosh process serial number
  `psn (Ç0123456789ABCDEFÈ)`
A remote process
  `aprl(Òeppc://steveo.apple.com/AlphaXÓ)`
A unix process id
  `kpid(Ç000004c1È)`
  Only available on Mac OS X
A bundle id
  `bund(Ònet.sourceforge.alphatclÓ)`
  Only available on Panther and above

## `AEDesc`

A hash key tied to an AppleEvent descriptor record.

If your procedure received the `AEDesc` as an argument, it must not dispose of it.

## `AEDescList`

An `AEDesc` hash key tied to an AppleEvent descriptor list.

## `AERecord`

An `AEDescList` hash key tied to an AppleEvent keyed record.

## `AEGizmo`

An `AEGizmo` is a string in the syntax described by Jens Alfke in the AEGizmos documentation. This is the syntax that Alpha has always(?) used for AppleEvents and is the same that is returned by the Capture AE control panel.

## `DescType`

`four-character code` defining the data type of an `AEDesc`.

## `four-character code`

Will be truncated or padded with spaces to exactly four characters.

## `TargetID`

A hash key tied to an AppleEvent target. This target may be on the same machine or located remotely, either on the local AppleTalk network or via AppleTalk-over-IP. The hash key is a text representation of the application name and location.

Copyright © 1999Ð2004 Jonathan E. Guyer
All rights reserved.

Last modified Saturday, February 28, 2004 12:47:45 PM