HP 3000 Manuals HP 3000 Manuals
The HPFOPEN Intrinsic
The HPFOPEN intrinsic establishes access to a disk or device file and
enables you to create a file on a shareable device. HPFOPEN is used to
define a file's physical characteristics, including file and record
structure. Its syntax is
HPFOPEN (filenum, status, [, itemnum, item]...);
The HPFOPEN optional parameters are a superset of the options provided in
the FOPEN intrinsic and provide more efficient access to files.
[REV BEG]
NOWAIT I/O
Sometimes a programmer wants an application to read or write a record,
but does not want it to wait for I/O to complete. For such an
application, waiting is wasting time when it could be doing other
processing. Timeouts do not adequately address this problem. The
programmer wants this application to start an I/O, continue processing
immediately, and check periodically to see if the I/O has finished
MPE/iX provides a way to solve this problem with NOWAIT I/O. This feature
is requested by enabling the NOWAIT I/O option (item #16) in HPFOPEN.
When using NOWAIT I/O, the process must make at least two intrinsic calls
to perform the I/O, one to start it and one to finish it. MPE/iX still
handles the file in the same way; but instead of waiting for the I/O to
complete, MPE/iX returns control to the application so that the
application can do some useful processing.
NOWAIT I/O has been available to users of standard files for a long time,
but to use it on standard files requires privileged mode. On standard
files the mechanics of NOWAIT I/O prevent MPE/iX from protecting a
process from corrupting its own stack; however, because message files
work differently, NOWAIT I/O on message files does not require privileged
mode.
NOWAIT I/O intrinsics
To perform a NOWAIT I/O, the FREAD or FWRITE intrinsic must be called to
initiate the transfer. These intrinsics return immediately, and no data
is transferred yet. The return value for FREAD is set to zero and is not
needed.
To complete the transfer, either IODONTWAIT or IOWAIT must be called.
IODONTWAIT tests whether the I/O has finished. If it has, the intrinsic
returns a condition code of CCE and the file number as the return value.
If the I/O has not completed, CCE and a zero return value are passed
back. If IOWAIT is called, it waits until the I/O has finished, like a
normal WAIT I/O FREAD or FWRITE.
Only one NOWAIT I/O can be outstanding against a file by a particular
accessor at a time; however, an accessor can have NOWAIT I/Os outstanding
against several files at the same time. These I/Os can be completed by a
"generalized" IODONTWAIT or IOWAIT: the file number parameter is zero or
is omitted. In this case, these intrinsics report on the first I/O to
complete, returning the file number for that file. If the call to one of
these intrinsics is in a loop, then that one call can be used to complete
all the NOWAIT I/Os.
Aborting NOWAIT I/O
Occasionally, after a process has started a NOWAIT I/O with FREAD or
FWRITE, something occurs that causes completion of that I/O to be no
longer needed. Perhaps the process is "shutting down" and does not want
to wait for the I/O (that is, to issue IOWAIT or IODONTWAIT).
MPE/iX lets the process abort NOWAIT I/Os that have not yet completed by
using FCONTROL with a control code of 43. A condition code of CCE is
returned if the I/O was aborted; in this case, nothing more needs to be
done. CCG is returned if the I/O has already completed; in this case,
IODONTWAIT or IOWAIT must be called to clear it. CCL and FSERR 79, No
NOWAIT I/O pending for special file are returned if there was nothing to
abort.
Limitations
Currently, MPE/iX does not support NOWAIT I/O to message files across a
network. In most cases, this is not an important limitation, because it
is rare that both readers and writers to the same message file need to
use NOWAIT I/O. If the file is made local to the accessor that needs
NOWAIT I/O, the other accessor can then do WAIT I/O across the network.
More information on these intrinsics is found in the MPE/iX Intrinsics
Reference Manual (32650-90028). For detailed information about WAIT and
NOWAIT, consult the Interprocess Communications Programmers' Guide
(32650-90019).[REV END]
The following table lists the optional parameters you can use to specify
a file's physical characteristics, as well as the default values for
each.
Table 2-1. HPFOPEN Itemnum/Item Values
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 0 | | End of option list: |
| | | |
| | | There is no corresponding item. The absence of an |
| | | itemnum after the last itemnum,item pair is equivalent to |
| | | specifying this option. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 2 | CA | Formal designator: |
| | | |
| | | Passes a formal file designator, following MPE/iX file |
| | | naming conventions. The file name must begin with an |
| | | alphabetic character and contain alphanumeric characters, |
| | | slashes, or periods. |
| | | |
| | | (ASC) It is recommended that this itemnum,item pair be |
| | | used for asynchronous devices. |
| | | |
| | | Default: A nameless file that can be read from or |
| | | written to, but not saved, is assigned. (The domain of a |
| | | nameless file must be new.) |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 3 | I32 | Domain: |
| | | |
| | | Passes a value indicating which file domain MPE/iX |
| | | searches to locate the 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. |
| | | |
| | | Default: 0 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 5 | I32 | Designator: |
| | | |
| | | Passes a value indicating a special file opening. Any of |
| | | the following special files can be specified with the |
| | | itemnum=2. For example, a file name of $STDLIST opens |
| | | the standard list device. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Select $STDLIST, $STDIN, or $STDINX for terminals, |
| | | and $STDLIST for printers. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 6 | I32 | Record format: |
| | | |
| | | Passes a value indicating the internal record structure |
| | | desired for the file. This option is applicable only at |
| | | file creation. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) This itemnum,item pair is ignored for files opened |
| | | on a terminal; records of files on terminals are of |
| | | undefined length. If the file is to be redirected to |
| | | tape or disk, set the value to 0 (fixed-length). |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 7 | I32 | Carriage-control: |
| | | |
| | | Passes a value indicating 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. |
| | | |
| | | Carriage-control is defined only for ASCII files. This |
| | | option and itemnum=53 are exclusive, and attempts to open |
| | | new files with both binary and carriage-control |
| | | directives result in an access violation. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 8 | CA | Enable tape label: |
| | | |
| | | Passes the tape label name of a labeled tape. The name |
| | | must follow the ANSI standards for tape label names. The |
| | | name consists of <=6 printable characters that identify |
| | | the volume. In a multivolume set, only the first tape |
| | | label can be specified. |
| | | |
| | | Default: a null tape label |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 9 | I32 | Disallow file equation: |
| | | |
| | | Passes a value indicating whether or not MPE/iX file |
| | | equations are allowed. A leading * in a formal file |
| | | designator overrides the setting to disallow FILE. |
| | | |
| | | Default: 0 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 10 | I32 | File type: |
| | | |
| | | Passes a value indicating the internal record structure |
| | | used to access records in the file. If the file is old, |
| | | this option is ignored. Specifying an itemnum=5 value |
| | | other than zero overrides this option. This option is |
| | | applicable only at file creation. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 12 | I32 | Dynamic locking: |
| | | |
| | | Passes a value enabling/disabling file locking for the |
| | | file. When specified, the FLOCK and FUNLOCK intrinsics |
| | | can be used to dynamically permit/restrict concurrent |
| | | access to a disk file by other processes at specified |
| | | times. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 13 | I32 | Exclusive: |
| | | |
| | | Passes a value indicating continuous exclusive access to |
| | | the file, from open to close. Use this option when |
| | | performing a critical operation (for example, updating |
| | | the file). |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) This option is not used for printers. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 14 | I32 | Multiaccess: |
| | | |
| | | Passes a value indicating 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. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 15 | I32 | Multirecord: |
| | | |
| | | Passes a value indicating that individual read or write |
| | | requests are not confined to record boundaries. |
| | | |
| | | (ASC) This option is not used for printers. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 16 | I32 | NOWAIT I/O: |
| | | |
| | | Allows the accessor to initiate an I/O request and to |
| | | have control returned before the completion of the I/O. |
| | | This option implies the inhibit buffering option; if |
| | | NOBUF is not specified, the file system does it. |
| | | 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 PM (execution level 2) to specify this option. |
| | | Set itemnum=24 to 3 if the file is to be accessed while |
| | | in user mode (execution level 3). |
| | | |
| | | Default: 0 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 17 | I32 | Copy mode: |
| | | |
| | | Passes a value that determines if any file should be |
| | | treated as a standard sequential file so that it can be |
| | | copied by logical record or physical block to another |
| | | file. |
| | | |
| | | (KSAM) Not allowed for KSAM XL files. |
| | | |
| | | Default: 0 |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 18 | @32 | Short-mapped: |
| | | |
| | | Returns a short pointer to the beginning of the data area |
| | | of the file. This option maps the file into short |
| | | pointer space. A short-mapped file can be 4 megabytes in |
| | | length. The calling process can have up to 6 megabytes |
| | | of short-mapped files open at a time. Use the pointer as |
| | | a large array of any type to efficiently access the file. |
| | | |
| | | |
| | | Default: No short pointer returned |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 19 | I32 | Record size: |
| | | |
| | | Passes the size, in bytes, of the logical records in the |
| | | file. Valid range is dependent upon both storage format |
| | | (ASCII or binary) and record format. For fixed-length |
| | | and undefined-length ASCII files, a record size can be |
| | | specified in the range 1..32,767. For variable-length |
| | | ASCII files, and for fixed-length, variable-length, and |
| | | undefined-length binary files, a record size can be |
| | | specified in the range 1..32,766. |
| | | |
| | | HPFOPEN rounds up odd values to the next-highest even |
| | | number (equivalent to the nearest half-word boundary) if |
| | | the file is ASCII with variable-length record format, or |
| | | binary with fixed-length, variable-length, or |
| | | undefined-length record format. |
| | | |
| | | Default: 256 |
| | | |
| | | (ASC) For terminal and printer files, no rounding up |
| | | occurs if a record size consisting of an odd number of |
| | | bytes is specified. The record size can be different |
| | | from the port configuration. The default is the |
| | | configured record size (normally 40 words for terminals, |
| | | 66 words for printers). |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 20 | CA | Device name: |
| | | |
| | | Passes the logical device number, in ASCII form, of a |
| | | specific device. The file is assumed to be permanent. |
| | | If the device name option is specified, the nonshareable |
| | | device should be ready prior to the HPFOPEN call |
| | | (otherwise, an error results). |
| | | |
| | | Only one of the following options can be in effect when a |
| | | file is opened: |
| | | itemnum=20 |
| | | itemnum=22 |
| | | itemnum=23 |
| | | itemnum=42 |
| | | |
| | | Default: Disk file located on the volume class DISC |
| | | associated with the group in which file resides. |
| | | |
| | | Default: Not returned |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 22 | CA | Volume class: |
| | | |
| | | Passes a character array representing a volume class name |
| | | where the file space is to be restricted. This option is |
| | | applicable only at file creation. |
| | | |
| | | A volume class is a subset of volumes within a volume |
| | | set. The volume class name must be a valid volume class |
| | | name residing on the volume set bound to the volume (the |
| | | volume set is an attribute of the group in which the file |
| | | resides). |
| | | |
| | | Only one of the following options can be in effect when a |
| | | file is opened with this option: |
| | | |
| | | itemnum=20 |
| | | itemnum=22 |
| | | itemnum=23 |
| | | itemnum=42 |
| | | |
| | | Default: A disk file located on the volume class DISC |
| | | associated with the group in which file resides. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 23 | CA | Volume name: |
| | | |
| | | Passes a character array representing a volume name that |
| | | restricts the file specified to a specific volume. The |
| | | volume must reside within the volume set of the group |
| | | where the file resides. This option is applicable only |
| | | at file creation. |
| | | |
| | | Only one of the following options can be in effect when a |
| | | file is opened with this option: |
| | | |
| | | itemnum=20 |
| | | itemnum=22 |
| | | itemnum=23 |
| | | itemnum=42 |
| | | |
| | | Default: A disk file located on the volume class DISC |
| | | associated with the group in which the file resides. ( |
| | | ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 24 | I32 | Density: |
| | | |
| | | Passes the tape density required when 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 this option |
| | | |
| | | Default: The highest density available on the device |
| | | opened. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 25 | CA | Printer environment: |
| | | |
| | | Passes the name of a file that contains a printer |
| | | environment. This option is valid only for specified |
| | | printer devices. |
| | | |
| | | If opening an Hewlett-Packard 268x page printer file, |
| | | specify an optional printing environment for the job. |
| | | Any environment selected remains active until replaced by |
| | | a new environment, or until a call to FCLOSE (close the |
| | | printer). |
| | | |
| | | Default: No printer environment file specified |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 26 | CA | Remote environment: |
| | | |
| | | Passes the node name of the remote computer where the |
| | | file is located. This option is used when referencing a |
| | | file located on a remote computer. |
| | | |
| | | Default: No node name passed (local file access). |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 27 | I32 | Output priority: |
| | | |
| | | Passes the output priority to be attached to the file for |
| | | spooled output. This option is applicable only to |
| | | spooled devices. The output priority must be a number |
| | | between 1 (lowest priority) and 13 (highest priority), |
| | | inclusive. If the value specified is less than the |
| | | current outfence set by the system operator, file |
| | | printing is deferred until the operator raises the output |
| | | priority of the file or lowers the outfence. This option |
| | | can be specified for a file already opened (for example, |
| | | $STDLIST), where the highest value supplied before the |
| | | last FCLOSE takes effect. This option is ignored for |
| | | nonspooled devices. |
| | | |
| | | Default: 8 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 28 | CA | Spooled message: |
| | | |
| | | Passes a spooler message associated with a spool file. |
| | | For example, a message is passed that can be used for |
| | | telling the system operator what type of paper to use in |
| | | the line printer. This message must be displayed to the |
| | | system operator and verified before the file can be |
| | | printed on a line printer. The number of characters |
| | | allowed <=48; any quantity > 48 characters is truncated. |
| | | |
| | | |
| | | Default: No spooled message specified. |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array, for example: |
| | | %message% (% is the delimiter, message is the |
| | | designator) |
| | | fabcxyzf (f is the delimiter, abcxyz is the |
| | | designator) |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 29 | I32 | Privileged access: |
| | | |
| | | Passes a value that temporarily restricts access to the |
| | | file number returned from HPFOPEN to a calling process |
| | | whose execution level is equal to or less than the value |
| | | specified in this option. This restriction lasts until |
| | | the file associated with the restricted file number is |
| | | closed. Do not specify a value less than the execution |
| | | level of the calling process. |
| | | |
| | | Default: The execution level of the calling process |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 30 | I32 | Labeled tape type: |
| | | |
| | | Passes a value that indicates tape label type |
| | | information. This option is valid only for labeled |
| | | tapes. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 31 | CA | Labeled tape expiration: |
| | | |
| | | Passes the date of the expiration of the file or the date |
| | | after which the information in the file is no longer |
| | | useful, in the format mm/dd/yy. The file can be |
| | | overwritten after this date. If the default is |
| | | specified, the file can be overwritten immediately. In a |
| | | volume set, file expiration dates must always be equal to |
| | | or earlier than the date on the previous file. |
| | | |
| | | Default: No expiration date specified. |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array, for example, |
| | | %expdate% (% is the delimiter, expdate is the |
| | | designator) |
| | | fabcxyzf (f is the delimiter, abcxyz is the |
| | | designator) |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 32 | CA | Labeled tape sequence: |
| | | |
| | | Passes one of the following character arrays indicating |
| | | the position of the file in relation to other files on |
| | | the tape: |
| | | |
| | | |
| | | 0 Causes a search of all volumes until the file is |
| | | found. |
| | | |
| | | 1.. 9999ecifies the position of the file relative to the |
| | | current file on the tape. |
| | | |
| | | |
| | | |
| | | ADDF Causes the tape to be positioned so as to add a new |
| | | file at the end of the volume or last volume in a |
| | | multivolume set. |
| | | |
| | | NEXT Positions the tape at the next file on the tape. |
| | | If this is not the first HPFOPEN/FOPEN for the file |
| | | and a rewind occurred on the last close, then the |
| | | position remains at the beginning of the previous |
| | | file. |
| | | |
| | | Default: No array passed (no sequence indicated) |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array, for example, |
| | | %position% (% is the delimiter, position is the |
| | | designator) |
| | | fabcxyzf (f is the delimiter, abcxyz is the |
| | | designator) |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 33 | I32 | User labels: |
| | | |
| | | Passes the number, in the range 0..254, of user-label |
| | | records to be created for the file. Applicable for new |
| | | disk files only. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 34 | I32 | Spooler copies: |
| | | |
| | | Passes a value in the range 1..127 indicating the number |
| | | of copies of the entire file to be produced by the |
| | | spooling facility. This option is applicable to spooled |
| | | devices only. This option can be specified for a file |
| | | already opened (for example, $STDLIST), where 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 becomes |
| | | READY before the last copy is complete. This option is |
| | | ignored for nonspooled output devices. |
| | | |
| | | Default: 1 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 35 | I32 | File size: |
| | | |
| | | Passes the maximum file capacity: |
| | | |
| | | * For variable-length records, the capacity is |
| | | expressed in blocks (blockitem#=recordsize * |
| | | blockfactor). |
| | | * For fixed-length and undefined-length records, the |
| | | capacity is expressed in logical records. |
| | | * The maximum file size for standard and KSAM files |
| | | is 4 gigabytes. |
| | | * The maximum file size of 500 megabytes for RIO, |
| | | circular, and message files is dependent upon both |
| | | the record size and the number of extents defined |
| | | for the file: |
| | | * For circular and RIO files, recsize=256 |
| | | bytes and numextent=32. |
| | | * For message files, recsize=128 bytes and |
| | | numextent=32. |
| | | |
| | | This option is applicable only at file creation. |
| | | |
| | | Default: 4 gigabytes |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 36 | I32 | Initial allocation: |
| | | |
| | | Passes a positive integer value indicating the number of |
| | | records to be allocated to the file initially. This |
| | | option is applicable only at file creation. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 37 | I32 | File code: |
| | | |
| | | 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. This option is 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 positive file codes only. |
| | | |
| | | 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 is opened that |
| | | has a negative file code in its file label, the file code |
| | | specified must match the file code in the file label |
| | | (otherwise, an error results). |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 38 | I32 | File privilege: |
| | | |
| | | Passes a value that determines a permanent privilege |
| | | level to be associated with a newly created file. This |
| | | option permanently restricts file access to a process |
| | | whose execution level is less than or equal to the |
| | | specified value. A value cannot be specified for less |
| | | than the execution level of the calling process. This |
| | | option is applicable only at file creation. |
| | | |
| | | Default: 3 |
| | | |
| | | A file created with levels 0, 1, or 2 can be opened only |
| | | with the HPFOPEN intrinsic; the FOPEN intrinsic cannot be |
| | | used. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 39 | I32 | Access type: |
| | | |
| | | Passes a value indicating how to use the file, either |
| | | sequentially or randomly. The file system uses this |
| | | information to determine the most efficient prefetching |
| | | algorithm to improve the performance of the file access. |
| | | |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 40 | I32 | Block factor: |
| | | |
| | | Passes the number of logical records to be contained in |
| | | one physical record (block). This value is used to |
| | | calculate the physical record size (block size) for disk |
| | | and magnetic tape files. Valid ranges are 1..32,767. |
| | | This option is applicable only at file creation. |
| | | |
| | | Default: 1 for files opened NOBUF; for files opened BUF, |
| | | it is calculated by dividing the specified records into |
| | | the block size configured for the device. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 41 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 42 | CA | Device class: |
| | | |
| | | Passes a device class where the file resides. The file |
| | | system uses the device class name to select a |
| | | nonshareable device from a configured list of available |
| | | devices. The name can have a length of up to eight |
| | | alphanumeric characters, beginning with a letter (for |
| | | example, TAPE). If a device class is specified, the file |
| | | is allocated to any available device in that class. |
| | | |
| | | Only one of the following options can be in effect when a |
| | | file is opened: |
| | | itemnum=20 |
| | | itemnum=22 |
| | | itemnum=23 |
| | | itemnum=42 |
| | | |
| | | Default: A disk file located on the volume class DISC |
| | | associated with the group in which file resides. |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array, for example: |
| | | %devclass% (% is the delimiter, devclass is the |
| | | designator) |
| | | fabcxyzf (f is the delimiter, abcxyz is the |
| | | designator) |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 43 | record | UFID: |
| | | |
| | | Passes a unique file identifier (UFID) to provide a fast |
| | | opening of an old disk file. A UFID is a record |
| | | structure, 20 bytes in length, that uniquely identifies a |
| | | disk file. Using this option avoids a directory search. |
| | | Obtain the UFID of an opened file by calling FFILEINFO. |
| | | The UFID can then be passed to HPFOPEN. The file |
| | | represented by the UFID must be accessible to the process |
| | | calling HPFOPEN. (All file system security checks are |
| | | made.) New files cannot be opened with this option. If |
| | | the file to be opened by the UFID contains a lockword, |
| | | use itemnum=2 to specify the file name with the lockword. |
| | | |
| | | |
| | | Default: No UFID passed (a directory search is |
| | | performed). |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 44 | I32 | Numbuffers: |
| | | |
| | | Passes the number of buffers to allocate to the file. |
| | | Ignored for standard disk files. This option is useful |
| | | only for slow devices (such as tapes) used in a buffered |
| | | mode. Not applicable for files representing interactive |
| | | terminals; a system-managed buffering method is always |
| | | used. |
| | | |
| | | This option must not specify a number of buffers whose |
| | | combined size exceeds the physical capacity of the file. |
| | | |
| | | |
| | | Default: 2 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 45 | CA | Fill character: |
| | | |
| | | Passes two ASCII characters that determine what padding |
| | | character to use at the end of blocks or unused pages, |
| | | and the padding used by itemnum=53. Do not use delimiter |
| | | characters for this option. The fill character must be a |
| | | 2 byte array. The first character only is used as the |
| | | padding character. The second character is reserved for |
| | | future use. This option is applicable only at file |
| | | creation. |
| | | |
| | | Default: Null characters and ASCII blanks. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 46 | I32 | Inhibit buffering: |
| | | |
| | | Passes a value enabling/disabling automatic buffering by |
| | | MPE/iX. If NOBUF is specified, I/O is allowed to take |
| | | place directly between the data area and the applicable |
| | | hardware device. |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 47 | I32 | Numextents: |
| | | |
| | | Passes a value in the range 1..32 that determines the |
| | | number of extents for the file. If a value of 1 is |
| | | specified, the file is created as one contiguous extent |
| | | of disk space. If a value greater than 1 is specified, a |
| | | variable number of extents (with varying extent sizes) is |
| | | allocated on a need basis. This option is applicable |
| | | only at file creation. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
| | | Default: 1 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 48 | I32 | Reverse VT: |
| | | |
| | | Passes a value indicating whether or not the given device |
| | | name is to be allocated on a remote machine. Specify the |
| | | remote environment in the same open request, using either |
| | | the formal designator option or the remote environment |
| | | option. Reverse VT behaves nearly the same as a terminal |
| | | opened through remote file access, except that no session |
| | | is required on the remote machine. |
| | | |
| | | Default: 0 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 49 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 50 | I32 | Final disposition: |
| | | |
| | | Passes a value indicating the final disposition of the |
| | | file at close time (significant only for files on disk |
| | | and magnetic tape). A corresponding parameter in a FILE |
| | | command can override this option, unless file equations |
| | | are disallowed with itemnum=9. |
| | | |
| | | Default: 0 |
| | | |
| | | For more information on file disposition at close time, |
| | | refer to the description of the FCLOSE intrinsic. |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 51 | | Pascal/iX string: |
| | | |
| | | Passes a formal file designator, following MPE/XL file |
| | | naming conventions, but using the Pascal/iX STRING type |
| | | format. This option is identical to itemnum=2 except for |
| | | the type of item. No delimiters are needed. |
| | | |
| | | Default: No string passed. |
| | | |
| | | Only one of the following options can be in effect when a |
| | | file is opened: |
| | | itemnum=2 |
| | | itemnum=51 |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 52 | CA | File equation string: |
| | | |
| | | Passes a character string that matches the MPE/XL file |
| | | equation specification syntax exactly. (Refer to the |
| | | FILE command in the MPE/iX Commands Reference Manual |
| | | Volumes 1 and 2 (32650-90003 and 32650-90364).) This |
| | | option allows the specification of options available in |
| | | the FILE command. |
| | | |
| | | Default: No string passed. |
| | | |
| | | A character placed in the first element designates the |
| | | delimiter used by HPFOPEN to search for the end of the |
| | | character array. The delimiter can appear again only |
| | | following the last valid character of the character |
| | | array, for example: |
| | | %fileequation% (% is the delimiter, fileequation |
| | | is the designator) |
| | | fabcxyzf (f is the delimiter, abcxyz is the |
| | | designator) |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 53 | I32 | ASCII/binary: |
| | | |
| | | Passes a value indicating whether ASCII or binary code is |
| | | to be used for a new file when it is written to a device |
| | | that supports both codes. For disk files, this affects |
| | | padding that can occur when issuing 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 values are valid: |
| | | |
| | | |
| | | 0 Binary file |
| | | |
| | | 1 ASCII file |
| | | |
| | | Default: 0 |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 54 | REC | KSAM parm: |
| | | |
| | | Passes a record that defines the keys for a new KSAM |
| | | file. |
| | | |
| | | (KSAM XL) For KSAM XL files, refer to the parm parameter |
| | | discussion in the Using KSAM XL (32650-90168). |
| | | |
| | | (KSAM/3000) The record must be at least 34 bytes in size. |
| | | For details, refer to the ksamparam parameter discussion |
| | | in the KSAM/3000 Reference Manual (30000-90079). |
| | | |
| | | Default: No record passed |
| | | |
| | | (ASC) Not used for asynchronous devices. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 55 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 56 | I32 | Object class: |
| | | |
| | | Passes a user object class number, in the range 0..10, |
| | | that is associated with the file. |
| | | |
| | | Default: Determined by the file code for system and |
| | | subsystem files, and by the file type and record type for |
| | | normal user files. |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 57 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 58 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 59 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 60 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 61 | | Reserved for MPE/iX |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 64 | BA | ACD: |
| | | |
| | | Passes a byte array defining the access control |
| | | definition (ACD) to be attached to a new file. The byte |
| | | array has a length of 1 to 279 bytes. Unlike other |
| | | HPFOPEN options that expect a delimiter at both the |
| | | beginning and the end of the byte array, this option only |
| | | expects a trailing carriage-return character as a |
| | | delimiter, for example, |
| | | (X:@.@;R,W:MGR.SYS;RACD:JOHN.SMITH)<cr> |
| | | |
| | | Where, the <cr> is the carriage-return character (13, |
| | | 0x0D). |
| | | |
---------------------------------------------------------------------------------------
Table 2-1. HPFOPEN Itemnum/Item Values (cont.)
---------------------------------------------------------------------------------------
| | | |
| Itemnum | Mnemonic | Item Description |
| | | |
---------------------------------------------------------------------------------------
| | | |
| 74 | | Header/Trailer: |
| | | |
| | | Enable/disable standard headers/trailers: |
| | | |
| | | |
| | | 0 Enable header and trailer (default) |
| | | |
| | | 1 Disable header |
| | | |
| | | 2 Disable trailer |
| | | |
| | | 3 Disable header and trailer |
| | | |
| | | Provides a standard way for the spooler to control the |
| | | printing banners. |
| | | |
| | | Valid only for the initial HPFOPEN call to the printer |
| | | and prevents the header from being printed. On the last |
| | | FCLOSE, the trailer is not printed. |
| | | |
---------------------------------------------------------------------------------------
Optional parameters you can use to specify file access and device control
characteristics are described elsewhere in this manual. For more details
on the HPFOPEN intrinsic, refer to the MPE/iX Intrinsics Reference Manual
(32650-90028).