 |
HP OpenVMS System Services Reference Manual
$PERSONA_RESERVE (Alpha and Integrity servers)
On Alpha and Integrity server systems, reserves a persona ID in the
server's persona table to be filled in by the $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's
to-be-delegated persona.
Description
This service reserves a persona identifier slot within the current
process for a specific client process to use in delegating its persona
to this process. A reserved persona slot can be deleted by a call to
the $PERSONA_DELETE service. When a return fails, no persona slot has
been reserved for the client process.
The delegation of persona is only supported for processes residing on
the 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.
|
$POWER_CONTROL
Manipulates the platform's power and performance settings to the value
specified in the power_setting parameter. This applies to the entire
system just as though commanded through the Integrated Lights-Out (iLO)
web interface.
Format
SYS$POWER_CONTROL power_setting, current_value
C Prototype
int sys$power_control unsigned __int64 power_setting, unsigned __int64
*current_value;
Arguments
power_setting
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 64-bit value |
A quadword value to specify the new power or performance setting.
current_value
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 64-bit value |
The address of a quadword for the service to return the current setting
(optional).
Description
Power control on Integrity servers comprises power saving strategies
and a means of commanding a strategy to be used. The various means of
commanding include iLO web interface, Insight Power Manager (IPM), and
EFI command line.
Regardless of the interface used (iLO web interface, IPM, or EFI
command line), iLO commanding can specify one of the following four
states:
- Operate at the highest possible performance ("High Performance
Mode")
- Operate using the least possible power ("Low Power Mode")
- Operate using some efficient compromise between power and
performance ("Efficiency Mode")
- Give power control over to some OS-defined method ("OS Control")
"OS Control Mode", including platforms which have no iLO power
commands, is implemented on OpenVMS by the system service
$POWER_CONTROL.
This service can be used on all Integrity server platforms.
Power Setting---Enumerated values are as follows:
- POWER$C_HIGHEST_PERF---Similar to the iLO 'highest performance'
command
- POWER$C_LOWEST_POWER---Similar to the iLO 'lowest power' command
- POWER$C_EFFICIENCY---Similar to the iLO 'efficiency' command
Previous Value (Optional)---Returns the previous power control state.
Additional values can be added to provide finer control than is
possible with the iLO command, but they are not implemented initially.
Required Access or Privileges
This service requires WORLD privilege.
Related Quota
None
Related Services
None
Condition Values Returned
|
SS$_NORMAL
|
The requested action is performed.
|
|
SS$_WRONGSTATE
|
The platform power state is not set to OS control.
|
|
SS$_ACCVIO
|
The address specified by current_value is not writable.
|
|
SS$_BADPARAM
|
The value of power_setting is not a legal value.
|
|
SS$_NOWORLD
|
The user does not have the WORLD privilege, which is required to use
this service.
|
$PROCESS_AFFINITY (Alpha and Integrity servers)
On Alpha and Integrity server systems, allows modification of the CPU
affinity set for a specified kernel thread.
This service accepts 64-bit addresses.
Format
SYS$PROCESS_AFFINITY [pidadr], [prcnam], [select_mask], [modify_mask],
[prev_mask], [flags] [,[mask_length]]
C Prototype
int sys$process_affinity (unsigned int *pidadr, void *prcnam, struct
_generic_64 *select_mask, struct _generic_64 *modify_mask, struct
_generic_64 *prev_mask, struct _generic_64 *flags,...);
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 affinity mask 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 affinity mask of the current kernel
thread of the calling process. The pidadr argument
takes precedence over the prcnam argument in any
circumstances where both are supplied in the service call.
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 affinity mask 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 affinity 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.
select_mask
| OpenVMS usage: |
bitmap |
| type: |
quadword bitmap |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The select-mask argument specifies which bits of the
specified process's affinity mask are to be modified. The
select_mask argument is the 32- or 64-bit address of a
quadword bit vector wherein a bit, when set, specifies that the
corresponding CPU position in the mask is to be modified.
modify_mask
| OpenVMS usage: |
bitmap |
| type: |
quadword bitmap |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Mask specifying the settings for those explicit affinities selected in
the select_mask argument. The
modify_mask argument is the 32- or 64-bit address of a
quadword bit vector wherein a bit, when set, specifies that the
corresponding CPU is to be added to the specified process affinity set;
when clear, the corresponding CPU is to be removed from the specified
process affinity set.
To add a specific CPU to the affinity mask set, that bit position must
be set in both select_mask and
modify_mask. To remove a specific CPU from the
affinity mask set, that bit position must be set in
select_mask and clear in modify_mask.
The constant CAP$K_ALL_CPU_ADD, when specified in
modify_mask, indicates that all CPUs specified in
select_mask are to be added to the affinity mask set.
The constant CAP$K_ALL_CPU_REMOVE indicates that all CPUs in
select_mask are to be removed from the affinity mask
set.
prev_mask
| OpenVMS usage: |
bitmap |
| type: |
quadword bitmap |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Previous CPU affinity mask for the specified kernel thread before
execution of this call to $PROCESS_AFFINITY. The
prev_mask argument is the 32- or 64-bit address of a
quadword into which $PROCESS_AFFINITY writes the previous explicit
affinity bitmap.
flags
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Options selected for affinity modification. The flags
argument is a quadword bit vector wherein a bit corresponds to an
option. Only the bits specified below are used; the remainder of the
quadword bits are reserved and must be 0.
Each option (bit) has a symbolic name, which the $CAPDEF macro defines.
The flags 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_FLAG_PERMANENT
|
Indicates whether to modify the permanent process affinities in
addition to the current image copy. If CAP$M_FLAG_PERMANENT is set,
then both the permanent and current affinities are modified. If the
flag bit is clear or
flags is unspecified, then just the current image
process affinities are modified.
This bit also determines which of the affinity masks are returned in
prev_mask. If set, the permanent mask, used to
reinitialize the current set at image rundown, is returned. If the bit
is clear or the
flags argument is not specified, the current running
mask is returned.
|
|
CAP$M_FLAG_CHECK_CPU
|
Determines whether the kernel thread can be left in a nonrunnable state
under some circumstances. No operation of this service will allow a
transition from a runnable to blocked state; however, if the kernel
thread is already at a blocked state, this bit determines whether the
result of the operation must leave it runnable. If CAP$M_FLAG_CHECK_CPU
is set or
flags is unspecified, the kernel thread will be
checked to ensure it can safely run on one of the CPUs in the active
set; otherwise, any valid state operations on kernel threads already in
a blocked state will be allowed.
|
|
CAP$M_FLAG_CHECK_CPU_ACTIVE
|
Indicates whether a check is made to verify that all CPUs in the select
mask that are about to be selected for affinity binding are in the
active set. This does not apply to CPUs that are about to be cleared
from the current affinity set. Unlike CAP$M_FLAG_CHECK_CPU where only a
single CPU has to be valid for the condition to pass,
CAP$M_FLAG_CHECK_CPU_ACTIVE requires that all CPUs in the selected set
must pass the criteria.
|
|
CAP$M_PURGE_WS_IF_NEW_RAD
|
Causes the working set of the process to be purged if the choice of
affinity results in a change to the home RAD of the process.
|
mask_length
| OpenVMS usage: |
bitmap |
| type: |
quadword bitmap |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The mask_length specifies the length in bytes of each
of the three bitmaps: select_mask,
modify_mask, prev_mask. If
mask_length is not supplied or specified as zero, a
length of 8 bytes is used.
The correct value for mask_length is determined by the
number of supported CPUs on the system. You can compute the number of
bytes needed for the bitmap as follows: Use the $GETSYI system service
with an item code of SYI$_MAX_CPUS to find the minimum number of bits
needed, round this number up to a multiple of 64, and divide the result
by 8.
Description
The Modify Process Affinity system service, based on the arguments
select_mask and modify_mask, adds or
removes CPUs from the specified kernel thread's affinity mask sets. If
specified, the previous affinity mask is returned in
prev_mask. With the modify_mask
argument, multiple CPUs can be added to or removed from the process
affinity mask set in the same system service call.
Adding a specific CPU to the process affinity mask indicates that the
kernel thread is able to execute only on that CPU or on the others
specified in the mask. Affinity scheduling takes effect as soon as the
affinity mask becomes nonzero, limiting the CPU selection for the
kernel thread to what is specified and available. Thread selection and
execution is still subject to standard capability requirements, but
only the affinity CPU set is considered when looking for an available
site. When the affinity mask is cleared, all CPUs are again considered
available and affinity is deactivated.
Either modify_mask or prev_mask, or
both, must be specified as arguments. If modify_mask
is specified, then select_mask must be specified as an
argument. If modify_mask is not specified, then no
modifications are made to the affinity mask for the specified kernel
thread. In this case, select_mask is ignored. If
prev_mask is not specified, then no previous mask is
returned.
No service changes will be allowed if the specified kernel thread will
transition from a runnable to blocked state. The CAP$M_FLAG_CHECK_CPU
bit in the flags argument requires that the final
thread state be runnable regardless of previous state; otherwise,
interim changes that maintain a blocked state are allowed if the thread
is already in one.
Required Privileges
The caller must have the ALTPRI privilege to call SYS$PROCESS_AFFINITY
to modify its own affinity mask. To modify another process' affinity
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$PROCESS_AFFINITY simply to retrieve the specific process or
global mask, 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
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_BADPARAM
|
One of more arguments has an invalid value.
|
|
SS$_ACCVIO
|
The service cannot access the locations specified by one or more
arguments.
|
|
SS$_NOPRIV
|
Insufficient privilege for attempted operation.
|
|
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 has more than 15
characters.
|
|
SS$_CPUCAP
|
No CPU can run the specified process with new affinities.
|
|
SS$_INSFARG
|
Fewer than the required number of arguments were specified or no
operation was specified.
|
$PROCESS_CAPABILITIES (Alpha and Integrity servers)
On Alpha and Integrity server systems, allows modification of the user
capability set for a specified kernel thread, or for the global user
capability process default.
This service accepts 64-bit addresses.
Format
SYS$PROCESS_CAPABILITIES [pidadr] [,prcnam] [,select_mask]
[,modify_mask] [,prev_mask] [,flags]
C Prototype
int sys$process_capabilities (unsigned int *pidadr, void *prcnam,
struct _generic_64 *select_mask, struct _generic_64 *modify_mask,
struct _generic_64 *prev_mask, struct _generic_64 *flags);
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 user capability
mask 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 calling process. The pidadr argument
takes precedence over the prcnam argument where both
are supplied in the service call.
If the constant CAP$M_FLAG_DEFAULT_ONLY is specified in
flags, then the user portion of the default process
user capability mask is modified or returned instead, regardless of the
values specified in pidadr.
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 user capability mask 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.
You can use the prcnam argument only if the process
identified by the descriptor has the same UIC group number as the
calling process. To obtain information about processes in other groups,
the pidadr argument must be used.
If pidadr and prcnam are both
specified, then prcnam is ignored. If neither argument
is specified, then the context of the current kernel thread of the
calling process is modified or returned.
select_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Mask specifying which bits of the specified process' user capability
mask are to be modified. The select_mask argument is
the 32- or 64-bit address of a quadword bit vector wherein a bit, when
set, specifies that the corresponding user capability is to be modified.
The individual user capability bits in select_mask can
be referenced by their symbolic bit constant names, CAP$M_USER1 through
CAP$M_USER16. These constants (not zero-relative) specify the position
in the mask quadword that corresponds to the bit name. Multiple
capabilities can be selected by ORing together the appropriate bits.
Alternatively, the constant CAP$K_ALL_USER, when specified as the
select_mask argument, selects all user capabilities.
modify_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Mask specifying the settings for those capabilities selected in the
select_mask argument. The modify_mask
argument is the 32- or 64-bit address of a quadword bit vector wherein
a bit, when set, specifies that the corresponding user capability is to
be added to the specified kernel thread; when clear, the corresponding
user capability is to be removed.
The symbolic bit constants CAP$M_USER1 through CAP$M_USER16 can be used
to modify the appropriate bit position in modify_mask.
Multiple capabilities can be modified by ORing together the appropriate
bits.
To add a specific user capability to a kernel thread, that bit position
must be set in both select_mask and
modify_mask. To remove a specific user capability from
a kernel thread, that bit position must be set in
select_mask and clear in modify_mask.
The symbolic constant CAP$K_ALL_USER_ADD, when specified in
modify_mask, indicates that all capabilities specified
in select_mask are to be added to the appropriate
capability set. The symbolic constant CAP$K_ALL_USER_REMOVE indicates
that all specified capabilities are to be removed from the set.
prev_mask
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Previous user capability mask for the specified process or thread
before execution of this call to $PROCESS_CAPABILITIES. The
prev_mask argument is the 32- or 64-bit address of a
quadword into which $PROCESS_CAPABILITIES writes the previous bit mask.
If CAP$M_FLAG_DEFAULT_ONLY is set in the flags
argument, then prev_mask will contain the user portion
of the global default capability mask.
flags
| OpenVMS usage: |
mask_quadword |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
Options selected for the user capability modification. The
flags argument is a quadword bit vector wherein a bit
corresponds to an option. Only the bits specified below are used; the
remainder of the quadword bits are reserved and must be zero.
Each option (bit) has a symbolic name, defined by the $CAPDEF macro.
The flags 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_FLAG_DEFAULT_ONLY
|
Indicates that the specified operations are to be performed on the
global context 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
service operations to the capabilities for all newly created processes.
|
|
CAP$M_FLAG_PERMANENT
|
Indicates whether to modify the permanent user process capabilities in
addition to the current image copy. If CAP$M_FLAG_PERMANENT is set,
then both the permanent and current user process capabilities are
modified. If this bit is clear or
flags is unspecified, then just the current image
process capabilities are modified.
This bit also determines which of the capability masks are returned
in
prev_mask. If set, the permanent mask, used to
reinitialize the current set at image rundown, is returned. If the bit
is clear or the
flags argument is not specified, the current running
mask is returned.
|
|
CAP$M_FLAG_CHECK_CPU
|
Determines whether the kernel thread can be left in a nonrunnable state
under some circumstances. No operation of this service will allow a
transition from runnable to blocked state; however, if the kernel
thread is already at a blocked state, this bit determines whether the
result of the operation must leave it runnable. If CAP$M_FLAG_CHECK_CPU
is set or
flags is unspecified, the kernel thread will be
checked to ensure it can safely run on one of the CPUs in the active
set; otherwise, any state operations on kernel threads already in a
blocked state will be allowed.
|
|
CAP$M_PURGE_WS_IF_NEW_RAD
|
Causes the working set of the process to be purged if the choice of
capability results in a change to the home RAD of the process.
|
Description
The Modify Process User Capabilities system service, based on the
arguments select_mask and
modify_mask, adds or removes user capabilities for the
specified kernel thread. If specified, the previous capability mask is
returned in prev_mask. With the
modify_mask argument, multiple user capabilities for a
kernel thread can be added or removed in the same system service call.
|
