HPlogo MPE/iX Intrinsics Reference Manual > Chapter 5 Command Definitions (FCONTROL - FLOCK)

FLABELINFO

MPE documents

Complete PDF
Table of Contents
Index

Edition 7 E0701
Edition 7 E0300 ♥
Edition 6 E0195

NM and CM callable.

Returns information from the file label of a disk file.

Syntax


              CA           I16V  I16
  FLABELINFO (formaldesig, mode, fserrorcode,
  
    I16A     REC   I16A
    itemnum, item, itemerror);

Parameters

formaldesig

character array (required)

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 be an HFS syntax name beginning with a dot or a slash.

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 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.

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, FLABELINFO fails and a file system error code (398) is returned in the fserrorcode parameter.

If the file can be named using both MPE syntax and HFS syntax (for example, FILEA.MYGROUP.MYACCT and /MYACCT/MYGROUP/FILEA), the file can be either permanent or temporary. If a temporary and a permanent file have the same name, FLABELINFO returns information about the temporary file only.

mode

16-bit signed integer by value (required)

Passes an option specifying the valid backreferencing to file equations for the file.

Bits

Value/Meaning

0:11

Reserved for future use.

11:1

Symbolic Link Traversal

0

To traverse through symbolic links, if they exist.

1

Do not traversing through symbolic links, if they exist.

12:2

Caller Privilege Level

Allows the caller to pretend to be less privileged. The privilege level is passed in this field.

14:2

File Equations

0

Use file equations if they exist.

1

A file equation must be used.

2

Do not use a file equation.

fserrorcode

16-bit signed integer by reference (required)

Returns a value indicating whether an error or warning occurred when FLABELINFO attempted to return requested information:

  • A value of zero indicates that no errors were encountered.

  • A positive value is a file system error code and indicates that an error was encountered and no information was returned in item.

  • A -1 indicates that an item error or warning has occurred. Check the itemerror parameter to determine which item(s) has an error/warning and what it is.

itemnum

16-bit signed integer array (required)

Specifies which item value is to be returned. (Refer to Table 5-6 "FLABELINFO Itemnum/Item Values".)

To indicate the end of the list, place a zero in the element following the last itemnum.

item

record (required)

Returns the value of the item specified in the corresponding itemnum. (Refer to Table 5-6 "FLABELINFO Itemnum/Item Values".)

Itemnum/items are paired such that the nth field of the item record corresponds to the nth element of the itemnum array.

itemerror

16-bit signed integer array (required)

Returns an error number corresponding to the items specified in the itemnum array. The itemnum/item and itemerror parameters are paired such that the nth element of the itemerror array corresponds to the nth element of the itemnum array.

If a value in the itemerror array is negative, a warning exists for the corresponding item. If the value is positive, an error was detected for the corresponding item. The absolute value of each value is a file system error number.

Table 5-6 FLABELINFO Itemnum/Item Values

Itemnum Mnemonic Item Description
1CAFile name (8 bytes):

The file name component for the file referenced in formaldesig is returned as the value. If the file name is not expressible using MPE-only semantics, a file system error code (391) is returned in the associated itemerror.
2CAGroup name (8 bytes):

The group name component for the file referenced in formaldesig is returned as the value. If the group name is not expressible using MPE-only semantics, a file system error code (391) is returned in the associated itemerror.
3CAAccount name (8 bytes):

The account name component for the file referenced in formaldesig is returned as the value. If the account name is not expressible using MPE-only semantics, a file system error code (391) is returned in the associated itemerror.
4CAFile creator name (8 bytes):

An unqualified form of the file owner's name is returned as the value. The file owner is not necessarily the file's creator.

A symbolic zero (ASCII 48 in decimal) is returned as the file owner for root directories, MPE accounts, and MPE groups created prior to release 4.5.

If the file is not located in the account where the file owner is a member, a blank file owner name is returned. Use itemnum=43 to obtain the full file owner name.
5U32Security matrix for access:

Returns the file's security matrix. This value does not indicate the actual security enforced for a file, since group and account security masks can also restrict access. This field is ignored if an ACD is active on a file.
6U16File creation date:

The date in CALENDAR intrinsic format. Either creator (C) or manager (AM if file is within account, otherwise SM) access required.

Zero is returned as the creation date for root directories, MPE accounts, and MPE groups created prior to release 4.5.
7U16Last access date:

The date in CALENDAR intrinsic format. May not be up-to-date when the file is open.

Zero is returned as the last access date for root directories, MPE accounts, and MPE groups created prior to release 4.5.
8U16Last modification date:

The date in CALENDAR intrinsic format. May not be up-to-date when the file is open.

Zero is returned as the modification date for root directories, MPE accounts, and MPE groups created prior to release 4.5.
9I16File code of disk file
10U16Number of user labels written:

May not be up-to-date when the file is open.
11U16Number of user labels available:

May not be up-to-date when the file is open.
12I32Total number of logical records possible in the file:

Equivalent to the file limit measured in logical records.
13U16File options:

The record format extension bit is returned as the foption (1:1) bit. Byte stream record format is represented as a record format extension of one with a variable record format (foption (8:2) bits equal to 01).

Directories, symbolic links, device links, pipes and FIFO's cannot be represented by foption. If the object referenced by filenum is is an object, MPE error 399 is returned in the associated itemerror.

Refer to the foption figure.
14I16Record size:

Maintained for compatibility with MPE V/E-based systems. (If a zero is returned, use itemnum 30 instead.)
15I16Block size:

Maintained for compatibility with MPE V/E-based systems. (If a zero is returned, use itemnum 31 instead.)
16I16Maximum number of extents:

Maintained for compatibility with MPE V/E-based systems. (If a zero is returned, use itemnum 32 instead.)
17I16Last extent size:

Indicates sectors. May not be up-to-date when the file is open.
18I16Extent size:

Indicates sectors. (If a zero is returned, use itemnum 32 instead.)
19U32Number of logical records in file:

Equivalent to EOF. May not be up-to-date when the file is open.
20U32File allocation time:

The time when file was last restored (in CLOCK intrinsic format).

Zero is returned as the file allocation time for root directories, MPE accounts, and MPE groups created prior to release 4.5.
21U16File allocation date:

The date when the file was last restored (in CALENDAR intrinsic format).

Zero is returned as the file allocation date for root directories, MPE accounts, and MPE groups created prior to release 4.5.
22I32Number of open/close records:

MSG files only. May not be up-to-date when the file is open.
23CADevice name (8 bytes)
24U32Last modification time:

The time when the file was last modified (in CALENDAR intrinsic format). May not be up-to-date when the file is open.
25CAFirst user label (user label 0) (256 bytes):

May not be up-to-date when the file is open. For all but PM files, Manager capabilitiy (AM if file is within account, otherwise SM) or read/write (R/W) access required. For PM files, Manager capability is required; otherwise, FLABELINFO fails with FSERR93.
27RECUnique file identifier (UFID) (20 bytes)
28U32Total number of bytes allowed in file:

Equivalent to the file limit measured in bytes. May not be up-to-date when the file is open. If the file limit of the file is larger than 4gb, this item will return FSERR 311. Item number 62 returns the file limit of the file in bytes, in a 64-bit value which can safely be used for all files.
29U32Start of file offset:

Indicates the byte offset where user data starts.
30U32Record size (indicates bytes
31U32Block size (indicates bytes)
32U32Extent size (indicates bytes)
33CAFile lockword (8 bytes):

Returned if you are the file creator, account manager, or system manager.
34CAVolume restriction (34 bytes):

The last two characters indicate the type of restriction, as follows:
0

File is placed on the specified volume at creation

1

File can be placed on any volume containing the specified class at creation

2

File can be placed on any volume within the specified volume set at creation (Default)

35CAVolume set names (32 bytes)

No restrictions.
36U32Transaction management log set id (4 bytes)

No restrictions.
37U16Logical device number
38RECTerminated HFS-syntax system absolute pathname:

Upon input, the first four bytes are interpreted as a 32-bit unsigned integer specifying the maximum available buffer size in bytes. This maximum available buffer size does not include the four bytes used to represent this size. Upon output, the first four bytes represent the pathname length excluding the null terminator as a 32-bit unsigned integer. The pathname is returned in bytes following the pathname length. Bytes beyond the pathname terminator are undefined. If the maximum available buffer size is incorrect upon input, variables allocated near the buffer can be overwritten or a bounds violation could occur. A zero pathname length is returned for unnamed new files and when an error occurs. Zero is the minimum buffer length upon input for this itemnum. 

  Format of the buffer on input:
  byte
    #1   #2   #3   #4 | #1   ..   #N
  +----+----+----+----+----+ .. +----+
  |      maximum      |              |
  |     length = N    |              |
  +----+----+----+----+----+ .. +----+

  Format of the buffer on output:
  byte
    #1   #2   #3   #4 | #1   ..   #L   ..   #N
  +----+----+----+----+----+ .. +----+ .. +----+
  |    length =       | /  |    | \0 |    |    |
  |    (L - 1)        |    |    |    |    |    |
  +----+----+----+----+----+ .. +----+ .. +----+
39U32The current number of hard links to the file
40I32Time of last file access (clock format):

The bit assignments are: 

  bits 0-7   = hours
  bits 8-15  = minutes
  bits 16-23 = seconds
  bits 24-31 = tenths of seconds
41I32Time of last file status change (clock format):

The bit assignments are: 

  bits 0-7   = hours
  bits 8-15  = minutes
  bits 16-23 = seconds
  bits 24-31 = tenths of seconds
42U16Date of the last file status change (calendar format):

The bit assignments are: 

  bits 0-7  = years since 1900
  bits 8-15 = day of the year
43CAFile owner (32 bytes):

The full file owner name. Unused characters are filled with blanks. A symbolic zero (ASCII 48 in decimal) is returned as the file owner for root directories, accounts, and MPE groups created prior to release 4.5.
44I32File owner identifier:

The file owner identifier (UID). Zero is returned as the file owner ID for root directories, MPE accounts, and MPE groups created prior to release 4.5.
45CAFile group (32 bytes):

The file group name. Unused characters are filled with blanks. A symbolic zero (ASCII 48 in decimal) is returned as the group for root directories where GIDs have not been explicitly assigned.
46I32File group identifier:

The file group identifier (GID). Zero is returned as the group ID for root directories where GIDs have not been explicitly assigned.
47U32File type:

Following are valid file types that can be returned: 

  0 = Ordinary file
  1 = KSAM/3000
  2 = RIO
  3 = KSAM XL
  4 = CIR
  5 = Native Mode Spool File
  6 = MSG
  7 = KASM64
  8 = N/A
  9 = Directory
  10-11= N/A
  12 = Pipe
  13 = FIFO
  14 = Symbolic Link
  15 = Device Link
  16 = TTY Device link
  17 = RAID Device link
48U32Record type:

Following are valid record types that can be returned: 

  0 = fixed
  1 = variable
  2 = undefined
  3 = spool block
  4 = root directory
  5 = N/A
  6 = account directory
  7 = group directory
  8 = N/A
  9 = byte stream
  10 = hierarchical directory
49I64Current file size (in bytes):

The value returned represents the current position of the end-of-file (EOF) and may not reflect the number of bytes actually occupied by the file on disk if the file is sparsely allocated.
50I32KSAM XL and KSAM64 File Version:

This item returns a value indicating the version number of a KSAM XL or KSAM64 file. A value of 1 indicates an original type KSAM XL file. A value of 2 indicates the next generation KSAM XL file. A value of zero is returned if the file is not a KSAM XL file. A value of 4 indicates a KSAM64 file.
51I32KSAM XL/64 Parameters:

This item returns the ksamparam for KSAM XL/64 files, which is an array that specifies the characteristics for up to 16 keys for the file.
52I32MPE/iX Device Type:

This item returns the following values for the following types of devices: 

  0 = Disk device
  1 = Tape device
  2 = Terminal device
  3 = Printer device
  4 = Remote device
  5 = Ports device
  6 = Reserved
  7 = Streams device
  8 = Sockets device
53I16Secure/Release:

This item returns a value indicating whether the file is currently secured or released. A value of 1 indicates that the file is secured. A value of zero indicates that the file is released.
54I32Setuid flag

This item returns a value indicating whether or not the setuid flag is on for the specified file. When the setuid flag is on for a program file (the value is 1), the program will execute under the identity of the file's owner rather than assuming the identity of the process that invoked the program. A value of zero indicates the flag is off.
55I32Setgid flag

This item returns a value indicating whether or not the setgid flag is on for the specified file. When the setgid flag is on for a program file (the value is 1), the program will execute with the GID membership of the file rather than assuming the GID membership of the invoking process. A value of zero indicates that the flag is off.
56I32File compressed flag

This value indicates whether or not the data in the specified file is compressed or not.
0

data is not compressed

1

data is compressed

57I32File migrated flag

This value indicates wheter or not the data in the specidfied file has been migrated off of disk.
0

data has not been migrated

1

data has been migrated

58I32Number of sectors allocated to file (32)

This value returns the number of 256 byte disk sectors that are currently allocated to this file. Note that this value is limited to returning valid data for files 512MB and less. To safely get this information for all file sizes, use item 63 , which returns the same value in a 64-bit integer.
59I32Number of extents in the file

This value returns the number of extents (contiguously allocated chunks of disk space) that are allocated to this file.
60I32File create time

The time when the file was created (in CLOCK intrinsic format).
61I32Number of Accessors

Returns the number of times the file has been opened at the moment of the call. Note that additional opens or closes may occur immediately after this value is computed., rendering the value stale.
62I6464-bit file limit in bytes

This item is identical to item 28, except that the file size is returned in a 64-bit integer which can safely be used for files of all sizes.
63I6464-bit number of sectors allocated to file

This item is identical to item 58, except that the value is returned in a 64-bit integer making it safe for use with files of all sizes.
64I32Large file flag

This flag indicates whether or not the specified file's file limit is large (greater than 4GB- 64KB or 4,294,901,760 bytes) Note that this applies to the file limit or potential capacity of the file only , and not to the actural amount of disk space allocated to the file.
0

file is not large

1

file is large

Condition Codes

CCE (2)

Request granted.

CCG (0)

Not returned. U

CCL (1)

Request denied. An error occurred. Refer to the fserrorcode and itemerror parameters for more information.

Related Information

None



FINTSTATE

FLOCK