CP/M/CPM_CDROM.iso/cpm/utils/dskutl/swp-ms10.ark/TRAMDF.DOC

Text File | 1989-09-27 | 24KB | 586 lines

TraMDF : TRAnsfer_Msdos_Disk_Files


                         Transfer_Msdos_Disk_Files
                              on a CP/M host.

                                Written by
                             Wim Nelis, 199111
                              ([e-mail])


1. Introduction

Transfer_Msdos_Disk_Files, abbreviated to TraMDF, is a utility to copy
files between a CP/M disk and an MS-DOS disk on a CP/M host. It's features
are:

 - TraMDF supports all MS-DOS disk formats, which are supported by the
   hardware and the BIOS of your CP/M host.
 - TraMDF supports subdirectories on the MS-DOS disk.
 - TraMDF uses a SWEEP-like user interface.
 - TraMDF can swap easily from one CP/M user area to another.
 - TraMDF optionally copies the file attributes, from MS-DOS to CP/M as
   well as in the opposite direction.
 - TraMDF performs extensive error checking and error handling.
 - TraMDF can determine the actual end-of-file position of CP/M text files.
 - TraMDF can handle files of up to 4 MegaBytes each.
 - TraMDF is written entirely in Turbo Pascal 3.0

In order to run TraMDF you need to have:
 - CP/M version 2.2 or later,
 - a TPA size of 40 KByte or more,
 - the Turbo Pascal 3.0 compiler,
 - a BIOS which can read/write MS-DOS disk sectors (see chapter 3.1 for an
   explanation)  and optionally,
 - a way to retrieve the current position of the cursor.


2. Usage of TraMDF

TraMDF is a utility to copy files between an MS-DOS disk and a CP/M disk.
It incorporates a 'file manager', with a SWEEP-like user interface, as well
as a 'parameter manager' with a simple menu interface to set various
parameters. The next chapters explain how to use TraMDF once it is
installed properly.

2.1 Invokation

TraMDF does not expect any arguments to be passed at the invokation. All
parameters can be set and viewed within TraMDF, using the parameter
manager.

Upon startup, TraMDF will enter the parameter manager. When you leave it
using the Quit command, the file manager is entered.

2.2 Parameter manager

The parameter manager uses a menu driven interface to display and to modify
the values of the parameters. For all parameters a default value is
defined; the default value of the (name of the) MS-DOS disk drive is
'undefined' however.


                                  - 1 -

TraMDF : TRAnsfer_Msdos_Disk_Files



Note: when leaving the parameter manager, the MS-DOS drive MUST be defined:
the file manager assumes that the MS-DOS drive is usable.

In the next paragraphs, the commands of the parameter manager are described
in alphabetical order.

 A Specify the options to be used in copying files from CP/M to MS-DOS.
   This command will display another menu. The commands in this menu are,
   in alphabetical order:
    C Select whether file attributes are copied or not. Note that all files
      created on the MS-DOS disk will have the Archive attribute set.
    F Set the type of files to be copied. The type will circulate between
      three values: Text, Binary and AskUser. In the latter case for each
      file to be copied the actual file type will be asked.
    P Specify the padding character of the last cluster. This 'character'
      must be specified as a hexadecimal number.
    Q Quit, that is return to the previous menu.

 B Specify the options to be used in copying files from MS-DOS to CP/M.
   This command will display another menu. The commands in this menu are,
   in alphabetical order:
    B Specify the padding character for a file of type Binary. This
      'character' must be specified as a hexadecimal number.
    C Select whether file attributes are copied or not. Note that only the
      attributes System, Hidden and ReadOnly can be copied: the other
      attributes are ignored.
    F Set the type of files to be copied. The type will circulate between
      three values: Text, Binary and AskUser. In the latter case for each
      file to be copied the actual file type will be asked.
    Q Quit, that is return to the previous menu.
    T Specify the padding character for a file of type Text. This
      'character' must be specified as a hexadecimal number.

 C Specify the CP/M drive and the user area to be used. The format of the
   specification is
      [<CpmDriveLetter>][<UserNumber>][:]
   If <CpmDriveLetter> is not specified, the 'default' drive at the time of
   invokation of TraMDF is used. If <UserNumber> is not specified, the
   'current' user number at the time of invokation of TraMDF is used.

 D Display the parameters of the MS-DOS disk. These parameters are read
   from the boot sector of the MS-DOS disk. If the MS-DOS disk is
   installed, the title will show the word 'current'. Otherwise, it will
   show the word 'last'.

 E Exit from program TraMDF. As it is not allowed to (re)enter the file
   manager if the MS-DOS drive is not defined and installed, this
   additional exit is needed in case the installation of the disk fails.

 M Specify the drive containing the MS-DOS disk. The MS-DOS disk is
   installed and the working directory is set to the root directory. If the
   installation of the MS-DOS disk fails, the drive name is set to '?',
   which means that the MS-DOS drive is undefined.

 Q Quit and (re)enter the file manager. However, if the is MS-DOS drive is
   undefined, 'Q' will not work.



                                  - 2 -

TraMDF : TRAnsfer_Msdos_Disk_Files


 S Specify the initial source drive. The value will flip between MS-DOS and
   CP/M. This command is analogous to the X command of the file manager.

 T Specify today's date. Initially, the date is set to the date of
   compilation of TraMDF. The date is set in all files created on the MS-
   DOS disk.


2.3 File Manager

Like SWEEP, the file manager builds a list of all files and subdirectories
each time a source is selected. Stepping through the list, an action on a
file of subdirectory can be performed with a one-letter command.

The file copy is the basic function of TraMDF. The file names and the file
formats of CP/M and MS-DOS are almost identical. Both file systems
recognise two file types: text files and binary files. Text files consists
of lines separated by two characters, a CarriageReturn and a LineFeed
character. Binary files are considered to be a (long) string of bytes. Thus
copying a file is simple as no transformations are required.

However, there is a difference between CP/M and MS-DOS: CP/M reords the
length of a file in multiples of 128 bytes while MS-DOS records the length
in mutiples of 1 byte. In other words, CP/M does not know the exact length
of a file. In (printable) text files, the (non-printable) ^Z character is
used to flag the actual end of file position. Thus if a text file is copied
from CP/M to MS-DOS the actual end of file position must be determined,
while on the other hand the ^Z must be added when copying in the reverse
direction. If a non-text file is copied from CP/M to MS-DOS, the CP/M
length is passed to MS-DOS. However, in the reverse direction the last
record of the CP/M file needs to be filled up with a padding character. The
action performed at the end of the file is determined by the parameter
FileType (which can be specified using the Z command).

In the next paragraphs, the commands of the file manager are explained one
by one in alphabetical order.

   (Space) Move to the next entry in the file list. If at the last entry of
   the list, wrap to the first entry of the list.

 B Move to the previous entry in the file list. If at the first entry in
   the list, wrap to the last entry of the list.

 C Copy the file to the destination. The destination must have been set
   already using either the L, S and/or P commands.

 D Delete the file. The user is always asked to confirm the deletion.
   Therefore, no special action is taken if the file has the attribute
   ReadOnly set.

 E Delete all the tagged files. The user is asked to confirm the deletion
   of each file.

 F Display the free disk space on both the CP/M disk and the MS-DOS disk.

 L Log in a CP/M drive to serve as either source or destination in the file
   manager commands.  The format of the specification is
      [<CpmDriveLetter>][<UserNumber>][:]


                                  - 3 -

TraMDF : TRAnsfer_Msdos_Disk_Files


   If <CpmDriveLetter> is not specified, the 'default' drive at the time of
   invokation of TraMDF is used. If <UserNumber> is not specified, the
   'current' user number at the time of invokation of TraMDF is used.

 M Copy all tagged files. Once a file is copied, it is untagged.

 P (MS-DOS only) Select the subdirectory to serve as either source or
   destination area. This command can only be used on 'files' with the
   atrribute Directory set.

 Q Exit from the file manager and from program TraMDF.

 S Specify the drive containing the MS-DOS disk. The MS-DOS disk is
   installed and the working directory is set to the root directory. If the
   installation of the MS-DOS disk fails, the drive name is set to '?',
   which means that the MS-DOS drive is undefined. In that case the Z
   command will be executed, in order to define the MS-DOS drive.

 T Tag the file and show the sum of the sizes of the tagged files. Only
   files can be tagged: if you try to tag a directory, the command is
   ignored without any error message.

 U Untag the file.

 W Tag multiple files using a wildcard mask. The normal CP/M conventions
   with regard to wild cards and ambigous file names are followed.

 X Swap source and destination area. Thus the source area becomes the
   destination area and the destination area becomes the source area.

 Z Set parameter values. Using this command, the parameter manager is
   entered. It is described in the preceeding chapter.

 ? Show a short list of the commands of the file manager.


2.4 Error messages

There are two types of errors. The first type are those errors which are
reported (and handled) by TraMDF. This type of errors is often related to
(problems with) MS-DOS disk I/O.
The second type are those errors which are reported by either CP/M (BDOS)
or the run-time system of Turbo Pascal. Typical examples of this type of
error are bugs in the TraMDF (not so many, I hope) and CP/M disk I/O
problems.

2.4.1 Errors reported by TraMDF

All the errors reported by TraMDF are non-fatal, that is the current
operation is terminated immediatly and control is returned to the file
manager or the parameter manager. If necessary, a partial file will be
deleted. The error is reported in the following format:

   Error in <Procedure_Chain> : <Error_Description>

Procedure_Chain specifies the chain of procedures and functions invoked by
the file manager or the parameter manager: the last one in the chain
detected the error. The names of the procedures and functions are


                                  - 4 -

TraMDF : TRAnsfer_Msdos_Disk_Files


abbreviated, using the first 3 characters from the verb and the first
character of each of the nouns in the full name. The table below contains
the abbreviation and the full name of all involved procedures and
functions.

   Abbreviation  FullName
   CloMF         CloseMsdosFile
   CopF          CopyFile
   CreMF         CreateMsdosFile
   DelMF         DeleteMsdosFile
   FluC          FlushCache
   GetFFE        GetFreeFatEntry
   GetNDE        GetNextDirectoryEntry
   InsMD         InstallMsdosDrive
   LocMD         LocateMsdosDirectory
   LocMF         LocateMsdosFile
   ReaC          ReadCluster
   ReaF          ReadFat
   ReaMD         ReadMsdosDirectory
   ReaMF         ReadMsdosFile
   ReaS          ReadSector
   SetCD         SetCpmDrive
   SetMD         SetMsdosDrive
   SetTD         SetTodaysDate
   WriC          WriteCluster
   WriF          WriteFat
   WriMF         WriteMsdosFile
   WriS          WriteSector

Error_Desciption specifies the type of error detected. In most cases, this
gives a clue of what to do to solve or to circumvent the problem. The
Error_Description can be:

   Disk read error
      BIOS detected an error while reading an MS-DOS sector.

   Disk write error
      BIOS detected an error while writing an MS-DOS sector.

   Can't read the boot sector
      BIOS detected an error while reading the first sector of an MS-DOS
      disk.

   Disk full
      There are no more free clusters in the FAT.

   File not found : <FileName>
      The indicated file could not be found in the directory any more,
      while it was there at the time the file list was established.

   CP/M disk write error
      The TP run-time system reported an error. A possible cause is a full
      CP/M disk.

   Illegal date : <Date>
      The format of the supplied date is not 'yyyymmdd' or the yearnumber,
      the monthnumber and/or the daynumber is/are out of range. The range
      of valid yearnumbers is [1980..2012].


                                  - 5 -

TraMDF : TRAnsfer_Msdos_Disk_Files



   Directory is full
      There are no more free entries in the directory. TraMDF is not able
      to extend the MS-DOS subdirectories (yet?).

   Illegal specification : <Drive_Name>
      The specified drive cannot be accepted, because either the drive does
      not exist or the drive is already in use in another drive
      specification.

   Incompatible drive selected : <Drive_Name>
      The specified MS-DOS drive cannot be used because it cannot read the
      MS-DOS disk. The number of heads and/or the number of cylinders of
      the drive is smaller than required to read and write the disk.

   Cluster/FAT buffer too small
      The cluster buffer or the FAT buffer is too small. Check the disk
      parameters for the required size and adapt TraMDF accordingly.

   Media descriptors don't match
      The media descriptor in the boot sector differs from the media
      descriptor in the FAT. Is it really an MS-DOS disk?

   MS-DOS drive unspecified
      Upon leaving the parameter manager, the MS-DOS drive must be
      specified and installed.

   Not enough space on destination disk
      The destination disk cannot hold the file to be copied. Free up space
      or copy to another disk.

2.4.2 Errors reported by other

All the errors from either the runtime system of Turbo Pascal or from CP/M
are fatal: the execution of the program will be terminated. There is a
small problem when terminating TraMDF: it has modified a table within BIOS
and it has modified the CP/M entry vector address (see EXTFN.UNT). Both
modifications must be undone before control is passed to CP/M.

For this purpose, TraMDF contains a small errorhandler, which restores the
BIOS table and the BDOS entry vector. However, it is found that BDOS errors
are not always catched by the TP runtime system. As a result, the
aforementioned restoration is not performed. Thus, after a BDOS error
without a TP error message, it is advisable to reboot the CP/M host.


3. Adaption of TraMDF to your CP/M system.

TraMDF needs to be changed to your CP/M system for three reasons:
 - Your BIOS must be able to address, read and write each sector on the MS-
   DOS disk. TraMDF will change the BIOS tables to achieve this goal using
   system dependent extensions.
 - The disk drive configuration of your CP/M system must be known to
   TraMDF.
 - (Optional) Knowledge of the screen size and the location of the cursor
   results in a somewhat nicer screen layout.

In the following chapters, the modifications are described one by one. The


                                  - 6 -

TraMDF : TRAnsfer_Msdos_Disk_Files


first step is to determine if it is possible to get YraMDF working on your
CP/M host.

3.1. Check if your BIOS can read/write MS-DOS floppy disks.

Your BIOS must be able to perform two functions. The first function is to
read and write sectors of 512 bytes. In some CP/M systems, like mine, the
physical sector size is just a parameter in the extension of the DPB. On
other systems, the physical sector size is hardcoded into BIOS: if you have
one of those systems, check if it can support 512 byte sectors.

The second function to be performed by your BIOS is to address each sector
on the MS-DOS floppy disk in the correct sequence. The addressing of the
sectors is a two-step proces. Within TraMDF, a sector is addressed only by
a (logical) sector ordinal: sector 0 is the boot sector, while sector 719
is the last sector of a 360 kByte floppy disk. In the procedures ReadSector
and WriteSector, the logical sector ordinal is mapped onto the address
required by BIOS. It consists of two numbers, the logical track number and
the record (= CP/M 128 byte sector) number. Within your BIOS this address
is effectivly mapped onto a physical address, which consists of four
numbers: the cylinder ordinal C, the head ordinal H, the physical track
number T and the physical sector number S.

The sequence of the two mappings should map logical sector 0, the boot
sector, onto physical address C0H0T0S1 and, for a disk with 9 sectors per
track, it should map logical sector 9 onto either physical address C1H0T1S1
for a single sided disk or C0H1T0S1 for a double sided disk.

ONLY IF YOUR BIOS IS ABLE TO PERFORM THE TWO FUNCTIONS DESCRIBED ABOVE, IT
IS POSSIBLE TO INSTALL TraMDF ON YOUR SYSTEM!


3.2  Change TraMDF for MS-DOS disk I/O

In the following paragraphs, the modifications to be able to perform MS-DOS
disk I/O are described.

3.2.1  Disk Paramater Block (DPB)

Change the definition of the DPB (TRAMDF.IF0) to reflect the format of the
DPB in your system. The default DPB consists of the fields SPT through OFF;
all the other fields are specific to Aster CT-80 BIOS. The constant
SkeletDPB (TRAMDF.IF0) needs to be modified accordingly. Don't forget to
change the address computation in procedure DetermineDriveAttributes
(TRAMDF.PAS).

3.2.2  Procedure DetermineDriveAttributes

Change procedure DetermineDriveAttributes (TRAMDF.PAS). This procedure must
determine the disk drive configuration of your system. It leaves
information in the following variables:
     ConfiguredDrives : The set of drives which can be used for CP/M files.
                        Normally this set will contain all your drives.
     FloppyDrives     : The set of drives which can be used for MS-DOS
                        files. The drives in this set will be floppy disk
                        drives.
     DriveAttribute   : Some physical attributes of each of the drives in
                        the set ConfiguredDrives and the address of the DPB


                                  - 7 -

TraMDF : TRAnsfer_Msdos_Disk_Files


                        for that drive.
You can extract some information from BIOS but often it is necessary to
hardcode the configuration information into this procedure.

The field DevAddress in record DriveAttribute needs some explanation. The
BIOS of the Aster CT-80 allows one to assign two logical drives to one
physical drive. However, it does not prevent you from using the two logical
drives simultaneously, giving undesired results. Therefore, TraMDF checks
the physical drive address too, in order to avoid the MS-DOS drive and the
CP/M drive to be assigned to the same physical drive, in spite of being
assigned to different logical drives. If your BIOS does not have this kind
of problems, you can inactivate effectivly these test by assigning the
logical drive address (0 for A:, 1 for B:, etc.) to the physical drive
address in procedure DetermineDriveAttributes.

3.2.3  Procedure InstallMsdosDrive

Change procedure InstallMsdosDrive (TRAMDF.IF5). It modifies in two steps
the DPB in BIOS according to the format of the MS-DOS disk. In the first
step, the characteristics of the MS-DOS disk are not yet known. In this
step BIOS is prepared to read the bootsector, which contains a table with
the disk format characteristics. In the second step the DPB is modified to
reflect the format of the disk. It involves three fields in the standard
DPB: SPT, BLM and OFF. Field SPT contains the size of a logical track. This
is either the size of a physical track or the size of a physical cylinder.
This depends on the address mapping performed by your BIOS. Field BLM
contains the size of a physical sector expressed as the number of CP/M
records in one sector minus one. (Perhaps field BSH must be set
accordingly.) Field OFF should be set to zero. The other fields in the
standard DPB are most probably not important.

3.2.4  Address mapping

Change procedures ReadSector and WriteSector (TRAMDF.IF1). They must map
the logical sector ordinal onto the CP/M address, a logical track number
and a record ordinal, in such a way that BIOS will translate the CP/M
address to the correct physical disk address. Using the documentation of
BIOS and through some experiments, you can determine the required mapping.

At this point I can only give you some hints:
 - The logical track can be identified with either a physical track or, in
   case of a double sided disk, with a cylinder. In field SPT in the DPB
   the size of the logical track is specified.
 - The physical sector number of the first sector on an MS-DOS track is
   always 1. If record ordinal 0 is mapped on sector number 0, adding
   RecordsPerSector to the record ordinal will result in a mapping onto
   sector number 1.
 - Perhaps invokations of the BIOS function to translate the record address
   are needed.


3.3  Change TraMDF for nicer displays

In the file manager, stepping through the list of files will cause the
header to scroll from the screen. It is somewhat nicer if those header
lines are not scrolled. On some hosts, it is possible to define the
scrolling region. However, for hosts which do not support such a feature,
but which can supply the current position of the cursor, TraMDF can


                                  - 8 -

TraMDF : TRAnsfer_Msdos_Disk_Files


simulate this behaviour using an output filter. Currently the code to do so
is inactive as it is embedded within comment delimiters.

For the output filter to work, it is necessary that TraMDF can retrieve the
current position of the cursor and that the predefined TP procedures
GotoXY, DelLine and InsLine are properly functioning. The following actions
are needed to activate the output filter:

 - In CONSOLE.UNT the procedures GetMaxX and GetMaxY need to be defined.
   There are already some skeleton procedures available in this 'unit'.
   Moreover, the integer functions WhereX and WhereY must be defined: they
   deliver the X and the Y coordinate of the cursor.
 - In WINDOW.UNT the procedure WindowConOut, which is the implementation of
   the output filter, needs to be adjusted to the behaviour of your console
   device. If the cursor moves to the next line after a character is
   written on the right-most character position of a line, the code to
   handle this case in procedure WindowConOut must be changed.
 - In TRAMDF.PAS the inclusion of file WINDOW.UNT must be uncommented, as
   well as the invokation of procedure InitWindowUnit at the beginning of
   the main program.
 - In TRAMDF.IF6 the invokation of the procedures EnableWindow, SetWindow
   and DisableWindow in procedure EnterFileManager must be uncommented.

4. Epilogue

I hope you will have fun using TraMDF. If you have any comments, bug
reports or suggestions, please send them to me written in either Dutch or
English.

 Postal address : Wim Nelis
                  Rozenhof 4
                  8316 CX  Marknesse
                  The Netherlands

 E-mail address : [e-mail]

























                                  - 9 -