FORMATTING BINARY INPUT/OUTPUT

This section explains the format specifier used in READ and WRITE statements to read and write binary (unformatted) data for each data item. Binary input/output operations are sometimes referred to as unformatted, as opposed to text (ASCII) input/output operations that are referred to as formatted.

The built-in SET_FILE_ATR with the ATR_UF attribute is used to designate a file variable for binary operations. If not specified, ASCII text operations will be used.

Data items in READ and WRITE statements can be any of the following data types for binary files:

INTEGER REAL BOOLEAN STRING VECTOR POSITION XYZWPR XYZWPREXT JOINTPOS

Vision and array variables cannot be read or written in unsubscripted form. The elements of an ARRAY are read or written in the format that corresponds to the data type of the ARRAY.

Entire PATH variables can be read or written, or you can specify that only node[0] (containing the PATH header), a specific node, or a range of nodes be read or written. Format specifiers have no effect on PATH data. PATH data can be read or written only to a file and not to a serial port, CRT/KB, or teach pendant.

Binary I/O is preferred to text I/O when creating files that are to be read only by KAREL programs for the following reasons:

• Positional, VECTOR, and PATH variables cannot be read directly from text input.

• Some formats and data combinations are not read in the same manner as they were written in text files or they become invalid if read with the same format.

• Binary data is generally more compact, reducing both the file size and the I/O time.

• There is some inevitable loss of precision when converting from REAL data to its ASCII representation and back.

Generally, no format specifiers need to be used with binary I/O. If this rule is followed, all input data can be read exactly as it was before it was written.

However, if large numbers of INTEGER values are to be written and their values are known to be small, writing these with format specifiers reduces both storage space and I/O time.

7. FILE INPUT/OUTPUT OPERATIONS MARRC75KR07091E Rev H

For example, INTEGER values in the range of -128 to +127 require only one byte of storage space, and INTEGER values in the range of -32768 to +32767 require two bytes of storage space. Writing INTEGER values in these ranges with a first format specifier of 1 and 2, respectively, results in reduced storage space and I/O time requirements, with no loss of significant digits.

Table 7–17summarizes input and output format specifiers that can be used with the data items in READ and WRITE statements. The default format of each data type is also included.Section 7.8.1 throughSection 7.8.6explain the effects of format specifiers on each data type in more detail.

See Also: SET_FILE_ATR Built-In Routine,Appendix A.

Table 7–17. Binary Input/Output Format Specifiers

DATA TYPE DEFAULT 1ST FORMAT SPECIFIER 2ND FORMAT SPECIFIER

INTEGER Four bytes read or written Specified number of least significant bytes read or written, starting with most significant (1-4)

Ignored

REAL Four bytes read or written Ignored Ignored

BOOLEAN Four bytes read or written Specified number of least significant bytes read or written, starting with most significant (1-4)

Ignored

STRING Current length of string (1 byte), followed by data bytes

Number of bytes read or written Ignored

VECTOR Three 4-byte REAL numbers read or written

Ignored Ignored

POSITION 56 bytes read or written Ignored Ignored

XYZWPR 32 bytes read or written Ignored Ignored

XYZWPREXT 44 bytes read or written Ignored Ignored

JOINTPOSn 4 + n*4 bytes read or written Ignored Ignored

PATH Depends on size of structure Ignored Ignored

7.9.1 Formatting INTEGER Data Items

INTEGER data items in a READ or WRITE statement are formatted as follows:

Default: Four bytes of data are read or written starting with the most significant byte.

First Format Specifier: Indicates the number of least significant bytes of the INTEGER to read or write, with the most significant of these read or written first. The sign of the most significant byte read is extended to unread bytes. The format specifier must be in the range from 1 to 4.

MARRC75KR07091E Rev H 7. FILE INPUT/OUTPUT OPERATIONS

For example, if an INTEGER is written with a format specifier of 2, bytes 3 and 4 (where byte 1 is the most significant byte) will be written. There is no check for loss of significant bytes when INTEGER values are formatted in binary I/O operations.

NoteFormatting of INTEGER values can result in undetected loss of high order digits.

Second Format Specifier: Ignored for INTEGER data items.

7.9.2 Formatting REAL Data Items

REAL data items in a READ or WRITE statement are formatted as follows:

Default: Four bytes of data are read or written starting with the most significant byte.

First Format Specifier: Ignored for REAL data items.

Second Format Specifier: Ignored for REAL data items.

7.9.3 Formatting BOOLEAN Data Items

BOOLEAN data items in a READ or WRITE statement are formatted as follows:

Default: Four bytes of data are read or written. In a read operation, the remainder of the word, which is never used, is set to 0.

First Format Specifier: Indicates the number of least significant bytes of the BOOLEAN to read or write, the most significant of these first. The format specifier must be in the range from 1 to 4. Since BOOLEAN values are always 0 or 1, it is always safe to use a field width of 1.

Second Format Specifier: Ignored for BOOLEAN data items.

7.9.4 Formatting STRING Data Items

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

Default: The current length of the STRING (not the declared length) is read or written as a single byte, followed by the content of the STRING. STRING values written without format specifiers have their lengths as part of the output, while STRING values written with format specifiers do not.

Likewise, if a STRING is read without a format specifier, the length is expected in the data, while if a STRING is read with a format specifier, the length is not expected.

This means that, if you write and then read STRING data, you must make sure your use of format specifiers is consistent.

7. FILE INPUT/OUTPUT OPERATIONS MARRC75KR07091E Rev H

First Format Specifier: Indicates the number of bytes to be read or written.

Second Format Specifier: Ignored for STRING data items.

In a read operation, if the first format specifier is greater than the declared length of the STRING, the data is truncated on the right. If it is less than the declared length of the STRING, the current length of the STRING is set to the number of bytes read.

In a write operation, if the first format specifier indicates a shorter field than the current length of the STRING, the STRING data is truncated on the right. If it is longer than the current length of the STRING, the output is padded on the right with blanks.

Writing STRING values with format specifiers can cause truncation of the original STRING values or padding blanks on the end of the STRING values when reread.

7.9.5 Formatting VECTOR Data Items

VECTOR data items in a READ or WRITE statement are formatted as follows:

Default: Data is read or written as three 4-byte binary REAL numbers.

First Format Specifier: Ignored for VECTOR data items.

Second Format Specifier: Ignored for VECTOR data items.

7.9.6 Formatting POSITION Data Items

POSITION data items in a READ or WRITE statement are formatted as follows:

Default: Read or written in the internal format of the controller, which is 56 bytes long.

7.9.7 Formatting XYZWPR Data Items

XYZWPR data items in a READ or WRITE statement are formatted as follows:

Default: Read or written in the internal format of the controller, which is 32 bytes long.

7.9.8 Formatting XYZWPREXT Data Items

XYZWPREXT data items in a READ or WRITE statement are formatted as follows:

MARRC75KR07091E Rev H 7. FILE INPUT/OUTPUT OPERATIONS

Default: Read or written in the internal format of the controller, which is 44 bytes long.

7.9.9 Formatting JOINTPOS Data Items

JOINTPOS data items in a READ or WRITE statement are formatted as follows:

Default: Read or written in the internal format of the controller, which is 4 bytes plus 4 bytes for each axis.