SYSTEM CALLS - 1/0 86

This chapter describes the PL/M-86 calling sequences to Basic I/O System calls. The system calls are listed here alphabetically by the same shorthand notation used throughout this manual. For example,

A$DELETE$FILE refers to the asynchronous-level delete-file system call and appears alphabetically before SET$DEFAULT$PREFIX. This notation is language-independent and should not be confused with the actual form of the PL/M-86 call. The precise format of each call is spelled out as part of its detailed description.

Basic I/O operations are declared as typed or untyped external procedures for PL/M-86. PL/M-86 programs perform I/O operations by making external procedure calls.

INPUT PARAMETER SPECIFICATION

The following paragraphs explain special properties of certain input parameters to Basic I/O System calls.

USER PARAMETER

This parameter is specified in some asynchronous system calls. It contains a token designating the caller's user object. A zero

specification designates the default user. The Basic I/O System ignores this parameter for physical and stream files.

FILE-PATH PARAMETER(S) FOR NAMED FILES

Named files are designated in system calls by specifying their path, that is, their prefix and subpath. The prefix parameter can be a token

designating an existing device connection or file connection. If this parameter is zero, the default prefix for the calling task's job is assumed.

For named files, the subpath parameter is a pointer to an ASCII string.

The form of this string is described in the following paragraph. The subpath can also be zero or can point to a null string, in which case a prefix indicates the desired connection. For physical and stream files, the subpath parameter is always ignored.

SYSTEM CALLS

Prefix parameter contains a token for a connection. ASCII

SYSTEM CALLS

If the ASCII string begins with a slash, the prefix merely designates the tree and the subpath is assumed to start at the root directory of the tree associated with the prefix. For example, if the prefix designates

directory GYNECOLOGY in Figure 8-1, the sub path to OUT-PATIENT is /OBSTETRICS/DELIVERY/POST-PARTUM/OUT-PATIENT

Named files can also be addressed relative to other files in the tree, using "t" as a path component. The "t" refers to the parent directory of the current file in the path scan. For example, now that we have a

connection to OUT-PATIENT in Figure 8-1, we can use that connection to specify a sub path to IN-PATIENT. With the token for the OUT-PATIENT connection as our prefix, the subpath string would be

tIN-PATIENT

Note that no slash follows the "t" in this example.

Of course an even simpler approach would be to designate directory POST-PARTUM as the prefix, in which case the ASCII string becomes:

IN-PATIENT

RESPONSE MAILBOX PARAMETER

This parameter is specified only in asynchronous system calls. It

contains a token designating the mailbox that is to receive the result of the call. This information is provided by tasks to synchronize parallel operations. To receive the result of the call, a task must either call RECEIVE$MESSAGE and wait at the designated mailbox or call WAIT$IO. Be aware that if several calls share the same mailbox, the results may be received out of order.

Most asynchronous system calls return only an I/O result segment to the response mailbox. This segment contains an exception code and other information about the operation. Appendix C describes the I/O result segment. Other system calls -- A$ATTACH$FILE, A$CREATE$FILE, and

A$PHYSICAL$ATTACH$DEVICE -- return to the mailbox a token for a connection if the system call performs successfully or an I/O result segment

otherwise. After calling RECEIVE$MESSAGE to obtain the result of one of these system calls, a task should perform a GET$TYPE system call to ascertain the type of object returned to the response mailbox. The iRMX 86 NUCLEUS REFERENCE MANUAL describes the GET$TYPE system call in detail.

NOTE

I/O result segments should be deleted when they are no longer needed.

Otherwise, they will consume available memory.

I

IN-LABOR POST-PARTUM

SYSTEM CALLS

PRENATAL DELIVERY

IN-PATIENT OUT-PATIENT

OBSTETRICS GYNECOLOGY

ROOT DIRECTORY

EMPTY

·DIRECTORY

Figure 8-1. Sample Named File Tree

8-4

EMPTY DIRECTORY

x-303

SYSTEM CALLS

I/O BUFFERS

The A$READ and A$WRITE system calls each require a buffer while performing I/O. When you create these buffers, bear in mind the following restrictions:

• Once the I/O operation has been invoked, the tasks of your application should avoid changing the contents of the buffer until the Basic I/O System finishes the operation.

• If you use an iRMX 86 segment as a buffer, be sure that the buffer is not deleted while an I/O operation is in progress.

• If you choose to use an iRMX 86 segment as a buffer, you should ensure that the segment is in the same job as the task performing the I/O operation. Using segments from one job as buffers for I/O operations in a different job can lead to a problem. For instance, suppose that Job A owns an iRMX 86 segment, and that Job B uses this segment as a buffer for I/O. If Job A is

deleted, the iRMX 86 Operating System automatically deletes the buffer even if I/O is in progress.

CONDITION CODES

The Basic I/O System returns a condition code when a system call is invoked. If the call executes without error, the Basic I/O System returns the code "E$OK." If an error is encountered, some other code is returned.

For those system calls that do not require a response mailbox parameter, the Basic I/O System returns the condition code to the word pointed to by the except$ptr parameter. If an exceptional condition occurs, the Basic I/O System can then either return control to the calling task or pass control to an exception handler. See the iRMX 86 NUCLEUS REFERENCE MANUAL for a detailed description of exception handling.

For those system calls that do require a response mailbox parameter (the asynchronous calls), the Basic I/O System returns a condition code for the sequential portion of the call to the word pointed to by the

except$ptr parameter and a condition code for the concurrent portion of the call to the status field of the I/O result segment (see Appendix C).

If a sequential exceptional condition occurs, the Basic I/O System either returns control to the calling task or passes control to an exception

SYSTEM CALLS

The following pages provide a detailed description of each Basic I/O System call, listed alphabetically. The system call dictionary, which appears first, provides a summary of these calls, grouped by function and correlated to the file types to which they apply. That system call

dictionary also acts as a cross-reference to the detailed descriptions.

Throughout this chapter, PLhf-86 data types, such as BYTE and WORD, are used. In addition, the iRMX 86 data type TOKEN is used. Definitions of both PL/M-86 and iRMX 86 data types are given in Appendix A. Because TOKEN is not a PL/M-86 data type, if you use it you must declare it to be

literally a WORD or a SELECTOR in every module in which it is used.

8-6

SYSTEM CALLS

SYSTEM CALL DICTIONARY

This section summarizes the Basic I/O System calls by function and_t where applicable_t indicates the file types to which they apply:

PF Physical file SF Stream file NF Named data file ND Named directory file

The page reference listed with each call points to the detailed description for the call.

JOB-LEVEL SYSTEM CALLS System Call SET$DEFAULT$PREFIX GET$DEFAULT$PREFIX SET$ DEFAULT$ USER GET$DEFAULT$USER

DEVICE-LEVEL SYSTEM CALLS System Call

A$PHYSICAL$ATTACH$-DEVICE

A$PHYSICAL$DETACH$-DEVICE

A$SPECIAL

Function

Set default prefix for job.

Inspect default prefix.

Set default user for job.

Inspect default user.

Function

Asynchronous attach device.

Asynchronous detach device.

Asynchronous perform device-level function.

Page 8-122 8-115 8-124 8-117

Page 8-66

8-70

8-87

SYSTEM CALLS

FILE/CONNECTION-LEVEL SYSTEM CALLS

System Call Function P S N N Page

F F F D

A$CREATE$FILE Asynchronous data file creation.

* * *

^8-28

A$ ATTACH$ FILE Asynchronous attach

* * * *

^8-11

file.

A$ CREATE$ DIRECTORY Asynchronous directory

*

^8-23

file creation.

A$DELETE$CONNECTION Asynchronous delete

* * * *

^8-34

file connection.

A$DELETE$FILE Asynchronous data or

* * *

^8-37

directory file deletion.

FILE~ODIFICATION SYSTEM CALLS

System Call Function P S N N Page

F F F D

A$CHANGE$ACCESS Asynchronous change

* *

^8-15

access rights to file.

A$RENAME$FILE Asynchronous rename _file.

* *

^8-76

A$TRUNCATE Asynchronous truncate

*

^8-101

file.

FILE INPUT/OUTPUT SYSTEM CALLS

System Call Function P S N N Page

F F F D

A$OPEN Asynchronous open file.

* * * *

^8-62

A$SEEK Asynchronous move file

* * *

^8-81

pointer.

A$READ Asynchronous read file.

* * * *

^8-73

A$WRITE Asynchronous write file.

* * *

^8-107

A$CLOSE Asynchronous close file.

* * * *

^8-20

8-8

SYSTEM CALLS

FILE INPUT/OUTPUT SYSTEM CALLS (continued)

System Call Function P S N N Page

F F F D

A$UPDATE Asynchronous finish

* * *

^8-104

writing to output device.

WAIT$IO Synchronous wait for

* * * *

^8-127

status after I/O.

GET STATUS/ATTRIBUTE SYSTEM CALLS

System Call Function P S N N Page

F F F D

A$ GET$ CON- Asynchronous get

* * * *

^8-42

NECTION$STATUS connection status.

A$GET$FILE$STATUS Asynchronous get file

* * * *

^8-52

status.

A$GET$DIRECTORY$ENTRY Asynchronous inspect

*

^8-46

directory entry.

A$GET$PATH$COMPONENT Asynchronous obtain

* *

^8-58

path name from connection token.

USER OBJECT SYSTEM CALLS

System Call Page

CREATE$USER Create a user object. 8-111

INSPECT$USER Get IDs in a user object. 8-120

DELETE$USER Delete a user object. 8-113

EXTENSION DATA SYSTEM CALLS

System Call Function P S N N Page

F F F D

A$SET$EXTENSION$DATA Asynchronous store a

* *

^8-84

file's extension data.

A$GET$EXTENSION$DATA Asynchronous receive a

* *

^8-49

file's extension data.

TIME/DATE SYSTEM CALLS System Call

I

^SET$TIME

GET$TIME

SYSTEM CALLS

Function

Set date/time value in internally-stored format.

Get date/time value in internally-stored format.

8-10

Page 8-126

8-119

A$ATTACH$FILE

A$ATTACH$FILE creates a connection to an existing file.

CALL RQ$A$ATTACH$FILE(user, prefix, subpath$ptr, resp$mbox, except$ptr) ;

INPUT PARAMETERS user

prefix

subpath$ptr

OUTPUT PARAMETERS resp$mbox

except$ptr

A TOKEN for the user object to be inspected in any access checking that takes place. A zero

specifies the default user for the calling task's job. This parameter is ignored when attaching physical or stream files. Access checking does occur for named files.

A TOKEN for the connection object to be used as the path prefix. A zero specifies the default prefix for the calling task's job.

A POINTER to a STRING containing the subpath of the file to be attached. A null string indicates that the new connection is to the file designated by the prefix. The new connection will not be open, regardless of the open state of the prefix.

A TOKEN into which the Basic I/O System places a token for the mailbox that receives the result object of the call. This result object is a new file connection if the call succeeds or an I/O-result segment ot'herwise (see Appendix C). To ascertain the type of object returned, use the Nucleus system call GET$TYPE.

If the object received is an I/O result segment, the calling task should call DELETE$SEGMENT to delete the segment after examining it.

A POINTER to a WORD where the sequential condition code will be returned.

I

DESCRIPTION

A$ATTACH$FILE creates a connection to an existing file. Once the connection is established, it remains in effect until the connection object is deleted, or until the creating job is deleted. Once attached, the file may be opened, closed, read, written, etc., as many times as desired. A$ATTACH$FILE has no effect on the owner ID or the access list for the file.

CONDITION CODES

A$ATTACH$FILE 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$DEV$OFF$LlNE

E$EXIST

No exceptional conditions.

The prefix parameter in this system call refers to a logical connection. One of the following is true:

• The device has been physically attached but is now off-line.

• The device has never been physically attached.

(See Appendix E for a more detailed explanation. )

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 user parameter

• The prefix parameter

• The resp$mbox parameter

2. The prefix connection is being deleted.

8-12

E$LIMIT

Im Dokument 1/0 86 (Seite 59-71)