Formatting STRING Data Items

STRING data items in a READ statement are formatted as follows:

Default: Read starting at the current position and continuing to the end of the line. If the length of the data obtained is longer than the declared length of the STRING, the data is truncated on the right. If it is shorter, the current length of the STRING is set to the actual length.

First Format Specifier: Indicates the total field length of the input data. If the field length is longer than the declared length of the STRING, the input data is truncated on the right. If it is shorter, the current length of the STRING is set to the specified field length.

Second Format Specifier: Indicates whether or not the input STRING is enclosed in single quotes. If the format specifier is equal to 0, the input is not enclosed in quotes.

If it is equal to 2, the input must be enclosed in quotes. The input is scanned for the next nonblank character. If the character is not a quote, the STRING is not valid and the read operation fails.

If the character is a quote, the remaining characters are scanned until another quote or the end of line is found. If another quote is not found, the STRING is not valid and the read operation fails.

If both quotes are found, all of the characters between them are read into the STRING variable, unless the declared length of the STRING is too short, in which case the data is truncated on the right.

Table 7–13lists examples of STRING input data items and their format specifiers, where str_var has been declared as a STRING[5]. The input data and the resulting value of the STRING data items are included in the table. The symbol [eol] indicates end of line and X indicates extraneous data on the input line.

Table 7–13. Examples of STRING Input Data Items

DATA ITEM INPUT DATA RESULT

str_var

"

ABC[eol]

"

"

ABC

"

str_var

"

ABCDEFG[eol]

"

"

ABCDE

"

(FG is read but the STRING is truncated to 5 characters)

7. FILE INPUT/OUTPUT OPERATIONS MARRC75KR07091E Rev H

Table 7–13. Examples of STRING Input Data Items (Cont’d)

DATA ITEM INPUT DATA RESULT

str_var

"

'ABC'XX

"

"

'AB

"

(blanks and quote are read as data) str_var::0::2

"

'ABC'XX

"

"

'ABC'

"

(read ends with second quote)

STRING data items in a WRITE statement are formatted as follows:

Default: Content of the STRING is written with no trailing or leading blanks or quotes.

The STRING must not be over 127 bytes in length for files or 126 bytes in length for other output devices. Otherwise, the program will be aborted with the “STRING TOO LONG” error.

First Format Specifier: Indicates the total number of characters to be written, including blanks. If the format specifier is larger than required for the data, the data is left justified and trailing blanks are added. If the format specifier is smaller than required, the STRING is truncated on the right.

The specifier must be in the range of 1 to 127 for a file or 1 to 126 for other output devices.

Second Format Specifier: Indicates whether the output is to be left or right justified and whether the STRING is to be enclosed in quotes using the following values:

0 left justified, no quotes 1 right justified, no quotes 2 left justified, quotes 3 right justified, quotes

Quoted STRING values, even if left justified, are preceded by a blank. Unquoted STRING values are not automatically preceded by a blank.

MARRC75KR07091E Rev H 7. FILE INPUT/OUTPUT OPERATIONS

Table 7–14lists examples of STRING output data items and their format specifiers. The output values of the STRING data items are also included in the table. Double quotes are used in the table as delimiters to show leading blanks; however, double quotes are not written by KAREL programs.

Table 7–14. Examples of STRING Output Data Items

DATA ITEM OUTPUT COMMENT

’ABC’

"

ABC

"

No leading blanks

’ABC’::2

"

AB

"

Truncated on right

’ABC’::8

"

ABC

"

Left justified

’ABC’::8::0

"

ABC

"

Same as previous

’ABC’::8::1

"

ABC

"

Right justified

’ABC’::8::2

"

'ABC'

"

Note leading blank

7. FILE INPUT/OUTPUT OPERATIONS MARRC75KR07091E Rev H

Table 7–14. Examples of STRING Output Data Items (Cont’d)

DATA ITEM OUTPUT COMMENT

’ABC’::8::3

"

'ABC'

"

Right justified

’ABC’::4::2

"

'A'

"

Truncated

Format specifiers for STRING data items can cause the truncation of the original STRING values or the addition of trailing blanks when the values are read again.

If STRING values must be successively written and read, the following guidelines will help you ensure that STRING values of varying lengths can be read back identically:

• The variable into which the STRING is being read must have a declared length at least as long as the actual STRING that is being read, or truncation will occur.

• Some provision must be made to separate STRING values from preceding variables on the same data line. One possibility is to write a ’ ’ (blank) between a STRING and the variable that precedes it.

• If format specifiers are not used in the read operation, write STRING values at the ends of their respective data lines (that is, followed in the output list by a CR) because STRING variables without format specifiers are read until the end of the line is reached.

• The most general way to write string values to a file and read them back is to use the format ::0::2 for both the read and write.