Search    
 

   
 

 
PRAGMA PROGRAM REFERENCE MANUAL
Index
All Operation

Expand All      ADDENDUM
DOS WRITE DW Standard Verb Operating System Operation
Target = IPC STATUS (IS)

After having opened with DOS OPEN APPEND or DOS OPEN CREATE an operating sys-
tem file, you can write to the file with the verb DOS WRITE.
After having finished writing to the file you must then close it with the verb
DOS CLOSE WRITE.

The noun IPC STATUS contains the result of the operation DOS WRITE.

DOS OPEN APPEND filename FILENAME
DOS WRITE the value TEXT
DOS CLOSE WRITE
FILENAME is an expression or noun containing the name and optional path of the
operating system file you want to write the noun or expression TEXT to.

SEE ALSO: DOS OPEN APPEND / DOS OPEN CREATE / DOS WRITE LAYOUT

DOS OPEN CREATE (DOC)
DOS OPEN APPEND (DOA)
DOS WRITE (DW)
DOS WRITE LAYOUT (DWL)
DOS CLOSE WRITE


DOS OPEN CREATE creates and opens an operating system text file so that a DOS WRITE or a DOS WRITE LAYOUT writes the contents of a noun to the text file. If a file with that name already exists, it will be overwritten with an empty file of the same name.

DOS OPEN APPEND opens the specified operating sytem text file so that a DOS WRITE or a DOS WRITE LAYOUT writes the contents of a noun to the text file. If the file already contains text, the new text will be appended to it. If a file with that name does not exist, it will be created.

You can open only one file at a time, either with DOS OPEN CREATE or with DOS OPEN APPEND.

DOS WRITE will write the whole contents of the noun, without a size limit to the opened file. DOS WRITE LAYOUT will write the number of characters specified in the layout.

DOS WRITE and DOS WRITE LAYOUT will also append at the end of every write the SEND TERM CHARACTER specified in PRAGMA.DES.

If SEND TERM CHARACTER is not specified in PRAGMA.DES, DOS WRITE and DOS WRITE LAYOUT will append the default character, which is a null character (_@). Be careful with the null character. The null character is a string terminator in PRAGMA (and the C language). A DOS READ will always stop when it encounters a null character. This may or may not be desirable, depending upon the format of the data in the text file being read at the time. The SEND TERM CHARACTER must be set correctly when writing the file to correspond with the data format desired. For more information please read the DOS READ reference.

If you don't want PRAGMA to append anything at the end of every write, you must specify NONE as the SEND TERM CHARACTER in PRAGMA.DES.

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


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).

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


EXAMPLES


VERB called TEST DOS WRITE

1 COPY the value "Hello World" to the noun TEXT
2 DOS OPEN CREATE filename "TEST.TXT"
3 IF the value IPC STATUS "<>" the value "OK"
do
4 GO TO line labeled ERROR
else
end
5 DOS WRITE the value TEXT
6 IF the value IPC STATUS "<>" the value "OK"
do
7 GO TO line labeled ERROR
else
end
8 DOS CLOSE WRITE
9 IF the value IPC STATUS "<>" the value "OK"
do
10 GO TO line labeled ERROR
else
end
11 RETURN
12 LABEL this line with
ERROR
13 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 creates a textfile TEST.TXT in the same directory where PRAGMA is, since no path is indicated. If the file TEST.TXT already exists, it will be overwritten and all it's contents will be lost. To avoid overwriting an existing file you can check if the file already exists with the verb DOS EXIST (DE).

The contents of the noun TEXT ("Hello World") will be written to the file TEST.TXT. At the end of the write the character specified in SEND TERM CHARACTER will be appended to the file, unless the character specified in SEND TERM CHARACTER is NONE, in which case nothing will be appended to the file following the the contents of the noun TEXT.


To append to an existing file you substitute in line two the verb DOS OPEN CREATE with the verb DOS OPEN APPEND. Every time you will then run the verb you will be appending the contents of the noun TEXT to the file TEST.TXT. Everything else will remain the same.


You can use the verb TEST DOS READ, shown in the reference of the verb DOS READ (DR), to see what you wrote with the verb TEST DOS WRITE.

 
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