Obtains information about a file of any type. This call can be used with any file, including those created by the BIOS.
CALL rq$s$get$file$status (path_ptr, info_ptr, except_ptr);
rq_s_get_file_status (path_ptr, info_ptr, except_ptr);
| Parameter | PL/M Data Type | C Data Type |
| path_ptr | POINTER | STRING far * |
| info_ptr | POINTER | S_FILE_STATUS_STRUCT far * |
| except_ptr | POINTER to WORD_16 | UINT_16 far * |
path_ptr
A pointer to a STRING that contains the path for the file. The format of this path varies depending on the file type.
See also:Path syntax, System Concepts
info_ptr
A pointer to this structure where the EIOS returns file status information. The information returned depends on the type of file specified. For all types of files, the first part of this structure through the device_connection field returns. If the contents of the named_file field indicate a named file, the second part (from file_ID on) returns. The create_time, access_time, modify_time, and owner_access elements have different meaning for DOS files.
DECLARE file_info STRUCTURE(
device_shareWORD_16,
number_connectionsWORD_16,
number_readersWORD_16,
number_writersWORD_16,
shareBYTE,
named_fileBYTE,
device_name(14)BYTE,
file_driversWORD_16,
functionsBYTE,
flagsBYTE,
device_granularityWORD_16,
device_sizeWORD_32,
device_connectionsWORD_16,
file_idWORD_16,
file_typeBYTE,
file_granularityBYTE,
owner_idWORD_16,
create_timeWORD_32,
access_timeWORD_32,
modify_timeWORD_32
file_sizeWORD_32,
file_blocksWORD_32,
volume_name(6)BYTE,
volume_granularityWORD_16,
volume_sizeWORD_32,
accessor_countWORD_16,
owner_accessBYTE);
or
typedef struct {
UINT_16device_share;
UINT_16number_connections;
UINT_16number_readers;
UINT_16number_writers;
UINT_8share;
UINT_8named_file;
UINT_8device_name[14];
UINT_16file_drivers;
UINT_8functions;
UINT_8flags;
UINT_16device_granularity;
UINT_32device_size;
UINT_16device_connections;
UINT_16file_id;
UINT_8file_type;
UINT_8file_granularity;
UINT_16owner_id;
UINT_32creation_time;
UINT_32access_time;
UINT_32modify_time;
UINT_32file_size;
UINT_32file_blocks;
UINT_8volume_name[6];
UINT_16volume_granularity;
UINT_32volume_size;
UINT_16accessor_count;
UINT_8owner_access;
} S_FILE_STATUS_STRUCT;
Where:
device_share
This is always set to 1, indicating that all devices can be shared.
number_connections
The number of connections to the file. For remote and NFS files, this field indicates the number of connections the calling job has to the file.
number_readers
The number of connections currently open for reading. For remote and NFS files a 0 indicates either no connection or a connection open for writing only, and a 1 indicates an open readable or read/writable connection.
number_writers
The number of connections currently open for writing. For remote files a 0 indicates either no connection or a connection open for reading only, and a 1 indicates an open writable or read/writable connection.
shareThe current shared status of the file; possible values are
| Value | Meaning |
| 0 | Private use only |
| 1 | Share with readers only |
| 2 | Share with writers only |
| 3 | Share with all users |
If a remote or NFS file is open, the share mode used to open the connection is returned, but if the file connection is not open, share mode 3 is indicated.
named_file
Indicates if this structure contains any information beyond the device_connections field.
| Value | Meaning |
| 0 | No |
| 0FFH | Yes |
device_name
The physical device name where this file resides. This name is padded with blanks. Device names should not exceed 14 characters in length.
For remote files, this is the name of the remote server on which the file resides. For NFS files, this is the host name and path used when the device was attached.
file_drivers
Indicates what kinds of files can reside on this device. When the device is formatted, this value is copied into the device volume label.
| File Type Bit | File Type |
| 7-6 | Reserved |
| 5 | EDOS file |
| 4 | Remote (iRMX-NET) or NFS file |
| 3 | Named file |
| 2 | DOS |
| 1 | Stream file |
| 0 | Physical file |
functionsDescribes the functions supported by the device where this file resides. A bit set to 1 indicates the corresponding function is supported. This field is not supported by the remote file driver; 0 is always returned for remote files.
| Bit | Function |
| 7 | F_CLOSE |
| 6 | Reserved |
| 5 | F_DETACH_DEV |
| 4 | Reserved |
| 3 | F_ATTACH_DEV |
| 2 | F_SEEK |
| 1 | F_WRITE |
| 0 | F_READ |
flagsMeaningful only for diskette drives. This field is not supported by iRMX-NET or the NFS file driver; 0 returns for such remote files.
| Bits | Value | Function |
| 7-5 | Reserved; set to 0 | |
| 4 | 0 | Standard diskette, for MBI only; track 0 is single-density, 128-byte sectors |
| 1 | Uniform diskette or not a diskette | |
| 3 | 0 | High (quad) density |
| 1 | Low (double) density For 8" diskettes, set to 0 |
|
| 2 | 0 | Single sided |
| 1 | Double sided | |
| 1 | 0 | Single density |
| 1 | Not single density | |
| Disk SizeBit 1Bit 3
3.5D11 3.5Q10 5.25D11 5.25Q10 8S00 8D10 |
||
| 0 | 0 | This field is undefined |
| 1 | Bits 7-1 are valid |
See also:Supporting the standard diskette format, Driver
Programming Concepts
device_granularity
The granularity, in bytes, of the device where this file resides.
device_size
The storage capacity of the device, in bytes.
device_connections
The number of connections to the device. For remote and NFS files, this field contains the number of connections that local users have to files on the remote server.
file_idAn fnode number that distinguishes this file from all other files on the same device.
file_typeThe file type.
| Value | Meaning |
| 6 | Directory file |
| 8 | Data file |
file_granularity
The file granularity as a multiple of volume_granularity. For remote and NFS files, 1 is always returned.
owner_idThe first ID in the creating task's default user object.
create_time, access_time, modify_time
The time and date when the file was created, accessed, or modified. For DOS files, only creation_time or modify_time returns. For ICU-configurable systems, an ICU option determines whether the OS maintains these fields.
See also:TF parameter, ICU User's Guide and Quick
Reference
file_sizeThe total size of the file, in bytes.
file_blocks
The number of volume blocks allocated to this file. A volume block is a contiguous area of storage that contains volume_granularity bytes of data.
volume_name
The left-adjusted, null-padded ASCII name for the volume containing this file.
volume_granularity
The volume granularity, in bytes.
volume_size
The storage capacity, in bytes, of the volume on which this file is stored.
accessor_count
The number of IDs in the file's accessor list. User IDs for NFS files may be mapped differently for different OSs.
owner_access
The access rights to this file that are currently held by the owner. In this table, access is granted if a bit is set to 1. Access rights for NFS files may be mapped differently for different OSs:
| Bits | Data File | Directory File |
| 7-4 | Reserved | Reserved |
| 3 | Update | Change Entry |
| 2 | Append | Add Entry |
| 1 | Read | List |
| 0 | Delete | Delete |
See also:Accessing NFS files, Chapter 17, System Concepts
except_ptr
A pointer to a variable declared by the application where the call returns a condition code.
For asynchronous BIOS calls, some returned information might be inaccurate. For instance, if the application invokes s_get_file_status while the BIOS is processing an a_write call for the same file, the values returned in the file size fields might be incorrect. The EIOS cannot check such values and does not check access before returning file status information.
See also:BIOS call a_write
| E_OK | 0000H | No exceptional conditions occurred. |
| E_ALREADY_ATTACHED | 0038H | The EIOS is unable to attach the device containing the file because the BIOS has done so. |
| E_CONTEXT | 0005H | The calling task's job is not an I/O job. |
| E_DEV_DETACHING | 0039H | The device containing the specified file is being detached. |
| E_DEVFD | 0022H | The EIOS attempted to physically attach a device that had formerly been only logically attached. It found that the device and the device driver specified in the logical attachment were incompatible. |
| E_FNEXIST | 0021H | At least one of these is true:
·A file in the specified path, or the target file itself, does not exist or is marked for deletion. ·The physical device specified in the call was not found. |
| E_FTYPE | 0027H | A path component is not a directory file. |
| E_ILLVOL | 002DH | The EIOS attempted to physically attach a device that had formerly been only logically attached. It found that the volume does not contain named files. The named, remote, DOS, or EDOS file driver was requested during logical attachment. |
| E_INVALID_FNODE | 003DH | The fnode for the specified file is invalid. The file cannot be accessed; delete it or fix it with diskverify.
See also:diskverify, Command Reference |
| E_IO_HARD | 0052H | A hard error occurred; the BIOS cannot retry the request. |
| E_IO_MODE | 0056H | A tape drive attempted a read (write) before the previous write (read) completed. |
| E_IO_NO_DATA | 0055H | A tape drive attempted to read the next record, but it found no data. |
| E_IO_OPRINT | 0053H | The device was off-line. Operator intervention is required. |
| E_IO_SOFT | 0051H | A soft I/O error occurred. The I/O System tried to perform the operation a number of times and failed (the number of retries is a configuration parameter). Another retry might be successful.
See also:For ICU-configurable systems, RPA parameter, ICU User's Guide and Quick Reference |
| E_IO_UNCLASS | 0050H | An unknown I/O error occurred. |
| E_IO_MEM | 0042H | The BIOS job does not currently have a block of memory large enough to allow this system call to complete. |
| E_LIMIT | 0004H | At least one of these is true:
·The user object or the calling task's job is involved in 255 I/O operations. ·The calling task's job is not an I/O job. ·The calling task's object limit has been reached. |
| E_LOG_NAME_NEXIST | 0045H | The specified path contains a logical name, but the call was unable to find this name in the object directories of the calling task's local job, the global job, or the root job. |
| E_LOG_NAME_SYNTAX | 0040H | The specified logical name contains at least one of these syntax errors:
·The logical name was missing matching colons. ·Contains a logical name that exceeds 12 characters, has no characters, or contains invalid characters. |
| E_MEDIA | 0044H | The device containing the specified file is off-line. |
| E_MEM | 0002H | The memory available to the calling task's job is not sufficient to complete the call. |
| E_NOPREFIX | 8022H | The default prefix for the calling task's job is undefined, or is not a valid device or file connection. |
| E_NOT_CONFIGURED | 0008H | This system call is not part of the present configuration. |
| E_NOT_FILE_CONN | 0032H | For remote files, the connection parameter must be a file connection, not a device connection. |
| E_NOT_LOG_NAME | 8040H | The specified path contains a logical name that refers to an object that is not a device connection or a file connection. |
| E_NOUSER | 8021H | The calling task's job does not have a default user, or is not a user object. |
| E_PARAM | 8004H | The EIOS attempted to physically attach a device that had formerly been only logically attached. It found that the logical attachment referred to a file driver that is not configured into your system.
See also:For ICU-configurable systems, DFD parameter, ICU User's Guide and Quick Reference |
| E_PATHNAME_SYNTAX | 003EH | The specified pathname contains invalid characters. |
| E_UDF_IO | 02D0H | An error occurred while accessing the remote server's UDF. The server's UDF must have World read permission. |