View source for Assign

The [[Borland Pascal]] [[Procedure|<syntaxhighlight lang="pascal" inline>procedure</syntaxhighlight>]] {{Doc|package=RTL|unit=system|identifier=assign|text=<syntaxhighlight lang="delphi" inline>assign</syntaxhighlight>}} associates a file variable with an external entity (e. g. a device file or a file on disk).
<syntaxhighlight lang="delphi" inline>Assign</syntaxhighlight> only operates on the program’s internal management data and has otherwise no immediate observable effect.

== usage ==
In non-ISO modes the [[FPC]] needs files to be explicitly associated with external entities.
This can be achieved with <syntaxhighlight lang="delphi" inline>assign</syntaxhighlight>.
The first parameter is a file variable, the second parameter specifies a path.
<syntaxhighlight lang="delphi">program assignDemo(input, output, stdErr);
var
	FD: text;
begin
	assign(FD, '/tmp/assignDemo.txt');
	assign(FD, '/root/.bashrc');
end.</syntaxhighlight>
Note, you can run this program without any troubles as any user on any platform.
Nonexistent path components (e. g. directories), missing privileges to eventually access the file or any path component, or unacceptable characters (usually [[Chr|<syntaxhighlight lang="pascal" inline>chr(0)</syntaxhighlight>]]) do not pose a problem to <syntaxhighlight lang="delphi" inline>assign</syntaxhighlight>.
It merely operates on internal management data.

== application ==
* <syntaxhighlight lang="delphi" inline>Assign</syntaxhighlight> is used before operating on any file variable.<syntaxhighlight lang="delphi">program assignApplication(input, output, stdErr);
var
	executable: file of Byte;
begin
	assign(executable, paramStr(0));
	fileMode := 0; { 0 = read-only; only relevant for `file of …` variables }
	reset(executable);
	writeLn(paramStr(0), ' has a size of ', fileSize(executable), ' Bytes.');
end.</syntaxhighlight>
* <syntaxhighlight lang="delphi" inline>Assign</syntaxhighlight> can be used to ''redirect'' standard files {{Doc|package=RTL|unit=system|identifier=input|text=<syntaxhighlight lang="pascal" inline>input</syntaxhighlight>}}/{{Doc|package=RTL|unit=system|identifier=output|text=<syntaxhighlight lang="pascal" inline>output</syntaxhighlight>}}. Our [[Hello, World]] program needs only a few changes as highlighted:<syntaxhighlight lang="delphi" highlight="2-5,7,8">program redirectDemo(input, output, stdErr);
const
	blackhole = {$ifDef Linux}   '/dev/null' + {$endIf}
	            {$ifDef Windows} 'nul'       + {$endIf}
	            '';
begin
	assign(output, blackhole);
	rewrite(output);
	writeLn('Hello world!');
end.</syntaxhighlight>

== caveats ==
* Regardless of the utilized [[Character and string types|string data type]], <syntaxhighlight lang="delphi" inline>assign</syntaxhighlight> can only process paths of up to 255 [[Byte]]s. This limitation comes from the internally used  {{Doc|package=RTL|unit=system|identifier=filerec|text=<syntaxhighlight lang="delphi" inline>fileRec</syntaxhighlight>}}/{{Doc|package=RTL|unit=system|identifier=textrec|text=<syntaxhighlight lang="delphi" inline>textRec</syntaxhighlight>}}. Relative paths in conjunction with working directories cannot overcome this. Cf.&nbsp;{{gitlab|issue|FPC|35185}}.
* Since <syntaxhighlight lang="delphi" inline>assign</syntaxhighlight> only operates on internal management data, specifying illegal paths is accepted. It is even possible to supply an empty string as a path. The specific behavior on a file variable bearing an empty file name depends on the used I/O routine.

== notes ==
* If <syntaxhighlight lang="delphi" inline>{$modeSwitch objPas+}</syntaxhighlight> (automatically set via [[Mode ObjFPC|<syntaxhighlight lang="delphi" inline>{$mode objFPC}</syntaxhighlight>]] or [[Mode Delphi|<syntaxhighlight lang="delphi" inline>{$mode Delphi}</syntaxhighlight>]]), the <syntaxhighlight lang="pascal" inline>procedure</syntaxhighlight> <syntaxhighlight lang="delphi" inline>assignFile</syntaxhighlight> is available, too. It performs the very same task.
* In [[Extended Pascal]] a combination of <syntaxhighlight lang="pascal" inline>bindingType</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>bind</syntaxhighlight> are usually used to achieve linking a file variable with an external entity.

[[Category: Delphi]]
[[Category: File Handling]]
[[Category: Code]]