|
|
|
|
| CAClose | CADelete | CAError | CAGet |
| CAHigh | CAInit | CAInsert | CAMode |
| CAOpen | CAResetErrorProcedure | CASetErrorProcedure | CATerminate |
| HandleIsNull | NullHandle | ReturnFileHandle | TotalItems |
PROCEDURE NullHandle
(VAR vTable : CATable);
PROCEDURE HandleIsNull
(CONST vTable : CATable) : BOOLEAN;
PROCEDURE CAInit
(VAR vTable : CATable;
CONST sizX : CARDINAL;
CONST numG : CARDINAL;
CONST Path : ARRAY OF CHAR;
VAR state : CARDINAL);
(**
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 CAGet
(VAR vTable : CATable;
CONST index : ModSys.INT32;
VAR pRec : 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.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 : SYSTEM.ADDRESS
Pointer which will receive the address of the indexed
item or group.
*)
PROCEDURE CAInsert
(VAR vTable : CATable;
CONST index : ModSys.INT32;
VAR pRec : SYSTEM.ADDRESS;
VAR state : CARDINAL);
(**
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 : SYSTEM.ADDRESS
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 TheChar : ModSys.INT32;
VAR pRec : SYSTEM.ADDRESS;
VAR state : CARDINAL);
(**
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 : SYSTEM.ADDRESS
Pointer which will receive the address
of the replacement item or group.
state : CARDINAL
state = 0 means ok to proceed.
state <> 0 means some condition is unsatisfactory (see CAError).
*)
PROCEDURE CAHigh
(CONST vTable : CATable) : ModSys.INT32;
(**
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);
(**
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);
(**
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, HighVal, state);
ENTRY -
vTable : CATable
The file table pointer.
HighVal : 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 -
HighVal : 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 : CARDINAL
state = 0 means ok to proceed.
state <> 0 means some condition is unsatisfactory (see CAError).
*)
PROCEDURE CAClose
(VAR vTable : CATable;
VAR state : CARDINAL);
(**
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);
(**
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);
(**
CASetErrorProcedure - Establish user defined error procedure.
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 -
MyErrorProc : CAErrorProcedure
user defined procedure described in the example above.
EXIT -
None
Note returning from the user procedure will encounter a halt.
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;
(**
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);
(**
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
less than 60.
*)
PROCEDURE ReturnFileHandle
(CONST vTable : CATable;
VAR FileHandle : Files.File);
PROCEDURE TotalItems
(CONST vTable : CATable) : CARDINAL;
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance