You can cause a QIO read operation to time out after a certain number
of seconds by modifying the operation with IO$M_TIMED and by specifying
the number of seconds in the P3 argument. A message
broadcast to a terminal resets a timer that is set for a timed read
operation (regardless of whether the operation was initiated with QIO
or SMG).
Note that the timed read operations work on a character-by-character
basis. To set a time limit on an input record rather than an input
character, you must use the SYS$SETIMR system service. The SYS$SETIMR
executes an AST routine at a specified time. The specified time is the
input time limit. When the specified time is reached, the AST routine
cancels any outstanding I/O on the channel that is assigned to the
user's terminal.
You can also inhibit line editing with a QIO read operation modified by
IO$M_NOFILTR (defined in $IODEF).
22.5.8 Using Broadcasts
If the terminal user has taken no action to handle broadcasts, a
broadcast is written to the terminal screen at the current position
(after a carriage return and line feed). If a write operation is in
progress, the broadcast occurs after the write ends. If a read
operation is in progress, the broadcast occurs immediately; after the
broadcast, any echoed user input to the aborted read operation is
written to the screen (same effect as pressing Ctrl/R).
22.5.8.2 How to Create Alternate Broadcast Handlers
The SMG$SET_BROADCAST_TRAPPING routine is not an SMG$ input routine.
Before invoking SMG$SET_BROADCAST_TRAPPING, you must invoke
SMG$CREATE_PASTEBOARD to associate a pasteboard with the terminal.
SMG$CREATE_PASTEBOARD returns a pasteboard identification number; pass
that number to SMG$SET_BROADCAST_TRAPPING to identify the terminal in
question. Read the contents of the broadcast with
SMG$GET_BROADCAST_MESSAGE.
| Example 22-15 Trapping Broadcast Messages |
.
.
.
INTEGER*4 STATUS,
2 PBID, ! Pasteboard ID
2 VDID, ! Virtual display ID
2 SMG$CREATE_PASTEBOARD,
2 SMG$SET_BROADCAST_TRAPPING
2 SMG$PASTE_VIRTUAL_DISPLAY
COMMON /ID/ PBID,
2 VDID
INTEGER*2 B_STATUS (4)
INCLUDE '($SMGDEF)'
INCLUDE '($BRKDEF)'
EXTERNAL BRKTHRU_ROUTINE
STATUS = SMG$CREATE_PASTEBOARD (PBID)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
STATUS = SMG$CREATE_VIRTUAL_DISPLAY (3, ! Height
2 80, ! Width
2 VDID,, ! Display ID
2 SMG$M_REVERSE)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
STATUS = SMG$SET_BROADCAST_TRAPPING (PBID, ! Pasteboard ID
2 BRKTHRU_ROUTINE) ! AST
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
.
.
.
|
SUBROUTINE BRKTHRU_ROUTINE ()
INTEGER*4 STATUS,
2 PBID, ! Pasteboard ID
2 VDID, ! Virtual display ID
2 SMG$GET_BROADCAST_MESSAGE,
2 SMG$PUT_CHARS,
2 SMG$PASTE_VIRTUAL_DISPLAY
COMMON /ID/ PBID,
2 VDID
CHARACTER*240 MESSAGE
INTEGER*2 MESSAGE_SIZE
! Read the message
STATUS = SMG$GET_BROADCAST_MESSAGE (PBID,
2 MESSAGE,
2 MESSAGE_SIZE)
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
! Write the message to the virtual display
STATUS = SMG$PUT_CHARS (VDID,
2 MESSAGE (1:MESSAGE_SIZE),
2 1, ! Line
2 1) ! Column
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS))
! Make the display visble by pasting it to the pasteboard
STATUS = SMG$PASTE_VIRTUAL_DISPLAY (VDID,
2 PBID,
2 22, ! Row
2 1) ! Column
END
|
Chapter 23
System Service Input/Output Operations
This chapter describes how to use system services to perform input and
output operations. It contains the following sections:
Section 23.1 describes the QIO operation.
Section 23.2 describes the use of quotas, privileges, and protection.
Section 23.3 describes device addressing modes.
Section 23.4 describes I/O function encoding.
Section 23.5 describes how to assign channels.
Section 23.6 describes how to queue I/O requests.
Section 23.7 describes how to synchronize I/O completions.
Section 23.8 describes the routine to use to wait for completion of an
asynchronous event.
Section 23.9 describes executing I/O services synchronously or
asynchronously.
Section 23.10 describes the completion status of an I/O operation.
Section 23.11 describes how to deassign I/O channels.
Section 23.12 presents a program example of a complete input and output
operation.
Section 23.13 describes how to cancel I/O requests.
Section 23.14 describes how to use logical names and physical device
names for I/O operations.
Section 23.15 describes how to use device name defaults.
Section 23.16 describes how to obtain information about physical
devices.
Section 23.17 describes device allocation.
Section 23.18 describes how to mount, dismount, and initialize disk and
tape volumes.
Section 23.19 describes format output strings.
Section 23.20 describes how to use mailboxes for I/O operations.
Section 23.21 provides a program example of using I/O system services.
Section 23.22 describes the Fast I/O and Fast Path features that
improve I/O performance.
Examples are provided to show you how to use the I/O services for
simple functions, such as terminal input and output operations. If you
plan to write device-dependent I/O routines, see the OpenVMS I/O User's Reference Manual.
On VAX systems, if you want to write your own device driver or connect
to a device interrupt vector, see the OpenVMS VAX Device Support Reference Manual. The OpenVMS VAX Device Support Reference Manual
has been archived but is available on the OpenVMS Documentation CD-ROM.
Besides using I/O system services, you can use OpenVMS Record
Management Services (RMS). OpenVMS RMS provides a set of routines for
general-purpose, device-independent functions such as data storage,
retrieval, and modification.
Unlike RMS services, I/O system services permit you to use the I/O
resources of the operating system directly in a device-dependent
manner. I/O services also provide some specialized functions not
available in OpenVMS RMS. Using I/O services requires more programming
knowledge than using OpenVMS RMS, but can result in more efficient
input/output operations.
23.1 Overview of OpenVMS QIO Operations
The OpenVMS operating system provides QIO operations that perform three
basic I/O functions: read, write, and set mode. The read function
transfers data from a device to a user-specified buffer. The write
function transfers data in the opposite direction---from a
user-specified buffer to the device. For example, in a read QIO
function to a terminal device, a user-specified buffer is filled with
characters received from the terminal. In a write QIO function to the
terminal, the data in a user-specified buffer is transferred to the
terminal where it is displayed.
The set mode QIO function is used to control or describe the
characteristics and operation of a device. For example, a set mode QIO
function to a line printer can specify either uppercase or lowercase
character format. Not all QIO functions are applicable to all types of
devices. The line printer, for example, cannot perform a read QIO
function.
23.2 Quotas, Privileges, and Protection
To preserve the integrity of the operating system, the I/O operations
are performed under the constraints of quotas, privileges, and
protection.
Quotas limit the number and type of I/O operations that a process can
perform concurrently and the total size of outstanding transfers. They
ensure that all users have an equitable share of system resources and
usage.
Privileges are granted to a user to allow the performance of certain
I/O-related operations, for example, creating a mailbox and performing
logical I/O to a file-structured device. Restrictions on user
privileges protect the integrity and performance of both the operating
system and the services provided to other users.
Protection controls access to files and devices. Device protection is
provided in much the same way as file protection: shareable and
nonshareable devices are protected by protection masks.
The Set Resource Wait Mode (SYS$SETRWM) system service allows
a process to select either of two modes when an attempt to exceed a
quota occurs. In the enabled (default) mode, the process waits until
the required resource is available before continuing. In the disabled
mode, the process is notified immediately by a system service status
return that an attempt to exceed a quota has occurred. Waiting for
resources is transparent to the process when resource wait mode is
enabled; the process takes no explicit action when a wait is necessary.
The different types of I/O-related quotas, privilege, and protection
are described in the following sections.
23.2.1 Buffered I/O Quota
The buffered I/O limit quota (BIOLM) specifies the maximum number of
concurrent buffered I/O operations that can be active in a process. In
a buffered I/O operation, the user's data is buffered in system dynamic
memory. The driver deals with the system buffer and not the user
buffer. Buffered I/O is used for terminal, line printer, card reader,
network, mailbox, and console medium transfers and file system
operations. For a buffered I/O operation, the system does not have to
lock the user's buffer in memory.
The system manager, or the person who creates the process, establishes
the buffered I/O quota value in the user authorization file. If you use
the Set Resource Wait Mode (SYS$SETRWM) system service to enable
resource wait mode for the process, the process enters resource wait
mode if it attempts to exceed its direct I/O quota.
23.2.2 Buffered I/O Byte Count Quota
The buffered I/O byte count quota (BYTLM) specifies the maximum amount
of buffer space that can be consumed from system dynamic memory for
buffering I/O requests. All buffered I/O requests require system
dynamic memory in which the actual I/O operation takes place.
The system manager, or the person who creates the process, establishes
the buffered I/O byte count quota in the user authorization file. If
you use the SYS$SETRWM system service to enable resource wait mode for
the process, the process enters resource wait mode if it attempts to
exceed its direct I/O quota.
23.2.3 Direct I/O Quota
The direct I/O limit quota (DIOLM) specifies the maximum number of
concurrent direct (unbuffered) I/O operations that a process can have
active. In a direct I/O operation, data is moved directly to or from
the user buffer. Direct I/O is used for disk, magnetic tape, most
direct memory access (DMA) real-time devices, and nonnetwork transfers,
such as DMC11/DMR11 write transfers. For direct I/O, the user's buffer
must be locked in memory during the transfer.
The system manager, or the person who creates the process, establishes
the direct I/O quota value in the user authorization file. If you use
the SYS$SETRWM system service to enable resource wait mode for the
process, the process enters resource wait mode if it attempts to exceed
its direct I/O quota.
23.2.4 AST Quota
The AST quota specifies the maximum number of outstanding asynchronous
system traps that a process can have. The system manager, or the person
who creates the process, establishes the quota value in the user
authorization file. There is never an implied wait for that resource.
23.2.5 Physical I/O Privilege
Physical I/O privilege (PHY_IO) allows a process to perform physical
I/O operations on a device. Physical I/O privilege also allows a
process to perform logical I/O operations on a device.
23.2.6 Logical I/O Privilege
Logical I/O privilege (LOG_IO) allows a process to perform logical I/O
operations on a device. A process can also perform physical operations
on a device if the process has logical I/O privilege, the volume is
mounted foreign, and the volume
protection mask allows access to the device. (A foreign volume is one
volume that contains no standard file structure understood by any of
the operating system software.) See Section 23.3.2 for further
information about logical I/O privilege.
23.2.7 Mount Privilege
Mount privilege (MOUNT) allows a process to use the IO$_MOUNT function
to perform mount operations on disk and magnetic tape devices. The
IO$_MOUNT function is used in ancillary control processs (ACP)
interface operations.
23.2.8 Share Privilege
Share privilege (SHARE) allows a process to use the SYS$ASSIGN system
service to override another process's exclusive access request on the
specified device.
Performing any I/O operations to a device driver coded to expect
exclusive access---performing I/O to any device driver not explicitly
coded to expect shared multiple-process access---can result in unusual
and unexpected device and application behaviour, and can result in
problems of device ownership, and failures during the device driver
last channel deassign operation.
Using SHARE to override access is useful for a few specific situations,
such as user-written device driver debugging and user-written device
driver diagnostic tools. General use of SHARE is not recommended.
23.2.9 Volume Protection
Volume protection protects the integrity of mailboxes and both foreign
and Files-11 On-Disk Structure Level 2 structured volumes. Volume
protection for a foreign volume is established when the volume is
mounted. Volume protection for a Files-11 structured volume is
established when the volume is initialized. (If the process mounting
the volume has the override volume protection privilege, VOLPRO,
protection can be overridden when the volume is mounted.)
The SYS$CREMBX system service protection mask argument establishes
mailbox protection.
Set Protection QIO requests allow you to set volume protection on a
mailbox. You must either be the owner of the mailbox or have the BYPASS
privilege.
Protection for structured volumes and mailboxes is provided by a volume
protection mask
that contains four 4-bit fields. These fields correspond to the four
classes of user permitted to access the volume. (User classes are based
on the volume owner's UIC.)
The 4-bit fields are interpreted differently for volumes that are
mounted as structured (that is, volumes serviced by an ACP), volumes
that are mounted as foreign, and mailboxes (both temporary and
permanent).
Figure 23-1 shows the 4-bit protection fields for mailboxes.
Usually, volume protection is meaningful only for read and write
operations.
Figure 23-1 Mailbox Protection Fields
23.2.10 Device Protection
Device protection protects the allocation of nonshareable devices, such
as terminals and card readers.
Protection is provided by a device protection mask similar to that of
volume protection. The difference is that only the bit corresponding to
read access is checked, and that bit determines whether the process can
allocate or assign a channel to the device.
You establish device protection with the DCL command SET
PROTECTION/DEVICE. This command sets both the protection mask and the
device owner UIC.
23.2.11 System Privilege
System UIC privilege (SYSPRV) allows a process to be eligible for the
volume or device protection specified for the system protection class,
even if the process does not have a UIC in one of the system groups.
23.2.12 Bypass Privilege
Bypass privilege (BYPASS) allows a process to bypass volume and device
protection completely.
23.3 Physical, Logical, and Virtual I/O
I/O data transfers can occur in any one of three device addressing
modes: physical, logical, or virtual. Any process with device access
allowed by the volume protection mask can perform logical I/O on a
device that is mounted foreign; physical I/O requires privileges.
Virtual I/O does not require privileges; however, intervention by an
ACP to control user access might be necessary if the device is under
ACP control. (ACP functions are described in the OpenVMS I/O User's Reference Manual.)
23.3.1 Physical I/O Operations
In physical I/O operations, data is read from and written to the
actual, physically addressable units accepted by the hardware (for
example, sectors on a disk or binary characters on a terminal in the
PASSALL mode). This mode allows direct access to all device-level I/O
operations.
Physical I/O requires that one of the following conditions be met:
- The issuing process has physical I/O privilege (PHY_IO).
- The issuing process has all of the following characteristics:
- The issuing process has logical I/O privilege (LOG_IO).
- The device is mounted foreign.
- The volume protection mask allows physical access to the device.
If neither of these conditions is met, the physical I/O operation is
rejected by the SYS$QIO system service, which returns a condition value
of SS$_NOPRIV (no privilege). Figure 23-2 illustrates the physical
I/O access checks in greater detail.
The inhibit error-logging function modifier (IO$M_INHERLOG) can be
specified for all physical I/O functions. The IO$M_INHERLOG function
modifier inhibits the logging of any error that occurs during the I/O
operation.
