setitimer (BPX1STR, BPX4STR) — Set the value of the iterval timer

Function

The setitimer callable service sets the timer value and optionally returns a pointer to a structure that contains the previous timer value. This function also generates a signal that is to be delivered when the interval timer expires.

Requirements

Parameters

Interval_Type

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains a numeric value that identifies the interval timer (these values apply to both Interval_Value_Adr and Old_Interval_Value_Adr). This parameter can have the following values:

ITIMER_REAL

Real time (the default if VIRTUAL and PROF are not specified)

ITIMER_VIRTUAL

Virtual time (CPU time minus system time)

ITIMER_PROF

CPU time

ITIMER_MICRO

The initial and reload times are in microseconds (the default if NANO is not specified)

ITIMER_NANO

The initial and reload times are in nanoseconds

The ITIMER_ constants are defined in the BPXYITIM macro.

Interval_Value_Adr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

A fullword (doubleword) field containing the address of a structure that is defined by the BPXYITIM macro. This structure contains the initial interval and reload values in seconds and either microseconds or nanoseconds.

Old_Interval_Value_Adr

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

A fullword (doubleword) field containing the address of a structure that is defined by the BPXYITIM macro. This structure contains the time remaining and reload values in seconds and either microseconds or nanoseconds. This address may be zero if the current values are of no interest to the user.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setitimer service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setitimer service stores the return code. The setitimer service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The setitimer service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One of the following occurred: The value that was specified for Interval_Type is incorrect (JrStrIntervalTypeInvalid). The value that was specified in the structure that is pointed to by Interval_Value_Adr is incorrect (JrNanoSecondsTooBig, JrMSecondsTooBig, JRNegativeValueInvalid).

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the setitimer service stores the reason code. The setitimer service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.

Usage notes

1. The time between signals is maintained as a priority over the number of signals in an extended period of time. A delay in processing could result in a late signal; the signal generated by the reload value maintains the requested interval. As with other signals, multiples are lost. For example, for a 1 second timer, delays might result in 3597 signals per hour, with no two timers closer than 1 second. If the application requires exactly 3600 signals per hour, a reload value of zero should be used, and a new setitimer should be calculated and issued by the signal handler.
2. The duration between signals is always greater than, or equal to, the reload value that is specified.
3. Intervals vary, depending on when MVS™ gives the task its time slices.
4. The setting of the first two words of the Interval_Value disables the timer, regardless of the reload value (third and fourth words).
5. Any setitimer() cancels the previous timer of the same type (that is, REAL, VIRTUAL, or PROF).
6. Real interval timers and alarms are treated as mutually exclusive. If an ITIMER_REAL interval timer is issued while an alarm is set, the ITIMER_REAL interval timer overlays the alarm, and vice versa.
7. The setitimer environment is propagated on the exec() and not propagated on fork().
8. Below are the interval timers and the corresponding signals that are to be generated when the timer expires:
   • ITIMER_REAL, which decrements in real time. A SIGALRM signal is delivered when this timer expires.
   • ITIMER_VIRTUAL, which decrements in task virtual time. It runs only when the task is executing outside the kernel. A SIGVTALRM signal is delivered when it expires. Task virtual is a best estimate, and loses significance when it is run in a multiprocess environment.
   • ITIMER_PROF, which decrements in task time. It runs when the task is running on behalf of the process. A SIGVPROF signal is delivered when it expires.
9. The setitimer(), alarm(), and sleep() services use the MVS STIMERM macro. If the task invokes the STIMERM macro and a combination of these services, the limit of concurrent STIMERM SET requests for a task can be exceeded, which results in an abnormal end.
10. ITIMER_REAL interval timers are supported in both multiprocess and multithreaded environments.
11. You can issue Setitimer() for ITIMER_PROF or ITIMER_VIRTUAL in a multithreaded or multiprocess environment. However, for ITIMER_VIRTUAL in a multithread environment, the results may be unpredictable.
12. If two interval timers of the same type expire before a signal is delivered, only one signal is generated.
13. The reload time is set before the signal interface routine is given control.

MVS-related information

• getitimer (BPX1GTR, BPX4GTR) — Get the value of the interval timer
• alarm (BPX1ALR, BPX4ALR) — Set an alarm

Characteristics and restrictions

None (other than those indicated in the usage notes).