TEXT

The TEXT data type stores large text data.

Syntax

TEXT

Usage

A TEXT variable is actually a 'locator' for a large object stored in a file or in memory. The TEXT data type is a complex type that cannot be used like basic character string types such as VARCHAR or CHAR: It is designed to handle a large amount of text data. This type has a theoretical limit of 2^31 bytes (~2.14 Gigabytes), but the practical limit depends from the disk or memory resources available to the process. Use this data type to store, fetch or update the contents of a TEXT database column when using IBM^® Informix^®, or the content of a CLOB column when using another type of database.

Keep in mind that a TEXT variable must be initialized with the LOCATE instruction before usage. You might want to free resources allocated to the TEXT variable with the FREE instruction. A FREE will remove the file if the LOB variable is located in a file.

The LOCATE instruction basically defines where the large data object has to be stored (in file or memory). This instruction will actually allow you to fetch a LOB into memory or into a file, or insert a LOB from memory or from a file into the database.

When you assign a TEXT variable to another TEXT variable, the LOB data is not duplicated, only the handler is copied.

You can assign TEXT variables to/from VARCHAR, CHAR and STRING variables.

If you need to clone the large object, you can use the I/O built-in methods to read/write data from/to a specific file. The large object can be located in memory, in a specific file or in a temporary file (the temp dir can be defined by DBTEMP envrionment variable.

Methods

Table 1. Object methods for the TEXT data type
Name	Description
getLength() RETURNING `result` INTEGER	Returns the size of the text in bytes.
readFile(`filename` STRING)	Reads data from a file and copies into memory or to the file used by the variables according to the `LOCATE` statement issued on the object.
writeFile(`filename` STRING)	Writes data from the variable (memory or source file) to the destination file passed as parameter. The file is created if it does not exist.

MAIN
  DEFINE t TEXT
  DATABASE stock 
  LOCATE t IN FILE "/tmp/mytext.txt" 
  SELECT doc_text INTO t FROM documents WHERE doc_id = 123
  CALL t.writeFile("/tmp/document.txt")
END MAIN