LOB file reference variables

File reference variables are similar to host variables except that they are used to transfer data to and from IFS files (not to and from memory buffers).

A file reference variable represents (rather than contains) the file, just as a LOB locator represents (rather than contains) the LOB value. Database queries, updates, and inserts may use file reference variables to store, or to retrieve, single LOB values.

For very large objects, files are natural containers. It is likely that most LOBs begin as data stored in files on the client before they are moved to the database on the server. The use of file reference variables assists in moving LOB data. Programs use file reference variables to transfer LOB data from the IFS file directly to the database engine. To carry out the movement of LOB data, the application does not need to write utility routines to read and write files using host variables.

Note: The file referenced by the file reference variable must be accessible from (but not necessarily resident on) the system on which the program runs. For a stored procedure, this is the server.

A file reference variable has a data type of BLOB, CLOB, or DBCLOB. It is used either as the source of data (input) or as the target of data (output). The file reference variable may have a relative file name or a complete path name of the file (the latter is advised). The file name length is specified within the application program. The data length portion of the file reference variable is unused during input. During output, the data length is set by the application requester code to the length of the new data that is written to the file.

When using file reference variables there are different options on both input and output. You must choose an action for the file by setting the file_options field in the file reference variable structure. Choices for assignment to the field covering both input and output values are shown below.

Values (shown for C) and options when using input file reference variables are as follows:

SQL_FILE_READ (Regular file) — This option has a value of 2. This is a file that can be open, read, and closed. DB2^® determines the length of the data in the file (in bytes) when opening the file. DB2 then returns the length through the data_length field of the file reference variable structure. The value for COBOL is SQL-FILE-READ.

Values and options when using output file reference variables are as follows:

SQL_FILE_CREATE (New file) — This option has a value of 8. This option creates a new file. Should the file already exist, an error message is returned. The value for COBOL is SQL-FILE-CREATE.
SQL_FILE_OVERWRITE (Overwrite file) — This option has a value of 16. This option creates a new file if none already exists. If the file already exists, the new data overwrites the data in the file. The value for COBOL is SQL-FILE-OVERWRITE.
SQL_FILE_APPEND (Append file) — This option has a value of 32. This option has the output appended to the file, if it exists. Otherwise, it creates a new file. The value for COBOL is SQL-FILE-APPEND.

Note: If a LOB file reference variable is used in an OPEN statement, do not delete the file associated with the LOB file reference variable until the cursor is closed.