An attached object is a piece of data that belongs (is "attached") to a single record. It may be a text memo, BLOB (Binary Large Object), bitmap, gif, jpeg, video or sound clip, a word processor document, a spreadsheet, etc. An attached object can be a standard Microsoft OLE document (WORD, EXCEL, VISIO, etc.). Attached objects act like large-capacity fields, either of type Memo or Binary.

For Oracle, attached objects are stored in LONG RAW fields (for Binary) and LONG fields (for Memo). Although Oracle has a limit of one LONG field per record, Rich Client Architecture supports multiple attached objects per record. In SQL Anywhere, attached objects are stored in LONG BINARY and LONG VARCHAR. In FoxPro, all attached objects are stored in MEMO fields. Regardless of the back-end DBMS, the Database Library’s interface to attached objects is the same.

Binary attached objects can be of any type, whereas a Memo attached object can only be uncompressed text. The most important reason to choose Memo over Binary is to allow third-party tools, such as Crystal Report Writer, to directly access them.

Currently, the maximum length of an attached object is 9,999,000 bytes. For most types of attached objects, the Database subsystem automatically compresses them for transmission and storage, and uncompresses them on retrieval. An attached object is physically stored separately from the rest of the record, which actually contains only the Attached Object ID. This ID is used to locate the object and consists of the Last Modify User Code, Date and Time in character format.

The BFC Foundation Application includes two major samples of how to use attached objects, the Help System and the Note Test Form. Here's what the Note Test Form looks like:

• This sample demonstrates use of Attached Objects.
• An attached object can be a text memo, BLOB, bitmap, gif, jpeg, video, sound clip or any standard OLE document, such as Word, Excel, Visio etc.

Every attached object has an Attached Object Type, which identifies the type of data in the object. Information about each Attached Object Type, including its name, unique code and, if applicable, an OLE class ID, is stored in the Attached Object Type built-in records. Programmers can easily add more Attached Object Types, which will be stored and retrieved along with the attached objects.

An attached object acts like the contents of a database field within the record to which it is attached. An attached object can have a Database Field Type of 'M' (for Memo) or 'B' (for Binary) and holds a single object (unless it is empty, i.e. null).

The Database Field Dictionary entries for the record type (table) determines whether a record has zero, one, or more than one attached object fields. For example, a personnel record might contain one binary attached object field for holding a scanned in resume, another binary attached object field for holding the employee's picture, and a memo attached object field for comments from the employee's supervisor. The Database Field Dictionary records are cached locally (on the client as well as the Internet Server) and are removed based on a Least Recently Used (LRU) basis.

Getting and setting a record's attached objects is similar to getting and setting other types of database fields, such as numbers, dates and character strings. GetAttObj() is used to retrieve an attached object from a database buffer containing data fetched from the database. SetAttObj() is used to place or replace an attached object in a database buffer before the data is sent to the database. The programmer does not specify 'M' or 'B' because the database field dictionary stores whether an attached object is in memo or binary format.

Attached objects are not retrieved until the last moment. That is, when the record is retrieved, the AttObj ID is returned but the attached object itself is NOT retrieved until GetAttObj() is called. Each time GetAttObj() is called the database is accessed. Since an attached object can be large, the database subsystem does not try to hold on to a copy of the object. Multiple calls to GetAttObj() will go to the database each time, even if the same attached object is being retrieved. (This avoids potentially large amounts of disk space being grabbed to cache the objects temporarily and has the additional minor benefit of detecting up to the last minute whether or not other users have made modifications before the user starts making changes.)

If the same attached objects are likely to be accessed repeatedly and unlikely to be changed, the application programmer can cache them in local files to avoid extra database accesses. Note that for text fields that have a maximum length of 1975 (MAX_DbFldLenChar), the database designer has the option of making these CHAR fields instead of memo or bin attached object fields. (CHAR fields are completely retrieved at the time the record is fetched and are stored locally in the database buffer.)

Attached objects can be retrieved either into a programmer specified file or main memory location. Retrieving attached objects into main memory instead of a file is mainly for programmer convenience. The database system uses an intermediate work file whenever it retrieves or sends an attached object. From there, it is copied to the file or memory location specified by the programmer.

As opposed to GetAttObj(), SetAttObj() never accesses the database. Instead, the attached object is placed in a temporary file. The object is not added to the database until a record modification operation, such as AddRec() or ChgRec() takes place. ChgRec() operations will fail (and by default cause a rollback) if any attached objects have been modified since they were last retrieved.

Even though an attached object is stored separately from the record to which it is attached, the application programmer can think of the record as containing the attached objects. For example, DelRec() (Delete Record) removes a record and all of its attached objects.