Read From a DOS File

From CometWiki

Latest revision as of 10:30, 13 June 2009

Read from a DOS File

Syntax:

 DOSRW(AX-value, file-handle, number-of-bytes, format-statement-label) EXCP=statement-label  

Entry:

 AX-value = "@3F00@"
                                                                                                                           .
 file-handle = file handle established when the file was opened
                                                                                                                           .
 number-of-bytes = number of characters to be read
                                                                                                                           .
 format-statement-label = format statement to be used to receive incoming data from DOS file

Return:
If the read function is successful, the data variable(s) contained in the format statement will contain the data from the DOS file, and the AX register will contain the number of bytes that were actually read in hexidecimal.

If an exception occurs, byte 2 of the AX field will contain the DOS error code (in hex).

Discussion:
The DOSRW function can be used to read data from a DOS file. The data is received into a variable or multiple variables listed in an Internet Basic format statement.
This function requires that the AX-value be set to "@3F00@". The file's handle (established when the file was opened) must also be included in this function call. Likewise, you must specify the number of bytes to be read from the DOS file and the label of the format statement that will receive the incoming data.

After the function is executed, the data variable(s) contained in the format statement will contain the data read from the DOS file (assuming there was any data in the file). Also, the AX register will contain the number of bytes that were actually read from the file. This value is in hex, so it will have to be converted to decimal to serve any meaningful purpose.

One application of this AX value is to test for the "end of file." For example, if the number of bytes actually read from a DOS file equals 0, that means that there is no more data to read (i.e., the end of file).

Example:

 ! S SFREAD,DSK
 ! O FREAD,DSK
 ! L T00,E
 ! R QMONITOR
 !
 !==========  READ FROM A DOS FILE  ==============================
 !
 LENGTH 2 & LOCAL AX$,BX$,CX$,DX$        ! Define registers
            LOCAL FILEHANDLE$            ! Define file handle
 LENGTH 64 & LOCAL FILENAME$             ! Define file name
 LENGTH 4.0 & LOCAL BYTES                ! Define byte counter
 !
 LENGTH 100 & LOCAL DATASTRING$          ! Define data string
 !
 LENGTH 3 & LOCAL DOSCODE$               ! Define DOS error code
 LENGTH 37 & LOCAL DOSMESSAGE$           ! Define DOS message
 !
 1000 FORMAT DOSMESSAGE$                 ! File input format
 !
 100 FORMAT (ET)                         ! Screen format
 !
 9999 FORMAT DATASTRING$                 ! DOS file input format
 !
 CLEAR                                   ! Initialize variables
 PRINT (0,100)                           ! Set typewriter mode
 !
 PRINT (0) "NAME OF DOS FILE TO OPEN:"   ! Display prompt
 INPUT (0) FILENAME$                     ! Enter file name
 IF FILENAME$ = "" THEN RUN "QMONITOR"   ! If null, then stop
 !
 AX$ = "@3D42@"                          ! Set AX to "OPEN FILE"
 CX$ = "@0000@"                          ! Set CX to null
 !
 DOSFC(AX$,CX$,FILENAME$) EXCP=EXCEPTION ! Perform DOSFC call
 !
 FILEHANDLE$ = AX$                       ! Store the file handle
 !
 READ:                                   ! Start of read loop
 AX$ = "@3F00@"                          ! Set AX to "READ"
 !
 DOSRW(AX$,FILEHANDLE$,100,9999) EXCP=EXCEPTION   ! Read 100 bytes
 !
 BYTES = HEXDEC(AX$)                     ! Convert AX to decimal
 IF BYTES = 0 THEN GOTO BOTTOM           ! Check for end-of-file
 !
 PRINT (0) DATASTRING$                   ! Display data from file
 !
 GOTO READ                               ! Loop back
 !
 EXCEPTION:                              ! Exception routine
 PRINT (0) "DOS ERROR DURING READ"       ! Display message
 OPEN (1) "QERCOMET"                     ! Open error file
 DOSCODE$ = "D" + HEXASC(SUB(AX$,2,1))   ! Construct key to file
 READ (1,1000) KEY=DOSCODE$              ! Read error record
 PRINT (0) "DOS error code: ";DOSCODE$   ! Display DOS error code
 PRINT (0) DOSMESSAGE$                   ! Display error message
 INPUT (0) ""                            ! Hold
 CLOSE (1)                               ! Close error file
 RUN "QMONITOR"                          ! Exit
 !
 BOTTOM: AX$ = "@3E00@"                  ! Set AX to "CLOSE FILE"
        BX$ = FILEHANDLE$               ! Set BX to file handle
        CX$ = "@0000@"                  ! Set CX to null
        DX$ = "@0000@"                  ! Set DX to null
        DOSMS(AX$,BX$,CX$,DX$)          ! Perform DOSMS call
        RUN "QMONITOR"                  ! Exit
 END

DOS function calls/pseudo calls