Assign: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		The [[Borland Pascal]] [[Procedure\|procedure]] [`assign`](https://www.freepascal.org/docs-html/rtl/system/assign.html) associates a file variable with an external entity (e. g. a device file or a file on disk). `Assign` only operates on the program’s internal management data and has otherwise no immediate observable effect.
2	2
3	3		## usage
4	4
5	5		In non-ISO modes the [[FPC]] needs files to be explicitly associated with external entities. This can be achieved with `assign`. The first parameter is a file variable, the second parameter specifies a path.
6	6
7	7		```delphi
8	8		program assignDemo(input, output, stdErr);
9	9		var
10	10		FD: text;
11	11		begin
12	12		assign(FD, '/tmp/assignDemo.txt');
13	13		assign(FD, '/root/.bashrc');
14	14		end.
15	15		```
16	16
17	17		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\|chr(0)]]) do not pose a problem to `assign`. It merely operates on internal management data.
18	18
19	19		## application
20	20
21	21		- `Assign` is used before operating on any file variable.
22	22
23	23		var
24	24
25	25		` executable: file of Byte;`
26	26
27	27		begin
28	28
29	29		` assign(executable, paramStr(0));`\
30	30		`` fileMode := 0; { 0 = read-only; only relevant for `file of …` variables } ``\
31	31		` reset(executable);`\
32	32		` writeLn(paramStr(0), ' has a size of ', fileSize(executable), ' Bytes.');`
33	33
34	34		end.
35	35
36		-	~~</syntaxhighlight>~~
37		-
38	36		- `Assign` can be used to redirect standard files [`input`](https://www.freepascal.org/docs-html/rtl/system/input.html)/[`output`](https://www.freepascal.org/docs-html/rtl/system/output.html). Our [[Hello, World]] program needs only a few changes as highlighted:
39	37
40	38		const
41	39
42	40		` blackhole = {$ifDef Linux} '/dev/null' + {$endIf}`\
43	41		` {$ifDef Windows} 'nul' + {$endIf}`\
44	42		` '';`
45	43
46	44		begin
47	45
48	46		` assign(output, blackhole);`\
49	47		` rewrite(output);`\
50	48		` writeLn('Hello world!');`
51	49
52	50		end.
53		-
54		-	~~</syntaxhighlight>~~
55	51
56	52		## caveats
57	53
58	54		- Regardless of the utilized [[Character and string types\|string data type]], `assign` can only process paths of up to 255 [[Byte\|Bytes]]. This limitation comes from the internally used [`fileRec`](https://www.freepascal.org/docs-html/rtl/system/filerec.html)/[`textRec`](https://www.freepascal.org/docs-html/rtl/system/textrec.html). Relative paths in conjunction with working directories cannot overcome this. Cf. [FPC issue 35185](https://gitlab.com/freepascal.org/fpc/source/-/issues/35185).
59	55		- Since `assign` 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.
60	56
61	57		## notes
62	58
63	59		- If `{$modeSwitch objPas+}` (automatically set via [[Mode ObjFPC\|{$mode objFPC}]] or [[Mode Delphi\|{$mode Delphi}]]), the `procedure` `assignFile` is available, too. It performs the very same task.
64	60		- In [[Extended Pascal]] a combination of `bindingType` and `bind` are usually used to achieve linking a file variable with an external entity.
65	61
66	62		---
67	63		From the Free Pascal wiki, page "Assign", as it stood on 2022-09-03 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
68	64		Category: Code
69	65		Category: Delphi
70	66		Category: File Handling

Back to history