READ_HEADER

Syntax

error = READ_HEADER(#channel, buffer)

Location

DJToolkit 1.16

The file that is opened on the given channel has its header data read into memory starting at the given address (buffer). The buffer address must have been reserved using RESERVE_HEAP, or some similar command.

The buffer must be at least 64 bytes long or unpredictable results will occur. The function will read the header but any memory beyond the end of the buffer will be overwritten if the buffer is too short. After a successful call to this function, the contents of the buffer will be as follows :

Address

Value

Size

Buffer + 0

File length

4 bytes long (see FILE_LENGTH)

Buffer + 4

File access

1 byte long - currently zero

Buffer + 5

File type

1 byte long (see FILE_TYPE)

Buffer + 6

File dataspace

4 bytes long (see FILE_DATASPACE)

Buffer + 10

Unused

4 bytes long

Buffer + 14

Name length

2 bytes long, size of filename

Buffer + 16

Filename

36 bytes long

Directory devices also have the following additional data :

Address

Value

Size

Buffer + 52

Update date

4 bytes long (see FILE_UPDATE)

Buffer + 56

Reference date

4 bytes long - see below

Buffer + 60

Backup date

4 bytes long (see FILE_BACKUP)

Miracle Systems hard disc’s users and level 2 users will find the files version number stored as the the 2 bytes starting at buffer + 56, the remaining 2 bytes of the reference date seem to be hex 094A or decimal 2378 which has no apparent meaning, this of course may change at some point!

This function returns an error code if something went wrong while attempting to read the file header or zero if everything went ok. It can be used as a more efficient method of finding out the details for a particular file rather than calling all the various FILE_XXX functions. Each of these functions internally call the READ_HEADER routine.

To extract data, use PEEK for byte values, PEEK_W for the filename length and version number (if level 2 drivers are present, see LEVEL2), or PEEK_L to extract 4 byte data items.

The filename can be extracted from the buffer by something like:

f$ = PEEK_STRING(buffer + 16, PEEK_W(buffer + 14)).

EXAMPLE The following example allows you to change the current dataspace requirements for an EXECutable file:

6445 DEFine PROCedure ALTER_DATASPACE
6450   LOCal base, loop, f$, ft, nv
6455   base = RESERVE_HEAP (64)
6460   IF base < 0 THEN
6465     PRINT "ERROR: " & base & ", reserving heap space."
6470     RETurn
6475   END IF
6480   REPeat loop
6485     INPUT'Enter filename:';f$
6490     IF f$ = '' THEN EXIT loop
6495     ft = FILE_TYPE(f$)
6500     IF ft < 0 THEN
6465       PRINT "ERROR: " & ft & ", reading file type for " & f$ & "."
6510     END IF
6515     IF ft <> 1 THEN
6520       PRINT f$ & 'is not an executable file!'
6525       NEXT loop
6530     END IF
6535     PRINT 'Current dataspace is:'; FILE_DATASPACE(f$)
6540     INPUT 'Enter new value:'; nv
6545     OPEN #3,f$ : fer = READ_HEADER (#3,base)
6550     IF fer < 0 : CLOSE #3 : PRINT "READ_HEADER error: " & fer : NEXT loop
6555     POKE_L base + 6,nv
6560     fer = SET_HEADER(#3,base)
6565     IF fer < 0 : PRINT "SET_HEADER error: " & fer
6570     CLOSE #3
6575   END REPeat loop
6580   RELEASE_HEAP base
6585 END DEFine ALTER_DATASPACE

CROSS-REFERENCE

SET_HEADER, FILE_LENGTH, FILE_TYPE, FILE_DATASPACE, FILE_UPDATE, FILE_BACKUP.