Delphi Basics : $I command

DelphiBasics

$I
Compiler Directive

Allows code in an include file to be incorporated into a Unit

{$I FileName}

1
2	{$I-}
3	{$I+}

Description

The $I compiler directive covers two purposes. Firstly to include a file of code into the current unit. Secondly, to control whether exceptions are thrown when an IO error occurs.

Version 1

This is very useful for including compiler directives or common code into all of your units to ensure consistency, and a single point of control.

The default file name extension is .pas, so for .pas files, only the name is required. Use quotes if the name includes one or more spaces.

For example:

Common.pas file:
{$ReferenceInfo On}
{$RangeChecks On}
{$OverFlowChecks On}

Unit1.pas file:
...
{$I Common}
...

Versions 2 and 3

{$I+} default generates the EInOutError exception when an IO error occurs.

{$I-} does not generate an exception. Instead, it is the responsiblity of the program to check the IO operation by using the IOResult routine.

Notes

$I FileName is equivalent to $Include FileName.
$I- is equivalent to $IOChecks Off.
$I+ is equivalent to $IOChecks On.

This directive can be used multiple times within your code.

Related commands

$Include		Allows code in an include file to be incorporated into a Unit
$IOChecks		When on, an IO operation error throws an exception
IOResult		Holds the return code of the last I/O operation

Download this web site as a Windows program.

Example code : Trapping IO exceptions, and using IOResult

var
  error : Integer;

begin
  // Try to create a new subdirectory in the current directory
  // Switch off I/O error checking
  {$I-}
  MkDir('TempDirectory');

  // Did the directory get created OK?
  error := IOResult;
  if error = 0
  then ShowMessage('Directory created OK')
  else ShowMessageFmt('Directory creation failed with error %d',[error]);

  // Try to create the directory again - this will fail!
  MkDir('TempDirectory');
  error := IOResult;
  if error = 0
  then ShowMessage('Directory created OK again')
  else ShowMessageFmt('Repeat creation failed with error %d',[error]);

  // Delete the directory to tidy up
  RmDir('TempDirectory');

  // Switch IO checking back on
  {$I+}
end;

Show full unit code

Directory created OK
Repeat creation failed with error 183