OpenVMS System Services Reference Manual

None

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC, $DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI, $GETQUIW, $MOUNT, $PUTMSG, $QIO, $QIOW, $SET_SECURITY, $SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The item list or an address specified in the item list cannot be accessed.

SS$_BADPARAM A buffer length of 0 was specified with a nonzero item code or an illegal item code was specified.

SS$_IVSSRQ A concurrent call to SYS$INIT_VOL is already active for the process.

SS$_NOPRIV The caller does not have sufficient privilege to initialize the volume.

SS$_NOSUCHDEV The specified device does not exist on the host system.

The$INIT_VOL service can also return the following condition values, which are specific to the Initialize Volume utility:

INIT$_ALLOCFAIL Index file allocation failure.

INIT$_BADACCESSED Value for INIT$_ACCESSED item code out of range.

INIT$_BADBLOCKS Invalid syntax in bad block list.

INIT$_BADCLUSTER Value for INIT$_CLUSTER_SIZE item code out of range.

INIT$_BADDENS Invalid value for INIT$_DENSITY item code.

INIT$_BADDIRECTORIES Value for INIT$_DIRECTORIES item code out of range.

INIT$_BADEXTENSION Value for INIT$_EXTENSION item code out of range.

INIT$_BADHEADERS Value for INIT$_HEADER item code out of range.

INIT$_BADMAXFILES Value for INIT$_MAXFILES item code out of range.

INIT$_BADOWNID Invalid value for owner ID.

INIT$_BADRANGE Bad block address not on volume.

INIT$_BADVOL1 Bad VOL1 ANSI label.

INIT$_BADVOLACC Invalid value for INIT$_LABEL_ACCESS item code.

INIT$_BADVOLLBL Invalid value for ANSI tape volume label.

INIT$_BADWINDOWS Value for INIT$_WINDOWS item code out of range.

INIT$_BLKZERO Block 0 is bad---volume not bootable.

INIT$_CLUSTER Unsuitable cluster factor.

INIT$_CONFQUAL Conflicting options were specified.

INIT$_DIAGPACK Disk is a diagnostic pack.

INIT$_ERASEFAIL Volume not completely erased.

INIT$_FACTBAD Cannot read factory bad block data.

INIT$_ILLOPT Item codes not appropriate for the device were specified.

INIT$_INDEX Invalid index file position.

INIT$_LARGECNT Disk too large to be supported.

INIT$_MAXBAD Bad block table overflow.

INIT$_MTLBLLONG Magnetic tape label specified is longer than 6 characters.

INIT$_MTLBLNONA Magnetic tape label specified contains non-ANSI "a" characters.

INIT$_NOBADDATA Bad block data not found on volume.

INIT$_NONLOCAL Device is not a local device.

INIT$_NOTRAN Logical name cannot be translated.

INIT$_NOTSTRUC1 Options not available with Files-11 On-Disk Structure Level 1.

INIT$_UNKDEV Unknown device type.

$IO_CLEANUP (Alpha Only)

On Alpha systems, returns all resources allocated by $IO_SETUP.
This service accepts 64-bit addresses.

Format

SYS$IO_CLEANUP fandle

C Prototype

int sys$io_cleanup (unsigned __int64 fandl);

ARGUMENTS

fandle

OpenVMS usage: fandle

type: 64-bit integer (unsigned)

access: read only

mechanism: by value

A fandle, passed by value, returned by a previous call to $IO_SETUP.

DESCRIPTION

The Clean Up Fast I/O system service returns various internal resources allocated by the $IO_SETUP system service. Buffer objects passed to $IO_SETUP cannot be deleted until every $IO_SETUP call has had a corresponding $IO_CLEANUP call.
Image rundown executes any required $IO_CLEANUP operations on behalf of the process.
Required Privileges

None
Required Quota

None
Related Services

$IO_PERFORM(W), $IO_SETUP

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADFANDLE Argument was not a valid fandle.

SS$_BUSY The fandle cannot be cleaned up because an I/O is in progress. Reissue the call to $IO_CLEANUP after the I/O has finished.

$IO_PERFORM (Alpha Only)

On Alpha systems, starts the Fast I/O operation. The $IO_PERFORM service completes asynchronously. For synchronous completion, use the Perform Fast I/O and Wait ($IO_PERFORMW) service.
This service accepts 64-bit addresses.

Format

SYS$IO_PERFORM fandle ,chan ,iosadr ,bufadr ,buflen ,porint

C Prototype

int sys$io_perform (unsigned __int64 fandl, unsigned short int chan, struct _iosa *iosadr, void *bufadr, unsigned __int64 buflen, unsigned __int64 devdata);

ARGUMENTS

fandle

OpenVMS usage: fandle

type: 64-bit integer (unsigned)

access: read only

mechanism: by value

A fandle returned by a previous call to $IO_SETUP.
chan

OpenVMS usage: channel

type: word (unsigned)

access: read

mechanism: by value

Software I/O channel number.
iosadr

OpenVMS usage: address

type: address

access: read only

mechanism: by value

Address of the I/O Status Area (IOSA). This value cannot be 0; that is, an IOSA is required. The iosadr must be aligned to a quadword boundary.
bufadr

OpenVMS usage: char_string

type: address

access: read only

mechanism: by value

The process buffer address. Must be aligned on a 512-byte boundary.
buflen

OpenVMS usage: byte count

type: 64-bit integer

access: read only

mechanism: by value

The byte count for the I/O. The buflen argument must be a multiple of 512 bytes. Drivers have further limitations on the maximum size of an I/O request.
porint

OpenVMS usage: address

type: pointer or integer

access: read only

mechanism: by value

A hardware integer passed unchanged to the driver. For disk devices, this is the media address for the transfer; that is, the virtual block number (VBN) for virtual I/O functions or the logical block number (LBN) for logical I/O functions. This argument is ignored for tape devices.
For drivers with complex parameters, porint would be the address of a descriptor or buffer specific to the device and function and would be documented with the driver.

DESCRIPTION

The Perform Fast I/O system service initiates an I/O operation on the channel number specified by the chan argument. The bytes specified by the buflen argument are transferred between the location (porint) on the device driver and the user's buffer starting at the process buffer address (bufadr). The byte count is read or written according to the function code previously specified in the $IO_SETUP call associated with the fandle argument.
Upon completion, the I/O status is written to the IOSA starting at the location specified by iosadr, and an AST is delivered to the astadr address supplied in the $IO_SETUP call associated with fandle. The IOSA address is passed to the AST as the AST parameter.
Required Privileges

None
Required Quota

None
Related Services

$IO_CLEANUP, $IO_SETUP, $IO_PERFORMW

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADBUFADR The data buffer does not reside within the bounds of the data buffer object for the fandle.

SS$_BADIOSADR The IOSA does not reside within the bounds of the IOSA buffer object for this fandle.

SS$_FANDLEBUSY The operation using this fandle is already in progress.

SS$_IVCHAN An invalid channel number was specified; that is, a channel number of 0 or a number larger than the number of channels available.

SS$_UNALIGNED The buffer specified by bufadr or iosadr is not properly aligned.

SS$_WRONGACMODE The request is invalid because the fandle was created from a more privileged access mode, or the channel was assigned from a more privileged access mode.

Condition Values Returned in the I/O Status Block

The OpenVMS I/O User's Reference Manual lists these device-specific condition values for each device.

$IO_PERFORMW (Alpha Only)

On Alpha systems, starts a Fast I/O operation. The $IO_PERFORMW service completes synchronously; that is, it returns to the caller after performing the Fast I/O operation.
In all other respects, $IO_PERFORMW is identical to $IO_PERFORM. For all other information about the IO_PERFORMW service, refer to the description of $IO_PERFORM in this manual.

Format

SYS$IO_PERFORMW fandle ,chan ,iosadr ,bufadr ,buflen ,porint

C Prototype

int sys$io_performw (unsigned __int64 fandl, unsigned short int chan, struct _iosa *iosadr, void *bufadr, unsigned __int64 buflen, unsigned __int64 devdata);

$IO_SETUP (Alpha Only)

On Alpha systems, allocates resources for Fast I/O.
This service accepts 64-bit addresses.

Format

SYS$IO_SETUP func ,bufobj ,iosobj ,astadr ,flags ,return_fandle

C Prototype

int sys$io_setup (unsigned int func, struct _generic_64 *bufobj, struct _generic_64 *iosobj, void (*astadr)(struct _iosa *), unsigned int flags, unsigned __int64 *return_fandle);

ARGUMENTS

func

OpenVMS usage: function_code

type: longword

access: read only

mechanism: by value

I/O function code. Must be one of the following:

IO$_READVBLK
IO$_WRITEVBLK
IO$_READLBLK
IO$_WRITELBLK

Various function modifiers are supported, depending on the device and driver. Disk drivers support IO$M_NOVCACHE and IO$M_DATACHECK. Some tape devices support IO$M_REVERSE. Illegal modifiers are detected by the $IO_PERFORM(W) service.
bufobj

OpenVMS usage: buffer object

type: vector longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Handle describing the buffer object that contains the user's buffer. This identifier cannot be 0.
iosobj

OpenVMS usage: object handle

type: vector longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Buffer object handle describing the buffer object that contains the I/O Status Area (IOSA). This might or might not be the same identifier as the bufobj argument. This identifier cannot be 0.
astadr

OpenVMS usage: ast_procedure

type: procedure value

access: read only

mechanism: by 32- or 64-bit reference

Completion AST routine address (0, if none). There is no AST parameter argument. When the AST routine is called, the AST parameter will be the address of the IOSA for the operation. Applications can store data in the IOSA at offset IOSA$IH_CONTEXT.
flags

OpenVMS usage: mask_longword

type: 64-bit integer (unsigned)

access: read only

mechanism: by value

Flag mask. The flags argument is a bit vector in which each bit corresponds to a flag. Flags are defined in the module IOSADEF. The following table describes the flags that are valid for the $IO_SETUP service:

Flag Description

FIO$M_EXPEDITE This is a high priority I/O; that is, it is to be given preferential treatment by the I/O subsystem. Use of this bit requires ALTPRI or PHY_IO privilege.

FIO$M_AST_NOFLOAT The AST procedure does not use, or call any procedure that uses, any floating-point registers. This is a performance option. If set, AST delivery will neither save nor restore floating-point registers. Caution: Use of floating-point registers when FIO$M_AST_NOFLOAT has been specified can cause unpredictable, difficult to detect, error conditions.

All other bits in the flags argument are reserved for future use by Digital and should be specified as 0.
return_fandle

OpenVMS usage: fandle

type: 64-bit integer (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

Address of an aligned quadword to receive the fandle for this I/O operation.

Flag	Description
FIO$M_EXPEDITE	This is a high priority I/O; that is, it is to be given preferential treatment by the I/O subsystem. Use of this bit requires ALTPRI or PHY_IO privilege.
FIO$M_AST_NOFLOAT	The AST procedure does not use, or call any procedure that uses, any floating-point registers. This is a performance option. If set, AST delivery will neither save nor restore floating-point registers. Caution: Use of floating-point registers when FIO$M_AST_NOFLOAT has been specified can cause unpredictable, difficult to detect, error conditions.

DESCRIPTION

The Set Up Fast I/O system service allocates and initializes a number of internal objects based on the parameters supplied. Because these objects are then ready for use when a subsequent $IO_PERFORM or $IO_PERFORMW is issued, the I/O operation will require less CPU time and fewer multiprocessor steps.
Required Privileges

If you use the flags argument FIO$M_EXPEDITE, a process must have ALTPRI or PHY_IO privilege.
Required Quota

Byte count
Related Services

$IO_CLEANUP, $IO_PERFORM(W)

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The fandle does not have 8 bytes of writability, or the two buffer objects do not have 8 bytes of readability each.

SS$_INSFMEM There is no pool available from which to create a fandle vector, or the fandle vector is already full and an attempted expansion failed.

SS$_ILLIOFUNC The function code is not valid.

SS$_ILLMODIFIER The I/O function modifier is not permitted.

SS$_UNALIGNED The I/O Status Area (IOSA) or data buffer is not aligned on a quadword boundary.

$LCKPAG

Locks a page or range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and in this sense are locked in the working set as well.

Format

SYS$LCKPAG inadr ,[retadr] ,[acmode]

C Prototype

int sys$lckpag (struct _va_range *inadr, struct _va_range *retadr, unsigned int acmode);

ARGUMENTS

inadr

OpenVMS usage: address_range

type: longword (unsigned)

access: read only

mechanism: by reference

Starting and ending virtual addresses of the range of pages to be locked. The inadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses. Only the virtual page number portion of each virtual address is used; the low-order byte-within-page bits are ignored.
On VAX systems, if the starting and ending virtual addresses are the same, a single page is locked.
retadr

OpenVMS usage: address_range

type: longword (unsigned)

access: write only

mechanism: by reference

Starting and ending process virtual addresses of the pages that $LCKPAG actually locked. The retadr argument is the address of a 2-longword array containing, in order, the starting and ending process virtual addresses.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode to be associated with the pages to be locked. The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the four access modes.
The most privileged access mode used is the access mode of the caller. For the $LCKPAG service to complete successfully, the resultant access mode must be equal to or more privileged than the access mode already associated with the pages to be locked.

DESCRIPTION

The Lock Pages in Memory service locks a page or range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and in this sense are locked in the working set as well.
If more than one page is being locked and you need to determine specifically which pages were previously locked, the pages should be locked one at a time.
If an error occurs while the $LCKPAG service is locking pages, the return array, if requested, indicates the pages that were successfully locked before the error occurred. If no pages are locked, both longwords in the return address array contain the value --1.
On Alpha systems, if you are attempting to lock executable code, you should issue multiple $LCKPAG calls: one to lock the code pages and others to lock the linkage section references into these pages.
Required Access or Privileges

The calling process must have PSWAPM privilege to lock pages into memory.
Required Quota

None
Related Services

You can unlock pages locked in memory with the Unlock Pages from Memory ($ULKPAG) service. Locked pages are automatically unlocked at image exit.
For more information, see the chapter on memory management in the OpenVMS Programming Concepts Manual.

Condition Values Returned

SS$_WASCLR The service completed successfully. All of the specified pages were previously unlocked.

SS$_WASSET The service completed successfully. At least one of the specified pages was previously locked.

SS$_ACCVIO The input array cannot be read; the output array cannot be written; the page in the specified range is inaccessible or nonexistent; or an attempt to lock pages was made by a caller whose access mode is less privileged than the access mode associated with the pages.

SS$_LCKPAGFUL The system-defined maximum limit on the number of pages that can be locked in memory has been reached.

SS$_LDWSETFUL The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.

SS$_NOPRIV The process does not have the privilege to lock pages in memory.

SS$_PAGOWNVIO The pages could not be locked because the access mode associated with the call to $LCKPAG was less privileged than the access mode associated with the pages that were to be locked.

$LCKPAG_64 (Alpha Only)

On Alpha systems, locks a range of pages in memory. The specified virtual pages are forced into the working set and then locked in memory. A locked page is not swapped out of memory if the working set of the process is swapped out. These pages are not candidates for page replacement and, in this sense, are locked in the working set as well.
This service accepts 64-bit addresses.

Format

SYS$LCKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64 ,return_length_64

C Prototype

int sys$lckpag_64 (void *start_va_64, unsigned __int64 length_64, unsigned int acmode, void *(*(return_va_64)), unsigned __int64 *return_length_64);

ARGUMENTS

start_va_64

OpenVMS usage: address

type: quadword address

access: read only

mechanism: by value

The starting virtual address of the pages to be locked. The specified virtual address will be rounded down to a CPU-specific page boundary.
length_64

OpenVMS usage: byte count

type: quadword (unsigned)

access: read only

mechanism: by value

Length of the virtual address space to be locked. The specified length will be rounded up to a CPU-specific page boundary so that it includes all CPU-specific pages in the requested range.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode associated with the pages to be locked. The acmode argument is a longword containing the access mode.
The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H in SYS$STARLET_C.TLB define the following symbols and their values for the four access modes:

Value Symbolic Name Access Mode

0 PSL$C_KERNEL Kernel

1 PSL$C_EXEC Executive

2 PSL$C_SUPER Supervisor

3 PSL$C_USER User

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P052.HTM
  OSSG Documentation
  22-NOV-1996 13:00:08.17
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list or an address specified in the item list cannot be accessed.
SS$_BADPARAM	A buffer length of 0 was specified with a nonzero item code or an illegal item code was specified.
SS$_IVSSRQ	A concurrent call to SYS$INIT_VOL is already active for the process.
SS$_NOPRIV	The caller does not have sufficient privilege to initialize the volume.
SS$_NOSUCHDEV	The specified device does not exist on the host system.

The$INIT_VOL service can also return the following condition values, which are specific to the Initialize Volume utility:
INIT$_ALLOCFAIL	Index file allocation failure.
INIT$_BADACCESSED	Value for INIT$_ACCESSED item code out of range.
INIT$_BADBLOCKS	Invalid syntax in bad block list.
INIT$_BADCLUSTER	Value for INIT$_CLUSTER_SIZE item code out of range.
INIT$_BADDENS	Invalid value for INIT$_DENSITY item code.
INIT$_BADDIRECTORIES	Value for INIT$_DIRECTORIES item code out of range.
INIT$_BADEXTENSION	Value for INIT$_EXTENSION item code out of range.
INIT$_BADHEADERS	Value for INIT$_HEADER item code out of range.
INIT$_BADMAXFILES	Value for INIT$_MAXFILES item code out of range.
INIT$_BADOWNID	Invalid value for owner ID.
INIT$_BADRANGE	Bad block address not on volume.
INIT$_BADVOL1	Bad VOL1 ANSI label.
INIT$_BADVOLACC	Invalid value for INIT$_LABEL_ACCESS item code.
INIT$_BADVOLLBL	Invalid value for ANSI tape volume label.
INIT$_BADWINDOWS	Value for INIT$_WINDOWS item code out of range.
INIT$_BLKZERO	Block 0 is bad---volume not bootable.
INIT$_CLUSTER	Unsuitable cluster factor.
INIT$_CONFQUAL	Conflicting options were specified.
INIT$_DIAGPACK	Disk is a diagnostic pack.
INIT$_ERASEFAIL	Volume not completely erased.
INIT$_FACTBAD	Cannot read factory bad block data.
INIT$_ILLOPT	Item codes not appropriate for the device were specified.
INIT$_INDEX	Invalid index file position.
INIT$_LARGECNT	Disk too large to be supported.
INIT$_MAXBAD	Bad block table overflow.
INIT$_MTLBLLONG	Magnetic tape label specified is longer than 6 characters.
INIT$_MTLBLNONA	Magnetic tape label specified contains non-ANSI "a" characters.
INIT$_NOBADDATA	Bad block data not found on volume.
INIT$_NONLOCAL	Device is not a local device.
INIT$_NOTRAN	Logical name cannot be translated.
INIT$_NOTSTRUC1	Options not available with Files-11 On-Disk Structure Level 1.
INIT$_UNKDEV	Unknown device type.

OpenVMS usage:	fandle
type:	64-bit integer (unsigned)
access:	read only
mechanism:	by value

SS$_NORMAL	The service completed successfully.
SS$_BADFANDLE	Argument was not a valid fandle.
SS$_BUSY	The fandle cannot be cleaned up because an I/O is in progress. Reissue the call to $IO_CLEANUP after the I/O has finished.

OpenVMS usage:	channel
type:	word (unsigned)
access:	read
mechanism:	by value

OpenVMS usage:	address
type:	address
access:	read only
mechanism:	by value

OpenVMS usage:	char_string
type:	address
access:	read only
mechanism:	by value

OpenVMS usage:	byte count
type:	64-bit integer
access:	read only
mechanism:	by value

SS$_NORMAL	The service completed successfully.
SS$_BADBUFADR	The data buffer does not reside within the bounds of the data buffer object for the fandle.
SS$_BADIOSADR	The IOSA does not reside within the bounds of the IOSA buffer object for this fandle.
SS$_FANDLEBUSY	The operation using this fandle is already in progress.
SS$_IVCHAN	An invalid channel number was specified; that is, a channel number of 0 or a number larger than the number of channels available.
SS$_UNALIGNED	The buffer specified by bufadr or iosadr is not properly aligned.
SS$_WRONGACMODE	The request is invalid because the fandle was created from a more privileged access mode, or the channel was assigned from a more privileged access mode.

OpenVMS usage:	function_code
type:	longword
access:	read only
mechanism:	by value

OpenVMS usage:	buffer object
type:	vector longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	object handle
type:	vector longword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	ast_procedure
type:	procedure value
access:	read only
mechanism:	by 32- or 64-bit reference

OpenVMS usage:	mask_longword
type:	64-bit integer (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

SS$_WASCLR	The service completed successfully. All of the specified pages were previously unlocked.
SS$_WASSET	The service completed successfully. At least one of the specified pages was previously locked.
SS$_ACCVIO	The input array cannot be read; the output array cannot be written; the page in the specified range is inaccessible or nonexistent; or an attempt to lock pages was made by a caller whose access mode is less privileged than the access mode associated with the pages.
SS$_LCKPAGFUL	The system-defined maximum limit on the number of pages that can be locked in memory has been reached.
SS$_LDWSETFUL	The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
SS$_NOPRIV	The process does not have the privilege to lock pages in memory.
SS$_PAGOWNVIO	The pages could not be locked because the access mode associated with the call to $LCKPAG was less privileged than the access mode associated with the pages that were to be locked.

Value	Symbolic Name	Access Mode
0	PSL$C_KERNEL	Kernel
1	PSL$C_EXEC	Executive
2	PSL$C_SUPER	Supervisor
3	PSL$C_USER	User