FCLOSE

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.
	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.
10.1	Set EOF to File Limit on Close This flag indicates whether or not to set the EOF of a file to the file limit at close time. This is primarily useful when the file has been opened for user mapped access. The FPOINT and FCONTROL(6) intrinsics can be used to set the EOF of a file to any value except the file limit. This option can be used in this situation to set the EOF to the file limit.
	0	Do not change the EOF from its current value.
	1	Move the EOF to the file limit.
0:7	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. The disposition can also be effected by file equations and HPFOPEN item 50 Multiple access is NOT required to have a problem here as you can do a file equation, HPFOPEN and FCLOSE with one user, one time and the disposition is the "lowest" of all specified.

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

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

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

Condition Codes

Related Information