Long text/binary fields

An alphanumeric/binary array field that is assigned the p (packed text) flag becomes a long text field. Such a field can store dim * length characters, where dim is the array size and length the length in bytes of each element in the array. This enables the storage of alpha fields longer than 255 bytes, the limit for an ordinary alpha field. Typical uses are as the linked field to a free format textbox, or for assigning data to or from an OLE control text field. Use of the p flag means that the entire text is assigned; otherwise the limit would be 255 characters.

A temporary field can be allocated the p flag directly. For example:

!temp LongText,,a200[40],,p

This declares a long text field capable of storing up to 8000 characters. The characters are stored as a single text string.

To turn a data dictionary field into a long text field, include the character “p” in its format string. The compiler recognises this format, and sets the field’s p flag.

The maximum length of a long text field is 132,000 characters.

Sculptor treats a long text field as a non-array field. The individual elements should not be referenced directly. Sculptor does not allow the p flag to be set or cleared at run time. If the p flag is included in the text_expression in the command

field_id->flags = text_expression

it is ignored, though other flags included in text_expression will be set.

Functions such as getstr(), getbyte(), setstr(), setbyte() and instr() all work with long text fields and should be used to extract or modify parts of the text.

Long text fields are null terminated unless the full length is used. When a value is stored in a long text field, Sculptor sets all unused bytes to null, so if setbyte() or setstr() is used to store new text at the end of the current text, this must start at the first null character.

In general, Sculptor’s built-in functions and operators all work on the full length of long text fields. Long text can be used with ODBC, and assigned to and from OLE controls and the clipboard. Long text is truncated to a maximum of 255 characters when retrieved for any of the following purposes:

1

For the name of any object.

2

For filenames and pathnames.

3

For headings, titles, labels etc.

4

For text passed across the DDE interface.

5

In the chain and exec commands.

6

In commands such as caption, error, info and prompt.

7

TAPI strings.

8

Web strings such as cookie values. See Internet functions. Since Sculptor version 6.2.0 all the XML/JSON functions support the packed flag.

9

XML attributes.

Some of the above restrictions may be removed in the future.

Programs using long text fields must be compiled and run with Sculptor 5.3 (Alpha 19) or later if they are to work properly. If a program defines one or more !temps as long text, the compiler flags it as unsuitable for running with earlier versions of Sculptor. However, if the only long text fields are data dictionary fields, Sculptor does not flag the program in this way, since it is not practical for the compiler to determine whether a field is referenced in the program. For safety, therefore, programs that make use of long text fields should declare at least one !temp field with the p flag, even if it is not used. This ensures that the compiler flags the program correctly.


Using long text fields with free format textboxes

Long text fields are ideal for use as the linked field for a free format textbox. The text is stored as a packed string, so it is not possible to type more characters into the textbox that can be stored in the field. Hard line feeds (newlines typed by the user) are stored in the standard DOS format as a carriage return, line feed pair (0x0d, 0x0a). Soft line feeds (generated by automatic word wrapping) are not stored.

If the same text is displayed in a free format textbox with a different width, the word wrap changes to match the new width, but user-typed line feeds are preserved.

Long text that has been stored in a database field from a free format textbox should not be used in programs running with versions of Sculptor earlier than 5.3 (Alpha 19). The text will not display correctly, and can be corrupted if saved.


RELATED TOPICS

Data fields

Alphanumeric field formats

Field flags

Textboxes

Free format textboxes

Extracting characters from an array and storing them in a long textfield

Copying characters from a long text field to anarray

Reading/writing JSON/XML

nph-srep functions