Imagine Transparency

The Imagine Transparency facility allows Model 204 programs to access files stored in the Imagine database as if they were local files. This facility is available in Model 204 Version 8.0 and later.

While a fair amount of setup is required to define and populate the Imagine files being accessed in Transparency mode, and create Imagine broker processes to provide Model 204 access to the Imagine files, very little setup is required on Model 204.

First, an IMAGINET port must be defined in an Online that would be using Transparency Mode. The number of connections required is the maximum number of threads simultaneously accessing Imagine files in the Online. The total number of threads in the Online is, of course, an upper bound for this number.

Then, each Model 204 file hosted on Imagine needs to be allocated as an Imagine file. For example:

ALLOCATE SOMEFILE WITH IMAGINE

Once this is done, any reference to SOMEFILE in aModel 204 application (including in file groups) would access the data from Imagine via the IMAGINET port. Note that a single Model 204 file can corresponding to many Imagine files if record types are used.

Accessing Imagine files from SOUL

No application changes are required to read or update a Transparency file. Ordinary SOUL statements such as FIND, FOR EACH RECORD, FIND AND PRINT COUNT, STORE RECORD, CHANGE, ADD, and DELETE operate on a Transparency file exactly as they do on a native Model 204 file. Model 204 transparently sends the corresponding requests to the Imagine broker over the IMAGINET port and returns the results to the application.

To reduce broker round trips, Model 204 caches the results of Transparency finds and prefetches records from find result sets. Cached finds are automatically deoptimized and revalidated when records they reference are changed, so applications always see a consistent view of the data.

Releasing held records

Records retrieved from Imagine are held on a Transparency thread for the duration of the request. The RELEASE IMAGINE RECORDS statement releases those held records and frees the Transparency thread. Specify the CLEARLISTS option to also clear any $lists and StringLists that reference the released records:

RELEASE IMAGINE RECORDS CLEARLISTS

Populating and synchronizing Imagine files

Before a Model 204 file can be switched to Transparency mode, its data must be loaded into Imagine. The IMAGINE command extracts the data from an existing Model 204 file and loads it into Imagine:

• IMAGINE EXTRACT copies the file's records to Imagine as a one-time operation.
• IMAGINE SYNC copies the records and then keeps Model 204 and Imagine in sync, so that subsequent updates are also applied to Imagine. This makes it feasible to switch a file to Transparency mode with a minimal outage.
• IMAGINE ENDSYNC ends a SYNC or EXTRACT for the file.

The DISPLAY IMAGINESYNC command lists all files that are currently in IMAGINE SYNC mode.

Restrictions

The following operations are not supported against an Imagine Transparency file:

• DEFINE FIELD — field definitions are determined by the underlying Imagine file and cannot be changed from Model 204.
• FOR EACH RECORD IN ORDER — ordered retrieval is not supported for Transparency files.

See also

• IMAGINE command
• DISPLAY IMAGINESYNC command
• JANUS DEFINE (the IMAGINET port type)
• DEFINE DATASET command (allocating a file WITH IMAGINE)
• Model 204 version 8.0 release notes