DESCRIPTION
The A$GET$DlRECTORY$ENTRY system call applies to named files only. When called, it returns the file name associated with a specified directory entry. This name is a single subpath component for a file whose parent is the designated directory. As an alternative to using this system call, an application task can open and read a directory file.
CONDITION CODES
NOTE
The caller must have display access to the designated directory.
A$GET$DlRECTORY$ENTRY returns condition codes at two different times. The code returned to the calling task immediately after invocation of the system call is considered a sequential condition code. A code returned as a result of asynchronous processing is a concurrent condition code. A complete explanation of sequential and concurrent parts of system calls is in Chapter 7 of this manual.
The following list is divided into two parts -- one for sequential codes, and one for concurrent codes.
Sequential Condition Codes
The Basic I/O System can return the following condition codes to the word specified by the except$ptr parameter of this system call.
E$OK E$EXIST
E$IFDR
E~LIMIT
No exceptional conditions.
Two conditions can cause this exception code to be returned:
1. One or more of the following parameters is not a token for an existing object:
• The connection parameter
• The resp$mbox parameter 2. The connection is being deleted.
This system call applies only to named directories, but the connection parameter specifies another type of file.
The call cannot be processed without exceeding the maximum number (specified when the job was created)
:J)li.r.iTtI)UllU!A.iTU.l1. I tI).l!.il~Tn. I
I
I
E$MEM
E$NOT$CONFIGURED
E$SUPPORT
E$TYPE
The memory pool of the calling task's job does not currently have a block of memory large enough to allow this system call to run to completion.
A$GET$DlRECTORY$ENTRY was not included when the system was configured.
The connection parameter specified is not valid in this system call because the connection was not created by this job.
One of more of the following is true:
• The connection parameter contained a token for an object that is not a connection.
• The resp$mbox parameter contained a token for an object that is not a mailbox.
Concurrent Condition Codes
The Basic I/O System can return the following condition codes in an I/O result segment at the mailbox specified by resp$mbox. After examining the segment, you should delete it.
E$OK E$DIR$END
E$EMPTY$ENTRY E$FACCESS
E$FTYPE
E$IO
No exceptional conditions.
The entry$num parameter is greater than the number of entries in the directory.
The file entry designated in the call is empty.
The specified connection is not qualified for
"display" access to the directory.
The specified connection does not refer to a directory.
An I/O error occurred, which might or might not have prevented the operation from being completed.
8-48
A$GET$EXTENSION$DATA
The A$GET$EXTENSION$DATA system call returns extension data stored with a Basic I/O System file.
CALL RQ$A$GET$EXTENSION$DATA(connection, resp$mbox, except$ptr);
INPUT PARAMETERS connection
resp$mbox
OUTPUT PARAMETER except$ptr
A TOKEN of a connection to a file whose extension data is desired.
A TOKEN for the mailbox that will receive a segment containing the named file-status
information. The calling task is responsible for deleting this segment after examining it.
Structure of the named file-status information is as follows:
DECLARE ext$data$seg STRUCTURE ( status WORD,
count BYTE, info(*) BYTE);
These fields are interpreted as follows:
status
count
info
A condition code indicating the outcome of the status-fetch
operation. If this code is not E$OK, the remaining fields must be
considered invalid.
A number (from 0 to 255 decimal) indicating the number of bytes returned.
The extension data.
A POINTER to a WORD where the sequential condition code will be returned.
DESCRIPTION
A$sociated with each file created through the Basic I/O System is a file descriptor containing information about the file. Some of that
information is used by the Basic I/O System and can be accessed by tasks through the A$GET$FILE$STATUS system call. Up to 255 additional bytes of the file descriptor, known as extension data, are available for use by Operating System extensions. OS extensions can write extension data by using A$SET$EXTENSION$DATA and they can read extension data by using A$ GET$ EXTENS ION$DATA.
When a task calls A$GET$EXTENSION$DATA, it specifies a response mailbox to which the system returns a segment with the extension data. The information is located in the low-memory portion of the segment.
A$GET$EXTENSION$DATA can only be applied to connections created via the named file driver.
CONDITION CODES
A$GET$EXTENSION$DATA can return condition codes at two different times.
The code returned to the calling task immediately after invocation of the system call is considered a sequential code. A code returned as a result o·f asynchronous processing is a concurrent exception code. A complete explanation of sequential and concurrent parts of system calls is in Chapter 7 of this manual.
The following list is divided into two parts -- one for sequential codes and one for concurrent codes.
Sequential Condition Codes
The Basic I/O System can return the following exception codes to the word specified by the except$ptr parameter of this system call.
E$OK E$EXIST
E$IFDR
No exceptional conditions.
Two conditions can cause this exception code to be returned:
1. One or more of the following parameters is not a token for an existing object:
• The connection parameter
• The resp$mbox parameter.
2. The connection is being deleted.
This system call applies only to named files, but the prefix and subpath parameters specify another type of file.
8-50
E$LIMIT The call cannot be processed without exceeding the maximum number (specified when the job was created) of objects allowed for this job.
E$MEM The memory pool of the calling task's job does not currently have a block of memory large enough to allow this system call to run to completion.
E$NOT$CONFIGURED A$GET$EXTENSION$DATA was not included when the system was configured.
E$SUPPORT
E$TYPE
The connection parameter specified is not valid in this system call because the connection was not created by this job.
One or more of the following is true:
•
The connection parameter contained a token for an object that is not a connection.•
The resp$mbox parameter contained a token for an object that is not a mailbox.Concurrent Exception Codes
The Basic I/O System will return one of the following codes in an 1/0 result segment at the mailbox specified by resp$mbox. After examining the segment, you should delete it.
E$OK E$IO
No exceptional conditions.
An I/O error occurred, which might or might not have prevented the operation from being completed.
I
I
A$GET$FILE$STATUS
A$GET$FILE$STATUS returns status and attribute information about a file.
CALL RQ$A$GET$FILE$STATUS(connection, resp$mbox, except$ptr);
INPUT PARAMETER contents of the named$file field indicates whether the file is a named file.
DECLARE file$info STRUCTURE ( status
A$GET$FILE$STATU
Tells whether this structure contains any information beyond the dev$conn field. OFFH means yes and 0 means no.
$GET$FILE$STATUS corresponding function is supported. Bit 0 is the low-order bit.