.GROW - grow a file.

Alternate entry: _GROW

Usage:

B:
   status = .grow( unit, llinks [, doerr] );
C:
   int _grow(FILE* unit, int llinks [, int doerr]);

Where:

unit: is the unit number of an open disk file that is to be grown.
llinks: specifies the minimum number of llinks that the file should grow. In batch, this is rounded up to the next link. A temporary file is grown by the maximum of this amount and the current size of the file. A value of minus -1 indicates that no grow is to be done, but the file description needs to be updated because the file may have been grown by something else in the system.
doerr: Is an optional argument argument indication how grow denials will be handled. It defaults to non-zero indicating that a grow failure should set the unit into error status. See below for further discussion.
status: is the negative of the value in bits 1-11 of the first status word. Zero indicates that the "grow" operation was successful.

Description:

.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.)

Notes:

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.

.GROW - grow a file.

Usage:

Where:

Description:

Notes:

See Also: