|
|
|
|
subtype FilePosition is ModSys.S_FilePosition;
type DISKOP is (Read,
Write,
Modify);
type FileState is (Ok, -- no error
nameError, -- illegal syntax in file name as passed
noFile, -- file with specified name not found
noMemory, -- no memory for file buffers
existingFile, -- file already exists
DeviceError, -- some hardware error during I/O
noMoreRoom, -- no room on volume/medium/directory
accessError, -- protect, read/write, binary/text error
notOpen, -- operation on unopened file
endError, -- read attempted after EOL or EOF
outsideFile, -- position before BOF or after EOF
otherError); -- error unanticipated by this definition
type BinTextMode is (binMode,
textMode);
-- TextMode sees the CTRL-Z as an end-of-file marker.
-- BinMode will allow a CTRL-Z to pass through (such as when
-- writing the file to a printer).
type ReadWriteMode is (ReadOnly,
readWrite,
appendOnly);
type SharingModes is -- DOS Sage depends on enumerated order
(compatibility, -- Same as denyReadWrite, pre-"DOS 3.0"
denyReadWrite, -- Exclusive Read/Write lock on file
denyWrite, -- Make file "Read Only" to others
denyRead,
denyNone); -- No lock on file
type ReplaceMode is (noReplace,
replace);
type PosResult is (PosEqual,
PosLess,
PosGreater);
type File is private;
type DirProcType is access
procedure (FileName : in System.Address;
FileName_High : in ModSys.S_Natural;
ContinueOn : in out boolean);
pragma Convention
(WIN32,
DirProcType);
FilePosition_Zero : constant ModSys.S_FilePosition := (0,
0);
NOPARITY : constant := 0;
ODDPARITY : constant := 1;
EVENPARITY : constant := 2;
MARKPARITY : constant := 3;
SPACEPARITY : constant := 4;
ONESTOPBIT : constant := 0;
ONE5STOPBITS : constant := 1;
TWOSTOPBITS : constant := 2;
XONXOFF : constant := 0;
DTRRTS : constant := 1;
CTSFLOW : constant := 2;
NOFLOW : constant := 3;
type CommStatus is record
cbInQue : ModSys.S_Natural := 0; -- characters in the input que
cbOutQue : ModSys.S_Natural := 0; -- characters in the output que
fCtsHold : boolean := False; -- Tx waiting for CTS signal
fDsrHold : boolean := False; -- Tx waiting for DSR signal
fRlsdHold : boolean := False; -- Tx waiting for DCD signal
fXoffHold : boolean := False; -- Tx waiting, XOFF char recv'd
fXoffSent : boolean := False; -- Tx waiting, XOFF char sent
fEof : boolean := False; -- EOF character sent
fTxim : boolean := False; -- character waiting for Tx
end record;
for CommStatus use record
cbInQue at 0 range 0 .. ModSys.S_Natural_Size - 1;
cbOutQue at 4 range 0 .. ModSys.S_Natural_Size - 1;
fCtsHold at 8 range 0 .. ModSys.Boolean_Size - 1;
fDsrHold at 9 range 0 .. ModSys.Boolean_Size - 1;
fRlsdHold at 10 range 0 .. ModSys.Boolean_Size - 1;
fXoffHold at 11 range 0 .. ModSys.Boolean_Size - 1;
fXoffSent at 12 range 0 .. ModSys.Boolean_Size - 1;
fEof at 13 range 0 .. ModSys.Boolean_Size - 1;
fTxim at 14 range 0 .. ModSys.Boolean_Size - 1;
end record;
type CommError is record
CE_RXOVER : boolean := False;
CE_OVERRUN : boolean := False;
CE_RXPARITY : boolean := False;
CE_FRAME : boolean := False;
CE_BREAK : boolean := False;
CE_TXFULL : boolean := False;
CE_PTO : boolean := False;
CE_IOE : boolean := False;
CE_DNS : boolean := False;
CE_OOP : boolean := False;
CE_MODE : boolean := False;
end record;
for CommError use record
CE_RXOVER at 0 range 0 .. ModSys.Boolean_Size - 1;
CE_OVERRUN at 1 range 0 .. ModSys.Boolean_Size - 1;
CE_RXPARITY at 2 range 0 .. ModSys.Boolean_Size - 1;
CE_FRAME at 3 range 0 .. ModSys.Boolean_Size - 1;
CE_BREAK at 4 range 0 .. ModSys.Boolean_Size - 1;
CE_TXFULL at 5 range 0 .. ModSys.Boolean_Size - 1;
CE_PTO at 6 range 0 .. ModSys.Boolean_Size - 1;
CE_IOE at 7 range 0 .. ModSys.Boolean_Size - 1;
CE_DNS at 8 range 0 .. ModSys.Boolean_Size - 1;
CE_OOP at 9 range 0 .. ModSys.Boolean_Size - 1;
CE_MODE at 10 range 0 .. ModSys.Boolean_Size - 1;
end record;
procedure GetCommState
(File1 : in out File;
baud : in out ModSys.S_Natural;
Data : in out ModSys.S_Natural;
Parity : in out ModSys.S_Natural;
stop : in out ModSys.S_Natural;
done : in out boolean);
procedure SetCommState
(File1 : in out File;
baud : in ModSys.S_Natural;
Data : in ModSys.S_Natural;
Parity : in ModSys.S_Natural;
stop : in ModSys.S_Natural;
done : in out boolean);
procedure SetCommFlow
(File1 : in out File;
flow : in ModSys.S_Natural;
done : in out boolean);
procedure GetCommTimeouts
(File1 : in out File;
readTimeout : in out ModSys.S_Natural;
readMultiplier : in out ModSys.S_Natural;
readConstant : in out ModSys.S_Natural;
writeMultiplier : in out ModSys.S_Natural;
writeConstant : in out ModSys.S_Natural;
done : in out boolean);
procedure SetCommTimeouts
(File1 : in out File;
readTimeout : in ModSys.S_Natural;
readMultiplier : in ModSys.S_Natural;
readConstant : in ModSys.S_Natural;
writeMultiplier : in ModSys.S_Natural;
writeConstant : in ModSys.S_Natural;
done : in out boolean);
procedure ClearCommError
(File1 : in out File;
errors : in out CommError;
Status : in out CommStatus;
done : out boolean);
procedure CalcFilePos
(File1 : in out File;
Pos : out FilePosition;
NumOfElements : in ModSys.S_Integer;
ElementLength : in ModSys.S_Natural);
--*
-- CalcFilePos - Calculate new file position.
--
-- Calculate a file position relative to a given file position ('pos')
-- offset by NumOfElements. Return the resulting file position.
--
-- CALLING SEQUENCE -
--
-- CalcFilePos (File1, pos, NumOfElements, ElementLength)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- pos : FilePosition
-- The position to begin with.
--
-- NumOfElements : ModSys.S_integer
-- Number of elements (records) to offset the given position (pos)
-- with (-n..+n).
--
-- ElementLength : ModSys.S_Natural
-- The byte length of each element (record).
--
-- EXIT -
--
-- pos : FilePosition
-- The resultant position. Note - The position is not set. This must
-- be done using SetFilePos.
--
procedure Close
(File1 : in out File;
state : out FileState);
--*
-- Close - Close and save file.
--
-- This procedure closes a file that has already been opened by one of the
-- standard procedures supplied in this library.
--
-- CALLING SEQUENCE -
--
-- Close (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure Create
(File1 : out File;
FileName : in string;
BinText : in BinTextMode;
ReplMode : in ReplaceMode;
state : out FileState);
--*
-- Create - Create new external file.
--
-- This procedure creates a new file. If the named file already exists,
-- then that file will be overwritten when the 'ReplMode' variable is set
-- to replace. Otherwise, no file will be created and an error will be
-- returned.
--
-- CALLING SEQUENCE -
--
-- Create (file1, Fileame, BinText, ReplMode, state);
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- FileName : string
-- Name of the file to be created. This may optionally include the
-- drive and/or directories.
--
-- BinText : BinTextMode
-- Mode of the file to be opened. This includes the enumerated values
-- BinMode and TextMode where TextMode treats the CTRL-Z as an end-of-file
-- marker and BinMode will allow a CTRL-Z to pass through (such as when
-- writing the file to a printer).
--
-- ReplMode : ReplaceMode
-- Replace mode of the file to create. This includes the enumerated
-- values NoReplace and Replace.
--
-- EXIT -
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure Delete
(FileName : in string;
state : out FileState);
--*
-- Delete - Delete file.
--
-- This procedure allows the developer to delete a specific file.
--
-- CALLING SEQUENCE -
--
-- Delete (filename, state);
--
-- ENTRY -
--
-- filename : string
-- Name of the file to delete
--
-- EXIT -
--
-- state : FileState
-- State resulting from the action.
--
procedure DirQuery
(Wild : in string;
DirProc : in DirProcType;
state : out FileState);
--*
-- DirQuery - Query system for specified file(s).
--
--
-- DirQuery allows the querying of files by name much the same as the DOS
-- DIR (or Unix ls) command. The 'Wild' variable is set to a file name
-- (that may include '*' and/or '?' characters). This procedure then calls
-- DirProc to process each file name that meets the wild-card
-- specification. DirQuery stops calling DirProc whenever DirProc returns
-- FALSE for the 'ContinueOn' value.
--
-- The DirQuery procedure is instantiated with a user-supplied procedure
-- that is passed the name of each file found and returns a variable
-- indicating whether the process should continue. This procedure must
-- have the following format:
--
-- procedure DirProc
-- (filename : in string;
-- ContinueOn : in out boolean);
--
-- CALLING SEQUENCE -
--
-- Files.DirQuery (Wild, MyProc, state)
--
-- ENTRY -
--
-- Wild : string
-- String containing a file name and/or wild card values to represent the
-- file name(s) to be located. This is compatible with the DOS file name
-- and wild card format (use '*' and '?' characters as wild card values).
--
-- EXIT -
--
-- state : FileState
-- The state.
--
-- EXAMPLE -
--
-- with Files;
-- with TermX;
--
-- procedure ListFiles is
--
-- state : Files.FileState;
--
-- procedure MyList
-- (fileName : in string;
-- ContinueOn : in out boolean) is
-- begin
-- TermX.WriteString (fileName);
-- TermX.WriteLn;
-- ContinueOn := TRUE;
-- end MyList;
--
-- procedure MyDir is new Files.DirQuery
-- (MyList);
--
-- begin
-- MyDir ("*.*", state);
-- end ListFiles;
--
procedure DiskIO
(FileHandle : in out File;
Operation : in DISKOP;
Buffer : in System.Address;
DiskAddress : in FilePosition;
Number : in ModSys.S_Natural;
Error : out ModSys.S_Natural);
--*
-- DiskIO - Perform I/O operations to disk.
--
-- This routine performs the necessary procedures to allow the user to
-- read, write, or modify data on a disk file.
--
-- CALLING SEQUENCE -
--
-- DiskIO (FileHandle, Operation, Buffer, DiskAddress, Number, Error)
--
-- ENTRY -
--
-- FileHandle : File
-- A file variable referencing an open file.
--
-- Operation : DISKOP
-- Operation to perform on the disk. This will be READ, WRITE, or MODIFY.
--
-- Buffer : System.Address
-- The address of the data buffer.
--
-- DiskAddress : FilePosition
-- The disk address where the operation is to be performed.
--
-- Number : ModSys.S_Natural
-- The number of bytes to transfer in the operation.
--
-- EXIT -
--
-- Buffer : System.Address
-- A modified array may be returned.
--
-- Error : ModSys.S_natural
-- Error flag returned indicating the status of the disk operation.
--
procedure EOF
(File1 : in out File;
flag : out boolean);
--*
-- EOF - End of file error return.
--
-- This procedure returns the 'flag' as TRUE if the last operation was not
-- performed due to an end-of-file error.
--
-- CALLING SEQUENCE -
--
-- EOF (file1, flag)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- flag : boolean
-- TRUE if an end-of-file condition exists.
--
procedure GetBOF
(File1 : in out File;
Pos : out FilePosition);
--*
-- GetBOF - Get first position in file.
--
-- Return the first position or the start of the file.
--
-- CALLING SEQUENCE -
--
-- GetBOF (File1, pos)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- EXIT -
--
-- pos : FilePosition
-- The first position in the file.
--
procedure GetEOF
(File1 : in out File;
Pos : out FilePosition);
--*
-- GetEOF - Get last position of file.
--
-- Return the position in the file which is 1 beyond the last actual byte
-- of the file.
--
-- CALLING SEQUENCE -
--
-- GetEOF (File1, pos)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- EXIT -
--
-- pos : FilePosition
-- The position 1 byte beyond last actual byte on file. For an empty
-- file, this will be returned as zero.
--
-- EXAMPLE -
--
-- with Files;
-- with ModSys;
--
-- procedure AppendToFile is
--
-- f : Files.File;
-- state : Files.FileState;
-- buffer : string (1..16);
-- filePos : ModSys.S_Natural;
--
-- begin
-- Files.Open (f, "DEST.DAT", Files.BinMode, Files.ReadWrite, state);
-- Files.GetEOF (f, filePos);
-- Files.SetFilePos (f, filePos, state);
-- buffer := "Last of the file";
-- Files.WriteBytes (f, buffer'address, 16, state);
-- Files.Close (f, state);
-- end AppendToFile;
--
procedure GetFileHandle
(File1 : in File;
handle : out DosLib.HandleType);
procedure GetFileName
(File1 : in out File;
FileName : out string;
state : out FileState);
--*
-- GetFileName - Return file name.
--
-- This procedure returns the complete and unambiguous name of the file
-- associated with the file handle.
--
-- CALLING SEQUENCE -
--
-- GetFileName (file1, FileName, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- FileName : string
-- The name of the file.
--
-- state : FileState
-- The state.
--
procedure GetPathFileName
(File1 : in out File;
PathFileName : out string;
state : out FileState);
--*
-- GetPathFileName - Return the complete file name including path.
--
-- This procedure returns the complete and unambiguous name of the
-- file associated with the file handle including its path. The
-- return name will include the path to the file even if the
-- original name passed in did not include a path.
--
-- CALLING SEQUENCE -
--
-- GetPathFileName (File1, PathFileName, state)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- EXIT -
--
-- PathFileName : string
-- The name of the file including the path.
--
-- State : FileState
-- The state.
--
procedure GetFilePos
(File1 : in out File;
Pos : out FilePosition);
--*
-- GetFilePos - Get current file position.
--
-- Return the current position in the open file specified by the supplied
-- file handle.
--
-- CALLING SEQUENCE -
--
-- GetFilePos (File1, pos)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- EXIT -
--
-- pos : FilePosition
-- Current position in file (0..n) where 0 is the first byte of the file.
--
function GetInheritMode return ModSys.S_Natural; --* -- GetInheritMode - Return the set inheritance mode. -- -- This function returns the current setting of the -- inheritance mode. -- -- CALLING SEQUENCE - -- -- mode := GetInheritMode; -- -- EXIT - -- -- mode : ModSys.S_Natural -- Set to '0' if child process is to inherit the -- parent files, or '1' if the child processes -- are not to inherit the parent files. --
function GetSharingModes return SharingModes; --* -- GetSharingModes - Get current sharing mode. -- -- The various access rights options can be found in the DosLib -- specification file (e.g., OpenReadOnly, OpenWriteOnly, OpenReadWrite, -- etc.). The default is OpenExclusive. -- -- CALLING SEQUENCE - -- -- mode := GetSharingModes; -- -- ENTRY - -- -- None -- N/A -- -- EXIT - -- -- mode : SharingModes -- The current sharing mode. --
procedure Lookup
(FileHandle : out File;
FileName : in string;
NewF : in boolean;
state : out FileState);
--*
-- Lookup - Open and/or create file.
--
-- This procedure combines the Open and Create process. A file may be
-- requested to be opened and optionally created if it does not exist
-- already.
--
-- CALLING SEQUENCE -
--
-- Lookup (FileHandle, FileName, NewF, State)
--
-- ENTRY -
--
-- FileHandle : File
-- The file handle.
--
-- FileName : string
-- The name of the file.
--
-- NewF : boolean
-- Create a new file if the specified file does not exist (TRUE).
--
-- EXIT -
--
-- State : FileState
-- The state.
--
procedure LookupRead
(FileHandle : out File;
FileName : in string;
NewF : in boolean;
state : out FileState);
--*
-- LookupRead - Open and/or create file read only.
--
-- This procedure combines the Open and Create process. A file may be
-- requested to be opened and optionally created if it does not exist
-- already.
--
-- CALLING SEQUENCE -
--
-- LookupRead (FileHandle, FileName, NewF, State)
--
-- ENTRY -
--
-- FileHandle : File
-- The file handle.
--
-- FileName : string
-- The name of the file.
--
-- NewF : boolean
-- Create a new file if the specified file does not exist (TRUE).
--
-- EXIT -
--
-- State : FileState
-- The state.
--
procedure Open
(File1 : out File;
FileName : in string;
BinText : in BinTextMode;
WriteMode : in ReadWriteMode;
state : out FileState);
--*
-- Open - Open existing external file.
--
-- This procedure opens an existing file and returns an error if that
-- file is not present.
--
-- CALLING SEQUENCE -
--
-- Open (file1, FileName, BinText, WriteMode, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- FileName : string
-- Name of the file to open. This may optionally include the drive
-- and/or directories.
--
-- BinText : BinTextMode
-- Mode of the file to open. This includes the enumerated values BinMode
-- and TextMode where TextMode treats the CTRL-Z as an end-of-file marker
-- and BinMode will allow a CTRL-Z to pass through (such as when writing
-- the file to a printer).
--
-- WriteMode : ReadWriteMode
-- Write mode in which to open the file. This includes the enumerated
-- values ReadOnly, ReadWrite, and AppendOnly.
--
-- EXIT -
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure ReadBlock
(File1 : in out File;
block : out ModSys.Byte_U_Array;
state : out FileState);
--*
-- ReadBlock - Read data from binary file.
--
-- This procedure reads a block of binary data from a file beginning at
-- the current position. As much data as can be contained within the
-- supplied array will be read. After the read, the current position will
-- be updated by the number of bytes read.
--
-- CALLING SEQUENCE -
--
-- ReadBlock (file1, block, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- block : Modsys.byte_u_array
-- Array to receive data. If the end-of-file was reached first, it may
-- be detected by using the EOF procedure.
--
-- state : FileState
-- The state.
--
procedure ReadByte
(File1 : in out File;
byte1 : out Unsigned.BYTE;
state : out FileState);
--*
-- ReadByte - Read one byte from file.
--
-- This procedure reads one byte of information from a binary file from
-- the current position. After reading, the current position of the file
-- is one byte beyond the previous position.
--
-- CALLING SEQUENCE -
--
-- ReadByte (file1, byte1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- byte1 : Unsigned.byte
-- The byte read from the file.
--
-- state : FileState
-- The state.
--
procedure ReadBytes
(File1 : in out File;
addr : in System.Address;
bytes : in ModSys.S_Natural;
bytesRead : out ModSys.S_Natural;
state : out FileState);
--*
-- ReadBytes - Read specified number of bytes from file.
--
-- This procedure reads a specified number of bytes from a file beginning
-- at the current position of the file. After the read, the current
-- position will be updated by the number of bytes read.
--
-- CALLING SEQUENCE -
--
-- ReadBytes (file1, addr, bytes, bytesRead, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- addr : System.Address
-- The address into which the data is to be read.
--
-- bytes : ModSys.S_Natural
-- The number of bytes requested to be read.
--
-- EXIT -
--
-- bytesRead : ModSys.S_Natural
-- The actual number of bytes read into the specified address.
--
-- state : FileState
-- The state.
--
-- EXAMPLE -
--
-- with Files;
-- with ModSys;
--
-- procedure CopyFile is
--
-- bufSize : constant := 1_000;
--
-- f1 : Files.File;
-- f2 : Files.File;
-- state1 : Files.FileState;
-- state2 : Files.FileState;
-- buffer : string (1..bufSize);
-- bytesRead : ModSys.S_Natural;
-- finished : boolean;
--
-- begin
-- Open (f1, "SOURCE.DAT", Files.BinMode, Files.ReadWrite, state1);
-- Create (f2, "DEST.DAT", Files.BinMode, Files.Replace, state2);
--
-- loop
-- ReadBytes (f1, buffer'address, bufSize, bytesRead, state1);
-- EOF (f1, finished);
-- exit when finished;
-- WriteBytes (f2, buffer'address, bytesRead, state2);
-- end loop;
--
-- Close (f1, state1);
-- Close (f2, state2);
-- end CopyFile;
--
procedure ReadWord
(File1 : in out File;
word1 : out Unsigned.WORD;
state : out FileState);
--*
-- ReadWord - Read one word from file.
--
-- This procedure reads one word of information from a binary file from
-- the current position. After reading, the current position of the file
-- is one word beyond the previous position.
--
-- CALLING SEQUENCE -
--
-- ReadWord (file1, word1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- word1 : Unsigned.word
-- The word read from the file.
--
-- state : FileState
-- The state.
--
procedure Remove
(File1 : in out File;
state : out FileState);
--*
-- Remove - Close file, remove external file.
--
-- This procedure closes a file that was opened using one of the standard
-- procedures in this library. The file is then removed (deleted).
--
-- CALLING SEQUENCE -
--
-- Remove (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure Rename
(fromName : in string;
toName : in string;
state : out FileState);
--*
-- Rename - Change file name.
--
-- This procedure allows the developer to change the file name.
--
-- CALLING SEQUENCE -
--
-- Rename (fromName, toName, state);
--
-- ENTRY -
--
-- fromName : string
-- Old file name
--
-- toName : string
-- New file name
--
-- EXIT -
--
-- state : FileState
-- The file state after the operation.
--
procedure Reset
(File1 : in out File;
state : out FileState);
--*
-- Reset - Reposition open file to beginning.
--
-- This procedure causes an open file to be repositioned to the beginning.
-- This is the default condition when a file is first opened or created.
--
-- CALLING SEQUENCE -
--
-- Reset (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure ResetState
(File1 : in out File;
state : out FileState);
--*
-- ResetState - Reset error state to allow continued operation.
--
-- This procedure resets the state variable to allow continued operation.
-- If an error state was detected, most file operations would not be
-- allowed to continue. This reevaluates the EOF/EOL (end-of-file) so
-- that it indicates a file position instead of an error.
--
-- CALLING SEQUENCE -
--
-- ResetState (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- state : FileState
-- The state.
--
procedure Rewrite
(File1 : in out File;
state : out FileState);
--*
-- Rewrite - Reposition to start of file & truncate it.
--
-- This procedure repositions to the start of the file and truncates it
-- from there, effectively removing all of the data from the file just as
-- it was when first created.
--
-- CALLING SEQUENCE -
--
-- Rewrite (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure SetFilePos
(File1 : in out File;
Pos : in FilePosition;
state : out FileState);
--*
-- SetFilePos - Set current file position.
--
-- This procedure sets the current file position. An illegal position
-- leaves the position as it was and returns an error state.
--
-- CALLING SEQUENCE -
--
-- SetFilePos (File1, pos, state)
--
-- ENTRY -
--
-- File1 : File
-- The file handle.
--
-- pos : FilePosition
-- The location to set the current position to (0..n).
--
-- EXIT -
--
-- state : FileState
-- The state.
--
procedure SetInheritMode
(mode : in ModSys.S_Natural);
--*
-- SetInheritMode - Sets inheritance for child processes.
--
-- This procedure defines the inheritance of a parent's
-- files by a child process.
--
-- CALLING SEQUENCE -
--
-- SetInheritMode (mode)
--
-- ENTRY -
--
-- mode : ModSys.S_Natural
-- Set to '0' if child process is to inherit the
-- parent files, or '1' if the child processes
-- are not to inherit the parent files.
--
procedure SetSharingModes
(mode : in SharingModes);
--*
-- SetSharingModes - Set sharing mode of file.
--
-- The various access rights choices can be found in the DosLib
-- specification file (e.g., OpenReadOnly, OpenWriteOnly, OpenReadWrite,
-- etc.). The default is OpenExclusive.
--
-- CALLING SEQUENCE -
--
-- SetSharingModes (mode);
--
-- ENTRY -
--
-- mode : SharingModes
-- The sharing mode desired for the file.
--
function State1
(File1 : in File) return FileState;
--*
-- State1 - Return current state of file.
--
-- This function returns the current state of the file as set by a
-- previous operation.
--
-- CALLING SEQUENCE -
--
-- s := State1 (file1)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- EXIT -
--
-- State : FileState
-- This may be one of the following - ok noMoreRoom
-- nameError accessError
-- noFile notOpen
-- noMemory endError
-- existingFile outsideFile
-- deviceError otherError
--
procedure Truncate
(File1 : in out File;
state : out FileState);
--*
-- Truncate - Set physical end of file to current position.
--
-- This procedure truncates the file at the current position.
--
-- CALLING SEQUENCE -
--
-- Truncate (file1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- state : FileState
-- The status of the requested operation (ok => successful).
--
procedure WriteBlock
(File1 : in out File;
block : out ModSys.Byte_U_Array;
state : out FileState);
--*
-- WriteBlock - Write one block of data to file.
--
-- This procedure writes one block of data to the file at the current
-- position. After the write, the current position is updated by the
-- block size. If at the end of the file, the file size increases by that
-- block size.
--
-- CALLING SEQUENCE -
--
-- WriteBlock (file1, block, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- block : ModSys.byte_u_array
-- The block to be written.
--
-- EXIT -
--
-- state : FileState
-- The state.
--
procedure WriteByte
(File1 : in out File;
byte1 : in Unsigned.BYTE;
state : out FileState);
--*
-- WriteByte - Write one byte of data to file.
--
-- This procedure writes one byte of data to the file at the current
-- position. After the write, the current position is updated by one
-- byte. If at the end of the file, the file size increases by one byte.
--
-- CALLING SEQUENCE -
--
-- WriteByte (file1, byte1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- byte1 : Unsigned.byte
-- The byte to be written.
--
-- EXIT -
--
-- state : FileState
-- The state.
--
procedure WriteBytes
(File1 : in out File;
addr : in System.Address;
bytes : in ModSys.S_Natural;
state : out FileState);
--*
-- WriteBytes - Write bytes of data to file.
--
-- This procedure writes a specified number of bytes of data to a file at
-- the current position from the specified memory location (ADDRESS).
--
-- CALLING SEQUENCE -
--
-- WriteBytes (file1, addr, bytes, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- addr : System.Address
-- The memory location to retrieve the data from for the write.
--
-- bytes : ModSys.S_Natural
-- Number of bytes to write from specified memory location onto file.
--
-- EXIT -
--
-- state : FileState
-- The state.
--
-- EXAMPLE -
--
-- with Files;
-- with ModSys;
--
-- procedure CopyFile is
--
-- bufSize : constant := 1_000;
--
-- f1 : Files.File;
-- f2 : Files.File;
-- state1 : Files.FileState;
-- state2 : Files.FileState;
-- buffer : string (1..bufSize);
-- bytesRead : ModSys.S_Natural;
-- finished : boolean;
--
-- begin
-- Open (f1, "SOURCE.DAT", Files.BinMode, Files.ReadWrite, state1);
-- Create (f2, "DEST.DAT", Files.BinMode, Files.Replace, state2);
--
-- loop
-- ReadBytes (f1, buffer'address, bufSize, bytesRead, state1);
-- EOF (f1, finished);
-- exit when finished;
-- WriteBytes (f2, buffer'address, bytesRead, state2);
-- end loop;
--
-- Close (f1, state1);
-- Close (f2, state2);
-- end CopyFile;
--
procedure WriteWord
(File1 : in out File;
word1 : in Unsigned.WORD;
state : out FileState);
--*
-- WriteWord - Write one word of data to file.
--
-- This procedure writes one word of data to the file at the current
-- position. After the write, the current position is updated by one
-- word. If at the end of the file, the file size increases by one word.
--
-- CALLING SEQUENCE -
--
-- WriteWord (file1, word1, state)
--
-- ENTRY -
--
-- file1 : File
-- The file handle.
--
-- word1 : unsigned.word
-- The word to be written.
--
-- EXIT -
--
-- state : FileState
-- The state.
--
procedure CopyFile
(SourceFile : in string;
DestFile : in string;
PreserveDate : in boolean;
Success : in out boolean);
--*
-- CopyFile - Copy a file from one place to another.
--
--
-- This procedure copies the SourceFile to the DestFile. If the
-- DestFile exists it is overwritten.
--
-- CALLING SEQUENCE -
--
-- CopyFile (SourceFile, DestFile, PreserveDate, Success);
--
-- ENTRY -
--
-- SourceFile : String
-- The complete name (including path to copy from).
--
-- DestFile : String
-- The complete name (including path to copy to).
--
-- PreserveDate : boolean
-- True - Keep the original date and time of the file
-- False - Set date and time to the copy date and time
--
-- EXIT -
--
-- Success : Boolean
-- True - The copy was completed okay.
-- False - The copy could not be completed.
--
procedure ConcatFiles
(SourceFile1 : in string;
SourceFile2 : in string;
Success : out boolean);
--*
-- ConcatFiles - Concat SourceFile1 + SourceFile2.
--
--
-- This procedure concats SourceFile2 onto the end of SourceFile1.
-- If SourceFile1 does not exist it will be created.
--
-- CALLING SEQUENCE -
--
-- ConcatFiles (SourceFile1, SourceFile2, Success);
--
-- ENTRY -
--
-- SourceFile1 : string
-- The complete name (including path to copy from) of the first
-- file in the concatenation.
--
-- SourceFile2 : string
-- The complete name (including path to copy from) of the first
-- file in the concatenation.
--
-- EXIT -
--
-- Success : boolean
-- TRUE - The concat was completed okay.
-- FALSE - The concat could not be completed.
--
function FileExists
(FileName : in string) return boolean;
--*
-- FileExists - Returns a boolean to indicate the files existence.
--
--
-- This procedure checks to see if a file exists and returns a boolean
-- indicating the result. The FileName should include the full path unless
-- the current directory is being checked. You may also use wildcard
-- characters in the filename to check for the existence of any files
-- matching the string.
--
-- CALLING SEQUENCE -
--
-- FileExists (FileName);
--
-- ENTRY -
--
-- FileName : String
-- The complete name (including path if needed) to look for.
--
-- EXIT -
--
-- BOOLEAN
-- TRUE - The indicated file was found.
-- FALSE - The indicated file was NOT found.
--
function GetHandleState
(handle : in File) return ModSys.HandleState;
--*
-- GetHandleState - Gets the current state of the handle (HandleOpened or HandleClosed).
--
--
-- This procedure gets the state of the handle. It returns one of two values depending
-- on whether the handle is currently open or closed.
--
-- CALLING SEQUENCE -
--
-- GetHandleState (Handle);
--
-- ENTRY -
--
-- Handle : File
-- The file handle to be tested.
--
-- EXIT -
--
-- HandleState
-- HandleClosed - The handle is currently closed.
-- HandleOpen - The handle is open for use.
--
procedure SetToValue
(ThePosition : in out FilePosition;
TheValue : in FilePosition);
--*
-- SetToValue - Compiler portable way of setting to a value within a range.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of setting the position variable to a given value.
--
-- CALLING SEQUENCE -
--
-- SetToValue (ThePosition, TheValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The variable to be set to a value.
--
-- TheValue : FilePosition
-- A value to be assigned to the file position variable.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The FilePosition variable set to the value.
--
procedure SetToValueByNum
(ThePosition : in out FilePosition;
TheValue : in ModSys.S_Natural);
--*
-- SetToValueByNum - Compiler portable way of setting to a value within a range.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of setting the position variable to a given value.
--
-- CALLING SEQUENCE -
--
-- SetToValueByNum (ThePosition, TheValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The variable to be set to a value.
--
-- TheValue : ModSys.S_Natural
-- A value to be assigned to the file position variable.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The FilePosition variable set to the value.
--
procedure AddToPosition
(ThePosition : in out FilePosition;
AddValue : in FilePosition);
--*
-- AddToPosition - Compiler portable way of adding to a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of adding to the current position.
--
-- CALLING SEQUENCE -
--
-- AddToPosition (ThePosition, AddValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- AddValue : FilePosition
-- The amount to be added to ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition incremented by AddValue.
--
procedure AddToPositionByNum
(ThePosition : in out FilePosition;
AddValue : in ModSys.S_Natural);
--*
-- AddToPositionByNum - Compiler portable way of adding to a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of adding to the current position.
--
-- CALLING SEQUENCE -
--
-- AddToPositionByNum (ThePosition, AddValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- AddValue : ModSys.S_Natural
-- The amount to be added to ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition incremented by AddValue.
--
procedure SubtractFromPosition
(ThePosition : in out FilePosition;
SubtractValue : in FilePosition);
--*
-- SubtractFromPosition - Compiler portable way of subtacting from a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of subtracting from the current position.
--
-- WARNING - If the result of the operation would be a value less than zero
-- and minor error checking is on you will get a popup that the range min
-- has been exceeded.
--
-- CALLING SEQUENCE -
--
-- SubtractFromPosition (ThePosition, SubtractValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- SubtractValue : FilePosition
-- The amount to be subtracted from ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition decremented by SubtractValue. If the
-- SubtractValue was larger than ThePosition then ThePosition is
-- set to zero.
--
procedure SubtractFromPositionByNum
(ThePosition : in out FilePosition;
SubtractValue : in ModSys.S_Natural);
--*
-- SubtractFromPositionByNum - Compiler portable way of subtacting from a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of subtracting from the current position.
--
-- WARNING - If the result of the operation would be a value less than zero
-- and minor error checking is on you will get a popup that the range min
-- has been exceeded.
--
-- CALLING SEQUENCE -
--
-- SubtractFromPositionByNum (ThePosition, SubtractValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- SubtractValue : ModSys.S_Natural
-- The amount to be subtracted from ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition decremented by SubtractValue. If the
-- SubtractValue was larger than ThePosition then ThePosition is
-- set to zero.
--
procedure MultiplyPosition
(ThePosition : in out FilePosition;
MultiplyValue : in ModSys.S_Natural);
--*
-- MultiplyPosition - Compiler portable way of multiplying a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of multiplying the current position.
--
-- CALLING SEQUENCE -
--
-- MultiplyPosition (ThePosition, MultiplyValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- MultiplyValue : ModSys.S_Natural
-- The amount to multiply the ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition multiplied by MultiplyValue.
--
procedure DividePosition
(ThePosition : in out FilePosition;
DivideValue : in ModSys.S_Natural);
--*
-- DividePosition - Compiler portable way of dividing a file position.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of dividing the current position.
--
-- CALLING SEQUENCE -
--
-- DividePosition (ThePosition, DivideValue);
--
-- ENTRY -
--
-- ThePosition : FilePosition
-- The current/starting value of the file position.
--
-- DivideValue : ModSys.S_Natural
-- The amount to divide the ThePosition.
--
-- EXIT -
--
-- ThePosition : FilePosition
-- The new value of FilePosition divided by DivideValue.
--
function ComparePositions
(Position1 : in FilePosition;
Position2 : in FilePosition) return PosResult;
--*
-- ComparePositions - Compiler portable way of comparing file positions.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of comparing two file positions. The return value of this
-- routine is the relationship of Position1 vs. Position2.
--
-- CALLING SEQUENCE -
--
-- ComparePositions (Position1, Position2);
--
-- ENTRY -
--
-- Position1 : FilePosition
-- The first position. The return value will show how this value is related
-- to Position2.
--
-- Position2 : FilePosition
-- The second position. The return value will show where Position1 is relative
-- to this value.
--
-- EXIT -
--
-- PosResult
-- PosEqual - The two positions are exactly equal.
-- PosLess - Position2 is less than Position1.
-- PosGreater - Position 2 is greater then Position1.
--
function ComparePositionsByNum
(Position1 : in FilePosition;
Position2 : in ModSys.S_Natural) return PosResult;
--*
-- ComparePositions - Compiler portable way of comparing file positions.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of comparing two file positions. The return value of this
-- routine is the relationship of Position1 vs. Position2.
--
-- CALLING SEQUENCE -
--
-- ComparePositions (Position1, Position2);
--
-- ENTRY -
--
-- Position1 : FilePosition
-- The first position. The return value will show how Position2 compares
-- to this value.
--
-- Position2 : CARDINAL
-- The second position. The return value will show where this position
-- is relative to Position1.
--
-- EXIT -
--
-- PosResult
-- PosEqual - The two positions are exactly equal.
-- PosLess - Position2 is less than Position1.
-- PosGreater - Position 2 is greater then Position1.
--
procedure PositionDifference
(Position1 : in FilePosition;
Position2 : in FilePosition;
Difference : in out FilePosition);
--*
-- PositionDifference - Compiler portable way of finding the difference in two positions.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of calculating the difference in two file positions. The
-- return value of this routine is the distance between the values of Position1
-- and Position2. NOTE - the return value is the absolute difference. It does
-- not matter if Position1 is larger, smaller or equal to Position2 the return
-- value will always be in the range of 0 .. N.
--
-- CALLING SEQUENCE -
--
-- PositionDifference (Position1, Position2, Difference);
--
-- ENTRY -
--
-- Position1 : FilePosition
-- The first position. The return value will show the distance between
-- Position2 and this value.
--
-- Position2 : FilePosition
-- The second position. The return value will show the distance between
-- Position1 and this value.
--
-- EXIT -
--
-- Difference : FilePosition
-- The absolute value of the distance between the two positions.
--
procedure PositionDifferenceByNum
(Position1 : in FilePosition;
Position2 : in FilePosition;
Difference : in out ModSys.S_Natural);
--*
-- PositionDifferenceByNum - Compiler portable way of finding the difference in two positions.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of calculating the difference in two file positions. The
-- return value of this routine is the distance between the values of Position1
-- and Position2. NOTE - the return value is the absolute difference. It does
-- not matter if Position1 is larger, smaller or equal to Position2 the return
-- value will always be in the range of 0 .. N.
--
-- WARNING - If the result of the operation would be a value greater than the
-- capacity of a ModSys.S_Natural value and minor error checking is on you will get a
-- popup that the range max has been exceeded.
--
-- CALLING SEQUENCE -
--
-- PositionDifferenceByNum (Position1, Position2, Difference);
--
-- ENTRY -
--
-- Position1 : FilePosition
-- The first position. The return value will show the distance between
-- Position2 and this value.
--
-- Position2 : FilePosition
-- The second position. The return value will show the distance between
-- Position1 and this value.
--
-- EXIT -
--
-- Difference : ModSys.S_Natural
-- The absolute value of the distance between the two positions.
--
procedure ConvertPositionToNum
(Position : in FilePosition;
NumValue : in out ModSys.S_Natural);
--*
-- ConvertPositionToNum - Compiler portable way of converting to a number.
--
--
-- Not every compiler used by SageST supports the 64 bit numbers necessary to
-- track a file position. This routine provides a safe mechanism to do
-- arithmetic operations on the FilePosition type. This particular routine
-- provides a method of converting the position back to a number.
--
-- WARNING - If the result of the operation would be a value greater than the
-- capacity of a ModSys.S_Natural value and minor error checking is on you will get a
-- popup that the range max has been exceeded.
--
-- CALLING SEQUENCE -
--
-- ConvertPositionToNum (Position, NumValue);
--
-- ENTRY -
--
-- Position : FilePosition
-- The current position. The return value is this position converted to
-- a simple number.
--
-- EXIT -
--
-- NumValue : ModSys.S_Natural
-- The value of Position in a simple number.
--
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance