OpenVMS System Services Reference Manual

Document revision date: 30 March 2001

OpenVMS System Services Reference Manual

Contents

Index

If you specify astadr, the AST routine executes at the same access mode as the caller of the $SET_DEVICE service.

astprm

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

AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument is the longword parameter.

nullarg

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

Placeholding argument reserved to Compaq and should be zero.

Item Codes

SDV$_MP_SWITCH_PATH
Forces an immediate I/O path switch for the specified device. The active path will be switched from the current I/O path to the path name specified in the buffer for this item code. Note that issuing $SET_DEVICE with SDV$_MP_SWITCH_PATH will initiate the process of switching the path. A delay may occur between when the service completes and when the path switch is complete. A synchronous version of this service, $SET_DEVICEW, is available that will wait until the path switch attempt is complete before returning to the caller.
The path name specified in this and the following item codes must be fully specified. It may be in either uppercase or lowercase, however the entire name must be specified.
The Return Length field in this and the following item codes should set to zero.
The SDVDEF macro contains these item codes.
SDV$_MP_DISABLE_PATH
Disables the path specified in the buffer for this item code so that it will no longer be considered as a switch candidate. Note that this does not apply to the current path, which cannot be disabled. The reasons one might want to disable a path include the following:

You know a specific path is broken or that a failover to that path will cause some members of the cluster to lose access.
To prevent automatic switching to a selected path while it is being serviced.

SDV$_MP_ENABLE_PATH
Re-enables the path name specified in the buffer for this item code as a switch candidate.

Description

The Set Device service modifies the characteristics of devices or I/O paths that have been established to those devices. For Multipath, the service allows the user to switch the current I/O path to a different available path and to enable and disable paths from being used for I/O.
Required Access or Privileges

None.
Required Quota

None.
Related Services

$ASSIGN, $DASSGN, $DEVICE_SCAN, $DEVICE_PATH_SCAN, $GETDVI, $GETDVIW

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The device name string descriptor, device name string, or itmlst argument cannot be read; or the buffer or return length longword cannot be written.

SS$_BADPARAM The item list contains an invalid item code, or the buffer length field in an item descriptor specified insufficient space for the return length information.

SS$_EXQUOTA Quota for pool has been exceeded.

SS$_IVCHAN You specified an invalid channel number, that is, a channel number larger than the number of channels.

SS$_IVDEVNAM The device name string contains invalid characters, or neither the devnam nor chan argument was specified.

SS$_NOOPER Caller does not have OPER privileges.

SS$_NOPRIV The specified channel is not assigned or was assigned from a more privileged access mode.

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

SS$_NOSUCHPATH The specified pathname does not exist on the host system.

SS$_PATHAMBIG The specified pathname is ambiguous for this device.

$SET_DEVICEW

Modifies the characteristics of a device or the paths used to access that device.
The $SET_DEVICEW completes synchronously; that is, it returns to the caller only after the requested action has taken effect.

Format

SYS$SET_DEVICEW [efn] [,chan] [,devnam] ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$set_devicew (unsigned int efn, unsigned short int chan, void *devnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, struct_generic_64 *nullarg);

$SET_IMPLICIT_AFFINITY (Alpha Only)

On Alpha systems, controls or retrieves the activation state for the implicit affinity system capability of a specific kernel thread or of the global process default.
This service accepts 64-bit addresses.

Format

SYS$SET_IMPLICIT_AFFINITY [pidadr] [,prcnam] [,state] [,cpu_id] [,prev_mask]

C Prototype

int sys$set_implicit_affinity (unsigned int *pidadr, void *prcnam, struct _generic_64 *state, int cpu_id, struct _generic_64 *prev_mask);

Arguments

pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

Process identification (PID) of a kernel thread whose implicit affinity is to be modified or returned. The pidadr argument is the 32- or 64-bit address of a longword that contains the PID.
Process selection is made through a combination of the pidadr and prcnam arguments. If neither are specified or if both have a zero value, the service operations are made to the user capability mask of the current kernel thread of the current calling process. The pidadr argument takes precedence over the prcnam argument where both are supplied in the service call.
If the bit constant CAP$M_IMPLICIT_DEFAULT_ONLY is specified in the state argument, then the implicit affinity state portion of the default capability mask is modified or returned instead.
prcnam

OpenVMS usage: process_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor

Process name of the process whose implicit affinity capability state is to be modified or returned. The prcnam argument is the 32- or 64-bit address of a character string descriptor pointing to the process name string. A process can be identified with a 1- to 15-character string. The service operations are made to the user capability mask of the initial thread of the specified process.
If pidadr and prcnam are both specified, then pidadr is modified or returned and prcnam is ignored. If neither argument is specified, then the context of the current kernel thread of the calling process is modified or returned.
state

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference

State options that can be selected for the affected thread's implicit affinity. The state argument is a pointer to a quadword bit vector wherein a bit corresponds to a requested state for the implicit affinity feature. Only the bits specified below are used; the remainder of the quadword bits are reserved.
Each option (bit) has a symbolic name, defined in the $CAPDEF macro. The state argument is constructed by performing a logical OR operation using the symbolic names of each desired option.
The following table describes the symbolic name of each option:

Symbolic Name Description

CAP$M_IMPLICIT_DEFAULT_ONLY Indicates the specified operations are to be performed on the global cell instead of on a specific kernel thread. This bit supersedes any individual kernel thread specified in pidadr or prcnam. Specifying this bit constant applies the implicit affinity operations to all newly created processes.

CAP$M_IMPLICIT_AFFINITY_SET Indicates that the implicit affinity capability bit is to be set for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_CLEAR.

CAP$M_IMPLICIT_AFFINITY_CLEAR Indicates that the implicit affinity capability bit is to be cleared for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_SET.

cpu_id

OpenVMS usage: longword

type: longword (unsigned)

access: read only

mechanism: by value

Identifier of the CPU requested as the first CPU on which this kernel thread is to execute. The cpu_id is a longword containing this number, which is in the supported range of individual CPUs from 0 to SYI$_MAX_CPUS - 1 .
If no explicit CPU is needed, specifying a value of -1 in this argument indicates the system is to select the initial association based on system dynamics and load balancing.
Note that, regardless of what explicit CPU is supplied to this argument, it will be taken only as a suggestion. This service will attempt to make the requested association, but it will be superseded by another CPU if the system dynamics are adversely affected by the operation.
prev_mask

OpenVMS usage: mask_quadword

type: quadword (unsigned)

access: write only

mechanism: by 32- or 64-bit reference

Previous implicit affinity state mask for the specified kernel thread before execution of this call to $SET_IMPLICIT_AFFINITY. The prev_mask argument is the 32- or 64-bit address of a quadword into which $SET_IMPLICIT_AFFINITY writes a bit mask specifying the implicit affinity state.
The current state of the kernel thread's current implicit affinity feature can be determined by testing the returned mask with the symbolic bit definitions described for the state argument. These bit definitions are found in the $CAPDEF macro.

Symbolic Name	Description
CAP$M_IMPLICIT_DEFAULT_ONLY	Indicates the specified operations are to be performed on the global cell instead of on a specific kernel thread. This bit supersedes any individual kernel thread specified in pidadr or prcnam. Specifying this bit constant applies the implicit affinity operations to all newly created processes.
CAP$M_IMPLICIT_AFFINITY_SET	Indicates that the implicit affinity capability bit is to be set for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_CLEAR.
CAP$M_IMPLICIT_AFFINITY_CLEAR	Indicates that the implicit affinity capability bit is to be cleared for the specified kernel thread. This is mutually exclusive with CAP$M_IMPLICIT_AFFINITY_SET.

Description

The Modify Process Implicit Affinity system service modifies or returns the implicit affinity state for the specified kernel thread or from the system default process creation cell.
Setting a kernel thread's implicit affinity function indicates to the system that it is to schedule the process in ways that will maximize the cache and TB performance in the current symmetric multiprocessing (SMP) configuration. This might tend to bias the process towards specific CPUs more than the standard scheduling algorithm would normally have allowed.
Required Access or Privileges

The caller must have the ALTPRI privilege to call SYS$SET_IMPLICIT_AFFINITY to modify its own implicit affinity capability bit. To modify another process' capability mask, the caller must have:
ALTPRI---To modify any process with a matching UIC
ALTPRI and GROUP---To modify any process in the same UIC group
ALTPRI and WORLD---To modify any process

To call SYS$SET_IMPLICIT_AFFINITY simply to retrieve the state of a specific process or global bit, the caller need only have the following privileges:
None---To retrieve the state of itself or any process with a matching UIC
GROUP---To retrieve the state of any process in the same UIC group
WORLD---To retrieve the state of any process

Related Services

$CPU_CAPABILITIES, $PROCESS_CAPABILITIES, $PROCESS_AFFINITY

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_BADPARAM One or more arguments has an invalid value.

SS$_ACCVIO The service cannot access the locations specified by one or more arguments.

SS$_NOSUCHTHREAD The specified kernel thread does not exist.

SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_IVLOGNAM The process name string has a length of 0 or more than 15 characters.

SS$_NOPRIV Insufficient privilege for attempted operation.

SS$_CPUCAP No CPU can run the specified process with new capabilities.

SS$_INSFARG Fewer than the required number of arguments were specified or no operation was specified.

$SET_PROCESS_PROPERTIESW (Alpha Only)

Sets a simple value associated with a process.

Format

SYS$SET_PROCESS_PROPERTIESW mbz1 ,mbz2 ,mbz3 ,property ,value ,prev_value

C Prototype:

int sys$set_process_propertiesw (unsigned int mbz1, unsigned int mbz2, unsigned int mbz3, unsigned int property, unsigned __int64 value, unsigned __int64 *prev_value);

Arguments

mbz1,mbz2,mbz3

type:

access:

Reserved for future use by Compaq. Must be specified as 0.
property

OpenVMS usage: integer

type: longword (unsigned)

access: read only

mechanism: by value

A constant that selects which property to set.
Valid values for property are defined by the $PPROPDEF macro as follows:

Property Code Description

PPROP$C_HOME_RAD: The Resource Affinity Domain (RAD) to which the process is assigned. Newly mapped memory in the process will come from the home RAD of the process. Currently mapped memory will not move into the new home RAD unless $PURGWS is issued. Valid values are integers between 0 and the maximum RAD on the system. Valid home RADs must also contain either memory or CPUs.
Note: OpenVMS support for RADs is available only on the new AlphaServer GS series systems. For more information about using RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.

PPROP$C_PARSE_STYLE_TEMP: The type of command parsing to use. This value is set only for the life of the image. The value reverts to the permanent style on image rundown. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.

PPROP$C_PARSE_STYLE_PERM: The type of command parsing to use. This value is set for the life of the process unless the style is set again. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.

value

OpenVMS usage: integer

type: quadword (unsigned)

access: read

mechanism: by value

New property value.
prev_value

OpenVMS usage: access_mode

type: quadword (unsigned) address of a quadword value

access: write

mechanism: by reference

The address of a quadword that will receive the previous value of the property.

Property Code	Description
PPROP$C_HOME_RAD:	The Resource Affinity Domain (RAD) to which the process is assigned. Newly mapped memory in the process will come from the home RAD of the process. Currently mapped memory will not move into the new home RAD unless $PURGWS is issued. Valid values are integers between 0 and the maximum RAD on the system. Valid home RADs must also contain either memory or CPUs. Note: OpenVMS support for RADs is available only on the new AlphaServer GS series systems. For more information about using RADs, refer to the OpenVMS Alpha Partitioning and Galaxy Guide.
PPROP$C_PARSE_STYLE_TEMP:	The type of command parsing to use. This value is set only for the life of the image. The value reverts to the permanent style on image rundown. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.
PPROP$C_PARSE_STYLE_PERM:	The type of command parsing to use. This value is set for the life of the process unless the style is set again. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.

Description

The $SET_PROCESS_PROPERTIESW system service sets a simple value associated with a process.
This service is used for changing process properties that have a maximum of a single quadword. You can only change one property value at a time per call to this service.
Required Access or Privileges

None.
Required Quota

None.
Related Services

$GETJPI

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO Access violation.

$SET_RESOURCE_DOMAIN

Controls the association between a calling process and resource domains.

Format

SYS$SET_RESOURCE_DOMAIN func ,rsdm_id ,domain_number ,[nullarg] ,[access] ,[acmode]

C Prototype

int sys$set_resource_domain (unsigned int func, unsigned int *rsdm_id, unsigned int domain_number, unsigned int nullarg, unsigned int access, unsigned int acmode);

Arguments

func

OpenVMS usage: function_code

type: longword (unsigned)

access: read only

mechanism: by value

Function code specifying the action that $SET_RESOURCE_DOMAIN is to perform. The func argument is a longword containing this function code. See the Function Codes section for a description of $SET_RESOURCE_DOMAIN function codes.
rsdm_id

OpenVMS usage: longword

type: longword (unsigned)

access: write only to join, read only to leave

mechanism: by reference

Resource domain identification. The rsdm_id argument is the address of a longword specifying the association of the calling process with the resource domain.
The RSDM$_JOIN_DOMAIN function returns a resource domain identification. The RSDM$_LEAVE function requires the rsdm_id argument as input to specify which resource domain association the process is leaving.
The resource domain identification can be used as input to the $ENQ and $ENQW system services.
domain_number

OpenVMS usage: longword

type: longword (unsigned)

access: read only

mechanism: by value

Domain number that identifies the resource domain. The domain_number argument is a longword value containing the resource domain number.
The domain_number argument is required for the RSDM$_JOIN_DOMAIN function but ignored for the RSDM$_LEAVE function.
nullarg

OpenVMS usage: null_arg

type: longword (unsigned)

access: read only

mechanism: by value

Placeholder reserved to Compaq. You must specify 0.
access

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by value

Types of access desired when using the lock management services within the resource domain. The access argument is a longword bit mask specifying the access types required; these can include read, write, and lock.
The following table lists the symbols that the $RSDMDEF macro defines, their descriptions, and the lock management system services that might require each type of access:

Symbol Access Description System Service

RSDM$M_READ Read lock value blocks $DEQ, $ENQ, $ENQW, $GETLKI, $GETLKIW

RSDM$M_WRITE Write lock value blocks $DEQ, $ENQ, $ENQW,

RSDM$M_LOCK Take locks $ENQ, $ENQW

The service grants the desired access, provided your process has the necessary access rights to the resource domain. If you do not specify the access argument or if you specify 0, $SET_RESOURCE_DOMAIN attempts to access the domain in the following order:

Read, write, lock
Read, lock
Write, lock
Lock

The access attempt terminates with the first success.
The access argument defaults to 0. It is ignored for the RSDM$_LEAVE function.
acmode

OpenVMS usage: access_mode

type: longword (unsigned)

access: read only

mechanism: by value

Access mode requested for the association to the resource domain. The most privileged access mode granted is the access mode of the caller. Locks cannot be taken from access modes less privileged than the access mode of the association.
The acmode argument is a longword containing the access mode. The $PSLDEF macro defines the following symbols for the access modes:

Symbolic
Name Access
Mode Privilege
Rank

PSL$C_KERNEL Kernel High

PSL$C_EXEC Executive --

PSL$C_SUPER Supervisor --

PSL$C_USER User Low

The acmode argument is optional for the RSDM$_JOIN_DOMAIN function. If you do not specify the acmode argument, the access mode is set to the access mode of the calling process. The acmode argument is ignored for the RSDM$_LEAVE function.

Symbol	Access Description	System Service
RSDM$M_READ	Read lock value blocks	$DEQ, $ENQ, $ENQW, $GETLKI, $GETLKIW
RSDM$M_WRITE	Write lock value blocks	$DEQ, $ENQ, $ENQW,
RSDM$M_LOCK	Take locks	$ENQ, $ENQW

Symbolic Name	Access Mode	Privilege Rank
PSL$C_KERNEL	Kernel	High
PSL$C_EXEC	Executive	--
PSL$C_SUPER	Supervisor	--
PSL$C_USER	User	Low

Function Codes

RSDM$_JOIN_DOMAIN
A process has the option of forming multiple associations with one or more resource domains. Each association can have different access rights to the resource domain, such as to read lock value blocks or to write lock value blocks. This request sets up a new association with a resource domain.
$SET_RESOURCE_DOMAIN verifies the desired access against the security profile of the resource domain. If the desired access is allowed, a new association to the resource domain is created, and a resource domain identification for the association is returned.
This function code returns the following condition values:
SS$_NORMAL
SS$_BADPARAM
SS$_EXQUOTA
SS$_INSFMEM
SS$_NOOBJSRV
SS$_NOPRIV

RSDM$_LEAVE
This operation requests that a process end an association with a resource domain.
A process must leave a resource domain association in the same mode as, or in a more privileged mode than, the mode in which it joined the resource domain.
Before a process can end its association with a resource domain, it must release all locks taken using that association.
This function code returns the following condition values:
SS$_NORMAL
SS$_BADPARAM
SS$_IVMODE
SS$_RSDM_ACTIVE
SS$_RSDMNOTFOU

Description

The Set Resource Domain system service enables a process to use the lock management system services $DEQ, $ENQ, $ENQW, $GETLKI, and $GETLKIW.
The lock management services enable processes with the appropriate access rights to take and release locks on resource names and to perform other functions related to lock management. Applications use resource names to represent resources to which they want to synchronize access. A resource domain is a namespace for resource names. A process must join a resource domain to take and release locks and to read and write value blocks associated with resources in that resource domain.
When a process requests to join a resource domain, $SET_RESOURCE_DOMAIN performs an access check. After $SET_RESOURCE_DOMAIN verifies the desired access to the resource domain, the service creates an association between the resource domain and the calling process. The association is represented by a resource domain identification. A process can request different types of access to the same resource domain; the type of access is a characteristic of the association with the resource domain.

Previous Next Contents Index

privacy and legal statement

4527PRO_090.HTML

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The device name string descriptor, device name string, or itmlst argument cannot be read; or the buffer or return length longword cannot be written.
SS$_BADPARAM	The item list contains an invalid item code, or the buffer length field in an item descriptor specified insufficient space for the return length information.
SS$_EXQUOTA	Quota for pool has been exceeded.
SS$_IVCHAN	You specified an invalid channel number, that is, a channel number larger than the number of channels.
SS$_IVDEVNAM	The device name string contains invalid characters, or neither the devnam nor chan argument was specified.
SS$_NOOPER	Caller does not have OPER privileges.
SS$_NOPRIV	The specified channel is not assigned or was assigned from a more privileged access mode.
SS$_NOSUCHDEV	The specified device does not exist on the host system.
SS$_NOSUCHPATH	The specified pathname does not exist on the host system.
SS$_PATHAMBIG	The specified pathname is ambiguous for this device.

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

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

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

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

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

OpenVMS usage:	access_mode
type:	quadword (unsigned) address of a quadword value
access:	write
mechanism:	by reference

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

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