diff options
Diffstat (limited to 'ksiders/atr.txt')
| -rw-r--r-- | ksiders/atr.txt | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/ksiders/atr.txt b/ksiders/atr.txt new file mode 100644 index 0000000..44c2b06 --- /dev/null +++ b/ksiders/atr.txt @@ -0,0 +1,521 @@ +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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
|