|
|
|
|
type FileNameType is (invalidName,
singleName,
wildName);
function TypeOfFileName
(FileName : in string) return FileNameType;
--*
-- TypeOfFileName - Checks a file name and returns general type info about it.
--
--
-- This procedure checks the file name that is passed in. It returns one of
-- three values based on what it finds. It can return invalidName which would
-- indicate that invalid elements were found. It can return wildName indicating
-- that wild card characters are present in the name. The last value it can return
-- is singleName which would indicate a valid single file name is contained in the
-- string.
--
-- CALLING SEQUENCE -
--
-- TypeOfFileName (FileName);
--
-- ENTRY -
--
-- FileName : string
-- The file name to be checked.
--
-- EXIT -
--
-- FileNameType
-- The type that this name appears to be. Can be invalidName, singleName or
-- wildName.
--
function PrinterName
(Test_Name : in string) return boolean;
--*
-- PrinterName - Returns boolean as to whether this appears to be a port name.
--
--
-- This procedure checks the name that was passed in and returns a boolean that
-- shows if this appears to be a printer port name such as LPT1, LPT2, etc.
--
-- CALLING SEQUENCE -
--
-- PrinterName (TestName);
--
-- ENTRY -
--
-- TestName : string
-- The name to be checked.
--
-- EXIT -
--
-- boolean
-- true - The name does appear to be a port name such as LPT1, LPT2, etc.
-- false - The name is not a printer port name.
--
procedure ConvertToFullPath
(CurrentName : in string;
FullPathName : out string);
--*
-- ConvertToFullPath - Converts a given path and/or filename to its full path.
--
--
-- This procedure converts an input path and/or file name into the full path
-- equivalent based on the current directory. Uses for this routine include
-- converting relative names (begins with .\ or ..\ or \ or nextdir\myfile.doc)
-- into the full name. For instance if the current directory is E:\Dir1\Dir2
-- and you pass in ..\Testdir\Myfile.txt the return value would be
-- E:\Dir1\Testdir\Myfile.txt. Or given the same current directory and input
-- of nextdir\Myfile.out the output value would be E:\Dir1\Dir2\nextdir\Myfile.out.
--
-- The output value is always based on the current directory of the application.
--
-- CALLING SEQUENCE -
--
-- ConvertToFullPath (CurrentName, FullPathName);
--
-- ENTRY -
--
-- CurrentName : string
-- The current value for a file and/or path. Can include relative references.
--
-- EXIT -
--
-- FullPathName : string
-- The full path including the drive, directory and filename if included in the
-- input value. All relative directory references at the start of the CurrentName
-- parameter will have been replaced with their explicit equivalents.
--
procedure JoinPath
(Full : in out string;
Drive : in string;
Directory : in string;
FileName : in string;
Extension : in string);
--*
-- JoinPath - Build a complete path from subcomponents.
--
--
-- This will build a complete path + filename identifier from a Drive,
-- Directory, Filename and File Extension.
--
-- CALLING SEQUENCE -
--
-- JoinPath (MyFile, "D:", "\TEST\TEMP\", "TEST", ".TXT");
--
-- ENTRY -
--
-- Drive : DriveType
-- The drive designator i.e. D
--
-- Directory : DirectoryType
-- The directory name
--
-- FileName : NameType
-- The file name (up to eight characters)
--
-- Extension : NameType
-- The file name extension including the . i.e. .TXT
--
-- EXIT -
--
-- Full : FullType
-- The concatenated full file name with path and drive
--
procedure SplitPath
(Full : in string;
Drive : in out string;
Directory : in out string;
FileName : in out string;
Extension : in out string);
--*
-- SplitPath - Split a complete path into subcomponents.
--
--
-- This will split a complete path + filename identifier into a Drive,
-- Directory, Filename and File Extension.
--
-- CALLING SEQUENCE -
--
-- SplitPath ("D:\TEST\TEMP\TEST.TXT", Drive, Directory, Name, Extension);
--
-- ENTRY -
--
-- Full : FullType
-- The concatenated full file name with path and drive
--
-- EXIT -
--
-- Drive : DriveType
-- The drive designator i.e. D
--
-- Directory : DirectoryType
-- The directory name
--
-- FileName : NameType
-- The file name (up to eight characters)
--
-- Extension : NameType
-- The file name extension including the . i.e. .TXT
--
procedure GetRunInfo
(FullCommandLine : out string;
AppRunPathOnly : out string;
AppNameOnly : out string;
AppFullRunName : out string;
ParamsOnly : out string;
CurrentDirectory : out string;
Success : out boolean);
--*
-- GetRunInfo - Gets the application run information such as start directory, etc.
--
--
-- This procedure gets the run information for the current application. This
-- includes such things as the directory that the .EXE is in, the commmand line
-- parameters and the current directory. This is very usefull when trying to find
-- other files associated with the .EXE that you know should be in that same directory.
--
-- NOTE - If relative values were used to start the application and the current
-- directory has been changed since that time this routine will not correctly interpret
-- the relative path. Consequently the run path will be wrong. This routine should be
-- called before the current directory is changed if that may occur.
--
-- CALLING SEQUENCE -
--
-- GetRunInfo (FullCommandLine, AppRunPathOnly, AppNameOnly, AppFullRunName,
-- ParamsOnly, CurrentDirectory, Success);
--
-- ENTRY -
--
-- None
-- N/A
--
-- EXIT -
--
-- FullCommandLine : string
-- The complete command line for the app including the full path to .EXE, the .EXE
-- name and any commmand line arguments.
--
-- AppRunPathOnly : string
-- The run path of the app only, ending in a backslash.
--
-- AppNameOnly : string
-- The .EXE name only in the form of APPNAME.EXE.
--
-- AppFullRunName : string
-- The path and name of the application. This is basically the concatination of
-- AppRunPathOnly and AppNameOnly.
--
-- ParamsOnly : string
-- Any parameters to the app that were sent on the command line.
--
-- CurrentDirectory : string
-- The current directory that the application is using. In other words this is
-- the current directory as far as reading/writing files is concerned if no path
-- is used as part of their name.
--
-- Success : boolean
-- true - The information was successfully obtained.
-- false - Some error prevented the information to be collected.
--
-- EXAMPLE -
--
-- Assume that 1) the .EXE file is located in D:\MyApp\ExeDir 2) while running
-- the current directory has been changed to C:\Dir1\Dir2 and 3) the application
-- was started with the command "D:\MyApp\ExeDir\MyApp.EXE VAL1 VAL2" the call
-- would return the following values:
--
-- GetRunInfo (FullCommandLine, AppRunPathOnly, AppNameOnly, AppFullRunName,
-- ParamsOnly, CurrentDirectory, Success);
--
-- FullCommandLine = "D:\MyApp\ExeDir\MyApp.EXE VAL1 VAL2"
-- AppRunPathOnly = "D:\MyApp\ExeDir\"
-- AppNameOnly = "MyApp.EXE"
-- AppFullRunName = "D:\MyApp\ExeDir\MyApp.EXE"
-- ParamsOnly = "VAL1 VAL2"
-- CurrentDirectory = "C:\Dir1\Dir2\"
--
-- If relative paths are used to start the app they are interpreted before returning
-- the values. However read the NOTE above for more information on that. In the
-- second example assume that the command line was "ExeDir\MyApp.EXE VAL1 VAL2" and
-- that the current directory has NOT been changed (current directory starts as
-- "D:\MyApp"). In this case the routine can correctly interpret the relative path
-- and will return the correct information. The following values will be returned:
--
-- GetRunInfo (FullCommandLine, AppRunPathOnly, AppNameOnly, AppFullRunName,
-- ParamsOnly, CurrentDirectory, Success);
--
-- FullCommandLine = "D:\MyApp\ExeDir\MyApp.EXE VAL1 VAL2"
-- AppRunPathOnly = "D:\MyApp\ExeDir\"
-- AppNameOnly = "MyApp.EXE"
-- AppFullRunName = "D:\MyApp\ExeDir\MyApp.EXE"
-- ParamsOnly = "VAL1 VAL2"
-- CurrentDirectory = "D:\MyApp\"
--
procedure ReplaceExtension
(OldName : in string;
NewExtension : in string;
NewName : out string);
--*
-- ReplaceExtension - Replaces the current extension on the filename with a new one.
--
--
-- This procedure allows for quickly replacing the current file extension on the
-- passed in file name with a new one.
--
-- CALLING SEQUENCE -
--
-- ReplaceExtension (OldName, NewExtension, NewName);
--
-- ENTRY -
--
-- OldName : string
-- The file name before the it is replaced. May include a path.
--
-- NewExtension : string
-- The new extension to put on.
--
-- EXIT -
--
-- NewName : string
-- The file name with any path info intact but the extension replaced.
--
-- EXAMPLE -
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- ReplaceExtension (FullName,
-- ".DFL",
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test.DFL"
--
procedure ReplacePrefix
(OldName : in string;
NewPrefix : in string;
NewName : out string);
--*
-- ReplacePrefix - Replaces the current filename prefix with a new one with same extension.
--
--
-- This procedure allows for quickly replacing the current filename on the
-- passed in name with a new one without disturbing the current path or
-- extension.
--
-- CALLING SEQUENCE -
--
-- ReplacePrefix (OldName, NewPrefix, NewName);
--
-- ENTRY -
--
-- OldName : string
-- The file name before the it is replaced. May include a path and extension.
--
-- NewPrefix : string
-- The new file name prefix to put on. For convenience any path on this name
-- may be included and will be put on the new name.
--
-- EXIT -
--
-- NewName : string
-- The file name with any path and extension info intact but the name replaced.
--
-- EXAMPLE -
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- ReplacePrefix (FullName,
-- "MyTest",
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\MyTest.EXE"
--
procedure ReplacePrefixAndExtension
(OldName : in string;
ReplacementName : in string;
NewName : out string);
--*
-- ReplacePrefixAndExtension - Replaces the name and extension with or without path.
--
--
-- This procedure allows for quickly replacing the current filename and extension
-- with a new name. The new name may or may not include an extension. If no
-- extension is give there will not be one on the resulting name. The main
-- purpose of this routine is to handle names that may or may not include the
-- path. This way you do not have to be concerned with finding just the
-- filename part before replacing.
--
-- CALLING SEQUENCE -
--
-- ReplacePrefixAndExtension (OldName, ReplacementName, NewName);
--
-- ENTRY -
--
-- OldName : string
-- The file name before the extension is replaced.
--
-- ReplacementName : string
-- The new file name with or without extension that will replace the old one.
--
-- EXIT -
--
-- NewName : string
-- The file name with any path info intact but the name replaced.
--
-- EXAMPLE -
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- ReplaceNameAndExtension (FullName,
-- "MyNewTest.EXE",
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\MyNewTest.EXE"
--
procedure LocateFile
(SearchName : in string;
FullFileName : out string;
Success : out boolean);
--*
-- LocateFile - Searchs for a file and returns the full path if found.
--
--
-- This procedure searches for a file when its location may not be known
-- for certain. First it searches the current directory, then if the
-- file is not found it checks the directory from where the application
-- executable was started. In addition if the application is Win32 it will
-- continue on and check the search path.
--
-- CALLING SEQUENCE -
--
-- LocateFile (SearchName, FullFileName, Success);
--
-- ENTRY -
--
-- SearchName : string
-- The file name to search for.
--
-- EXIT -
--
-- FullFileName : string
-- The full path and name of the file if it was located.
--
-- Success : boolean
-- TRUE - the file was located.
-- FALSE - the file was not found in the areas checked.
--
-- EXAMPLE -
--
-- LocateFile ("TEST.OUT",
-- FullFileName,
-- Success);
--
procedure CheckFileModifyStatus
(FileName : in string;
Found : out boolean;
CanModify : out boolean);
--*
-- CheckFileModifyStatus - Checks a file to see if it is read/write or read/only.
--
--
-- This procedure checks a file and if found returns a value to indicate
-- if the file can be modified.
--
-- CALLING SEQUENCE -
--
-- CheckFileModifyStatus (FileName, Found, CanModify);
--
-- ENTRY -
--
-- FileName : string
-- The file name to search for.
--
-- EXIT -
--
-- Found : boolean
-- Indicates if the file was located.
--
-- CanModify : boolean
-- TRUE - the file can be changed (attribute is NOT read only).
-- FALSE - the file CANNOT be changed (attibute is read only).
--
-- EXAMPLE -
--
-- CheckFileModifyStatus ("TEST.OUT",
-- Found,
-- CanModify);
--
-- if Found then
-- Files.Open (FileHandle,
-- "TEST.OUT",
-- Files.binMode,
-- Files.readOnly,
-- State);
--
function FilenameExtensionIs
(FileName : in string;
Extension : in string) return boolean;
--*
-- FilenameExtensionIs - Do NON case sensitive compare of the file extension.
--
--
-- This procedure does a non case sensitive comparison of the extension on the
-- file name and the given extension and returns a boolean result of the
-- comparison.
--
-- CALLING SEQUENCE -
--
-- FilenameExtensionIs (FileName, Extension);
--
-- ENTRY -
--
-- FileName : string
-- The file name whose extension will be checked.
--
-- Extension : string
-- The extension to search for. May or may not include the '.' character.
--
-- EXIT -
--
-- boolean
-- True - The file name does have that extension.
-- False - The file name does NOT have that extension.
--
-- EXAMPLE -
--
-- if FilenameExtensionIs ("C:\MyDir\TEST.res",
-- ".RES") then
-- Will return True
--
-- or
--
-- if FilenameExtensionIs ("C:\MyDir\TEST.res",
-- "RES") then
-- Will return True
--
procedure FilesTextEqual
(SourceName1 : in string;
SourceName2 : in string;
SameText : out boolean;
FirstDiffLine : out ModSys.S_Natural);
--*
-- FilesTextEqual - Text comparison of files for equality.
--
--
-- This procedure does a case sensitive text comparison of two files.
-- This is a faster way to compare but only works for text. If either file
-- does not exist or the files are different size or any part of the text
-- differs from the other file the SameText value returns as False. Even though
-- this is doing a text comparison the files must be of the same size or the
-- routine will return False that the files are not the same.
--
-- CALLING SEQUENCE -
--
-- FileTextEqual (SourceName1, SourceName2, SameText, FirstDiffLine);
--
-- ENTRY -
--
-- SourceName1 : string
-- The file name of one of the files to compare.
--
-- SourceName2 : string
-- The file name of other file to compare.
--
-- EXIT -
--
-- SameText : boolean
-- TRUE - The files are identical.
-- FALSE - The files differ in size or content.
--
-- FirstDiffLine : ModSys.S_Natural
-- The line number where the first difference was detected. A return
-- value of 0 can indicate that one of the files did not exist or
-- there was a problem opening one of the files.
--
-- EXAMPLE -
--
-- FileUtil.FilesTextEqual ("FirstFile.txt",
-- "SecondFile.txt",
-- TextEqual,
-- FirstDiffLine);
--
procedure FilesBinaryEqual
(SourceName1 : in string;
SourceName2 : in string;
SameBinary : out boolean;
FirstDiffByte : out ModSys.S_Natural);
--*
-- FilesBinaryEqual - Binary comparison of files for equality.
--
--
-- This procedure does a binary (byte by byte) comparison of two files.
-- This is a slower way to compare but will work for any type of file.
-- If either file does not exist or the files are different size or any
-- byte in the file differs from the other file the SameBinary value
-- returns as False.
--
-- CALLING SEQUENCE -
--
-- FileBinaryEqual (SourceName1, SourceName2, SameBinary, FirstDiffByte);
--
-- ENTRY -
--
-- SourceName1 : string
-- The file name of one of the files to compare.
--
-- SourceName2 : string
-- The file name of other file to compare.
--
-- EXIT -
--
-- SameBinary : boolean
-- TRUE - The files are identical.
-- FALSE - The files differ in size or content.
--
-- FirstDiffByte : CARDINAL
-- The line number where the first difference was detected. A return
-- value of 0 can indicate that one of the files did not exist or
-- there was a problem opening one of the files.
--
-- EXAMPLE -
--
-- FileUtil.FilesBinaryEqual ("FirstFile.txt",
-- "SecondFile.txt",
-- TextBinary,
-- FirstDiffByte);
--
procedure GetUniqueFilename
(baseName : in string;
AppendToPrefix : in boolean;
PrefixDigits : in ModSys.S_Natural;
AppendToExtension : in boolean;
ExtensionDigits : in ModSys.S_Natural;
UniqueName : out string);
--*
-- GetUniqueFilename - Get a unique (unused) filename.
--
--
-- This procedure generates a unique name that is currently not used.
-- You have the option of appending a numeric value onto the prefix,
-- the extension or both parts in order to make a unique name.
-- The unique name will be created using numbers for uniqueness. Note
-- that the return name will be fully qualified with a path.
--
-- CALLING SEQUENCE -
--
-- GetUniqueFilename (BaseName, AppendToPrefix, AppendToExtension,
-- UniqueName);
--
-- ENTRY -
--
-- BaseName : string
-- The base file name to use. This string may be null in which case the
-- UniqueName returned will be completely composed of the generated name.
--
-- AppendToPrefix : boolean
-- Append onto the current prefix portion of the name to attain uniqueness.
--
-- PrefixDigits : ModSys.S_Natural
-- Number of digits to add, will zero fill if needed.
--
-- AppendToExtension : boolean
-- Replace the extension portion of the name to attain uniqueness.
--
-- ExtensionDigits : ModSys.S_Natural
-- Number of digits to add, will zero fill if needed.
--
-- EXIT -
--
-- UniqueName : string
-- The name which currently is not used by any file. This name will have
-- numbers appended to its prefix or extension or both depending on the flags
-- which were passed in. Also this name will be fully qualified with the path
-- to where the file would be.
--
-- EXAMPLE -
--
-- FullName := "C:\Dir1\Dir2\Test";
--
-- GetUniqueFilename (FullName,
-- TRUE,
-- 4,
-- FALSE,
-- 0,
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test0001"
--
-- FullName := "C:\Dir1\Dir2\Test";
--
-- GetUniqueFilename (FullName,
-- FALSE,
-- 0,
-- TRUE,
-- 3,
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test.001"
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- GetUniqueFilename (FullName,
-- TRUE,
-- 4,
-- FALSE,
-- 0,
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test0001.EXE"
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- GetUniqueFilename (FullName,
-- FALSE,
-- 0,
-- TRUE,
-- 2,
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test.EXE01"
--
-- FullName := "C:\Dir1\Dir2\Test.EXE";
--
-- GetUniqueFilename (FullName,
-- TRUE,
-- 4,
-- TRUE,
-- 4,
-- FullName);
--
-- FullName returns as "C:\Dir1\Dir2\Test0001.EXE0001"
--
procedure SetToExePath
(OldFileName : in string;
NewFileName : out string);
--*
-- SetToExePath - Set this file to the same folder as the exe.
--
--
-- This procedure takes in a filename with or without path, modifies
-- it so that the path is the same as the .exe folder and returns the
-- result. This is ideal for applications that may let the user browse
-- around the drives but when certain files are accessed want to store
-- them in the same location as the executable. This is an easy way to
-- figure out what that path should be.
--
-- CALLING SEQUENCE -
--
-- SetToExePath (OldFileName, NewFileName)
--
-- ENTRY -
--
-- OldFileName : string
-- The filename with or without a path.
--
-- EXIT -
--
-- NewFileName : string
-- A fully qualified filename including path that now points to the
-- same folder where the currently running executable is located.
--
Send mail to
warren.merrill@inl.gov
with questions or comments about this web site.
Copyright © 1989-2006 Battelle Energy Alliance