 |
HP OpenVMS System Services Reference Manual
$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 and I64)
On Alpha and I64 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.
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 and I64)
On Alpha and I64 systems, 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
Reserved for future use by HP. 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_CASE_LOOKUP_TEMP
|
The type of case lookup to use. This value is set for the life of the
currently active image. This value reverts to the permanent case
setting on image rundown. In the absence of an explicit case lookup
specification in a user-provided NAML, RMS uses this value to determine
the case setting for the current file operation.
Valid values are PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE.
Refer to the Guide to OpenVMS File Applications for additional information.
|
|
PPROP$C_CASE_LOOKUP_PERM
|
The type of case lookup to use. This value is set for the life of the
process or until the case is set again. This value is copied to the
PPROP$C_CASE_LOOKUP_TEMP setting at image rundown. Setting this value
affects only future activated images for this process. To change the
case setting for the current active image, you must modify the
PPROP$C_CASE_LOOKUP_TEMP setting.
Valid values are PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE.
Refer to the Guide to OpenVMS File Applications for additional information.
|
|
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 AlphaServer GS series systems. For more information about using RADs, refer to the HP 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 |
A quadword value to which to set the property.
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.
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 HP. 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.
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.
Each time a process joins a resource domain, a new association is
created.
Processes use their resource domain identifications when using $ENQ or
$ENQW to request a new lock.
The service can grant the following three types of access to resource
domains:
- The right to read lock value blocks
- The right to write lock value blocks
- The right to take and release locks
Required Access or Privileges
None
Required Quota
$SET_RESOURCE_DOMAIN uses system dynamic memory, which uses BYTLM
quota, for the creation of the resource domain data structures.
Related Services
$DEQ, $ENQ, $ENQW, $GETLKI, $GETLKIW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BADPARAM
|
The
func, the
domain_number, or the
rsdm_id argument was specified incorrectly.
|
|
SS$_EXQUOTA
|
The caller has insufficient BYTLM quota.
|
|
SS$_INSFMEM
|
There is insufficient memory to join the resource domain.
|
|
SS$_IVMODE
|
An attempt was made to leave an association created by a more
privileged access mode.
|
|
SS$_NOOBJSRV
|
The audit server process, which maintains the security profile for
resource domains, is not running. The process access rights to the
domain cannot be determined, so access is denied.
|
|
SS$_NOPRIV
|
Access to the resource domain was denied.
|
|
SS$_RSDM_ACTIVE
|
Unable to leave the resource domain because there are locks still
associated with this resource domain.
|
|
SS$_RSDMNOTFOU
|
The resource domain was not found.
|
|
