TweetFollow Us on Twitter

Format Driver
Volume Number:4
Issue Number:1
Column Tag:The Visiting Developer

Format Drivers Bring Freedom
of Revison

By David Dunham, James Hopper, Goleta, CA

Introduction

Data interchange is a real problem. Everyone likes to save information in their own format, and no one wants to deal with anyone else’s format (especially not to write it!). Programs like the original version of Acta, David’s desk accessory outline processor, support only limited file format interchange, usually via a separate translator program. Such translation programs are very inconvenient, but there are reasons for writing them. First, the extra code required to read additional file formats can significantly enlarge a program while adding support for formats which most users never need. It’s better to separate this code from the more commonly-used parts of the program. Also, the intermediate file is necessary because many programs don’t use the public clipboard (desk scrap) for formatted text. Second, many of these formats are considered proprietary and are not generally available, for example Microsoft Word 1.05. Finally, there are a lot of file formats out there -- most of us are simply too lazy to cover all of them.

Many people work with a variety of editors, word processors, and desk accessories, and need the ability to exchange files between them. Separate translation programs such as the one used with WriteNow are simply too inconvenient. Macintosh users have grown accustomed to (and deserve) a higher degree of integration between programs. One way this can be done is to ‘teach’ the program what the data must look like by having the program look-up the format externally to itself. In this way, the program does not have to be revised to read or write a new format whenever someone releases a hot new product. In this article, we will discuss an example of such a technique used in Acta 2.0, that can be applied to other developer’s software projects to ease the burden of being compatible. [It is hoped this article will spur someone to write a similar article on how Pagemaker compatibility can be achieved by new word processors without having to wait for Aldus to release a new Pagemaker version. Wouldn’t it be neat if the word processor or graphics developer could make his product Pagemaker compatible without Aldus having to do anything? -Ed]

Acta 2.0 handles additional data formats with format drivers, files which, like printer drivers, reside in the system folder. Because they’re separate from the main program, users can install only the formats required by dragging these driver files to the system folder. As new word processors come out, the new file formats can be supported with new format drivers, rather than a new version of Acta. Given the file format documentation for the new word processing program, drivers to support new formats can be produced by third party programmers such as Jim.

David will first explain format drivers using C as the target language. Jim will then discuss a simple input format driver in Pascal, focusing on the glue required to link functions written in C to units written in Pascal. Although this article deals with format drivers as implemented in Acta, the concept of format drivers can be adopted in most programs.

Additional technical information on Acta can be found in a short document describing the format of Acta files, available from online services such as Delphi or CompuServe, or from Symmetry Corp. For convenience, it is included at the end of this article. This information would be useful if you’re implementing your own Acta format driver, but you won’t need it to read this article.

Input Drivers

Acta supports two kinds of format drivers: input and output. A file can contain resources for both, but we’ll start by looking at input drivers. An input driver’s job is to read a file, parse the data, and pass it to Acta as topics (Acta’s smallest data object). Acta handles everything else, which keeps down the overhead in each format driver. We’ll use the input driver a_TEXT as an example format driver. This example was written in C and compiled using MPW C. This driver reads text files, splitting the text into topics at return characters.

The driver a_TEXT is composed of a variety of resources stored in the resource fork of the file a_TEXT. The file type for a format driver is ‘ACTF,’ which is how Acta recognizes it as a format driver. The file creator ‘Atxt’ associates a unique icon with the driver file in the Finder using the usual additional (bundle) resources. We discuss other resources in the following paragraphs.

ACTf -- The code for the driver is stored as a resource of type ACTf. It’s actually a standard code resource which Acta loads using GetResource.

ICN# -- An input driver file must contain an ICN# 64 resource which, along with the file name, identifies a particular format driver. The user selects an input driver from a scrolling icon list (see Appendix) as part of Acta’s Open dialog (see illustration below). To avoid confusion with application names, format driver files start with ‘a_’ by convention; however, this prefix is not displayed in the scrolling icon list.

FILT -- If a resource FILT 64 is present, it’s assumed to be a code resource containing a file filter function, defined as in SFGetFile:

pascal short fileFilter(pb) ParmBlkPtr pb;

The driver author provides this filter so Acta can open multiple file types using the format driver.

TYPE -- If there is no FILT 64, Acta determines which files to open by examining the input driver’s resource TYPE 64, which is four ASCII characters and specifies a single file type to be converted.

Once the user decides to open a file, Acta calls the driver, assuming it’s a C routine defined as is read_text() in Listing 1.


{1}
/*
Read TEXT documents into Acta
Written by David Dunham
©1987 Maitreya Design -- code may be freely used 
in Acta format drivers 
*/

typedef int word;/* Synonyms for VAX-hackers */
typedef unsigned charbyte;

#define TAB ‘\t’
#define CR‘\r’

#define NIL (0L)
#define TRUE(-1)
#define FALSE    0

#define TEXTtype 1
#define PICTtype 2

struct BLOCK_ATT { /* Attribute portion of a topic */
 word bType;/* TEXTtype, PICTtype,   */
 word bAttributes; /* 0 */
 word bFont;
 word bStyle;
 word bSize;
 byte bColor;    /*Triangle color: index to COL#               
 resource, 0 = black */
 byte filler;    /* 0 */
 byte firstLine; /* Show first line only? 0xFF or 0 */
 byte expanded;  /* Subtopics visible? 0xFF or 0 */
 word hidden;    /* Is block hidden (by Collapse)? count       
 of hide depth */
};
typedef struct BLOCK_ATT  BLOCK_ATT;

/*
READ_TEXT -- Read generic TEXT file to Acta outline
 infil  : refNum of input file
 resfil : refNum of input file’s resource fork
 att    : default topic attributes
 add_topic: pointer to routine to call
*/
OSErr read_text(infil,resfil,att,add_topic)
word infil, resfil; BLOCK_ATT *att; ProcPtr add_topic; {
 register char   **text;  /* Handle for  text */
 register OSErr  error;
 long   count;   /* Used in FS calls */
 register word   level;   /* Topic’s level */
 word i_count, last_count, spaces;
 word last_level;/* Level of previous topic */
 word space_indent;/* No. of spaces = to a tab */
 char c;
 long size; /* Length of text */
 Handle h;
 word oldResFile;

 oldResFile = CurResFile(); /* Previous top resource file */
 UseResFile(resfil); /* Just look in document */
 h = GetIndResource(‘EFNT’,1);
 /* MDS Edit/QUED/miniWRITER font */
 if (h != NIL) { /* There is such a resource */
 att->bSize = **(word **)h;
 GetFNum(*(char **)h + 2,&att->bFont);
 }
 UseResFile(oldResFile);  /* Restore search order */
 level = -1;/* We’ve never parsed a topic */
 last_level = 0;
 space_indent = 5; /* SHOULD be rsrc; 5 for MORE 1.0 */
 last_count = i_count = spaces = 0;
 text = NIL;
 att->bType = TEXTtype; /* Everything is text! */
 while (TRUE) {  /* Keep going until EOF */
 /* Will this die with empty file? */
 count = 1L;/* Read a single character */
 error = FSRead(infil,&count,&c);
 if (error) {    /* Probably hit EOF before RETURN */
 if (error == eofErr) return(noErr); 
 /* Finished with the file */
 return(error);  /* Uh-oh  */
 }
 if (c == TAB) {
 i_count++; /* Increment indent count */
 spaces = 0;/* Start count over */
 } else if (c == ‘ ‘) {
 spaces++;
 if (spaces == space_indent) {/* A pseudo-tab */
 i_count++; /* Increment indent count */
 spaces = 0;/* Start count over */
 }
 } else { /* Not space or tab */
 if (level == -1)/* Very first topic */
 level = 1;
   else
 level = level + i_count - last_count;
 if (level < 1)
 level = 1; /* Minimum indent */
 if (level > last_level + 1)
 level = last_level + 1;   /*go one level deeper */
 if (level == 1) { /* Left-margin topic? */
 att->expanded = TRUE;
 att->hidden = 0;
     } else {    /* Subtopics aren’t expanded */
 att->expanded = FALSE;
 att->hidden = level - 2; 
 /* # of collapsed levels above */
 }
 text = NIL;/* No text so far */
 /* Read until end of line or end of file */
 while (c != CR && error == noErr) {
 if (text == NIL) {/* First character? */
 text = NewHandle(1L);
 **text = c;/* Copy it in */
 } else
 PtrAndHand(&c,text,1L);  /* Add to the end */
 count = 1L;/* Read a single character */
 error = FSRead(infil,&count,&c);
 }
 if (error != noErr && error != eofErr)
 return(error);  /* Uh-oh  */
 if (text == NIL) {/* Empty topic */
 (*add_topic)(NIL,0L,level,att,NIL);
   } else {
 size = GetHandleSize(text);
 HLock(text);    /* Keep dereference valid */
 (*add_topic)(*text,size,level,att,NIL);
 DisposHandle(text); /* Free the memory */
 text = NIL;/* Mark it as empty */
 }
 if (error == eofErr) {
 return(noErr);  /* Finished with the file */
 }
 last_count = i_count;  /* input file’s indent */
 i_count = spaces = 0;
 last_level = level; /* Remember topic’s level */
 } /* end if */
 } /* end while */
}

«listing 1»

The actual code in our example is straightforward. First, it looks in the resource fork for the EFNT resource (where MDS Edit, QUED, and miniWRITER save a text file’s font and size). Then it reads the data fork a character at a time, appending them to the end of a block of memory until it reaches either the end of the file or a return character. When this happens, it calls add_topic, a routine in one of Acta’s code resources. If there are any errors, it just returns the error to Acta, which takes care of informing the user. A driver can display its own error messages, in which case it returns -2048.

Add_topic inserts the data into Acta’s family tree structure. It’s declared as:

{2}
/*
ADD_TOPIC -- Create a new topic and link it in
 data   : topic data
 len    : length of data
 level  : level of topic (1 = left margin)
 attributes : topic’s attributes
 styleHandle   : RESERVED
*/
void add_topic(data,length,level,attributes,styleHandle)
Ptr data; long length; word level; BLOCK *attributes; Handle styleHandle;

The code is compiled into the resource ACTf 64:

{3}
c a_TEXT.c
link -rt ACTf=64 -sn Main=a_TEXT -c Atxt -t ACTF 
 a_TEXT.c.o -o d20:MPW:a_TEXT 
 “{Libraries}”Interface.o 
 “{CLibraries}”CInterface.o

Listing 2 summarizes the resources which make up an input driver, in REZ format:

{4}
resource ‘BNDL’ (128) {
 ‘Atxt’,
 0,
 { /* array TypeArray: 2 elements */
 ‘ICN#’,
 { /* array IDArray: 1 elements */
 0, 128
 };
 ‘FREF’,
 { /* array IDArray: 1 elements */
 0, 128
 }
 }
};

resource ‘FREF’ (128, “a_TEXT”) {
 ‘ACTF’,
 0,
 “”
};

data ‘Atxt’ (0, purgeable) {
 “©1987 Maitreya Design 23 January 1987”
};

data ‘TYPE’ (64, purgeable) {
 ‘TEXT’
};

and the ICN#

«listing 2 -- Rez input»

Output Drivers

An output driver is responsible for taking the data from an Acta topic and writing it to a file. Again, Acta handles most of the overhead, but the process is slightly more complicated, because most word processor formats involve tables and pointers. Acta calls the output driver before passing any topic data, once for each topic, and again after all the data. The driver generally builds any tables during the first and last call. For example, a word processor format may begin with a list of paragraphs (conveniently written during the first call) and end with a pointer to free space (best written after all the topics have been output).

The example output driver is a_RTF, which converts an outline to Rich Text Format, Microsoft’s interchange format. It creates a file which is as true as possible to the screen appearance of the Acta outline. (The RTF specification is available from Microsoft. It’s beyond the scope of this article to explain in detail, but it’s a format for representing formatting information using only the standard 7-bit printing ASCII characters. Backslashes precede formatting words, and braces group items. This format is also used for Microsoft’s MSDOS word processor.)

ACTf -- The actual code for the output driver is in the ACTf 0 resource and is loaded by Acta using GetResource.

ICN# -- An output driver file must contain an ICN# 0 resource which, along with the file name, identifies the format driver to the user. The user selects an output driver from a scrolling icon list (see Appendix) as part of Acta’s Save as dialog (see illustration below). When the user clicks on this icon, Acta highlights the ruler and label buttons depending on the RULR 0 resource.

RULR -- This is a word, in which the following bits have meaning:

0x8000 format has rulers

0x4000 format doesn’t use labels

As usual, don’t set unused bits.

TYPE and CREA -- The resources TYPE 0 and CREA 0 are OSTypes, 4 ASCII characters Acta uses to set the output file’s type and creator.

Acta passes a pointer to a parameter block which indicates the topic’s level, data, attributes, label, and other information; this is defined in Listing 3.

When the example driver gets the -1 message (indicating the initial call), it writes the RTF header, including the name of every installed font. When it gets the 0 message (indicating a topic’s data), it outputs the topic’s style, ruler, label, and data. If it encounters an error, it must return the error (or -2048 if it doesn’t want Acta to put up an error dialog). Since a code resource can’t have globals, it sets already_error in the parameter block. A_RTF ignores the +1 message, which follows all the 0 messages.


{5}
/*
Outputs Acta outline as Rich Text Format (Word 3.x) document
Written by David Dunham
©1987 Maitreya Design -- code may be freely used 
in Acta format drivers 
*/

typedef int word;/* Synonyms for VAX-hackers */
typedef unsigned charbyte;

#define TAB ‘\t’
#define CR‘\r’

#define NIL (0L)
#define TRUE(-1)
#define FALSE    0

/* Label types */
#define NONE10
#define DECIMAL  11
#define ROMAN    12
#define BULLETS  14

/* Topic types */
#define TEXTtype 1
#define PICTtype 2

struct BLOCK_ATT { /* Attribute portion of a topic */
 word bType;/* TEXTtype, PICTtype,   */
 word bAttributes; /* 0 */
 word bFont;
 word bStyle;
 word bSize;
 byte bColor;    /* Triangle color: index to COL#              
 resource, 0 = black */
 byte filler;    /* 0 */
 byte firstLine; /* Show first line only? 0xFF or 0 */
 byte expanded;  /* Subtopics visible? 0xFF or 0 */
 word hidden;    /* Is block hidden (by Collapse)? count       
 of hide depth */
};
typedef struct BLOCK_ATT  BLOCK_ATT;

struct OUT_PARMS {
 word   fRef;    /* Data fork refNum */
 word   rRef;    /* Resource fork refNum */
 word   message;
 word   level;
 word   n;/* Topic’s absolute number */
 char   *data;
 long   len;/* Length of data */
 BLOCK_ATT*att;
 THPrintprint_rec;
 word   already_error;
 char   *label;
 word   labelType;
 word   *raw_label;
 word   rulers;
 word   error_reporting;  /* not used */
 Handle reserved;/* Currently NIL */
 word   last_level;
 word   private;
};
typedef struct OUT_PARMS  *P_PTR;

/* Function prototypes */
void    file_error();
void    warp();
void    w_byte();
void    w_str();
OSErr   write_RTF();

/*
WRITE_RTF -- Write Rich Text Format document
*/
OSErr write_RTF(p) register P_PTR p; {
 char   *s;
 long   count;
 OSErr  error;
 Handle handle;
 register word i;
 word   id, last_space, rsrc_fonts;
 Str255 name, string;
 WindowPtrfront;

 switch (p->message) {
   case -1:
 w_str(p,”\P{\\rtf\\mac”);
 /* Output font table (every installed font) */
 w_str(p,”\P{\\fonttbl”);
 rsrc_fonts = CountResources(‘FONT’);
 for (i = 1; i <= rsrc_fonts; i++) {
 SetResLoad(FALSE);/* Don’t actually load fonts! */
 handle = GetIndResource(‘FONT’,i);
 GetResInfo(handle,&id,&count,&name);
 SetResLoad(TRUE); /* Back to normal */
 if (name.length != 0) {
 w_str(p,”\P\\f”);
 NumToString((long)id >> 7,&string);
 w_str(p,&string);
 w_byte(p,’ ‘);
 w_str(p,&name);
 w_byte(p,’;’);
 }
 }
 w_str(p,”\P}\r”);
 break;
   case 0:
 w_str(p,”\P{\\sl0\\f”);
 NumToString((long)p->att->bFont,&string);
 w_str(p,&string);
 w_str(p,”\P\\fs”);
 NumToString((long)p->att->bSize << 1,&string);
 w_str(p,&string);
 if (p->att->bStyle & bold) {
 w_str(p,”\P\\b”);
 }
 if (p->att->bStyle & italic) {
 w_str(p,”\P\\i”);
 }
 if (p->att->bStyle & underline) {
 w_str(p,”\P\\ulw”);
 }
 if (p->att->bStyle & outline) {
 w_str(p,”\P\\outl”);
 }
 /* Output ruler stuff */
 if (p->level > 1 && p->labelType == DECIMAL)
 i = 48;
   else
 i = 32;
 if (p->labelType == BULLETS) i = 16;
 if (p->labelType == NONE) i = 0;
 /* Output first indent and left indent in twips (1/20 point) */
 w_str(p,”\P\\li”);
 NumToString((long)(p->level * 16 + i) * 20,&string);
 w_str(p,&string);
 w_str(p,”\P\\fi”);
 NumToString((long)i * -20,&string);
 w_str(p,&string);
 w_byte(p,’ ‘);  /* Be sure not to run into text */
 /* Output label */
 if ((p->label)[0] != 0) {
 for (i = 1; i <= p->label[0]; i++)
 w_byte(p,p->label[i]);
 }
 if (p->att->bType == PICTtype) {
 w_str(p,”\P{\\pict\\macpict\\bin”);
 NumToString((long)p->len,&string);
 w_str(p,&string);
 w_byte(p,’ ‘);
 count = p->len;
 error = FSWrite(p->fRef,&count,p->data);
 w_byte(p,’}’);
   } else { /* Not a PICT */
 warp(p,p->len,p->data);
 }
 w_str(p,”\P\\par}\r”);
 break;
   case 1:
 w_str(p,”\P}\r”);
 break;
 }
 return(p->already_error);
}

/*
FILE_ERROR - Display the appropriate message for a file error
*/
void file_error(error,p) register OSErr error; P_PTR p; {

 if (p->already_error != noErr) return;/* Only once */
 p->already_error = error;/* Indicate error */
}

/*
WARP -- Escape {,\,},CR,TAB
*/
void warp(p,len,s) P_PTR p; long len; register char *s; {
 long   count;
 register word i;
 register char c;
 
 if (p->already_error) return;/* Already have error */
 for (i = 0; i < len; i++) {
 c = *s++;
 switch (c) {
   case ‘{‘:
   case ‘}’:
   case ‘\\’:
 w_byte(p,’\\’); w_byte(p,c);
 break;
   case CR:
 w_str(p,”\P\\line “);
 break;
   case TAB:
 w_str(p,”\P\\tab “);
 break;
   default:
 w_byte(p,c);
 }
 }
}

/*
W_BYTE
*/
void w_byte(p,b) P_PTR p; unsigned char b; {
 long   count;
 register OSErr  error;
 
 if (p->already_error) return;/* Already have error */
 count = sizeof(char);
 error = FSWrite(p->fRef,&count,&b);
 if (error) {
 file_error(error,p);
 return;
 }
}

/*
W_STR -- Write a Pascal string
*/
void w_str(p,s) P_PTR p; char s[]; {
 long   count;
 register OSErr  error;

 if (p->already_error) return;/* Already have error */
 count = s[0];
 error = FSWrite(p->fRef,&count,&s[1]);
 if (error) {
 file_error(error,p);
 return;
 }
}

«listing 3»

Listing 4 summarizes the additional resources which make up an output driver.

{6}
resource ‘BNDL’ (128) {
 ‘Artf’,
 0,
 { /* array TypeArray: 2 elements */
 /* [1] */
 ‘ICN#’,
 { /* array IDArray: 1 elements */
 /* [1] */
 0, 128
 };
 /* [2] */
 ‘FREF’,
 { /* array IDArray: 1 elements */
 /* [1] */
 0, 128
 }
 }
};

resource ‘FREF’ (128, “a_TEXT”) {
 ‘ACTF’,
 0,
 “”
};

data ‘TYPE’ (0, purgeable) {
 ‘TEXT’
};

data ‘CREA’ (0, purgeable) {
 ‘MSWD’
};

data ‘RULR’ (0, purgeable) {
 $”0000"
};

data ‘Artf’ (0, purgeable) {/* Signature */
 “©1987 Maitreya Design 11 March 1987”
};

and the ICN#s

«listing 4 -- Rez input»

Doing it with Pascal

It’s a little known fact that Acta makes a superior Scrapbook. The example in this section is a relatively simple input format driver (in Lightspeed Pascal [LSP]) which reads a scrapbook file into an Acta outline, converting each text block and picture in the scrapbook to a separate topic. With this driver, those of you with a lot invested in scrapbooks can painlessly convert to Acta.

Unfortunately (for Pascal programmers) Acta assumes its format drivers are C functions. This is because Acta is written in C, and because David takes a perverse pleasure in making Pascal programmers read C declarations. (The authors of Inside Macintosh no doubt have a similar feeling.) But some Pascal compilers won’t generate code that can call or be called by code written in C. This section will discuss a relatively general method of coercing a standard Pascal compiler to generate code compatible with C. Note that MPW Pascal allows you to declare procedures as C functions so they can talk directly to Acta.

Linking Code Produced by Different Compilers

Except for a few systems like MPW, it’s not possible to link code compiled by different compilers. On the Macintosh, one way to overcome this is to compile code into code resources. These can then be loaded using the segment loader, or in the case of a DA such as Acta, with GetResource. Using this method it’s possible to separately compile and link blocks of code totally independent of which compiler generated them, using virtually any compiler desired by the programmer.

Argument Order

In both C (at least Aztec C, in which Acta is written; MPW C, used in the examples; and LightspeedC, another compiler we’re familiar with) and Pascal, arguments are passed to procedures on the stack. However the order in which the arguments are pushed onto the stack is different for the two languages. Pascal pushes arguments onto the stack in the order in which they are declared. C pushes the arguments in the reverse order of declaration. (Note that this allows C routines to have a variable number of arguments; the first argument is always in a known place [the top of the stack] and can indicate how many other arguments there are.)

If a Pascal procedure is to be callable from C, it must declare its arguments reversed from the C function call, for example:

The C declaration for the format driver main procedure read_Scrap is:

OSErr read_Scrap(infil,resfil,att,add_topic)
word infil, resfil; BLOCK_ATT *att; ProcPtr add_topic;

while the Pascal declaration is:

Function read_Scrap(add_topic:ProcPtr; att:Block_Att; resfil,infil:Integer) 
: OSErr;

When calling a C function from Pascal the arguments must be passed in the reverse order from the C function declaration, for example:

If the C declaration for add_topic is:

void add_topic(data,length,level,attributes,styleHandle)
Ptr data; long length; word level; BLOCK *attributes; Handle styleHandle;

the Pascal call to the function add_topic is:

add_topic(Nil,att,level,size,^text);

while the C call is:

(*add_topic)(*text,size,level,att,NIL);

Argument Passing

C allows a variable number of arguments to be passed to a function, so the function can’t simply remove a fixed number of bytes from the stack before returning as is done in Pascal. When a C function calls a Pascal procedure (Acta calls the a_Scrap main procedure) this creates problems as both the Pascal procedure and the calling C function will remove the arguments from the stack. The converse problem occurs when a Pascal procedure calls a C function (a_Scrap calls add_topic) -- no one removes the arguments from the stack.

For some Macintosh Pascal compilers (Lightspeed and TML) this problem can only be solved by resorting to assembly language “glue” routines. Those of you who don’t care for assembly code please just hold your nose and read on. The result of this discussion is two small, relatively general assembly procedures. One procedure lets Acta call an input format driver written in Pascal and the other allows a Pascal driver to call Acta’s add_topic procedure. You won’t have to write any assembly language to add your own input format driver (well, as long as the format driver interface doesn’t change anyway), though output format drivers are left as an exercise for the reader (or a future column)!

Calling a Pascal procedure from C involves declaring the Pascal procedure as having no arguments, and copying the arguments from the stack into local variables using an assembly procedure (Listing 5). By doing this Pascal will not mess with the stack by deleting the arguments. This is one of those areas where languages like C have it all over Pascal, which was designed to keep the programmer as far from the machine as possible. This promotes machine independence, but like most blessings extracts a price. When you absolutely must get down to the bare metal of the machine, you’re forced to use assembly language to do it.

;Procedure GetArguments( VAR add_topic_Ptr : ProcPtr;
;VAR att : Topic_Attributes;
;VAR ResRefNum : Integer;
;VAR Refnum : Integer);

This procedure will pull the arguments passed to input routines from the stack and put them in the input routines internal variables. This procedure will not change the stack from what C expects on return from the input routine.

This procedure is called as the first statement in the input module. it assumes that A6 was linked at the beginning of the code module. this occurs if there are any local variables at the top level of the code module main entry point routine.

{7}
;
;Stack looks like this:
;------------------------------------------------
;input parameters to input module from Acta
;------------------------------------------------
;Return Address
;------------------------------------------------
;A6===> Old A6
;------------------------------------------------
;arguments for GetArguments
;------------------------------------------------
;GetArguments calling procedure return address
;------------------------------------------------
;A0===> Old A0     <==== SP
;------------------------------------------------
;
;
 link   A0,#0    ; A0 points to getarguments stack frame
 move.L A2,-(SP) ; save A2
 move.L 8(A0),A1 ; A1 = ptr to RefNum
 move.W 8(A6),(A1) ; move refnum from c frame to pascal frame
 move.L 12(A0),A1; A1 = Ptr to ResRefNum
 move.W 10(A6),(A1); move ResRefNum from c to pascal frame
 move.L 16(A0),A1; A1 = Ptr to ATT
 move.L 12(A6),A2; A2 = ptr to C ATT
 move.L (A2)+,(A1)+; move C ATT to pascal ATT
 move.L (A2)+,(A1)+
 move.L (A2)+,(A1)+
 move.L (A2)+,(A1)+
 move.L 20(A0),A1; A1 = ptr to Pascal Procptr
 move.L 16(A6),(A1); move procptr from c to pascal
 move.L (SP)+,A2 ; restore A2
 unlk   A0
 rts

«listing 5»

Function Results

Pascal allocates space on the stack for the functional result and places the arguments on the stack. When the function returns the result is on top of the stack. A function written in C returns the functional value in register D0. Acta (a C program) calls input format drivers as functions. A format driver written in Pascal must conform to this standard for passing functional results.

A Pascal format driver must be defined as a procedure so it doesn’t try to write its function result to the stack. An assembly language procedure is called as the driver’s last statement to load the functional result into register D0 (Listing 6).

;Procedure CFunctionReturn(Error:OsErr);
;

This procedure is a kludge to allow C and Pascal routines to work together Acta calls the a_Text Main routine and expects its functional value to be in the register D0, however Pascal expects there to be space reserved on the stack for it, and would save it there if allowed. This procedure takes an argument which would normally be set equal to the functional result and puts it in D0. The calling procedure will then not set the function equal to this value.

 move.L (SP)+,A0 ; Get Return address 
 move.W (SP)+,D0 ; put functional result in D0 for C
 jmp    (A0); RTS

«listing 6»

Calling a Procedure Passed as an Argument

Acta passes the address of add_topic as an argument to the input module. Unfortunately Pascal can’t call a procedure by pointer directly. The solution, once again, is an assembly glue routine to take this procedure address as an argument and jump to the procedure (Listing 7).

; add_topic(text: Ptr;size: LongInt;level:Integer;
;att:Topic_Attributes; add_topic_Ptr:ProcPtr);
;

This procedure is the glue routine between pascal call to add_topic and Acta’s add_topic routine. Pascal can not call a procedure by using the procptr so a ASM glue routine is required. In addition C requires the calling routine to take its own arguments off the stack. The procptr was added to the add_topic argument list on the end so that this routine could easily pull it off and be left with the arguments on the stack as C wants to see them. This procedure must then remove the arguments off the stack as the C procedure will not do it.

{8}
;
add_topic
 lea    SaveReturn,A0
 move.L (SP)+,(A0) ; save return
 move.L (SP)+,A0 ; get subroutine address 
 jsr    (A0); JSR to C add_topic routine
 lea    18(SP),SP; pull arguments off stack
 lea    SaveReturn,A0; restore return address
 move.L (A0),-(SP)
 rts
SaveReturnDC.L 0 ; storage for return address

«listing 7»

Putting it All Together in Pascal

Listing 8 is a shell which can be called from Acta. A call to the user’s input driver is inserted in this shell. The user’s format driver code is stored in a separate unit and a uses clause which references it is added to the shell replacing the Scrapbook Uses. The assembly language procedures are contained in a file called ASM LIB Library which is compiled using Consulair’s Assembly Development System (formerly MDS) and converted into an LSP library using REL Convert. This library must be added to the project in build order before the format driver code (see figure). See the LSP manual for more information on how to build a code resource.


{9}
UNIT InputDriverShell;

INTERFACE
 USES
 Globals, Scrapbook;

   { main entry point for the code unit }

PROCEDURE Main;

IMPLEMENTATION

PROCEDURE Main;

 VAR
 anErr  : OsErr;
 add_topic_Ptr   : ProcPtr;
 att    : Topic_Attributes;
 ResRefNum  : Integer;
 Refnum : Integer;

  { def for ASM C/Pascal glue for Acta input format driver }
 PROCEDURE CFunctionReturn (anErr : OsErr); external;
 PROCEDURE GetArguments (VAR add_topic_Ptr : ProcPtr;
 VAR att : Topic_Attributes;
 VAR ResRefNum : Integer;
 VAR Refnum : Integer); External;

 BEGIN

 { get the funtion arguments from the stack, 
 behind compiler’s back }
 GetArguments(add_topic_Ptr, att, ResRefNum, Refnum);

 { call the specific input format driver     }
 anErr := a_ScrapBook(add_topic_Ptr, att, 
 ResRefNum, Refnum);

 { put the functional result in register D0 so 
 Acta can get it }
 CFunctionReturn(anErr);

 END;
END.

«listing 8»

Finally, here’s the actual source code which converts TEXT and PICT resources in a scrapbook file (actually, in any resource file) into Acta topics.

{10}
UNIT Scrapbook;
{ this unit will read a scrapbook file into a set of Acta topics for 
use with Acta 2.0 or higher }

INTERFACE

 USES
 Globals; { Pascal def of Topic_Attributes record }

 FUNCTION a_ScrapBook (add_topic_Ptr : ProcPtr;
 att : Topic_Attributes;
 ResRefNum : Integer;
 Refnum : Integer) : OsErr;

IMPLEMENTATION

 FUNCTION a_ScrapBook;

 CONST
 ActaTextTopic = 1;
 ActaPictTopic = 2;
 TopicLevel1 = 1;
 TopicLevel2 = 2;

 VAR
 ResHandle : Handle;
 TempPtr : Ptr;
 anErr : OSErr;
 ErrorString : Str255;
 RError : Integer;
 AppResNumber : Integer;
 ResCount : Integer;
 Size : LongInt;
 TType : OSType;
 i, j, k : Integer;

   { Acta internal procedure for adding a topic to the active window. 
This procedure was written in C, so arguments must be put on the stack 
in the reverse order of Dave’s documentation. This procedure is really 
linked to an ASM glue routine which pulls the pointer to the add_topic 
procedure off the stack and jumps to it and pulls the arguments off the 
stack before returning as well }

 PROCEDURE add_topic (empty : Ptr;
 att : Topic_Attributes;
 level : Integer;
 size : LongInt;
 text : Ptr;
 add_topic_Ptr : ProcPtr);external;


 PROCEDURE Init;

 { initialize a_Scrapbook }

 VAR
 Watch : CursHandle;

 BEGIN

 Watch := GetCursor(WatchCursor);
   { change cursor to watch while converting file }
 SetCursor(Watch^^);

      { save away the current resource file }
 AppResNumber := CurResFile;

   { Read from the input file }
 UseResFile(ResRefNum);

   { start out with the text blocks }
 ATT.bType := ActaTextTopic;
 TType := ‘TEXT’;

 END; { Init }

BEGIN { a_Scrapbook}

 Init;  { Initialize }

 FOR j := 1 TO 2 DO
 BEGIN
 { if the current output type is text then count TEXT }
 {  resource, else count number of picture resources }
 ResCount := CountResources(TType);
 RError := ResError;
 IF RError = noErr THEN
 BEGIN
 { loop through all resources of current type }
 FOR i := 1 TO ResCount DO
 BEGIN
 ResHandle := GetIndResource(TType, i);
 RError := ResError;
 { convert only resources actually in 
 the scrapbook file }
 IF (RError = noerr) AND (HomeResFile( ResHandle) = ResRefNum) THEN
 BEGIN
 Hlock(ResHandle);
 Size := Longint(GetHandleSize(ResHandle));
 add_topic(NIL, ATT, TopicLevel2, Size, ResHandle^, add_topic_ptr);
 HUnLock(ResHandle);
 END; { If (RError = ...  }
 ReleaseResource(ResHandle);
 END; { For (rescount)  }
 END; { RError }
 ATT.bType := ActaPictTopic;
 TType := ‘PICT’;
 END; { for (1 to 2) }
 { Use the application resource fork }
 UseResFile(AppResNumber);
 InitCursor;{ initialize cursor }
 { somewhat simplistic error reporting }
 a_ScrapBook := RError;
 END; { a_ScrapBook}
END. { ScrapBook }

«listing 9»

Conclusion

Format drivers allow programs to be extended easily, adding new features without an entirely new program. They also allow the user to customize the program’s features. On the implementation side, they are easy to write and allow packages to be written in multiple languages, even with development systems that do not normally support this.

Extensibility need not be limited to handling file formats. Future versions of Acta may have feature drivers.

The shrewd reader will have noticed that the techniques we’ve discussed allow you to break up your program into pieces which can be sold separately. This means you can get the program out the door quicker, and add the features later. And your marketing experts can have a field day packaging the different pieces.

Exercises

The answers to these exercises will not appear in next month’s MacTutor. But, you may be able to release them as free or shareware programs.

1. Modify a_TEXT to support MPW’s font and size specification.

2. Write an input driver which reads a tab (or comma) delimited file, creating a new level at each delimiter. (This format driver should have a name such as a_TEXT/tab, so the user has the choice of how to split topics.)

3. Write an input driver which reads a text file into a single topic. Acta uses TextEdit, so check for files which are too large. (This format driver should have a name such as a_TEXT/1 topic, so the user has the choice of how to split topics.)

4. Adopt the format driver technique in your own program.

5. (extra credit) Write a format driver for Microsoft Word 3.0 format.

Appendix -- Scrolling Icon List

Implementing the user interface really isn’t in the scope of this article, but we haven’t seen many examples of custom list definition functions (LDEFs).

Adding a scrolling list to the Standard File dialogs is pretty easy. Custom (SFPGetFile/ SFPPutFile) dialogs have a userItem, and the List Manager handles the work (with the aid of a custom LDEF). The dlgHook initializes the list when it gets passed item -1, and the filterProc checks for mouseDown events in the list. The only tricky part is in disposing of the list after the SFPPutFile call. If you call LDispose after the call, the List Manager tries to call DisposControl for the scroll bar but DisposDialog has already disposed of all the controls. If you try to call LDispose in the dlgHook after a click on the OK button, you’re faced with the problem that the dialog may not really go away -- the user may decide not to replace a file with the same name. Our solution was to set the list’s vScroll field to NIL before calling LDispose, since after the return from SFPPutFile, the control no longer exists.

Flying in the face of Inside Macintosh volume IV, the LDEF is written in C. The routine presented here shows only how to draw labelled icons (Acta’s LDEF uses additional data structures, and disposes them when it receives an lCloseMsg).

{11}
struct ListEntry {
 Handle icon;
 char   name[64]; /* Icon label (file name) */
};
typedef struct ListEntry  ListEntry;

/*
LDEF -- List Definition Procedure
*/
pascal void ldef(message,select,rect,cell,dataOffset,dataLen,handle)
word    message;
word    select;
Rect    *rect;
Cell    cell;
word    dataOffset;
word    dataLen;
ListHandlehandle;
{
 Rect   box;
 ListEntrylistData;
 BitMap iconBits;
 GrafPtrthePort;
 char   displayName[64];

 if (dataLen == 0) return;/* Nothing to draw (excludes         
 lCloseMsg) */
 GetPort(&thePort);/* Get current grafPort */
 /* Get our rectangle (only lDrawMsg, lHiliteMsg should get    
 past */
 /*  the dataLen test) */
 box = *rect;  /* Make a copy so we can change it */
 box.top += 2;
 box.left += 16;
 box.bottom = box.top + 32; /* Icons are 32 pixels */
 box.right = box.left + 32;
 /* dataLen is already set */
 LGetCell(&listData,&dataLen,cell,handle);
 switch (message) {
  case lDrawMsg:
 EraseRect(rect);
 PlotIcon(&box,listData.icon);
 /* If name begins with “a_” then ignore prefix */
 if ((listData.name[1] == ‘a’ || listData.name[1] == ‘A’) &&
 listData.name[2] == ‘_’) {
 /* Make a copy, since listData has filename */
 displayName[0] = listData.name[0] - 2;
 BlockMove(&listData.name[3],&displayName[1],(long)displayName[0]);
  } else {
 BlockMove(&listData.name[0],&displayName[0],
 (long)listData.name[0] + 1L);
 }
 TextFont(geneva);
 TextSize(9);
 MoveTo(rect->left + 32 - StringWidth(displayName) / 2,
 rect->top + 32 + 12);  /* Center the name */
 DrawString(displayName);
 /* Restore typestyle to assumed value */
 TextFont(systemFont);
 TextSize(12);
 if (!(select & 0x100))
 break;
 /* else fall through */
  case lHiliteMsg:
 /* Set up the bit map */
 iconBits.rowBytes = 4;
 SetRect(&iconBits.bounds,0,0,32,32);

 /* According to Steve Brecher, no need to lock, since         
 CopyBits won’t alter the heap configuration                   unless 
a picture or region is being recorded. */

 iconBits.baseAddr = (char *)(*listData.icon) + 128;
 CopyBits(&iconBits,&thePort->portBits, &iconBits.bounds,&box,
 srcXor,NIL);    /* Blit the icon */
 break;
 }
} 

Acta Document Format

Written by David Dunham

©25 September 1987 Maitreya Design

Maitreya Design

POB 1480

Goleta, CA 93116

This note assumes you are familiar with Acta and its terminology. Acta documents have the type ‘OTLN’ and creator ‘ACTA.’

An outline on disk consists of a data fork. This is simply the data for each topic in sequence (top-to-bottom order). The file is terminated with a zero word.

Each topic is preceded by its level. Topics at the left margin are level 1, their daughters 2, etc. The topic’s attributes indicate its type and formatting. Data is preceded by its length as a longword. The data itself is either text (not a Pascal string!) or a QuickDraw picture, and is not padded.

The same format is used for the clipboard; Acta uses a scrap type of ‘ACTA.’ (It also writes a TEXT scrap.)

{12}
struct TOPIC_ATTRIBUTES {
 word bType;/* TEXTtype, PICTtype */
 word bAttributes; /* currently 0, except for                  
 optionWord bits */
 word bFont;/* Typestyle */
 word bStyle;
 word bSize;
 byte bColor;    /* color index */
 byte bExtra;    /* reserved; currently 0 */
 byte firstLine; /* Show first line only? */
 byte expanded;  /* Y/N */
 word hidden;    /* Is block hidden (by Collapse)?             
 count of hide depth */
}

BType is 1 for a text topic, 2 if the topic is a QuickDraw picture. Other values are reserved for future use. BAttributes is currently unused and should be left 0, except that the bAttributes for the first topic is used to determine the options. BFont, bStyle, and bSize determine the typestyle of a topic, and have their usual QuickDraw interpretation. BColor is an index into a table of color values; 0 is black. BExtra is reserved and should be 0. FirstLine should be set to TRUE (-1) if the topic is shrunken, FALSE (0) otherwise. Expanded is TRUE if the daughters are visible, FALSE if they are hidden. If a topic is visible, hidden is 0, otherwise it is the number of collapsed ancestors.

If bAttributes of the first topic is 0, the default options of alphabetic sort A-Z, no ancestress constraint, and outline current topic are used. You can choose different options by setting the following bits (all other bits should be left reset). These bits are ignored if set on topics other than the first.

0x0100 numeric sort

0x0001 Z-A sort

0x0002 single ancestress

0x0004 “smart quotes”

0x0020 don’t label pictures

0x0040 don’t outline current topic

0x0080 don’t put bullets in Clipboard

In future releases, additional information (such as TextEdit ‘styl’ records) may be added. It will follow the zero word. This data can be ignored, as the above format will be used for backward compatibility.

 
AAPL
$111.78
Apple Inc.
-0.87
MSFT
$47.66
Microsoft Corpora
+0.14
GOOG
$516.35
Google Inc.
+5.25

MacTech Search:
Community Search:

Software Updates via MacUpdate

calibre 2.13 - Complete e-library manage...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Mellel 3.3.7 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
ScreenFlow 5.0.1 - Create screen recordi...
Save 10% with the exclusive MacUpdate coupon code: AFMacUpdate10 Buy now! ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your... Read more
Simon 4.0 - Monitor changes and crashes...
Simon monitors websites and alerts you of crashes and changes. Select pages to monitor, choose your alert options, and customize your settings. Simon does the rest. Keep a watchful eye on your... Read more
BBEdit 11.0.2 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
ExpanDrive 4.2.1 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe After Effects CC 2014 13.2 - Creat...
After Effects CC 2014 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). After Effects CS6 is still available... Read more
Evernote 6.0.5 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
Command-C 1.1.7 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Tidy Up 4.0.2 - Find duplicate files and...
Tidy Up is a complete duplicate finder and disk-tidiness utility. With Tidy Up you can search for duplicate files and packages by the owner application, content, type, creator, extension, time... Read more

Latest Forum Discussions

See All

Make your own Tribez Figures (and More)...
Make your own Tribez Figures (and More) with Toyze Posted by Jessica Fisher on December 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
So Many Holiday iOS Sales Oh My Goodness...
The holiday season is in full-swing, which means a whole lot of iOS apps and games are going on sale. A bunch already have, in fact. Naturally this means we’re putting together a hand-picked list of the best discounts and sales we can find in order... | Read more »
It’s Bird vs. Bird in the New PvP Mode f...
It’s Bird vs. Bird in the New PvP Mode for Angry Birds Epic Posted by Jessica Fisher on December 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Telltale Games and Mojang Announce Minec...
Telltale Games and Mojang Announce Minecraft: Story Mode – A Telltale Games Series Posted by Jessica Fisher on December 19th, 2014 [ permalink ] | Read more »
WarChest and Splash Damage Annouce Their...
WarChest and Splash Damage Annouce Their New Game: Tempo Posted by Jessica Fisher on December 19th, 2014 [ permalink ] WarChest Ltd and Splash Damage Ltd are teaming up again to work | Read more »
BulkyPix Celebrates its 6th Anniversary...
BulkyPix Celebrates its 6th Anniversary with a Bunch of Free Games Posted by Jessica Fisher on December 19th, 2014 [ permalink ] BulkyPix has | Read more »
Indulge in Japanese cuisine in Cooking F...
Indulge in Japanese cuisine in Cooking Fever’s new sushi-themed update Posted by Simon Reed on December 19th, 2014 [ permalink ] Lithuanian developer Nordcurrent has yet again updated its restaurant simulat | Read more »
Badland Daydream Level Pack Arrives to C...
Badland Daydream Level Pack Arrives to Celebrate 20 Million Downloads Posted by Ellis Spice on December 19th, 2014 [ permalink ] | Read more »
Far Cry 4, Assassin’s Creed Unity, Desti...
Far Cry 4, Assassin’s Creed Unity, Destiny, and Beyond – AppSpy Takes a Look at AAA Companion Apps Posted by Rob Rich on December 19th, 2014 [ permalink ] These day | Read more »
A Bunch of Halfbrick Games Are Going Fre...
A Bunch of Halfbrick Games Are Going Free for the Holidays Posted by Ellis Spice on December 19th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »

Price Scanner via MacPrices.net

The Apple Store offering free next-day shippi...
The Apple Store is now offering free next-day shipping on all in stock items if ordered before 12/23/14 at 10:00am PT. Local store pickup is also available within an hour of ordering for any in stock... Read more
It’s 1992 Again At Sony Pictures, Except For...
Techcrunch’s John Biggs interviewed a Sony Pictures Entertainment (SPE) employee, who quite understandably wished to remain anonymous, regarding post-hack conditions in SPE’s L.A office, explaining “... Read more
Holiday sales this weekend: MacBook Pros for...
 B&H Photo has new MacBook Pros on sale for up to $300 off MSRP as part of their Holiday pricing. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699... Read more
Holiday sales this weekend: MacBook Airs for...
B&H Photo has 2014 MacBook Airs on sale for up to $120 off MSRP, for a limited time, for the Thanksgiving/Christmas Holiday shopping season. Shipping is free, and B&H charges NY sales tax... Read more
Holiday sales this weekend: iMacs for up to $...
B&H Photo has 21″ and 27″ iMacs on sale for up to $200 off MSRP including free shipping plus NY sales tax only. B&H will also include a free copy of Parallels Desktop software: - 21″ 1.4GHz... Read more
Holiday sales this weekend: Mac minis availab...
B&H Photo has new 2014 Mac minis on sale for up to $80 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 1.4GHz Mac mini: $459 $40 off MSRP - 2.6GHz Mac mini: $629 $70 off MSRP... Read more
Holiday sales this weekend: Mac Pros for up t...
B&H Photo has Mac Pros on sale for up to $500 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2599, $400 off MSRP - 3.5GHz 6-core Mac Pro: $3499, $... Read more
Save up to $400 on MacBooks with Apple Certif...
The Apple Store has Apple Certified Refurbished 2014 MacBook Pros and MacBook Airs available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Save up to $300 on Macs, $30 on iPads with Ap...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
iOS and Android OS Targeted by Man-in-the-Mid...
Cloud services security provider Akamai Technologies, Inc. has released, through the company’s Prolexic Security Engineering & Research Team (PLXsert), a new cybersecurity threat advisory. The... Read more

Jobs Board

*Apple* Store Leader Program (US) - Apple, I...
…Summary Learn and grow as you explore the art of leadership at the Apple Store. You'll master our retail business inside and out through training, hands-on experience, Read more
Project Manager, *Apple* Financial Services...
**Job Summary** Apple Financial Services (AFS) offers consumers, businesses and educational institutions ways to finance Apple purchases. We work with national and Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.