aboutsummaryrefslogtreecommitdiff
path: root/ksiders/atr.txt
blob: 3e5a614de83db471ddf147673bb2fc21988403e2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
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.