|
|
|
|
| CAClose | CADelete | CAError | |
| CAGet | CAHigh | CAInit | CAInsert |
| CAMode | CAOpen | CAResetErrorProcedure | CASetErrorProcedure |
| CATerminate | HandleIsNull | NullHandle | ReturnFileHandle |
| STRCAError | STRCAInit | TotalItems |
//* // CACHE - memory/disk management for temporary or permanent storage. // // // // The Cache library allows dynamic allocation of any item (structure) // or group of items using memory and disk as needed. The only // limiting factor on the total amount is the disk available. Cache // will not use the disk if the items will fit in memory and CAClose // and CAOpen are not used. // // For the most part RANCACHE accomplishes the same purpose as // CACHE. The following notes may help in determining which // library to use : // // Items unique to CACHE // 1. Easer to learn for first-time users doing // sequential processing. // // 2. Provides insert/delete functions. // // 3. Optimized for sequential processing. // // 4. Easily converts to RANCACHE. // // Items unique to RANCACHE // 1. Provides for optimizing both random and sequential // processing. // // 2. Provides for multiple simultaneous access in the same // file. // // 3. Provides for locking some items in memory while others // are allowed to compete for memory space. // // 4. Provides for writing designated records while in read-only // mode and for overriding the write on designated records // while in read-write mode. // // 5. Provides for setting an offset into a file for all // subsequent I/O operations. // // // The Library consists of the following items: // // All you need for normal use // --------------------------------- // CATable - hidden type for cache variables. // CAInit - initialize cache. // CAGet - perform disk IO if necessary, then establish pointer. // CATerminate - terminate cache and release resources. // CAError - return error description. // // The error numbers are assigned as follows: // 1 = cannot allocate enough memory // 2 = not enough memory // 3 = file error (see below) // 4 = previous procedure returned failure state // 5 = requested allocation is greater than 65000 // 6 = no more than 999 files can be opened // 7 = y is out of range // 8 = file has no records to delete // 9 = unknown // // The file error numbers are : // 201 = illegal syntax in file name as passed // 202 = file with specified name not found // 203 = no memory for file buffers // 204 = file already exists // 205 = some hardware error during I/O // 206 = no room on volume/medium/directory // 207 = protect, read/write, binary/text error // 208 = operation on unopened file // 209 = read attempted after EOL or EOF // 210 = position before BOF or after EOF // 211 = error unanticipated by this definition // 212 = unknown // // // Needed if items are to be inserted or deleted // as in a spread sheet. // -------------------------------------------------- // CAInsert - insert item or items. // CADelete - delete item or items. // CAHigh - returns the highest index which has // been referenced by CAGet. // // // Needed if the cache is to be saved on disk // ------------------------------------------- // CAOpen - open a cache. (use after CAInit) // CAClose - close a cache. (use instead of CATerminate) // // // Needed if the cache is opened read only for // multiuser access. // ------------------------------------------- // CAMode - Set read-only/read-write modes. // Default is read-write. // // Needed if the user supplies a fatal error handling // routine. // --------------------------------------------------- // CASetErrorprocedure - Establish user defined error procedure // to be called on all file errors. // CAResetErrorprocedure - Reset the error procedure // to the default. // // // For discussion an 'item' can be considered to be any structure // where : // // s = number of bytes in one item (structure). // n = number of items to be buffered in memory. // // It is assumed that enough memory can be allocated by Cache // for at least s*n bytes. // // The cache is defined and used as follows: // // (1) Set up the structure by defining a type : // // Example : // // type // myType = packed record; // aValue : ModSys.Float32; // cValue : cardinal; // end; // // (2) Define a pointer to the type : // // var // pRec : POINTER to myType = nil; // // (3) Define a variable to be used by CACHE. // // vTable : CATable; // // (4) Initialize the cache : // // CAInit (vTable, TSIZE (myType), 1, '', status); // // // (5) Access the items: // // CAGet (vTable, i, pRec); // // where 'i' is the index and could range from 1 to // however many is needed. // // (6) The example program that follows would set // 350 of the above items to inital values. // // MODULE MyProg; // IMPORT SYSTEM; // // IMPORT CACHE; // CAError, CATerminate; // // IMPORT TermX; // // // type // myType = packed record // // // value : ModSys.Float32; // // // flag : boolean; // // end; // // var // // i : ModSys.INT32; // // status : cardinal; // // vTable : CATable; // // // // pRec : POINTER to myType = nil; // // // string : array [0 .. 79] of char; // // begin // // -- Initialize the cache -- // CAInit (vTable, TSIZE (myType), 1, '', status); // // -- process all items -- // for i := 1 to 350 DO; // // -- call CAGet for each item -- // CAGet (vTable, i, pRec); // // -- process each item -- // pRec^.value := 0.0; // pRec^.flag := False; // // end; // // -- if status is not zero, print a description of the error -- // if status <> 0 then begin // CAError (vTable, status, string); // WriteString (string); // WriteLn; // end; // // -- deallocate the resources -- // CATerminate (vTable) // // end; // MyProg. // // // (7) The next example program uses an array of items. // // MODULE MyProg; // // IMPORT SYSTEM; // IMPORT CACHE; // IMPORT TermX; // // // type // myType = packed record // value : ModSys.Float32; // flag : boolean; // end; // // var // // i, n : ModSys.INT32; // // status : cardinal; // // vTable : CATable; // // // // pRec : POINTER to array [1 .. 900] of myType = nil; // // // string : array [0 .. 79] of char; // // begin // // -- Initialize the cache -- // CAInit (vTable, TSIZE (myType)*900, 1, '', status); // // -- process all groups -- // for i := 1 to 350 DO; // // -- call CAGet for each group -- // CAGet (vTable, i, pRec); // // -- process each item in a group -- // for n := 1 to 900 DO; // pRec^[n].value := 0.0; // pRec^[n].flag := False; // end; // // end; // // -- if status is not zero, print a description of the error -- // if status <> 0 then begin // CAError (vTable, status, string); // WriteString (string); // WriteLn; // end; // // -- deallocate the resources -- // CATerminate (vTable) // // end; // MyProg. //
procedure NullHandle
(var vTable : CATable); stdcall;
exports NullHandle name 'Cache_NullHandle';
function HandleIsNull
(const vTable : CATable) : boolean; stdcall;
exports HandleIsNull name 'Cache_HandleIsNull';
procedure CAInit
(var vTable : CATable;
const sizX : cardinal;
const numG : cardinal;
const Path : array of char;
var state : cardinal); overload; stdcall;
exports CAInit (var vTable : CATable;
const sizX : cardinal;
const numG : cardinal;
const Path : array of char;
var state : cardinal) name 'Cache_CAInit';
//*
// CAInit - Cache initialize.
//
//
// This procedure establishes the parameters and
// allocates the memory required for one cache. Zero
// is returned if the user can proceed. Non-zero
// is returned if resources are not available and the
// user cannot proceed.
//
// CALLING SEQUENCE -
//
// CAInit (vTable, sizX, numG,
// path, state)
//
// ENTRY -
//
// vTable
// The file table pointer. vTable must be unique for
// each cache.
//
// sizX
// size of the item being used.
//
// numG (requirement : numG > 0)
// number of items to buffer in memory for processing efficiency.
//
// If CAGet is called with an index
// greater than numG then disk storage will be used
// requiring a path and file as follows -
// path
// path and file name to be used to create disk storage.
// If path is null then the DOS default is used and a file
// name will be the default 'CA-FILE.nnn'
// where 'nnn' is a number between 001 and 999.
// 'nnn' is sequentially assigned for each cache in a process.
// if the application could exceed 999 files then
// the user should specify the path including the file name.
//
// EXIT -
//
// state : cardinal
// state = 0 means ok to proceed.
// state <> 0 means some condition is unsatisfactory (see CAError).
//
procedure CAInit
(var vTable : CATable;
const sizX : cardinal;
const numG : cardinal;
const Path : string;
var state : cardinal); overload; stdcall;
exports CAInit (var vTable : CATable;
const sizX : cardinal;
const numG : cardinal;
const Path : string;
var state : cardinal) name 'Cache_STRCAInit';
//*
// STRCAInit - See documentation of CAInit.
//
procedure CAGet
(var vTable : CATable;
const index : ModSys.INT32;
var pRec : pointer); stdcall;
exports CAGet name 'Cache_CAGet';
//*
// CAGet - Set pointer to item (group) determined by index.
//
//
// This procedure sets the pointer to the item or group
// index after loading it from disk if necessary.
// If disk is being used the current item or group is
// written out before the new data is read.
//
// CALLING SEQUENCE -
//
// CAGet (vTable, index, pRec);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// index : ModSys.INT32
// Which item or group to set pointer to.
// Requirement : 0 < index <= maximum number
// of items or groups.
// Note to users of CAInsert, CADelete -
// If index = 0 then the CAHigh
// variable is reset to 0.
//
// EXIT -
//
// pRec : pointer
// pointer which will receive the address
// of the indexed item or group.
//
procedure CAInsert
(var vTable : CATable;
const index : ModSys.INT32;
var pRec : pointer;
var state : cardinal); stdcall;
exports CAInsert name 'Cache_CAInsert';
//*
// CAInsert - Insert an item or group before the indexed item or group.
//
//
// This procedure inserts a new item or group just ahead of the
// indexed item or group and then sets the pointer to the beginning
// of the new item or group.
// Note : The CAHigh variable is used to determine the amount
// of data that needs to be moved and is set with the
// normal use of CAGet. CAHigh can be reset to 0 with
// a call to CAGet with C = 0.
//
// CALLING SEQUENCE -
//
// CAInsert (vTable, index, pRec, state);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// index : ModSys.Int32
// The item or group before which the insert will occur.
// (Requirement : (0 > index <= maximum items or groups.)
//
// EXIT -
//
// pRec : pointer
// pointer which will receive the address of the beginning of
// the item or group.
//
// state : cardinal
// state = 0 means ok to proceed.
// state <> 0 means some condition is unsatisfactory (see CAError).
//
procedure CADelete
(var vTable : CATable;
const index : ModSys.INT32;
var pRec : pointer;
var state : cardinal); stdcall;
exports CADelete name 'Cache_CADelete';
//*
// CADelete - Delete the item or column at C.
//
//
// This procedure deletes the item or group at index
// and then sets the pointer to replacement item or group.
//
// CALLING SEQUENCE -
//
// CADelete (vTable, C, pRec, state);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// index : ModSys.INT32
// The item or group to delete.
// (Requirement : (0 > index <= maximum items or groups.)
//
// EXIT -
//
// pRec : pointer
// pointer which will receive the address
// of the replacement item or group.
//
// state :
// state = 0 means ok to proceed.
// state <> 0 means some condition is unsatisfactory (see CAError).
//
function CAHigh
(const vTable : CATable) : ModSys.INT32; stdcall;
exports CAHigh name 'Cache_CAHigh';
//*
// CAHigh - Return the highest item or group referenced.
//
//
// This procedure returns the highest column referenced
// by the user. This can be reset to 0 with a call
// to CAGet with index=0.
//
// CALLING SEQUENCE -
//
// High := CAHigh (vTable)
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// EXIT -
//
// High : ModSys.INT32
// Highest item or group referenced.
//
procedure CAMode
(var vTable : CATable;
const mode : boolean); stdcall;
exports CAMode name 'Cache_CAMode';
//*
// CAMode - Set read-only or read-write mode.
//
//
// This procedure sets read-only or read-write mode. If read-only
// is set then no writes to the files are ever invoked. Any changes
// in the data by the user will be lost when cacheing occurs or when
// the cache is closed. Read-only is intended to allow multi-access
// on a network.
// CAMode can be used before CAOpen to cause the file to be opened
// with the DOS read only mode. In this case however do not attempt
// to change to readWrite mode without closing and reopening the file.
//
// CALLING SEQUENCE -
//
// CAMode (vTable, mode)
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// mode : boolean
// False = Read-Write (Default)
// True = Read-Only
//
procedure CAOpen
(var vTable : CATable;
var HighVal : ModSys.INT32;
var created : boolean;
var state : cardinal); stdcall;
exports CAOpen name 'Cache_CAOpen';
//*
// CAOpen - Open a cache on disk.
//
// Use after the cache has been saved on the disk with CAClose.
//
//
// The file saved with CAClose will be opened for use.
// Note : CAInit must be used immediatly before CAOpen.
//
// CALLING SEQUENCE -
//
// CAOpen (vTable, high, state);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// high : ModSys.INT32
// Set the highest referenced item or group
// (needed only if CAInsert and/or CADelete are used)
// if high = 0 then high will be returned based on the EOF
//
// EXIT -
//
// high : ModSys.INT32
// If high is 0 on entry then high will be returned
// based on the EOF.
//
// created : boolean
// True = A file did not exist so a new one was created.
// False = A file did exist so a new one was not created.
//
// state :
// state = 0 means ok to proceed.
// state <> 0 means some condition is unsatisfactory (see CAError).
//
procedure CAClose
(var vTable : CATable;
var state : cardinal); stdcall;
exports CAClose name 'Cache_CAClose';
//*
// CAClose - Save cache on disk, close files and release resources.
//
// Takes the place of CATerminate.
//
//
// All items or groups will be saved in a disk file for later access
// and all resources will be released.
//
// CALLING SEQUENCE -
//
// CAClose (vTable, state);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// EXIT -
//
// state : cardinal
// state = 0 means ok to proceed.
// state <> 0 means some condition is unsatisfactory (see CAError).
//
procedure CATerminate
(var vTable : CATable); stdcall;
exports CATerminate name 'Cache_CATerminate';
//*
// CATerminate - Terminate cache and release resources.
//
// Use in place of CAClose if cache was temporary.
//
//
// All records will be disgarded and all resources will
// be released.
//
// CALLING SEQUENCE -
//
// CATerminate (vTable);
//
// ENTRY -
//
// vTable : CATable
// The file table pointer.
//
// EXIT -
//
// None
// N/A
//
procedure CASetErrorProcedure
(const UserProc : CAErrorProcedure); stdcall;
exports CASetErrorProcedure name 'Cache_CASetErrorprocedure';
//*
// CASetErrorprocedure - Establish user defined error procedure.
//
//
// To be called on all fatal file errors. If this procedure is
// not called a default procedure will be used. The default error
// procedure reports the error, waits for the user to hit <Enter>
// then halts.
//
// Note : CACache will HALT upon return from the user error procedure.
//
// CALLING SEQUENCE -
//
// CASetErrorprocedure (userprocedure : CAErrorprocedure);
//
// ENTRY -
//
// UserProc : CAErrorprocedure
// User defined procedure described in the example above.
//
// EXIT -
//
// None
// N/A
//
// EXAMPLE -
//
// CASetErrorprocedure (MyErrorProc);
//
// where MyErrorProc is written like the following procedure.
//
// procedure MyErrorProc
// ( errNum : cardinal);
// var errString : array [0 .. 9];
// var success : boolean;
// begin
// Convert.CardToStr (errNum, errString, 4, success);
// WriteString ('Aborting due to fatal error number ');
// WriteString (errString);
// WriteLn;
// WriteString ('Press <Enter> to continue to the main menu.);
// WriteLn;
// ReadString (errString);
// HALT;
// end; // MyErrorProc
//
procedure CAResetErrorProcedure; stdcall; exports CAResetErrorProcedure name 'Cache_CAResetErrorprocedure'; //* // CAResetErrorprocedure - Reset the error procedure to the default. // // // The default error procedure reports the error, waits for the user to // hit <Enter> then halts. // // CALLING SEQUENCE - // // CAResetErrorprocedure; //
procedure CAError
(var vTable : CATable;
const state : cardinal;
var Str : array of char); overload; stdcall;
exports CAError (var vTable : CATable;
const state : cardinal;
var Str : array of char) name 'Cache_CAError';
//*
// CAError - Return description of non fatal errors.
//
//
// CALLING SEQUENCE -
//
// CAError (vTable, state, Str);
//
// ENTRY -
//
// state : cardinal
// Error code from one of the CA procedures.
//
// EXIT -
//
// Str : array of char
// The error string (less than 60).
//
procedure CAError
(var vTable : CATable;
const state : cardinal;
var Str : string); overload; stdcall;
exports CAError (var vTable : CATable;
const state : cardinal;
var Str : string) name 'Cache_STRCAError';
//*
// STRCAError - See documentation of CAError.
//
procedure ReturnFileHandle
(const vTable : CATable;
var FileHandle : Files.STFile); stdcall;
exports ReturnFileHandle name 'Cache_ReturnFileHandle';
function TotalItems
(const vTable : CATable) : cardinal; stdcall;
exports TotalItems name 'Cache_TotalItems';
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance