SAUCE Specs.

Introduction.

Let us begin with a description of the record layouts used. The record layouts and code examples are in a variated pascal pseudo code, and should be transferrable enough to implement in most other programming languages. For ease of reading, the examples assume that the file is correct and that no error- checking need be included. How rigorous you check for errors is completely up to you, and will most likely depend on the file type you are describing.

A File with SAUCE added to it, will look like this:

File Data	Actual file data as it would be without SAUCE.
EOF Marker	End Of File marker. This will assure character files like ANSi files (the main reason why SAUCE was made) can easily determine the end of the file.
SAUCE Comment block	Optional SAUCE comment block.
SAUCE Record	The SAUCE record.

SAUCE Record.

The SAUCE record describes the file in short, and provides other information not included in the SAUCE record itself. A sauce record is EXACTLY 128 bytes in size.

Layout of a SAUCE record.

FieldName	Size	Type	Version	Description
ID	5	Character	00	SAUCE identification. This should be equal to 'SAUCE' or the record is not a valid SAUCE record.
SAUCE Version	2	Character	00	Version number of SAUCE. Current version is '00'. As new features are added to the specifications of SAUCE, this version may change. Future versions SHOULD remain compatible with version 00, adding to the specifications only. It is however not unlikely that this compatibility is impossible to maintain.
Title	35	Character	00	Title of the file
Author	20	Character	00	Name or 'handle' of the creator of the file.
Group	20	Character	00	Name of the group/company the creator is employed by.
Date	8	Character	00	Date the file was created. This date is in the format CCYYMMDD (century, year, month, day).
FileSize	4	Long	00	Original filesize NOT including any information of SAUCE.
DateType	1	Byte	00	Type of data. See Datatypes.
FileType	1	Byte	00	Type of file. See Filetypes.
TInfo1	2	Word	00	Numeric information field 1 (See Datatypes). When used, this field holds informative values. Any program using SAUCE should NOT rely on these values being correct or filled in.
TInfo2	2	Word	00	Numeric information field 2 (See Datatypes).
TInfo3	2	Word	00	Numeric information field 3 (See Datatypes).
TInfo4	2	Word	00	Numeric information field 4 (See Datatypes).
Comments	1	Byte	00	Number of comment lines (See Comments )
Flags	1	Byte	00	Flags indicating optional settings/switches. These flags have different meaning depending on the datatypes & filetypes.
Filler	22	Byte	00	Padding bytes to make record 128 in size.  All bytes should be binary zero.

• Byte : One byte unsigned numeric value (0 to 255)
• Word : Two bytes unsigned numeric value (0 to 65535)
• Long : Four bytes signed numeric value (-2147483648 to -2147483647)
• Character : One byte ASCII value.  It is not a PASCAL type string (with leading length byte) nor is it a C style string (with a trailing zero-terminator).
• Numeric fields should be zero when not used.  Character fields should be all spaces when not used

An example PASCAL record looks like this:

TYPE SAUCERec = RECORD
                  ID       : Array[1..5] of Char;
                  Version  : Array[1..2] of Char;
                  Title    : Array[1..35] of Char;
                  Author   : Array[1..20] of Char;
                  Group    : Array[1..20] of Char;
                  Date     : Array[1..8] of Char;
                  FileSize : Longint;
                  DataType : Byte;
                  FileType : Byte;
                  TInfo1   : Word;
                  TInfo2   : Word;
                  TInfo3   : Word;
                  TInfo4   : Word;
                  Comments : Byte;
                  Flags    : Byte;
                  Filler   : Array[1..22] of Char;
END;

An Example C record looks like this:

typedef SAUCEREC {
   char           ID[5];
   char           Version[2];
   char           Title[35];
   char           Author[20];
   char           Group[20];
   char           Date[8];
   signed long    FileSize;
   unsigned char  DataType;
   unsigned char  FileType;
   unsigned short TInfo1;
   unsigned short TInfo2;
   unsigned short TInfo3;
   unsigned short TInfo4;
   unsigned char  Comments;
   unsigned char  Flags;
   char           Filler[22];
} SAUCEREC;

Datatypes.

Datatype and filetype hold the information needed to determine what type of file it is. There are currently 9 DataTypes, these are (with their respective numeric values) :

• 0) None :: Undefined filetype, you could use this to add SAUCE information to personal datafiles needed by programs, but not having any other meaning.
• 1) Character : Any character based file. Examples are ASCII, ANSi and RIP.
• 2) Graphics : Any bitmap graphic file. Examples are GIF, LBM, and PCX.
• 3) Vector : Any vector based graphic file. Examples are DXF and CAD files.
• 4) Sound : Any sound related file. Examples are samples, MOD files and MIDI.
• 5) BinaryText: This is RAW memory copy of a text screen. It's basically the BIN format you can save from whitin TheDraw. Each character is built up of two consecutive bytes. The first is the character to be displayed. The second is the Attribute byte.
• 6) XBIN : XBIN is the so called eXtended BIN format. It is similar to the BinaryText, but provides for fonts, palettes, and has built-in compression.
• 7) Archive : Any type of archive. Examples are ARC, ZIP, ARJ and LZH.
• 8) Executable: Any file that is executable.

FileTypes.

Given a certain datatype, a file can be classified even further.  The following is a list of all the currently defined filetypes for each datatype.

None.

When using the 'None' datatype, you should have FileType set to zero also. This is a compatibility issue as it's not unlikely, the 'None' datatype will have filetypes in the future.

Character.

When using the 'Character' datatype, you have following filetypes available :

• 0) ASCII : Plain text file with no formatting codes or color codes. TInfo1 is used for the width of the file. TInfo2 is used to hold the number of lines in the file.
• 1) ANSi : ANSi file. With ANSi color codes and cursor positioning. TInfo1 is used for the width of the file. TInfo2 is used to hold the number of ANSi screen lines in the file.
• 2) ANSiMation: ANSi Animation. With ANSi color codes and cursor positioning. While an ANSi file can also have animated sequences, there is a clear distinction. While an ANSi may or may not have a beginning animated sequence introducing the group or artist the rest is just a sequence of colored characters. An ANSiMation on the other hand is a more like a text mode cartoon. TInfo1 is used for the width of the file. TInfo2 is used to hold the number of ANSi screen lines the ANSiMation was created for. A program using SAUCE may use these two values to switch to the appropriate video mode.
• 3) RIP : Remote Imaging Protocol (RIP) graphics file. TInfo1 holds the width (should be 640) TInfo2 holds the height (should be 350) TInfo3 holds the number of colors (should be 16).
• 4) PCBoard : File with PCBoard style @X color codes and @ macro's and ANSi codes. TInfo1 is used for the width of the file. TInfo2 is used to hold the number of ANSi screen lines in the file.
• 5) AVATAR : A file with AVATAR and ANSi color codes and cursor positioning. TInfo1 is used for the width of the file. TInfo2 is used to hold the number of ANSi screen lines
• 6) HTML : HyperText Markup Language. The type of file used on World Wide Web (WWW).
• 7) SOURCE : A piece of sourcecode for any type of programming language. The file extention should determine the programming language (.C=C, .PAS=Pascal, ...)

Flags for the Character datatype.

7	6	5	4	3	2	1	0
0	0	0	0	0	0	0	A

A) Non-Blink mode (iCE Color). When this bit is SET (equal to 1) The ANSi is created using iCE color codes. This is a special mode where the blinking is disabled, and you have 16 background colors available. Basically, you have the same choice for background colors as for foreground colors.
Please note: When the picture does not make specific use of the iCE color, you should NOT have this bit set. When you do not support the iCE color mode, you should probably not display the file as it could look pretty weird in normal mode

Graphics.

WARNING: Adding SAUCE to some of the graphic file formats will make them invalid.

For all graphics types :

• TInfo1 holds width of the image,
• TInfo2 holds the Height of the image and
• TInfo3 holds the number of bits per pixel (a 256 colour image would have 8 bits per pixel, a TrueColour image would have 24).

Following Graphics filetypes are available :

• 0) GIF (CompuServe Graphics Interchange format)
• 1) PCX (ZSoft Paintbrush PCX format)
• 2) LBM/IFF (DeluxePaint LBM/IFF format)
• 3) TGA (Targa Truecolor)
• 4) FLI (Autodesk FLI animation file)
• 5) FLC (Autodesk FLC animation file)
• 6) BMP (Windows or OS/2 Bitmap)
• 7) GL (Grasp GL Animation)
• 8) DL (DL Animation)
• 9) WPG (Wordperfect Bitmap)
• 10) PNG (Portable Graphics)
• 11) JPG (JPeg compressed File)
• 12) MPG (MPeg compressed animation/video)
• 13) AVI (Audio Visual Interlace)

Flags for the graphics datatype:

Not used, should be all zeroes.

Vector.

WARNING: Adding SAUCE to some of the vector file formats will make them invalid.

Following Vector filetypes are available :

• 0) DXF (CAD Data eXchange File)
• 1) DWG (AutoCAD Drawing file)
• 2) WPG (WordPerfect/DrawPerfect vector graphics)
• 3) 3DS (3D Studio file).

Flags for the vector datatype

Not used, should be all zeroes.

Sound.

WARNING: Adding SAUCE to some of the sound file formats will make them invalid.

Following sound filetypes are available :

• 0) MOD (4, 6 or 8 channel MOD/NST file)
• 1) 669 (Renaissance 8 channel 669 format)
• 2) STM (Future Crew 4 channel ScreamTracker format)
• 3) S3M (Future Crew variable channel ScreamTracker3 format)
• 4) MTM (Renaissance variable channel MultiTracker Module)
• 5) FAR (Farandole composer module)
• 6) ULT (UltraTracker module)
• 7) AMF (DMP/DSMI Advanced Module Format)
• 8) DMF (Delusion Digital Music Format (XTracker))
• 9) OKT (Oktalyser module)
• 10) ROL (AdLib ROL file (FM))
• 11) CMF (Creative Labs FM)
• 12) MIDI (MIDI file)
• 13) SADT (SAdT composer FM Module)
• 14) VOC (Creative Labs Sample)
• 15) WAV (Windows Wave file)
• 16) SMP8 (8 Bit Sample, TInfo1 holds sampling rate)
• 17) SMP8S (8 Bit sample stereo, TInfo1 holds sampling rate)
• 18) SMP16 (16 Bit sample, TInfo1 holds sampling rate)
• 19) SMP16S (16 Bit sample stereo, TInfo1 holds sampling rate)
• 20) PATCH8 (8 Bit patch-file)
• 21) PATCH16(16 Bit Patch-file)
• 22) XM (FastTracker ][ Module)
• 23) HSC (HSC Module)
• 24) IT (Impulse Tracker)

Flags for the sound datatype

Not used, should be all zeroes.

BinaryText .

The binary text format, basically has no Filetype, since the datatype has already defined how the file will look. The filetype however specifies the width of the binary text screen. Only the width is required, as the height can be calculated by dividing the filesize by the width. In an attempt to provide as much width as possible in a possible 256 values of the byte-sized filetype. The width is specified in multiples of 2. The fact that the width is specified in multiples of 2 isn't really a problem, since you also need to define the effective screen size in multiples of 2.

An example : For normal 80*25 binary images as made with TheDraw the filetype value would be 40 (since 2*40 equals 80). All you need to do is divide the width of the binary text image by 2. This gives a maximum width of 510 characters. Although currently not supported, should there be a need for even bigger images, this can be arranged.

Please note. BinaryText expects the character-attribute pairs to be stored one row at a time. If you wanted to create a 80*100 Image, you could do this by just copying 4 80*25 or 2 80*50 together to form one bigger image. If for example you wanted to create a 160*25 image from 2 80*25 images, you would need to write a little program which would copy line 1 from image 1, line 1 from image 2, Line 2 from Image 1, Line 2 from Image 2 and so on. Basically, you should have all character-attribute pairs from one line of the complete image one after the other, followed by all char-attribute pairs from the next row, and so on. If the picture does not fit this format. You should use the None datatype. Besides, you'd probably want to have it in this format anyway, as it seems to be the most logical approach to have these kind of images.

Flags for the BinaryText datatype.

7	6	5	4	3	2	1	0
0	0	0	0	0	0	0	A

A) Non-Blink mode (iCE Color). This bit has exactly the same meaning as for the Character datatype. It indicates whether the picture uses iCE color or not.

XBin.

The XBin datatype has no other filetypes. Further specifications on the XBin format are available in the XBin archive or on the XBin web-page. The filetype should be zero. TInfo1 holds width of the image, TInfo2 holds the Height of the image. Flags are not used

Archive.

WARNING: Adding SAUCE to some of the archive file formats will make them invalid.

Following archive filetypes are available :

• 0) ZIP (PKWare)
• 1) ARJ (Robert K. Jung)
• 2) LZH (Haruyasu Yoshizaki (Yoshi))
• 3) ARC (SEA)
• 4) TAR (Unix TAR format)
• 5) ZOO
• 6) RAR
• 7) UC2
• 8) PAK
• 9) SQZ

Flags for the sound datatype

Not used, should be all zeroes.

Executable.

WARNING: Adding SAUCE to some of the archive file formats will make them invalid.

The executable datatype has no other filetypes. Executables usually have any of the following file extentions : BAT, COM, EXE, OVL, OVR, DLL, ... The filetype and flags should be zero.

Comments.

The comment block is an addition to the SAUCE record. It holds up to 255 lines of additional information. Each line 64 characters wide. When the Comments field (in the SAUCE record) is not zero, it holds the number of additional comment lines available. A single comment line is 64 characters long. Like the character fields in the SAUCE record, it is padded with spaces, and has no leading length byte or trailing null-byte. The comment block is preceded with a 5 character identification mark. This identification mark is 'COMNT'.

ID ('COMNT')	Comment block identification bytes.
Comment Line 1	First comment line.
Comment Line 2	Second comment line
...
Comment Line X	X-th comment line, X equals the Comments field in the SAUCE record

Example pseudocode to read SAUCE.

Variables:
   Byte : Count;
   Long : FileSize;
   file : F;

Code:
   Open_File(F);                          | Open the file for read access
   FileSize = Size_of_file(F);            | Determine filesize
   Seek_file (F, FileSize-128);           | Seek to start of SAUCE (Eof-128)
   Read_File (F, SAUCE);                  | Read the SAUCE record
   IF SAUCE.ID="SAUCE" THEN               | ID bytes match "SAUCE" ?
      IF SAUCE.Comments>0 THEN            | Is there a comment block ?
         Seek_File(F, FileSize-128-(SAUCE.Comments*64)-5); | Seek to start of Comment block.
         Read_File(F, CommentID);         | Read Comment ID.
         IF CommentID="COMNT" THEN        | Comment ID matches "COMNT" ?
            For Count=1 to SAUCE.Comments | \ Read all comment lines.
            Read_File(F, CommentLine)     | /
            ENDFOR
         ELSE
            Invalid_Comment;              | Non fatal, No comment present.
         ENDIF
      ENDIF
   ELSE
      Invalid_SAUCE; | No valid SAUCE record was found.
   ENDIF

You can also download a fully working implementation for SAUCE extraction as a Turbo Pascal unit.  The extraction code itself is implemented in built-in Assembly.  It should be fairly easy to port the sourcecode to C.  Download SAUCE_.PAS.

Information and Upgrades.

If you have a need for additional information on SAUCE, or want to see some modifications, you can email me at Tasmaniac@acid.org

Back to SAUCE

This page is being maintained by