 |
» |
|
|
|
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:
- aoption
16-bit unsigned integer by value (optional) Specifies up to eight different file access options by setting
corresponding bit groupings:
- 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: 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 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.
- ;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 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:
- 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
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 - Commands
None - Manuals
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL (32650-90168), and KSAM/3000 Reference Manual (30000-90079)
|
Printable version
