HP OpenVMS Systems Documentation

On Alpha systems, modifies the software IEEE floating-point controlregister and, optionally, returns the previous register value.

The service provides the mechanism to set the specified bits in theIEEE floating-point control register, to clear the specified bits inthe register, and to swap the values of the register.

Format

SYS$IEEE_SET_FP_CONTROL [clrmsk] ,[setmsk] ,[prvmsk]

C Prototype

int sys$ieee_set_fp_control (struct _ieee *clrmsk, struct _ieee*setmsk, struct _ieee *prvmsk);

Arguments

clrmsk

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Address of a quadword bit mask to be cleared in the IEEE floating-pointcontrol register.

The $IEEEDEF macro defines symbols for the floating-point controlregister. Table SYS-46 shows the symbols, their corresponding masks,and their meaning:

Table SYS-46 Format of the IEEE Floating-Point Control Register (Alpha Only)

Symbol	Mask	Meaning
IEEE$M_TRAP_ENABLE_INV	2	Invalid operation
IEEE$M_TRAP_ENABLE_DZE	4	Divide by 0
IEEE$M_TRAP_ENABLE_OVF	8	Overflow
IEEE$M_TRAP_ENABLE_UNF	10	Underflow
IEEE$M_TRAP_ENABLE_INE	20	Inexact
IEEE$M_MAP_UMZ	4000	Underflows are mapped to 0.0
IEEE$M_INHERIT	8000	Inherit FP state on thread create
IEEE$M_STATUS_INV	20000	Invalid operation
IEEE$M_STATUS_DZE	40000	Divide by 0
IEEE$M_STATUS_OVF	80000	Overflow
IEEE$M_STATUS_UNF	100000	Underflow
IEEE$M_STATUS_INE	200000	Inexact

setmsk

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Address of a quadword bit mask to be set in the IEEE floating-pointcontrol register.

Table SYS-46 shows the format of the IEEE floating-point controlregister.

prvmsk

OpenVMS usage:	mask_quadword
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

Address of a quadword to receive the previous value of the IEEEfloating-point control register.

Description

The Set IEEE Floating-Point Control Register service updates the IEEEfloating-point control register, maintained by the operating system,with the values supplied by the calling program.

The following steps are used to update the register:

1. If the prvmsk argument is specified, $IEEE_SET_FP_CONTROL first reads the previous value of the IEEE floating-point control register.
2. If the clrmsk argument is specified, $IEEE_SET_FP_CONTROL then clears the specified bit masks in the clrmsk argument.
3. If the setmsk argument is specified, $IEEE_SET_FP_CONTROL then sets the specified bit masks in the setmsk argument.

A program can swap the IEEE floating-point control register (that is,save the old value and specify a new value) by specifying the following:

• The clrmsk argument with the address of a quadword of all 1s
• The setmsk argument with the address of a quadword that holds the new register value
• The prvmsk argument with the address of a quadword to save the old register value

Required Access or Privilege

None

Required Quota

None

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The specified argument cannot be read or cannot be written.

On Alpha systems, initializes system process alignment fault reporting.

This service accepts 64-bit addresses.

Format

SYS$INIT_SYS_ALIGN_FAULT_REPORT match_table ,buffer_size ,flags

C Prototype

int sys$init_sys_align_fault_report (void *match_table, intbuffer_size, unsigned int flags);

Arguments

match_table

OpenVMS usage:	address
type:	longword (unsigned)
access:	read
mechanism:	by 32-bit or 64-bit reference

Describes the system fault match table. Thematch_table argument is the 32-bit or 64-bit virtualaddress of an array of longwords describing the system fault matchtable. The first longword is the number of match entries; the remaininglongwords are the match entries.

The match table is used to restrict the number of alignment faultsreported. Each entry in the table is a bit mask divided into threegroups: mode bits, program counter (PC) space bits, and virtual address(VA) space bits.

The following table lists the symbols that can be used to define thesebits:

Bit Type	Symbols
Mode bits	AME$M_KERNEL_MODE	Kernel mode
	AME$M_EXEC_MODE	Executive mode
	AME$M_SUPER_MODE	Supervisor mode
	AME$M_USER_MODE	User mode
Program counter bits	AME$M_USER_PC	PC in User space
	AME$M_SYSTEM_PC	PC in System space
Virtual address bits	AME$M_SYSTEM_VA	VA in System space
	AME$M_USER_VA_P0	VA in User P0 space
	AME$M_USER_VA_P1	VA in User P1 space
	AME$M_USER_VA_P2	VA in User P2 space

The following diagram illustrates the data structure of the match table:

When an alignment fault occurs, a fault bit mask is created with onebit set in each group. The alignment fault handler then compares thisfault bit mask against each entry in the match table. If the fault bitmask is a subset of an entry in the match table, the fault is reported.

buffer_size

flags

If the flags argument is 0, data items of sizeAFR$K_VMS_LENGTH will be returned. If the flagsargument is AFR$M_USER_INFO, the user name and image name are added toeach data item and they are returned in a buffer of lengthAFR$K_EXTENDED_LENGTH. If the user name and image name are notavailable, an empty string is returned in the data item.

Description

The Initialize System Alignment Fault Reporting service initializessystem alignment fault reporting.

System alignment faults must be written to a buffer. The followingdiagram illustrates the format in which system alignment fault data issaved in the buffer:

Only one user on a system can initialize system alignment faultreporting at any time. Subsequent calls will return SS$_AFR_ENABLED.

System alignment fault reporting is disabled when the program thatcalled the service completes.

Required Access or Privileges

CMKRNL privilege is required.

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT,$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,$STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The match table is not read accessible.
SS$_AFR_ENABLED	The service was already called.
SS$_BADPARAM	The buffer_size argument is less than the minimum size required. If the flags argument is 0, AFR$K_VMS_LENGTH + 32 is required. If the flags argument is 1, AFR$K_EXTENDED_LENGTH + 32 is required.
SS$_NOPRIV	The caller does not have CMKRNL privilege.

Formats a disk or magnetic tape volume and writes a label on thevolume. At the end of initialization, the disk is empty except for thesystem files containing the structure information. All former contentsof the volume are lost.

Format

SYS$INIT_VOL devnam, volnam [,itmlst]

C Prototype

int sys$init_vol (void *devnam, void *volnam, void *itmlst);

Arguments

devnam

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Name of the device on which the volume is physically mounted. Thedescriptor must point to the device name, a character string of 1 to 64characters. The device name can be a physical device name or a logicalname; if it is a logical name, it must translate to a physical name.

The device does not have to be currently allocated; however, allocatingthe device before initializing it is recommended.

volnam

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Identification to be encoded on the volume. The descriptor must pointto the volume name, a character string of 1 to 12 characters. For adisk volume name, you can specify a maximum of 12 ANSI characters; fora magnetic tape volume name, you can specify a maximum of 6 ANSI"a" characters.

Any valid ANSI "a" characters can be used; these includenumbers, uppercase letters, and any one of the followingnonalphanumeric characters:

! " % ' ( ) * + , - . / : ; < = >

HP strongly recommends that a disk volume name consist of onlyalphanumeric characters, dollar signs ($), underscores (_), and hyphens(-).

itmlst

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

Item list specifying options that can be used when initializing thevolume. The itmlst argument is the address of a listof item descriptors, each of which describes one option. The list ofitem descriptors is terminated by a longword of 0.

The following diagram depicts the format of a single item descriptor:

The following table defines the item descriptor fields:

Item Codes

INIT$_ACCESSED

An input item code that specifies the number of directories allowed insystem space on the volume.

You must specify an integer between 0 and 255 in the input buffer. Thedefault value is 3.

The INIT$_ACCESSED item code applies only to Files-11 On-Disk StructureLevel 1 disks.

INIT$_BADBLOCKS_LBN

An input item code that enables $INIT_VOL to mark bad blocks on thevolume; no data is written to those faulty areas. INIT$_BADBLOCKS_LBNspecifies faulty areas on the volume by logical block number and blockcount.

The buffer from which $INIT_VOL reads the option information containsan array of quadwords containing information in the following format:

The following table describes the information to be specified forINIT$_BADBLOCKS_LBN:

For example, if the input buffer contains the values 5 and 3, INIT_VOLstarts at logical block number 5 and allocates 3 blocks.

The number of entries in the buffer is determined by the buffer lengthfield in the item descriptor.

All media supplied by HP and supported on the operating system, exceptdisks and TU58 cartridges, are factory formatted and contain bad blockdata. The Bad Block Locator utility (BAD) or the diagnostic formatterEVRAC can be used to refresh the bad block data or to construct it forthe disks and TU58 cartridges. The INIT$_BADBLOCKS_LBN item code isnecessary only to enter bad blocks that are not identified in thevolume's bad block data. For more information, refer to theOpenVMS Bad Block Locator Utility Manual (available on the Documentation CD-ROM).

The INIT$_BADBLOCKS_LBN item code applies only to disks.

INIT$_BADBLOCKS_SEC

The input buffer must contain an array of octawords containinginformation in the following format:

The following table describes the information to be specified forINIT$_BADBLOCKS_SEC:

For example, if the input buffer contains the values 12, 3, 1, and 2,INIT_VOL starts at sector 12, track 1, cylinder 2, and allocates 3blocks.

The number of entries in the buffer is determined by the buffer lengthfield in the item descriptor.

All media supplied by HP and supported on the operating system, exceptdisks and TU58 cartridges, are factory formatted and contain bad blockdata. The Bad Block Locator utility (BAD) or the diagnostic formatterEVRAC can be used to refresh the bad block data or to construct it forthe disks and TU58 cartridges. The INIT$_BADBLOCKS_SEC item code isnecessary only to enter bad blocks that are not identified in thevolume's bad block data. For more information, refer to theOpenVMS Bad Block Locator Utility Manual.

The INIT$_BADBLOCKS_SEC item code applies only to disks.

INIT$_CLUSTERSIZE

volume size in blocks/(255 * 4096)

The INIT$_CLUSTERSIZE item code applies only to Files-11 On-DiskStructure Level 2 disks (for Files-11 On-Disk Structure Level 1 disks,the cluster size is 1). For Files-11 On-Disk Structure Level 2 disks,the cluster size default depends on the disk capacity.

• Disks that are 50,000 blocks or larger have a default cluster size of 3.
• Disks smaller than 50,000 blocks have a default value of 1.

INIT$_COMPACTION

INIT$_NO_COMPACTION---Default

The INIT$_COMPACTION item code applies only to TA90 drives.

INIT$_DENSITY

For magnetic tape volumes, the INIT$_DENSITY item code specifies thedensity.

The DENSITY item code is dependent on the type of tape device. If atape device is seen as capable of using the MT3 density codes thebuffer for MNT$_DENSITY item code must contain a longword with one ofthe MT3 codes, as defined in SYS$LIBRARY:STARLET (MT3$K_TK50,MT3$K_3480, M53$K_DSDLT, MT3$K_AIT2 and so on). Refer to theMT3_SUPPORTED argument for $GETDVI.

If the device does not support MT3 densities, the buffer specifies thedensity in bytes per inch (bpi) at which the magnetic tape is written.The following are possible symbolic values for tapes:

• INIT$K_DENSITY_800_BPI
• INIT$K_DENSITY_1600_BPI
• INIT$K_DENSITY_6250_BPI

The specified density value must be supported by the drive. If you donot specify a density item code for a blank magnetic tape, the systemuses a default density of the highest value allowed by the tape drive.If the drive allows 6250, 1600, and 800 bpi operation, the defaultdensity is 6250. If the drive allows only 1600 and 800 bpi operation,the default density is 1600. If you do not specify a density item codefor a magnetic tape that has been previously written, the system usesthe previously set volume density.

For diskettes, the INIT$_DENSITY item code specifies how the disketteis to be formatted. Possible symbolic values for diskettes are asfollows:

• INIT$K_DENSITY_SINGLE_DISK
• INIT$K_DENSITY_DOUBLE_DISK
• INIT$K_DENSITY_DD_DISK
• INIT$K_DENSITY_HD_DISK

For disk volumes that are to be initialized on RX02, RX23, or RX33diskette drives, the following values specify how the disk is to beformatted:

• INIT$K_DENSITY_SINGLE_DISK
• INIT$K_DENSITY_DOUBLE_DISK
• INIT$K_DENSITY_DD_DISK
• INIT$K_DENSITY_HD_DISK

Diskettes are initialized as follows:

• RX23 diskettes---DD or HD density
• RX33 diskettes---double density only
• RX02 dual-density diskette drives---single or double density

If you do not specify a density item code for a disk, the system leavesthe volume at the density at which it was last formatted. RX02 diskspurchased from HP are formatted in single density.

INIT$_DIRECTORIES

The INIT$_DIRECTORIES item code applies only to disks.

INIT$_ERASE

INIT$_NO_ERASE---Default

• ODS--2 disk volumes
• ANSI magnetic tape volumes on magnetic tape devices that support the hardware erase function, for example, TU78 and MSCP magnetic tapes

For disk devices, this item code sets the ERASE volume attribute,causing each file on the volume to be erased when it is deleted.

INIT$_EXTENSION

The default extension set by this item code is used only if thefollowing conditions are in effect:

• No default extension for the file has been set.
• No default extension for the process has been set using the SET RMS command.

INIT$_FPROT

The following diagram depicts the structure of the protection mask onsystems:

The INIT$_FPROT item code applies only to Files-11 On-Disk StructureLevel 1 disks and is ignored if it is used on an OpenVMS system.OpenVMS systems use the default file extension set by the DCL commandSET PROTECTION/DEFAULT.

INIT$_HEADERS

The INIT$_HEADERS item code applies only to disks.

INIT$_HIGHWATER---Default

INIT$_NO_HIGHWATER

INIT$_NO_HIGHWATER disables FHM for a volume.

The INIT$_HIGHWATER and INIT$_NO_HIGHWATER item codes apply only toFiles-11 On-Disk Structure Level 2 disks.

INIT$_HOMEBLOCKS

• INIT$K_HOMEBLOCKS_GEOMETRY
  Causes the homeblocks to be placed at separate locations on disk, to protect against failure of a disk block. Placement depends on the reported geometry of the disk.
• INIT$K_HOMEBLOCKS_FIXED
  Causes the homeblocks to be placed at separate fixed locations on the disk; this is the default. Placement is independent of the reported geometry of the disk. This caters for disks that report different geometries according to the type of controller to which they are attached.
• INIT$K_HOMEBLOCKS_CONTIGUOUS
  Causes the homeblocks to be placed contiguously at the start of the disk. This allows container file systems to maximize the amount of contiguous space on the disk, when used with the INIT$_INDEX_BEGINNING item code.

INIT$_INDEX_BEGINNING

When issuing calls to $INIT_VOL, using this item code in conjunctionwith INIT$_INDEX_BLOCK results in an error. If you specify both itemcodes from DCL, INIT$_INDEX_BLOCK takes precedence.

This item code applies only to disks.

INIT$_INDEX_BLOCK

When issuing calls to $INIT_VOL, using this item code withINIT$_INDEX_BEGINNING, INIT$_INDEX_MIDDLE, or INIT$_INDEX_END resultsin an error. From DCL, if you specify INIT$_INDEX_BLOCK withINIT$_INDEX_BEGINNING, INIT$_INDEX_MIDDLE, or INIT$_INDEX_END, thenINIT$_INDEX_BLOCK takes precedence.

The INIT$_INDEX_BLOCK item code applies only to disks.

INIT$_INDEX_END

When issuing calls to $INIT_VOL, using this item code withINIT$_INDEX_BLOCK results in an error. If you specify both item codesfrom DCL, INIT$_INDEX_BLOCK takes precedence.

This item code applies only to disks.

INIT$_INDEX_MIDDLE

When issuing calls to $INIT_VOL, using this item code withINIT$_INDEX_BLOCK results in an error. If you specify both item codesfrom DCL, INIT$_INDEX_BLOCK takes precedence.

This item code applies only to disks.

INIT$_INTERCHANGE

For more information about the INIT$_INTERCHANGE item code and aboutmagnetic tape labeling and tape interchange, refer to the HP OpenVMS System Manager's Manual, Volume 1: Essentials.

INIT$_LABEL_ACCESS

! " % ' ( ) * + , - . / : ; < = >

By default, the operating system provides a routine SYS$MTACCESS thatchecks this field in the following manner:

• If the magnetic tape was created on a version of the operating system that conforms to Version 3 of ANSI, this item code is used to override any character except an ASCII space.
• If the magnetic tape conforms to an ANSI standard that is later than Version 3, this item code is used to override any character except an ASCII 1 character.

INIT$_LABEL_VOLO

INIT$_MAXFILES

volume size in blocks/cluster factor + 1

Once initialized, the maximum number of files can be increased only byreinitializing the volume.

The default maximum number of files is calculated as follows:

volume size in blocks/(cluster factor + 1) * 2

The INIT$_MAXFILES item code applies only to disks.

INIT$_OVR_ACCESS

INIT$_NO_OVR_ACCESS---Default

To specify INIT$_OVR_ACCESS, the caller must either own the volume orhave VOLPRO privilege.

INIT$_OVR_EXP

INIT$_NO_OVR_EXP---Default

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

INIT$_OVR_VOLO

INIT$_NO_OVR_VOLO---Default

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

INIT$_OWNER

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

INIT$_READCHECK

INIT$_NO_READCHECK---Default

The INIT$_READCHECK item code applies only to disks.

INIT$_SIZE

INIT$_STRUCTURE_LEVEL_1

INIT$_STRUCTURE_LEVEL_2---Default

• INIT$_READCHECK
• INIT$_WRITECHECK
• INIT$_CLUSTERSIZE

The default protection for a Structure Level 1 disk is full access tosystem, 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

INIT$_VERIFIED

INIT$_NO_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

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 volumelabel. The system applies only read and write access restrictions;execute and delete access are ignored. Moreover, the system and theowner 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 securityprofile is created from the VOLUME.DEFAULT profile, with the owner andprotection as currently defined for INITIALIZE.

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

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

INIT$_WINDOW

When a file is opened, the file system uses the mapping pointers toaccess 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 tapevolume and writes a label on the volume. At the end of initialization,the disk is empty except for the system files containing the structureinformation. All former contents of the volume are lost.

A blank magnetic tape can sometimes cause unrecoverable errors when itis read. $INIT_VOL attempts to read the volume unless the followingthree 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 causea fatal drive error. Such a diskette can be initialized successfully byspecifying the INIT$_DENSITY item code to format the diskette.

Required Access or Privileges

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

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

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 resourcesallocated by the $IO_SETUP system service. Buffer objects passed to$IO_SETUP cannot be deleted until every $IO_SETUP call has had acorresponding $IO_CLEANUP call.

Image rundown executes any required $IO_CLEANUP operations on behalf ofthe 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.

Provides the ability to control the set of Fast Path devices and theirassignment 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 intfunction_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) operationcompletes. The efn argument is a longword containingthe 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 beoperated upon.

function_code

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

The function_code specifies the operation to beperformed. Note that there is currently only one function code:

FP$K_BALANCE_PORTS - Distribute Fast Path ports across CPUs.

Description

The $IO_FASTPATH system service performs operations on the set of FastPath devices and CPUs enabled for Fast Path use. The $IO_FASTPATHWsystem service completes synchronously. That is, it returns after theoperation is complete.

The FP$K_BALANCE_PORTS function code specifies that the system serviceis to distribute the set of system assignable Fast Path ports acrossthe intersection of a caller-supplied set of candidate CPUs(cpu_mask) and the current set of usable CPUs. UsableCPUs are the intersection of the set of CPUs both enabled for Fast Pathuse by IO$_PREFERRED_CPUS and whose current state is RUN.

The service does this by:

1. Eliminating all CPUs not in the set of usable CPUs from the set of candidate CPUs.
2. Restoring any user assigned ports that are not currently on the user's preferred CPU to the user's preferred CPU, if that CPU is in the set of usable CPUs.
3. 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.

Performs operations on the set of Fast Path devices and CPUs enabledfor 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, unsignedint function_code);

On Alpha systems, starts the Fast I/O operation. The $IO_PERFORMservice completes asynchronously. For synchronous completion, use thePerform Fast I/O and Wait ($IO_PERFORMW) service.

This service accepts 64-bit addresses.

Format

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

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 aquadword 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 mustbe a multiple of 512 bytes. Drivers have further limitations on themaximum size of an I/O request.

devdata

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 blocknumber (VBN) for virtual I/O functions or the logical block number(LBN) for logical I/O functions. This argument is ignored for tapedevices.

For drivers with complex parameters, devdata would bethe address of a descriptor or buffer specific to the device andfunction and would be documented with the driver.

Description

The Perform Fast I/O system service initiates an I/O operation on thechannel number specified by the chan argument. Thebytes specified by the buflen argument are transferredbetween the location (devdata) on the device driverand the user's buffer starting at the process buffer address(bufadr). The byte count is read or written accordingto the function code previously specified in the $IO_SETUP callassociated with the fandle argument.

Upon completion, the I/O status is written to the IOSA starting at thelocation specified by iosadr, and an AST is deliveredto the astadr address supplied in the $IO_SETUP callassociated with fandle. The IOSA address is passed tothe 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 HP OpenVMS I/O User's Reference Manual lists these device-specific condition values for eachdevice.

On Alpha systems, starts a Fast I/O operation. The $IO_PERFORMW servicecompletes synchronously; that is, it returns to the caller afterperforming the Fast I/O operation.

In all other respects, $IO_PERFORMW is identical to $IO_PERFORM. Forall other information about the IO_PERFORMW service, refer to thedescription of $IO_PERFORM in this manual.

Format

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

C Prototype

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

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 intflags, 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 anddriver. Disk drivers support IO$M_NOVCACHE and IO$M_DATACHECK. Sometape devices support IO$M_REVERSE. Illegal modifiers are detected bythe $IO_PERFORM(W) service.

bufobj

OpenVMS usage:	buffer object
type:	quadword (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/OStatus Area (IOSA). This might or might not be the same identifier asthe 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 ASTparameter argument. When the AST routine is called, the ASTparameter 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 whicheach 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 forfuture use by HP 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/Ooperation.

Description

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

Required Privileges

If you use the flags argument FIO$M_EXPEDITE, aprocess 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$_BADPARAM	Invalid flags options specified.
SS$_EXBUFOBJLM	Buffer object cannot be created because it would bring the total number of buffer object pages above the systemwide limit MAXBOBMEM.
SS$_ILLBUFOBJ	The buffer object is not valid.
SS$_ILLIOFUNC	The function code is not valid.
SS$_ILLMODIFIER	The I/O function modifier is not permitted.
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$_INSFSPTS	Insufficient system page table entries.
SS$_IVSTSFLG	The specified status flag is invalid.
SS$_NOBUFOBJID	The process attempted to create a buffer object from user mode but was not holding required rights identifier VMS$BUFFER_OBJECT_USER.
SS$_NOPRIV	Valid flag options were specified but from user mode.
SS$_PAGNOTWRITE	A page within the address range is not writable.
SS$_PAGOWNVIO	Page owner violation. The pages could not be put into the buffer object because the access mode associated with the call to $IO_SETUP was less privileged than the access mode associated with the pages. See $CREATE_BUFOBJ_64 for additional information.
SS$_UNALIGNED	The I/O Status Area (IOSA) or data buffer is not aligned on a quadword boundary.

Adds a new Resource Manager (RM) participant to a transaction.

Format

SYS$JOIN_RM [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id [,[tid],[part_name] ,[rm_context] ,[timout] ,[bid]]

C Prototype

int sys$join_rm (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intrm_id,...);

Arguments

efn

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

Number of the event flag that is set when the service completes. Ifthis argument is omitted, event flag 0 is used.

flags

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

Flags specifying options for the service. The flagsargument is a longword bit mask in which each bit corresponds to anoption flag. The $DDTMDEF macro defines symbolic names for these optionflags described in Table SYS-47. All undefined bits must be 0. If thisargument is omitted, no flags are used.

Table SYS-47 $JOIN_RM Option Flags

Flag Name	Description
DDTM$M_COORDINATOR	Set this flag to specify that the new RM participant is to be a coordinator of the transaction on this node.
DDTM$M_SYNC	Specifies successful synchronous completion by returning SS$_SYNCH. When SS$_SYNCH is returned, the AST routine is not called, the event flag is not set, and the I/O status block is not filled in.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

The I/O status block in which the completion status of the service isreturned as a condition value. See the Condition Values Returnedsection.

The following diagram shows the structure of the I/O status block:

astadr

astprm

rm_id

• Types of event that are to be reported to the new RM participant.
• Event handler to which these event reports are to be delivered, and the access mode in which its ASTs are to be fired.
• Minimum access mode that the new RM participant must be in to acknowledge one of these event reports by calling $ACK_EVENT.
• Whether or not the DECdtm transaction manager may log information about the new RM participant.

tid

If this argument is omitted (the default) or its value is zero,$JOIN_RM adds an RM participant to the default transaction of thecalling process.

part_name

Used by recoverable resource managers to specify the RM participant touse in a subsequent call to $GETDTI or $SETDTI during recovery.

This argument has no effect if the RMI is volatile. If this argument isomitted (the default) or its value is zero, the name of the new RMparticipant is the same as that of the RMI with which it is associated.

The string passed in this argument can be no longer than 32 characters.

To ensure smooth operation in a mixed-network environment, refer to thechapter entitled Managing DECdtm Services in the HP OpenVMS System Manager's Manual, forinformation on defining node names.

rm_context

If this argument is omitted (the default) or is zero, the contextassociated with the new RM participant is the same as that of the RMIwith which it is associated.

timout

bid

Description

The $JOIN_RM system service:

• Adds a new RM participant to the specified transaction. The new RM participant is associated with the RMI whose identifier is passed in the rm_id argument.
• Introduces a new transaction to DECdtm if the new RM participant is a coordinator and the specified transaction is unknown to DECdtm.
• Authorizes a new branch of the transaction if the new RM participant is a coordinator.

Preconditions for the successful completion of $JOIN_RM are:

• Unless the DDTM$M_COORDINATOR flag is set, the calling process must contain at least one branch of the specified transaction.
• The calling process must contain the specified RMI.
• The caller must not be in a less privileged mode than the access mode of the specified RMI.
• If the DDTM$M_COORDINATOR flag is set, either the calling process must have the SYSPRV privilege, or the caller must be in executive or kernel mode.
• If the DDTM$M_COORDINATOR flag is set, the specified RMI must not be volatile. That is, the DDTM$M_VOLATILE flag must not have been set on the call to the $DECLARE_RM that created it.
• The access mode of the specified RMI must not be less privileged than that of the specified transaction in this process.

$JOIN_RM can fail for various reasons, including:

• Preconditions were not met.
• The DDTM$M_COORDINATOR flag was set, but no bid argument was supplied.

When $JOIN_RM completes successfully, a new RM participant running inthe calling process is added to the transaction. This RM participant isassociated with the specified RMI.

The DECdtm transaction manager will report to the new RM participantthe types of event specified in the call to $DECLARE_RM that createdthe RMI with which it is associated. Note however that events of typeprepare, one-phase commit, and commit are never reported to RMparticipants that set the DDTM$M_COORDINATOR flag on the call to$JOIN_RM.

If the call to $DECLARE_RM requested prepare and one-phase commitevents, and the $JOIN_RM call does not set the DDTM$M_COORDINATOR flag,the new RM participant is entitled to a vote on the outcome of thetransaction.

If the $JOIN_RM call sets the DDTM$M_COORDINATOR flag, then the new RMparticipant is expected to initiate commit or abort processing by acall to $TRANS_EVENT. No events of type prepare, one-phase commit, orcommit are delivered to the RM participant.

Events of type abort are reported to the RM participant.

The new RM participant is removed from the transaction when the firstof the following conditions is met:

• On successful completion of a call to $ACK_EVENT that acknowledges an event report delivered to that RM participant, if the event and its acknowledgment were one of those listed in the following table:

  Event	Acknowledgment (report_reply)
  Abort	SS$_FORGET
  Commit	SS$_FORGET or SS$_REMEMBER
  Prepare	SS$_FORGET
  One-phase commit	SS$_NORMAL or SS$_VETO

• On completion of a successful call to $TRANS_EVENT that specifies a commit or abort event, if the DDTM$M_COORDINATOR flag is set.
• When a commit or abort event occurs, and no associated event report is delivered to the RM participant.
• On successful completion of a call to $FORGET_RM that deletes the RMI with which it is associated.
• When the current process terminates (normally or abnormally).
• When the current image terminates (normally or abnormally).

If the DDTM$M_COORDINATOR flag is set:

• A new branch is authorized for the transaction and its identifier is returned in the octaword that the bid argument points to. $JOIN_RM uses the $CREATE_UID system service to generate the BID. No other call to $ADD_BRANCH, $JOIN_RM, or $CREATE_UID on any other node ever returns the same BID value.
• The transaction cannot commit until the new branch has been started by a matching call to $START_BRANCH. (See the description of $START_BRANCH for the definition of a matching call to $START_BRANCH.)
• If the transaction is not already known to this process, then the transaction is introduced to this process with an access mode equal to the access mode of the caller. (See the description of $START_TRANS for a definition of the access mode of a transaction.)

There is also a wait form of the service, $JOIN_RMW.

Required Privileges

If the DDTM$M_COORDINATOR flag is set, then either the calling processmust have the SYSPRV privilege or the caller must be in executive orkernel mode.

Required Quotas

BYTLM, ASTLM

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW,$CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW,$END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW,$GET_DEFAULT_TRANS, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS,$SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS,$START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

SS$_NORMAL	If returned in R0, the request was successfully queued. If returned in the I/O status block, the service completed successfully.
SS$_SYNCH	The service completed successfully and synchronously (returned only if the DDTM$M_SYNC flag is set).
SS$_ACCVIO	An argument was not accessible to the caller.
SS$_BADPARAM	The options flags were invalid, the specified tid was invalid, or DTM$M_COORDINATOR set but no bid supplied.
SS$_EXASTLM	The process AST limit (ASTLM) was exceeded.
SS$_EXQUOTA	The job buffered I/O byte limit quota (BYTLM) was exceeded.
SS$_ILLEFC	The event flag number was invalid.
SS$_INSFARGS	A required argument was missing.
SS$_INSFMEM	There was insufficient system dynamic memory for the operation.
SS$_INVBUFLEN	The string passed in the part_name argument was too long.
SS$_NOSYSPRIV	The DDTM$M_COORDINATOR flag was set and the caller was in user or supervisor mode but the calling process did not have the SYSPRV privilege.
SS$_NOCURTID	An attempt was made to add a new participant to the default transaction (the tid argument was zero or omitted) but the calling process did not have a default transaction.
SS$_NOSUCHTID	The DDTM$M_COORDINATOR flag was clear and the calling process did not contain any branches in the transaction.
SS$_NOSUCHRM	The calling process did not contain the specified RMI.
SS$_WRONGACMODE	The caller was in a less privileged access mode than that of the RMI.
SS$_WRONGSTATE	The transaction was in the wrong state for the attempted operation because either: An abort event had occurred for the transaction. A call to $END_TRANS to end the transaction was in progress and it is too late to add a new RM participant to the transaction.

Adds a new Resource Manager (RM) participant to a transaction.

$JOIN_RMW always waits for the request to complete before returning tothe caller. Other than this, it is identical to $JOIN_RM.

Format

SYS$JOIN_RMW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,rm_id [,[tid],[part_name] ,[rm_context] ,[timout] ,[bid] ]

C Prototype

int sys$join_rmw (unsigned int efn, unsigned int flags, struct _iosb*iosb, void (*astadr)(__unknown_params), int astprm, unsigned intrm_id,...);

Locks a page or range of pages in memory. The specified virtual pagesare forced into the working set and then locked in memory. A lockedpage is not swapped out of memory if the working set of the process isswapped out. These pages are not candidates for page replacement and inthis 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 belocked. The inadr argument is the address of a2-longword array containing, in order, the starting and ending processvirtual addresses. Only the virtual page number portion of each virtualaddress is used; the low-order byte-within-page bits are ignored.

On VAX systems, if the starting and ending virtual addresses are thesame, 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 $LCKPAGactually locked. The retadr argument is the address ofa 2-longword array containing, in order, the starting and endingprocess 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. Theacmode argument is a longword containing the accessmode. 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 accessmode must be equal to or more privileged than the access mode alreadyassociated with the pages to be locked.

Description

The Lock Pages in Memory service locks a page or range of pages inmemory. The specified virtual pages are forced into the working set andthen locked in memory. A locked page is not swapped out of memory ifthe working set of the process is swapped out. These pages are notcandidates for page replacement and in this sense are locked in theworking set as well.

If more than one page is being locked and you need to determinespecifically which pages were previously locked, the pages should belocked one at a time.

If an error occurs while the $LCKPAG service is locking pages, thereturn array, if requested, indicates the pages that were successfullylocked before the error occurred. If no pages are locked, bothlongwords in the return address array contain the value --1.

On Alpha systems, if you are attempting to lock executable code, youshould issue multiple $LCKPAG calls: one to lock the code pages andothers to lock the linkage section references into these pages.

Required Access or Privileges

The calling process must have PSWAPM privilege to lock pages intomemory.

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

For more information, refer to the chapter on memory management in theOpenVMS 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.

On Alpha systems, locks a range of pages in memory. The specifiedvirtual pages are forced into the working set and then locked inmemory. A locked page is not swapped out of memory if the working setof the process is swapped out. These pages are not candidates for pagereplacement 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 specifiedvirtual 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 lengthwill be rounded up to a CPU-specific page boundary so that it includesall 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. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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

The most privileged access mode used is the access mode of the caller.For the $LCKPAG_64 service to complete successfully, the resultantaccess mode must be equal to or more privileged than the access modealready associated with the pages to be locked.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the pages locked in memory. Thereturn_va_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned quadword into which the service returnsthe virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword intowhich the service returns the length of the virtual address rangelocked in bytes.

Description

The Lock Pages in Memory service locks a range of pages in memory. Thespecified virtual pages are forced into the working set and then lockedin memory. A locked page is not swapped out of memory if the workingset of the process is swapped out. These pages are not candidates forpage replacement and, in this sense, are locked in the working set aswell.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments. If a condition value other than SS$_ACCVIO is returned, thereturned address and returned length indicate the pages that weresuccessfully locked before the error occurred. If no pages were locked,the return_va_64 argument will contain the value -1,and a value cannot be returned in the memory location pointedto by the return_length_64 argument.

Required Privileges

A process must have PSWAPM privilege to call the $LCKPAG_64 service.

Required Quota

None

Related Services

$LCKPAG, $ULKPAG, $ULKPAG_64

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 in the working set.
SS$_ACCVIO	The return_va_64 argument or the return_length_64 argument cannot be written by the caller, or an attempt was made to lock pages 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$_LKWSETFUL	The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
SS$_NOPSWAPM	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_64 was less privileged than the access mode associated with the pages that were to be locked.

Locks a range of pages in the working set; if the pages are not alreadyin the working set, it brings them in and locks them. A page locked inthe working set does not become a candidate for replacement.

Format

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

C Prototype

int sys$lkwset (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 belocked in the working set. The inadr argument is theaddress of a 2-longword array containing, in order, the starting andending process virtual addresses. Only the virtual page number portionof each virtual address is used; the low-order byte-within-page bitsare ignored.

On VAX systems, if the starting and ending virtual addresses are thesame, 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 range of pagesactually locked by $LCKWSET. The retadr argument isthe address of a 2-longword array containing, in order, the startingand 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. Theacmode argument is a longword containing the accessmode. The $PSLDEF macro defines the four access modes.

The most privileged access mode used is the access mode of the caller.For the $LKWSET service to complete successfully, the resultant accessmode must be equal to or more privileged than the access mode alreadyassociated with the pages to be locked.

Description

The Lock Pages in Working Set service locks a range of pages in theworking set; if the pages are not already in the working set, it bringsthem in and locks them. A page locked in the working set does notbecome a candidate for replacement.

If more than one page is being locked and you need to determinespecifically which pages were previously locked, the pages should belocked one at a time.

If an error occurs while the $LKWSET service is locking pages, thereturn array, if requested, indicates the pages that were successfullylocked before the error occurred. If no pages are locked, bothlongwords in the return address array contain the value --1.

Global pages with write access cannot be locked into the working set.

On Alpha systems, if you are attempting to lock executable code, youshould issue multiple $LKWSET calls: one to lock the code pages andothers to lock the linkage section references into these pages.

Required Access or Privileges

None

Required Quota

None

Related Services

You can unlock pages locked in the working set with the Unlock Pagefrom Working Set ($ULWSET) service.

For more information, refer to the chapter on memory management in theOpenVMS 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 in the working set.
SS$_ACCVIO	The input address array cannot be read; the output address array cannot be written; a page in the specified range is inaccessible or nonexistent; or an attempt was made to lock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
SS$_LKWSETFUL	The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
SS$_NOPRIV	A page in the specified range is in the system address space, or a global page with write access was specified.
SS$_PAGOWNVIO	The pages could not be locked because the access mode associated with the call to $LKWSET was less privileged than the access mode associated with the pages that were to be locked.

On Alpha systems, locks a range of virtual addresses in the workingset; if the pages are not already in the working set, the servicebrings them in and locks them. A page locked in the working set doesnot become a candidate for replacement.

This service accepts 64-bit addresses.

Format

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

C Prototype

int sys$lkwset_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 in the workingset. The specified virtual address will be rounded down to aCPU-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 in the working set.The specified length will be rounded up to a CPU-specific page boundaryso 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. Theacmode argument is a longword containing the accessmode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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

The most privileged access mode used is the access mode of the caller.For the $LKWSET_64 service to complete successfully, the resultantaccess mode must be equal to or more privileged than the access modealready associated with the pages to be locked.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address of the pages locked in the workingset. The return_va_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword into which the servicereturns the virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The length of the virtual address range locked in the working set. Thereturn_length_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned quadword into which the service returnsthe length of the virtual address range in bytes.

Description

The Lock Pages in Working Set service locks a range of pages in theworking set; if the pages are not already in the working set, it bringsthem in and locks them. A page locked in the working set does notbecome a candidate for replacement.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments. If a condition value other than SS$_ACCVIO is returned, thereturned address and returned length indicate the pages that weresuccessfully locked before the error occurred. If no pages were locked,the return_va_64 argument will contain the value -1,and a value cannot be returned in the memory location pointedto by the return_length_64 argument.

Global pages with write access cannot be locked into the working set.

Required Privileges

None

Required Quota

None

Related Services

$LKWSET, $ULWSET, $ULWSET_64

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 in the working set.
SS$_ACCVIO	The return_va_64 or return_length_64 argument cannot be written by the caller, or an attempt was made to lock pages by a caller whose access mode is less privileged than the access mode associated with the pages.
SS$_LKWSETFUL	The locked working set is full. If any more pages are locked, not enough dynamic pages will be available to continue execution.
SS$_NOPRIV	No privilege; global pages with write access cannot be locked into the working set.
SS$_PAGNOTINREG	A page in the specified range is not within the specified region.
SS$_PAGOWNVIO	The pages could not be locked because the access mode associated with the call to $LKWSET_64 was less privileged than the access mode associated with the pages that were to be locked.

Establishes a correspondence between pages (maps) in the virtualaddress space of the process and physical pages occupied by a globalsection.

Format

SYS$MGBLSC inadr ,[retadr] ,[acmode] ,[flags] ,gsdnam ,[ident] ,[relpag]

C Prototype

int sys$mgblsc (struct _va_range *inadr, struct _va_range *retadr,unsigned int acmode, unsigned int flags, void *gsdnam, struct _secid*ident, unsigned int relpag);

Arguments

inadr

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

Starting and ending virtual addresses into which the section is to bemapped. The inadr argument is the address of a2-longword array containing, in order, the starting and ending processvirtual addresses. Only the virtual page number portion of each virtualaddress is used to specify which pages are to be mapped; the low-orderbyte-within-page bits are ignored for this purpose.

The interpretation of the inadr argument depends onthe setting of SEC$M_EXPREG in the flags argument andon whether you are using an Alpha or a VAX system. The two system typesare discussed separately in this section.

Alpha System Usage

On Alpha systems, if you do not set the SEC$M_EXPREG flag, theinadr argument specifies the starting and endingvirtual addresses of the region to be mapped. Addresses in system spaceare not allowed. The addresses must be aligned on CPU-specific pages;no rounding to CPU-specific pages occurs. The lower address of theinadr argument must be on a CPU-specific page boundaryand the higher address of the inadr argument must be 1less than a CPU-specific boundary, thus forming a range, from lowest tohighest, of address bytes. You can use the SYI$_PAGE_SIZE item code inthe $GETSYI system service to set the inadr argumentto the proper values. You do this to avoid programming errors thatmight arise because of incorrect programming assumptions about pagesizes.

If, on the other hand, you do set the SEC$M_EXPREG flag,indicating that the mapping should take place using the first availablespace in a particular region, the inadr argument isused only to indicate the desired region: the program region (P0) orthe control region (P1).

Caution Mapping into the P1 region is generally discouraged, but, if done, mustbe executed with extreme care. Since the user stack is mapped in P1, itis possible that references to the user stack might inadvertently reador write the pages mapped with $CRMPSC.

When the SEC$M_EXPREG flag is set, the second inadrlongword is ignored, while bit 30 (the second most significant bit) ofthe first inadr longword is used to determine theregion of choice. If the bit is clear, P0 is chosen; if the bit is set,P1 is chosen. On Alpha systems, bit 31 (the most significant bit) ofthe first inadr longword must be 0. To ensurecompatibility between VAX and Alpha systems when you choose a region,HP recommends that you specify, for the first inadrlongword, any virtual address in the desired region.

VAX System Usage

On VAX systems, if you do not set the SEC$M_EXPREG flag, theinadr argument specifies the starting and endingvirtual addresses of the region to be mapped. Addresses in system spaceare not allowed. If the starting and ending virtual addresses are thesame, a single page is mapped.

Note If the SEC$M_EXPREG flag is not set, HP recommends that theinadr argument always specify the entire virtualaddress range, from starting byte address to ending byte address. Thisensures compatibility between VAX and Alpha systems.

If, on the other hand, you do set the SEC$M_EXPREG flag,indicating that the mapping should take place using the first availablespace in a particular region, the inadr argument isused only to indicate the desired region: the program region (P0) orthe control region (P1).

Caution Mapping into the P1 region is generally discouraged, but, if done, mustbe executed with extreme care. Since the user stack is mapped in P1, itis possible that references to the user stack might inadvertently reador write the pages mapped with $CRMPSC.

When the SEC$M_EXPREG flag is set, the second inadrlongword is ignored, while bit 30 (the second most significant bit) ofthe first inadr longword is used to determine theregion of choice. If the bit is clear, P0 is chosen; if the bit is set,P1 is chosen. On VAX systems, bit 31 (the most significant bit) of thefirst inadr longword is ignored. To ensurecompatibility between VAX and Alpha systems when you choose a region,HP recommends that you specify, for the first inadrlongword, any virtual address in the desired region.

retadr

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

Starting and ending process virtual addresses into which the sectionwas actually mapped by $MGBLSC. The retadr argument isthe address of a 2-longword array containing, in order, the startingand ending process virtual addresses.

On Alpha systems, the retadr argument returns thestarting and ending addresses of the usable range ofaddresses. This might differ from the total amount mapped. Theretadr argument is required when therelpag argument is specified. If the section beingmapped does not completely fill the last page used to map the section,the retadr argument indicates the highest address thatactually maps the section. If the relpag argument isused to specify an offset into the section, the retadrargument reflects the offset.

acmode

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

Access mode to be associated with the pages mapped into the processvirtual address space. The acmode argument is alongword containing the access mode. The $PSLDEF macro defines symbolsfor the four access modes.

The most privileged access mode used is the access mode of the caller.

flags

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

Flag mask specifying options for the operation. Theflags argument is a longword bit vector wherein a bitwhen set specifies the corresponding option.

The $SECDEF macro defines symbolic names for the flag bits. Youconstruct the flags argument by specifying thesymbolic names of each desired option in a logical OR operation.

The following table describes each flag option:

Flag Option	Description
SEC$M_WRT	Map the section with read/write access. By default, the section is mapped with read-only access. If SEC$M_WRT is specified and the section is not copy-on-reference, write access is required.
SEC$M_SYSGBL	Map a system global section. By default, the section is a group global section.
SEC$M_EXPREG	Map the section into the first available virtual address range. By default, the section is mapped into the range specified by the inadr argument. See the inadr argument description for a complete explanation of how to set the SEC$M_EXPREG flag.

gsdnam

OpenVMS usage:	section_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Name of the global section. The gsdnam argument is theaddress of a character string descriptor pointing to this name string.

For group global sections, the operating system interprets the groupUIC as part of the global section name; thus, the names of globalsections are unique to UIC groups. Further, all global section namesare implicitly qualified by their identification fields.

You can specify any name from 1 to 43 characters. All processes mappingto the same global section must specify the same name. Note that thename is case sensitive.

Use of characters valid in logical names is strongly encouraged. Validvalues include alphanumeric characters, the dollar sign ($), and theunderscore (_). If the name string begins with an underscore (_), theunderscore is stripped and the resultant string is considered to be theactual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after theapplication of the prefix GBL$ to the name. If the result translates,it is used as the name of the section. If the resulting name does nottranslate, the name specified by the caller is used as the name of thesection.

Additional information on logical name translations and on section nameprocessing is available in the OpenVMS Programming Concepts Manual.

ident

OpenVMS usage:	section_id
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Identification value specifying the version number of a global sectionand, for processes mapping to an existing global section, the criteriafor matching the identification. The ident argument isthe address of a quadword structure containing three fields.

The first longword specifies, in the low-order two bits, the matchingcriteria. Their valid values, the symbolic names by which they can bespecified, and their meanings are as follows:

Value/Name	Match Criteria
0 SEC$K_MATALL	Match all versions of the section.
1 SEC$K_MATEQU	Match only if major and minor identifications match.
2 SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

The version number is in the second longword and contains two fields: aminor identification in the low-order 24 bits and a majoridentification in the high-order 8 bits.

If you do not specify ident or specify it as the value0 (the default), the version number and match control fields default tothe value 0.

relpag

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

Relative page number within the section of the first page to be mapped.The relpag argument is a longword containing thisnumber.

On Alpha systems, the relpag argument is interpretedas an index into the section file, measured in pagelets for afile-backed section or CPU-specific pages for a PFN-mapped section.

On Alpha and VAX systems, if you do not specify relpagor specify it as the value 0 (the default), the global section ismapped beginning with the first virtual block in a file-backed sectionor the first CPU-specific page in a PFN-mapped section.

Description

The Map Global Section service establishes a correspondence betweenpages (maps) in the virtual address space of the process and physicalpages occupied by a global section. The protection mask specified atthe time the global section is created determines the type of access(for example, read/write or read only) that a particular process has tothe section.

When $MGBLSC maps a global section, it adds pages to the virtualaddress space of the process. The section is mapped from a low addressto a high address, whether the section is mapped in the program orcontrol region.

If an error occurs during the mapping of a global section, the returnaddress array, if specified, indicates the pages that were successfullymapped when the error occurred. If no pages were mapped, both longwordsof the return address array contain the value --1.

Required Access or Privileges

Read access is required. If the SEC$M_WRT flag is specified, writeaccess is required.

Required Quota

The working set quota (WSQUOTA) of the process must be sufficient toaccommodate the increased size of the virtual address space when the$MGBLSC service maps a section.

If the section pages are copy-on-reference, the process must also havesufficient paging file quota (PGFLQUOTA).

This system service causes the working set of the calling process to beadjusted to the size specified by the working set quota (WSQUOTA). Ifthe working set size of the process is less than quota, the working setsize is increased; if the working set size of the process is greaterthan quota, the working set size is decreased.

Related Services

$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,$LKWSET, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,$UPDSECW

For more information, refer to the chapter on memory management in theOpenVMS Programming Concepts Manual.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The input address array, the global section name or name descriptor, or the section identification field cannot be read by the caller; or the return address array cannot be written by the caller.
SS$_ENDOFFILE	The starting virtual block number specified is beyond the logical end-of-file.
SS$_EXQUOTA	The process exceeded its paging file quota, creating copy-on-reference pages.
SS$_INSFWSL	The working set limit of the process is not large enough to accommodate the increased virtual address space.
SS$_INVARG	Invalid argument specified to service. Common sources are the incorrect specification of relpag or the values in the inadr array.
SS$_IVLOGNAM	The global section name has a length of 0 or has more than 43 characters.
SS$_IVSECFLG	You set a reserved flag.
SS$_IVSECIDCTL	The match control field of the global section identification is invalid.
SS$_NOPRIV	The file protection mask specified when the global section was created prohibits the type of access requested by the caller; or a page in the input address range is in the system address space.
SS$_NOSHPTS	The region ID of a shared page-table region was specified.
SS$_NOSUCHSEC	The specified global section does not exist.
SS$_PAGOWNVIO	A page in the specified input address range is owned by a more privileged access mode.
SS$_SECREFOVF	The maximum number of references for a global section has been reached (2,147,483,647).
SS$_TOOMANYLNAM	Logical name translation of the gsdnam string exceeded the allowed depth.
SS$_VA_IN_USE	The existing underlying page cannot be deleted because it is associated with a buffer object.
SS$_VASFULL	The virtual address space of the process is full; no space is available in the page tables for the pages created to contain the mapped global section.

On Alpha systems, establishes a correspondence between pages in thevirtual address space of the process and the pages occupied by a globaldisk file, page file, or demand-zero section and can map to ademand-zero section with shared page tables.

This service accepts 64-bit addresses.

Format

SYS$MGBLSC_64 gs_name_64 ,ident_64 ,region_id_64 ,section_offset_64,length_64 ,acmode ,flags ,return_va_64 ,return_length_64
[,start_va_64]

C Prototype

int sys$mgblsc_64 (void *gsdnam_64, struct _secid *ident_64, struct_generic_64 *region_id_64, unsigned __int64 section_offset_64, unsigned__int64 length_64, unsigned int acmode, unsigned int flags, void*(*(return_va_64)), unsigned __int64 *return_length_64,...);

Arguments

gs_name_64

OpenVMS usage:	section_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

Name of the global section. The gs_name_64 argument isthe 32- or 64-bit virtual address of a naturally aligned 32-bit or64-bit string descriptor pointing to this name string.

You can specify any name from 1 to 43 characters. All processes mappingto the same global section must specify the same name. Note that thename is case sensitive.

Use of characters valid in logical names is strongly encouraged. Validvalues include alphanumeric characters, the dollar sign ($), and theunderscore (_). If the name string begins with an underscore (_), theunderscore is stripped and the resultant string is considered to be theactual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after theapplication of the prefix GBL$ to the name. If the result translates,it is used as the name of the section. If the resulting name does nottranslate, the name specified by the caller is used as the name of thesection.

Additional information on logical name translations and on section nameprocessing is available in the OpenVMS Programming Concepts Manual.

ident_64

OpenVMS usage:	section_id
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Identification value specifying the version number of a global section.The ident_64 argument is a quadword containing threefields. The ident_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword that contains theidentification value.

The first longword specifies the matching criteria in its low-order twobits.

The valid values, symbolic names by which they can be specified, andtheir meanings are as follows:

Value	Symbolic Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section.
1	SEC$K_MATEQU	Match only if major and minor identifications match.
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

If you specify the ident_64 argument as 0, the versionnumber and match control fields default to 0.

The version number is in the second longword. The version numbercontains two fields: a minor identification in the low-order 24 bitsand a major identification in the high-order 8 bits. You can assignvalues for these fields by installation convention to differentiateversions of global sections. If no version number is specified when asection is created, processes that specify a version number whenmapping cannot access the global section.

region_id_64

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The region ID associated with the region to map the global section. Thefile VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in STARLET.MLBdefine a symbolic name for each of the three default regions in P0, P1,and P2 space.

The following region IDs are defined:

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can bespecified.

section_offset_64

OpenVMS usage:	byte offset
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Offset into the global section at which to start mapping into theprocess's virtual address space.

If a map to a global disk file section is being requested, thesection_offset_64 argument specifies an even multipleof disk blocks. If a map to a global page file or demand-zero sectionis being requested, the section_offset_64 argumentspecifies an even multiple of CPU-specific pages. If zero is specified,the global section is mapped beginning with the first page of thesection.

If the region_id_64 argument specifies a shared pagetable region, section_offset_64 must be an evenmultiple of pages mapped by a page table page.

length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by value

Length, in bytes, of the desired mapping of the global disk filesection.

If a map to a global section is being requested, thelength_64 argument must specify an even multiple ofdisk blocks. If a map to a global page file or demand-zero section isbeing requested, the length_64 argument must specifyan even multiple of CPU-specific pages. If zero is specified, the sizeof the disk file is used.

If a shared page-table region is specified by theregion_id_64 argument, length_64 mustbe an even multiple of the number of bytes that can be mapped by aCPU-specific page-table page or must include the last page within thememory-resident global section.

acmode

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

Access mode that is to be the owner of the pages created during themapping. This is also the read access mode and, if the SEC$M_WRT flagis specified, the write access mode. The acmodeargument is a longword containing the access mode.

The $PSLDEF macro in STARLET.MLB and the file PSLDEF.H inSYS$STARLET_C.TLB define the following symbols and their values for thefour 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

The most privileged access mode used is the access mode of the caller.Address space cannot be created within a region that has a create modeassociated with it that is more privileged than the caller's mode. Thecondition value SS$_IVACMODE is returned if the caller is lessprivileged than the create mode for the region.

flags

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

Flag mask specifying options for the operation. Theflags argument is a longword bit vector in which eachbit corresponds to a flag. The $SECDEF macro and the SECDEF.H filedefine a symbolic name for each flag. You construct theflags argument by performing a logical OR operation onthe symbol names for all desired flags.

The following table describes each flag that is valid for the$MGBLSC_64 service:

Flag	Description
SEC$M_EXPREG	Pages are mapped into the first available space at the current end of the specified region. If /ALLOCATE was specified when the memory-resident global section was registered in the Reserved Memory Registry, virtually aligned addresses after the first available space are chosen for the mapping. It the region_id_64 argument specifies a shared page-table region, the first available space is round up to the beginning of the next CPU-specific page-table page.
SEC$M_GBL	Pages form a global section. By default, this flag is always present in this service and cannot be disabled.
SEC$M_NO_OVERMAP	Pages cannot overmap existing address space.
SEC$M_SHMGS	On OpenVMS Galaxy systems, create a shared-memory global section.
SEC$M_SYSGBL	The global section map is a system global section. By default, the section is a group global section.
SEC$M_WRT	Map the section with read/write access.

All other bits in the flags argument are reserved for future use by HPand should be specified as 0. The condition value SS$_IVSECFLG isreturned if any undefined bits are set or if an attempt is made to usethe SEC$M_PAGFIL flag, which applies only to the creation of apage-file backed section.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The process virtual address into which the global disk or page filesection was mapped. The return_va_64 argument is the32- or 64-bit virtual address of a naturally aligned quadword intowhich the service returns the virtual address.

Upon successful completion of this service, if thesection_offset_64 argument was specified, the virtualaddress returned in the return_va_64 argument reflectsthe offset into the global section mapped such that the virtual addressreturned cannot be aligned on a CPU-specific page boundary. The virtualaddress returned will always be on an even virtual disk block boundary.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The length of the usable virtual address range mapped. Thereturn_length_64 argument is the 32- or 64-bit virtualaddress of a naturally aligned quadword into which the service returnsthe length of the virtual address range mapped in bytes.

Upon successful completion of this service, the value in thereturn_length_64 argument might differ from the totalamount of virtual address space mapped. The value in thereturn_va_64 argument plus the value in thereturn_length_64 argument indicates the address of thefirst byte beyond the end of the mapping of the global disk filesection.

If the value in the section_offset_64 argument plusthe value in the length_64 argument did not specify tomap the entire global section, this byte can be located at an evenvirtual disk block boundary within the last page of the mapping.

If the section being mapped does not completely fill the last page usedto represent the global disk file section, this byte can be mapped intoyour address space; however, it is not backed up by the disk file.

start_va_64

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

The starting virtual address to which to map the global section. Thespecified virtual address must be a CPU-specific page-aligned address.If the flag SEC$M_EXPREG is specified, the start_va_64argument must not be specified or must be specified as 0. IfSEC$M_EXPREG is set and the start_va_64 argument isnonzero, the condition value SS$_IVSECFLG is returned.

If the region_id_64 argument specifies a sharedpage-table region, start_va_64 must be aligned to aCPU-specific page-table page boundary.

Description

The Map to Global Section service establishes a correspondence betweenpages in the virtual address space of the process and pages occupied bya global disk file, page file, or memory-resident demand-zero section.This service adds pages to the virtual address space of the process.

If a global disk file or page file backed section is being mapped,invalid page table entries are placed in the process page table.

If a memory-resident global section is being mapped, global pages arenot charged against the process's working set quota when the virtualmemory is referenced and the global pages are not charged against theprocess's pagefile quota.

If the memory-resident global section was not registered in theReserved Memory Registry or /NOALLOCATE was specified when the globalsection was registered, invalid page table entries are placed in theprocess page table.

If the memory-resident global section was registered in the ReservedMemory Registry and /ALLOCATE was specified when the memory-residentglobal section was registered, valid page table entries are placed inthe process page tables.

If a global disk file or page file backed section is being mapped, andthe flag SEC$M_EXPREG is set, the first free virtual address within thespecified region is used to start mapping to the global section.

To use the shared page tables associated with a memory-resident globalsection, you must first create a shared page table region (withSYS$CREATE_REGION_64). To map to the memory-resident global sectionusing the shared page tables you must do the following:

• Specify a shared page table region in the region_id_64 argument.
• Specify SEC$M_WRT in the flags argument.
• Set the flag SEC$M_EXPREG or provide a CPU-specific page-table page-aligned virtual address in the start_va_64 argument.
• Specify a CPU-specific page-table page-aligned value for the section_offset_64 argument or zero.
• Specify a value for the map_length_64 argument that is an even multiple of bytes mapped by a CPU-specific page-table page, or include the last page of the section or zero.

See the description of $CREATE_REGION_64 for information aboutcalculating virtual addresses that are aligned to a CPU-specific pagetable page boundary.

A memory-resident global section can be mapped with shared page tablesor private page tables. The following table lists the factorsassociated with determining whether the mapping occurs with shared pagetables or private page tables:

Global Section Created with Shared Page Tables	Shared Page-Table Region Specified by region_id_64	Type of Page Tables Used in Mapping
No	No	Private
No	Yes	Private
Yes	No	Private
Yes	Yes	Shared

In general, if the flag SEC$M_EXPREG is set, the first free virtualaddress within the specified region is used to map to the globalsection.

If the flag SEC$M_EXPREG is set, a memory-resident global section isbeing mapped and the region_id_64 argument indicates ashared page-table region, the first free virtual address within thespecified region is rounded up to a CPU-specific page-table pageboundary and used to map to the global section.

If the flag SEC$M_EXPREG is set and the /ALLOCATE qualifier wasspecified with the SYSMAN command RESERVED_MEMORY ADD for thememory-resident global section, the first free virtual address withinthe specified region is rounded up to the same virtual alignment as thephysical alignment of the preallocated pages and used to map to theglobal section. Granularity hints are set appropriately for eachprocess private page-table entry (PTE).

In general, if the flag SEC$M_EXPREG is clear, the virtual address inthe start_va_64 argument is used to map to the globalsection.

If the flag SEC$M_EXPREG is clear and a memory-resident global sectionis being mapped, the value specified in thestart_va_64 argument can determine if the mapping ispossible and if granularity hints are used in the private page tables.If a shared page-table region is specified by theregion_id_64 argument, the virtual address specifiedby the start_va_64 argument must be on an evenCPU-specific page-table page boundary or an error is returned by thisservice. If the region_id_64 argument does not specifya shared page-table region and the /ALLOCATE qualifier was specifiedwith the SYSMAN command RESERVED_MEMORY ADD for this global section,granularity hints are used only if the virtual alignment ofstart_va_64 is appropriate for the use of granularityhints (either 8-page, 64-page or 512-page alignment).

Whenever granularity hints are being used within the mapping of amemory-resident global section, if the length_64argument is not an exact multiple of the alignment factor, lowergranularity hints factors are used as appropriate at the higheraddressed portion of the global section. If thesection_offset_64 argument is specified, a lowergranularity hint factor can be used throughout the mapping of theglobal section to match the physical alignment of the first page mapped.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments.

If a condition value other than SS$_ACCVIO is returned, the returnedaddress and returned length indicate the pages that were successfullymapped before the error occurred. If no pages were mapped, thereturn_va_64 argument contains the value --1.

Required Privileges

None

Required Quota

If private page tables are used to map to the global section, theworking set limit quota (WSQUOTA) of the process must be sufficient toaccommodate the increased size of the process page tables required bythe increase in virtual address space when the section is mapped.

If private page tables are used to map to a memory-resident globalsection, the pagefile quota (PGFLQUOTA) of the process must besufficient to accommodate the increased size of the process page tablesrequired by the increase in virtual address space.

If the process is mapping to a global copy-on-reference section, thepagefile quota (PGFLQUOTA) of the process must be sufficient toaccommodate the increased size of the virtual address space.

Related Services

$CREATE_GDZRO, $CREATE_GFILE, $CREATE_GPFILE, $CREATE_REGION_64,$CRMPSC_GDZRO_64, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64,$DELETE_REGION_64, $DELTVA_64, $LCKPAG_64, $LKWSET_64, $MGBLSC,$MGBLSC_GPFN_64, $PURGE_WS, $ULKPAG_64, $ULWSET_64, $UPDSEC_64,$UPDSEC_64W

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The gs_name_64 argument cannot be read by the caller, or the return_va_64 argument or the return_length_64 argument cannot be written by the caller.
SS$_EXPGFLQUOTA	The process's page file quota is not large enough to accommodate the increased virtual address space.
SS$_GBLSEC_MISMATCH	Global section type mismatch. The specified global section was found; however, it is not a global disk-file, page-file, or demand-zero section.
SS$_INSFWSL	The process's working set limit is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE	The specified access mode is greater than PSL$_USER or the caller's mode is less privileged than the create mode associated with the region. Or, if a shared page table region is specified by the region_id_64 argument, the acmode argument does not match the access mode of the shared PTEs.
SS$_IVLOGNAM	The specified global section name has a length of 0 or has more than 43 characters.
SS$_IVREGID	An invalid region ID was specified.
SS$_IVSECFLG	An invalid flag, a reserved flag, or an invalid combination of flags was specified.
SS$_IVSECIDCTL	The match control field of the global section identification is invalid.
SS$_LEN_NOTBLKMULT	The length_64 argument is not a multiple of virtual disk blocks if a map to a global section was requested (SEC$M_PAGFIL is clear in the flags argument).
SS$_LEN_NOTPAGMULT	The length_64 argument is not a multiple of CPU-specific pages and a map to a global page file section was requested.
SS$_NOSHPTS	The region ID of a shared page-table region was specified, and a gobal section was specified that is not a memory-resident demand-zero section.
SS$_NOSHPTS	The region ID of a shared page table region was specified.
SS$_NOSUCHSEC	The specified global section does not exist.
SS$_OFF_NOTPAGALGN	The section_offset_64 argument is not CPU-specific page aligned if a map to a global page-file or demand-zero section is requested. Or, if a shared page table region is specified by the region_id_64 argument, the section_offset_64 argument is not CPU-specific page-table page aligned.
SS$_OFFSET_TOO_BIG	The section_offset_64 argument specified is beyond the logical end-of-file.
SS$_PAGNOTINREG	A page in the specified input address range is not within the specified region.
SS$_PAGOWNVIO	A page in the specified input address range already exists and cannot be deleted because it is owned by a more privileged access mode.
SS$_PROTVIO	The file protection mask specified when the global section was created prohibits the type of access requested by the caller.
SS$_REGISFULL	The specified virtual region is full; no space is available in the region for the pages created to contain the mapped section.
SS$_SECREFOVF	The maximum number of references for a global section has been reached (2,147,483,647).
SS$_SECTBLFUL	There are no entries available in the system global section table.
SS$_TOOMANYLNAM	The logical name translation of the gs_name_64 argument exceeded the allowed depth of 10.
SS$_VA_IN_USE	A page in the specified input address range is already mapped and the flag SEC$M_NO_OVERMAP is set, or a page in the specified input address range is in another region, in system space, or inaccessible; or, the existing underlying page cannot be deleted because it is associated with a buffer object.
SS$_VA_NOTPAGALGN	The start_va_64 argument is not CPU-specific page aligned. Or, if a shared page table region is specified by the region_id_64 argument, the start_va_64 argument is not CPU-specific page-table page aligned.
SS$_NOWRTACC	The specified global section is not copy-on-reference and does not allow write access.

On Alpha systems, establishes a correspondence between pages in thevirtual address space of the process and the pages occupied by a globalpage frame section.

This service accepts 64-bit addresses.

Format

SYS$MGBLSC_GPFN_64 gs_name_64 ,ident_64 ,region_id_64 ,relative_page,page_count ,acmode ,flags ,return_va_64 ,return_length_64[,start_va_64]

C Prototype

int sys$mgblsc_gpfn_64 (void *gsdnam_64, struct _secid *ident_64,struct _generic_64 *region_id_64, unsigned int relative_page, unsignedint page_count, unsigned int acmode, unsigned int flags, void*(*(return_va_64)), unsigned __int64 *return_length_64,...);

Arguments

gs_name_64

OpenVMS usage:	section_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor

Name of the global section. The gs_name argument isthe 32- or 64-bit virtual address of a naturally aligned 32-bit or64-bit descriptor pointing to this name string.

You can specify any name from 1 to 43 characters. All processes mappingto the same global section must specify the same name. Note that thename is case sensitive.

Use of characters valid in logical names is strongly encouraged. Validvalues include alphanumeric characters, the dollar sign ($), and theunderscore (_). If the name string begins with an underscore (_), theunderscore is stripped and the resultant string is considered to be theactual name. Use of the colon (:) is not permitted.

Names are first subject to a logical name translation, after theapplication of the prefix GBL$ to the name. If the result translates,it is used as the name of the section. If the resulting name does nottranslate, the name specified by the caller is used as the name of thesection.

Additional information on logical name translations and on section nameprocessing is available in the OpenVMS Programming Concepts Manual.

ident_64

OpenVMS usage:	section_id
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Identification value specifying the version number of a global section.The ident_64 argument is a quadword containing threefields. The ident_64 argument is the 32- or 64-bitvirtual address of a naturally aligned quadword that contains theidentification value.

The first longword specifies the matching criteria in its low-order twobits. The valid values, symbolic names by which they can be specified,and their meanings are as follows:

Value	Symbolic Name	Match Criteria
0	SEC$K_MATALL	Match all versions of the section.
1	SEC$K_MATEQU	Match only if major and minor identifications match.
2	SEC$K_MATLEQ	Match if the major identifications are equal and the minor identification of the mapper is less than or equal to the minor identification of the global section.

If you specify the ident_64 argument as 0, the versionnumber and match control fields default to 0.

The version number is in the second longword. The version numbercontains two fields: a minor identification in the low-order 24 bitsand a major identification in the high-order 8 bits. You can assignvalues for these fields by installation convention to differentiateversions of global sections. If no version number is specified when asection is created, processes that specify a version number whenmapping cannot access the global section.

region_id_64

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The region ID associated with the region to map the private page framesection. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro inSTARLET.MLB define a symbolic name for each of the three defaultregions in P0, P1, and P2 space.

The following region IDs are defined:

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region

Other region IDs, as returned by the $CREATE_REGION_64 service, can bespecified.

relative_page

OpenVMS usage:	CPU-specific page count
type:	longword (unsigned)
access:	read only
mechanism:	by value

Relative CPU-specific page number within the global section to startmapping.

page_count

OpenVMS usage:	CPU-specific page count
type:	longword (unsigned)
access:	read only
mechanism:	by value

Length of mapping in CPU-specific pages. If zero is specified, theglobal page frame section is mapped to the end of the section.

acmode

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

Access mode to be associated with the pages mapped into the processvirtual address space. The acmode argument is alongword containing the access mode. The $PSLDEF macro defines symbolsfor the four access modes.

The most privileged access mode used is the access mode of the caller.Address space cannot be created within a region that has a create modeassociated with it that is more privileged than the caller's mode. Thecondition value SS$_IVACMODE is returned if the caller is lessprivileged than the create mode for the region.

flags

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

Flag mask specifying options for the operation. Theflags argument is a longword bit vector in which eachbit corresponds to a flag. The $SECDEF macro and the SECDEF.H filedefine a symbolic name for each flag. You construct theflags argument by performing a logical OR operation onthe symbol names for all desired flags.

The following table describes each flag that is valid for the$MGBLSC_GPFN_64 service:

Flag	Description
SEC$M_GBL	Pages form a global section. By default, this flag is always present in this service and cannot be disabled.
SEC$M_EXPREG	Map the section into the first available space at the current end of the specified region. If this flag is specified, the start_va_64 argument is not used.
SEC$M_PERM	Pages are permanent. By default, this flag is always present in this service and cannot be disabled.
SEC$M_PFNMAP	Pages form a page frame section. By default, this flag is always present in this service and cannot be disabled.
SEC$M_PAGFIL	Pages form a global page-file section. SEC$M_PAGFIL also implies SEC$M_WRT and SEC$M_DZRO.
SEC$M_SYSGBL	Map a system global section. By default, the section is a group global section.
SEC$M_WRT	Map the section with read/write access. By default, the section is mapped with read-only access. If SEC$M_WRT is specified, write access is required.

All other bits in the flags argument are reserved forfuture use by HP and should be specified as 0. The condition valueSS$_IVSECFLG is returned if any undefined bits are set or if an illegalcombination of flags is set.

return_va_64

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32- or 64-bit reference

The lowest process virtual address into which the global page framesection was mapped. The return_va_64 argument is the32- or 64-bit virtual address of a naturally aligned quadword thatcontains the virtual address.

return_length_64

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference

The 32- or 64-bit virtual address of a naturally aligned quadword intowhich the $MGBLSC_GPFN_64 service returns the length of the virtualaddress range in bytes.

start_va_64

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

The starting virtual address to map the global section. The specifiedvirtual address must be a CPU-specified page-aligned address. If theflag SEC$M_EXPREG is specified, the start_va_64argument must not be specified or must be specified as 0. IfSEC$M_EXPREG is set and the start_va_64 argument isnonzero, the condition value SS$_IVSECFLG is returned.

Always refer to the return_va_64 andreturn_length_64 arguments to determine the range ofvirtual addresses mapped.

Description

The Map Global Page Frame Section service establishes a correspondencebetween pages in the virtual address space of the process and pagesoccupied by a global page frame section. It adds pages to the virtualaddress space of the process.

Pages mapped to a global page frame section are not included in orcharged against the process's working set; they are always valid. Donot lock these pages in the working set by using $LKWSET; this canresult in a machine check if they are in I/O space.

If the condition value SS$_ACCVIO is returned by this service, a valuecannot be returned in the memory locations pointed to by thereturn_va_64 and return_length_64arguments.

If a condition value other than SS$_ACCVIO is returned, the returnedaddress and returned length indicate the pages that were successfullymapped before the error occurred. If no pages were mapped, thereturn_va_64 argument will contain the value -1, and avalue cannot be returned in the memory location pointed to bythe return_length_64 argument.

Required Privileges

Read access is required. If the SEC$M_WRT flag is specified, writeaccess is required.

Required Quota

The working set quota (WSQUOTA) of the process must be sufficient toaccommodate the increased length of the process page table required bythe increase in virtual address space.

The page file quota (PAGFLQUOTA) of the process must be sufficient toaccommodate the increased number of process page tables required by theincrease in virtual address space. (Note that this service can returnthe SS$_EXPGFLQUOTA.)

Related Services

$CREATE_GPFN, $CREATE_REGION_64, $CRMPSC_GPFN_64, $DELETE_REGION_64,$DELTVA_64, $MGBLSC, $MGBLSC_64

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The gs_name_64 argument cannot be read by the caller, or the return_va_64 or return_length_64 argument cannot be written by the caller.
SS$_GBLSEC_MISMATCH	Global section type mismatch. The specified global section was found; however, it is not a global page frame section.
SS$_ILLRELPAG	The specified relative page argument is either larger than the highest page number within the section or is not a valid 32-bit physical page frame number.
SS$_INSFWSL	The working set limit of the process is not large enough to accommodate the increased virtual address space.
SS$_IVACMODE	The caller's mode is less privileged than the create mode associated with the region.
SS$_IVLOGNAM	The specified global section name has a length of 0 or has more than 43 characters.
SS$_IVREGID	Invalid region ID specified.
SS$_IVSECFLG	An invalid flag, a reserved flag, or an invalid combination of flags was specified.
SS$_IVSECIDCTL	The match control field of the global section identification is invalid.
SS$_NOSUCHSEC	The specified global section does not exist.
SS$_NOWRTACC	The specified global section is not copy-on-reference and does not allow write access.
SS$_PROTVIO	The file protection mask specified when the global section was created prohibits the type of access requested by the caller.
SS$_PAGNOTINREG	A page in the specified range is not within the specified region.
SS$_PAGOWNVIO	A page in the specified range already exists and cannot be deleted because it is owned by a more privileged access mode than that of the caller.
SS$_REGISFULL	The specified virtual region is full; no space is available in the region for the pages created to contain the mapped global section.
SS$_TOOMANYLNAM	The logical name translation of the gs_name_64 argument exceeded the allowed depth of 10.
SS$_VA_IN_USE	The existing underlying page cannot be deleted because it is associated with a buffer object.
SS$_VA_NOTPAGALGN	The start_va_64 argument is not CPU-specific page aligned.

Modifies the specified holder record of the target identifier in therights database.

Format

SYS$MOD_HOLDER id ,holder ,[set_attrib] ,[clr_attrib]

C Prototype

int sys$mod_holder (unsigned int id, struct _generic_64 *holder,unsigned int set_attrib, unsigned int clr_attrib);

Arguments

id

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

Binary value of target identifier whose holder record is modified when$MOD_HOLDER completes execution. The id argument is alongword containing the identifier value.

holder

OpenVMS usage:	rights_holder
type:	quadword (unsigned)
access:	read only
mechanism:	by reference

Identifier of holder being modified when $MOD_HOLDER completesexecution. The holder argument is the address of aquadword containing the UIC identifier of the holder in the firstlongword and the value of 0 in the second longword.

set_attrib

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

Bit mask of attributes to be enabled for the identifier when$MOD_HOLDER completes execution. The set_attribargument is a longword containing the attribute mask.

The attributes actually enabled are the intersection of those specifiedand the attributes of the identifier. If you specify the same attributein set_attrib and clr_attrib, theattribute is enabled.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The following symbols for each bitposition are defined in the system macro library ($KGBDEF):

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows the holder to charge resources, such as disk blocks, to the identifier.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

clr_attrib

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

Bit mask of attributes to be disabled for the identifier when$MOD_HOLDER completes execution. The clr_attribargument is a longword containing the attribute mask.

If you specify the same attribute in set_attrib andclr_attrib, the attribute is enabled.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The following symbols for each bitposition are defined in the system macro library ($KGBDEF):

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET RIGHTS_LIST.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows the holder to charge resources, such as disk blocks, to the identifier.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

Description

The Modify Holder Record in Rights Database service modifies thespecified holder record in the rights database. Identifier attributescan be added or removed.

When you specify both the set_attrib andclr_attrib arguments, the attribute is cleared first.Thus, if you specify the same attribute bit with each argument, theresult is that the bit is set.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD,$FIND_HOLDER, $FINISH_RDB, $GET_SECURITY, $GRANTID, $IDTOASC,$MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The holder argument cannot be read by the caller.
SS$_BADPARAM	The specified attributes contain invalid attribute flags.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The specified identifier or holder identifier is of invalid format.
SS$_NOSUCHID	The specified identifier does not exist in the rights database, or the specified holder identifier does not exist in the rights database.
RMS$_PRV	The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMSRMS, this service can also return RMS status codes associated withoperations on indexed files. For descriptions of these status codes,refer to the OpenVMS Record Management Services Reference Manual.

Modifies the specified identifier record in the rights database.

Format

SYS$MOD_IDENT id ,[set_attrib] ,[clr_attrib] ,[new_name] ,[new_value]

C Prototype

int sys$mod_ident (unsigned int id, unsigned int set_attrib, unsignedint clr_attrib, void *new_name, unsigned int new_value);

Arguments

id

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

Binary value of identifier whose identifier record is modified when$MOD_IDENT completes execution. The id argument is alongword containing the identifier value.

set_attrib

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

Bit mask of attributes to be enabled for the identifier when $MOD_IDENTcompletes execution. The set_attrib argument is alongword containing the attribute mask.

The attributes actually enabled are the intersection of those specifiedand the attributes of the identifier. If you specify the same attributein set_attrib and clr_attrib, theattribute is enabled.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The following symbols for each bitposition are defined in the system macro library ($KGBDEF):

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET_RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN	Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves.
KGB$V_NAME_HIDDEN	Allows holders of an identifier to have it translated---either from binary to ASCII or vice versa---but prevents unauthorized users from translating the identifier.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

clr_attrib

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

Bit mask of attributes to be disabled for the identifier when$MOD_IDENT completes execution. The clr_attribargument is a longword containing the attribute mask.

If you specify the same attribute in set_attrib andclr_attrib, the attribute is enabled.

Symbol values are offsets to the bits within the longword. You can alsoobtain the values as masks with the appropriate bit set using theprefix KGB$M rather than KGB$V. The following symbols for each bitposition are defined in the system macro library ($KGBDEF):

Bit Position	Meaning When Set
KGB$V_DYNAMIC	Allows holders of the identifier to remove it from or add it to the process rights list by using the DCL command SET_RIGHTS_LIST.
KGB$V_HOLDER_HIDDEN	Prevents someone from getting a list of users who hold an identifier, unless they own the identifier themselves.
KGB$V_NAME_HIDDEN	Allows holders of an identifier to have it translated---either from binary to ASCII or vice versa---but prevents unauthorized users from translating the identifier.
KGB$V_NOACCESS	Makes any access rights of the identifier null and void. This attribute is intended as a modifier for a resource identifier or the Subsystem attribute.
KGB$V_RESOURCE	Allows holders of an identifier to charge disk space to the identifier. It is used only for file objects.
KGB$V_SUBSYSTEM	Allows holders of the identifier to create and maintain protected subsystems by assigning the Subsystem ACE to the application images in the subsystem.

new_name

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

New name to be given to the specified identifier. Thenew_name argument is the address of the descriptorpointing to the identifier name string.

An identifier name consists of 1 to 31 alphanumeric characters,including dollar signs ($) and underscores (_), and must contain atleast one nonnumeric character. Any lowercase characters specified areautomatically converted to uppercase.

new_value

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

New value to be assigned to the specified identifier. Thenew_value argument is a longword containing the binaryvalue of the specified identifier. When the identifier value ischanged, $MOD_IDENT also changes the value of the identifier in all ofthe holder records in which the specified identifier appears.

Description

The Modify Identifier in Rights Database service modifies the specifiedidentifier record in the rights database. Identifier attributes can beadded or removed. The identifier name or value can be changed. When youspecify both the set_attrib andclr_attrib arguments, the attribute is cleared first.Thus, if you specify the same attribute bit with each argument, theresult is that the bit is set.

Required Access or Privileges

Write access to the rights database is required.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CREATE_RDB, $FIND_HELD,$FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_HOLDER,$REM_HOLDER, $REM_IDENT, $REVOKID

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_NOSUCHID	The specified identifier does not exist in the rights database.
SS$_BADPARAM	The specified attributes contain invalid attribute flags.
SS$_DUPIDENT	The specified identifier value already exists.
SS$_DUPLNAM	The specified identifier name already exists in the rights database.
SS$_INSFMEM	The process dynamic memory is insufficient for opening the rights database.
SS$_IVIDENT	The specified identifier is of invalid format.
RMS$_PRV	The user does not have write access to the rights database.

Because the rights database is an indexed file accessed with OpenVMSRMS, this service can also return RMS status codes associated withoperations on indexed files. For descriptions of these status codes,refer to the OpenVMS Record Management Services Reference Manual.

Mounts a tape, disk volume, or volume set and specifies options for themount operation.

Format

SYS$MOUNT itmlst

C Prototype

int sys$mount (void *itmlst);

Argument

itmlst

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

Item list specifying options for the mount operation. Theitmlst argument is the address of a list of itemdescriptors, each of which specifies an option and provides theinformation needed to perform the operation.

The item list must include at least one device item descriptor and isterminated by a longword value of 0.

The following diagram depicts the format of a single item descriptor:

The following table defines the item descriptor fields:

Item Codes

MNT$_ACCESSED

Specifies the number of directories that will be in use, concurrently,on the volume. The buffer must contain a longword integer value in therange 0 to 255. This value overrides the number of directoriesspecified when the volume was initialized. To specify MNT$_ACCESSED,the caller must have OPER privilege. The MNT$_ACCESSED item codeapplies only to disks.

MNT$_BLOCKSIZE

Specifies the default block size for tape volumes. The buffer mustcontain a longword integer value in the range 20 to 65,532 bytes forOpenVMS RMS operations or 10 to 65,534 bytes for operations that do notuse RMS. The MNT$_BLOCKSIZE item code applies only to tapes.

If you do not specify MNT$_BLOCKSIZE, the default block size is 2048bytes for Files-11 tape volumes and 512 bytes for foreign and unlabeledtapes.

You must specify MNT$_BLOCKSIZE when mounting (1) tapes that do nothave ANSI HDR2 labels, (2) tapes to which data will be written fromcompatibility mode, and (3) tapes that are to contain records whosesize is larger than the default value.

MNT$_COMMENT

Specifies text to be associated with an operator request. The buffermust contain a character string of no more than 78 characters. Thistext will be printed on the operator's console if an operator requestis issued for the device being mounted.

MNT$_DENSITY

Specifies the density at which data is to be written to a foreign orunlabeled tape. The DENSITY item code suppled is dependent on the typeof tape device. If a tape device is capable of using the MT3 densitycodes, the buffer for the MNT$DENSITY item code must contain a longwordwith one of the MT3 codes, as defined in SYS$LIBRARY:STARLET(MT3$K_TK50, MT3$K_3480, MT3$K_SDLT, MT3$K_AIT2, and so on). Refer tothe MT3_SUPPORTED argument for $GETDVI.

If the device does not support MT3 densities, the buffer must contain alongword value that specifies one of the following legal densities: 800bpi, 1600 bpi, or 6250 bpi.

The specified density will be used only if (1) the tape is foreign orunlabeled and (2) the first operation is a write.

MNT$_DEVNAM

Specifies the name of the device to be mounted. The buffer must containa character string of from 1 to 64 characters, which is the devicename. The device name can be a physical device name or a logical name;if it is a logical name, it must translate to a physical device name.

The MNT$_DEVNAM item code must appear at least once in an item list,and it can appear more than once. It appears more than once when avolume set is being mounted, because, in this case, one device is beingmounted for each volume in the volume set.

MNT$_EXTENSION

Specifies the number of blocks by which files will be extended. Thebuffer must contain a longword value in the range 0 to 65,535. TheMNT$_EXTENSION item code applies only to disks.

MNT$_EXTENT

Specifies the size of the extent cache in units of extent pointers. Thebuffer must contain a longword value, which specifies this size. Tospecify MNT$_EXTENT, you need OPER privilege. The value 0 (the default)disables caching. The MNT$_EXTENT item code applies only to disks.

MNT$_FILEID

Specifies the size of the file-ID cache in units of file numbers. Thebuffer must contain a longword value, which specifies this size. Tospecify MNT$_FILEID, you need OPER privilege. The value 1 disablescaching. The MNT$_FILEID item code applies only to disks.

MNT$_FLAGS

Specifies a 2-longword bit vector wherein each bit specifies an optionfor the mount operation. The buffer must contain a quadword, which isthe bit vector.

The $MNTDEF macro defines symbolic names for each option (bit) in thebit vector. You construct the bit vector by specifying the symbolicnames for the desired options in a logical OR operation. In the firstlongword you logically OR the MNT$M_ mask bits, and in the secondlongword you logically OR the MNT2$M_ mask bits. The following tabledescribes the symbolic names for each option. The MNT2$M_ options areat the end of the table.

Option	Description
MNT$M_CLUSTER	The volume is to be mounted for clusterwide access; that is, every OpenVMS Cluster node can access the volume. $MOUNT mounts the volume first on the caller's node and then on every other node in the existing cluster. Only system or group volumes can be mounted clusterwide. If you do not specify MNT$M_GROUP or MNT$M_SYSTEM, $MOUNT mounts the volume as a system volume, provided the caller has SYSNAM privilege. To mount a group volume clusterwide, the caller must have GRPNAM privilege. To mount a system volume clusterwide, the caller must have SYSNAM privilege. MNT$M_CLUSTER has no effect if the system is not a member of a cluster. MNT$M_CLUSTER applies only to disks.
MNT$M_FOREIGN	The volume is to be mounted as a foreign volume; a foreign volume is not Files-11 structured. If you specify MNT$M_FOREIGN, the following item codes can each appear in the item list only once: the caller must either own the volume or have VOLPRO privilege.
MNT$M_GROUP	The logical name for the volume to be mounted is entered in the group logical name table, and the volume is made accessible to other users with the same UIC group number as that of the calling process. To specify MNT$M_GROUP, the caller must have GRPNAM privilege. MNT$M_GROUP applies only to disks.
MNT$M_INCLUDE	Automatically reconstructs a shadow set to the state it was in before the shadow set was dissolved (due to dismounting or system failure). Use this option to mount a shadow set or a volume set of shadow sets. You must specify the exact name of the original virtual unit and the device name of at least one of the shadow set members. The shadowing software reads the shadow set membership information from the named device to determine the membership of the original shadow set. You can include the MNT$M_INCLUDE option in executable images to have a shadow set reconstructed. Using MNT$M_INCLUDE prevents your having to manually reinstate shadow sets after they have been dismounted. If you do not select this option, $MOUNT does not automatically reconstruct the former shadow set.
MNT$M_INIT_CONT	Additional volumes in the volume set are to be initialized without operator intervention. $MOUNT initializes new volumes with the protections specified for the first magnetic tape of the volume set and creates unique volume label names for up to 99 volumes in a volume set.
	If MNT$M_INIT_CONT is specified, you must allocate multiple magnetic tape drives to the volume set. If $MOUNT switches to a drive that has no magnetic tape loaded or has the wrong magnetic tape loaded or if $MOUNT tries to read a magnetic tape that is not loaded, it notifies the operator to load the correct magnetic tape. $MOUNT will dismount and unload volumes as soon as they have been read or written. The operator can load the next volume in the volume set before the current reel of the volume set reaches the end of the magnetic tape.
	If writing to the volume set, $MOUNT automatically (1) switches to the next magnetic tape drive, (2) initializes that magnetic tape with the same volume name and protection as specified in the volume labels of the first volume in the set, and (3) notifies the operator that the switch has occurred. If reading the volume set, $MOUNT generates the label for the next volume in the volume set and reads that volume.
	The label name that $MOUNT generates for each additional volume in the volume set consists of six characters: the first four characters are the same as the first four characters of the label name of the previous volume; the fifth and sixth characters represent the number of the volume in the volume set. MNT$M_INIT_CONT applies only to magnetic tapes.
MNT$M_MESSAGE	Messages will be sent to the caller's SYS$OUTPUT device.
MNT$M_MINICOPY_OPTIONAL	$MOUNT fails if minicopy has not been enabled on the disk.
MNT$M_MINICOPY_REQUIRED	$MOUNT continues even if minicopy has not been enabled on the disk.
MNT$M_MULTI_VOL	Specifies, for foreign or unlabeled magnetic tapes, that subsequent volumes can be processed by overriding MOUNT's access checks. You can use this option when a utility that supports multivolume magnetic tape sets needs to process subsequent volumes, and these volumes do not contain labels that MOUNT can interpret. You need VOLPRO privilege to specify the MNT$M_MULTI_VOL option. MNT$M_MULTI_VOL can only be used with the MNT$M_FOREIGN option. HP recommends the use of this qualifier only when it is not possible to alter the utility to explicitly perform MOUNT and DISMOUNT operations on each reel in the set.
MNT$M_NOASSIST	$MOUNT does not request operator assistance if errors are encountered during the mount operation. If not specified, $MOUNT requests operator assistance to recover from some error conditions.
MNT$M_NOAUTO	Automatic volume labeling (AVL) and automatic volume recognition (AVR) are to be disabled. If MNT$M_NOAUTO is specified, the operator must enter commands from the console to process each additional volume in a volume set. When a volume is finished processing, the operator specifies the drive on which the next volume is loaded and the label name of the next volume. You might want to use MNT$M_NOAUTO to disable AVL and AVR when not reading a volume set sequentially. You can enable AVL and AVR by specifying MNT$M_INIT_CONT. MNT$M_NOAUTO applies only to magnetic tapes.
MNT$M_NOCACHE	All caching associated with the volume is turned off. Specifying MNT$M_NOCACHE is equivalent to (1) specifying MNT$M_WRITETHRU, (2) specifying a value of 1 for the item descriptor MNT$_FILEID, and (3) specifying a value of 0 for the item descriptors MNT$M_EXTENT and MNT$M_QUOTA.
MNT$M_NOCOPY	Disables full copy operations on all physical devices being mounted or added to a shadow set. This option provides you with the opportunity to confirm the states of all of the devices or members of a shadow set before proceeding with any full copy operation. This prevents any accidental loss of data that could occur if an unintended device is added to the shadow set. If you do not select this option, $MOUNT automatically overwrites the data on shadow set members that are not current. When you select this option, a $MOUNT operation fails if any of the specified potential shadow set members require full copy operations.
MNT$M_NODISKQ	Disk quotas are not to be enforced for the volume to be mounted. If not specified, disk quotas are enforced. To specify MNT$M_NODISKQ, the caller must either own the volume or have VOLPRO privilege. MNT$M_NODISKQ applies only to disks.
MNT$M_NOHDR3	ANSI HDR3 and HDR4 labels are not to be written to magnetic tapes as they are mounted. If not specified, ANSI HDR3 and HDR4 labels are written to all tapes. Use MNT$M_NOHDR3 when writing to volumes that will be read by a system, such as the RT-11 system, which does not process HDR3 and HDR4 labels correctly. MNT$M_NOHDR3 applies only to tapes.
MNT$M_NOLABEL	The volume is to be mounted as a foreign volume; a foreign volume is not Files-11 structured. If you specify MNT$M_NOLABEL, the following item codes can each appear in the item list only once: MNT$_DEVNAM, MNT$_VOLNAM, and MNT$_LOGNAM. To specify MNT$M_NOLABEL, the caller must either own the volume or have VOLPRO privilege.
MNT$M_NOMNTVER	The volume is not marked as a candidate for automatic mount verification. If not specified, the volume is marked as a candidate for mount verification.
MNT$M_NOREBUILD	The volume to be mounted should be returned to active use immediately, without performing a rebuild operation. This flag defers the disk rebuild operation, so that the volume to be mounted is returned to active use immediately. A rebuild operation can consume a considerable amount of time, depending on the number of files on the volume and on the number of different file owners (if quotas are in use). The volume can be rebuilt later with the DCL command SET VOLUME/REBUILD to recover the free space; for more information, refer to the HP OpenVMS DCL Dictionary. If a disk volume is improperly dismounted, for example, during a system failure, it must be rebuilt to recover any caching limits that were enabled on the volume at the time of the dismount. By default, $MOUNT attempts to rebuild. When mounting a volume set, you must mount all members of the set to reclaim all available free space. MNT$M_NOREBUILD applies only to disks.
MNT$M_NOUNLOAD	The volume to be mounted is not to be unloaded when it is dismounted. Specifying MNT$M_NOUNLOAD causes the volume to remain loaded when it is dismounted unless the dismount explicitly requests that the volume be unloaded.
MNT$M_NOWRITE	The volume to be mounted is software write locked. If not specified, the volume is assumed to have read and write access.
MNT$M_OVR_ACCESS	If the installation allows, this option overrides any character in the accessibility field of the volume. The necessity of this option is defined by the installation. That is, each installation has the option of specifying a routine that the magnetic tape file system will use to process this field. By default, the operating system provides a routine that checks this field in the following manner: If the magnetic tape was created on a version of the operating system that conforms to Version 3 of ANSI, then you must use this option to override any character other than an ASCII space. If a protection is specified and that magnetic tape conforms to an ANSI standard that is higher than Version 3, then you must use this option to override any character other than an ASCII 1. To specify MNT$M_OVR_ACCESS, the caller must either own the volume or have VOLPRO privilege. MNT$M_OVR_ACCESS applies only to tapes.
MNT$M_OVR_EXP	A tape that has not yet reached its expiration date can be overwritten. To specify MNT$M_OVR_EXP, the caller must own the volume or have VOLPRO privilege.
MNT$M_OVR_IDENT	You can mount the volume without specifying the volume name (by using the MNT$_VOLNAM item code). If specified, the following options must not be specified: MNT$M_CLUSTER, MNT$M_GROUP, MNT$M_SHARE, and MNT$M_SYSTEM.
MNT$M_OVR_LOCK	The software write lock that occurs when a volume has a corrupted storage bit mask can be overridden.
MNT$M_OVR_SETID	Checks on the volume set identification are not to be performed when subsequent reels in the volume set are mounted. MNT$M_OVR_SETID applies only to tapes.
MNT$M_OVR_SHAMEM	Allows you to mount former shadow set members outside of the shadow set. If you do not specify this option, $MOUNT automatically mounts the volume write-locked to prevent accidental deletion of data. To specify this option, you must either own the volume or have VOLPRO privilege. When you use this option, the shadow set generation number is erased from the volume. If you then remount the volume in the former shadow set, $MOUNT considers it an unrelated volume and marks it for a full copy operation.
MNT$M_OVR_VOLO	The volume label's owner identifier field is not to be processed. $MOUNT reads volume owner and protection information from the volume owner field of the volume labels. The operating system requires that you specify MNT$M_OVR_VOLO to process magnetic tapes when all of the following conditions exist: (1) the volume was created on an operating system other than OpenVMS; (2) the volume was initialized with a protection specified; and (3) the volume conforms to the Version 3 ANSI label standard. To specify MNT$M_OVR_VOLO, the caller must either have VOLPRO privilege or own the volume. MNT$M_OVR_VOLO applies only to tapes.
MNT$M_READCHECK	Read checks are to be performed following all read operations.
MNT$M_REQUIRE_MEMBERS	Controls whether every physical device specified with the /SHADOW qualifier must be accessible when the MOUNT command is issued in order for the $MOUNT system service to take effect.
MNT$M_SHARE	Volume is to be mounted shared and is therefore accessible to other users. MNT$M_SHARE applies only to disks. If the volume was previously mounted shared by another user and MNT$M_SHARE is specified in the current call, all other options specified in the current call are ignored. If the caller allocated the device and specified MNT$M_SHARE in the call to $MOUNT, $MOUNT will deallocate the device so that other users can access the volume.
MNT$M_SYSTEM	The logical name for the volume to be mounted is entered in the system logical name table, and the volume is made accessible to all other users, provided that UIC-based protection allows access to the volume. To specify MNT$M_SYSTEM, the caller must have SYSNAM privilege. MNT$M_SYSTEM applies only to disks.
MNT$M_TAPE_DATA_WRITE	Enables the tape controller's write cache for this device. Enabling the write cache improves data throughput for write operations. By default, the tape controller's write cache is disabled for the device. This option applies only to tape systems that support a write cache.
MNT$M_VERIFY_LABEL	Requires that any member to be added to the shadow set have a volume label of SCRATCH_DISK. This helps ensure that the wrong disk is not added to a shadow set. If you plan to use VERIFY_LABEL, you must first assign the disk to a label. You can do this either by initializing the disk to be added to the set with the label SCRATCH_DISK, or by specifying the label for the disk with the SET VOLUME/LABEL command.
MNT$M_WRITECHECK	Write checks are to be performed after all write operations.
MNT$M_WRITETHRU	Disables the deferred write feature for file headers. By default this feature is enabled, which improves the performance of the applications, such as PATHWORKS, that use it. The deferred write feature is not available on Files-11 ODS-1 volumes.
MNT2$M_CDROM	Mounts a volume assuming the media to be ISO 9660 (or High Sierra) formatted.
MNT2$M_COMPACTION	Enables data compaction for those magnetic tapes that support data compaction (TA90, TA91, and others).
MNT2$M_DISKQ	Controls whether quotas are to be enforced on the specified disk volume.
MNT2$_DSI	Enables XAR permissions Owner and Group for XARs containing DIGITAL System Identifiers (DSI). For more information, refer to the OpenVMS Record Management Services Reference Manual.
MNT2$_INCLUDE	Automatically reconstructs a former shadow set to the way it was before the shadow set was dissolved. Applicable only if you have the volume shadowing option. For more information, refer to HP Volume Shadowing for OpenVMS.
MNT2$M_NOCOMPACTION	Forces the density to no compaction for those magnetic tapes that support data compaction (TA90, TA91, and others).
MNT2$_OVR_LIMITED_SEARCH	For disk type devices that do not provide for bad-block revectoring, it is possible that the Files-11 homeblock has been placed numerous I/Os from the start of the volume. To decrease the failover time when accessing media which does not contain a valid Files-11 homeblock, a limited-search algorithm was implemented. This switch overrides the limited-search algorithm so that the entire volume will be searched for a valid Files-11 homeblock.
MNT2$M_OVR_NOFE	This bit mask is set to override those SCSI devices that do not support forced error functionality. By overriding those SCSI devices not supporting forced error capabilities, MNT2$M_OVR_NOFE enables those devices to be mounted; otherwise, the shadowing code would report to $MOUNT that the device does not support forced error, and the device would not be mounted.
MNT2$_OVR_SECURITY	Enables you to continue mounting a volume if an error is returned because the volume has an invalid SECURITY.SYS file. You must have the VOLPRO privilege or own the volume to use this keyword.
MNT2$M_SUBSYSTEM	Enables the processing of protected subsystem identifiers on the volume. By default, subsystem identifiers are ignored on all but the system disk. Requires SECURITY privilege.
MNT2$M_XAR	Enables enforcement of the extended record attribute (XAR) access controls. For more information about XAR, refer to the HP OpenVMS System Manager's Manual.

MNT$_LIMIT

Specifies the maximum amount of free space in the extent cache. Thebuffer must contain a longword value, which specifies the amount offree space in units of tenths of a percent of the disk's total freespace. The MNT$_LIMIT item code applies only to disks.

MNT$_LOGNAM

Specifies a logical name for the volume; this logical name is equatedto the device name specified by the first MNT$_DEVNAM item code. Thebuffer must contain a character string from 1 to 64 characters, whichis the logical name.

Unless you specify MNT$M_GROUP or MNT$M_SYSTEM, the logical name isentered in the process logical name table.

MNT$_OWNER

Specifies the UIC to be assigned ownership of the volume. The buffermust contain a longword octal value, which is the UIC. If the volume isFiles-11 structured, the specified value overrides the ownershiprecorded on the volume. You need either VOLPRO privilege or ownershipof the volume to assign a UIC to a Files-11 structured volume.

MNT$_PROCESSOR

For magnetic tapes and Files-11 On-Disk Structure Level 1 disks,MNT$_PROCESSOR specifies the name of the ancillary control process(ACP) that is to process the volume. The specified ACP overrides thedefault ACP associated with the device.

For Files-11 On-Disk Structure Level 2 disks, MNT$_PROCESSOR controlsblock cache allocation.

To specify MNT$_PROCESSOR, the caller must have OPER privilege.

The buffer must contain a character string specifying either the stringUNIQUE, a device name, or a file specification. Following is adescription of the action taken for each of these cases:

String	Description
UNIQUE	For magnetic tapes and Files-11 Structure Level 1 disks, UNIQUE specifies that $MOUNT create a new process to execute a copy of the default ACP image associated with the device specified by the MNT$_DEVNAM item code. For Files-11 Structure Level 2 disks, UNIQUE allocates a separate block cache.
ddcu	For magnetic tapes and Files-11 Structure Level 1 disks, ddcu specifies that $MOUNT use the ACP process currently being used by the device ddcu. The device specified must be in the format ddcu, for example, DRA3. For Files-11 Structure Level 1 disks, ddcu specifies that $MOUNT take the block allocation from the specified device.
filespec	Specifies that $MOUNT create a new process to execute the ACP image with the file specification filespec. Wildcard characters are not allowed in the file specification. The file must be in the disk and directory specified by the logical name SYS$SYSTEM. This operation requires CMKRNL privilege.

MNT$_QUOTA

Specifies the size of the quota record cache in units of quota records.The buffer must contain a longword value, which is this size. Tospecify MNT$_QUOTA, you need OPER privilege. The value 0 disablescaching. The MNT$_QUOTA item code applies only to disks.

MNT$_RECORDSIZ

Specifies the number of characters in each record and is used withMNT$_BLOCKSIZE to specify the data formats for foreign volumes. Thebuffer must contain a longword value less than or equal to the blocksize. The MNT$_RECORDSIZ item code applies only to tapes.

If you do not specify MNT$_RECORDSIZ, the record size is assumed to beequal to the block size.

MNT$_SHAMEM

Specifies the name of a physical device to be mounted into a shadowset. The MNT$_SHAMEM descriptor is a 1- to 64-character stringcontaining the device name. The string can be a physical device name ora logical name; if it is a logical name, it must translate to aphysical device name. An item list must contain at least one itemdescriptor specifying a member; this item descriptor must appear afterthe MNT$_SHANAM item descriptor.

Volume Shadowing for OpenVMS automatically performs a copy or a mergeoperation, if necessary, when it mounts the disk into the shadow set.

MNT$_SHANAM

Specifies the name of the virtual unit to be mounted. The buffer is a1- to 64-character string containing the device name. The virtual unitname can be a logical name; if it is a logical name, it must translateto a virtual unit name.

Because every shadow set is represented by a virtual unit, you mustinclude at least one MNT$_SHANAM item descriptor in the item list thatyou pass to $MOUNT to create and mount the shadow set. If you aremounting a volume set containing more than one shadow set, you mustinclude one MNT$_SHANAM item descriptor for each virtual unit includedin the volume set.

The relative position of the item descriptors in the item listdetermines the membership of the shadow set. That is, it indicateswhich members should be bound to a specific virtual unit to form theshadow set. You must first specify the virtual unit by using theMNT$_SHANAM item code. Then, you can specify any number of members thatare to be represented by that virtual unit by using one of thefollowing item codes: MNT$_SHAMEM, MNT$_SHAMEM_COPY, orMNT$_SHAMEM_MGCOPY. If you specify one shadow set and want to specify asecond, specify a second virtual unit item descriptor. The members youspecify subsequently are bound to the shadow set represented by thevirtual unit specified in the second virtual unit item descriptor.

MNT$_UCS

Specifies a descriptor containing a Universal Character Sequence (UCS)defined by ISO 2022 and used when mounting an ISO 9660 CD-ROM. For moreinformation, refer to the HP OpenVMS System Manager's Manual.

MNT$_UNDEFINED_FAT

Specifies the default file attributes to be used for the records on ISO9660 media for which no record format has been specified.

The buffer contains a 32-bit structure that defines a file's recordformat, record attributes, and maximum record size.

The following diagram depicts the structure of the Undefined FileAttributes buffer:

The following table defines the buffer fields:

MNT$_VOLNAM

The operating system requires disk volume labels to be unique in thefirst 12 characters within a given domain.

The MNT$_VOLNAM item code can appear more than once in an item list; itappears more than once when a volume set is being mounted because, inthis case, one volume name is given to each volume in the volume set.

When a disk volume set is being mounted, you must specify MNT$_DEVNAMand MNT$_VOLNAM once for each volume of the volume set. The $MOUNTservice mounts the volume specified by the first MNT$_VOLNAM item codeon the device specified by the first MNT$_DEVNAM item code in the itemlist; it mounts the volume specified by the second MNT$_VOLNAM code onthe device specified by the second MNT$_DEVNAM code, and so on for allspecified volumes and devices. Thus, there must be an equal number ofthese two item codes in the item list.

When a tape volume set is being mounted, the number of MNT$_DEVNAM itemcodes specified need not be equal to the number of MNT$_VOLNAM itemcodes specified, because more than one volume can be mounted on thesame device.

MNT$_VOLSET

An ISO 9660 volume set name can be from 1 to 128 characters in length.

Volume set names must be unique in the first 12 characters. Inaddition, if the first 12 characters of the volume set name are thesame as the first 12 characters of any volume label, a lock managerdeadlock will occur. To avoid this problem, you must override eitherthe volume label (by using the MNT$_VOLNAM item code) or the volume setname (by using the MNT$_VOLSET item code).

When you specify MNT$_VOLSET, volumes specified by the MNT$_VOLNAM itemcode are bound into a new volume set or added to an existing volumeset, depending on whether the name specified by MNT$_VOLSET is a new oralready existing name.

When you specify MNT$_VOLSET to add volumes to an existing volume set,the root volume (RVN1) must either (1) already be mounted or (2) bespecified first (by the MNT$_DEVNAM and MNT$_VOLNAM item codes) in theitem list.

When you specify MNT$_VOLSET to create a new volume set, the firstvolume specified (by the MNT$_DEVNAM and MNT$_VOLNAM item codes) in theitem list becomes the root volume.

MNT$_VPROT

The protection mask consists of four 4-bit fields. Each field grants ordenies read, write, logical, and physical access to a category ofusers. Cleared bits grant access; set bits deny access. The followingdiagram depicts the structure of the protection mask:

If you do not specify MNT$_VPROT or specify it as the value 0, thevolume receives the protection that it was assigned when it wasinitialized. To specify MNT$_VPROT for a Files-11 structured volume,the caller must either own the volume or have VOLPRO privilege.

MNT$_WINDOW

When a file is opened, the file system uses the mapping pointers toaccess the data in the file. To specify MNT$_WINDOW, you need OPERprivilege.

Description

The Mount Volume service mounts a tape, disk volume, or volume set andspecifies options for the mount operation.

When a subprocess mounts a private volume without explicitly allocatingthe device, the master process of the job becomes the owner of thisdevice. This provision is necessary because the subprocess can bedeleted and the volume should remain privately mounted for this job.

When a subprocess explicitly allocates a device and then mounts aprivate volume on this device, this subprocess retains the deviceownership. In this case, only subprocesses of the device owner, andprocesses with SHARE privilege, have access to the device.

The $MOUNT service uses the following system resources to mount volumeswith group or systemwide access allowed:

• Nonpaged pool
• Paged pool

When $MOUNT mounts a disk volume, the logical name DISK$volume-label isalways created. If you specify a logical name in the mount request thatis different from DISK$volume-label, there will be two logical namesassociated with the device.

If the logical name of a volume is in a process-private table, then thename is not deleted when the volume is dismounted.

Required Access or Privileges

To mount a volume on a device, you must have read or control access tothat device.

To mount a particular volume, the caller must either own or haveprivilege to access the specified volume or volumes. The privilegesrequired depend on the operation and are listed with the item codesthat specify the operation.

The calling process must have TMPMBX or PRMMBX privilege to perform anoperator-assisted mount. SECURITY privilege is required to enableprotected subsystems.

Required Quota

None

Related Services

$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,$DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG,$GETQUI, $GETQUIW, $INIT_VOL, $PUTMSG, $QIO, $QIOW, $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; an illegal item code was specified; or no device was specified.
SS$_NOGRPNAM	The caller does not have GRPNAM privilege.
SS$_NOHOMEBLK	Files-11 home block not found on volume.
SS$_NOOPER	The caller does not have the required OPER privilege.
SS$_NOPRIV	The caller does not have sufficient privilege to access a specified volume.
SS$_NOSUCHDEV	The specified device does not exist on the host system.
SS$_NOSYSNAM	The caller does not have SYSNAM privilege.

The $MOUNT service can also return a condition value that is specificto the Mount utility. The symbolic definition macro $MOUNDEF definesthese condition values.

Allows installations to provide their own routine to interpret andoutput the accessibility field in the VOL1 and HDR1 labels of an ANSIlabeled magnetic tape.

Format

SYS$MTACCESS lblnam ,[uic] ,[std_version] ,[access_char] ,[access_spec],type

C Prototype

int sys$mtaccess (unsigned int *lblnam, unsigned int uic, unsigned intstd_version, unsigned int access_char, unsigned int access_spec,unsigned int type);

Arguments

lblnam

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

ANSI label to be processed. The lblnam argument is theaddress of a longword containing the label. On input, the label passedis either the VOL1 or HDR1 label read from the magnetic tape; on outputof labels, the value of this field is 0. The type of label passed isdetermined by type.

uic

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

UIC of the user performing the operation. The uicargument is a longword containing the UIC.

std_version

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

Decimal equivalent of the ANSI standard version read from the VOL1label. The std_version argument is a longwordcontaining the standard version number.

access_char

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

Accessibility character specified by the user. Theaccess_char argument is a byte containing theaccessibility character used for the output of labels.

access_spec

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

Value specifying whether the accessibility character passed inaccess_char was specified by the user.

The access_spec argument is a byte containing one ofthe following values:

Value	Meaning
MTA$K_CHARVALID	Yes
MTA$K_NOCHAR	No

This argument is used only for the output of labels.

type

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

Type of accessibility field to process.

The type argument is a byte containing one of thefollowing values:

Value	Meaning
MTA$K_INVOL1	Input a VOL1 label
MTA$K_INHDR1	Input a HDR1 label
MTA$K_OUTVOL1	Output a VOL1 label
MTA$K_OUTHDR1	Output a HDR1 label

Description

The Magnetic Tape Accessibility service allows installations to providetheir own routine to interpret and output the accessibility field inthe VOL1 and HDR1 labels of ANSI labeled magnetic tapes. Theinstallation can override the default routine by providing anMTACCESS.EXE executive loaded image.

The default installation routine first checks the ANSI standard versionof the label. For magnetic tapes with a version number of 3 or less,the routine outputs either a blank or the character you specified. Oninput of these magnetic tapes, the routine checks for a blank andreturns the value SS$_FILACCERR if the field is not blank.

For magnetic tapes with a version number greater than 3, the routineoutputs either the character specified by theaccess_char argument or an ASCII 1 if no character wasspecified. On input of these magnetic tapes, the routine checks for ablank. If the field is blank, R0 is set to 0. In that case, you aregiven full access and protection is not checked. If the field containsan ASCII 1, and the VOL1 Implementation Identifier field contains thesystem code, R0 is set to SS$_NORMAL. In that case, the protection ischecked.

If the field is not blank and does not contain an ASCII 1, R0 is set toSS$_FILACCERR, which forces you to override accessibility checking andallows the magnetic tape file system to check protection.

The following table summarizes the results of label input check:

Contents of R0	Result
SS$_NORMAL	Check the protection on the magnetic tape.
0	Give the user full access. Protection is not checked.
SS$_FILACCERR	Check for explicit override, then check protection.

Note that the default accessibility routine does not outputSS$_NOVOLACC or SS$_NOFILACC. These statuses are included for theinstallation's use, and the magnetic tape file system handles thesecases.

The magnetic tape file system calls $MTACCESS to process theaccessibility field in the VOL1 and HDR1 labels. After a call to thesystem service, the magnetic tape file system checks that theinstallation did not move the magnetic tape. If the magnetic tape wasmoved, the magnetic tape file system completes the current operationwith an SS$_TAPEPOSLOST error. Finally, it processes the remainder ofthe label according to the status returned by $MTACCESS.

Required Access or Privileges

Because accessibility is an installation-provided routine, theoperating system cannot determine which users have the authority tooverride the processing of this field. However, the magnetic tape filesystem allows only operator class users to deal with blank magnetictapes so that a user must have both OPER and VOLPRO privileges toinitialize or mount blank magnetic tapes.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,$ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL,$FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC,$MOD_HOLDER, $MOD_IDENT, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID,$SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_FILACCERR	The accessibility characteristic in the HDR1 label is not blank and you cannot access the file without overriding the field.
SS$_NOFILACC	The user has no access to the file.
SS$_NOVOLACC	The user has no access to the volume.

Converts an absolute or delta time from 64-bit system time format tobinary integer date and time values.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$NUMTIM timbuf ,[timadr]

C Prototype

int sys$numtim (unsigned short int timbuf [7], struct _generic_64*timadr);

Arguments

timbuf

OpenVMS usage:	vector_word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Buffer into which $NUMTIM writes the converted date and time. Thetimbuf argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a 7-word structure.

The following diagram depicts the fields in this structure:

If the timadr argument specifies a delta time, $NUMTIMreturns the value 0 in the year since 0 and month of year fields. Itreturns in the day of month field the number of days specified by thedelta time.

timadr

If you do not specify timadr, $NUMTIM returns thecurrent system time.

If timadr specifies the value 0, $NUMTIM returns thebase date (November 17, 1858).

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The 64-bit time value cannot be read by the caller, or the buffer cannot be written by the caller.
SS$_IVTIME	The specified delta time is equal to or greater than 10,000 days.

Converts an absolute 128-bit binary time into its numeric components.The numeric components are returned in local time.

On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$NUMUTC timbuf ,[utcadr]

C Prototype

int sys$numutc (unsigned short int timbuf [13], unsigned int *utcadr[4]);

Arguments

timbuf

OpenVMS usage:	vector_word_unsigned
type:	word
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Buffer into which $NUMUTC writes the converted date and time. Thetimbuf argument is the 32-bit address (on VAX systems)or the 32- or 64-bit address (on Alpha systems) of a 13-word structurecontaining time, inaccuracy of time, and time differential factor. Thetime differential factor encoded in the 128-bit buffer is used toconvert the UTC to its numerical components. Negative values in theinaccuracy field indicate an infinite inaccuracy.

The following diagram depicts the fields in this structure:

utcadr

The utcadr argument is optional; if it is not used,$NUMUTC will use the current time.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_INVTIME	The 128-bit UTC time is not valid.

The Next Volume service allows you to process the next tape volume in amultiple volume set. This service applies only to files on magnetictape volumes.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

The Open service makes an existing file available for processing byyour program. The Open service specifies the type of record access tobe used and determines whether the file can be shared. The Open servicealso performs an implicit Display service.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

The Parse service analyzes the file specification string and fills invarious NAM block fields.

Refer to the OpenVMS Record Management Services Reference Manual for additional information about thisservice.

Parses the specified text string and converts it to the binaryrepresentation for an access control entry (ACE).

Format

SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam] ,[nullarg]

C Prototype

int sys$parse_acl (void *aclstr, void *aclent, unsigned short int*errpos, void *accnam, int (*routin)(void));

Arguments

aclstr

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

Formatted ACE that is parsed when $PARSE_ACL completes execution. Theaclstr argument is the address of a string descriptorpointing to the text string to be parsed.

aclent

OpenVMS usage:	char_string
type:	character-coded text string
access:	write only
mechanism:	by descriptor--fixed-length string descriptor

Description of the ACE that is parsed when $PARSE_ACL completesexecution. The aclent argument is the address of adescriptor pointing to the buffer in which the ACE is written. Thefirst byte of the buffer contains the length of the ACE; the secondbyte contains a value that identifies the type of ACE, which in turndefines the format of the ACE.

For information about the ACE types and their associated formats, see$FORMAT_ACL system service documentation.

errpos

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Number of characters from aclstr processed by$PARSE_ACL. The errpos argument is the address of aword that receives the number of characters actually processed by theservice. If the service fails, this count points to the failing pointin the string.

accnam

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

Names of the bits in the access mask when $PARSE_ACL is executing. Theaccnam argument is the address of an array of 32quadword descriptors that define the names of the bits in the accessmask. Each element points to the name of a bit. The first element namesbit 0, the second element names bit 1, and so on.

You can call LIB$GET_ACCNAM to retrieve the access name table for theclass of object whose ACL is to be formatted. If you omitaccnam, the following names are used:

Bit	Name
Bit 0	READ
Bit 1	WRITE
Bit 2	EXECUTE
Bit 3	DELETE
Bit 4	CONTROL
Bit 5	BIT_5
Bit 6	BIT_6
. . .
Bit 31	BIT_31

nullarg

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

Placeholding argument reserved to HP.

Description

The Parse Access Control List Entry service parses the specified textstring and converts it to the binary representation for an accesscontrol entry (ACE).

Required Access or Privileges

None

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB,$ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL,$FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $IDTOASC,$MOD_HOLDER, $MOD_IDENT, $MTACCESS, $REM_HOLDER, $REM_IDENT, $REVOKID,$SET_SECURITY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The string or its descriptor cannot be read by the caller; the buffer descriptor cannot be read by the caller; the buffer cannot be written by the caller; or the buffer is too small to hold the ACL entry.
SS$_IVACL	The format of the access control list entry is not valid.
SS$_NOSUCHID	The specified identifier does not exist in the rights database.

On Alpha systems, disables user process alignment fault reporting.

Format

SYS$PERM_DIS_ALIGN_FAULT_REPORT

C Prototype

int sys$perm_dis_align_fault_report (void);

Arguments

None.

Description

The Disable Alignment Fault Reporting service disables user processalignment fault reporting.

See the description of the $PERM_REPORT_ALIGN_FAULT service for anexample of a program that can be used to enable and disable userprocess alignment fault reporting.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT,$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,$STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL

The service completed successfully.

On Alpha systems, initializes user process alignment fault reporting.

Format

SYS$PERM_REPORT_ALIGN_FAULT

C Prototype

int sys$perm_report_align_fault (void);

Arguments

None.

Description

The Report Alignment Fault service allows the user to permanentlyenable user process alignment fault reporting for all subsequent images.

This service reports alignment faults only in exception mode. For moreinformation about reporting modes, see the $START_ALIGN_FAULT_REPORTservice.

Image alignment fault reporting takes precedence over process alignmentfault reporting; that is, if both image and process alignment faultreporting are enabled, faults are reported to the image first.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $GET_SYS_ALIGN_FAULT_DATA,$INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT,$START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT,$STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

SS$_NORMAL

The service completed successfully.

Example

/**********************************************************************//*                                                                    *//* SET_ALIGN_REPORT.C                                                 *//*                                                                    *//*  This program can be used to permanently turn on and off           *//*  alignment fault reporting for a process. After creating the       *//*  executable, do:                                                   *//*                                                                    *//*        $ align :== $dir:set_align_report.exe                       *//*        $ align on                                                  *//*        $ run program        ! will generate align faults on screen *//*        $ align off                                                 *//*        $ run program        ! will not generate align faults       *//*                                                                    *//**********************************************************************/#include <stdio>#include <ctype>#include <ssdef>/*                alignment fault reporting system services           */extern         sys$perm_report_align_fault(),               sys$perm_dis_align_fault_report();main(argc, argv)  int                argc;  char               *argv[];{  int                status;  /* check arguments */  if (argc < 2) {    printf ("Insufficient arguments\n");    return (40);  }  /* check if the argument is on or off */  if ((strcmp ("ON", argv[1]) == 0) || (strcmp ("on", argv[1]) == 0))    /* on, turn alignment fault reporting on for this process */    status = sys$perm_report_align_fault ();  else if ((strcmp ("OFF", argv[1]) == 0) || (strcmp ("off", argv[1]) == 0))    /* off, turn alignment fault reporting off for this process */    status = sys$perm_dis_align_fault_report ();  else    return (SS$_BADPARAM);  /* return status */  return (status);}      

This example shows a program that can be used to enable and disablealignment fault reporting for a process.

Modifies the context of the current process to match the context of agiven persona. The $PERSONA_ASSUME service allows an OpenVMS process toassume the identity of another user or to discard a persona to returnthe process to its original state.

Format

SYS$PERSONA_ASSUME persona ,[flags]

C Prototype

int sys$persona_assume (unsigned int *persona, unsigned int flags);

Arguments

persona

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

Address of a longword in which the persona identification handle isexpected.

If the value of the context passed is 1, then the current persona isdiscarded, and the state of the calling process is returned to thestate that existed prior to the first call to $PERSONA_CREATE.

flags

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

Flag mask specifying which Persona services options are to be employedwhen the persona is assumed. This argument is ignored when a persona isbeing discarded.

The following table describes each flag:

Flag	Description
IMP$M_ASSUME_SECURITY	Assume access rights, UIC, authorized privileges, user name, and security audit flag.
IMP$M_ASSUME_ACCOUNT	Assume OpenVMS account.
IMP$M_ASSUME_JOB_WIDE	Assume the new persona, even in a multiprocess job.

Description

When assuming a persona using the IMP$M_ASSUME_SECURITY option, anypreviously enabled image privileges will be disabled. The caller'sprocess will have only the privileges of the impersonated user enabled.These privileges are enabled in the Current, Process, and Authorizedprivilege masks.

When using IMP$M_ASSUME_SECURITY, access to the job logical name tablemight no longer be possible because the table is protected by the UICof the user on whose behalf the current process was created. Also, anew access to the process' controlling terminal might fail, and theprocess might be in a different default resource domain for locking.

Any persona is automatically discarded and deleted upon image exit.Hence, it is not possible to permanently change the persona of aprocess using $PERSONA_ASSUME.

The arguments are read in caller's mode, so an invalid argument cancause an access violation to be signaled.

Required Access or Privileges

None

Required Quota

None

Related Services

$PERSONA_CREATE, $PERSONA_DELETE

Condition Values Returned

SS$_NORMAL	The service completed successfully; the desired access is granted.
IMP$_NOCHJIB	The Job Information Block cannot be modified.
IMP$_PERSONANONGRATA	Invalid persona argument.

Allows an OpenVMS thread to assume the identity of another persona.

Format

SYS$PERSONA_ASSUME persona ,[flags], [previous], [acmode]

C Prototype

int sys$persona_assume (unsigned int *persona, unsigned int flags,unsigned int *previous, unsigned int acmode);

Arguments

persona

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

Address of a longword in which the persona identification handle isexpected.

If the value passed is ISS$C_ID_NATURAL, then the state of the callingthread is returned to the natural persona.

flags

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

Ignored.

previous

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the persona identification handle ofthe currently active persona being replaced is written.

acmode

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

Access mode to be considered when assuming a persona. Theacmode argument is a longword containing the accessmode.

The most privileged access mode used is the access mode of the caller.Only equal or more privileged access modes can use this persona.

Description

This service establishes the specified persona as the active securityprofile and returns the persona identification handle of the personathat was active at the point in which the call to this service was made.

On image exit, the natural persona is assumed and all nonpermanentpersonae are deleted.

The arguments are validated against the caller's mode, so an invalidargument can cause an access violation to be signaled.

Required Access or Privileges

None

Required Quota

None

Related Services

$PERSONA_CLONE, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully; the desired access is granted.
SS$_ACCVIO	Access violation.
SS$_INSFARG	Certain required arguments were not specified.
SS$_IVMODE	The caller cannot create a persona that is more privileged than the caller.
SS$_NOPRIV	The operation requires IMPERSONATE privilege.
SS$_PERSONANONGRATA	Invalid persona argument.

Creates a copy of an existing persona within the context of the currentprocess. The service returns the assigned persona identification forthe new persona in the persona argument. This personacan be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CLONE persona ,[input]

C Prototype

int sys$persona_clone (unsigned int *persona, unsigned int *input);

Arguments

persona

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the persona identification handle iswritten.

input

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword containing the persona identification of thepersona to be cloned. If this argument is 0, null, or absent, thecurrently active persona is cloned.

Description

The Clone Persona service creates a copy of an existing persona withinthe context of the current process. The service returns the assignedpersona identification for the new persona in thepersona argument. This persona can be assumed usingthe $PERSONA_ASSUME service.

On image exit, the natural persona is assumed and all nonpermanentpersonae are deleted.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CREATE, $PERSONA_CREATE_EXTENSION,$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	Access violation.
SS$_EXQUOTA	The caller lacks sufficient quota to allocate a new persona.
SS$_INSFMEM	Insufficient memory.
SS$_IVMODE	The caller cannot create a persona that is more privileged than the caller.
SS$_PERSONANONGRATA	The persona ID supplied was invalid.

Creates a persona that can be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CREATE persona ,usrnam ,flags

C Prototype

int sys$persona_create (unsigned int *persona, void *usrnam, unsignedint flags);

Arguments

persona

OpenVMS usage:	integer
type:	longword (unsigned)
access:	write
mechanism:	by reference

Address of a longword into which the persona identification handle iswritten.

usrnam

OpenVMS usage:	char_string
type:	character coded text string
access:	read only
mechanism:	by descriptor - fixed-length descriptor

Name of the user to be impersonated. The usrnamargument is the address of a descriptor pointing to a character stringcontaining the user name. The string can contain a maximum of 12alphanumeric characters.

flags

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

Flag mask specifying which Persona services options are to be employedwhen the persona is created.

The following table describes each flag:

Flag	Description
IMP$M_ASSUME_DEFPRIV	Create a persona with only default privileges.
IMP$M_ASSUME_DEFCLASS	Create a persona with default classification.

Description

On calling the Create Persona service, the required informationconcerning the OpenVMS user specified by the usrnamargument is read from the User Authorization File and Rights databaseand is stored in system memory. A handle that identifies the createdpersona is returned in the persona argument.

It is not possible to create a persona for a user name that has beendisabled.

No changes are made to the caller's process as a result of calling$PERSONA_CREATE.

Some of the $PERSONA_CREATE service executes in the caller's accessmode (assumed to be user mode). An improper use of theusernam argument can cause an access violation to besignaled.

Required Access or Privileges

All calls to $PERSONA_CREATE require DETACH privilege and access to thesystem authorization database.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_DELETE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The persona argument cannot be written by the caller.
SS$_NODETACH	Operation requires DETACH privilege.
SS$_INSFMEM	Insufficient memory.
IMP$_USERDISABLED	User name disabled.

Any condition value returned by the $LKWSET, $GETUAI, or, $FIND_HELDcan also be returned.

Creates a persona that can be assumed using the $PERSONA_ASSUME service.

Format

SYS$PERSONA_CREATE persona ,[usrnam] ,[flags], [usrpro], [itmlst]

C Prototype

int sys$persona_create (unsigned int *persona, void *usrnam, unsignedint flags, unsigned int *usrpro, unsigned int *itmlst);

Arguments

persona

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the persona identification handle iswritten.

usrnam

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length descriptor

Name of the user to be impersonated. The usrnamargument is the address of a descriptor pointing to a character stringcontaining the user name. The string can contain a maximum of 32alphanumeric characters.

flags

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

The $ISSDEF macro defines these codes:

• ISS$V_CREATE_AUTHPRIV - This bit is used to create a persona with the privilege fields set to the authorized privileges of the specified user.
  
• ISS$V_CREATE_DEFPRIV - This bit is used for backward compatibility with the previous implementation of personae. This bit is accepted but not processed, as it describes the default behavior of the service.
  
• ISS$V_NOACCESS - Tells $PERSONA_CREATE not to access the SYSUAF file. Only valid in exec or kernel mode.

usrpro

OpenVMS usage:	char_string
type:	opaque byte stream
access:	read only
mechanism:	by descriptor

Buffer containing an encoded security profile. Theusrpro argument is the address of a descriptorpointing to a buffer that contains encoded security profile data. Thisprofile can be created by calling the SYS$CREATE_USER_PROFILE systemservice.

itmlst

OpenVMS usage:	item_list_3
type:	longword
access:	read only
mechanism:	by reference

Attributes describing modifications to the security profile. Theitmlst argument is the address of an item_listdefining changes to be made to the specified user profile.

This section lists the ISS$ item codes and definitions.

Item Codes

ISS$_WORKPRIV

$PERSONA_CREATE sets the working privileges for the new persona as aquadword value.

ISS$_MODE

$PERSONA_CREATE sets the access mode of the new persona as a longwordvalue. The mode cannot be more privileged than that of the caller.

ISS$_FLAGS

$PERSONA_CREATE sets the flags field of the new persona as a longwordbit mask. The following bits are currently defined for this field:

• ISS$V_PERMANENT - Mark this persona as permanent. It will survive image activations/deactivations.
• ISS$V_SECAUDIT - Always audit this persona's operations.
• ISS$V_DEBIT - Debit and credit the process BYTLM/BYTCNT for this persona. (This flag is always set for user mode persona.)

ISS$_RIGHTS_INDEX

The index indicates into which rights chain the rights are placed.Values for the index are: ISS$M_ENABLED_PERSONA, ISS$M_ENABLED_SYSTEM,ISS$M_ENABLED_INSTALLED, ISS$M_ENABLED_SUBSYSTEM, andISS$M_ENABLED_TEMPORARY. All subsequent rights item packets use theindex until a new ISS$_RIGHTS_INDEX item changes the index. If a rightsindex is not specified, the rights item packets will use the PERSONAchain as the default. Rights item packets include: ISS$_AUTHRIGHTS,ISS$_RIGHTS, ISS$_ADD_AUTHRIGHTS, and ISS$_ADD_RIGHTS.

ISS$_AUTHRIGHTS (Reserved for use by HP.)

$PERSONA_CREATE sets the user authorized rights of the new persona as alist of quadword values. Any existing authorized rights will beoverwritten. By default, the rights will be placed in the PERSONArights chain. See ISS$_RIGHTS_INDEX for more information on specifyingdifferent indexes.

ISS$_RIGHTS

$PERSONA_CREATE sets the user rights of the new persona as a list ofquadword (paired longword) values. Any existing authorized rights willbe overwritten. By default, the rights will be placed in the PERSONArights chain. See ISS$_RIGHTS_INDEX for more information on specifyingdifferent indexes. The format of the list is the same asISS$_AUTHRIGHTS.

The format of the list is as follows:

ISS$_USERNAME

ISS$_ACCOUNT

ISS$_NOAUDIT

ISS$_UIC

ISS$_AUTHPRIV

ISS$_PERMPRIV

ISS$_IMAGE_WORKPRIV

ISS$_ENABLED

ISS$_ADD_AUTHRIGHTS

ISS$_ADD_RIGHTS

Description

When you call this service, you can specify either theusrnam or usrpro argument, but notboth. The required information specifying the OpenVMS user is read fromeither the User Authorization File (UAF) and rights database or theusrpro buffer and is stored in system memory. Anymodifications specified in the itmlst are then appliedto complete the new persona. A persona identification handle thatrefers to the created persona is returned in the persona argument. Thisservice creates a default VMS extension for the persona.

It is possible to call $PERSONA_CREATE in any mode. To call$PERSONA_CREATE in kernel mode, the calling sequence is different. Onlythe usrpro argument is valid (usrnamcannot be used because kernel mode access to the SYSUAF file is notallowed), and it is necessary to set the PSB$M_NOACESS value in theflags.

No changes are made to the caller's thread as a result of calling$PERSONA_CREATE.

The arguments are validated against the caller's mode, so an invalidargument can cause an access violation to be signaled.

Required Access or Privileges

All calls to $PERSONA_CREATE require IMPERSONATE privilege and readaccess to the system authorization database.

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE_EXTENSION,$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The persona argument cannot be written by the caller.
SS$_NOPRIV	The operation requires IMPERSONATE privilege.
SS$_INSFMEM	Insufficient memory.
SS$_USERDISABLED	User name disabled.
SS$_IVMODE	The caller cannot create a persona that is more privileged than the caller.
SS$_INSFARG	Certain required arguments were not specified.
SS$_BADPARAM	The value of at least one of the arguments is incorrect.
SS$_BADCHECKSUM	The buffer specified by usrpro is not valid.
SS$_BADBUFLEN	The buffer length for data within the usrpro or itmlst was invalid.
SS$_BADITMCOD	At least one argument in the item code is invalid.
SS$_INVARG	An incorrect combination of arguments was specified.
SS$_INVSECDOMAIN	The buffer specified by usrpro contains data that originated outside the local security domain.

Any condition value returned by the $LKWSET, $GETUAI, or $FIND_HELDservice can also be returned.

Creates an extension on the current persona. A persona extension is amechanism to attach support for additional security credentials.

Format

SYS$PERSONA_CREATE_EXTENSION persona ,extensionID ,buffer ,length ,flags

C Prototype

int sys$persona_create_extension (unsigned int *persona, unsigned int*extensionID, void *buffer, unsigned int *length, unsigned int *flags);

Arguments

persona

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

Address of a longword containing the persona identification to which$PERSONA_CREATE_EXTENSION attaches a new persona extension.

Two special values for persona are also permitted: 0,which means the current persona, and -1, which means the process'natural persona is used.

extensionID

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

Address of a longword containing the extension identification (EID) forwhich the registered CREATE routine will be called to create a newpersona extension block.

buffer

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

Address of a buffer containing data to be used in creating the personaextension data structure. The interpretation of the data within thisbuffer is the responsibility of the extension create routine. Forexample, this data could be a Type-Length-Value (TLV) structurecontaining fields in the extension data structure. Specifying thisbuffer is optional; a caller who does not want to supply a buffershould specify an address of zero (0).

length

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

Address of a longword containing the size, in bytes, of thebuffer argument. Specifying length isoptional; a caller who does not want to supply a length should specifyan address of zero (0). Specifying a buffer without a length is thesame as not specifying a buffer.

flags

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

Flag mask specifying the options to be employed when the personaextension is created. Specifying flags is optional; a caller who doesnot want to supply flags should specify an address of zero (0).

Flag	Description
PXB$V_PRIMARY_EXTENSION	This extension is recorded as the persona's primary extension. If a persona already has a primary extension, the error SS$_UNSUPPORTED is returned and the extension is not created. The primary extension is returned when the persona is queried for its "Primary Extension." There is no other meaning for this value.

Description

This service creates an extension by calling the registered ExtensionCreate routine for the specified extension and by attaching it to thepersona represented by the persona argument.

When a return fails, no persona extension is created.

A VMS extension is already associated with every persona. An attempt tocreate a VMS extension using this service returns SS$_DUPLNAM.

Required Access or Privileges

This service requires that the caller have the IMPERSONATE privilegeenabled or be in exec or kernel mode.

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_DELETE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	A buffer or return address specified in the item list cannot be read.
SS$_BADITMCOD	The item list contains an invalid identifier code.
SS$_BADPARAM	An invalid parameter was specified.
SS$_DUPLNAM	The persona already has an extension of this type.
SS$_EXQUOTA	The caller lacks sufficient quota to allocate a new persona.
SS$_NOIMPERSONATE	The caller does not have the privilege to extend its original identity/persona.
SS$_NOSUCHEXT	The extension requested does not exist on the system.
SS$_PERSONANONGRATA	The persona ID supplied was invalid.
SS$_UNSUPPORTED	An unsupported request was made; check the PRIMARY_EXTENSION flags bit.

Delegates or assigns the currently active persona to another process.

Format

SYS$PERSONA_DELEGATE serverPID ,persona ,input

C Prototype

int sys$persona_delegate (unsigned int *serverPID, unsigned int*persona, unsigned int *input);

Arguments

serverPID

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

Address of a longword containing the extended process identification(PID) of the server process to which $PERSONA_DELEGATE grants thecurrent persona.

persona

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

Address of a longword containing the identification that the$PERSONA_RESERVE service reserved in the server's process for thisclient's persona.

input

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

Address of a longword containing the persona identification thatdescribes which persona is delegated to the server. If theinput argument is zero (0) or null, or if the inputvalue is zero (0), the current persona is delegated. If the input valueis -1, then the natural persona of the process is delegated.

Description

This service delegates or assigns either the specified persona or thecurrently active persona to another process. The server process musthave reserved a persona slot for the current process to use by calling$PERSONA_RESERVE before calling this service.

The delegation of persona is only supported for processes residing onthe same node in the cluster. When a return fails, the persona is notdelegated.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The arguments cannot be read by the service.
SS$_BADPARAM	An invalid parameter was specified.
SS$_EXQUOTA	The caller lacks sufficient quota to allocate a new persona.
SS$_NONEXPR	The process specified does not exist.
SS$_PERSONANONGRATA	The persona ID supplied was invalid.

Deletes a persona created using the $PERSONA_CREATE, the$PERSONA_CLONE, or the $PERSONA_RESERVE service.

Format

SYS$PERSONA_DELETE persona

C Prototype

int sys$persona_delete (unsigned int *persona);

Arguments

persona

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

Address of a longword in which the persona identification handle isexpected.

Description

The PERSONA_DELETE service frees the resources used by the persona. Nochanges to the caller's process are made as a result of calling$PERSONA_DELETE.

The persona argument is validated against the caller'smode, so an invalid argument can cause an access violation to besignaled.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND,$PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	Access violation.
SS$_PERSONADELPEND	Persona is in use; delete pending on release.
SS$_NODELPERMANENT	Permanent personae cannot be deleted.

Deletes an extension attached to a persona.

Format

SYS$PERSONA_DELETE_EXTENSION persona ,extensionID

C Prototype

int sys$persona_delete_extension (unsigned int *persona, unsigned int*extensionID);

Arguments

persona

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

Address of a longword containing the persona identification for which$PERSONA_DELETE_EXTENSION calls the registered Extension Deletefunction.

extensionID

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

Address of a longword containing the extension identification (EID) forwhich the registered DELETE routine is called in order to delete apersona extension block from the specified persona.

Description

This service deletes an extension data structure by calling theregistered Extension Delete routine for the specified extension.

When a return fails, the persona extension is not deleted.

The VMS extension associated with each persona cannot be deleted. Anattempt to delete that extension returns SS$_UNSUPPORTED.

Required Access or Privileges

This service requires that the caller have the IMPERSONATE privilegeenabled or be in exec or kernel mode.

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELEGATE, $PERSONA_DELETE,$PERSONA_EXTENSION_LOOKUP, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	An invalid parameter was specified.
SS$_NOIMPERSONATE	The caller does not have the privilege to delete pieces of the thread's original identity/persona.
SS$_NOSUCHEXT	The extension specified does not exist in the persona.
SS$_PERSONANONGRATA	The persona ID supplied was invalid.
SS$_UNSUPPORTED	The specified extension cannot be deleted.

Translates a text name of an extension (for example, VMS or NT) into anextension identification (EID) that can be used in otherpersona-related system services.

Format

SYS$PERSONA_EXTENSION_LOOKUP extensionName ,extensionID

C Prototype

int sys$persona_extension_lookup (void *extensionName, unsigned int*extensionID);

Arguments

extensionName

OpenVMS usage:	extension_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length descriptor

Address of a character string descriptor pointing to the name of theextension being looked up.

extensionID

OpenVMS usage:	extension_ID
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the value of the extensionidentification (EID) returned by the service is written.

Description

This service translates a text name of an extension into an extensionidentification (EID) that can be used in other persona-related systemservices.

There are currently two extension names: VMS and NT.

Required Access or Privileges

None

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_FIND, $PERSONA_MODIFY,$PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The string descriptor supplied in the extensionName argument cannot be read by the service.
SS$_BADPARAM	An invalid argument was specified.
SS$_NOSUCHTEXT	The supplied extensionName does not exist on this system.

Enables the caller to find the personae within a process that havecertain attributes or settings.

Format

SYS$PERSONA_FIND persona ,itmlst ,contxt

C Prototype

int sys$persona_find (unsigned int *persona, void *itmlst, unsigned int*contxt);

Arguments

persona

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the persona identification thatmatches all of the items present in the item list is written.

itmlst

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

Attributes specifying which information about the persona is to becompared. The itmlst argument is the address of a listof item descriptors, each describing an item of information or an itemlist processing directive. The list of item descriptors is terminatedby a longword value of 0.

The following diagram shows the format of a single item descriptor:

The following table lists the item descriptor fields and theirdefinitions:

contxt

Description

This service enables the caller to find the personae within a processthat have certain attributes or settings.

A persona identification is returned only if all the items specified inthe item list match those in the persona and its extensions.

The item list cannot be changed between context-saved calls. Resultsare unpredictable if the item list is changed between calls.

Repeated calls to $PERSONA_FIND return subsequent matching personae.When the service returns SS$_NOMOREPROC, there are no more personae toexamine.

OpenVMS Persona Item Codes

The following table contains the item codes specific to the OpenVMSpersona extension data:

Item Code	Use+	Size (bytes)	Description
ISS$_USERNAME	Q,M,F	32	OpenVMS user name as text string
ISS$_ACCOUNT	Q,M,F	32	OpenVMS account name as text string
ISS$_DOMAIN	Q,F	32	OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
ISS$_PRINCIPAL	Q,F	64	OpenVMS user name as text string
ISS$_EXTENSION	Q,F	32	The text string VMS
ISS$_WORKPRIV	Q,M	8	Working privilege mask
ISS$_WORKCLASS	Q,M	Varying	Working classification
ISS$_RIGHTS	Q	Varying	Enabled list of rights identifiers
ISS$_NOAUDIT	Q,M	4	No audit counter---0 means audits disabled
ISS$_UIC	Q,M,F	4	Current UIC
ISS$_AUTHPRIV	Q,M	8	Authorized privilege mask
ISS$_PERMPRIV	Q,M	8	Permanent privilege mask
ISS$_IMAGE_WORKPRIV	Q,M	8	Image working privilege mask
ISS$_ENABLED	Q	4	Mask of enabled rights chains
ISS$_AUTHRIGHTS	Q	Varying	Authorized list of rights identifiers
ISS$_MINCLASS	Q	Varying	Minimum classification
ISS$_MAXCLASS	Q	Varying	Maximum classification

Required Access or Privileges

The caller may require extension-specific privileges to search on somedata items. The Persona Item Codes section lists the privileges thatare needed.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP,$PERSONA_MODIFY, $PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read by the caller.
SS$_BADPARAM	An invalid parameter was specified.
SS$_BADITMCOD	The item list contains an invalid item code.
SS$_IVCONTEXT	The context value is invalid.
SS$_NOIMPERSONATE	The caller does not have the privilege to obtain information about the specified personae.
SS$_NOMOREPROC	There are no more personae to check.
SS$_NOSUCHEXT	The extension requested does not exist on the system.

Sets attribute values for a persona.

Format

SYS$PERSONA_MODIFY persona ,itmlst

C Prototype

int sys$persona_modify (unsigned int *persona, void *itmlst);

Arguments

persona

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

Address of a longword containing the persona identification for whichthis service is to set information.

itmlst

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

Attributes specifying which information in the persona is to bemodified. The itmlst argument is the address of a listof item descriptors, each describing an item of information or an itemlist processing directive. The list of item descriptors is terminatedby a longword value of 0.

The following diagram shows the format of a single item descriptor:

The following table lists the item descriptor fields and theirdefinitions:

Description

The Modify Persona Data service sets attribute values for a persona.

OpenVMS Persona Item Codes

The following table contains the item codes specific to the OpenVMSpersona extension data:

Item Code	Use+	Size (bytes)	Description
ISS$_USERNAME	Q,M,F	32	OpenVMS user name as text string
ISS$_ACCOUNT	Q,M,F	32	OpenVMS account name as text string
ISS$_DOMAIN	Q,F	32	OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
ISS$_PRINCIPAL	Q,F	64	OpenVMS user name as text string
ISS$_EXTENSION	Q,F	32	The text string VMS
ISS$_WORKPRIV	Q,M	8	Working privilege mask
ISS$_WORKCLASS	Q,M	Varying	Working classification
ISS$_RIGHTS	Q	Varying	Enabled list of rights identifiers
ISS$_NOAUDIT	Q,M	4	No audit counter---0 means audits disabled
ISS$_UIC	Q,M,F	4	Current UIC
ISS$_AUTHPRIV	Q,M	8	Authorized privilege mask
ISS$_PERMPRIV	Q,M	8	Permanent privilege mask
ISS$_IMAGE_WORKPRIV	Q,M	8	Image working privilege mask
ISS$_ENABLED	Q	4	Mask of enabled rights chains
ISS$_AUTHRIGHTS	Q	Varying	Authorized list of rights identifiers
ISS$_MINCLASS	Q	Varying	Minimum classification
ISS$_MAXCLASS	Q	Varying	Maximum classification

Required Access or Privileges

This service requires that the caller have the IMPERSONATE privilegeenabled or be in exec or kernel mode.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP,$PERSONA_FIND, $PERSONA_QUERY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read by the caller, or the buffer cannot be read by the caller.
SS$_BADPARAM	An invalid parameter was specified.
SS$_BADITMCOD	The item list contains an invalid item code.
SS$_NOIMPERSONATE	The caller does not have the privilege to obtain information about the specified personae.
SS$_NOSUCHEXT	The extension requested does not exist on the system.
SS$_PERSONANONGRATA	The persona ID supplied was invalid. This service may also return status codes associated with the various extension routines.

Retrieves attribute values from a persona (and accompanying extensions).

Format

SYS$PERSONA_QUERY persona ,itmlst

C Prototype

int sys$persona_query (unsigned int *persona, void *itmlst);

Arguments

persona

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

Address of a longword into which the persona identification handle iswritten.

Two special values for persona are also permitted: 0,which means use the current persona, and -1, which means use theprocess' natural persona.

itmlst

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

Attributes describing which information about the persona is to bereturned. The itmlst argument is the address of a listof item descriptors, each of which describes an item of information oran item list processing directive. The list of item descriptors isterminated by a longword value of 0.

The following diagram shows the format of a single item descriptor:

The following table lists the item field descriptors and theirdefinitions:

Description

The Query for Persona Data service returns the requested items in thebuffers supplied.

OpenVMS Persona Item Codes

The following table contains the item codes specific to the OpenVMSpersona extension data:

Item Code	Use+	Size (bytes)	Description
ISS$_USERNAME	Q,M,F	32	OpenVMS user name as text string
ISS$_ACCOUNT	Q,M,F	32	OpenVMS account name as text string
ISS$_DOMAIN	Q,F	32	OpenVMS SCSNODE as text string as obtained from $GETJPI's nodename
ISS$_PRINCIPAL	Q,F	64	OpenVMS user name as text string
ISS$_EXTENSION	Q,F	32	The text string VMS
ISS$_WORKPRIV	Q,M	8	Working privilege mask
ISS$_WORKCLASS	Q,M	Varying	Working classification
ISS$_RIGHTS	Q	Varying	Enabled list of rights identifiers
ISS$_NOAUDIT	Q,M	4	No audit counter---0 means audits disabled
ISS$_UIC	Q,M,F	4	Current UIC
ISS$_AUTHPRIV	Q,M	8	Authorized privilege mask
ISS$_PERMPRIV	Q,M	8	Permanent privilege mask
ISS$_IMAGE_WORKPRIV	Q,M	8	Image working privilege mask
ISS$_ENABLED	Q	4	Mask of enabled rights chains
ISS$_AUTHRIGHTS	Q	Varying	Authorized list of rights identifiers
ISS$_MINCLASS	Q	Varying	Minimum classification
ISS$_MAXCLASS	Q	Varying	Maximum classification

Common Item Codes

The following table contains the item codes specific to the commonpersona extension data:

General Persona Item Codes

The following table contains the item codes specific to the generalpersona extension data:

NT Persona Item Codes

The following table contains the item codes specific to the NT personaextension data:

Required Access or Privileges

No privileges are required to call this service.

Required Quota

None

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP,$PERSONA_FIND, $PERSONA_MODIFY, $PERSONA_RESERVE

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read by the caller, or the buffer length or buffer cannot be written by the caller.
SS$_BADPARAM	An invalid parameter was specified.
SS$_BADITMCOD	The item list contains an invalid item code.
SS$_NOSUCHEXT	The extension requested does not exist on the system.
SS$_PERSONANONGRATA	The persona ID supplied is invalid.

Reserves a persona ID in the server's persona table to be filled in bythe $PERSONA_DELEGATE system service.

Format

SYS$PERSONA_RESERVE clientPID ,persona

C Prototype

int sys$persona_reserve (unsigned int *clientPID, unsigned int*persona);

Arguments

clientPID

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

Address of a longword containing the External Process Identification(EPID) of the client process for which the server is reserving the slot.

persona

OpenVMS usage:	persona
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Address of a longword into which the persona identification is written.This service sets aside the identification for the client'sto-be-delegated persona.

Description

This service reserves a persona identifier slot within the currentprocess for a specific client process to use in delegating its personato this process. A reserved persona slot can be deleted by a call tothe $PERSONA_DELETE service. When a return fails, no persona slot hasbeen reserved for the client process.

The delegation of persona is only supported for processes residing onthe same node of a cluster.

Required Access or Privileges

IMPERSONATE

Required Quota

BYTLM

Related Services

$PERSONA_ASSUME, $PERSONA_CLONE, $PERSONA_CREATE,$PERSONA_CREATE_EXTENSION, $PERSONA_DELETE_EXTENSION,$PERSONA_DELEGATE, $PERSONA_DELETE, $PERSONA_EXTENSION_LOOKUP,$PERSONA_FIND, $PERSONA_MODIFY

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The item list cannot be read by the caller.
SS$_BADPARAM	An invalid parameter was specified.
SS$_EXQUOTA	The caller lacks sufficient quota to allocate a new persona.
SS$_NONEXPR	The specified process does not exist, or an invalid process identification was specified.