FWrite

Description: This function writes ASCII or binary data to a file and may also be used to create or delete a file. It returns the number of data items not written.

Returns: Numeric

Usage: Script

Format: FWrite([N, ] FileSpec, Mode, Position, Format, V1[, V2, V3, ...])

Parameters: N { numeric } { optional } { no default: }

An optional parameter for backward compatibility. If used it must be a constant non-zero decimal number that specifies the exact number of additional Vn parameters.

FileSpec { text } { required } { no default: }

Specifies any output file or printer as the destination to which to write. When specifying a printer, FileSpec will accept any of the following:

* Local Printer:

* Port name (including virtual ports) with or without a trailing colon (e.g. DEF or DEF:; COM1 or COM1:; USB001 or USB001:; etc.)

* Windows printer share (e.g. "XYZ Laser Printer")

* Windows share name (if the printer is shared) (e.g. "XYZLaser")

* Local or Remote Printer:

* UNC share name (which includes the host and share name (e.g. "\\localhost\XYlaser" or "\\lab1\NetPrinter")

Mode { numeric } { required } { no default: }

Any numeric expression giving the method of opening the file as shown: (further detail follows the table)

Mode	Method of opening
0	Overwrite old data at specified position (other data unaffected)
1	Clear existing data before using file (all data lost)
2	Append data to end of file (other data unaffected)
3	Delete file (all data lost)
4	Open specifically for printer output
5	Print mode, DC-based

If the file does not exist, it will be created if a mode of 0, 1, or 2 is used.

In the case of Mode 2, the Position parameter is ignored. If a position past the end of file is specified, the file will be extended to include the new information. If the file is extended, any information not specified by the Fwrite (such as a gap between the old end of file and the present Fwrite position) will be a string of unknown, random characters (bytes).

In the case of Mode 3, the remaining parameters in Fwrite are ignored, but must be present and valid.

In the case of Mode 4, special handling and error checking for printer output will be provided.

Position { numeric } { required } { no default: }

Any numeric expression giving the byte offset (number of characters) from the start of the file, where data is to be written. This parameter is ignored for Modes 1 - 3 but must be a valid value for all modes. It must be greater than or equal to 0. The start of the file is at Position 0.

Format { text } { required } { no default: }

Any text expression giving the format of how the values (Vn parameters) are to be written to the stream. This format is similar, but not identical, to the C language format string for the printf function, whereby each of the Vn parameters in the FWrite statement is assigned to a % format specification in the order in which each appears in the list. Note that like a standard text string, these format specifiers must also be enclosed by double quotes. If a format specification appears for which there are no remaining V parameters, the format specification characters themselves are output to the stream exactly as they appear in the Format. For the % format specifications, the following form applies (where the [ ] indicates optional elements):

%[ - ][ + ][ SPACE ][ #][ width ][ .precision ]type

The % is mandatory;

The – causes the data to be left-justified within the field. For binary types b and ASCII character types c, this option is ignored;

The + causes positive numbers to be prefaced with a + sign (negative numbers are unaffected). This allows easy alignment of positive and negative numbers in a printed column. For binary types b and non-numerical types, this option is ignored;

Space represents the single space character, and is similar to the + option, but places a single space, rather than a plus sign, in front of positive numbers (negative numbers are still unaffected). This allows alignment of a column of numbers without having to show all signs. For binary types b and non-numerical types, this option is ignored;

# When used with the o , x , or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.

width is a number that specifies the minimum number of characters to output. Numbers that require more characters than specified by the width value are truncated on output. If the number of characters in the number or string is less than width, blanks will be added to the left or right, depending upon whether the output is left or right justified (i.e. whether or not the [-] option has been specified) until the width is reached. For binary types b and ASCII character types c, this option is ignored.

precision has a different meaning for each of the type options as follows:

Integer types d, i, u, o, x, and X: precision specifies the minimum number of digits to output. If the number contains fewer digits, leading zeros will be added to the left of the number. If precision is 0, omitted, or if the decimal point appears without a number following it, the precision defaults to 1. The number is never truncated.

Floating point types e and E: precision specifies the number of digits after the decimal point. The last digit is rounded. The default precision in this case is 6. If the precision is 0, or if the decimal point appears without a number following it, no decimal point appears in the output.

Floating point type f: precision specifies the number of digits after the decimal point. The last digit is rounded. the default precision is 0. If the precision is explicitly 0, no decimal point is output. If a decimal point is output, at least one digit will be placed before the decimal point.

Floating point types g and G: precision specifies the maximum number of significant digits to be output. If no precision is specified, all significant digits are written.

String type s: precision specifies the maximum number of characters of the string to be output. If the string contains more characters than specified by the precision, the string is truncated, and only the first characters are written. If the precision is not specified, all of the string characters are output (up to the default buffer size of 256 characters, unless Width has been declared to be larger.

ASCII character type c: This option is ignored.

Binary type b: This option is ignored.

type is mandatory. This specification must be one of those listed below; note that the case of the letter is important. Specifying a character for the type which is not in this list will result in all the characters following the % up to that point to be outputted exactly as they appear in the Format string.

Type

Meaning

Binary format, where n is a number indicating the type of value

Binary type b For the format specification of %nb, where n specifies the type of number, n must be a single digit from one of the following choices:

n Value	Type
0	Byte
1	Short integer (2 bytes, low byte first)
2	Long integer (4 bytes, low bytes first)
3	IEEE single precision float (4 bytes)
4	<obsolete>
5	IEEE double precision float (8 bytes)
6	<obsolete>
7	Binary unsigned short (2 bytes)

Note that the other options such as Width and precision do not apply to the b type.

Single ASCII character (byte)

This type is not representative of a single character in a string, but rather, represents single byte ASCII characters. Input values (the Vn parameter to which this format specification applies) must be integers in the range of 0 to 255 in order for the output to be a valid ASCII equivalent character. Strings are not acceptable input values. Note that the %c format specifier behaves differently when used in an output statement such as FWrite, then when used in an input statement, such as FRead.

Signed decimal integer

Signed exponential; exponent key is "e"

Signed exponential; exponent key is "E"

Signed floating point

e or f formats, whichever is shorter

E or f format, whichever is shorter

Handle to a window

This type is used for building structures to be handed to DLLs, and should be used by advanced users only.

Signed decimal integer

Unsigned octal integer

Pointer to a buffer

This type is also used for building structures to be handed to DLLs and should be used by advanced users only.

Text string (see following notes)

Unsigned decimal integer

Unsigned hex integer using "abcdef"

Unsigned hex integer using "ABCDEF"

Text string type s The buffer size for the Format parameter defaults (and is therefore limited) to 256 characters but may be explicitly declared larger by using the width option.

Plain text Text in the Format parameter is written exactly as it appears, with three exceptions:

• Percentage sign (%): Since format specifications for the Vn parameters are indicated by a percentage sign, to include an actual percentage sign as part of the Format parameter, precede it with a backslash character (i.e. \%).

• Backslash character (\): Since this is used to indicate special control characters such as line feed, carriage return, and form feed, to write a backslash as part of the Format parameter, use two backslash characters (i.e. \\).

• Quotation marks ("): The entire test string is delimited by quotation marks, so to include a set of quotation marks as part of the Format parameter, use a set of quotations marks (i.e. "").

Control characters In order to encode certain control characters as part of the Format parameter, one of two methods may be used. The first is to use a backslash character followed by one of the single character codes listed below to produce the desired result. Please note that the letters must be lower case.

Code	Meaning
\b	Backspace
\f	Form feed
\n	Line feed
\r	Carriage return
\t	Horizontal tab
\v	Vertical tab

In addition to these pre-defined codes, an alternate form may be used:

\nnn Where nnn is a three digit integer in the range of 0 to 255 specifying a certain ASCII character. If the number contains less than three digits, the leading spaces must be padded with zeroes; this is not the case with the previously listed single character control characters. For example, to include the one byte ASCII character G in the output, you could place its decimal equivalent of 71 in the Format string as \071.

V1, V2, … { varies } { required } { no default: }

Are any expressions giving the values to be output in the form described by the Format parameter. Each of the Vn parameters is evaluated and written in the order in which each appears in the parameter list. The way in which they are formatted is dictated by the % format specifications.

V1 is formatted by the first % sequence in the Format parameter, V2 by the second, and so on. If there are more V parameters than % sequences in the Format string, the remainder are ignored. If there are fewer V parameters than % sequences in the Format string, the remaining % sequences are written literally without any translation.

Comments: You cannot write to a read-only file. You may use GetFileAttribs and SetFileAttribs to get/set the read-only attribute.

If one of the values to be written is outside of the range of the type indicated by the format specifier, a 0 is written. If the value to be written is invalid, nothing is written for most format specifiers, with the exception of %nb, which will write a 0 in the place of the invalid. Invalidity of the output values does not preclude execution of this function.

This function returns the number of Vn parameters not written to the file; a 0 return value indicates success. Variables that contain invalid values that were not written due to their invalidity do not increment this count. An invalid return value indicates an error with one of the parameters. For Mode 3, a 0 indicates success and a 1 (true) indicates a problem deleting the file.

FWrite cannot be used to open COM 1 or COM 2 for direct writing; however, FWrite can connect to a printer on either COM1 or COM2.

All print functions are compatible with the values returned in either of the first two parameters of the PrintDialogBox function.

Example:

If timeToWrite;

[

FWrite(4 { Number of parameters },

"ASCII.DAT" { File to write to },

1 { Clear data currently in file },

0 { Starting point },

"A=%d\r\nB=%3.2d\r\nC=%6.2f\r\n%8.3s\r\n%c"

{ Format string },

100.8, 2, 2/3, "finished", 33

{ Values to be written });

timeToWrite = 0;

]

If the variable timeToWrite is true, the FWrite statement would produce a file called ASCII.DAT with five lines of text as follows:

A=100

B= 02

C= 0.67

fin