FOPEN

Syntax

  I16               CA           U16V     U16V     I16V     CA
  filenum := FOPEN (formaldesig, foption, aoption, recsize, device,
    CA       I16V
    formmsg, userlabels,
    I32V      I16V       I16V        I16V
    filesize, numextent, initialloc, filecode);

Functional Return

filenum

16-bit signed integer (assigned functional return)

Returns a unique file number identifying the opened file.

Parameters

formaldesig

character array (optional)

Passes a formal file designator, following file naming conventions. The file name must begin with a letter and contain alphanumeric characters, slashes, or periods. Terminate the string by placing a delimiter in the array element following the last valid character. The delimiter can be any nonalphanumeric character except a slash (/), period (.), colon (:), or exclamation point (!).

If the file name is the name of a user-defined file, it can begin with an asterisk (*). If the file name is the name of a system-defined file, it can begin with a dollar sign ($). The remote location of a device can be specified as filename:envid. The file, lockword, group, and account names are each limited to eight characters in length.

The formal file designator can contain command interpreter variables and expressions that are evaluated before the formal file designator is parsed and validated.

Default: A nameless file is assigned that can be read or written to, but not saved. (The domain option of a nameless file must specify a new file unless it is a device file.)

foption

16-bit unsigned integer by value (optional)

Specifies up to eight different file characteristics, as noted below, by setting corresponding bit groupings:

NOTE: For existing files, default conditions are specified in the file label. Device characteristics may override some foptions.

Bits

Value/Meaning

14:2

Domain

Indicates which file domain is searched to locate a file. A nameless disk file must always be a new file. A device file (such as a tape or terminal) always resides in the system file domain (permanent file directory). Always specify a device file as old or permanent.

The following bit settings are valid:

00

The file is new. No search is necessary.

01

The file is a permanent file. The system file domain (permanent file directory) is searched.

10

The file is a temporary file. The job file domain (temporary file directory) is searched.

11

The file is an old (permanent or temporary) file. The job file domain (temporary file directory) is searched. If not found, the system file domain is searched.

Default: 00

13:1

ASCII/binary

Indicates which code, ASCII or binary, a new file is in when written to a device that supports both codes. This option is applicable only at file creation time.

The following bit settings are valid:

0

Binary file

1

ASCII file

Default: 0

10:3

Designator

The actual file designator is the same as the formal file designator (000). This is the default and only setting allowed for KSAM files.

8:2

Record format

Bit settings indicate internal record structure for a file. This option is applicable only at file creation.

KSAM XL/64 support fixed-length records only (00). The file contains logical records of uniform length.

7:1

Carriage control

No carriage-control directive is expected for KSAM files.

5:1

Disallow file equation option

Indicates whether or not to allow file equations. A leading * in a formal file designator can override the setting to disallow FILE. The following bit settings are valid:

0

Allow FILE equations to override programmatic or system-defined file specifications.

1

Disallow FILE equations from overriding programmatic or system-defined file specifications.

Default: 0

2:3

File type option

Indicates internal record structure used to access records in a file. KSAM XL files are identified by a setting of 011. KSAM64 files are identified by a setting of 111.

0:2

Reserved for MPE/iX

aoption

16-bit unsigned integer by value (optional)

Specifies up to eight different file access options, as noted below, by setting corresponding bit groupings:

Bits

Value/Meaning

12:4

Access type

Indicates the type of access intended for the file. This option restricts usage of file system intrinsics.

The following bit settings are valid:

0000

Allows read access only, provided that the file's security provisions specify read access. FWRITE, FUPDATE, and FREMOVE intrinsic calls cannot reference this file. The end-of-file (EOF) is not changed.

0001

Allows write access only, provided that the file's security provisions allow write access. Any data written in the file prior to the current FOPEN request is deleted. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The EOF is set to 0.

0010

Allows write-save access only, if the file's security provisions allow write access. Previous data in the file is not deleted. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The EOF is not changed. Therefore, data is overwritten if a call to FWRITE is made. The system changes this value to append for message files.

0011

Allows append access only, if the file's security provisions allow either append or write access. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. For disk files, the EOF is updated after each FWRITE call. Therefore, data cannot be overwritten.

0100

Allows read/write (I/O) access only, provided that the file's security provisions allows both read and write access. If both read and write access are not allowed, the access type specified in the security provisions (either read or write) is allowed. Any file intrinsic except FUPDATE and FREMOVE can be called for this file. The EOF is not changed. This option is not valid for message files.

0101

Allows update access only, if the file's security provisions allows both read and write access. If both read and write access are not allowed, the access type specified in the security provisions (either read or write) is allowed. All file intrinsics can be called for this file. The EOF is not changed. This option is not valid for message files.

0110

Allows execute access only, if the file's security provisions allow execute access. This access allows read/write access to any loaded file. The program must be running in PM to specify execute access. This option is not valid for message files.

0111

Allows execute/read access only, if the file's security provisions allow execute access. This access allows only read access to any loaded file. The program must be running in PM to specify execute/read access. This access is changed to execute (only) access for KSAM, CIR, and RIO files. This option is not valid for message files.

Default: 0000

10:1

Dynamic locking

Enables/disables file locking for the file. When this option is specified, the FLOCK and FUNLOCK intrinsics can be used to dynamically permit or restrict concurrent access to a disk file by other processes at specified times.

The following bit settings are valid:

0

Disallow dynamic locking/unlocking.

1

Allow dynamic locking/unlocking.

Default: 0

If several accessors are sharing the file, they must all specify, or not specify, this option. For example, if a file is opened with the dynamic locking option enabled, and a subsequent accessor tries to open the file with dynamic locking disabled, the subsequent attempt to open fails.

NOTE: The file system does not guarantee exclusive access, even when FLOCK and FUNLOCK are used, unless all programs that access the file cooperate by using locking. A program that opens the file with dynamic locking enabled will still be allowd to modify the file, even if it never calls FLOCK.

8:2

Exclusive option

Indicates continuous exclusive access to this file, from open to close. Use this option when performing a critical operation (for example, updating the file).

The following bit settings are valid:

00

If access type option (aoption bit (12:4)) specifies read only access, then read-share access takes effect. Otherwise, exclusive access takes effect. Regardless of which access option was selected, FFILEINFO reports zero.

01

Exclusive access. After the file is opened, any additional HPFOPEN/FOPEN requests for this file are prohibited until this process issues the FCLOSE request or terminates. If any process is already accessing this file when an HPFOPEN/FOPEN call is issued with exclusive access specified, an error status is returned. If another HPFOPEN/FOPEN call is issued for this file while exclusive access is in effect, an error code is returned to the process that issued the call. Request exclusive access only if the lock access mode is allowed by the security provisions for the file.

10

Read-share access (semi-exclusive access). After the file is opened, concurrent write access to this file through another HPFOPEN/FOPEN request is prohibited, whether issued by this process or another process, until this process issues the FCLOSE request or terminates. A subsequent request for the read/write or update access type option (aoption bit (12:4)) obtains read access. However, other types of read access are allowed. If a process already has write access to the file when this call is issued, an error code is returned to the calling process. If another HPFOPEN/FOPEN call that violates the read only restriction is issued while read-share access is in effect, that call fails and an error code is returned to the calling process. Request read-share access only if the lock access mode is allowed by the security provisions for the file.

11

Share access. After the file is opened, concurrent access to this file by any process is permitted, in any access mode, subject to other security provisions in effect.

Default: 00

5:2

Multiaccess mode option. KSAM XL/64 support no multiaccess (00).

Default: 00

4:1

NOWAIT I/O option. KSAM XL/64 does not support NOWAIT I/O (0).

Default: 0

3:1

Copy mode option Determines whether a file should be treated as a standard sequential file (copy by logical record) or physical block (copy to another file).

KSAM XL/64 do not allow the copy mode option (0).

Default: 0

0:3

Reserved for MPE/iX.

recsize

16-bit signed integer by value (optional)

Passes the size, in halfwords or bytes, of the logical records in the file. Positive values are halfwords, negative values are bytes. The valid range is dependent on storage and record formats:

• For fixed-length and undefined-length ASCII files, the valid range is 1 to 32,767 bytes.

• For variable-length ASCII files and fixed-length, variable-length, and undefined-length binary files, the range is 1 to 32,766 bytes (1 to 16,383 halfwords). All odd values specified are rounded up to the next even value (the next halfword boundary).

Default: Device dependent.

device

character array (optional)

Passes a string of ASCII characters terminating with any nonalphanumeric character except a slash (/) or period (.), designating the device where the file is to reside. For a KSAM file, the device must be a random access device such as a disk.

Default: DISC

ksamparam

character array (optional)

Contains a description of the KSAM parameters including the primary key and up to 15 alternate keys. If a new file is being created, this parameter must be specified. If this is an existing file, check flag word field to see if the default values are acceptable. In the flag word field you can set bit 13 to sequential write. For COBOL, set flag 9. If this is not an existing file, specify this field explicitly. (Refer to Figure 9-6 "FOPEN KSAM Parameter Format" for parameter format.)

Language ID Number

This three-digit code identifies the native language to be used for the file. To display a list of native languages that are available on your system, enter RUN NLUTIL.PUB.SYS.

If the file already exists, this field is ignored.

Flag word

The flag word contains a halfword defining the file characteristics.

Bits

Value/Meaning

15:1

Reserved, do not use. Always set to 0.

14:1

Enter 1 if record numbering is to start with 1. Enter 0 if record numbering is to start with 0.

13:1

Enter 1 if only sequential writing by primary key is allowed. Enter 0 if random writing by primary key is allowed.

12:1

Enter 1 if deleted record space can be reused. Enter 0 if deleted record space cannot be used.

11:1

Enter 1 if a language type is specified. Enter 0 if a language type is not specified.

10:1

Enter 1 if the primary key cannot be changed with the FUPDATE intrinsic for files that are opened for sequential processing. Enter 0 if the primary key can be changed with the FUPDATE intrinsic for files that are opened for sequential processing. This enables KSAM processing of COBOL information according to COBOL standards.

9:1

Enter 1 if the file is programmatically accessed by the COBOL programming language. Enter 0 if the file is not programmatically accessed by the COBOL programming language. This enables KSAM to process COBOL information according to COBOL standards.

8:1

Enter 1 if selecting optimal block size.

0:9

Enter 0. These bits are reserved and must contain zeros.

Number of Keys

In bits 8:8, enter a number between 1 and 16 specifying the number of keys to be defined for this file.

Key Definitions

Each key in the file requires a 4-halfword word definition. The first definition is always the primary key. Up to 15 alternate keys are allowed for any KSAM file. The key definitions contain the key type, key length, key location, duplicate key flag, and random insert flag:

Key Type

Bits 0:4 specify the type of key:

Value

Meaning

0001

Byte key (1 to 255 bytes)

0010

Short integer key (255 bytes)

0011

Integer key (255 bytes)

0100

Real number key (255 bytes)

0101

Long real number key (255 bytes)

0110

Numeric display key (1 to 28 bytes)

0111

Packed decimal key (1 to 14 bytes)

1000

Signed packed decimal key (2 to 14 bytes)

1001

IEEE floating-point decimal key (4, 8, or 16 bytes)

Key Length

Bits 4:12 specify the key length. Enter the length of the key in bytes. A maximum of 255 bytes is allowed, but the length is dependent on the type of key data specified.

Key Location

Enter the relative location in bytes of the key field in the record. Note that the first byte of the record is considered 1.

Duplicate Key Flag

Bits 0:1 specify the duplicate key flag. Enter 1 if duplicate key values are allowed for this key. Enter 0 if duplicate key values are not allowed for this key.

Random Insert Flag

Bits 8:1 specify the random insert flag. This field specifies the method of inserting duplicate key values. To use this feature, the previous duplicate key flag must be set to 1. Bits 0:8 and 9:7 are reserved and always set to 0.

Enter 1 if duplicate key values are to be inserted randomly in the duplicate key chain.

Enter 0 if duplicate key values are to be inserted at the end of the duplicate key chain.

userlabels

16-bit signed integer by value (optional)

Passes the number, in the range 0 to 254, of user-label records to be created for the file. Applicable to new disk files only.

Default: 0

filesize

32-bit signed integer by value (optional)

Passes the maximum file capacity.

KSAM XL/64 require extra space for their index area. The actual space needed is computed by the KSAM XL type manager, based on the file size specified by the user. If the space required to build a KSAM XL file of the user-specified size exceeds 4 gigabytes, FOPEN returns an error. For a KSAM64 file, FOPEN returns an error if the space required exceeds 128 gigabytes

numextent

16-bit signed integer by value (optional)

Passes a value in the range 1 to 32 that determines the number of extents for the file. If a value of 1 and an initialloc value of 1 is specified, the file is created as one contiguous extent of disk space. If a value >1 is specified, a variable number of extents (with varying extent sizes) are allocated on a need basis. Applicable only at file creation.

Default: >=1 extents

initialloc

16-bit signed integer by value (optional)

Passes an integer value in the range 1 to 32 that determines the number of extents to be allocated to the file initially. Applicable only at file creation.

Default: 0

filecode

16-bit signed integer by value (optional)

Passes a value that can be used as a file code to identify the type of file. This code is recorded in the file label and is accessible through the FFILEINFO intrinsic. Applicable only at file creation (except when opening an old file that has a negative file code).

If the program is running in user mode, specify a file code in the range 0 to 32,767 to indicate the file type being created; programs running in user mode can access files with nonnegative file codes. If the program is running in privileged mode, specify a file code in the range -32,768 to 32,767; programs running in privileged mode can access files with a file code in the range -32,768 to 32,767. If an old file with a negative file code is opened, the file code specified must match the file code in the file label.

Default: 0

Operation Notes

Condition Codes

CCE

Request granted. The file is open.

CCG

Not returned.

CCL

Request denied. For example, another process already has exclusive or semi-exclusive access for this file, the privilege level of this file is not user (3), or an initial allocation of disk space cannot be made due to lack of disk space. If the file is not opened successfully, the file number value returned by FOPEN is 0. Call the FCHECK intrinsic for more details.