 |
» |
|
|
|
NM and CM callable. Establishes access to a file and defines the physical characteristics
of the file prior to access. Syntax | |
I16 CA U16V U16V I16V CA
filenum:=FOPEN(formaldesig,foption,aoption,recsize,device,
CA I16V I16V I16V
formmsg,userlabels,blockfactor,numbuffer
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 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
If formaldesig is the name of a user-defined file, it can begin
with an asterisk (*). If formaldesig is the name of a system-defined file, it can begin
with a dollar sign ($). When creating a KSAM file, formaldesig must be a unique file name, that is, one not currently
existing in the permanent file directory. 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:
- 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
- Bits
Value/Meaning - 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: (ASC) Not valid for asynchronous device files. Default: 0
- Bits
Value/Meaning - 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.
Default: 000 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.
A leading * in a formal file designator passed by the formaldesig parameter overrides the disallow file equation option
setting.
- Bits
Value/Meaning - 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.
Default: 00
- 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.
Default: 0 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 information
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
(ASC) Not valid for asynchronous device files, but may be
set if file direction is anticipated. 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.
Default: 0
- 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
Default: 000
- 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)
Default: 0 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
Default: 0 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.
Default: 00
- 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)
Default: 0 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
If writing to a message file, open it NOBUF; if the copy mode option is enabled, access the
file block-by-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.
Default: 0 (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
Default: 0 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.
Default: 0
- 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).
Default: Device dependent; refer to the Accessing
Files Programmer's Guide for default record sizes. - 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 ] - 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.
- ;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.
Default: NEXT (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 XL and KSAM64 files, refer to the Using
KSAM XL (32650-90168) for a complete description of
this parameter. For KSAM/3000 files, refer to the KSAM/3000 Reference Manual (30000-90079)
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 is ignored for standard disk files, useful only
for slow devices (such as tapes) used in a buffered mode, and is
not applicable for files representing interactive terminals. 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.
Applicable only at file creation. 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 file in MPE groups. Default: 0 (ASC) Not valid for asynchronous device files.
Table 6-1 FOPEN/HPFOPEN Parameter Equivalents | 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 |
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, and KSAM/3000 Reference
Manual
|
Printable version
