Action Statement

Write a textual, image, or graphical region, or a table to a file.

For Textual Regions and Tables:

write [append|destructive]

{TR_NAME|TABLE_NAME} to [colored] file FILE_NAME

For Image Regions and Graphical Regions:

write REGION_NAME to file FILE_NAME

append

Append the contents of the region to the end of the contents of the specified file. If no file with the specified name exists, a new file will be created.

destructive

Replace the contents of an existing file with the contents of the textual region. If no file with the specified name exists, a new file will be created.

TR_NAME

The identifier for a textual region.

TABLE_NAME

The identifier for a table.

colored

Write a textual region to a color-attributed file. If an uncolored textual region is written to a colored file, the file will contain color specifications based upon the background and foreground colors of the textual region. If a colored textual region is written to a colored file, the file will retain the color specifications for individual characters. This specification does not apply to tables.

file FILE_NAME

A string value representing the name, including the extension, of a file to which you want the region copied. If a colored textual region is written to an ASCII file, the color specifications for individual characters will be dropped.

REGION_NAME

The identifier for an image region or graphical region.

Description

Use this statement to perform either of the following write operations:

Write a textual region or a table to an ASCII text file or a color-attributed file.

Write an image region or graphical region to a bitmap file.

For textual regions and tables, if the file already exists (and you do not specify destructive), the operation fails and the function ioerror is set to true. For image and graphical regions, write is always destructive, replacing the contents of any existing file.

When you use write to create a file from a table, ESL writes every row in the table to the file. Files created with this statement can be read by add to table insert and by read file. See delimiter is in the table definition for further information about the formats.

None of the write statements affect the region or table in any way.

You should test the value of the built-in function ioerror after each write statement, to see if the operation was successful.

ESL only distinguishes between colored and uncolored files when you write files from textual regions.

When writing an image or graphical region, the output file is in the bitmap format (.BMP) and is a pseudo-color file. If it is color-mapped, the current color map is used.

If, for any reason, the operating system will not let ESL create, append to, or delete the specified file, the built-in function ioerror will be set to true, and an error message will be generated.

Example

 

response to char "OK" from keyboard

 write Manual_TR to file "Archive.dat"

 

response to OverwriteFile_PB

 write destructive FirstDraft_TR to file Store_SV

 

action AddText is

 write append Chapter_TR to colored file Book_SV

 if (ioerror) then

         action WarnUser

 end if

See Also

insert Drawing Statement

ioerror Action Inquiry Built-in Function

read Action Statement