AppleIIWorks Envoy

A. AppleIIWorks Envoy - What is It?

AppleIIWorks Envoy is a 'faceless' application for Mac OS X (10.4.x Tiger through 10.8.x Mountain Lion) with a two-fold purpose.

First, it provides for Mac Finder recognition of Apple II AppleWorks Files, presenting both a custom Mac Finder icon as well as a custom 'Kind' description.

Second, the application implements a Spotlight metadata importer for AppleWorks Word Processor (ProDOS type 'AWP/$1A') files that not only indexes the text content of these files, but also sets (2) ProDOS-related custom metadata attributes that display in the 'More Info' portion of the 'Get Info' window.

A brief discussion of each of these features follows.

I. Mac Finder Recognition of AppleWorks Files

With AppleIIWorks Envoy, AppleWorks (Apple II) Word Processor, Spreadsheet, and Database files that have had their Mac OSTypes (File Type) set in the Apple-prescribed 'proper' manner for Apple II-based ProDOS attributes ('p' + 1-byte ProDOS File Type + 2-byte ProDOS Aux Type) will show a custom Mac Finder icon and display a custom Finder 'Kind' in the 'Get Info' window.

For example, the Mac Finder icons for AppleWorks files are as shown here in this window:

Finder Icons for AppleWorks Files
Finder Get Info for AWP Files

And, in the Mac Finder 'Get Info' window and in folder listings, AppleWorks files show the Mac Finder 'Kind' as:

For AWP files: 'Kind' = AppleWorks Word Processor File (Apple II)

For ASP files: 'Kind' = AppleWorks Spreadsheet File (Apple II)

For ADB files: 'Kind' = AppleWorks Database File (Apple II)


AppleIIWorks Envoy accomplishes this by registering _all_ 98,304 (32,768 x 3) possible AppleWorks File Type/Aux Type combinations (upper/lower case filename stuff) with OS X Launch Services.

Note that while there are only (3) ProDOS File Types that pertain to AppleWorks files (e.g. $1A (AWP) / $19 (ADB) / $1B (ASP) ) , there are thousands of ProDOS Aux Types used to control the upper/lower case filename display within AppleWorks. For completeness of coverage, AppleIIWorks Envoy registers every possible combination of File Type / Aux Type with Launch Services.

The Apple-prescribed method mentioned above for setting the proper Mac OSType (File Type) for the ProDOS attributes is detailed in the following:

- Apple Technical Note PT515

- Programmer's Reference for [GS/OS] System 6.0 (page 335-336)

- AppleShare Programmer's Guide for the Apple II (page 141)


This method is presently implemented by several programs. For example:

1. GS/OS - Files written to HFS Volumes by the Apple IIGS Finder;

2. AppleShare - Files written to HFS/HFS+ Volumes on a Mac;

3. ShrinkFitX - Files written to HFS/HFS+ Volumes by Kelvin Sherlock's un-shrinking utility on the Mac (be sure to set 'Finder Info' in Preferences);

4. Nulib2 - Files written to HFS/HFS+ Volumes by Andy McFadden's un-shrinking command line utility on the Mac;

5. Deja IIx - Files written to HFS/HFS+ Volumes by Mark Munz's AppleWorks emulator application on the Mac;

6. ADFS - Files extracted from Apple II disk images and written to HFS/HFS+ Volumes by David M. Cotter's Apple DOS File System (ADFS) Utility on the Mac;

7. Bernie ][ the Rescue - Files written to HFS/HFS+ Volumes by the 'Total Integration' feature of this Mac OS 'Classic' Apple IIGS emulator;

8. and quite a few others ...


In addition, when the icon of one of these AppleWorks files is double-clicked, Mark Munz's 'Deja IIx' AppleWorks 5.1 emulator, (only if present in your 'Applications' folder) will open and be the frontmost application, although obviously, the AppleWorks file will still need to be manually added to the Deja IIx emulated AppleWorks desktop.

Download Deja IIx 2.0 beta (109) for Mac OS X {external link to Mark Munz's Unmarked Software}

Download AppleWorks 5.1 'Install/Extras' Disk for the 256K RAM Apple II {external link to David Finnigan's MacGUI.com}

Download AppleWorks 5.1 'Program' Disk for the 256K RAM Apple II {external link to David Finnigan's MacGUI.com}



II. Spotlight Metadata Importer

AppleIIWorks Envoy also has an integral Spotlight Metadata Importer for AppleWorks Word Processor files. (Database and Spreadsheet file importers are planned for a future version).

AppleIIWorks Envoy accomplishes this by automatically assigning a unique Uniform Type Identifier (UTI) to AppleWorks Word Processor files that have the 'proper' Mac OSType (File Type).

The UTI is what the AppleIIWorks Envoy Spotlight importer uses to determine which files to import.

The importer handles the extraction of the AppleWorks word processor data and converts it to a 'text' representation. The conversion part of this process is based on the code from Andy (CiderPress) McFadden's 'convertawp2txt' command line utility, which Andy has graciously permitted me to use in this application.

As an example, say we use Spotlight to find the phrase 'ultramacros hackers'.

Here is what is returned, as shown:

SpotLight Window


Even better, if you use a Spotlight utility such as 'SpotInside', you get the text content displayed, as shown here:

SpotInside Window

Finder Get Info for AWP Files


A final 'feature' added by this Spotlight importer is that it adds (2) custom metadata attributes to AppleWorks Word Processor files. These attributes are not only searchable by Spotlight, but they also are displayed in the 'More Info' section of the Finder 'Get Info' section, as show here:

Notice the following displayed custom metadata attributes in the 'More Info':

 HFS Type Code (hex): $70 $1A $F8 $FF

ProDOS File/Aux Type: $1A (AWP) $F8FF

This information is useful for any type of ProDOS-based file, particularly if Apple II emulator technology evolves to support not only ProDOS disk images, but emulated ProDOS folders within the normal Mac HFS/HFS+ file systems. {BTW, a form of folder emulation is currently implemented in Mark Munz's DejaIIx}.




B. AppleIIWorks Envoy - How to Install?

(NOTE: If you previously installed the 'beta' version of AppleIIWorks Envoy, first 'Un-Install' the beta version according to the instructions in 'C' below).

First, you need to drag the application 'AppleIIWorks Envoy' to your 'Applications' folder. This should notify Launch Services of the AppleWorks file types, 'kind' descriptions, and custom icons.

Next, you need to launch (double click) the 'AppleIIWorks Envoy' application in order to register the Spotlight importer part of the app. You should only have to do this once.

Then restart your computer, and copy the sample AppleWorks files (from the disk image included in this download) to your hard drive. The Spotlight importer should begin indexing them, and you will be able to search on their text content.

Note that any new AppleWorks files copied to your hard drive will now be recognized, provided the ProDOS attributes have been preserved in the Mac OS Type Code. (The Creator Code is not relevant for AppleIIWorks Envoy). Any AppleWorks files that previously existed on your hard drive may need to first be indexed by Spotlight, although the Finder will display the correct icons and 'kind' regardless of whether they are indexed.

There are several common methods of forcing Spotlight to re-index files. Just ask if you are not familiar with that procedure.


C. AppleIIWorks Envoy - How to Un-Install?

To remove 'AppleIIWorks Envoy', merely drag it to the Trash, restart your computer, and then empty the trash.

Launch Services will no longer recognize the AppleWorks file types, and the Spotlight importer will be removed. That's all.


D. Questions and Suggestions

If you have any questions about any of this, or suggestions for improvements, please post them in comp.sys.apple2 with the subject 'AppleIIWorks Envoy'. This will allow for idea exchange and improvements.


E. Revision History

Version 1.0.1 - September 1, 2013
Public Release [32-bit/64-bit PPC/Intel Universal Binary]
- for OS X 10.4.x / 10.5.x / 10.6.x / 10.7.x / 10.8.x

Changes from prior version:
- compiled 32-bit/64-bit Universal for Tiger through Mountain Lion
(Lion and Mountain Lion require 64-bit Spotlight plugins)

- replaced NSTask call of discrete command 'convertawp2text' with conversion code integral to importer
(Snow Leopard and up 'Sandbox' the Spotlight plugin and thus NSTask would fail)


Version 1.0.0 (beta) - March 17, 2013
Initial beta release [32-bit PPC/Intel Universal Binary]
- for OS X 10.4.x / 10.5.x


F. Future Additions

1. Spotlight metadata importer for AppleWorks Database Files (ADB)
2. Spotlight metadata importer for AppleWorks Spreadsheet Files (ASP)
3. Mac Finder recognition of other Apple II file types
4. QuickLook plugin for AppleWorks Word Processor Files (AWP) {not available for Tiger}


G. Credits

First, my sincere thanks goes out to Steven Nelson for his patience during the beta testing phase of this project.

Steven's testing revealed both the 'Sandbox' and the '32-bit vs. 64-bit' issues that affected the original beta release of the project, and confirmed that this release version would indeed work properly under OS X 10.8.x Mountain Lion.


I also must mention Mark 'DejaIIx' Munz, who at the early conceptual stage of this project offered both his constructive criticisms and his suggestions.

Mark had expressed concerns about populating the OS X Launch Services database with the 98,304 unique file types required to recognize all combinations of AppleWorks file type codes.

As you may remember, Mark was a programmer for Beagle Bros and wrote quite a few 'TimeOut' applications for AppleWorks. Coming from the Apple II, where small, efficient, tightly written assembler code was his specialty, he was concerned about whether adding such a large number of file types to Launch Services would cause a drop in Finder performance.

I am pleased to report, though, after many months of testing AppleIIWorks Envoy on even relatively slow PPC Macs, I have noticed no performance degradation. I suspect that in these days of computers with RAM measured in Gigabytes, photo, video and music files spanning Megabytes, and hard drives storing Terabytes, a mere 100,000 4-byte file types is a trivial thing for a modern Mac to handle.


H. Download

This download consists of a zipped '.dmg' disk image.

The '.dmg' will contain not only the app 'AppleIIWorks Envoy' (Universal Binary), but also a folder full of Apple II AppleWorks files, which are all from a sampler edition of the Resource-Central disk magazine 'TimeOut Central'.

It will also contain a related AppleScript droplet 'Show File Info' that will display the Mac Creator and File Type Codes (both in text and in hex) and Uniform Type Indentifiers (UTI) for any type of file dropped on it, even those unrelated to AppleWorks or the Apple II.


Download AppleIIWorks Envoy




This site was last updated: April 14, 2014

The Contents of this site are Copyright © 2014 Hugh Hood.