HP 3000 Manuals HP 3000 Manuals
FCLOSE
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.
Table 4-2. (cont.)
Bits Value/Meaning
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.)
Table 4-2. (cont.)
Bits Value/Meaning
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.
NOTE When a file is opened with the FOPEN/HPFOPEN intrinsic, the file
count (maintained by the operating system for each file) is
incremented by one; when a file is closed, the file count is
decremented by one. If more than one FOPEN/HPFOPEN is in effect
for a particular file, its domain disposition is saved but not
affected by the FCLOSE call until the file count is decremented to
zero; the saved disposition is the smallest nonzero disposition
parameter specified for all FCLOSE calls issued against the file.
For example, the file XYZ is opened three successive times by a
process. The first FCLOSE disposition is 1, the second is 2, and
third is 3. On the last FCLOSE, a disposition of 1 will occur.
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)