HP 3000 Manuals HP 3000 Manuals
FOPEN (contd)
=||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 (32650-90017) 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:
[* ]
[**vol ]
device=[node#][*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 NS
3000/XL User/Programmer Reference Manual
(36920-90001).
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= tape density option
density
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= printer environment option
printenv
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 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.
blockfactor16-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 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)
Table 4-8. (cont.)
Bits Value/Meaning
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 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 4-9. 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 | 3, domain |
| Bit (7:1) Carriage-control | |
| Bit (6:1) Labeled tape | 53, ASCII/binary |
| Bit (5:1) Disallow file equation | |
| Bits (2:3) File type | 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 | 11, access type |
| Bit (7:1) Inhibit buffering | |
| Bits (5:2) Multiaccess mode | 15, multirecord |
| Bit (4:1) Nowait I/O | |
| Bit (3:1) File copy | 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 |
| | |
---------------------------------------------------------------------------------------------
Table 4-9. FOPEN/HPFOPEN Parameter Equivalents (cont.)
---------------------------------------------------------------------------------------------
| | |
| FOPEN Parameter | HPFOPEN Itemnum,Item |
| | |
---------------------------------------------------------------------------------------------
| | |
| 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
Commands None
Manuals Accessing Files Programmer's Guide (32650-90017),
Using KSAM XL (32650-90168), and KSAM/3000
Reference Manual (30000-90079)