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.