[prev] [prev-tail] [tail] [up]

2.3 Functions and Procedures

AddDisk

Declaration:
Procedure AddDisk (Const S : String);
Description:
AddDisk adds a filename S to the internal list of disks. It is implemented for systems which do not use DOS type drive letters. This list is used to determine which disks to use in the DiskFree (80) and DiskSize (81) calls. The DiskFree (80) and DiskSize (81) functions need a file on the specified drive, since this is required for the statfs system call. The names are added sequentially. The dos initialization code presets the first three disks to:

The first call to AddDisk will therefore add a name for the second harddisk, The second call for the third drive, and so on until 23 drives have been added (corresponding to drives 'D:' to 'Z:')

Errors:
None
See also:
DiskFree (80), DiskSize (81)

DiskFree

Declaration:
Function DiskFree (Drive: byte) : int64;
Description:

DiskFree returns the number of free bytes on a disk. The parameter Drive indicates which disk should be checked. This parameter is 1 for floppy a:, 2 for floppy b:, etc. A value of 0 returns the free space on the current drive.

For unix only:
The diskfree and disksize functions need a file on the specified drive, since this is required for the statfs system call. These filenames are set in the initialization of the dos unit, and have been preset to :

There is room for 1-26 drives. You can add a drive with the AddDisk (80) procedure. These settings can be coded in dos.pp, in the initialization part.

Errors:
-1 when a failure occurs, or an invalid drive number is given.
See also:
DiskSize (81), AddDisk (80)

Listing: dosex/ex6.pp

Program Example6;
uses Dos;

{ Program to demonstrate the DiskSize and DiskFree function. }

begin
  WriteLn('This partition size has ',DiskSize(0),' bytes');
  WriteLn('Currently ',DiskFree(0),' bytes are free');
end.

DiskSize

Declaration:
Function DiskSize (Drive: byte) : int64;
Description:

DiskSize returns the total size (in bytes) of a disk. The parameter Drive indicates which disk should be checked. This parameter is 1 for floppy a:, 2 for floppy b:, etc. A value of 0 returns the size of the current drive.

For unix only:
The diskfree and disksize functions need a file on the specified drive, since this is required for the statfs system call. These filenames are set in the initialization of the dos unit, and have been preset to :

There is room for 1-26 drives. You can add a drive with the AddDisk (80) procedure. These settings can be coded in dos.pp, in the initialization part.

Errors:
-1 when a failure occurs, or an invalid drive number is given.
See also:
DiskFree (80), AddDisk (80)

For an example, see DiskFree (80).

DosExitCode

Declaration:
Function DosExitCode : Word;
Description:

DosExitCode contains (in the low byte) the exit-code of a program executed with the Exec call.

Errors:
None.
See also:
Exec (85)

Listing: dosex/ex5.pp

Program Example5;
uses Dos;

{ Program to demonstrate the Exec and DosExitCode function. }

begin
{$IFDEF Unix}
  WriteLn('Executing /bin/ls -la');
  Exec('/bin/ls','-la');
{$ELSE}
  WriteLn('Executing Dir');
  Exec(GetEnv('COMSPEC'),'/C dir');
{$ENDIF}
  WriteLn('Program returned with ExitCode ',Lo(DosExitCode));
end.

DosVersion

Declaration:
Function DosVersion : Word;
Description:
DosVersion returns the operating system or kernel version. The low byte contains the major version number, while the high byte contains the minor version number.
Portability:
On systems where versions consists of more then two numbers, only the first two numbers will be returned. For example Linux version 2.1.76 will give you DosVersion 2.1. Some operating systems, such as FREEBSD, do not have system calls to return the kernel version, in that case a value of 0 will be returned.
Errors:
None.
See also:

Listing: dosex/ex1.pp

Program Example1;
uses Dos;

{ Program to demonstrate the DosVersion function. }

var
  OS      : string[32];
  Version : word;
begin
{$IFDEF LINUX}
  OS:='Linux';
{$ENDIF}
{$ifdef FreeBSD}
  OS:='FreeBSD';
{$endif}
{$ifdef NetBSD}
  OS:='NetBSD';
{$endif}
{$ifdef Solaris}
  OS:='Solaris';
{$endif}
{$ifdef QNX}
  OS:='QNX';
{$endif}

{$IFDEF DOS}
  OS:='Dos';
{$ENDIF}
  Version:=DosVersion;
  WriteLn('Current ',OS,' version is ',Lo(Version),'.',Hi(Version));
end.

EnvCount

Declaration:
Function EnvCount : longint;
Description:
EnvCount returns the number of environment variables.
Errors:
None.
See also:
EnvStr (84), Dos:GetEnv (90)

EnvStr

Declaration:
Function EnvStr (Index: integer) : string;
Description:

EnvStr returns the Index-th Name=Value pair from the list of environment variables. The index of the first pair is zero.

Errors:
The length is limited to 255 characters.
See also:
EnvCount (84), Dos:GetEnv (90)

Listing: dosex/ex13.pp

Program Example13;
uses Dos;

{ Program to demonstrate the EnvCount and EnvStr function. }

var
  i : Longint;
begin
  WriteLn('Current Environment is:');
  for i:=1to EnvCount do
   WriteLn(EnvStr(i));
end.

Exec

Declaration:
Procedure Exec (const Path: pathstr; const ComLine: comstr);
Description:

Exec executes the program in Path, with the options given by ComLine. After the program has terminated, the procedure returns. The Exit value of the program can be consulted with the DosExitCode function.

Errors:
Errors are reported in DosError.
See also:
DosExitCode (82)

For an example, see DosExitCode (82)

FExpand

Declaration:
Function FExpand (const path: pathstr) : pathstr;
Description:

FExpand takes its argument and expands it to a complete filename, i.e. a filename starting from the root directory of the current drive, prepended with the drive-letter or volume name (when supported).

Portability:
On case sensitive file systems (such as UNIX and LINUX), the resulting name is left as it is, otherwise it is converted to uppercase.
Errors:
FSplit (88)
See also:

Listing: dosex/ex5.pp

Program Example5;
uses Dos;

{ Program to demonstrate the Exec and DosExitCode function. }

begin
{$IFDEF Unix}
  WriteLn('Executing /bin/ls -la');
  Exec('/bin/ls','-la');
{$ELSE}
  WriteLn('Executing Dir');
  Exec(GetEnv('COMSPEC'),'/C dir');
{$ENDIF}
  WriteLn('Program returned with ExitCode ',Lo(DosExitCode));
end.

FindClose

Declaration:
Procedure FindClose (Var F: SearchRec);
Description:
FindClose frees any resources associated with the search record F.

This call is needed to free any internal resources allocated by the FindFirst (753) or FindNext (754) calls.

The LINUX implementation of the DOS unit therefore keeps a table of open directories, and when the table is full, closes one of the directories, and reopens another. This system is adequate but slow if you use a lot of searchrecs. So, to speed up the findfirst/findnext system, the FindClose call was implemented. When you don’t need a searchrec any more, you can tell this to the DOS unit by issuing a FindClose call. The directory which is kept open for this searchrec is then closed, and the table slot freed.

Portability:
It is recommended to use the LINUX call Glob when looking for files on LINUX.
Errors:
Errors are reported in DosError.
See also:
Glob (401).

FindFirst

Declaration:
Procedure FindFirst (const Path: pathstr; Attr: word; var F: SearchRec);
Description:

FindFirst searches the file specified in Path. Normal files, as well as all special files which have the attributes specified in Attr will be returned.

It returns a SearchRec record for further searching in F. Path can contain the wildcard characters ? (matches any single character) and * (matches 0 ore more arbitrary characters). In this case FindFirst will return the first file which matches the specified criteria. If DosError is different from zero, no file(s) matching the criteria was(were) found.

Portability:
On OS/2, you cannot issue two different FindFirst calls. That is, you must close any previous search operation with FindClose (86) before starting a new one. Failure to do so will end in a Run-Time Error 6 (Invalid file handle)
Errors:
Errors are reported in DosError.
See also:
FindNext (87), FindClose (86)

Listing: dosex/ex7.pp

Program Example7;
uses Dos;

{ Program to demonstrate the FindFirst and FindNext function. }

var
  Dir : SearchRec;
begin
  FindFirst('*.*',archive,Dir);
  WriteLn('FileName'+Space(32),'FileSize':9);
  while (DosError=0) do
   begin
     Writeln(Dir.Name+Space(40-Length(Dir.Name)),Dir.Size:9);
     FindNext(Dir);
   end;
  FindClose(Dir);
end.

FindNext

Declaration:
Procedure FindNext (var f: searchRec);
Description:

FindNext takes as an argument a SearchRec from a previous FindNext call, or a FindFirst call, and tries to find another file which matches the criteria, specified in the FindFirst call. If DosError is different from zero, no more files matching the criteria were found.

Errors:
DosError is used to report errors.
See also:
FindFirst (86), FindClose (86)

For an example, see FindFirst (86).

FSearch

Declaration:
Function FSearch (Path: pathstr; DirList: string) : pathstr;
Description:
FSearch searches the file Path in all directories listed in DirList. The full name of the found file is returned. DirList must be a list of directories, separated by semi-colons. When no file is found, an empty string is returned.
Portability:
On UNIX systems, DirList can also be separated by colons, as is customary on those environments.
Errors:
None.
See also:
FExpand (85)

Listing: dosex/ex10.pp

Program Example10;
uses Dos;

{ Program to demonstrate the FSearch function. }

var
  s : string;
begin
  s:=FSearch(ParamStr(1),GetEnv('PATH'));
  if s='' then
   WriteLn(ParamStr(1),' not Found in PATH')
  else
   Writeln(ParamStr(1),' Found in PATH at ',s);
end.

FSplit

Declaration:
Procedure FSplit (path: pathstr;
var dir: dirstr; var name: namestr; var ext: extstr);
Description:

FSplit splits a full file name into 3 parts : A Path, a Name and an extension (in ext.) The extension is taken to be all letters after the last dot (.). For DOS, however, an exception is made when LFNSupport=False, then the extension is defined as all characters after the first dot.

Errors:
None.
See also:
FSearch (87)

Listing: dosex/ex12.pp

Program Example12;
uses Dos;

{ Program to demonstrate the FSplit function. }

var
  Path,Name,Ext : string;
begin
  FSplit(ParamStr(1),Path,Name,Ext);
  WriteLn('Splitted ',ParamStr(1),' in:');
  WriteLn('Path     : ',Path);
  WriteLn('Name     : ',Name);
  WriteLn('Extension: ',Ext);
end.

GetCBreak

Declaration:
Procedure GetCBreak (var breakvalue: boolean);
Description:

GetCBreak gets the status of CTRL-Break checking under DOS and AMIGA. When BreakValue is false, then DOS only checks for the CTRL-Break key-press when I/O is performed. When it is set to True, then a check is done at every system call.

Portability:
Under non-DOS and non-AMIGA operating systems, BreakValue always returns True.
Errors:
None
See also:
SetCBreak (97)

GetDate

Declaration:
Procedure GetDate (var year, month, mday, wday: word);
Description:

GetDate returns the system’s date. Year is a number in the range 1980..2099.mday is the day of the month, wday is the day of the week, starting with Sunday as day 0.

Errors:
None.
See also:
GetTime (94),SetDate (97)

Listing: dosex/ex2.pp

Program Example2;
uses Dos;

{ Program to demonstrate the GetDate function. }

const
  DayStr:array[0..6] of string[3]=('Sun','Mon','Tue','Wed','Thu','Fri','Sat');
  MonthStr:array[1..12] of string[3]=('Jan','Feb','Mar','Apr','May','Jun',
                                      'Jul','Aug','Sep','Oct','Nov','Dec');
var
  Year,Month,Day,WDay : word;
begin
  GetDate(Year,Month,Day,WDay);
  WriteLn('Current date');
  WriteLn(DayStr[WDay],', ',Day,' ',MonthStr[Month],' ',Year,'.');
end.

GetEnv

Declaration:
Function GetEnv (EnvVar: String) : String;
Description:

Getenv returns the value of the environment variable EnvVar. When there is no environment variable EnvVar defined, an empty string is returned.

Portability:
Under some operating systems (such as UNIX), case is important when looking for EnvVar.
Errors:
None.
See also:
EnvCount (84), EnvStr (84)

Listing: dosex/ex14.pp

Program Example14;
uses Dos;

{ Program to demonstrate the GetEnv function. }

begin
  WriteLn('Current PATH is ',GetEnv('PATH'));
end.

GetFAttr

Declaration:
Procedure GetFAttr (var F; var Attr: word);
Description:

GetFAttr returns the file attributes of the file-variable f. F can be a untyped or typed file, or of type Text. f must have been assigned, but not opened. The attributes can be examined with the following constants :

Under LINUX, supported attributes are:

Errors:
Errors are reported in DosError
See also:
SetFAttr (98)

Listing: dosex/ex8.pp

Program Example8;
uses Dos;

{ Program to demonstrate the GetFAttr function. }

var
  Attr : Word;
  f    : File;
begin
  Assign(f,ParamStr(1));
  GetFAttr(f,Attr);
  WriteLn('File ',ParamStr(1),' has attribute ',Attr);
  if (Attr and archive)<>0 then WriteLn('- Archive');
  if (Attr and directory)<>0 then WriteLn('- Directory');
  if (Attr and readonly)<>0 then WriteLn('- Read-Only');
  if (Attr and sysfile)<>0 then WriteLn('- System');
  if (Attr and hidden)<>0 then WriteLn('- Hidden');
end.

GetFTime

Declaration:
Procedure GetFTime (var F; var Time: longint);
Description:

GetFTime returns the modification time of a file. This time is encoded and must be decoded with UnPackTime. F must be a file type, which has been assigned, and opened.

Errors:
Errors are reported in DosError
See also:
SetFTime (98), PackTime (96),UnPackTime (100)

Listing: dosex/ex9.pp

Program Example9;
uses Dos;

{ Program to demonstrate the GetFTime function. }

Function L0(w:word):string;
var
  s : string;
begin
  Str(w,s);
  if w<10 then
   L0:='0'+s
  else
   L0:=s;
end;

var
  f    : File;
  Time : Longint;
  DT   : DateTime;
begin
  Assign(f,ParamStr(1));
  Reset(f);
  GetFTime(f,Time);
  Close(f);
  UnPackTime(Time,DT);
  Write ('File ',ParamStr(1),' is last modified on ');
  Writeln (L0(DT.Month),'-',L0(DT.Day),'-',DT.Year,
           ' at ',L0(DT.Hour),':',L0(DT.Min));
end.

GetIntVec

Declaration:
Procedure GetIntVec (IntNo: byte; var Vector: pointer);
Description:

GetIntVec returns the address of interrupt vector IntNo.

Portability:
This call does nothing, it is present for compatibility only.
Errors:
None.
See also:
SetIntVec (99)

GetLongName

Declaration:
function GetLongName(var p : String) : boolean;
Description:
This function is only implemented in the GO32V2 version of Free Pascal.

GetLongName changes the filename p to a long filename if the DOS call to do this is successful. The resulting string is the long file name corresponding to the short filename p.

The function returns True if the DOS call was successful, False otherwise.

This function should only be necessary when using the DOS extender under Windows 95 and higher.

Errors:
If the DOS call was not succesfull, False is returned.
See also:
GetShortName (93)

GetShortName

Declaration:
function GetShortName(var p : String) : boolean;
Description:
This function is only implemented in the GO32V2 version of Free Pascal.

GetShortName changes the filename p to a short filename if the DOS call to do this is successful. The resulting string is the short file name corresponding to the long filename p.

The function returns True if the DOS call was successful, False otherwise.

This function should only be necessary when using the DOS extender under Windows 95 and higher.

Errors:
If the DOS call was not successful, False is returned.
See also:
GetLongName (93)

GetTime

Declaration:
Procedure GetTime (var hour, minute, second, sec100: word);
Description:

GetTime returns the system’s time. Hour is a on a 24-hour time scale. sec100 is in hundredth of a second.

Portability:
Certain operating systems (such as AMIGA), always set the sec100 field to zero.
Errors:
None.
See also:
GetDate (89), SetTime (99)

Listing: dosex/ex3.pp

Program Example3;
uses Dos;

{ Program to demonstrate the GetTime function. }

Function L0(w:word):string;
var
  s : string;
begin
  Str(w,s);
  if w<10 then
   L0:='0'+s
  else
   L0:=s;
end;

var
  Hour,Min,Sec,HSec : word;
begin
  GetTime(Hour,Min,Sec,HSec);
  WriteLn('Current time');
  WriteLn(L0(Hour),':',L0(Min),':',L0(Sec));
end.

GetVerify

Declaration:
Procedure GetVerify (var verify: boolean);
Description:

GetVerify returns the status of the verify flag under DOS. When Verify is True, then DOS checks data which are written to disk, by reading them after writing. If Verify is False, then data written to disk are not verified.

Portability:
Under non-DOS systems (excluding OS/2 applications running under vanilla DOS), Verify is always True.
Errors:
None.
See also:
SetVerify (99)

Intr

Declaration:
Procedure Intr (IntNo: byte; var Regs: registers);
Description:

Intr executes a software interrupt number IntNo (must be between 0 and 255), with processor registers set to Regs. After the interrupt call returned, the processor registers are saved in Regs.

Portability:
Under non-DOS operating systems, this call does nothing.
Errors:
None.
See also:
MSDos (96), see the LINUX unit.

Keep

Declaration:
Procedure Keep (ExitCode: word);
Description:
Keep terminates the program, but stays in memory. This is used for TSR (Terminate Stay Resident) programs which catch some interrupt. ExitCode is the same parameter as the Halt function takes.
Portability:
This call does nothing, it is present for compatibility only.
Errors:
None.
See also:
Halt ()

MSDos

Declaration:
Procedure MSDos (var regs: registers);
Description:

MSDos executes an operating system. This is the same as doing a Intr call with the interrupt number for an os call.

Portability:
Under non-DOS operating systems, this call does nothing. On DOS systems, this calls interrupt $21.
Errors:
None.
See also:
Intr (95)

PackTime

Declaration:
Procedure PackTime (var T: datetime; var P: longint);
Description:

UnPackTime converts the date and time specified in T to a packed-time format which can be fed to SetFTime.

Errors:
None.
See also:
SetFTime (98), FindFirst (86), FindNext (87), UnPackTime (100)

Listing: dosex/ex4.pp

Program Example4;
uses Dos;

{ Program to demonstrate the PackTime and UnPackTime functions. }

var
  DT   : DateTime;
  Time : longint;
begin
  with DT do
   begin
     Year:=1998;
     Month:=11;
     Day:=11;
     Hour:=11;
     Min:=11;
     Sec:=11;
   end;
  PackTime(DT,Time);
  WriteLn('Packed Time : ',Time);
  UnPackTime(Time,DT);
  WriteLn('Unpacked Again:');
  with DT do
   begin
     WriteLn('Year  ',Year);
     WriteLn('Month ',Month);
     WriteLn('Day   ',Day);
     WriteLn('Hour  ',Hour);
     WriteLn('Min   ',Min);
     WriteLn('Sec   ',Sec);
   end;
end.

SetCBreak

Declaration:
Procedure SetCBreak (breakvalue: boolean);
Description:

SetCBreak sets the status of CTRL-Break checking. When BreakValue is false, then DOS only checks for the CTRL-Break key-press when I/O is performed. When it is set to True, then a check is done at every system call.

Portability:
Under non-DOS and non-AMIGA operating systems, this call does nothing.
Errors:
None.
See also:
GetCBreak (89)

SetDate

Declaration:
Procedure SetDate (year,month,day: word);
Description:

SetDate sets the system’s internal date. Year is a number between 1980 and 2099.

Portability:
On a LINUX machine, there must be root privileges, otherwise this routine will do nothing. On other UNIX systems, this call currently does nothing.
Errors:
None.
See also:
Dos:GetDate (89), SetTime (99)

SetFAttr

Declaration:
Procedure SetFAttr (var F; Attr: word);
Description:

SetFAttr sets the file attributes of the file-variable F. F can be a untyped or typed file, or of type Text. F must have been assigned, but not opened. The attributes can be a sum of the following constants:

Portability:
Under UNIX like systems (such as LINUX and BEOS) the call exists, but is not implemented, i.e. it does nothing.
Errors:
Errors are reported in DosError.
See also:
GetFAttr (90)

SetFTime

Declaration:
Procedure SetFTime (var F; Time: longint);
Description:

SetFTime sets the modification time of a file, this time is encoded and must be encoded with PackTime. F must be a file type, which has been assigned, and opened.

Portability:
Under UNIX like systems (such as LINUX and BEOS) the call exists, but is not implemented, i.e. it does nothing.
Errors:
Errors are reported in DosError
See also:
GetFTime (92), PackTime (96),UnPackTime (100)

SetIntVec

Declaration:
Procedure SetIntVec (IntNo: byte; Vector: pointer);
Description:
SetIntVec sets interrupt vector IntNo to Vector. Vector should point to an interrupt procedure.
Portability:
This call does nothing, it is present for compatibility only.
Errors:
None.
See also:
GetIntVec (93)

SetTime

Declaration:
Procedure SetTime (hour,minute,second,sec100: word);
Description:
SetTime sets the system’s internal clock. The Hour parameter is on a 24-hour time scale.
Portability:
On a LINUX machine, there must be root privileges, otherwise this routine will do nothing. On other UNIX systems, this call currently does nothing.
Errors:
None.
See also:
Dos:GetTime (94), SetDate (97)

SetVerify

Declaration:
Procedure SetVerify (verify: boolean);
Description:

SetVerify sets the status of the verify flag under DOS. When Verify is True, then DOS checks data which are written to disk, by reading them after writing. If Verify is False, then data written to disk are not verified.

Portability:
Under non-DOS operating systems (excluding OS/2 applications running under vanilla dos), Verify is always True.
Errors:
None.
See also:
SetVerify (99)

SwapVectors

Declaration:
Procedure SwapVectors ;
Description:

SwapVectors swaps the contents of the internal table of interrupt vectors with the current contents of the interrupt vectors. This is called typically in before and after an Exec call.

Portability:
Under certain operating systems, this routine may be implemented as an empty stub.
Errors:
None.
See also:
Exec (85), SetIntVec (99)

UnPackTime

Declaration:
Procedure UnPackTime (p: longint; var T: datetime);
Description:

UnPackTime converts the file-modification time in p to a DateTime record. The file-modification time can be returned by GetFTime, FindFirst or FindNext calls.

Errors:
None.
See also:
GetFTime (92), FindFirst (86), FindNext (87), PackTime (96)

For an example, see PackTime (96).

[prev] [prev-tail] [front] [up]