Search    
 

   
 

 
PRAGMA PROGRAM REFERENCE MANUAL
Index
All Operation

Expand All      ADDENDUM
DOS READ DR Standard Verb Operating System Operation
Target = IPC STATUS (IS), LENGTH (LT)

After having opened with DOS OPEN READ the text file that you want to read
from, you can read the contents of the file with the verb DOS READ.
The contents of the file will be put into the noun that is the object.
A maximum of 2 kilobytes can be read at a time. The RECEIVE TERM CHAR will
terminate reading the file. After DOS READ you must run DOS CLOSE READ.
IPC STATUS contains the result, LENGTH the number of characters received.

DOS OPEN READ filename FILENAME
DOS READ into the noun TEXT
DOS CLOSE READ

FILENAME is an expression or noun containing the name (and path) of the opera-
ting system file you want to read into the noun TEXT.

SEE ALSO: DOS OPEN READ / DOS CLOSE READ / DOS READ LAYOUT

DOS OPEN READ (DOR)
DOS READ (DR)
DOS READ LAYOUT (DRL)
DOS CLOSE READ (DCR)



DOS OPEN READ opens an operating system text file so that a DOS READ or a DOS READ LAYOUT reads all or part of that file into a noun. Only text files can be accessed, binary files not. You can open only one file at a time.

DOS READ terminates reading the file when it encounters the RECEIVE TERM CHAR specified in PRAGMA.DES, when it encounters a null (_@) or when it has read 2048 characters.

DOS READ LAYOUT terminates reading the file when it has read the number of characters specified in the layout number, when it encounters the RECEIVE TERM CHAR specified in PRAGMA.DES or if it encounters a null (_@). The layouts of DOS READ LAYOUT can be greater than 2048.

A null always terminates a read because null is a string terminator in PRAGMA (and the C language).

When DOS READ or DOS READ LAYOUT terminate because of the receive terminating character, the receive terminating character is always removed from the input data.

DOS READ and DOS READ LAYOUT will put the number of characters read into the standard noun LENGTH (LT).

After having finished reading, the operating system file must always be closed by running DOS CLOSE READ.


Every one of these verbs will write the results of the operation whether it was successful or not into the standard noun IPC STATUS (IS).

If you try to read a file and there is no more data to be read, you will get an END OF FILE message in the IPC STATUS. If any data is available, even just one byte, you will get an OK message. This allows you to read a large text file by performing various reads, as shown in the second example below.

For a list of all the possible IPC STATUS messages consult the IPC STATUS reference.


EXAMPLES


VERB called TEST DOS READ

1 DOS OPEN READ filename "TEST.TXT"
2 IF the value IPC STATUS "<>" the value "OK"
do
3 GO TO line labeled ERROR
else
end
4 DOS READ into the noun TEXT
5 IF the value IPC STATUS "<>" the value "OK"
do
6 GO TO line labeled ERROR
else
end
7 DOS CLOSE READ
8 IF the value IPC STATUS "<>" the value "OK"
do
9 GO TO line labeled ERROR
else
end
10 MOVE CURSOR DOWN the amount 1
11 DISPLAY the value TEXT
12 MOVE CURSOR DOWN the amount 1
13 DISPLAY the value LENGTH
14 RETURN
15 LABEL this line with
ERROR
16 DISPLAY the value IPC STATUS


It is important to always check the IPC STATUS since you are performing an operation on the operating system level where things are beyond the control of PRAGMA.

The verb reads a textfile TEST.TXT, which must be present in the same directory where PRAGMA is, since no path is indicated.

The whole file will be read, if the file has less than 2048 characters. If it is larger 2048 characters it will read up to 2048 characters unless it encounters a terminating character specified in RECEIVE TERM CHAR.


You can substitute line 4 with DOS READ LAYOUT, which lets you specify the number of characters that will be read. But remember that the terminating character specified in RECEIVE TERM CHAR takes precedence, and reading will be terminated upon finding that character, regardless of how many characters have been read. If you specify a number of characters larger than the file you want to read from, the IPC will contain an OK message, and the receiving noun will contain the complete file.



If you need to read a large file into a noun it is better to execute a DOS READ until the end of the file has been reached. The following example illustrates the principle:


VERB called TEST READ LONG FILE

1 COPY the value "" to the noun TEXT
2 DOS OPEN READ filename "TEST.TXT"
3 IF the value IPC STATUS "<>" the value "OK"
do
4 GO TO line labeled ERROR
else
end
5 LABEL this line with
LOOP
6 DOS READ into the noun HEAD
7 JOIN the value TEXT to the value HEAD
8 COPY the value HEAD to the noun TEXT
9 IF the value IPC STATUS "<>" the value "OK"
do
10 DOS CLOSE READ
else
11 GO TO line labeled LOOP
end
12 MOVE CURSOR DOWN the amount 1
13 DISPLAY the value TEXT
14 RETURN
15 LABEL this line with
ERROR
16 DISPLAY the value IS


In this verb DOS READ will read the file until it has read the maximum number of characters it can read and put the result into the standard noun HEAD. The contents of HEAD are then JOINed to the contents of the noun TEXT, thus always adding whatever is read to the contents of TEXT. When there is nothing left to be read the IPC STATUS contains END OF FILE rather than OK, the loop terminates, the file is closed and the program continues and the noun TEXT will be displayed.

If the receive terminating character is encountered DOS READ will stop reading, but the program will loop, and DOS READ will read again, until the receive terminating character is met again and so on, until the END OF FILE has been reached. The difference will be that the receive terminating character will have been eliminated from the contents of the noun TEXT, since the receive terminating character is always removed from the input data.

 
CustomWare® is a registered trademark of CustomWare Designs, Inc. All rights reserved.
CustomWare® is a registered servicemark of CustomWare Designs, Inc.  All rights reserved.
All images and designs on this web site are copyrighted© 2021.
v t