OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

Always refer to the return_va_64 and return_length_64 arguments to determine the range of virtual addresses mapped.

Description

The Map Global Page Frame Section service establishes a correspondence between pages in the virtual address space of the process and pages occupied by a global page frame section. It adds pages to the virtual address space of the process.
Pages mapped to a global page frame section are not included in or charged against the process's working set; they are always valid. Do not lock these pages in the working set by using $LKWSET; this can result in a machine check if they are in I/O space.
If the condition value SS$_ACCVIO is returned by this service, a value cannot be returned in the memory locations pointed to by the return_va_64 and return_length_64 arguments.
If a condition value other than SS$_ACCVIO is returned, the returned address and returned length indicate the pages that were successfully mapped before the error occurred. If no pages were mapped, the return_va_64 argument will contain the value -1, and a value cannot be returned in the memory location pointed to by the return_length_64 argument.
Required Privileges

Read access is required. If the SEC$M_WRT flag is specified, write access is required.
Required Quota

The working set quota (WSQUOTA) of the process must be sufficient to accommodate the increased length of the process page table required by the increase in virtual address space.
The page file quota (PAGFLQUOTA) of the process must be sufficient to accommodate the increased number of process page tables required by the increase in virtual address space. (Note that this service can return the 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.

$MOD_HOLDER

Modifies the specified holder record of the target identifier in the rights 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 a longword 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 completes execution. The holder argument is the address of a quadword containing the UIC identifier of the holder in the first longword 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_attrib argument is a longword containing the attribute mask.
The attributes actually enabled are the intersection of those specified and the attributes of the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position 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_attrib argument is a longword containing the attribute mask.
If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position 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.

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.

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 the specified holder record in the rights database. Identifier attributes can be added or removed.
When you specify both the set_attrib and clr_attrib arguments, the attribute is cleared first. Thus, if you specify the same attribute bit with each argument, the result 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, $CHANGE_ACL, $CREATE_RDB, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $GRANTID, $IDTOASC, $MOD_IDENT, $REM_HOLDER, $REM_IDENT, $REVOKID

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 OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the OpenVMS Record Management Services Reference Manual.

$MOD_IDENT

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, unsigned int 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 a longword 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_IDENT completes execution. The set_attrib argument is a longword containing the attribute mask.
The attributes actually enabled are the intersection of those specified and the attributes of the identifier. If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position 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_attrib argument is a longword containing the attribute mask.
If you specify the same attribute in set_attrib and clr_attrib, the attribute is enabled.
Symbol values are offsets to the bits within the longword. You can also obtain the values as masks with the appropriate bit set using the prefix KGB$M rather than KGB$V. The following symbols for each bit position 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. The new_name argument is the address of the descriptor pointing to the identifier name string.
An identifier name consists of 1 to 31 alphanumeric characters, including dollar signs ($) and underscores (_), and must contain at least one nonnumeric character. Any lowercase characters specified are automatically 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. The new_value argument is a longword containing the binary value of the specified identifier. When the identifier value is changed, $MOD_IDENT also changes the value of the identifier in all of the holder records in which the specified identifier appears.

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.

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.

Description

The Modify Identifier in Rights Database service modifies the specified identifier record in the rights database. Identifier attributes can be added or removed. The identifier name or value can be changed. When you specify both the set_attrib and clr_attrib arguments, the attribute is cleared first. Thus, if you specify the same attribute bit with each argument, the result 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.

$MOUNT

Mounts a tape, disk volume, or volume set and specifies options for the mount 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. The itmlst argument is the address of a list of item descriptors, each of which specifies an option and provides the information needed to perform the operation.
The item list must include at least one device item descriptor and is terminated 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.

Descriptor Field Definition

Buffer length A word specifying the length (in bytes) of the buffer that supplies the information $MOUNT needs to process the specified item code. The required length of the buffer depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length is too small, $MOUNT truncates the data.

Item code A word containing a user-supplied symbolic code that specifies an option for the MOUNT operation. The $MNTDEF macro defines these codes.

Buffer address A longword containing the address of the buffer that supplies information to $MOUNT.

Return length address This field is not used.

Descriptor Field	Definition
Buffer length	A word specifying the length (in bytes) of the buffer that supplies the information $MOUNT needs to process the specified item code. The required length of the buffer depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length is too small, $MOUNT truncates the data.
Item code	A word containing a user-supplied symbolic code that specifies an option for the MOUNT operation. The $MNTDEF macro defines these codes.
Buffer address	A longword containing the address of the buffer that supplies information to $MOUNT.
Return length address	This field is not used.

Item Codes

MNT$_ACCESSED
The MNT$_ACCESSED item code specifies the number of directories that will be in use, concurrently, on the volume. The buffer must contain a longword integer value in the range 0 to 255. This value overrides the number of directories specified when the volume was initialized. To specify MNT$_ACCESSED, the caller must have OPER privilege. The MNT$_ACCESSED item code applies only to disks.
MNT$_BLOCKSIZE
The MNT$_BLOCKSIZE item code specifies the default block size for tape volumes. The buffer must contain a longword integer value in the range 20 to 65,532 bytes for OpenVMS RMS operations or 10 to 65,534 bytes for operations that do not use RMS. The MNT$_BLOCKSIZE item code applies only to tapes.
If you do not specify MNT$_BLOCKSIZE, the default block size is 2048 bytes for Files-11 tape volumes and 512 bytes for foreign and unlabeled tapes.
You must specify MNT$_BLOCKSIZE when mounting (1) tapes that do not have ANSI HDR2 labels, (2) tapes to which data will be written from compatibility mode, and (3) tapes that are to contain records whose size is larger than the default value.
MNT$_COMMENT
The MNT$_COMMENT item code specifies text to be associated with an operator request. The buffer must contain a character string of no more than 78 characters. This text will be printed on the operator's console if an operator request is issued for the device being mounted.
MNT$_DENSITY
The MNT$_DENSITY item code specifies the density at which data is to be written to a foreign or unlabeled tape. The buffer must contain a longword value that specifies one of the following legal densities: 800, 1600, or 6250 bpi. The MNT$_DENSITY item code applies only to tapes.
The specified density will be used only if (1) the tape is foreign or unlabeled and (2) the first operation is a write.
MNT$_DEVNAM
The MNT$_DEVNAM item code specifies the name of the device to be mounted. The buffer must contain a character string of from 1 to 64 characters, which is the device name. 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 a volume set is being mounted, because, in this case, one device is being mounted for each volume in the volume set.
MNT$_EXTENSION
The MNT$_EXTENSION item code specifies the number of blocks by which files will be extended. The buffer must contain a longword value in the range 0 to 65,535. The MNT$_EXTENSION item code applies only to disks.
MNT$_EXTENT
The MNT$_EXTENT item code specifies the size of the extent cache in units of extent pointers. The buffer must contain a longword value, which specifies this size. To specify MNT$_EXTENT, you need OPER privilege. The value 0 (the default) disables caching. The MNT$_EXTENT item code applies only to disks.
MNT$_FILEID
The MNT$_FILEID item code specifies the size of the file-ID cache in units of file numbers. The buffer must contain a longword value, which specifies this size. To specify MNT$_FILEID, you need OPER privilege. The value 1 disables caching. The MNT$_FILEID item code applies only to disks.
MNT$_FLAGS
The MNT$_FLAGS item code specifies a 2-longword bit vector wherein each bit specifies an option for the mount operation. The buffer must contain a quadword, which is the bit vector.

Previous Next Contents Index

privacy and legal statement

4527PRO_066.HTML

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.

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

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

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

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

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.

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