 |
HP OpenVMS System Services Reference Manual
$SETIME
Changes the value of, or recalibrates, the system time.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$SETIME [timadr]
C Prototype
int sys$setime (struct _generic_64 *timadr);
Argument
timadr
| OpenVMS usage: |
date_time |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64); by 32-bit
reference (VAX) |
New absolute time value for the system time, specifying the number of
100-nanosecond intervals since 00:00 o'clock, November 17, 1858. The
timadr argument is the 32-bit address (on VAX systems)
or the 32- or 64-bit address (on Alpha and I64 systems) of a quadword
containing the new system time value. A negative (delta) time value is
invalid.
If you do not specify the value of timadr or specify
it as 0, $SETIME recalibrates the system time using the time-of-year
clock.
Description
The Set System Time service (1) changes the value of or (2)
recalibrates the system time, which is defined by a quadword value that
specifies the number of 100-nanosecond intervals since 00:00 o'clock,
November 17, 1858.
System time is the reference used for nearly all timer-related software
activities in the operating system. After changing or recalibrating the
system clock, $SETIME updates the timer queue by adjusting each element
in the timer queue by the difference between the previous system time
and the new system time.
The $SETIME service saves the new time (for future bootstrap
operations) in the system image SYS$SYSTEM:SYS.EXE on VAX systems or
SYS$LOADABLE_IMAGES:SYS$BASE_IMAGE.EXE on Alpha and I64 systems. To
save the time, the service assigns a channel to the system boot device
and calls $QIOW. You need the LOG_IO user privilege to perform this
operation.
Required Access or Privileges
To set system time, the calling process must have OPER, LOG_IO, and
SYSPRV privileges.
Required Quota
None
Related Services
$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIMR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The quadword that contains the new system time value cannot be read by
the caller.
|
|
SS$_IVTIME
|
The caller specified no time value or a negative time value and an
invalid processor clock was found.
|
|
SS$_NOIOCHAN
|
No I/O channel is available for assignment.
|
|
SS$_NOPRIV
|
The process does not have the privileges to set the system time.
|
$SETIMR
Sets the timer to expire at a specified time.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]
C Prototype
int sys$setimr (unsigned int efn, struct _generic_64 *daytim, void
(*astadr)(__unknown_params), unsigned __int64 reqidt, unsigned int
flags);
Arguments
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Event flag to be set when the timer expires. The efn
argument is a longword value containing the number of the event flag;
however, $SETIMR uses only the low-order byte.
If you do not specify efn, event flag 0 is used.
When $SETIMR first executes, it clears the specified event flag or
event flag 0.
daytim
| OpenVMS usage: |
date_time |
| type: |
quadword |
| access: |
read only |
| mechanism: |
by 64-bit reference (Alpha and I64); by 32-bit reference
(VAX) |
Time at which the timer expires. The daytim argument
is the 64-bit address (on Alpha and I64 systems) or the 32-bit address
(on VAX systems) of a quadword time value. A positive time value
specifies an absolute time at which the timer expires; a negative time
value specifies an offset (delta time) from the current time.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by 64-bit reference (Alpha and I64); by 32-bit reference
(VAX) |
AST service routine that is to execute when the timer expires. The
astadr argument is the 64-bit address (on Alpha and
I64 systems) or the 32-bit address (on VAX systems) of the procedure
value of this routine. If you do not specify the value of
astadr or specify it as 0 (the default), no AST
routine executes.
The AST routine, if specified, executes at the access mode of the
caller.
reqidt
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identification of the timer request. The reqidt
argument is a longword value containing a number that uniquely
identifies the timer request. If you do not specify
reqidt, the value 0 is used.
To cancel a timer request, the identification of the timer request (as
specified by reqidt in $SETIMR) is passed to the
Cancel Timer ($CANTIM) service (as the reqidt
argument).
If you want to cancel specific timer requests but not all timer
requests, be sure to specify a nonzero value for
reqidt in the $SETIMR call; $CANTIM interprets an
identification value of 0 as a request to cancel all timer requests.
You can specify unique values for reqidt for each
timer request or give the same value to related timer requests. This
permits selective canceling of a single timer request, a group of
related timer requests, or all timer requests.
If you specify the astadr argument in the $SETIMR
call, the value specified by the reqidt argument is
passed as a parameter to the AST routine. If the AST routine requires
more than one parameter, specify an address for the value of
reqidt; the AST routine can then interpret that
address as the beginning of a list of parameters.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Longword of bit flags for the set timer operation. Currently, only bit
0 is used for the flags argument. When the low bit
(bit 0) is set, it indicates that this timer request should be in units
of CPU time, rather than elapsed time. When bit 0 is clear (the
default), the timer request is in units of elapsed time. The
flags argument is optional.
Description
The Set Timer service sets the timer to expire at a specified time.
When the timer expires, an event flag is set and (optionally) an AST
routine executes. This service requires dynamic memory and executes at
the access mode of the caller, as does the AST routine if one is
specified.
Required Access or Privileges
None
Required Quota
This service uses the process's timer queue entries (TQELM) quota. If
you specify an AST routine, the service uses the AST limit (ASTLM)
quota of the process.
Related Services
$ASCTIM, $BINTIM, $CANTIM, $CANWAK, $GETTIM, $NUMTIM, $SCHDWK, $SETIME
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The expiration time cannot be read by the caller.
|
|
SS$_EXQUOTA
|
The process exceeded its quota for timer entries or its AST limit
quota; or the system dynamic memory is insufficient for completing the
request.
|
|
SS$_ILLEFC
|
You specified an illegal event flag number.
|
|
SS$_INSFMEM
|
The dynamic memory is insufficient for allocating a timer queue entry.
|
|
SS$_UNASEFC
|
The process is not associated with the cluster containing the specified
event flag.
|
$SETPRA
Establishes a routine to receive control after a power recovery is
detected.
Format
SYS$SETPRA astadr ,[acmode]
C Prototype
int sys$setpra (int (*astadr)(__unknown_params), unsigned int acmode);
Arguments
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference |
Power recovery AST routine to receive control when a power recovery is
detected. The astadr argument is the address of this
routine.
If you specify astadr as the value 0, an AST is not
delivered to the process when a power recovery is detected.
The system passes one parameter to the specified AST routine. This
parameter is a longword value containing the length of time that the
power was off, expressed as the number of 1/100th-of-a-second intervals
that have elapsed.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode at which the power recovery AST routine is to execute. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines symbols for the access modes.
The most privileged access mode used is the access mode of the caller.
Description
The Set Power Recovery AST service establishes a routine to receive
control after a power recovery is detected.
You can specify only one power recovery AST routine for a process. The
AST entry point address is cleared at image exit.
The entry and exit conventions for the power recovery AST routine are
the same as for all AST service routines.
Required Access or Privileges
None
Required Quota
One unit of quota is deducted from the process's ASTLM.
Related Services
$DCLAST, $SETAST
For more information, refer to the chapter on AST services in the
OpenVMS Programming Concepts Manual.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_EXQUOTA
|
The process exceeded its quota for outstanding AST requests.
|
$SETPRI
Changes the base priority of the process. The base priority is used to
determine the order in which executable processes are to run.
Format
SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri] ,[nullarg] ,[nullarg]
C Prototype
int sys$setpri (unsigned int *pidadr, void *prcnam, unsigned int pri,
unsigned int *prvpri, unsigned int *pol, unsigned int *prvpol);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process whose priority is to be
set. The pidadr argument is the address of the PID.
The pidadr argument can refer to a process running on
the local node or a process running on another node in the cluster.
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.
A process running on the local node can be identified with a 1- to
15-character string. To identify a process on a particular node on a
cluster, specify the full process name, which includes the node name as
well as the process name. The full process name can contain up to 23
characters.
You can use the prcnam argument only on behalf of
processes in the same UIC group as the calling process. To set the
priority for processes in other groups, you must specify the
pidadr argument.
pri
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
New base priority to be established for the process. The
pri argument is a longword value containing the new
priority. Priorities that are not real time are in the range 0 through
15; real-time priorities are in the range 16 through 31.
If the specified priority is higher than the base priority of the
target process, and if the caller does not have ALTPRI privilege, then
the base priority of the target process is used.
prvpri
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Base priority of the process before the call to $SETPRI. The
prvpri argument is the address of a longword into
which $SETPRI writes the previous base priority of the process.
policy
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
On Alpha and I64 systems, address of a longword containing the new
scheduling policy for the process.
The $JPIDEF macro defines the following symbols for the
policy argument:
| Symbol |
Meaning |
|
JPI$K_DEFAULT_POLICY
|
The normal scheduling policy. The priority interval for this policy is
defined as [0..
n], such that priorities [0..15] are interactive and
priorities [16..
n] are real time.
|
|
JPI$K_PSX_FIFO_POLICY
|
POSIX FIFO scheduling policy. The priority interval for this policy is
defined as [
n..
m] real-time priorities.
|
|
JPI$K_PSX_RR_POLICY
|
POSIX round-robin policy. The priority interval for this policy is
defined as [
n..
m] real-time priorities.
|
prvpol
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
On Alpha and I64 systems, address of a longword into which the previous
scheduling policy for the process is written. If the
policy argument is null, no change in policy is
requested and prvpol returns the current policy.
The valid priority intervals for specific scheduling policies might
change in the future. Applications should, therefore, not use embedded
numeric constants for scheduling priority, but should use the
appropriate $GETSYI item codes to fetch the legal priority intervals.
The application can then dynamically select a priority value that is
within the interval. The $GETSYI item codes are:
- SYI$_DEF_PRIO_MAX, SYI$_DEF_PRIO_MIN
- SYI$_PSXFIFO_PRIO_MAX, SYI$_PSXFIFO_PRIO_MIN
- SYI$_PSXRR_PRIO_MAX, SYI$_PSXRR_PRIO_MIN
See the Item Codes section of the $GETSYI service description for more
information about these item codes.
nullarg
| OpenVMS usage: |
null_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Placeholding argument reserved to HP.
Description
The Set Priority service changes the base priority of the process or,
optionally, changes the scheduling policy of the process. The base
priority is used to determine the order in which executable processes
are to run.
The scheduling policy denotes the following:
- The basic scheduling discipline (FIFO, round-robin, and so forth).
- The preemption/compensation rules by which a running process is
descheduled in favor of another process and, ultimately, rescheduled.
A source process can modify the priority or scheduling policy of a
target process if any of the following are true:
- The source and target processes are in the same job tree.
- The source and target processes have the same UIC.
- The source process has WORLD privilege enabled.
- The source and target processes are in the same process group.
The value to which the priority of a process can be set can be subject
to limitations. If the source has ALTPRI privilege enabled, the target
can be set to any valid priority. Otherwise, the priority value
specified by the source process is compared to the authorized priority
of the target process and the smaller of the two values is used as the
new base priority of the target process.
If you specify neither the pidadr nor the
prcnam argument, $SETPRI sets the base priority of the
calling process.
If the longword at address pidadr is the value 0, the
PID of the target process is returned.
The base priority of a process remains in effect until specifically
changed or until the process is deleted.
To determine the priority set by the $SETPRI service, use the Get
Job/Process Information ($GETJPI) service.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $SETPRI:
- GROUP privilege to change the priority of a process in the same
group, unless the target process has the same UIC as the calling
process.
- WORLD privilege to change the priority of any other process in the
system.
- ALTPRI privilege to set any process's priority to a value greater
than the target process's initial base priority. If a process does not
have ALTPRI privilege, the priority value specified by the source
process is compared to the authorized priority of the target process
and the smaller of the two values is used as the new base priority of
the target process.
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW,
$HIBER, $PROCESS_SCAN, $RESUME, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification or previous priority longword
cannot be written by the caller.
|
|
SS$_ILLPOLICY
|
An invalid scheduling policy was specified.
|
|
SS$_ILLPRIPOL
|
Setting the process to the specified priority and/or policy would
result in an illegal policy/priority combination. The illegal
combination can occur between the SETPRI policy and priority parameters
themselves, or it can occur between either of the parameters and the
current policy and/or priority of the target process.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_IVLOGNAM
|
The process name string has a length of 0 or has more than 15
characters.
|
|
SS$_NONEXPR
|
The specified process does not exist, or an invalid process
identification was specified.
|
|
SS$_NOPRIV
|
The process does not have the privilege to affect other processes.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the cluster.
|
|
SS$_REMRSRC
|
The remote node has insufficient resources to respond to the request.
(Bring this error to the attention of your system manager.)
|
|
SS$_UNREACHABLE
|
The remote node is a member of the cluster but is not accepting
requests. (This is normal for a brief period early in the system boot
process.)
|
|
