 |
» |
|
|
|
NM and CM callable. Terminates access to a file on any device. Syntax |  |
I16V I16V I16V
FCLOSE(filenum,disposition,securitycode);
|
Parameters |  |
- filenum
16-bit signed integer by value (required) Passes the file number of the file to be closed.
- disposition
16-bit signed integer by value (required) Passes the disposition of the file, significant only for files on
disk and magnetic tape; ignored for spooled and hot
printers. (ASC) This parameter is not meaningful for asynchronous devices.
 |  |  |  |  | NOTE: This disposition can be overridden by a corresponding parameter
in a FILE command entered prior to program execution. |  |  |  |  |
The disposition options are:
Bits | Value/Meaning |
---|
13:3 | Domain disposition: | | - 000
No change. The disposition remains as it was
before the file was opened. If the file is new,
it is deleted by FCLOSE; otherwise, the file is assigned to the domain it belonged to previously. An unlabeled tape file is rewound and a labeled tape is rewound and unloaded. - 001
Close as a permanent file. If the file is a disk file,
it is saved in the system file domain. A new or old temporary
file on disk has an entry created for it in the system file
directory. If a file of the same name already exists in the
directory, an error code is returned and the file remains open.
If the file is a permanent file on disk, this domain disposition
has no effect. If the file is stored on magnetic tape, the tape is
rewound and unloaded.
| 13:3 | Domain disposition (Continued): | | - 010
Close as a temporary job file (rewound). The file is
retained in your temporary (job/session) file domain and can
be requested by any process within your job/session. If the
file is a disk file, the file name is checked.
If a file of the same name already exists in the temporary
file domain, an error code is returned and the file remains open.
If a file resides on unlabeled magnetic tape, the tape is rewound.
If the file resides on labeled magnetic tape, the tape is
backspaced to the beginning of the opened file.
- 011
Close as a temporary job file (not rewound). This option
has the same effect as domain disposition 010, except that tape
files are not rewound. In the case of unlabeled magnetic tape,
if this FCLOSE is the last done on the device (with no
other FOPEN/HPFOPEN calls outstanding), the tape is
rewound and unloaded. If the file resides on a labeled magnetic
tape, the tape is positioned to the beginning of the next file
on the tape.
- 100
Release the file. The file is deleted from the system.
- 101
Makes a permanent standard disk file temporary (valid only for
standard disk files with either fixed-length, variable-length, or
undefined-length record formats). The file is removed from the
permanent file directory and inserted into the temporary file
directory. (PM capability is required for this option.)
| 11:2 | Disk space disposition (valid only for standard disk files with either
fixed-length, undefined-length, or variable-length record formats): | | - 00
Does not return any disk space allocated beyond the
end-of-file marker.
- 01
Returns any disk space allocated beyond the end-of-file (EOF) marker to the system.
The EOF becomes the file limit; records cannot be added to the file beyond the EOF.
- 10
Returns any disk space allocated beyond the end-of-file (EOF) marker to the system.
The file limit remains the same; records can be added to the file beyond EOF, up
to the file limit. The disk space disposition takes effect on each FCLOSE.
| 0:11 | Reserved for the system. |
- securitycode
16-bit signed integer by value (required) Returns the type of security initially applied to the file (significant
for new permanent files only). The valid options are:
Value | Meaning |
---|
0 | Unrestricted access; can be accessed by any user, unless prohibited | 1 | Private file creator security; can be accessed only by the creator |
The securitycode parameter selects the security mask
assigned to new permanent files whether or not the file is within an
MPE group. (ASC) This parameter is not meaningful for asynchronous devices.
Operation Notes |  |
FCLOSE deletes buffers and control blocks where the process accessed the file.
It also deallocates the device where the file resides, and it can change the disposition
of the file. If FCLOSE calls are not issued for all files opened by the process,
the calls are issued automatically by the operating system when the process terminates.
All magnetic tape files are left offline after FCLOSE calls, to indicate that
the system operator can remove them. For circular files, deletion of disk space beyond the end of file is not allowed.
Such a request is not an error but no operation is performed. For RIO files, cutback
disposition works
the same as for flat files: if you have any access to the file other than read and
you call FCLOSE with disp=%10, the file is closed, the space beyond the EOF is returned
to the system, the file's limit is changed to EOF, and no error is returned. The FCLOSE intrinsic can be used to maintain position when
creating or reading a labeled tape file that is part of a volume
set: If the file is closed with a disposition code of 3, the
tape does not rewind but remains positioned at the next file. If the file is closed with a disposition code of 2, the tape
rewinds to the beginning of the file, but is not unloaded. A subsequent request to open the file does not reposition if the
sequence (seq) subparameter
of formmsg in FOPEN/HPFOPEN specifies NEXT or the
default (1). A disposition code of 1 (rewind and unload) implies
the close of an entire volume set. If unlabeled magnetic tape is closed with a disposition code
of 0, 1, or 4, and the tape was written to while open, FCLOSE writes
three EOFs at the end of the tape before performing a rewind or
rewind/unload. This ensures that all tapes have an acceptable number
of EOF marks at the end. The three EOFs are written only after the
last FCLOSE occurs, before the rewind, and only if the tape was
written on. For circular files, deletion of disk space beyond the end-of-file
is not allowed.
If the new file status time stamp has changed, FCLOSE updates
this time stamp in the file label on disk.
(ASC) For serial devices: If one of the following device settings is altered programmatically,
the device returns to the system default at FCLOSE: Disable read timeout (value set by FCONTROL itemnum=4). Disable subsystem break (enabled through FCONTROL itemnum=17). Enable printing a string of three exclamation points (!!!)
when a line is deleted (disabled through FCONTROL itemnum=35). Disable transparent editing (enabled through FCONTROL itemnum=41).
These are only the control actions taken by the device control software;
additional changes can result from actions taken by other software modules.
For example, if your program disables the system break feature, break is
reenabled on FCLOSE by the CI software.
For most device settings that can be programmatically altered,
ensure that the altered characteristics are returned to their original
settings when the program ends unless the altered setting define the way
the device should act. For example, if the speed setting of a device is
programmatically altered, you should return the terminal to its original
setting unless the new speed setting should remain in effect for other
files opened against the device.
When all files have been closed on a device and the device is no longer
under the control of a program or session, all device characteristics are
returned to those specified by the device's configuration.
Directories exist only in the permanent file domain. Permanent (001)
and no change are the only values supported for disposition (13:3) bits
when filenum references a directory. Attempts to move a directory from
the permanent file domain to either the new or temporary file domain will
fail with a CCL condition code and the directory remains open.
Directories cannot be deleted by FCLOSE. Attempts to release a directory
will fail with a CCL condition and the directory remains open. Condition Codes |  |
- CCE (2)
Request granted. - CCG (0)
Not returned. - CCL (1)
Request denied. The file was not closed; an
incorrect filenum was specified or another file with the same
name and disposition exists. Any outstanding write I/Os that
failed (for example, buffered writes that are done in background) or
an illegal disposition.
Related Information |  |
- Intrinsics
FOPEN - Commands
None - Manuals
Accessing Files Programmer's Guide (32650-90017) and MPE XL Asynchronous Serial Communications
Programmer's Reference Manual (32022-90012)
|