|
|
|
|
| CAClose | CADelete | CAError | |
| CAGet | CAHigh | CAInit | CAInsert |
| CAMode | CAOpen | CATerminate | ReturnFileHandle |
| TotalItems |
--*
-- CACHE - memory/disk manager 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 limit on
-- the total memory allocated is the disk space available. Cache will not
-- use the disk if the items will fit in memory and CAOpen and CAClose 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. Easier 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 multi-user access.
-- -------------------------------------------------------------
-- CAMode - Set read-only/read-write modes. Default is
-- read-write.
--
--
-- 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 My_Type is record
-- aValue : float;
-- cValue : ModSys.S_Natural;
-- end record;
--
-- (2) Define a pointer to the type:
--
-- type pAccess is access My_Type;
-- pRec : pAccess;
--
-- (3) Define a variable to be used by CACHE.
--
-- vTable : CATable;
--
-- (4) Initialize the cache:
--
-- Cache.CAInit (vTable, My_Type'size/8, 1, "", status);
--
-- (5) Access the items:
--
-- Cache.CAGet (vTable, i, pRec);
--
-- where "i" is an index ranging from 1 to however many are needed.
--
-- (6) The example that follows would initialize the values of 350
-- records of My_Type.
--
-- EXAMPLE -
--
-- with Cache;
-- with ModSys;
-- with System;
-- with TermX;
-- with Unchecked_Conversion;
-- with Unsigned;
--
--
-- procedure MyProg is
--
-- type My_Type is record
-- Value : float;
-- Flag : boolean;
-- end record;
--
-- type My_Type_Access is access My_Type;
--
-- Error_Message : string (1 .. 80) := (others => ASCIIX.Nul);
-- Status : Modsys.S_Natural := 0;
-- VTable : Cache.CATable;
-- PRec : My_Type_Access;
-- Rec_Address : System.Address;
--
-- function Address_To_Access is new Unchecked_Conversion
-- (System.Address, My_Type_Access);
-- begin
-- -- Initialize the cache
-- Cache.CAInit (vTable => VTable,
-- sizX => (My_Type'size/Unsigned.Byte'size),
-- numG => 1,
-- path => "",
-- state => Status);
--
-- -- process all items
-- for I in 1 .. 350 loop
--
-- -- call CAGet for each item
-- Cache.CAGet (vTable => VTable,
-- index => ModSys.S_Natural(I),
-- pRec => Rec_Address);
--
-- -- convert the System.Address to My_Type_Access
-- PRec := Address_To_Access (Rec_Address);
--
-- -- process each item
-- PRec.all.Value := 0.0;
-- PRec.all.Flag := FALSE;
--
-- end loop;
--
-- -- if status is not zero, print a description of the error
-- if Status /= 0 then
-- Cache.CAError (vTable => VTable,
-- state => Status,
-- string2 => Error_Message);
--
-- TermX.WriteString (Str => Error_Message);
-- TermX.WriteLn;
-- end if;
--
-- -- deallocate the resources
-- Cache.CATerminate (vTable => VTable);
-- end MyProg;
--
-- (7) The next example uses an array of items.
--
-- EXAMPLE -
--
-- with Cache;
-- with ModSys;
-- with System;
-- with TermX;
-- with Unchecked_Conversion;
-- with Unsigned;
--
-- procedure MyProg is
-- type My_Type is record
-- Value : float;
-- Flag : boolean;
-- end record;
--
-- type My_Type_Array is array (1..900) of My_Type;
--
-- type My_Type_Array_Access is access My_Type_Array;
--
-- Error_Message : string (1..80) := (others => ASCIIX.Nul);
-- PRec : My_Type_Array_Access;
-- Rec_Address : System.Address;
-- Status : Modsys.S_Natural := 0;
-- VTable : Cache.CATable;
--
-- function Address_To_Access is new Unchecked_Conversion
-- (System.Address, My_Type_Array_Access);
--
-- begin
--
-- -- Initialize the cache
-- Cache.CAInit (vTable => VTable,
-- sizX => (My_Type_Array'size/Unsigned.Byte'size)*900,
-- numG => 1,
-- path => "tht.map",
-- state => Status);
--
-- -- process all groups
-- for I in 1..350 loop
--
-- -- call CAGet for each group
-- Cache.CAGet (vTable => VTable,
-- index => ModSys.S_Natural(I),
-- pRec => Rec_Address);
--
-- -- convert the System.Address to My_Type_Access
-- PRec := Address_To_Access (Rec_Address);
--
-- -- process each item in a group
-- for N in PRec.all'range loop
-- PRec.all(N).Value := 0.0;
-- PRec.all(N).Flag := FALSE;
-- end loop;
--
-- end loop;
--
-- -- if status is not zero, print a description of the error
-- if Status /= 0 then
-- Cache.CAError (vTable => VTable,
-- state => Status,
-- string2 => Error_Message);
--
-- TermX.WriteString (Str => Error_Message);
-- TermX.WriteLn;
-- end if;
--
-- -- deallocate the resources
-- Cache.CATerminate (vTable => VTable);
--
-- end MyProg;
--
type exceptionType is (NoError,
cacheCreateError, -- error in creation of cache file
cachePositionError, -- error positioning within cache file
cacheWriteError, -- error writing to the cache file
cacheReadError, -- error reading from the cache file
cacheCloseError); -- error closing the cache file
cacheException :exception;
cacheError : exceptionType; -- type of cache exception error
cacheErrorLoc : string (1 .. 50) := (others => ASCIIX.nul); -- further description of cache error
type CATable is private;
procedure CAClose
(vTable : in out CATable;
state : in out ModSys.S_Natural);
--*
-- CAClose - Save cache on disk, close files, release resources.
--
--
-- All items or groups will be saved in a disk file for later access and
-- all resources will be released. This procedure takes the place of
-- CATerminate if the cache is to be stored to disk.
--
-- CALLING SEQUENCE -
--
-- CAClose (vTable, state);
--
-- ENTRY -
--
-- vTable : CATable
-- The file table pointer.
--
-- EXIT -
--
-- state : ModSys.S_natural
-- state = 0 means ok to proceed.
-- state <> 0 means some condition is unsatisfactory (see CAError).
--
procedure CADelete
(vTable : in out CATable;
index : in ModSys.S_Natural;
pRec : in out System.Address;
state : in out ModSys.S_Natural);
--*
-- CADelete - Delete the item or column at 'index'.
--
--
-- This procedure deletes the item or group at 'index' and then sets the
-- pointer to replacement item or group.
--
-- CALLING SEQUENCE -
--
-- CADelete (vTable, index, pRec, state);
--
-- ENTRY -
--
-- vTable : CATable
-- The file table pointer.
--
-- index : ModSys.S_Natural
-- Item or group to delete. Requirement - (0 > index <= max items/groups.
--
-- EXIT -
--
-- pRec : System.Address
-- pointer to receive the address of the replacement item or group.
--
-- state : ModSys.S_natural
-- state = 0 means ok to proceed.
-- state <> 0 means some condition is unsatisfactory (see CAError).
--
procedure CAError
(vTable : in out CATable;
state : in ModSys.S_Natural;
string2 : in out string);
--*
-- CAError - Return description of error code.
--
--
-- CALLING SEQUENCE -
--
-- CAError (vTable, state, string2);
--
-- ENTRY -
--
-- state : ModSys.S_natural
-- Error code from one of the CA procedures.
--
-- EXIT -
--
-- string2 : string
-- String less than 60.
--
procedure CAGet
(vTable : in out CATable;
index : in ModSys.S_Natural;
pRec : in out System.Address);
--*
-- 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.S_Natural
-- Item or group to set pointer to. 0 < index <= max # items/groups.
-- Note to users of CAInsert, CADelete - If index = 0 then the CAHigh
-- variable is reset to 0.
--
-- EXIT -
--
-- pRec : System.Address
-- Pointer which will receive the address of the indexed item or group.
--
function CAHigh
(vTable : in CATable) return ModSys.S_Natural;
--*
-- CAHigh - Return the highest item or group referenced.
--
--
-- This function 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.S_Natural
-- Highest item or group referenced (returned as function value).
--
procedure CAInit
(vTable : in out CATable;
sizX : in ModSys.S_Natural;
numG : in ModSys.S_Natural;
Path : in string;
state : in out ModSys.S_Natural);
--*
-- CAInit - Initialize cache.
--
--
-- 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 : CATable
-- The file table pointer. vTable must be unique for each cache.
--
-- sizX : ModSys.S_natural
-- Size of the item being used (in BYTES).
--
-- numG : ModSys.S_natural
-- (numG > 0) Number of items to buffer in memory for processing effici-
-- ency. If CAGet is called with an index greater than numG, then disk
-- storage will be used, requiring a path and file.
--
-- path : string
-- Path and file name to use to create disk storage. If path is nul the
-- DOS default path is used; the default file name will be "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 and file name.
--
-- EXIT -
--
-- state : ModSys.S_natural
-- state = 0 means ok to proceed.
-- state <> 0 means some condition is unsatisfactory (see CAError).
--
procedure CAInsert
(vTable : in out CATable;
index : in ModSys.S_Natural;
pRec : in out System.Address;
state : in out ModSys.S_Natural);
--*
-- 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 index = 0.
--
-- CALLING SEQUENCE -
--
-- CAInsert (vTable, index, pRec, state);
--
-- ENTRY -
--
-- vTable : CATable
-- The file table pointer.
--
-- index : ModSys.S_Natural
-- Item or group before which insert will occur. 0 > index <= max items/groups
--
-- EXIT -
--
-- pRec : System.Address
-- Pointer to receive address of the beginning of the item or group.
--
-- state : ModSys.S_natural
-- state = 0 means ok to proceed.
-- state <> 0 means some condition is unsatisfactory (see CAError).
--
procedure CAMode
(vTable : in out CATable;
mode : in boolean);
--*
-- CAMode - Set read-only or read-write mode.
--
--
-- This procedure sets read-only or read-write (default) 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 caching occurs or
-- when the cache is closed. Read-only is intended to allow multi-user
-- 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 read-write 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
(vTable : in out CATable;
HighVal : in out ModSys.S_Natural;
created : in out boolean;
state : in out ModSys.S_Natural);
--*
-- CAOpen - Open a cache on disk.
--
--
-- This procedure is used to open or reopen a cache which will be or was
-- saved to the disk using CAClose. Note: CAInit must be used immediately
-- before CAOpen.
--
-- CALLING SEQUENCE -
--
-- CAOpen (vTable, HighVal, created, state);
--
-- ENTRY -
--
-- vTable : CATable
-- The file table pointer.
--
-- HighVal : ModSys.S_Natural
-- Set highest referenced item or group (needed only if CAInsert and/or
-- CADelete are used). If high = 0, 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.
--
-- EXIT -
--
-- state : ModSys.S_natural
-- state = 0 means ok to proceed.
-- state <> 0 means some condition is unsatisfactory (see CAError).
--
procedure CATerminate
(vTable : in out CATable);
--*
-- CATerminate - Terminate cache and release resources.
--
--
-- All records will be discarded and all resources will be released. Used
-- in place of CAClose if cache was temporary.
--
-- CALLING SEQUENCE -
--
-- CATerminate (vTable);
--
-- ENTRY -
--
-- vTable : CATable
-- The file table pointer.
--
-- EXIT -
--
-- none
-- N/A
--
function ReturnFileHandle
(vTable : in CATable) return Files.File;
function TotalItems
(vTable : in CATable) return ModSys.S_Natural;
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance