22. PROGRAM TERMINATION
2.3. TIMER SERVICES
During execution of a job, you may want to record the date and time that an event occurred, for example, the date a credit was posted to an accounts receivable record, the date and time a message was received from a remote communications terminal, or the date and time a job step was completed. You can do this by using the GETIME macroi nstruction.
At times you may want to request an interrupt to your program after a specified interval.
For example, you may wish to allow 30 seconds for a response from a terminal, and if no response if received within that time, branch to another subroutine or to another task. You can do this by using the SETIME macroinstruction.
2.3.1. Date and Time Facilities 2.3.11. Current Date
The current date is placed in the systems information block by the operator during initial program load. The date is automatically advanced each day at midnight unless the supervisor was configured at system generation time not to update. In that case, the operator must change the date through a console command. This date is referred to herein as the system date to distinguish it from the job date.
System Information Block
system date
There is a date for each job, which is stored in the preamble for the job. This is the date you get when you use the GETIME macroinstruction. Normally, the job date is the same as the system date. However, you can change it using the SET job control statement which changes the date for your own job and does not disturb the system date or the job dates for other jobs being processed. For example, if your application calls for statements to be produced on the fifteenth of each month but no processing was done that day because of a holiday or because of machine maintenance, you could change the job date in the preamble the next day from 16 to 1 5 so that the statements and other records produced will show the date the job was intended to be run.
Job Preamble
job date
UP-8832
23.1.2. Time of Day
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
2-16
In addition to the current date, the GETIME macroinstruction gives you the time. The current time of day is maintained by a simulated day clock in the system information block. This day clock specifies the amount of time that elapsed since midnight. The clock can show a maximum of 99 hours and maybe permitted to run past midnight if jobswere processing atthattime. The time of day is automatically reset at midnight along with the date unless the supervisor was configured notto update. Otherwise,the operator must resetthe clockeach day. Acommon use of the clock is to record the time of day a job was run and to calculate the length of time required to run it. The job log you receive with your listing shows the start and stop times for your job steps. The run time could be used to charge an account number, or to invoice your department for the computer time required to run your job.
2.3.1 .3. Get Current Date and Time (GETIME) Function
The GETIME macroinstruction obtains the calendar date and the current time of day from the simulated day clock function of the supervisor. The date is returned in register 0, and the time is returned in register 1.
Format:
M
S
Specifies that the current time of representation.
Specifies that the current time format.
day is to be expressed in milliseconds in binary
of day is to be expressed in packed decimal
System Information Block
day clock
C
LABEL LOPERATIONL, [symbol] GET IME
OPERAND
Positional Parameter 1
If omitted, the parameter S is assumed.
UP-8832 SPERRY UNIVAC 05/3 2-17 SUPERVISOR MACROINSTRUCTIONS
The current calendar date is returned in register 0 expressed in packed decimal in the form:
Oyym mdd+
where:
yy = year mm = month dd = day
The high order half byte is always zero, and the low order half byte is the sign, which is always positive.
The current time of day is returned in register 1. If you write this macroinstruction with the S parameter or with no parameter, the time is expressed in packed decimal format in the form:
Ohhmmss+
where:
hh hours mm = minutes ss = seconds
The high order half byte is always zero, and the low order half byte is the sign, which is always positive.
The following entries:
1 10 16
GETIME S
or
GET IME
return the date and time in registers 0 and 1 in packed decimal format. You can then store the contents of these registers, and edit the fields for a printout of the date and exact time that an event occurred.
GET IME
UP-8832 SPERRY UNIVAC OS/3
SUPERVISOR MACROINSTRUCTIONS
2-18
For example, let’s assume you wish to print the date and exact time a job step is completed.
The two subroutines shown in Figure 2—1 each get the date and time from the job preamble and the system information block, unpack and edit them into buffers, then print the contents of the buffers.
1.
Returns date in register 0 and Stores date from register 0 toWSI.
time in register 1.
Stores time from register 1 to WS2.
Unpacks date into BUFFER Unpacks time into BUFFER Changes contents of right hand Changes contents of right hand 3.
Inserts slashes, spaces, and periods in date and time.
Prints date and time from BUFFER.
Terminates the job step.
21. S
T IMMSK( 10) SAVE BUFFER2+10( 8) ,r IMMSK+2 PR I NT ,BUFFER2
Returns date in RO and time in RI.
Stores date in full-word save.
Unpacks and edits date.
Moves edited date to buffer.
Stores time in save.
Unpacks and edits time.
Moves edited time to buffer.
Prints date and time.
29.
K 402 120206 12020612020 X ‘402 120204820204B2020
Buffer initial ized to blanks Date mask format: 99/99/99 Timemaskformat; 99.99.99
Figure 2—1. Examples of GETIME Macroinstruction
Let’s assume the GETIME macroinstruction was executed October 24, 1 977 at 13 seconds after 9:30 A.M. The job date from the preamble would be returned in register 0, and the time from the day clock in the SIB would be returned in register 1. The registers would contain:
Register 0 07 71 02 4C Register 1 00 93 01 3C
UP-8832 SPERRY UNIVAC OS/3 2-19 SUPERVISOR MACROINSTRUCTIONS
Following execution of line 7, BUFFER contains:
7I7hI024I 109I3I0Ih13I
Following execution of line 18, BUFFER contains the date (year/mon/day) and the time (hours.min.sec):
11
10LI2f4The date and time are printed:
77/10/24 09.30.13
If the subroutine in lines 21 through 32 is executed with the same original contents of registers 0 and 1, BUFFER2 will contain the following after execution of line 27
1717LH10L12141 I 10191131011h131
and will print the same date and time as the subroutine of lines 1 through 20.
If you write this macroinstruction using the M parameter, the date is expressed in packed decimal in register 0, but the time is expressed in milliseconds in binary representation in register 1. For example, if the following macro instruction was executed at 10 seconds after midnight, September 26, 1979, registers 0 and 1 would contain:
1 10 16
GET IME M
Register 0 07
I
90 92I
6C Register 1I
00 00I
27I
102.3.2. Timer Interrupt Facilities
The timer services module also enables you to request a scheduled timer interrupt in the requesting task. Using the SETIME macroinstruction you may request an interrupt after any time period greater than 1 millisecond. You may:
‘ continue processing the task until the interrupt, then transfer control to the task’s timer island code;
UP-8832 SPERRY UNIVAC OS/3 2—20 SUPERVISOR MACROINSTRUCTIONS
• suspend processing the task until the interrupt, then continue with the next instruction; or
• cancel a previous SETIME request.
The time interval requested in the SETIME macroinstruction is added to the current time of day to calculate the time when the interrupt is scheduled to occur, and this SETIME expiration time is stored in the task control block.
Task Control Block
SETIME expiration time
timer island code address
If timer island code is to be executed, a STXIT macroinstruction must have been previously issued to link the island code to this task. If no timer island code is present, or if the interrupt request was canceled, the interrupt is ignored. There may only be one set of timer island code per task.
If the task is to be suspended, the next available task in the switch list is executed. When the interrupt occurs, control is returned to the next instruction in the task immediately following the SETIME macroinstruction.
2.3.2.1. Set Timer Interrupt (SETIME) Function:
The SETIME macroinstruction requests a scheduled timer interrupt in the requesting task and continues executing the requesting task. When the specified time interval elapses, the task’s timer island code (as specified by a STXIT macroinstruction) is executed.
Note that, in this case, the STXIT macroinstruction must have been previously issued to set up timer island code for this task. There may be only one set of timer island code per task.
If written with the WAIT parameter, this macroinstruction requests a timer interrupt and suspends execution of the requesting task until the timer interval elapses. At this time, the task resumes execution with the next instruction following the SETIME
macroinstruction.
ç
SPERRY UNIVAC OS/3 SUPERVISOR MACROINSTRUCTIONS
This macroinstruction cancels any previous SETIME request.
macroinstruction with no parameters or with a time interval of effectively eliminate any outstanding SETIME requests without having one.
Positional Parameter 1:
time - i nt e r v aI
Specifies the interval of time that must expire before the interrupt is generated.
This interval is expressed either in seconds or milliseconds depending on the entry in positional parameter 3. The maximum value that may be entered as positional parameter 1 is 4095. To specify a value greater than 4095, enter (1) as positional parameter 1 and preload register 1 with the required time interval value.
(1)
Indicates that register 1 has been preloaded with the time interval value.
If omitted, any previous SETIME request for this task is canceled, preventing the scheduled interrupt.
Positional Parameter 2:
WA I T
Specifies that the problem program is to relinquish control until the specified time interval expires, at which time control is returned to the point immediately following the SETIME macroinstruction.
If omitted, the requesting program retains program control. When the time interval expires, the timer island code is activated.
Positional Parameter 3:
M
$
Specifies that the time interval entered as positional parameter 1 is expressed in milliseconds.
Specifies that the time interval entered as positional parameter 1 is expressed in seconds.
tirne- interval [WAIT] [.{M]
If omitted, the parameter S is assumed.
UP-8832 SPERRY UNIVAC OS/3 2-22 SUPERVISOR MACROINSTRUCTIONS
2.3.2.2. Continue Processing until Interrupt
If you omit the WAIT parameter, the task retains program control and continues processing at the instruction immediately following the SETIME macroinstruction. When the time interval elapses, the timer island code for this task is executed. For example, the instruction:
1 10 16
SETIME 30,, S next instruction
or
SETIME 30
next instruction
requests a timer interrupt in 30 seconds. The task continues processing until the 30-second time interval elapses; then the timer island code is executed.
If you want to specify an interval smaller than a second, the instruction:
SETIME 200, ,M next instruction
requests a timer interrupt in 200 milliseconds. The task continues processing until the 200-miflisecond time interval elapses; then the timer island code is executed.
UP-8832 SPERRY UNIVAC OS/3 2—23 SUPERVISOR MACROINSTRUCTIONS
Figure 2—2 is an example of the use of the SETIME macroinstruction to request an interrupt in 25 seconds so that a time of 25 seconds can be placed on the computation that follows.
1 10 16 72
1. TIMER EXAMPLE - LIMIT COMPUTE LOOP TO 25 SECONDS 2.
3. ESTABLISH TIMER ISLAND CODE TO HANDLE INTERRUPT
4. STXIT ITJLANDCOD,ICSAVE
5. START TIMING INTERVAL
6. SETIME 25, ,S TWENTY FIVE SECONDS
7. START OF COMPUTE LOOP
8. COMPUTE EQU
9. TEST TO SEE IF TIME LIMIT HAS BEEN EXCEEDED
10. TM FLAGBYTE,TIMEFLAG TEST IF FLAG WAS SET BY ISLAND CODE
11. BO TOOLONG BRANCH IF FLAG IS SET
12. .
13. . ‘computationoccurshere
14. . ‘I
15. C X,Y TEST TO SEE IF COMPUTATION IS DONE
16. BNE COMPUTE LOOP BACK IF NOT
17. NORMAL EXIT FROM COMPUTE LOOP
18. STXIT IT DISABLES ISLAND CODE
}exit routine
19. ERROR IF COMPUTATION NOT DONE BEFORE TIME ELAPSES
20. TOOLONG EQU
21. STXIT IT DISABLES ISLAND CODE
22. PRINT ERROR MESSAGES, ETC
23. . .
24. . .er ror pr nt routine
25. .
26. TIMER ISLAND CODE — ACTIVATED WHEN TIME ELAPSES
27. ILANDCOD EQU
28. 01 FLAGBYTE,TIMEFLAG SET FLAG
29. EXIT IT
30. WORK AREAS
31. ICSAVE DS 1SF REGISTER SAVE AREA REQUIRED
32. FLAGBYTE DC X’øø’ INITIALLY ZERO
33. TIMEFLAG EQU X01’ BIT = 1 WHEN TIME ELAPSES
Fiqure 2—2. Example of SETIME Macroinstruction
Line 4 links the timer island code (lines 27 to 29) which sets a flag when the time interval expires. Line 6 requests an interrupt in 25 seconds and the compute routine (lines 8 to 1 6) is entered. Line 18 is the normal exit which occurs if computation is completed before the time elapses. Lines 20 to 25 are the error routine which is executed if the time elapses before the computation is completed.
UP-8832 SPERRY UNIVAC OS/3 2-24 SUPERVISOR MACROINSTRUCTIONS
23.2.3. Wait for Interrupt
If you use the WAIT parameter, the task suspends processing and program control is transferred to the next available task. When the time interval elapses, program control is returned to the next instruction in the task immediately following the SETIME macroinstruction. For example, the instruction:
1 10 16
SETIME 30WAIT
next instruction after interrupt
requests a timer interrupt in 30 seconds. The task is suspended until the 30-second time interval elapses, then processing continues with the next instruction. This instruction could be used following a message to the console operator or a question to a user at a remote terminal allowing a period of time (in this case, 30 seconds) to reply or to enter additional data.
2.3.2.4. Cancel a Previous Timer Interrupt Request
To cancel a previous timer interrupt request, simply use the SETIME macroinstruction without parameters. For example:
1. SETIME 300, ,M
2. next instruct ion 3.
4.
5.
6. SETIME
Line 1 requests activation of interval timer island code in 300 milliseconds. Line 6 cancels the request.