path: root/ksiders/atr.txt

All files Copyright 1997 Ken Siders

Ken's ATR manipulation C library.  This has only been used under Microsoft
C/C++ version 8.0.  It will probably work on 7.0 and possibly earlier
versions.  You are on your own for porting to other compilers.

With Microsoft C, you must use the /Zp option to pack structure members
on byte boundries.  I have no idea how this translates to other compilers.


To Do
1 Clean up warnings + make more portable
2 Allow opening write-protected ATRs
3 Allow more than one reference to an ATR file to be opened so more 
   than one atari file can be opened at once.
4 More specific error returns
5 Implement XFD handling
6 Create documentation
7 Optimize if necessary
8 Implement DCM images (maybe)

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

This source is a work in progress and in distributed for those wanting
to write ATR related programs.  I had planned to tidy them up a lot before
releasing them, but have been sidetracked by other projects.  Feel free to
use them in your own freeware and public domain programs if credit is given.

These have all been compiled with Microsoft C version 8.0.  They should
compile with 7.0 and possibly earlier versions.  They may need 
some tweaking for use on other compilers.  The /Zp option must be used
on the Microsoft compiler to pack structures on byte boundries.  I don't
know how this is done on other compilers.

Files:
The file that does all of the work is ATR.C.  The other programs do some
basic processing and call fucntions in ATR.C to do the work.  

The other C files, all build the ATR utilities that are on my Atari
web page.  They, of course must be linked with the main ATR file.

There are two header files: ATR.H and ATRDOS.H both of which will be
required by most programs.  ATR.H contains definitions for ATR image related
functions.  ATRDOS.H contains definitions for referencing Mydos and
Atari Dos files located on ATR images.  Hopefully the short descriptions
in the source are enough to allow one to figure out what each function does.
There is also a third header file with the Boot disk routine.


Note:  You cannot open write protected images yet and you can only have
one ATR open at a time.  If you Open an ATR and then call a function like
ATRDirectory, an error will result.  You must Close the ATR first, call
the function and then reopen the ATR.  This also means you can't have two
files open in a single ATR at the same time.  This will hopefully be
rectified soon.  Good Luck.



mailto:  ken_siders@compuserve.com
http://ourworld.compuserve.com/homepages/ken_siders/atari.htm


PS: I still am looking for info on other disk formats such as SpartaDOS.
Also info on subdirectory format, how to distinquish Dos 2.5 enhanced
density and MyDos enhanced density, etc.....

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

***********************************************************************
Structures
***********************************************************************
ATR File pointer structure definition.  Most of this info comes from
the ATR header:

struct S_AtrFile {
   FILE *atrIn;                     pointer to the file.
   unsigned long  imageSize;        image size
   unsigned short secSize;          sector size: 128/256
   unsigned long crc;               crc - ATR extension (not used)
   unsigned long sectorCount;       number of sectors in image
   byte flags;                      flags byte from ATR image.
   byte writeProtect;               image write protected?
   byte authenticated;              ATR extension (not used)
   unsigned short currentSector;    don't know what I have this here for.
   unsigned char dosType;           ataridos, mydos?  see atr.h for constants
};
typedef struct S_AtrFile AtrFile;
typedef AtrFile *AtrFilePtr; 


Atari File pointer structure definition.  This is info required to read and
write atari files in an ATR image as well as related functions.

struct S_AtariFile
   {
   AtrFilePtr atr;                  atr file is in
   unsigned short startSector;      start sector of file
   unsigned short currentSector;    current sector pointer
   unsigned short sectorSize;       sector size: 128 or 256
   unsigned short numberOfSectors;  number of sectors in file
   unsigned long fileSize ;         size of file in bytes
   byte openFlag;                   flag used in AtariOpenFile
   byte eofFlag;                    set if at eof
   short currentOffset;             current offset into sector
   short bytesData;                 bytes of data in current sector
   short sectorLinkOffset;          offset to link data.  usually 125 or 253
   short fileNo;                    file No for Atari Dos
   unsigned char sectorBuffer[256]; buffer with current sector
   };
typedef struct S_AtariFile AtariFile;
typedef AtariFile * AtariFilePtr;


***********************************************************************
Image Functions - These functions are used for low level access to
                  ATR disk images.
***********************************************************************

OpenAtr      AtrFilePtr OpenAtr(char *file )

   Description:     
       Opens an ATR image so sectors can be read or written or information
       on the image can be obtained.
     
   Parameters:
       file - the filename of the ATR.  Use the full drive and pathname if
              the file is not in the current directory.  You must add the
              .ATR extension.

   Returns:
       An ATR file pointer that is used with other functions to access the
       image's data.


CloseAtr     int CloseAtr( AtrFilePtr atr )

   Description:     
       Closes an ATR image opened with OpenATR.
    
   Parameters:
       atr - the ATR file pointer that was returned by the OpenAtr function.

   Returns:
       0 for success, 1 if an error occured.

         
ReadSector   int ReadSector(AtrFilePtr atr, unsigned short sector,
                            char *buffer)

   Description:
       Reads specified sector from the ATR file specified into buffer which
       must be big enough for the sector size of the ATR image file (128 or
       256 bytes).

   Parameters:
       atr - Atr file pointer returned from an OpenAtr function call.
       sector - Sector number to read.
       buffer - A pointer that points to a buffer large enough to hold a
            sector of data.  Usually you want this to be 256 bytes.

   Returns:
       Number of bytes read or 0 if error.


WriteSector  int WriteSector(AtrFilePtr atr, unsigned short sector,
                             char *buffer)

   Description:
       Writes specified sector from the ATR file specified from buffer
       specified. 

   Parameters:
       atr - Atr file pointer returned from an OpenAtr function call.
       sector - Sector number to write.
       buffer - A pointer that points to a buffer containing the sector
                data to write.  Usually 128 or 256 bytes.

   Returns:
       Number of bytes written or 0 if error.


CreateAtr   int CreateAtr( char *file, unsigned short sectors, 
               unsigned short sectorSize )

   Description: 
       Creates an new ATR file with parameters specified.  

   Parameters:
       file - Name of the ATR file to create.  If file exists it will
              be overwritten.
       sectors - The number of sectors in the image.  Common values are
                 720 (single/double density) or 1040 (1050 double) but
                 smaller an huge images may also be created.
       sectorSize - This should be 128 (single/1050 double density) or
                    256 (double density).

   Returns:
       0 for success, 1 on failure.


GetAtrInfo   int GetAtrInfo( AtrFilePtr atr, unsigned short *sectorSize,
                unsigned short *sectorCount, byte  *protected)

   Descriptions:
       Returns the sector size, and sector count for an image.  It also
       returns info if the disk is write protected or not.  (Write protect
       status is not fully implemented yet.)

   Parameters:
       atr - the ATR file pointer that was returned by the OpenAtr function.
       sectorSize - A pointer to a variable in which to return the sector
                    size. 
       sectorCount - A pointer to a variable in which to return the sector
                    count. 
       protected - A pointer to a variable in which to return the write
                   protect status.  1 = protected, 0 = not.  If the image
                   write protected or if the APE extension bit for write
                   protect is set, this will be 1.  Not implemented yet.

    Returns: 0 for success, 1 if error. 


AtariFindFirst  int AtariFindFirst( char *atrName, unsigned attrib,
                                    char *pattern,
                                    AtariFileInfoPtr fileInfo )
   Description:
       Finds first match for pattern and sets struct with file information.
       For those using Microsoft C compilers, this is similiar to
       _dosfindfirst.

   Parameters:
       atrName - Name of ATR image in which to look for the file.
       attrib - Not used yet.  Use 0.
       pattern - The atari file to look for.  * and ? are accepted as normal
                 atari wildcards.  Use only and 8.3 file name, no drive or
                 directory specifications.
       fileInfo - A pointer to your file info structure in which to return
                  the information.  This structure will also be use by
                  the AtariFindNext function.
        
   Returns:
        0 if a match was found.
        -1 if a match was not found.
        a positive number if an error occurred.     


AtariFindNext  int AtariFindFirst( AtariFileInfoPtr fileInfo )

   Description:
       Searches for the next match after a previous AtariFindFirst or 
       AtariFindNext.  Sets struct with file information.  For those using
       Microsoft C compilers, this is similiar to _dosfindnext.  The
       fileInfo structure should not be modified prior to calling this
       function.

   Parameters:
       fileInfo - A pointer to your file info structure in which to return
                  the information.  This structure should still have
                  unmodified info from the last AtariFindFirst or 
                  AtariFindNext function call.
        
   Returns:
        0 if a match was found.
        -1 if a match was not found.
        a positive number if an error occurred.     
        
CreateBootAtr - int CreateBootAtr( char *atrName, char *fileName)

   Description:
        Will create a minimally sized bootable ATR image from an Atari
        Executable.  The ATR file will be just long enough to hold
        three boot sectors and the file's data.  The executable must
        consist of only one file and not need DOS for any reason.  Note:
        Not all Atari computer and peripheral emulators may support
        non-standard sized images.  When booting from the image, the
        screen will turn red if an error occurs. 

   Parameters:     
        atrName - The ATR file name.
        fileName - The name of the MSDOS file to convert.
         
   Returns:
        0 for success.


ExtractExeFromBootAtr - long ExtractExeFromBootAtr( char *atrName,
                        char *fileName)

   Description:
        Undoes a CreateBootAtr by extracting the original executable from
        the ATR image.

   Parameters:     
        atrName - ATR file name of a disk created with CreateBootAtr.
        fileName - The name of the MSDOS file to write the output to.
        
   Returns:
        Returns 0 for error, or file length in bytes of file extracted.
        An error will result if the file was not created with CreateBootAtr.


***********************************************************************
Dos Functions - These functions are used to reference atari files 
                stored on ATR disk images.
***********************************************************************

OpenAtariFile - AtariFilePtr OpenAtariFile( char *atrName, char *fileName,
                                            byte mode)

   Description:
       Opens file in an ATR image in the mode specified: ATARI_OPEN_READ,
       ATARI_OPEN_WRITE, or ATARI_OPEN_DIR.  ATARI_OPEN_DIR is not supported
       yet.

   Parameters:
       atrName - Name of ATR image in which to look for the file.
       fileName - Filename of the atari file in the ATR image to open.              
       mode - ATARI_OPEN_READ to open the file for read, ATARI_OPEN_WRITE
              to open it for write.  "Or" the two together for both.
              ATARI_OPEN_DIR is not implemented yet.

   Returns:
        An Atari file pointer that can be used in functions to read or
        write from the file.  NULL is returned on error.


ReadAtariFile  - long ReadAtariFile( AtariFilePtr atFile, char *buffer,
                                     long bytes )

   Description:
        Reads bytes bytes from an open atari file (opened with OpenAtariFile).

   Parameters:     
   atFile - An Atari file pointer that was set from an OpenAtariFile function
            call
   buffer - A pointer to a buffer to read the bytes into.  Must be big 
            enough to hold the number of bytes requested.
   bytes - Number of bytes to read.
     
   Returns:
        Number of bytes actually read.  May be less than bytes if EOF was
        reached.  You can use EofAtariFile to see if the EOF was reached
        or if an error occurred.


CloseAtariFile - int CloseAtariFile( AtariFilePtr atFile )

   Description:
        Closes an atari file opened with OpenAtariFile.

   Parameters:
        atFile - An atari file pointer used in an OpenAtariFile function
                 call.

   Returns:
        0 if successful.
        

EofAtariuFile - int EofAtariFile( AtariFilePtr atFile )

   Description:
        Determines if pointer is at the end of an atari file.

   Parameters:
        atFile - An atari file pointer returned from an OpenAtariFile
                 function call.

   Returns:
        Returns 1 if at EOF of atari file, 0 if not 


AtariDirectory - int AtariDirectory( char *atrName, char *pattern)

   Description:
        Displays atari directory of disk image to screen.  The disk image
        must be Atari Dos, MyDos, or compatable.

   Parameters:
        atrName - The ATR file name.
        pattern - filename mask to use.  use "*.*" for all files.
        
   Returns:
        0 for no errors.


AtariFileSize long AtariFileSize( char *atrFile, char *fileName )

   Description:
        Get the actual length in bytes of an atari file in an ATR image.

   Parameters:     
        atrName - The ATR file name.
        fileName - The atari filename in 8.3 to look for.  No wildcards.

   Returns:
        Length of file in bytes or -1 for error.


ExtractAtariFile - int ExtractAtariFile( char *atrFile, char *fileName,
                                       char *dosPath )

   Description:
        Extracts an Atari file from an ATR image.  Atari Dos and MyDos
        formats are supported for the image.
     
   Parameters:     
        atrName - The ATR file name.
        fileName - Atari filename in 8.3 format.  Wildcards * and ? are
                   allowed.  If verbose is on, files will be displayed
                   as they are extracted.
        dosPath - Directory to store the file in.  File is stored with same
                  name in dosPath directory.  (don't add the trailing '\').
                  Use NULL for dosPath to extract to current directory.

   Returns:
        number of file extracted.  If the result is negative, an error 
        occured but the Absolute value of that number of files were
        extracted successfully before the error occurred.


FixAtariFileNo - int FixAtariFileNo( char *atrName, char *fileName,
                 int fileNo )
        
   Description - For atari dos, will fix the file no in each sector within
                 the file.  Used internally after a directory is sorted but
                 their may be other uses.  For larger MyDos disks the 
                 function has no effect.  I currently don't know how to
                 distinquish DOS 2.5 1050 double density disks and Mydos
                 disks so this may not work on Dos 2.5 1050 double density
                 disks.

   Parameters:     
        atrName - The ATR file name.
        fileName - Atari filename in 8.3 format to fix.  No wildcard's 
                   allowed.
        fileNo - File number to give the file.  This could probably be
                 made to be automatic.  
         
   Returns:
        0 for success.


SortAtariDir - int SortAtariDir( char *atrName )

   Description:
        Sorts the files in an ATR image.  BUT: 1. May not work on Dos 2.5
        1050 double density disks.  2.  Doesn't allow DOS.SYS and DUP.SYS,
        or other files to be specified not to be sorted.  

   Parameters:     
        atrName - The ATR file name.
         
   Returns:
        0 for success.



***********************************************************************
Other Functions - Other functions.
***********************************************************************


SetVerbose    int SetVerbose( int verb )

   Description:     
       Used to set verbose flag to 1 (on) or 0 (off).  Currently the only
       function that uses this is ExtractAtariFile.

   Parameters:
       verb - 1 for verbose, 0 for not verbose

   Returns:
       Previous state of verbose flag.