Read From a DOS File - Revision history

Badge at 10:30, 13 June 2009

2009-06-13T10:30:36Z

← Older revision		Revision as of 10:30, 13 June 2009
Line 14:		Line 14:


-	'''Return:'''	+	'''Return:''' <br>
	If the read function is successful, the data variable(s) contained in the format statement will contain the data from the		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.		DOS file, and the AX register will contain the number of bytes that were actually read in hexidecimal.

Badge at 10:30, 13 June 2009

2009-06-13T10:30:09Z

← Older revision		Revision as of 10:30, 13 June 2009
Line 1:		Line 1:
	'''Read from a DOS File'''		'''Read from a DOS File'''
-	~~'''Syntax:''' DOSRW(AX-value, file-handle, number-of-bytes, format-statement-label) EXCP=statement-label~~
-	~~'''Entry:''' AX-value = "@3F00@"~~

		+	'''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		file-handle = file handle established when the file was opened
-		+	.
	number-of-bytes = number of characters to be read		number-of-bytes = number of characters to be read
-		+	.
-	format-statement-label = format statement to be used to receive	+	format-statement-label = format statement to be used to receive incoming data from DOS file
-	incoming data from DOS file	+


-	'''Return:''' If the read function is successful, the data variable(s)	+	'''Return:'''
-	contained in the format statement will contain the data from the	+	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	+	DOS file, and the AX register will contain the number of bytes that were actually read in hexidecimal.
-	that were actually read in hexidecimal.	+

-	If an exception occurs, byte 2 of the AX field will contain the	+	If an exception occurs, byte 2 of the AX field will contain the DOS error code (in hex).
-	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.	+	'''Discussion:'''<br>
		+	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. <br>
	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.		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.

Badge: New page: '''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 = ...

2009-06-13T10:25:02Z

New page: '''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 = ...

New page

'''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