                        Turbo Pascal for DOS Tutorial
                             by Glenn Grotzinger
            Part 11 -- data representation; reading specs sheets
                  copyright (c) 1995-96 by Glenn Grotzinger

Is there still any interest in this tutorial?  If so, tell me! :>

Here is a solution to last chapter's problem.  Here is the unit.

UNIT10

{$O+}
unit unit10;

interface
  uses dos;
  function parse_filespec(filename: string):string;
  procedure copyafile(inname, outname: string);
  procedure writehelp;
  procedure process;

implementation

function parse_filespec(filename: string):string;
    const
      all_files = $27;
    var
      dir: dirstr;
      name: namestr;
      ext: extstr;
      attr: word;
      f: text;
    begin
      filename := fexpand(filename);
      if filename[length(filename)] <> '\' then
        begin
          assign(f, filename);
          getfattr(f, attr);
          if (doserror = 0) and (attr and $10 > 0) then
            filename := filename + '\';
        end;
      fsplit(filename, dir, name, ext);
      if name = '' then name := '*';
      if ext = '' then ext := '.*';
      parse_filespec := dir+name+ext;
    end;

  procedure copyafile(inname, outname: string);
    var
      infile, outfile: file;
      buffer: array[1..8192] of byte;
      bytesw, bytesr: integer;
      time: longint;
      attribute: word;

    begin
      assign(infile, inname);
      getfattr(infile, attribute);
      reset(infile, 1);
      write('Copying ', inname, ' (', filesize(infile), ' bytes)...');
      assign(outfile, outname);
      setfattr(outfile, attribute);
      rewrite(outfile, 1);
      repeat
        blockread(infile, buffer, sizeof(buffer), bytesr);
        if bytesr > 0 then
          blockwrite(outfile, buffer, bytesr, bytesw);
      until bytesr = 0;
      getftime(infile, time);
      setftime(outfile, time);
      close(infile);
      close(outfile);
      writeln('done...');
    end;

  procedure writehelp;
    begin
      writeln('Provide a source and a destination.');
      halt(1);
    end;

  procedure process;
    begin
      if paramcount <> 2 then
        writehelp;
      copyafile(parse_filespec(paramstr(1)), parse_filespec(paramstr(2)));
    end;

end.
And here is the main program

program part10; uses unit10, overlay;


  {$O UNIT10.TPU}


  begin
    ovrinit('PART10.OVR');
    if OvrResult <> 0 then
      begin
        case OvrResult of
          -1: writeln('Overlay manager error.');
          -2: writeln('Overlay file not found.');
          -3: writeln('Not enough memory for Overlay Buffer.');
          -4: writeln('Overlay I/O error.');
        end;
        halt(1);
      end;
    OvrInitEMS;
    case OvrResult of
      0: writeln('Overlay loaded to EMS memory!');
     -5: writeln('No EMS driver found! Loading to conventional.');
     -6: writeln('Not enough EMS memory!');
    end;
    process;
  end.


Basically, the plan for this tutorial is to go through all standard data
types and show how TP stores them in memory, so we will be able to interpret
a binary data file we may create.  Then, using the information we presented
on how things are stored, we will get a spec sheet on a common format, and
interpret the data, so we may be able to obtain data from that file through
a Pascal program.

Byte
====
The basic idea of a byte has been covered in part 7 of the tutorial.
Please refer back to there for a refresher on the concept of what a byte is.

Basically, a byte can be used to substitute or represent a char type,
or a number type....The number types, stored as a byte, have a limit of
0..255 as an unsigned number (byte), and -128..127 with a signed number
(shortint).  The terms in the parentheses are what we would define the
byte to be to get the specified range.  I will explain later in this
tutorial the difference between a "signed" and "unsigned" number, actually
signed and unsigned data space for numbers.

The number for an unsigned number is formed, much like we were doing the
binary computations in part 7.

Numbers as Integers
===================
There are several types of numbers we can define...

Byte, and ShortInt: as described above in the byte description...

Integer types are either as signed (range: -32768..32767) or unsigned
(0..65535) words.  A word is a unit of 2 bytes in TP.  Basically, in
a unsigned integer, the number is calculated from right to left in binary
much like a byte.  Since it is easier, for us to show binary storage
repsentation as hexadecimal units of bytes, we will use hexadecimal values
for an example.

An integer type is written to disk, to test something.  The sequence of
two bytes is:  3F 4D  .  What is the number in base 10 form?

If we remember from our hex notation, and the way things work:

   3 * 16^3 + 15 * 16^2 + 4 * 16^1 + 13 * 16^0 = 16205

An integer is ALWAYS two bytes, whether or not the number may technically
fill two bytes in this manner described before.  For example, 13 in base
10 is stored in memory and on disk by TP in integer form as 00 0D .  We
could equally store this number as a byte if we knew that this variable
location would never be requested to hold a number that is greater than
255.  For example, if we knew we were going to hold days of the month
in memory, we would never have a number greater than 31, so a byte type
for this number would be appropriate.

A longint type is always a signed number, but we do need to know, that
it is what is called a double word, or two words put together.  Therefore,
we know that a longint type is 4 bytes, and has a maximum limit of 2bil.
A longint is ALWAYS 4 bytes, whether or not the number may fill 4 bytes.
13 in base 10 would be stored in a longint as 00 00 00 0D .

Char
====
A character is stored in memory as a byte, with the byte value
representing the corresponding character as it refers to the
ASCII chart.

byte representation 67 as a char is C.

Signed vs. Unsigned Integer Numbers
===================================
We have talked before in this part about signed and unsigned numbers.  In
part 7, essentially, we have covered unsigned numbers, when we were
describing binary logic.  Let's describe what a signed number is.

A signed number is represented by either using a base system of 0..1, or
1..0 in binary.  In a signed number, the leftmost bit is either 0 for a
positive number, and 1 for a negative number.  For positive numbers, the
remaining bits are considered using a 0..1 scheme as we did in part 7
with the binary computations.  For a negative number, we count starting
from 1 and go down to 0.

Let's observe what that difference is, by demonstrating how 3 and -3 would
be shown in a shortint (signed) type in binary.

Let's start with 3 in binary as a signed number. That is a positive number
so the leftmost bit will be 0.  Then we will use a 0..1 counting system
to finish out the number using standard binary notation.  So, 3 will be
represented in a shortint value as:

                             0000     0010 

just like it was an unsigned number.  Now, lets observe what -3 would look
like.  That is a negative number, so the leftmost bit would be a 1.  Since
we use a 1..0 system, we would start with 1's in everything.  We know 3 is
10 in binary, so we use a reverse system and come up with:

                             1111     1101

To illustrate further, in binary counting (to a computer) -1..-5 would be
(represented in hex) as $FF,$FE,$FD,$FC,$FB; as opposed to $01,$02,$03,
$04,$05 for 1..5 .  In a signed system, negative number counting starts at
-1, which explains why the equal range of a shortint is -128..127, and
there are equally 128 items (positive and negative).

As practice, look at the integers.dat now, in a hex viewer, and see exactly
how the numbers are stored.  They are two bytes in length, and should count
from one to ten, as we did in the program.  It should look like this in
your hex viewer....

00 01 00 02 00 03 00 04 00 05 00 06 00 07 00 08 00 09 00 0A

I recommend very heavily that you get a hex viewer to be able to help out.

Boolean
=======
0 = False; 1 = True

Common Pascal Strings
=====================
Now we will start to discuss the format of grouped data.  The first format
we will discuss will be the common pascal string.  The format of a pascal
string formatted group of characters is the following.

When we define a string without a subscript, we are defining a maximum of
255 characters. When we define for example, a string[20], we are defining
a max of 20 characters.  In reality, we are defining the number of char-
acters + 1.  A string has a first byte (0th byte) that represents the
actual character length of the data stored in the string, as an unsigned
byte. (Actually, the length function reads this byte when you call it,
but it's also possible to read and refer to the byte, and even SET it.)

Refer back to part 8 where I said you could individually set each part
of the string.  It's possible to actually build a string by setting the
length byte, then setting the rest of the string as characters.  Say,
to set the dynamic length of a string to 4, we can do this, as in this
example, which will only write "Hello" instead of "Hello world!".  We
are setting the 0'th part of the string as a character, which we need
to do:

program test; 
  var
    p: string;
  begin
    p := 'Hello world!';
    p[0] := #5;
    writeln(p);
  end.

Blocked Character Strings
=========================
It's also possible to work with an array of characters as a string, by
referring to the whole array.  The maximum length must be set by the
length of the array, essentially.

str: array[1..20] of char;

if we read this structure in as a whole, it will have 20 characters in it,
in which we can write back out to the screen by saying WRITE(STR);, or
actually convert to a string by counting through to find the actual length
and then setting the length byte.

Null Terminated Strings
=======================
This is a length of characters, which are terminated by a null character,
or #0.  The strings unit is documented to work with these strings, but it's
easier to get away with simply converting it into something we can work
with through Pascal itself, if we have to do much with it.

Arrays
======
The general structure of an array was described in part 6.  It is basically
usable as a grouping of items.

Records
=======
A record is stored in memory basically as a grouping of data types.  The
record type below:

  datarecord = record
    int: integer;
    character: char;
  end;

would be stored in memory like this:

 INT CHARACTER


Now, we have described all of the pertinent items we need to know to be
able to work through a spec sheet on a common format.  Basically, data
for spec sheets are sometimes presented as the record format, in either
Pascal or C format.  We don't need to really do any work for that, but
most of the time, it will be presented in a byte by byte offset format.

Let us look at this structure file for an example.  It is of the standard
sound file called a MOD file. (you can find them anywhere, almost)  We
will cover just the header of the file for now...
-------------------------------------------------------------------------

Protracker 1.1B Song/Module Format:
 
Offset  Bytes  Description
   0     20    Songname. Remember to put trailing null bytes at the end...
 
Information for sample 1-31:
 
Offset  Bytes  Description
  20     22    Samplename for sample 1. Pad with null bytes.
  42      2    Samplelength for sample 1. Stored as number of words.
               Multiply by two to get real sample length in bytes.
  44      1    Lower four bits are the finetune value, stored as a signed
               four bit number. The upper four bits are not used, and
               should be set to zero.
               Value:  Finetune:
                 0        0
                 1       +1
                 2       +2
                 3       +3
                 4       +4
                 5       +5
                 6       +6
                 7       +7
                 8       -8
                 9       -7
                 A       -6
                 B       -5
                 C       -4
                 D       -3
                 E       -2
                 F       -1
 
  45      1    Volume for sample 1. Range is $00-$40, or 0-64 decimal.
  46      2    Repeat point for sample 1. Stored as number of words offset
               from start of sample. Multiply by two to get offset in bytes.
  48      2    Repeat Length for sample 1. Stored as number of words in
               loop. Multiply by two to get replen in bytes.
 
Information for the next 30 samples starts here. It's just like the info for
sample 1.
 
Offset  Bytes  Description
  50     30    Sample 2...
  80     30    Sample 3...
   .
   .
   .
 890     30    Sample 30...
 920     30    Sample 31...
 
Offset  Bytes  Description
 950      1    Songlength. Range is 1-128.
 951      1    Well... this little byte here is set to 127, so that old
               trackers will search through all patterns when loading.
               Noisetracker uses this byte for restart, but we don't.
 952    128    Song positions 0-127. Each hold a number from 0-63 that
               tells the tracker what pattern to play at that position.
1080      4    The four letters "M.K." - This is something Mahoney & Kaktus
               inserted when they increased the number of samples from
               15 to 31. If it's not there, the module/song uses 15 samples
               or the text has been removed to make the module harder to
               rip. Startrekker puts "FLT4" or "FLT8" there instead.
 
Source: Lars "ZAP" Hamre/Amiga Freelancers

--------------------------------------------------------------------------

Building the basic record format
================================
We will need to essentially, for any standard file, built record format(s)
for the file.  Let us start with this one.

It says above that the first 20 bytes would be a song title.  The description
best seems to define it as a null-terminated string, but we know the maximum
limit.  So, lets just call it a blocked character string of length 20.  So
we will use this description for part of our component record:

songname: array[1..20] of char;

If we read on through the file, it states data for samples 1-31.  They are
varied data, so that infers that we need to build another record format.
But for the position so far in our current record format, we will use
this, since we know that there are a group of 31 samples...we will call
our alternate record for the sample data, samplerec.

sampledata: array[1..31] of samplerec;

Alternate Sample Record
=======================
22 bytes are defined for a samplename.  Same logic for songname.  So this
unit of our sample record will be

samplename: array[1..22] of char;

The next part is a sample length defined by 2 bytes.  So, we could either
call this a word, or an integer:

samplelength: integer;

One byte for a finetune value.  Logical definition:

finetune: byte;

Volume is defined as one byte.  So...

volume: byte;

Repeat point and Repeat length are both defined as words above so...

repeatpoint: integer;
repeatlength: integer;

It is indicated above that we are done with the samples.  Therefore, our
final record format for the samples would be:

samplerec = record
  samplename: array[1..22] of char;
  samplelength: integer;
  finetune: byte;
  volume: byte;
  repeatpoint: integer;
  repeatlength: integer;
end;

Finishing the Record Format
===========================
Continuing on...

songlength is a byte.  So

songlength: byte;

A byte is defined next that seems like a filler byte.  So...

filler: byte;

The next set of 128 bytes are defined as "song positions 0-127".  Each byte
is also defined to hold a number, so lets keep to that:

positions: array[0..127] of byte;

The next 4 bytes to finish out our headers is the moduleid.  it's 4 bytes,
text, so...

id: array[1..4] of char;

Having gone through the header format for this file, we have come up with
a record we can use to read all the header data, that we would need to read
for a mod file.  Therefore, we can use a final type listing in our program
to read a mod file header of:

samplerec = record
  samplename: array[1..22] of char;
  samplelength: integer;
  finetune: byte;
  volume: byte;
  repeatpoint: integer;
  repeatlength: integer;
end;

modrecord = record
  songname: array[1..20] of char;
  sampledata: array[1..31] of samplerec;
  songlength: byte;
  filler: byte;
  positions: array[0..127] of byte;
  id: array[1..4] of char;
end;

We can use this format to gain any information we know about a file.  To
test this format, we need to write a program that pulls the information
out of a standard file, that we know, and check to see if they're identical.
For MODs, we would need to get a player, and load up the player, in order
to get data we are familiar with from the spec sheet, such as the id being
"M.K.".

All the data we need to know to extract data out, and get formatted data
from standards files, have been presented.

Practice Programming Problem #11
================================
In keeping with the topic of this tutorial, I am asking you to write a
program entirely in Pascal that will take a ZIP file name from the command-
line and then print a list of all the files within that zip file.  With
each filename, list the compressed size, uncompressed size, date, time,
and compression method, one per file.  At the end, list the total number
of files, total compressed and uncompressed size, effective compression
ratio, and write the comment. Then output this list to a file taken on
the command-line.  For example, a command-line will always be:

ZIPLIST FILENAME.ZIP OUTPUT.TXT

Be sure to design this program with any error checks you may need to perform.
Don't forget to devise a check to be sure you are dealing with a ZIP file
on the first parameter.  Here, we have gone to look at some references,
and have found the following out of a specs list:

--------A-ZIP-------------------------------
The ZIP archives are created by the PkZIP/PkUnZIP combo produced
by the PkWare company. The PkZIP programs have with LHArc and ARJ
the best compression.
The directory information is stored at the end of the archive, each local
file in the archive begins with the following header; This header can be used
to identify a ZIP file as such :
OFFSET              Count TYPE   Description
0000h                   4 char   ID='PK',03,04
0004h                   1 word   Version needed to extract archive
0006h                   1 word   General purpose bit field (bit mapped)
                                      0 - file is encrypted
                                      1 - 8K/4K sliding dictionary used
                                      2 - 3/2 Shannon-Fano trees were used
                                    3-4 - unused
                                   5-15 - used internally by ZIP
                                 Note:  Bits 1 and 2 are undefined if the
                                        compression method is other than
                                        type 6 (Imploding).
0008h                   1 word   Compression method (see table 0010)
000Ah                   1 dword  Original DOS file date/time (see table 0009)
000Eh                   1 dword  32-bit CRC of file (inverse??)
0012h                   1 dword  Compressed file size
0016h                   1 dword  Uncompressed file size
001Ah                   1 word   Length of filename
                                 ="LEN"
001Ch                   1 word   Length of extra field
                                 ="XLN"
001Eh               "LEN" char   path/filename
001Eh               "XLN" char   extra field
+"LEN"
After all the files, there comes the central directory structure.

(Table 0009)
Format of the MS-DOS time stamp (32-bit)
The MS-DOS time stamp is limited to an even count of seconds, since the
count for seconds is only 5 bits wide.

  31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16
 |<---- year-1980 --->|<- month ->|<--- day ---->|

  15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
 |<--- hour --->|<---- minute --->|<- second/2 ->|

(Table 0010)
PkZip compression types
0 - Stored / No compression
1 - Shrunk / LZW, 8K buffer, 9-13 bits with partial clearing
2 - Reduced-1 / Probalistic compression, lower 7 bits
3 - Reduced-2 / Probalistic compression, lower 6 bits
4 - Reduced-3 / Probalistic compression, lower 5 bits
5 - Reduced-4 / Probalistic compression, lower 4 bits
6 - Imploded / 2/3 Shanno-Fano trees, 4K/8K sliding dictionary
[7..9 also exist] => note added by Glenn Grotzinger from Phil Katz's
description

--- Central directory structure
The CDS is at the end of the archive and contains additional information
about the files stored within the archive.
OFFSET              Count TYPE   Description
0000h                   4 char   ID='PK',01,02
0004h                   1 byte   Version made by
0005h                   1 byte   Host OS (see table 0011)
0006h                   1 byte   Minimum version needed to extract
0007h                   1 byte   Target OS
                                 see above "Host OS"
0008h                   1 word   General purpose bit flag
                                 see above "General purpose bit flag"
000Ah                   1 word   Compression method
                                 see above "Compression method"
000Ch                   1 dword  DOS date / time of file (see table 0009)
0010h                   1 dword  32-bit CRC of file 
0014h                   1 dword  Compressed size of file
0018h                   1 dword  Uncompressed size of file
001Ch                   1 word   Length of filename
                                 ="LEN"
001Eh                   1 word   Length of extra field
                                 ="XLN"
0020h                   1 word   Length of file comment
                                 ="CMT"
0022h                   1 word   Disk number ??
0024h                   1 word   Internal file attributes (bit mapped)
                                    0 - file is apparently an ASCII/binary file
                                 1-15 - unused
0026h                   1 dword  External file attributes (OS dependent)
002Ah                   1 dword  Relative offset of local header from the
                                 start of the first disk this file appears on
002Eh               "LEN" char   Filename / path; should not contain a drive
                                 or device letter, all slashes should be forward
                                 slashes '/'.
002Eh+              "XLN" char   Extra field
+"LEN"
002Eh               "CMT" char   File comment
+"LEN"
+"XLN"

(Table 0011)
PkZip Host OS table
0 - MS-DOS and OS/2 (FAT)
1 - Amiga
2 - VMS
3 - *nix
4 - VM/CMS
5 - Atari ST
6 - OS/2 1.2 extended file sys
7 - Macintosh
8-255 - unused

--- End of central directory structure
The End of Central Directory Structure header has following format :
OFFSET              Count TYPE   Description
0000h                   4 char   ID='PK',05,06
0004h                   1 word   Number of this disk
0006h                   1 word   Number of disk with start of central directory
0008h                   1 word   Total number of file/path entries on this disk
000Ah                   1 word   Total number of entries in central dir
000Ch                   1 dword  Size of central directory
0010h                   1 dword  Offset of start of central directory relative
                                 to starting disk number
0014h                   1 word   Archive comment length
                                 ="CML"
0016h               "CML" char   Zip file comment

EXTENSION:ZIP
OCCURENCES:PC,Amiga,ST
PROGRAMS:PkZIP,WinZIP
REFERENCE:Technote.APP

Source: FILEFMTS (c) 1994,1995 Max Maischein


Sample output for this program
==============================

                       Files contained in FILENAME.ZIP

NAME         COMP-SIZE     DATE     TIME     UNCOMP-SIZE  COMP-METHOD       
---------------------------------------------------------------------
FOOBAR10.TXT       732  10-01-1993  02:30          1021       7
 FOBAR11.ZIP     11021  12-01-1995  22:03         23923       6
...
---------------------------------------------------------------------
               1520032                          4023232

15 files; Effective compression ratio: 65.3%

< write the comment here, or write "No ZIP comment." if there is no
ZIP comment >


Notes:
1) Note how I have the sample output.  It needs to be EXACTLY as I have
listed it.
2) The orders and the methods you need to use to read files should be
evident from the specs file.  They will be random reads...
3) With the random reads, it is about impossible to tell what you got
read unless you check first...Notice a good way to check out of the
first field of each record...
4) The "MS-DOS Time Format" can be done really easily.  Just think DOS
unit.
5) Do not read anything unless you HAVE to....
6) Since this is a program that happens to use another program's data,
more than likely, the data are correct, so there is no need to check
any of the data beyond determining whether it's an actual ZIP file.

With this data listed, you should be able to do anything related to listing,
stripping comments, showing comments, and so on and so forth.

Next Time
=========
We will cover the use of stacks and queues.  Send any comments,
encouragements, problems, etc, etc. to ggrotz@2sprint.net.  Haven't
seen anything of that type, ya know....

