Set Timer (QOLTIMER) API

  Required Parameter Group:

1 Return code Output Binary(4)
2 Reason code Output Binary(4)
3 Timer set Output Char(8)
4 Timer to cancel Input Char(8)
5 Qualified queue name Input Char(20)
6 Operation Input Char(1)
7 Interval Input Binary(4)
8 Establish count Input Binary(4)
9 Key length Input Binary(4)
10 Key value Input Char(256)
11 User data Input Char(60)

  Optional Parameter:

12 Queue type Input Char(1)

  Threadsafe: No

The Set Timer (QOLTIMER) API either sets or cancels a timer. Up to 128 timers, each uniquely identified by a name (timer handle), can be set in the job in which the application program is running.

When the QOLTIMER API is called to set a timer, a timer handle (timer set parameter) is returned to the application program. The timer handle, along with the user data supplied when the timer was set, is included in the timer-expired entry that is sent to the data queue or user queue when the specified amount of time for this timer has elapsed. The timer is then reestablished, if necessary.

For example, suppose a user-defined communications application program sets a timer with a five-second interval to be established two times. After five seconds, the timer-expired entry for this timer will be sent to the data queue or user queue specified when the timer was set. The timer will then be automatically reestablished, and five seconds later, another timer-expired entry for this timer will be sent to the data queue or user queue. See Timer-Expired Entry for the format of the timer-expired entry.

In addition to setting a timer, the application program can call the QOLTIMER API to cancel one or all timers currently set in the job in which the application program is running. User-defined communications support will implicitly cancel a timer in the following cases:

Note: User-defined communications support does not associate timers with links. If necessary, that association must be done by the application.


Authorities and Locks

None.


Required Parameter Group

Return code
OUTPUT; BINARY(4)

The recovery action to take. See Return and Reason Codes.

Reason code
OUTPUT; BINARY(4)

The error that occurred. See Return and Reason Codes.

Timer set
OUTPUT; CHAR(8)

The name of the timer (timer handle) that was set. TIMER001, TIMER002, ... , TIMER128 are the possible values.

The content of this parameter is only valid when setting a timer.

Timer to cancel
INPUT; CHAR(8)

The name of the timer (timer handle) to cancel. TIMER001, TIMER002, ... , TIMER128 may be used as values. The special value of *ALL (left-justified and padded on right with spaces) may be used to cancel all timers currently set in the job in which the user-defined communications application program is running.

The content of this parameter is only valid when canceling a timer.

Qualified queue name
INPUT; CHAR(20)

The name and library of the data queue or user queue where the timer-expired entry will be sent when the timer expires. The first 10 characters specify the name of the data queue or user queue and the second 10 characters specify the library in which the queue is located. Both entries are left-justified. The special values of *LIBL and *CURLIB may be used for the library name.

The content of this parameter is only valid when setting a timer.

Operation
INPUT; CHAR(1)

The timer operation to perform. The valid values are as follows:

X'01' Set a timer.
X'02' Cancel a timer.

Interval
INPUT; BINARY(4)

The number of milliseconds for which to set this timer. Any value between 1,048 and 3,600,000 may be used.

The content of this parameter is only valid when setting a timer.

Establish count
INPUT; BINARY(4)

The number of times this timer will be established. Any value between 1 and 60 may be used. The special value of -1 may be used to always have this timer established after it expires.

The content of this parameter is only valid when setting a timer.

Key length
INPUT; BINARY(4)

The key length when using a keyed data queue or user queue. Any value between 0 and 256 may be used, where 0 indicates the data queue or user queue is not keyed.

The content of this parameter is only valid when setting a timer.

Key value
INPUT; CHAR(256)

The key value when using a keyed data queue or user queue.

The content of this parameter is only valid when setting a timer.

User data
INPUT; CHAR(60)

The user data that is to be included in the timer-expired entry when the timer expires.

The content of this parameter is only valid when setting a timer.

Note: This data is treated as character data only and should not contain pointers.


Optional Parameter

Queue type
INPUT; CHAR(1)

The type of queue you specified for the queue name parameter.

D Data queue
U User queue

Return and Reason Codes

Return/Reason Code Meaning Recovery
0/0 Operation successful. Continue processing.
81/9999 Internal system error detected. Escape message CPF91F0 will be sent to the application program when this return and reason code is received. See messages in the job log for further information. Report the problem using the ANZPRB command.
82/1011 Queue type not valid. Correct the queue type parameter. Try the request again.
83/1001 Key length not valid. Correct the key length parameter. Try the request again.
83/1009 Timer operation not valid. Correct the operation parameter. Try the request again.
83/1010 Timer interval not valid. Correct the interval parameter. Try the request again.
83/1011 Number of times to establish timer not valid. Correct the establish count parameter. Try the request again.
83/3400 Timer not valid on cancel operation. Correct the timer to cancel parameter. Try the request again.
83/3401 All timers are currently set for the requested set operation. Cancel a timer. Try the request again.
83/3402 Timer not set on cancel operation. Continue processing.


Error Messages

Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
CPF91F0 E Internal system error.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R1

[ Back to top | Communications APIs | APIs by category ]