FGETINFO

Returns access and status information about a file.

Syntax

I6V CA U16 U16

FGETINFO(filenum,formaldesignator,foptions,aoptions,

I16 I16 U16 U16

,devtype,ldevnum,hdaddr,

I16 I32 I32 132 I32

filecode,lrecptr,EOF,filelimit,logcount,

I32 I16 U16 I16

physcount,blksize,extsize,numextents,

I16 CA I32

userlabels,creatorid,labaddr);

Use

The FGETINFO intrinsic returns access and status information about a file located on any device. The file must be opened by the calling process at the time of the FGETINFO call. When using this intrinsic you need only specify those parameters that return the information options you want. The default in all cases is that information that is not explicitly requested is not returned.

Only those parameters that return information that applies to asynchronous devices are described below. For an explanation of all the parameters, you should see the MPE/iX Intrinsics Reference Manual.

Parameters

filenum

16-bit signed integer by value (required)

The file number of the file about which information is required.

formaldesignator

character array (optional)

Returns the actual designator of the file being referenced in the following format:

filename.groupname.accountname

The formaldesignator array must be at least 28 bytes in length. When the actual designator is returned, unused bytes in the array are filled with blanks on the right. A nameless file returns an empty string. Note that all character arrays must start on a halfword boundary.

The fully qualified name of the file referenced by filenum is returned as the value of this parameter. Only names which can be expressed using MPE only semantics are returned. If the name of the object referenced by filenum cannot be expressed using MPE name semantics, a CCL condition code is returned. Calling FCHECK after this error will result in an error.

foptions

16-bit unsigned integer by reference (optional)

Returns information about the foption characteristics that are set through the FOPEN or HPFOPEN call. The bit settings that designate each of these characteristics are listed below. Note that not all of the foptions are meaningful for files on asynchronous devices.

Bits (14:2) —Domain foption.

Domain is meaningless for asynchronous devicefiles. However, if file redirection was anticipated at the time the file was opened, these bits may have been set.

=00: The file is a new file.
=01: The file is an old permanent file.
=10: The file is an old temporary file.
=11: The file is an old file.

Bit (13:1)—ASCII/binary foption.

Note that all files not on disk are treated as ASCII.

=0: Binary.
=1: ASCII.

Bit (10:3)—Default file designator foption.

=000: The actual and formal file designators are the same.
=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.

Bits (8:2)—Record format foption.

These bits are not meaningful for asynchronous devices since all records are of undefined length. However, if redirection was anticipated, "fixed-length" may have been specified.

=00: Fixed-length records.
=01: Variable-length records.
=10: Undefined-length records.
=11: Spoolfile.

Bit (7:1)—Carriage control foption.

=0: No carriage control character expected.
=1: Carriage Control character expected.

Bit (6:1)—MPE/iX tape label foption.

Not meaningful for asynchronous devices, but may have been set if file redirection was anticipated.

=0: Nonlabeled tape.
=1: Labeled tape.

Bits (5:1)—Disallow :FILE equation foption.

If this bit is set to 1, any :FILE equation intended to override the specifications set through the FOPEN or HPFOPEN call will be ignored.

=0: Allow :FILE command
=1: Disallow :FILE command.

Bits (2:3)—File type foption.

Will be set to 000 for asynchronous devicefiles.

=000: Standard file (STD).
=001: Keyed Sequential Access Method file (KSAM).
=010: Relative I/O file (RIO).
=100: Circular file (CIR).
=110: Message file (MSG).

Bits (0:2)—Reserved for MPE/iX. These should be set to 0.

aoptions

16-bit unsigned integer by reference (optional)

Returns information about the aoption characteristics that are set through the FOPEN or HPFOPEN call. The bit settings that designate each of these characteristics are listed below. Note that not all of the aoptions are meaningful for files on asynchronous devices.

Bits (12:4)—Access type aoption.

The type of access allowed users of the file. Refer to Table 8-10 “Access Types” for a summary of how these settings apply to terminals and printers.

=0000: Read access only.
=0001: Write access only.
=0010: Write access only, but previous data in file not deleted.
=0011: Append access only.
=0100: Input/output access.
=0101: Update access.
=0110: Execute access.
=0111: Execute/read access.
=1000: No access.

Bit (11:1)—Multirecord aoption.

Allows a block of data that exceeds the file's physical record size to be transmitted as several records. This option is available for use with terminals, but not for printers.

=0: Select non-multirecord mode.
=1: Select multirecord mode.

Bit (10:1)—Dynamic locking aoption

Not meaningful for asynchronous devices.

Bit (8:2)—Exclusive access aoption

Specifies whether you have continuous exclusive access to this file. This option does not apply to printers.

=00: Default.
=01: Exclusive access.
=10: Semi-exclusive access.
=11: Shared access.

Bit (7:1)—Inhibit buffering aoption

Not meaningful for asynchronous devices.

Bit (5:2)—Multiaccess mode aoption

Not meaningful for asynchronous devices.

Bit (4:1)—NOWAIT I/O aoption

Indicates whether or not NOWAIT I/O has been specified for the file. NOWAIT I/O allows the accessor to initiate an I/O request and to have control returned before the completion of the request.

=0: NOWAIT I/O not in effect.
=1: NOWAIT I/O in effect.

Bits (3:1)—File copy access aoption

Specifies whether or not a file may be treated as a standard sequential file rather than as a file of its own type.

=0: File must be accessed as its own type.
=1: File may be accessed as standard sequential file.

Bits (0:3)—Reserved for MPE/iX.

Table 8-10 Access Types

Access Types	Value	Used with a Terminal	Used with a Printer
Read only	0000	OK.	Returns File System Error 40: Operation Inconsistent with Access type.
Write only (Write/Delete)	0001	OK.	OK.
Write (save) only	0010	OK.	Executed as Write only.
Append only	0011	OK.	Executed as Write only.
Read/Write	0100	OK.	Executed as Write only.
Update	0101	OK.	Executed as Write only.
Execute	0110	Returns File System Error 40: Operation Inconsistent with Access type.	Returns File System Error 40: Operation Inconsistent with Access type.

lrecsize

16-bit signed integer by reference (optional)

Returns the logical record size associated with the file. This parameter is subject to record size limits imposed by MPE/V based systems, and is maintained only for backward compatibility.

If the record size of the specified file exceeds MPE/V limits, a zero is returned.

devtype

16-bit signed integer by reference (optional)

Returns the type and subtype of the device being used, where bits (0:8) indicate device subtype, and bits (8:8) indicate device type. Note that subtypes do not apply for terminals and printers.

If the file is not spooled the devtype returned is actual. The same is true if a spool file was opened via the logical device number. However, if an output file is spooled and was opened by device class name, devtype will return information about the first device in the class, which may not be the device actually being used.

ldevnum

16-bit unsigned integer by reference (optional)

Returns the logical device number of the port (and device) associated with the file.

hdaddr

16-bit unsigned integer by reference (optional)

Returns 2048. This value is meaningless on MPE/iX based systems; it is maintained only for backward compatibility.

filecode

16-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

lrecptr

32-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

EOF

32-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

filelimit

32-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

logcount

32-bit signed integer by reference (optional)

Returns the total number of logical records passed to and from the program during the current access of the file.

physcount

32-bit signed integer by reference (optional)

Returns the total number of physical input/output operations performed within this process against the file since the last FOPEN or HPFOPEN call.

blksize

16-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

extsize

16-bit unsigned integer by reference (optional)

Not meaningful for asynchronous devices.

numextent

16-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

userlabels

16-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

creatorid

character array (optional)

Not meaningful for asynchronous devices.

labaddr

32-bit signed integer by reference (optional)

Not meaningful for asynchronous devices.

Condition Codes

CCE: Request granted.
CCG: Not returned by this intrinsic.
CCL: Request denied. An error occurred.

Additional Discussion

See the discussion of requesting file information in Getting System Information and the MPE/iX Intrinsics Reference Manual. See also discussions of FFILEINFO and FOPEN in this manual.

FGETINFO

Technical documentation

» Table of Contents

» Glossary

» Index

Syntax

Use

Parameters

Condition Codes

Additional Discussion