View source for $SETPRI

'''$SETPRI''', or '''Set Priority''', is a [[System Service|system service]] that changes the [[Base Priority|base priority]] of a process.

=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|pidadr]] nor the [[#prcnam|prcnam]] argument, $SETPRI sets the base priority of the calling process.

If the longword at address [[#pidadr|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 [[$GETJPI|Get Job/Process Information ($GETJPI)]] service.

=Syntax=
 <nowiki>SYS$SETPRI [</nowiki>[[#pidadr|pidadr]]<nowiki>] ,[</nowiki>[[#prcnam|prcnam]]<nowiki>] ,</nowiki>[[#pri|pri]]<nowiki> ,[</nowiki>[[#prvpri|prvpri]]<nowiki>] ,[</nowiki>[[#nullarg|nullarg]]<nowiki>] ,[</nowiki>[[#nullarg|nullarg]]<nowiki>]</nowiki>

C prototype:
int sys$setpri
    (unsigned int *pidadr, void *prcnam, unsigned int pri,
     unsigned int *prvpri, unsigned int *pol, unsigned int *prvpol);

=Arguments=
==pidadr==
{{SyservArgument|process_id|longword (unsigned)|modify|by reference}}

[[PID|Process identification (PID)]] of the process whose [[Base Priority|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|cluster]].

==prcnam==
{{SyservArgument|process_name|character-coded text string|read only|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==
{{SyservArgument|longword_unsigned|longword (unsigned)|read only|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==
{{SyservArgument|longword_unsigned|longword (unsigned)|read only|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==
{{SyservArgument|longword_unsigned|longword (unsigned)|read only|by reference}}

On [[Alpha]] and [[Integrity]] server systems, address of a longword containing the new scheduling policy for the process. The [[$JPIDEF]] macro defines the following symbols for the policy argument:

{| class="wikitable"
! colspan="col" | Symbol
! colspan="col" | 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==
{{SyservArgument|longword_unsigned|longword (unsigned)|write only|by reference}}

On [[Alpha]] and [[Integrity]] server 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==
{{SyservArgument|ef_number|longword (unsigned)|read only|by value}}

Placeholding argument reserved to OpenVMS.

=Condition Values Returned=
{| class="wikitable"
! colspan="col" | Value
! colspan="col" | Description
|-
| 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.)
|}

=Privileges Required=
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.

=Quota Required=
None

=See also=
* [http://www.eight-cubed.com/examples/framework.php?file=sys_setpri.c James F. Duff's example on eight-cubed.com]
* [[$CANEXH]]
* [[$CREPRC]]
* [[$DCLEXH]]
* [[$DELPRC]]
* [[$EXIT]]
* [[$FORCEX]]
* [[$GETJPI]]
* [[$GETJPIW]]
* [[$HIBER]]
* [[$PROCESS_SCAN]]
* [[$RESUME]]
* [[$SETPRN]]
* [[$SETPRV]]
* [[$SETRWM]]
* [[$SUSPND]]
* [[$WAKE]]

[[Category:System Services]]