OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

To specify INIT$_OVR_EXP, the caller must either own the volume or have VOLPRO privilege.

INIT$_OVR_VOLO

INIT$_NO_OVR_VOLO---Default

A Boolean item code that allows the caller to override processing of the owner identifier field of the ANSI volume label VOL1 on an ANSI magnetic tape.

To specify INIT$_OVR_VOLO, the caller must either own the volume or have VOLPRO privilege.

INIT$_OWNER

An input item code that specifies the UIC that will own the volume. The input buffer must contain a longword value, which is the UIC. The default is the UIC of the caller.

For magnetic tapes, no UIC is written unless protection on the magnetic tape is specified. If the INIT$_VPROT item code is specified but the INIT$_OWNER item code is not specified, the UIC of the caller is assigned ownership of the volume.

INIT$_READCHECK

INIT$_NO_READCHECK---Default

A Boolean item code that specifies whether data checking should be performed for all read operations on the volume. For more information about data checking, see the OpenVMS I/O User's Reference Manual.

The INIT$_READCHECK item code applies only to disks.

INIT$_SIZE

An input item code that specifies the number of blocks allocated for a RAM disk with a device type of DT$_RAM_DISK. The input buffer must contain a longword value.

INIT$_STRUCTURE_LEVEL_1

INIT$_STRUCTURE_LEVEL_2---Default

Symbolic item codes that specify whether the volume should be formatted in Files-11 On-Disk Structure Level 1 or Structure Level 2. Structure Level 1 is incompatible with the following item codes:

INIT$_READCHECK
INIT$_WRITECHECK
INIT$_CLUSTERSIZE

The default protection for a Structure Level 1 disk is full access to system, owner, and group users, and read access to all other users.

The INIT$_STRUCTURE_LEVEL_1 item code applies only to disks.

INIT$_USER_NAME

An input item code that specifies the user name that is associated with the volume. The input buffer must contain a character string from 1 to 12 alphanumeric characters, which is the user name. The default is the user name of the caller.

INIT$_VERIFIED

INIT$_NO_VERIFIED

A Boolean item code that indicates whether the disk contains bad block data. INIT$_NO_VERIFIED indicates that any bad block data on the disk should be ignored. For disks with 4096 blocks or more, the default is INIT$_VERIFIED.

INIT$_NO_VERIFIED is the default for the following:

Disks with fewer than 4096 blocks
DIGITAL Storage Architecture (DSA) devices
Disks that are not last-track devices

The INIT$_VERIFIED item codes apply only to disks.

INIT$_VPROT

An input item code that specifies the protection assigned to the volume. The input buffer must contain a longword protection mask that contains four 4-bit fields. Each field grants or denies read, write, create, and delete access to a category of users. Cleared bits grant access; set bits deny access. The following diagram depicts the structure of the protection mask.

The default is the default protection of the caller.

For magnetic tape, the protection code is written to a specific volume label. The system applies only read and write access restrictions; execute and delete access are ignored. Moreover, the system and the owner are always given read and write access to magnetic tapes, regardless of the protection mask specified.

When you specify a protection mask for a disk volume, access type E (execute) indicates create access.

For Files-11 On-Disk Structure Level 2 volumes, an initial security profile is created from the VOLUME.DEFAULT profile, with the owner and protection as currently defined for INITIALIZE.

You can use the $SET_SECURITY service to modify the security profile after the volume is initialized and mounted.

The caller needs read, write, or control access to the device.

INIT$_WINDOW

The INIT$_WINDOW item code specifies the number of mapping pointers to be allocated for file windows. The input buffer must contain a longword value in the range 7 to 80. The default is 7.

When a file is opened, the file system uses the mapping pointers to access the data in the file.

The INIT$_WINDOW item code applies only to disks.

INIT$_WRITECHECK

INIT$_NO_WRITECHECK---Default

The INIT$_WRITECHECK item code applies only to disks.

Description

The Initialize Volume system service formats a disk or magnetic tape volume and writes a label on the volume. At the end of initialization, the disk is empty except for the system files containing the structure information. All former contents of the volume are lost.
A blank magnetic tape can sometimes cause unrecoverable errors when it is read. $INIT_VOL attempts to read the volume unless the following three conditions are in effect:

INIT$_OVR_ACCESS Boolean item code is specified.
INIT$_OVR_EXP Boolean item code is specified.
Caller has VOLPRO privilege.
If the caller has VOLPRO privilege, $INIT_VOL initializes a disk without reading the ownership information. Otherwise, the ownership of the volume is checked.

A blank disk or a diskette with an incorrect format can sometimes cause a fatal drive error. Such a diskette can be initialized successfully by specifying the INIT$_DENSITY item code to format the diskette.
Required Access or Privileges

To initialize a particular volume, the caller must either have volume protection (VOLPRO) privilege or the volume must be one of the following:

Blank disk or magnetic tape; that is, a volume that has never been written
Disk that is owned by the caller's UIC or by the UIC [0,0]
Magnetic tape that allows write access to the caller's UIC or that was not protected when it was initialized

Required Quota

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_FASTPATH (Alpha Only)

Provides the ability to control the set of Fast Path devices and their assignment to CPUs enabled for Fast Path use.

Format

SYS$IO_FASTPATH efn ,cpu_mask ,function_code

C Prototype:

int sys$io_fastpath (unsigned int efn, UINT32_PQ cpu_mask, unsigned int function_code);

Arguments

efn

OpenVMS usage: integer

type: longword bit mask (unsigned)

access: read

mechanism: by value

Number of the event flag to be set when the IO_FASTPATH(W) operation completes. The efn argument is a longword containing the number of the event flag.
cpu_mask

OpenVMS usage: integer

type: longword bit mask (unsigned)

access: read

mechanism: by 32- or 64-bit reference

The cpu_mask argument specifies a set of CPUs to be operated upon.
function_code

OpenVMS usage: integer

type: longword (unsigned)

access: read

mechanism: by value

The function_code specifies the operation to be performed. Must be one of the following:
FP$K_BALANCE_PORTS - Distribute Fast Path ports across CPUs.
Note that there is currently only one function code.

Description

The $IO_FASTPATH system service performs operations on the set of Fast Path devices and CPUs enabled for Fast Path use. The $IO_FASTPATHW system service completes synchronously. That is, it returns after the operation is complete.
The FP$K_BALANCE_PORTS function code specifies that the system service is to distribute the set of system assignable Fast Path ports across the intersection of a caller-supplied set of candidate CPUs (cpu_mask) and the current set of usable CPUs. Usable CPUs are the intersection of the set of CPUs both enabled for Fast Path use by IO$_PREFERRED_CPUS and whose current state is RUN.
The service does this by:

Eliminating all CPUs not in the set of usable CPUs from the set of candidate CPUs.
Restoring any user assigned ports that aren't currently on the user's preferred CPU to the user's preferred CPU, if that CPU is in the set of usable CPUs.
Spreading the system assignable Fast Path ports, and any Fast Path ports whose user preferred CPU is unavailable, evenly across the set of usable candidate CPUs.
If the primary CPU is in the set of usable candidate CPUs, the distribution will be biased against the primary CPU in that a port will only be assigned to the primary after ports have been assigned to each of the other usable candidate CPUs.

Required Access or Privileges

PHYS_IO
Required Quota

None.
Related Services

$GETDVI, $QIO

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADPARAM Unsupported value for cpu_mask.

SS$_ILLIOFUNC Illegal function code.

$IO_FASTPATHW (Alpha Only)

Performs operations on the set of Fast Path devices and CPUs enabled for Fast Path use.
The $IO_FASTPATHW system service is functionally equivalent to the $IO_FASTPATH service except that it completes synchronously. That is, it returns after the operation is complete.

Format

SYS$IO_FASTPATHW efn ,cpu_mask ,function_code

C Prototype:

int sys$io_fastpathw (unsigned int efn, UINT32_PQ cpu_mask, unsigned int function_code);

$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.

Contents

Index

Legal

 
4527PRO_062.HTML

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:	integer
type:	longword bit mask (unsigned)
access:	read
mechanism:	by value

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.