IFOPEN (HLI function)
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFOPEN call (OPEN) opens the specified file or group.
- Thread type
- multiple cursor IFSTRT, single cursor IFSTRT
- IFCALL function number
- 11
Syntax
IFOPEN(RETCODE,FILE_SPEC)
- Compile-only form
- Not available
- Execute-only form
- Not available
Specify the parameters in the syntax order shown above.
| Parameter | Description |
|---|---|
| RETCODE | [O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. See Completion return code (RETCODE). |
| FILE_SPEC | [I,c,r] The file specification is a required parameter that specifies the file or group to be opened. Specify a character string using the following format:
[FILE | GROUP] name [,deferred ddname]; [deferred ddname2]; [password[:newpassword]]; where: FILE or GROUP is the keyword that specifies that either a file or a group is to be opened. The keyword is optional. If you do not specify FILE or GROUP, Model 204 attempts to find a group with the specified name before searching for a file. name is required and specifies the name of the file or group to be opened. This name corresponds to a single file name or to a permanent group definition. deferred ddname is optional and specifies the name of the sequential data set used for deferred updates. If specified, this name must correspond to a DD statement in the JCL of the Host Language Interface/Model 204 service program. When you specify a deferred ddname to select the deferred form of file maintenance, file maintenance functions are divided into two phases, as described in "Notes and tips" below. If the deferred ddname is specified, insert a comma separator immediately following the file name. Note: The deferred update option is not available when a group open is performed. See "Notes and tips" below for more information about opening files in deferred update mode. deferred ddname2 is optional and specifies the name of a second data set in which deferred updates to the file are to be stored. This data set is for variable-length records. password is optional and specifies the user's identification that allows access to the file or group. You can omit the password for public and semipublic files and groups. Note: The update indicator in the IFSTRT function for IFAM2 or IFAM4 takes precedence over the password in IFOPEN. If the IFSTRT update indicator is 0, no updates are allowed, regardless of the password. If the IFSTRT update indicator is 1, the password indicates the privileges given. new password is an optional character string that changes the login password for the specified user, for future logins. Specify a new password if you need to replace the existing password. Note that changing passwords at open time requires special login privileges. If the new password is specified, insert a colon separator immediately following the password. |
Usage notes
Use the IFOPEN call before any data records are accessed to open a file or group. When IFOPEN is called, the named file or group becomes the current file or group.
On a single cursor IFSTRT thread, a file or group named in a previous call to IFOPEN is no longer available to the thread. On a multiple cursor IFSTRT thread, files or groups named in a previous IFOPEN call remain accessible.
If the file or group has already been opened by another thread or user, complete open processing is not performed by Model 204 and the file or group is made available to the new user.
Files and groups that are no longer needed should be closed explicitly with IFCLOSE to lessen memory requirements. However, IFCLOSE causes all server tables to be reinitialized, and saved compilations are lost.
Opening files in deferred update mode
When you specify a deferred data set name to select the deferred form of file maintenance, file maintenance functions are divided into the following two phases:
- The first phase updates records in the data area and is completed immediately.
-
Information for the second phase, the index update, is written onto the deferred update data set. Subsequent job steps must be run to complete phase two.
See Deferred update feature for information about job steps required for phase two.
Note: The deferred update mode can produce unexpected results if retrieval is attempted before phase two has been completed; this is because the record updates are not yet reflected in the index. Deferred updates are used to speed processing when major file maintenance is being performed.
The deferred update option is not available when a group open is performed. However, prior to the group open, the HLI program can open selected files individually in deferred update mode, and the following conditions apply:
- All updates to those files, even in group context, are written to the appropriate deferred data sets.
- Each deferred update file in the group must have its own deferred update data set, and phase two must be run for each file.
Completion return code (RETCODE)
IFOPEN returns the value (RETCODE) of the file's FISTAT parameter. In a group context, the file, or files, from which a nonzero FISTAT is returned cannot be determined. The settings of FISTAT are listed below.
| Code | Condition |
|---|---|
| 0 | File is normal. |
| 1 | File is not initialized. |
|
2 |
File is physically inconsistent. |
| 8 | File is full. |
| 16 | File has been recovered. |
| 32 | File is in deferred update mode. |
| 64 | File may be logically inconsistent. |
| 260 | The file or group could not be opened. A journal message further explains the problem. |
| 325 | IQB not large enough. Adjust the MODEL 204 parameters LIBUFF, LOBUFF, and IFAMBS as necessary. |
Note: If two or more FISTAT values are appropriate simultaneously, Model 204 returns the sum of these values.
Note the following conditions when evaluating IFOPEN completion codes:
- A nonzero completion code does not necessarily indicate a problem with the file, for example:
- A code of 0 or 16 indicates that file or group processing can proceed without further conditional testing. Any other return code indicates a potential problem and should be tested further.
- Codes 32 and 16 do not indicate broken files.
- The logically inconsistent condition (code 64) does not prevent use of the file. It is set by a soft restart of an updating request and indicates that data relationships that are maintained by the application might not be complete.
- Rocket Technical Support suggests that if you get a completion code that is not listed above, you first check HLI: Model 204 completion and ABEND codes to see if the code is listed. If it is not, the completion code is the sum of the codes listed above.
FISTAT codes are examined in subsequent calls
The Host Language Interface examines the FISTAT setting before any function is allowed to operate. After IFOPEN, any operation on a broken file (except IFRPRM) results in a completion code of 61, which indicates that the function was rejected.
Note: Although privileged users can reset the FISTAT parameter, subsequent operations on the file could cause further damage or unpredictable results.
Opening a file or group during system recovery
During system recovery, a file or group that is not participating in the system recovery can be opened.
However, updates are not allowed, and the file or group is opened with read-only privileges. The IFOPEN returns a normal completion code, but the first function call that tries to update the file or group returns a completion code of 40. To update, reissue the IFOPEN after system recovery has been completed. You can call IFEPRM to test the CURPRIV parameter for update privileges before attempting the update.
Coding examples (COBOL)
The COBOL coding example below opens a file and a group using the IFOPEN call:
- A file called FILEA with a password of MYSECRET. (In this example, the group name FILEA does not exist.)
- A group called WEEK without a password.
WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 FILE-INFO PIC X(15) VALUE `FILEA;MYSECRET;'. 05 GROUP-INFO PIC X(12) VALUE `GROUP WEEK;;'. . . . PROCEDURE DIVISION. . . . CALL "IFOPEN" USING RETCODE, FILE-INFO. . . . CALL "IFOPEN" USING RETCODE, GROUP-INFO. . . .