CLOSE - close currently open unit.

Alternate Entry Name: .CLOSE

Usage:

B:
   ret = close(unit);

/* C users use "fclose" */

Where:

unit

is the unit number to close.

ret

is a status indicating the action of CLOSE.

=0: indicates that "unit" was successfully closed, and there are no open files associated with "unit".
>0: indicates that "unit" was successfully closed, but another file was previously associated with "unit", and this file has been unstacked.
<0: indicates that an error occurred while attempting to close "unit", and "unit" has NOT been closed.

Description:

CLOSE cleans up the open file with unit number "unit". For output files, this involves flushing buffers and writing end-of-files. Buffers are not flushed if the "o" action was specified in the call to OPEN which opened "unit".

If "unit" is attached to a permanent file, the file will be removed from the AFT if it was not there when the file was opened and if the "k" action was not specified to OPEN. If the "t" action was given to OPEN, the file will be removed from the AFT. If "unit" is a string which was being written into, CLOSE puts a '*e' on the end of the string to terminate it.

Errors During CLOSE:

It is possible that errors can occur while trying to close "unit". In particular, errors can occur on output when trying to flush the last buffer(s) in the file. Normally, this will result in an error message being printed, and the program being terminated. However, if the file was opened with a request for I/O error recovery (OPEN action "e") and an error occurs during CLOSE, "unit" will not be closed and CLOSE will return a negative value for "ret". F.ERR may be used to get more information about the error, or you can use .STRER to extract the posted error message. After an error, a subsequent call to CLOSE the same "unit" will succeed.