 |
HP OpenVMS System Services Reference Manual
$SET_DEFAULT_TRANSW
Sets or clears the default transaction of the calling process.
$SET_DEFAULT_TRANSW always waits for the request to complete before
returning to the caller. Other than this, it is identical to
$SET_DEFAULT_TRANS.
Format
SYS$SET_DEFAULT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[new_tid] ,[old_tid]]
C Prototype
int sys$set_default_transw (unsigned int efn, unsigned int flags,
struct _iosb *iosb,...);
$SET_DEVICE
Modifies the characteristics of a device or the paths used to access
that device.
For synchronous completion, use the Set Device Characteristics and Wait
($SET_DEVICEW) service. The $SET_DEVICEW service is identical to the
$SET_DEVICE service, except that $SET_DEVICEW returns to the caller
only after the requested action has taken effect.
For additional information about system service completion, see the
Synchronize ($SYNCH) service.
Format
SYS$SET_DEVICE [efn] [,chan] [,devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
C Prototype
int sys$set_device (unsigned int efn, unsigned short int chan, void
*devnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), int astprm, struct_generic_64 *nullarg);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the event flag to be set when $SET_DEVICE returns the
requested information. The efn argument is a longword
containing this number; however, $SET_DEVICE uses only the low-order
byte.
Upon request initiation, $SET_DEVICE clears the specified event flag
(or event flag 0 if efn was not specified). Then, when
$SET_DEVICE returns the requested information, it sets the specified
event flag (or event flag 0).
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word
containing this number.
To identify a device to $SET_DEVICE, you can specify either the
chan or devnam parameters, but you
should not specify both. If you specify both arguments, the
chan argument is used.
If you specify neither chan nor
devnam, $SET_DEVICE uses a default value of 0 for
chan.
devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor-fixed-length string
descriptor |
The name of the device about which $SET_DEVICE is to modify the
characteristics or path settings. The devnam argument
is the address of a character string descriptor pointing to this name
string.
The device name string can be either a physical device name or a
logical name. If the first character in the string is an underscore
(_), the string is considered a physical device name; otherwise, the
string is considered a logical name and logical name translation is
performed until either a physical device name is found or the system
default number of translations has been performed.
If the device name string contains a colon (:), the colon and the
characters that follow it are ignored.
To identify a device to $SET_DEVICE, you can specify either the
chan or devnam argument, but you
should not specify both. If both arguments are specified, the
chan argument is used.
If you specify neither chan nor
devnam, $SET_DEVICE uses a default value of 0 for
chan.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list
of item descriptors, each of which describes an item of information.
The list of item descriptors is terminated by a longword of 0.
Currently, $SET_DEVICE allows only one valid item list
entry.
The following diagram depicts the format of a single item descriptor:
See the itmlst argument in the $GETDVI system service
description for information on the meaning of these fields in the item
list.
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
I/O status block that is to receive the final completion status. The
iosb argument is the address of the quadword I/O
status block. See iosb in the $GETDVI system service
description for more information.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
AST service routine to be executed when $SET_DEVICE completes. The
astadr argument is the address of this routine.
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 HP 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$_DEVOFFLINE
|
The specified path is not available.
|
|
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$_MPDEVBUSY
|
The specified path for this device is temporarily unavailable. This
condition is quite rare; if this status is returned, the operation
should be retried immediately, because the cause of the unavailability
is very short-lived.
|
|
SS$_MPDEVUSERDISABLE
|
The user has disabled the specified path for this device.
|
|
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 and Integrity servers)
On Alpha and Integrity server 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 Integrity servers)
On Alpha and Integrity server systems, sets a simple value associated
with a process.
Format
SYS$SET_PROCESS_PROPERTIESW mbz1 ,pidadr ,prcnam ,property ,value
,prev_value [,bufsiz ,bufcnt ,flags]
C Prototype
int sys$set_process_propertiesw (mbz1, unsigned int *pidadr, unsigned
int *prcnam, unsigned int property, unsigned __int64 value, unsigned
__int64 *prev_value,...);
Arguments
mbz1
Reserved for future use by HP. Must be specified as 0.
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process whose system service
logging characteristics are to be modified. The pidadr
argument is the address of the PID.
Supported only for use with PPROP$C_SS_LOG_ENABLE,
PPROP$C_SS_LOG_DISABLE, and PPROP$C_SS_LOG_UNLOAD. Otherwise, must be
specified as 0.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name of the process whose priority is to be changed. The
prcnam argument is the address of a character string
descriptor pointing to the process name. The process name can be 1 - 15
characters long.
You can use the prcnam argument only on behalf of
processes in the same UIC group as the calling process. To affect
system service logging for processes in other groups, you must specify
the pidadr argument.
Supported only for use with PPROP$C_SS_LOG_ENABLE,
PPROP$C_SS_LOG_DISABLE, and PPROP$C_SS_LOG_UNLOAD. Otherwise, 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.
For additional information, see the Guide to OpenVMS File Applications.
|
|
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 agairundown. 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.
For additional information, see the Guide to OpenVMS File Applications.
|
|
PPROP$C_SEARCH_SYMLINK_TEMP
|
Processes the active search mode. The value reverts to the permanent
setting on image rundown. Valid values are PPROP$K_SEARCH_SYMLINK_NONE,
PPROP$K_SEARCH_SYMLINK_ALL, and PROP$K_SEARCH_SYMLINK_NOELLIPS.
|
|
PPROP$C_SEARCH_SYMLINK_PERM
|
Processes the permanent search mode. This value is set for the life of
the process. Changing this setting only changes the behavior of
subsequently activated images. Valid values are
PPROP$K_SEARCH_SYMLINK_NONE, PPROP$K_SEARCH_SYMLINK_ALL, and
PROP$K_SEARCH_SYMLINK_NOELLIPS.
|
|
PPROP$C_DEADLOCK_WAIT
|
The per-process deadlock wait time (in 100-ns units). A value of zero
resets and disables the per-process deadlock wait time and fallback to
the systemwide deadlock wait time that comes from the system parameter
DEADLOCK_WAIT. Valid values are in the range of 100000 (=10ms) and
10000000 (=1 s). If the value is too small, the per-process deadlock
wait is set to 10 ms; if the value is too large, it is set to 1 s.
|
|
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.
|
|
PPROP$C_KERNEL_THREAD_LIMIT
|
Sets the process specific limit of the number of kernel threads that
can be created. By default, this is controlled systemwide through the
SYSGEN parameter MULTITHREAD. A value between 0 (use default) and the
current setting of the MULTITHREAD parameter can be used.
|
|
PPROP$C_MEDDLE
|
Reserved for use by HP.
|
|
PPROP$C_MEDDLE_ENABLE
|
Reserved for use by HP.
|
|
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.
|
|
PPROP$C_SS_LOG_DISABLE
|
Stop logging system service requests for the current or specified
process. If logging was previously disabled, the value returned in
prev_value is 0. If logging was previously enabled,
the value returned is 1.
For more information, see the HP OpenVMS System Analysis Tools Manual.
|
|
PPROP$C_SS_LOG_ENABLE
|
Allocate log buffers and enable logging of system service requests for
the current or specified process. If logging was previously disabled,
the value returned in
prev_value is 0. If logging was previously enabled,
the value returned is 1.
For more information, see the HP OpenVMS System Analysis Tools Manual.
|
|
PPROP$C_SS_LOG_UNLOAD
|
Stop logging system service requests for the current or specified
process and close the log file so that it can be analyzed. If logging
was previously disabled, the value returned in
prev_value is 0. If logging was previously enabled,
the value returned is 1.
For more information, see the HP OpenVMS System Analysis Tools Manual.
|
|
PPROP$C_TOKEN
|
Controls the token size used by DCL. When the bit is clear (the
default), traditional tokens are used, and each command token can hold
up to 255 characters. When the bit is set, extended tokens are used;
each command token can be up to 4000 characters.
|
|
PPROP$C_UNITS
|
Controls the process units. When the bit is clear (the default), all
size-related numbers are displayed in blocks. When the bit is set,
size-related numbers are converted to bytes.
|
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.
bufsize
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The requested system service log buffer size in bytes. Supported only
for use with PPROP$C_SS_LOG_ENABLE. If omitted, it defaults to 65,024
bytes. The maximum value is 65,024 bytes. The minimum value is 4096
bytes.
bufcnt
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The requested number of system service log buffers. Supported only for
use with PPROP$C_SS_LOG_ENABLE. If omitted, it defaults to 2. The
maximum number of buffers is 6.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the enable logging request. The
flags argument is a longword bit vector in which each
bit corresponds to a flag. The $LOGTYPDEF macro and the LOGTYPDEF.H
file define a symbolic name for each flag.
|
