Alternate entry: _GROW
B: status = .grow( unit, llinks [, doerr] ); C: int _grow(FILE* unit, int llinks [, int doerr]);
.GROW is used to grow a disk file. "unit" must refer to an open disk file. Any other use is an error and will give unpredictable results. Permanent files are grown by the amount requested; temporary files are doubled unless the requested increment is more than the current size. The F.SIZE routine may be called to find the actual new file size. A request size of zero, will grow by some system chosen size.
If the grow fails, the action depends on the "doerr" variable and the actions specified when the file was opened. If "doerr" is zero, then IO.ERR is never called, the unit is not placed into error state, and "status" is always returned. If "doerr" is non-zero, and the grow fails, IO.ERR will be called to place the unit into error status. Depending on whether the "e" and "m" actions were specified on open, this may print an error message, or terminate the program with a message. See "expl b lib open".
If "doerr" is false (zero), or you specified the "e" action when opening the file, .GROW returns FMS style statuses. In TSS, these may be returned from FMS by DRL GROW, or faked by DRL GROW. If there is a denial return in batch, .GROW cannot determine the FMS status; therefore, .GROW fakes a "system space exhausted" (4010) status for temporary files and "filespace quota exhausted" (4013) status for permanent files.
Note that .GROW should not be necessary in most applications, since files are normally grown automatically when writing. (When writing to a file, this automatic growth occurs if you attempt to write just beyond the current end of the file.)
In past releases, .GROW accepted an ACC.FIL vector as its first argument instead of "unit". This is no longer supported. If necessary, use
u = open("file","ow"); .grow(u,llinks); close(u);
In past releases, .GROW would never put the unit into error state, and it always returned a status. Programs that expect this old behaviour should now specify "doerr" with a value of zero.
You should not attempt to grow a file by more than 16376 llinks per call. Attempting to do so will cause unpredictable results. In the unlilely event that a file needs to be grow by more than this amount, .GROW should be called multiple times.
Copyright © 2000, Thinkage Ltd.