Appendix F:  String Handling

This appendix describes the details of ACCENT R string storage, string accessing, and string display formatting.  Side effects of the FIELDTRIM option are explained.

1. DEFINING AND STORING STRINGS

ACCENT R provides two data types to store strings:

• A (Alpha) fields may contain uppercase and lowercase letters of the alphabet and spaces.

• C (Character) fields may contain uppercase and lowercase letters of the alphabet, spaces, digits, punctuations, and most control codes (e.g., codes 1 through 31 decimal - see Appendix D).

NOTE: Code 0 represents a NULL character, which is used to denote the end of the string in an Alpha or Character field. The role of the NULL character in string handling is discussed later in this appendix. The NULL character can be generated by using system function @CHR 0.

Alpha (A) and Character (C) fields can appear in any Schema Definition and Global Storage definition. In addition, ACCENT R provides two system fields, @STRING and @COMMAND, for storing string values for the duration of the current session. @STRING can have up to 25 occurrences, each with a defined width of 20 characters. @COMMAND can have only one occurrence, but it can accommodate a string of up to 150 characters.

Storing string values into fields is only constrained by the field data type and field length. A field defined with a width of 5 characters cannot store a string longer than 5 characters. The only exception is when all the excess characters are trailing blanks; for example, "ABC    " can be stored into a 3-character field, but "ABCDEF" cannot.

Besides string values stored in data fields, ACCENT R can also handle string constants in commands and statements. ACCENT R recognizes several methods for defining string constants:

• characters enclosed in single or double quotation marks: "ABC" or 'ABC'. For example:

TYPE "ABC Company"

• quoted characters prefixed by an integer repeat count: 3"XYZ" defines the string "XYZXYZXYZ". For example:

PRINT 80"-"

• the letter B (blank) or S (space) prefixed by an integer repeat count defines a string filled with blanks (spaces): 3S and 3B both define a string of three blanks. For example:

PRINT NAME, 3B, ADDRESS, 3B, CITY, 2B, STATE, 2B, ZIP

2. RETRIEVING STRINGS

When retrieving a string from a field, ACCENT R examines each character in the field until the end of the field's defined width or until it encounters a NULL character, in which case it stops early and returns only the portion of the field before the NULL character. The rest of the field is ignored.

Since the presence of NULL characters affects string retrieval, ACCENT R sometimes handles binary fields (FORM IS BINARY) and ASCII fields (FORM IS ASCII) differently. This is because newly created binary fields are preset to NULL characters while ASCII fields are preset to blanks. Retrieving binary and ASCII fields will return different strings depending on the setting of FIELDTRIM. For example, consider the following field definition:

FIELD, C, 10

1. For a new, binary field, ACCENT R will return a null string (empty string of 0 length) regardless of the setting of FIELDTRIM.

Note: Care should be taken when entering secondary fields into a new, binary field. If the secondary fields do not occupy the first character position, ACCENT R will return an empty field value since it will encounter a NULL character first and ignore the rest of the field.

2. For a new ASCII field, ACCENT R will return a null string if FIELDTRIM is enabled, or return a string of 10 blanks if FIELDTRIM is disabled.

3. For a field containing the value "ABCDE", ACCENT R will return the string "ABCDE" with length 5 if FIELDTRIM is enabled, and "ABCDE     " with length 10 if FIELDTRIM is disabled. This is both true for binary and ASCII fields since once a binary field has been modified, trailing positions are blank filled rather than NULL filled.

The NULL character and FIELDTRIM option can be used to improve efficiency of programs. For example, certain applications may require a large field (say, FIELD,C,200) to store the largest string expected. If data is entered into the field in the manner:

"ABCDE" TO FIELD

Then all 200 characters must be examined and ACCENT R will retrieve a string of 200 characters with 195 trailing blanks. If FIELDTRIM is enabled, the 195 trailing blanks are ignored and ACCENT R returns a string of 5 characters instead of 200. Or, if data is entered as:

"ABCDE" + @CHR 0 TO FIELD

Then ACCENT R will only examine the positions up to the NULL character and return a string of 5 characters. The presence of the NULL character overrides the setting of FIELDTRIM.

For systems supporting USAGE IS SIXBIT, it should be further noted that new fields are also preset with NULL characters, but the SIXBIT character set defines NULL characters to be blanks. Applications using both USAGE IS ASCII and USAGE IS SIXBIT may return strings of different length for data that otherwise looks identical.

Consider the following Schema:

FLD1, C, 5, USAGE IS ASCII

FLD2, C, 5, USAGE IS ASCII

FLD3, C, 5, USAGE IS SIXBIT

FLD4, C, 5, USAGE IS SIXBIT

If the following assignments were performed on the above new fields:

"ABC"   TO FLD1

"ABC" + @CHR 0   TO FLD2

"ABC"   TO FLD3

"ABC" + @CHR 0   TO FLD4

ACCENT R will return the following string values when accessing the fields:

3. STRING DISPLAY FORMATTING

The width used for displaying a string is, for the most part, independent of the actual length of the string being displayed. The actual length of the string can be affected by the setting of FIELDTRIM or the presence of NULL characters in the data field, as discussed previously in this appendix. On the other hand, the width used to display strings stored in data fields is always the defined width of the field as specified in the Schema Definition or Global Storage definition. For example, a field defined as FIELD,C,10 will be shown with an implicit print picture of "10X".  Even an empty field will be displayed in the field's width, even though the string has no actual length.

To override the implicit output width, an explicit print picture can be specified at the end of the field name, in the form:

field.name @ "print.pictue"

The print picture for string outputs is in the form "nX" where n specifies the number of characters to display.  Explicit print pictures can truncate or extend the implied width; for example:

TYPE "ABCDE"   @ "3X"   will produce "ABC"

TYPE "ABCDE"   @ "10X"  will produce "ABCDE     "

TYPE ""        @ "5X"   will produce "     "

To display a string using its actual length (without truncation or trailing blanks) you specify free form output by appending @ "" to the field name. Free form output is ideal for displaying variable length strings embedded within other text. For example:

PRINT "Purchased by ", COMPANY @"", " on ", DATE

String constants, string expressions, and string functions are displayed with the length of the resulting string. For example:

TYPE "ABCDE" + "XYZ"

will display the string "ABCDEXYZ" of 8 characters.

Strings in system fields are displayed in free form output (e.g. no trailing blanks) if FIELDTRIM is enabled, and in their defined width if FIELDTRIM is disabled. For example,

*ENABLE FIELDTRIM<CR>

*TYPE @WEEKDAY + " is today."<CR>

Tuesday is today.

*DISABLE FIELDTRIM<CR>

*TYPE @WEEKDAY + " is today."<CR>

Tuesday   is today.

The following output display examples show the differences between output display and the actual length of the string.