FOPEN
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| Edition 7 E0701 | |
| Edition 7 E0300 ♥ | |
| Edition 6 E0195 |
Syntax
I16 CA U16V U16V I16V CA
filenum := FOPEN (formaldesig, foption, aoption, recsize, device,
CA I16V I16V I16V I32V
formmsg, userlabels, blockfactor, numbuffer, filesize,
I16V I16V I16V
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 interpreted according to MPE-escaped semantics. The file name must be terminated by a nonalphanumeric character other than a period (.), a slash (/), a hyphen (-), and an underscore (_).
The file referred to by formaldesig can be either an MPE file (i.e., one that uses MPE syntax) or it can follow HFS syntax. If formaldesig follows MPE syntax, the file name can include password, group, and account specifications. The file name can backreference a file equation and optionally be preceded by an asterisk. If formaldesig follows HFS syntax, the file name must start with either a dot (.) or a slash (/).
The file referred to by formaldesig may reside either in an MPE group or in an HFS directory. For files located in HFS directories, traverse directory entries (TD) access is required to all directories specified in formaldesig. If there is no TD access, FOPEN fails and a call to FCHECK with filenum set to 0 will return a system error code (398) in the fserrorcode parameter.
If formaldesig is an escaped pathname:
you cannot reference remote files
it cannot express a name equivalent to filename:envid
you cannot use the device parameter (device=node#) to specify the remote location of a device
The formal file designator can contain command interpreter variables and expressions that are evaluated before formaldesig is parsed and validated.
As the default, FOPEN creates a nameless file 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.)
(ASC) This parameter is recommended for use with asynchronous device files because of the flexibility it provides.
- foption
16-bit unsigned integer by value (optional)
Specifies up to eight different file characteristics by setting corresponding bit groupings:
NOTE: For old 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.
- 13:1
ASCII/binary
Indicates which code, ASCII or binary, a new file is in when written to a device that supports both codes. For disk files, this also affects padding (zeros for a binary file, blank characters for an ASCII file) that can occur when you issue a direct-write intrinsic call (FWRITEDIR) to a record that lies beyond the current logical end-of-file indicator. By default, magnetic tape and files are treated as ASCII files. This option is applicable only at file creation.
The following bit settings are valid:
- 0
Binary file
- 1
ASCII file
Default: 0
- 10:3
Designator
Passes a value indicating a special file opening. Any of the following special files can be specified with the formaldesig parameter. For example, a file name of $STDLIST opens standard list.
The following bit settings are valid:
- 000
The actual file designator is the same as the formal file designator.
- 001
The actual file designator is $STDLIST.
- 010
The actual file designator is $NEWPASS.
- 011
The actual file designator is $OLDPASS.
- 100
The actual file designator is $STDIN.
- 101
The actual file designator is $STDINX.
- 110
The actual file designator is $NULL.
For example, if you pass MYFILE in the formaldesig parameter, then using the designator option to equate it with $STDIN is equivalent to allowing the file equation FILE MYFILE=$STDIN.
The designator option is not equated with the formaldesig parameter if both of the following conditions are true:
The disallow file equation option foption bit (5:1) allows file equations for this file opening.
An explicit or implicit FILE command equating the formal file designator to a different actual file designator occurs in the job/session.
- 8:2
Record format
Bit settings indicate internal record structure for a file. This option is applicable only at file creation.
The following bit settings are valid:
- 00
Fixed-length records. The file contains logical records of uniform length.
Fixed-length records are supported by disk and magnetic tape devices only.
- 01
Variable-length records. The file contains logical records of varying length. This format is restricted to records that are written in sequential order. The size of each record is recorded internally. The actual physical record size is determined by multiplying the record size (specified or default) plus one by the blocking factor, and adding one word for the end-of-block indicator.
This format is the only valid combination with byte stream (1) record format extension.
Variable-length records are supported by disk and magnetic tape devices only.
- 10
Undefined-length records. The file contains records of varying length that were not written as variable-length files. By default, all files not on disk or magnetic tape are treated as containing undefined-length records. The file system makes no assumption about the amount of data that is useful. You must determine how much data is required. For undefined-length records, only the data supplied is written, with no information about its length.
Undefined-length records are supported by all devices.
- 7:1
Carriage control
Indicates whether or not a carriage control directive is supplied in the calling sequence of each FWRITE call that writes records onto the file. This option is applicable only at file creation.
The following bit settings are valid:
- 0
No carriage-control directive is expected.
- 1
Carriage-control directives are expected.
A carriage-control character passed through the controlcode parameter of FWRITE is acted upon for files that have carriage-control specified in HPFOPEN/FOPEN. Embedded control characters are treated as data for files specified no carriage-control, and do not invoke spacing. Spacing action can be specified on files specified with carriage-control either by embedding the control in the record or by sending the control code directly through the controlcode parameter of FWRITE.
Carriage control is supplied only for ASCII files. This option and the ASCII/binary option (foption bit (13:1)) are mutually exclusive, and attempts to open new files with both binary and carriage control directives result in an access violation.
If a carriage-control character is sent to a file where the control cannot be executed directly (for example, line-spacing characters sent to a disk or tape file), the control character is embedded as the first byte of the record. If a carriage-control character is sent to other types of files, the control is transmitted to the driver.
Control codes %400 through %403 are remapped to %100 through %103, so that they fit into one byte and thus can be embedded. Records written to the line printer with control codes %400 through %403 should contain only control information. A record written with control codes %400 through %403 and no data (count=0, or embedded control and count=1) does not cause physical I/O of any sort.
To compute record size, the file system assumes carriage-control informatio to be part of the data record. Therefore, specifying the carriage-control option adds one byte to the record size when the file is originally created. For example, a specification of REC=-132,1,F,ASCII;CCTL results in a recsize of 133 bytes.
In general, the entire record can be read (the size of which is returned in itemnum=67 of the FFILEINFO intrinsic). However, on writes to files where carriage-control characters are specified, the data transferred is limited to recsize-1 unless a control of 1 is passed, indicating that the data record is prefixed with embedded carriage-control characters.
- 6:1
Labeled tape
- 0
No labeled tapes
- 1
Labeled tapes
Default: 0
- 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.
- 2:3
File type option
Indicates internal record structure used to access records in a file. If the file is old, this option is ignored. Specifying a designator option (foption bits (10:3)) value other than zero overrides this option. This option is applicable only at file creation.
The following bit settings are valid:
- 000
Standard (STD) file
- 001
KSAM/3000 file
- 010
Relative I/O (RIO) file
- 011
KSAM XL file
- 100
Circular (CIR) file
- 101
NM spoolfile
- 110
Message (MSG) file
- 111
KSAM64 file
- 1:1
Record format extension
Byte stream record format is specified by setting the record format, foption (8:2), to variable-length records (01) and the record format extension, foption (1:1), to byte stream record format (1). Zero is the default value for this option. Using any record format value other than variable-length records with the record format extension results in an FSERR 49 (unimplemented function). Byte stream record format may only be specified for standard disk files. Specifying byte stream record format for any other type of file result in FSERR 49 error.
Record format extension
Files created using byte stream record format are assigned file attributes which override values specified by FOPEN parameters. The file attributes are as follows:
- Option
Description\Value
- foption (13:1)
ASCII/binary\ASCII (1)
- foption (7:1)
Carriage control\NOCCTL (0)
- recsize
Logical record size\1 Byte (-1)
- blockfactor
Blockfactor\1 Record/block
- 0:1
Reserved for the operating system
- aoption
16-bit unsigned integer by value (optional)
Specifies up to eight different file access options by setting corresponding bit groupings:
- Bits
Value/Meaning
- 12:4
Access type
Indicates the type of access intended for the file. This option restricts/allows minimal use of file system intrinsics.
The following bit settings are valid:
- 0000
Allows read access only, if the file's security provisions specify read access. FWRITE, FUPDATE, and FWRITEDIR intrinsic calls cannot reference this file. The end-of-file (EOF) is not changed; the record pointer starts at 0.
- 0001
Allows write access only, if the file's security provisions allow write access. (This only applies if the file is not open with shared access, otherwise you are given a "0010" access) Any data written in the file prior to the current FOPEN request is deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR intrinsic calls cannot reference this file. The EOF is set to 0; the record pointer starts at 0. On magnetic tape an EOF is written when the file is closed even if no data is written.
- 0010
Allows write-save access only, if the file's security provisions allow write access. Previous data in the file is not deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR intrinsic calls cannot reference this file. The EOF is not changed; the record pointer starts at 0. 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. FREAD, FREADDIR, FREADSEEK, FUPDATE, FSPACE, FPOINT, and FWRITEDIR intrinsic calls cannot reference this file. Data written by the FWRITE intrinsic is appended to the EOF, thereby extending the EOF. When a file is opened for append access, it is impossible to overwrite data in the 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 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 ( read or write) is allowed. Any file intrinsic except FUPDATE can be called for this file. The EOF is not changed; the record pointer starts at 0. 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 (read or write) is allowed. All file intrinsics, including FUPDATE, can be called for this file. The EOF is not changed; the record pointer starts at 0. 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.
- 1000
Reserved for the operating system.
- 1001
Allows directory read access. This access allows you to open a directory and read its contents. Attempt to open a file with this type of access will return an error.
- 11:1
Multirecord
Indicates whether or not individual read or write requests are confined to record boundaries.
The following bit settings are valid:
- 0
Nonmultirecord mode (NOMULTI)
- 1
Multirecord mode (MULTI)
If the number of half words or bytes to be transferred (specified in the length parameter of the read or write request) exceeds the size of the physical record that is referenced, the remaining half words or bytes are taken from subsequent successive records until the number specified by length has been transferred. For message (MSG) files not accessed with the copy mode option (aoption bit (3:1)) enabled, the file system sets this option to zero. This option is available only if the inhibit buffering option (aoption bit (7:1)) is set to 1.
- 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
The process can continue this temporary locking/unlocking until it closes the file. 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.
Dynamic locking/unlocking is made possible through the equivalent of a global resource identification number (RIN) assigned to the file and temporarily acquired by FOPEN.
Cooperating accessors that have opened a file with the dynamic locking option enabled must access the file using either the FLOCK and FUNLOCK intrinsics to ensure exclusive use of the file. These accessors are allowed concurrent access even when not using FLOCK and FUNLOCK, but exclusiveness is not guaranteed.
Lock access is available to a process if it has lock, execute, append, or write access to the file. This option is ignored for files not residing on disk.
If this option is specified for a new file, the dynamic locking bit is NOT changed to 0 as it is on MPE V systems. When a file is new, there can be only one accessor so setting this bit really makes no sense. When opening a directory, dynamic locking must be set to 0 (disallowed).
(ASC) Not valid for asynchronous device files.
- 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 bits (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.
For message files, specifying this value indicates that there can be only one writer and only one reader.
Exclusive access cannot be specified for directories.
- 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 bits (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.
For message files, this value specifies there can be multiple writers, but only one reader.
- 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.
For message files, this value specifies that there can be multiple readers and multiple writers.
- 7:1
Inhibit buffering option
Enables/disables automatic buffering by the operating system.
The following bit settings are valid:
- 0
Allow normal buffering (BUF)
- 1
Inhibit buffering (NOBUF)
NOBUF access is for physical block transfer; not logical record transfer.
NOBUF access assumes responsibility for blocking and deblocking of records in the file. To be consistent with files built using buffered I/O, records should begin on half word boundaries. When the information content of the record is less than the defined record length, pad the record with blanks if the file is ASCII, or with zeros if the file is binary.
The record size and block size for files with NOBUF specified follow the same rules as those files that are created using buffering. The default blocking factor for a file created under NOBUF is 1.
If a file is opened NOBUF without multirecord mode specified in multirecord option (aoption bit (11:1)), a maximum of only one block of data per read or write can be transferred.
The end-of-file (EOF) marker, next record pointer, and record transfer count are maintained in terms of logical records for all files. The number of logical records affected by each transfer is determined by the size of the transfer.
Transfers always begin on a block boundary. Those transfers that do not transfer whole blocks leave the next record pointer set to the first record in the next block. The EOF marker always points at the last record in the file.
For files opened NOBUF, the FREADDIR, FWRITEDIR, and FPOINT intrinsics treat the recnum parameter as a block number.
Indicate non-RIO access to an RIO file by specifying the file NOBUF. Use the physical block size from FFILEINFO to determine the maximum transfer length.
For message files, the file system normally resets the inhibit buffering option bit to zero. However, a message file can be opened with NOBUF if the copy mode option (aoption bit (3:1)) is set to 1; this determines whether access to the file is record-by-record or by block.
If you are reading a message file with the copy mode option enabled, the inhibit buffering option has the following meaning:
- 0
Read by logical record
- 1
Read by physical block
(ASC) Not valid for asynchronous device files.
- 5:2
Multiaccess mode option
Indicates how the file's record pointer is to be shared. This option is useful for sharing standard input devices where there is some natural sequence of access to the file. This option permits processes located in different jobs or sessions to open the same file and share that file's record pointer.
The following bit settings are valid:
- 00
No MULTI access. A unique record pointer is created for this access to the file.
For message files, the default value of bits (5:2) is 10 for normal access, or is 00 for copy mode access.
- 01
Intrajob MULTI access only allowed. A record pointer is shared with all other opened files of the same name in the same job/session who opened the file with this option set to either 01 or 10.
- 10
Interjob MULTI access allowed. A record pointer is shared with all other opened files of the same name on the system.
(ASC) Not valid for asynchronous device files.
- 4:1
Nowait I/O option
Enables/disables nowait I/O. Determines whether or not the accessor has control returned before the completion of an I/O request. The nowait I/O implies the inhibit buffering option (aoption bit (7:1)); if NOBUF is not specified, the file system does it for you and multirecord access is not available. This option is not available if the file is located on a remote computer. When opening nonmessage files, the process must be running in privileged mode to specify this option.
The following bit settings are valid:
- 0
Nowait I/O not in effect
- 1
Nowait I/O in effect
Nowait I/O cannot be specified for directories.
- 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). Copy must be set to obtain EXCLUSIVE access. This causes the multiaccess bits to be set to 00. The following values are valid:
- 0
The file is accessed as its own file type.
- 1
The file is treated as a standard (STD) file, with variable-length records. For message files, this allows nondestructive reading of an old message file at either the logical record or physical-block-record level. Only block-level access is permitted if the file has message file format. This prevents incorrectly formatted data from being written to the message file while it is unprotected.
In order to access a message file in copy mode, a process must be able to obtain EXCLUSIVE access to the file. If opening the message file for read only, the file system tries to grant exclusive access; for write only access to the message file, the EXCLUSIVE bits (8:2) in the aoptions must be set to 01.
- 0:3
Reserved for the operating system.
- recsize
16-bit signed integer by value (optional)
Passes the size, in half words or bytes, of the logical records in the file. If recsize=0, the system uses the default record size, 256 bytes. Positive values are half words; 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..32,767 bytes.
For variable-length ASCII files and fixed-length, variable-length, and undefined-length binary files, the range is 1..32,766 bytes (1..16,383 half words). All odd values specified are rounded up to the next even value (the next half word boundary).
- device
character array (optional)
Passes a string of ASCII characters terminating with any nonalphanumeric excluding a slash (/) or period (.), designating the device where the file is to reside. This parameter optionally specifies density for tape files (;DEN= parameter) and/or environment files for certain Hewlett-Packard laser printers (;ENV= parameter), a remote environment (node#), and whether the device is to be allocated on a remote machine (;VTERM).
Remote environments (device=node#) cannot be specified for directories, byte streams, or when the formal file designator specifies an escaped pathname.
Syntax of the options available through the device parameter are:
device = [node#] [ * **vol *volclass devname devclass ]
[;DEN=density ]
[;ENV=printenv]
[;VTERM]
- node#
remote environment option
Passes a remote node name to be accessed through remote file access (RFA). The node name string must be followed by a pound character (#) to delimit the string. The internal format of the name must match that defined by the NS 3000/XL subsystem. Refer to the Using NS3000/iX Network Services.
Default: Local file access
- *
volume set option
Passing only an asterisk character (*) indicates to FOPEN that the disk file can span all volumes in the volume set bound to the group where the file resides. No set name is actually passed. This option is applicable only at file creation.
- **vol
volume name option
Passing a name, preceded by two asterisks (**), indicates that the disk file is restricted to the volume whose name is specified in vol. The specified volume must reside within the volume set bound to the group where the file resides. This option is applicable only at file creation.
- *volclass
volume class option
Passing a name, preceded by one asterisk (*), indicates that the disk file is restricted to the volume class whose name is specified in volclass. The specified volume class must reside within the volume set bound to the group where the file resides. This option is applicable only at file creation.
- devname
device name option
Passes the logical device number, in ASCII format, of a specific device. The file is assumed to be permanent. If the logical device number of a nonshareable device is specified, the nonshareable device must be ready prior to the FOPEN call.
If the device name option is used to open a file residing on a disk, specify the logical device number of the disk drive where a volume which resides within the volume set bound to the group where the file resides is mounted (applicable only at file creation). Thereafter, the disk file is associated with that volume, not with the originally specified logical device number.
- devclass
device class option
Passes a device class name or volume class name of up to eight alphanumeric characters beginning with an alpha character. For example, TAPE or DISC. If devclass is specified, the file is allocated to any available device in that class.
If the device class option is used to open a file residing on a disk, specify a device class name that corresponds to a valid and mounted volume class name; otherwise, it is assumed that the attempt is to open a device file not a disk file. Applicable only at file creation. The specified volume class must reside within the volume set bound to the group where the file resides. The file is free to span any of the volumes that fall within the specified volume class.
NOTE: If either volumeset, vol, volclass, devname, or devclass is not specified, FOPEN defaults to a disk file located on the volume class DISC bound to the group where the file resides. The file is free to span all volumes in the volume class DISC. When opening a magnetic tape that is shared for a second time, open the device with the device name option instead of device class option. This ensures that the system operator is not confused by a second tape request.- ;DEN= density
tape density option
Passes the tape density to be used while writing to a tape file. This option is applicable only when writing to a tape on a drive that supports more than one density. When reading from a tape, the density of the tape overrides the density value specified.
To specify density when writing to the tape file, use the keyword ;DEN=.
Default: The highest density available on the device opened
- ;ENV= printenv
printer environment option
Passes the name of a file that contains a printer environment. Valid only for specified printers. If opening an Hewlett-Packard 268x page printer file, an optional printing environment can be specified for the job. The printing environment is defined as all of the characteristics of the printed page that are not part of the data itself, including the page size, the margin width, the character set, the orientation (horizontal or vertical), and the name of the forms to use. If an environment file is not specified, the file system selects a default printer environment.
To specify a printer environment, assign the keyword ;ENV=, followed by the name of the environment file, to the device parameter in the form ;ENV=printenv. Any environment selected remains active until replaced by a new environment or a call FCLOSE to close the printer.
Default: No printer environment file specified
- ;VTERM
reverse VT option
Indicates that the specified device name is allocated on a remote machine. Specify the remote location of a device with the device parameter as VTERM. Specify the remote environment in the same open request, using either the formaldesig parameter or the remote environment option (see node# above) of the device parameter. Reverse VT is almost the same as a terminal opened up through remote file access, except that no session is required on the remote machine.
Default: No reverse VT
- formmsg
character array (optional)
Passes a forms message that can be used for sending messages (for example, telling the system operator what type of paper to use in the line printer) The message is a string of ASCII characters terminated by a period. The maximum number of characters allowed is 49, including the terminating period; more than 49 characters are truncated.
Used for tape label information if bit (6:1) of the foption parameter is set. The tape label information is formatted as follows:
.[volid[,type[,exp[,seq]]]];
The period is required so that the tape label information is not mistaken for a forms message.- volid
Volume identifier, consisting of <=6 printable characters. In a multivolume set, specify only the first volid.
- type
Label type, identified by three alphabetic characters:
ANS - ANSI standard labels (default)
IBM - IBM standard labels
- exp
Month/day/year of the file expiration date or the date when the file information is no longer valid. The file can be overwritten after this date. If the default is 00/00/00, the file can be overwritten immediately. In a volume set, file expiration dates must be equal to or earlier than the date on the previous file.
- seq
Use one of the following methods to specify the position of the file in relation to other files on the tape:
A zero, which causes a search of all volumes until the file is found.
An unsigned integer (1-9999), which specifies the position of the file relative to the current file on the tape.
ADDF which causes the tape to be positioned to add a new file on the end of the volume (or last volume in a multivolume set).
NEXT which positions the tape at the next file on the tape. If this is not the first FOPEN for the file and a rewind occurred on the last close, then the position remains at the beginning of the previous file.
(KSAM) Contains a description of 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 flagword field to see if the default values are acceptable; if not acceptable, specify this field explicitly.
For KSAM/3000 files, refer to the KSAM/3000 Reference Manual for a complete description of this parameter.
- userlabels
16-bit signed integer by value (optional)
Passes the number, in the range 0..254, of user-label records to be created for the file. Applicable to new disk files only.
Default: 0
(ASC) Not valid for asynchronous device files.
- blockfactor
16-bit signed integer by value (optional)
Passes the number of logical records in one physical record (block). This value is used to calculate the physical record size for disk and magnetic tape files. The valid range for this option is 1..255. If a value greater than 255 is specified, FOPEN resets the value to 255. If a value less than 1 is specified, FOPEN resets the value to the default blockfactor setting.
For fixed-length records, blockfactor specifies the actual number of records in a block. For variable-length records, blockfactor is interpreted as a multiplier used to compute the block size (recsize*blockfactor). For undefined-length records, blockfactor is always one logical record per block.
Default: For files opened BUF, the default is calculated by dividing the specified recsize into the physical record size (block size) configured for the device. For files opened NOBUF, the default is 1.
(ASC) Not valid for asynchronous device files.
- numbuffer
16-bit signed integer by value (optional)
Passes the number of buffers, number of copies, and output priority indicated by setting the following bits:
- Bits
Value/Meaning
- 11:5
Numbuffers
Indicates the number of buffers to allocate to the file. The valid range is dependent on file type:
For standard files, the valid range is 1..31.
For circular and RIO files, the valid range is 1..16.
For message files, the valid range is 2..16 (if a 1 is specified, the file system sets this option to 2 and no error is returned).
For KSAM/3000 files, the valid range is 1..20.
Not used for KSAM XL and KSAM64 files.
This option must not specify a number of buffers whose combined size exceeds the physical capacity of the file.
Default: 00010 (decimal 2)
- 4:7
Spooler copies
Indicates the number of copies of the file to be produced by the spooling facility. The valid range is 0...127. This option is applicable to spooled devices only. Specify this option for a file already opened (for example, $STDLIST), this is the highest value supplied before the last FCLOSE takes effect. The copies do not appear continuously if the system operator intervenes or if a file of higher output priority is ready before the last copy is complete.
Default: 0000001 (decimal 1)
- 0:4
Output priority
Indicate the output priority to be attached to the file for spooled output. Applicable only to spooled devices. The valid range for this option is the binary equivalent of 1..13. The output priority must be a number between 1 (lowest priority) and 13 (highest priority), inclusive. If a value less than the current outfence set by the system operator is specified, file printing is deferred until the operator raises the output priority of the file or lowers the outfence. Specify this option for a file already opened (for example, $STDLIST), the highest value supplied before the last FCLOSE takes effect.
Default: 1000 (decimal 8)
- filesize
32-bit signed integer by value (optional)
Passes the maximum file capacity. For variable-length records, the capacity is expressed in blocks (block = recordsize * blockfactor). For fixed-length and undefined-length records, the capacity is expressed in logical records:
The maximum file size for ordinary, fixed length record files and KSAM64 files is 128GB (137,438,953,472 bytes)
The maximum file size for ordinary, byte stream record files is 2GB (2,147,483,648 bytes)
The maximum file size for other standard and KSAM XL files is 4,294,901,759 bytes (4 gigabytes less 64K bytes).
The maximum file size for RIO, circular, and message files is dependent upon both the record size and number of extents defined for the file:
For circular and RIO files, a maximum file size of 500 megabytes is possible if recsize=256 bytes and numextent=32.
For message files, a maximum file size of 500 megabytes is possible if recsize=128 bytes and numextent=32.
Default: 1023 records
(ASC) Not valid for asynchronous device files.
- numextent
16-bit signed integer by value (optional)
Passes a value in the range 1..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) is allocated on a need basis. Applicable only at file creation.
Default: >8 extents
(ASC) Not valid for asynchronous device files.
- initialloc
16-bit signed integer by value (optional)
Passes an integer value in the range 1..32 that determines the number of extents to be allocated to the file initially. Applicable only at file creation.
Default: 1
(ASC) Not valid for asynchronous device files.
- 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..32,767 to indicate the file type being created; programs running in user mode can access files with non-negative file codes. If the program is running in privileged mode, specify a file code in the range -32,768..32,767; programs running in privileged mode can access files with a file code in the range -32,768..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.
Negative file codes are only allowed for files in MPE groups.
Default: 0
(ASC) Not valid for asynchronous device files.
| FOPEN Parameter | HPFOPEN Itemnum,Item |
|---|---|
| filenum (functional return) | filenum (parameter) |
| formaldesig | 2,formaldesig |
foption:Bits (14:2) Domain Bit (13:1) ASCII/binary Bits (10:3) File designator Bits (8:2) Record format Bit (7:1) Carriage-control Bit (6:1) Labeled tape Bit (5:1) Disallow file equation Bits (2:3) File type |
3, domain 53, ASCII/binary 5, file designator 6, record format 7, carriage-control 8, labeled tape 9, disallow file equation 10, file type |
aoption:Bits (12:4) Access type Bit (11:1) Multirecord Bit (10:1) Dynamic locking Bits (8:2) Exclusive Bit (7:1) Inhibit buffering Bits (5:2) Multiaccess mode Bit (4:1) Nowait I/O Bit (3:1) File copy |
11, access type 15, multirecord 12, dynamic locking 13, exclusive 46, inhibit buffering 14, multiaccess mode 16, nowait I/O 17, file copy |
| recsize | 19, record size |
| device |
20, device name 22, volume class 23, volume name 24, density 25, printer environment 26, remote environment 42, device class 48, reverse VT |
| formmsg |
8, labeled tape label 28, spooled message 30, labeled tape type 31, labeled tape expiration 32, labeled tape sequence 54, KSAM parms |
| userlabels | 33, user labels |
| blockfactor | 40, block factor |
numbuffers:Bits (11:5) Numbuffers Bits (4:7) Spooler copies Bits (0:4) Output priority |
44, numbuffers 34, spooler copies 27, output priority |
| filesize | 35, filesize |
| numextent | 47, numextent |
| initialloc | 36, initial allocation |
| filecode | 37, filecode |
Operation Notes
A file can be referenced by its formal file designator. When executed, a unique file number is returned to the process. This file number can be used, rather than the formal file designator, in other calls to this file.
|
NOTE: If a file is opened with read access only (bits 12:4 = 0000) a subsequent call to FOPEN to write and set eof to 0 (bits 12:4 = 0001) succeeds but only after the system changes the call to write but not set eof to 0 (bits 12:4 =0010). This protects the reader, who opened the file first, from having the eof set to 0. |
Condition Codes
- CCE (2)
Request granted. The file is open.
- CCG (0)
Not returned.
- CCL (1)
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.
Related Information
- Intrinsics
HPFOPEN
- Manuals
Accessing Files Programmer's Guide
Using KSAM XL
KSAM/3000 Reference Manual
|
FMTDATE |
FPARSE |