nice (BPX1NIC, BPX4NIC) — Change the nice value of a process
Function
The nice callable service changes the nice value of the calling process.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1NIC): | 31-bit |
AMODE (BPX4NIC): | 64-bit |
ASC mode: | Primary mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
CALL BPX1NIC,(Nice_change,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4NIC with the same parameters.
Parameters
- Nice_change
- Supplied parameter
- Type:
- Signed Integer
- Length:
- Fullword
The name of a fullword that contains a value that indicates the relative change in the nice value of the calling process.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the nice service returns
-1
if it is not successful. If it is successful, the nice service returns the new nice value minus NICE_ZERO. The constant NICE_ZERO is defined in the BPXYCONS macro (see BPXYCONS — Constants used by services).Because the nice service can return the value
-1
on successful completion, it is necessary to set the Return_code parameter to 0 before a call to nice. If nice returns the value-1
, the Return_code parameter can be checked to see if an error occurred or if the service was successful. - Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the nice service stores the return code. The nice service returns Return_code only if Return_value is-1
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The nice service can return one of the following values in the Return_code parameter:Return_code Explanation EPERM The nice_change value is negative, and the calling process does not have the appropriate privileges (see Authorization). EMVSSAF2ERR A security product internal error has occurred. Consult Reason_code for the exact reason for the error. ENOSYS The system does not support this function. Your installation has chosen not to enable it. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the nice service stores the reason code. The nice service returns Reason_code only if Return_value is
-1
. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- A process's nice value is a non-negative integer for which a more positive value would result in a lower CPU priority. A minimum nice value of 0 and a maximum value of (2*NICE_ZERO)-1 are imposed on all processes. If the specified nice_change value would result in a nice value that is outside this range, the nice value is set to the limit value. The default nice value for all processes is set to the constant value NICE_ZERO, which is defined in BPXYCONS.
- If the specified nice_change value is negative, the value would result in a lowering of a process's nice value, thus giving the process a higher CPU priority. Only processes with the appropriate privileges (see Authorization) can lower their nice values.
- The changing of a process's nice value has the same effect on a process's priority value,
because they both represent the process's relative CPU priority. For example, increasing the nice
value of a process to its maximum value of
(2*NICE_ZERO)-1
has the effect of setting its priority value via the setpriority service to its maximum value (19), and will be reflected on the nice, getpriority, and setpriority services. - If the calling process is in a multiple-process address space, each of the processes in the address space has its nice value changed by the call to the nice service.
- If the ENOSYS return code is received, your installation does not support this service. Contact your system administrator if you require activation of this service.
- To set up the nice service, see Enabling nice(), setpriority(), and chpriority() support in z/OS UNIX System Services Planning.
Related services
Characteristics and restrictions
If the calling process is running in a multiple-process address space, the nice values of all the processes in the address space are changed upon successful completion of the nice service.