HP 3000 Manuals HP 3000 Manuals
FCLOSE
INTRINSIC NUMBER 9
Closes a file.
IV IV IV
FCLOSE(filenum,disposition,seccode);
The FCLOSE intrinsic terminates access to a file. This intrinsic applies
to files on all devices. FCLOSE deletes the buffers and control blocks
through which the user process accessed the file. It also deallocates
the device on which the file resides and it may change the disposition of
the file. If you do not issue FCLOSE calls for all files opened by your
process, such calls are issued automatically by MPE when the process
terminates.
PARAMETERS
filenum integer by value (required)
A word identifier supplying the file number of the file
to be closed.
disposition integer by value (required)
Indicates the disposition of the file, significant only
for files on disc. This disposition can be overridden
by a corresponding parameter in a :FILE command entered
prior to program execution. The disposition options are
defined in Table 4-4
Default: disposition is zero for no change, no return
of disc space.
seccode integer by value (required)
Denotes the type of security initially applied to the
file, significant only for new permanent files. The
options are:
0--Unrestricted access--the file can be accessed by any
user, unless prohibited by current MPE provisions.
1--Private file creator security--the file can be
accessed only by its creator.
Default: seccode is zero for unrestricted access.
NOTE Both parameters are required when FCLOSE is specified in a program;
the default values are used when MPE closes any open files at the
end of a job or session.
Table 4-4. FCLOSE disposition Parameter Bit Settings
---------------------------------------------------------------------------------------
![[]](../../pic3k/M010088/TA04043c50.gif)
CONDITION CODES
CCE The file was closed successfully.
CCG Not returned by this intrinsic.
CCL The file was not closed, perhaps because an incorrect
filenum was specified, or because another file with the
same name and disposition exists in the system.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FCLOSE
The FCLOSE intrinsic terminates access to a file so that it cannot be
accessed again by the current program until it is re-opened. FCLOSE can
also be used to change the disposition currently assigned to a file by a
previous FOPEN.
Because of the special structure of KSAM files, it is not good practice
to set the disc space bit in the disposition parameter in an attempt to
save disc space. For this reason, 4 is the largest value that should be
assigned to the disposition parameter when using FCLOSE to close a KSAM
file.
When a file is opened by the FOPEN intrinsic, a file count maintained by
the system is incremented by one. When the file is closed with FCLOSE,
the file count is decremented by one. If more than one FOPEN is in
effect for a particular file, its disposition is recorded by the FCLOSE
call but is not put into effect until the file count is zero. The
effective disposition at that time is the smallest non-zero disposition
parameter specified among all the FCLOSE calls issued against the file.
For example, a file XYZ is opened three successive times by a process.
The first FCLOSE disposition is 1, the second FCLOSE disposition is 4,
and the third and last FCLOSE disposition is 2. The final disposition of
the file XYZ is 1, that is, it is saved as a permanent file with no
return of disc space.
The use of FCLOSE differs slightly in its application to new files or to
existing files.
CLOSING A NEW KSAM FILE. When a new file is created by FOPEN, the job
temporary and system file domains are not searched to determine whether a
file of the same name exists already. Only when a file is closed and
saved as a permanent or temporary file with FCLOSE, is such a search
conducted. The job temporary file domain is searched if the file is
closed with the domain field of disposition set to 2 or 3 (save as
temporary file); the system file domain is searched if the file is closed
with domain set to 1 (save as permanent file). If a file of the same
name is found in either directory, an error code is returned. Thus it is
possible to open a new file with the same name as an existing file, but
an error results if FCLOSE is used to save such a file in the same domain
with a file of the same name.
In general, unless you plan to use the file once and then delete it, a
newly created file should be closed using FCLOSE with the disposition
parameter set to 1, 2, or 3. There is no need to set disposition to 4 in
order to delete a new file since a new file is deleted when it is closed
with a disposition of 0.
The security code parameter (seccode) is set only when the disposition
parameter is set to 1. If you want exclusive access to a file being
saved as a new permanent file, you should set seccode to 1 when you close
the file for the first time. Otherwise, the file can be accessed by any
other user.
In Figure 4-1, a new file is closed and saved as a permanent file in the
system file domain (disposition = 1), and access is permitted to the file
by other users (seccode = 0).
CLOSING AN EXISTING KSAM FILE. Unless you plan to change the domain
where a file is saved, you usually close an existing file with both
FCLOSE parameters set to zero. There are two limitations: you cannot
change an existing permanent file to a temporary file, and you cannot
change the security code that was assigned to a permanent file at
creation.
______________________________________________________________________
| |
| <<**************************************>> |
| <<* READ DATA FROM $STDIN DEVICE *>> |
| <<**************************************>> |
| L1 : |
| READ(INPUT,-72): <<READ ONE RECORD FROM $STDIN>> |
| IF > |
| THEN BEGIN <<END OF FILE ON $STDIN>> |
| FCLOSE(FILNUM,1,0); <<CLOSE THE KSAM FILE>> |
| IF <> THEN |
| BEGIN <<CANNOT CLOSE THE KSAM FILE>> |
| MOVE MESSAGE:="CANNOT CLOSE THE KSAM FILE": |
| PRINT (MESSAGE,-29,0): |
| FCHECK(FILNUM,ERRORCODE): <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH):<<GET MESSAGE STRING>>|
| PRINT(MESSAGE,-LENGTH,0)1 <<PRINT ERROR MESSAGE>> |
| END; |
| TERMINATE; |
| END; |
| IF < |
| THEN BEGIN |
| MOVE MESSAGE:="ERROR OCCURRED WHILE READING INPUT"; |
| PRINT(MESSAGE,-34,0); |
| TERMINATE; |
| END; |
| PRINT(OUTPUT,-72,0); <<ECHO CHECK>> |
______________________________________________________________________
Figure 4-1. FCLOSE Example
Assume, for example, that a file was closed as a job temporary file.
Should you want to make the file permanent, close the file with the
following call:
FCLOSE(FILENUM,1,0) close job temporary file as permanent file
If, however, you want to maintain this file with its cuff ent
disposition, you would close it with the following call:
FCLOSE(FILENUM,0,0) close file with current disposition
Regardless of the value assigned to seccode, the type of security
initially applied to the file when it is closed as a new permanent file
is not subsequently changed.
DELETING A KSAM FILE. The FCLOSE intrinsic can be used to delete a KSAM
file from the system. If you intend to use a new file once only, you can
delete it at the same time you close it for the first time by setting the
FCLOSE parameters to zero:
FCLOSE(FILNUM,0,0) delete a new file
In this case, because disposition is zero, the file is returned to its
domain before FCLOSE is executed. Since the file is not assigned a
domain until it is closed the first time, this effectively deletes the
file.
A file that has been assigned to a domain by a previous FCLOSE, can be
deleted by the call:
FCLOSE(FILNUM,4,0) delete an existing file
Note that the only other methods for deleting a KSAM file are to use the
KSAMUTIL>PURGE command, or to issue two MPE :PURGE commands, one for the
data file and one for the key file.