From 67344d6ecc255a8e5594bfab19685e223d18b207 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 10 May 2024 19:55:33 -0400 Subject: atr.txt: convert to *nix line endings. --- ksiders/README.txt | 10 +- ksiders/atr.txt | 1042 ++++++++++++++++++++++++++-------------------------- 2 files changed, 526 insertions(+), 526 deletions(-) (limited to 'ksiders') diff --git a/ksiders/README.txt b/ksiders/README.txt index b6c5934..0deba31 100644 --- a/ksiders/README.txt +++ b/ksiders/README.txt @@ -3,12 +3,12 @@ This is a quick & dirty Linux/UNIX port of Ken Siders' old Atr Utils package for MS-DOS. The original MS-DOS sources can be found in the file atrsrc.zip, or -you can download them from Ken's page: - http://atari.ksiders.tzo.com/a8emulators.html +you can download them from archive.org's copy of Ken's old page: + http://web.archive.org/web/20080430184935/http://atari.ksiders.tzo.com/a8emulators.html -Please do NOT contact Ken Siders about bugs or issues with these ported -and modified versions of his utilities. They are provided as-is, by me, -B. Watson (urchlay at urchlay dot com). +Sadly, Ken Siders is no longer with us. + +This collection is provided as-is, by me, B. Watson . The utilities are: diff --git a/ksiders/atr.txt b/ksiders/atr.txt index 44c2b06..3e5a614 100644 --- a/ksiders/atr.txt +++ b/ksiders/atr.txt @@ -1,521 +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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3