UI Style Guide Data Sharing

Data Sharing

This chapter is a little different from the other chapters in this book because it does not directly consider the question of how to make the best human-machine interface for Amiga applications. Instead, it covers the best ways for programs to share data with each other.

User interactions are not directly involved in data sharing, but the issue is crucial to the user. Without a data sharing standard, the user has to convert data to a different format every time it is used across applications. Worse still, a conversion tool may not be available. With a data sharing standard this problem is eliminated.

A data sharing standard is also important to get the best advantage from multitasking. When applications on the Amiga follow a data standard, a unique synergy is created - specialized applications from different vendors can be combined seamlessly for a custom environment.

For instance, you can create a background picture in a paint package, add three-dimensional text in a ray-tracing application, and add animation in an animation package, all without once running a conversion program. The applications can run together simultaneously as an integrated graphics package.

The Amiga's standard for data sharing, Interchange File Format (IFF), is a widely accepted and simple set of rules that was well-defined and adopted very early in the Amiga's history.

A Practical Introduction to the IFF Standard

This section provides a brief overview of the IFF standard. For more detail refer to Interchange File Format Specification.

An IFF data structure has two levels. The first level is a wrapper or envelope structure which is, technically, the syntax. It's easy to describe: the IFF wrapper is just a header containing an identifier and the file size. The identifier is four letters and the file size is a number taking up 32 bits of space. The whole IFF wrapper weighs in at eight bytes of disk space. That's it.

Perhaps the greatest strength of IFF is that it was well-defined and adopted very early in the Amiga's history.

There are only three possible identifiers for the wrapper part of IFF files: FORM, CAT (a space after the T) and LIST.

• FORM - This is by far the most common type, equivalent to a simple file.
• CAT - A concatenation, equivalent to multiple files put together.
• LIST - Also a concatenation but with some properties shared between the separate files to avoid redundancy.

It is possible to build some fairly complex files using just these three types since a FORM may contain FORMs within it; a LIST can contain other FORMs, CATs or LISTs and so forth. (To help with the possible complexity of IFF syntax, the operating system contains a function library named iffparse.library.) In practice, however, the most common IFF file is the simple FORM containing a single set of data. There may be any type of data within the FORM wrapper.

The second layer of an IFF file, underneath the wrapper, defines the particular file types. The file types consist of a four-letter identifier followed by a series of data chunks which contain the data natural to the type. Some examples are:

Type ID	Data Stored in this Type
ILBM	Graphics data in interleaved bitmap format. This is very widely used on the Amiga.
8SVX	Audio data in 8-bit sample bytes. The most widely used audio file format on the Amiga.
FTXT	Formatted text. Recommended for sharing text data.
ANIM	A common way to store interchangeable animation files.

Each IFF file type contains a number of data chunks specific to the type. These data chunks are the basic building blocks of IFF files and they come in a wide variety. They can be structured in any number of ways, but a chunk always starts with a four-letter ID followed by the chunk size which, as in the wrapper, is given as a 32-bit number.

For example the 8SVX file type consists of two chunks: a VHDR chunk which contains information like the sampling speed, and the BODY chunk which contains the sample bytes.

Here is a listing of typical 8SVX file to give you a better idea of how IFF files are structured:

  FORM                               IFF wrapper ID
  10120                              IFF file size as a 32-bit value

  8SVX                               type ID (10120 bytes of 8SVX data)

  VHDR                               chunk ID
  20                                 chunk size

  00 02 3D 90 00 00 00 00 00 00      20 bytes of VHDR chunk data
  00 00 21 4A 01 00 00 01 00 00

  BODY                               chunk ID
  10080                              chunk size

  12 00 10 55 00 90 13 FF 12 00      10080 bytes of BODY chunk data
  10 55 00 90 13 FF...

The IFF Philosophy

The goals of IFF are lofty but obviously within reach. IFF is intended to make data abstract enough to be stored independent of a particular program, compiler, device or machine architecture. With that achieved, IFF files could be shared not only between applications but also on and between platforms other than the Amiga.

The key to this is making the data abstract. The IFF standard accomplishes this by building the files through chunks each with an ID and size. The ID is a reference by name to a given implementation of an access procedure. The access procedures can evolve and change independently of the software which uses them. And the size count enables applications to support object operations like "copy" and "skip to next" regardless of the object type or contents.

IFF is meant to be easily extensible. The CAT and LIST wrappers make it easy to combine existing types to form new composite types. And if all else fails the IFF specification provides rules for creating new file types for special storage needs that are not handled by the existing IFF types.

IFF and Your Application

If an IFF format exists for your program's genre, you only need to provide two features:

• a way for users to save files in that IFF format;
• a way for your program to import files that have been saved in that IFF format.

In some cases the IFF format is also the best format for everyday file storage. Many applications have opted to use ILBM for those purposes. In other cases, the IFF format is not great as a normal storage format. In these cases, you can provide your own internal storage format, but you should also provide the means to save and import IFF.

Note, however, that revisions to your application could mean changes in your internal data format. If you have been using your internal data format as your storage format as well, any files saved in the old format may not be readable by the new format. If you don't use IFF as the default storage format, at least try to provide for backwards compatibility in your own program.

If No IFF Format Exists

If no IFF format exists for your program's genre, it would be a good idea to develop an IFF format and use that.

If you need to create a new IFF format or expand upon an existing one, then you must register the change with the AmigaOS Development Team. The AmigaOS Development Team serves as a central clearinghouse to keep track of new developments in the IFF standard. The official registry of IFF form and chunk types is at the IFF FORM and Chunk Registry.

The Clipboard

IFF provides a data sharing standard. In conjunction with that, the Amiga's clipboard device provides a place to store and retrieve that data. It does this by caching data to RAM and automatically spooling the data to disk if necessary.

The clipboard is the recommended storage device for cut-and-paste operations and it's the best place to store data which is meant to be quickly moved between between two applications that are running simultaneously. It also provides a solid metaphor in keeping with the Workbench.

The clipboard allows the exchange of data dynamically between your application and another.

Use IFF

All data written to the clipboard must be written in the IFF format. For most applications the data will be one of two types: graphics or text. For graphic clips use the ILBM form of IFF. For text clips use the FTXT form of IFF.

When reading from the clipboard, never blindly read the data assuming, for instance, that the clip contains FTXT with a CHRS as the first and only chunk. Remember, the user may have been switching between many applications and may even have made a mistake in the cut-and-paste operation.

Storage Concerns

When storing data in the clipboard, it is acceptable to write different representations of the same data. For instance, in a music application when the user cuts a bar of music, the application can write the information in three ways. The music itself could be saved in a SMUS form; the lyrics could be saved separately in an FTXT form; and a picture of the notation could be saved in an ILBM form. This type of multiple clip should be contained within a CAT "wrapper" form. Use CAT CLIP as the global form name.

Unit Selection

The clipboard device allows for the selection of units ranging from zero to 255. By default, your application should always use clipboard unit zero for interactive cut, copy and paste operations. Provide a means, however, for the user to specify a different unit number.

Notification

Notification is a means by which an application can receive a message whenever a certain file of interest is modified. By establishing "hot links" between applications, notification allows a change made to a file with one program to be automatically reflected in another application that is using the same file.

Hot links allow a change made to a file with one program to be automatically reflected in another application which is using the same file.

An example would be a paint package in which the user could save a brush and, using notification, automatically have an image processor application modify the brush and return it in a separate file. The scenario would work like this:

1. PAINT PACKAGE

• Writes brush to file named T:brush.

2. IMAGE PROCESSOR

• Gets notification that T:brush has been updated.
• Reads T:brush into work area.
• Alters brush using an image processing feature.
• Writes brush out to T:brush.mod.

3. PAINT PACKAGE

• Gets notification that T:brush.mod has been updated.
• Reads T:brush.mod into brush area.

There is only one style standard to worry about with notification: keep RAM usage reasonable. Because RAM is a limited resource, applications that have very large amounts of data should not store directly in RAM:.

Notification may not work in a network situation because it is not implemented with some file systems. It does work on RAM:, FFS and OFS.

Environment Variables

With general availability of networking cards for the Amiga, the use of environment variables is sure to increase. Environment variables are basically places where information can be stored; they are similar to logical assignments in that a variable text string is given a generic label. For example, in the Shell, the user can type:

 echo $workbench

and be presented with the current version in use. Environment variables are set by the user with the SetEnv command of AmigaDOS.

Store your variables in a subdirectory such as ENV:<basename>/variables. Only user-defined and standard system variables should go in ENV:. ENV:Sys/ is reserved for system functions.

Here are some recommended environment variable names currently in use in the system. Note: they are not case-sensitive.

workbench	The version of Workbench
kickstart	The version of Kickstart
hostname	Contains the machine name
username	Contains the login name of the current user of the machine
editor	Sets the preferred text editor

The following are local variables provided by the Shell. These are most relevant to applications that use DOS scripts. Of course you should avoid using these names for your variables since they are set automatically by the Shell.

process	The process number
RC	The primary return code of the last command run
Result2	The secondary return code of the last command run