MJCLOK (Multi-Job CLOcK program) Version II by S.C. CRIBBS Pinawa, Manitoba Canada R0E1L0 ABSTRACT MJCLOK is a Foreground or System job utility that displays current calendar and time values, and user defined messages, on a VT100 RT-11 console terminal in a manner transparent to the Background job. This program demonstrates the feasibility of routing output to the console from Foreground or System jobs through Background job completion routines thus avoiding terminal context switching. MJCLOK has the facility to avoid conflicts with Background jobs that require full use of the video display. Version II differs from the original version in two ways: Terminal flow control commands are used to regulate communication. A single line display option has been added. MJCLOK (Multi-Job CLOcK program) MJCLOK is a PDP-11 program that maintains a current display of date, day of the week, and time of day on the RT-11 console terminal. The display device used must be a VT100 series or equivalent terminal. This program has been written in MACRO-11 for the RT-11 V4 Foreground/Background (FB) and Extended Memory (XM) monitors. It will not execute properly under the Single Job (SJ) or Base Line (BL) monitors. 1.0 PURPOSE Apart from providing the user with an incessant reminder of his/her life ticking away, MJCLOK has been designed as a vehicle to demonstrate the feasibility of multi-job use of a video display under RT-11. When programs execute concurrently, RT-11 precedes output to the shared console with a job identification text string. I'm sure this was designed by DEC as a convenience feature and is appreciated when there is infrequent output from more than just the Background job directed to the same printing terminal. However, the job identification string is only a liability to programmers attempting to create software that write to specific display screen zones on a video terminal. MJCLOK is intended to be a Foreground or System Job that can be initiated when RT-11 is bootstrapped and remain in execution until the computer is shut down. To be practical, such a job should use very little memory and central processor time, be completely memory resident, require little or no operator interaction - yet still be useful. This program solves the multi-job I/O problem and exhibits the above named features. Even the price is right! 2.0 PROGRAM DESCRIPTION The program executes a simple loop. It obtains the current time from the monitor, modifies the display fields on the screen that must be changed and uses the .TWAIT programmed request to have the monitor put it to sleep for a time interval (eg. one second). When it re-awakens the cycle repeats. MJCLOK is composed of five main routines: screen initialization, date-day-time display, keyboard command processor and a Background job watch routine. The last two are optional features that may be omitted to minimize program size. Page 2 2.1 Screen Initialization Routine This subroutine requests the terminal to allocate the non-scrolling display area to be used, erases it, and defines the display area characteristics. A program assembly time option allows for the selection of either double height - double width characters or simply double width only characters in the top line of the display area. If the optional message display facility (see section 2.4) has been requested, the line immediately below the date - time fields will be cleared. The remaining screen lines are not affected and are defined as the terminal's scrolling region. Screen initialization is performed once as the program is started and whenever called by the keyboard command processor and Background job watch routines. 2.2 Date-Day-Time Display Routine The time of day field is updated each time the program awakens. The date field is written to the terminal whenever the screen is initialized and upon time of day rollover. Each time the date field is written, the current day of the week is also calculated and written to the screen. These three fields are displayed in VT100 oversized characters. For double height - double width fields, the same text must be sent to both lines one and two of the screen. The user is given the option of having the date field formatted in year/month/day numbers or day-month-year alphanumerics. 2.3 Keyboard Command Processor After each pass through the display routines MJCLOK checks the terminal input buffer for a command from the user. Two single character commands are recognized. Future display field updates are suspended when an "S" is received. MJCLOK then becomes almost dormant. It simply looks for a new command each time it awakes and then goes back to sleep if one has not been received. This feature allows the RT-11 console to be temporarily shifted to a hardcopy terminal or another program to have full control of the VT100 display screen. Anytime the user types an "R", the screen is re-initialized, the display fields are repainted and normal field updating resumes. Page 3 2.4 Message Display Routine This is an optional feature selected before program assembly. It's purpose is to allow the user to request that various single line text strings be displayed at predefined times of day for specified time intervals. Additionally, message requests can be made for only on a specific day of the week, only for weekdays (Monday-Friday), only on weekends, and for every day of the week. The user created messages will be displayed on the line immediately below the date - time fields. 2.5 Job Watch Routine The Background job watch routine is another optional feature that must be selected before the program is assembled. It's purpose is to inhibit MJCLOK from interfering with the output written to the display by Background jobs that utilize the VT100's programmable features. An example of such a program is the KED editor which assumes that it has exclusive ownership of the video screen. 3.0 OUTPUT METHOD To defeat the job identification features of the RT-11 console terminal handler, MJCLOK passes all of it's output text through the Background job for display. All print requests execute as completion routines for the Background job. Thus, there is a clean RT-11 solution to an RT-11 problem. The output from the higher priority job gets preference over text written by the Background job, the output requests from MJCLOK are transparent to the Background job and terminal direct cursor addressing by multiple jobs is made practical. Unfortunately there is no programmed request or SYSLIB routine that directly allows a job to queue such a completion routine. The solution, demonstrated by subroutine DSPLAY in program MJCLOK, is to simulate an interrupt and then use the .SYNCH request to queue the printing of the text string. The switch of context to the Background job is made by the monitor when the job number argument for .SYNCH is defined as zero. There is always a Background job in RT-11, even if it's only the Keyboard monitor, so the request will never fail because it has been queued for a non-existent job. Output performed by a completion routine does not interfere with normal output of a Background job so it is possible to execute virtually any Background job while MJCLOK is running. Page 4 The use of this technique is quite straight forward as long as the following considerations are observed. First, the job queueing the request must make sure the last request completes before an attempt is made to re-use the same workspace. This restriction is common to all usage of the .SYNCH programmed request. The user must test the word at offset octal 14 of the .SYNCH workspace to be sure it is zero before re-using it. Second, each call to .SYNCH results in the new request being put at the head of the Background job completion routine queue. This can be a problem if the order of execution of the output requests is important. An example of this is the screen initialization routine, INISCN in MJCLOK, which executes a .TWAIT request after it has issued it's commands to the terminal. This insures that the terminal is in the proper state before the time and date text fields are output. The RT-11 console terminal handler has been designed to throw away characters that are to be echoed if the job's output buffer is full. If this happened, the user would notice that the occasional character typed as input at the keyboard was not echoed on the display. This is, to say the least, undesirable and shows that the output method is somewhat baud rate dependent. One solution is to limit the amount of text output by the high priority job. A most significant enhancement in version II, is to insert ASCII flow control characters into the output stream. Every text string issued by MJCLOK is preceded by XOFF and terminates with XON . User typed characters are temporarily stored in the terminal's own input buffer while MJCLOK updates the display. In conjunction with the above, the higher priority job should not send text to the Background job's output buffer until there is room for it. Unfortunately, RT-11 V4 does not provide easy access to the character count values associated with ring buffers in non-multiterminal configurations. 4.0 GENERATING MJCLOK A demonstration version of the program (MJCLOK.REL) has been provided, but the source code (MJCLOK.MAC) has been included for people who wish to take advantage of the optional features. An option is selected by defining the associated symbol at the beginning of the source file. This is accomplished by simply deleting the semi-colon that proceeds the symbol name. Page 5 Users of PDP-11 computers equipped with the extended instruction set will wish to define symbol EIS. This will invoke hardware multiplication and division instructions which will speed execution and slightly reduce program size. Non-Hardware dependent (NHD) code is generated as a default condition. Defining symbol YMD results in the date field being displayed as year, month and day two digit numbers seperated by slash characters. Thus the sub fields are displayed in order of decreasing significance, a standard now adopted for international acceptance. The American traditional date format is used if this symbol is not defined, but costs an aditional 52 words in program size. Two more conditional assembly options are available. They are the message display feature (symbol MSGDSP) and the Background job watch function (symbol JBWTCH). These options require more user involvement than the previous two in that code at the end of the source file may have to be modified. I will describe the message display option first. If the option has been selected, MJCLOK looks at the current element of an event table each time it awakens. The event code is tested against the current day of the week. If the test is passed, a check is made to determine if the present time of day falls within the time interval specified for the message. In that case, the message is written to the display. Failure to pass the event code test or on finding the present time to be later than the specified interval causes MJCLOK to advance the event table pointer. The structure of the event table and message strings are most easily understood by looking at the examples found at the end of the MJCLOK source file (begins at symbol EVNTBL:). The event table consists of a number of six word table elements. The table must be terminated by a zero word. The first word of each table entry defines the day of week conditions that the message should be displayed. A code of -3 specifies only on weekends, -2 every day of the week, -1 means only on weekdays and the positive numbers ranging from 1 to 7 select the appropriate day of the week (Sunday=day#1). Table element words 2 and 3 specify, in RT-11 internal time format, the time of day that the message display should be initiated. Words 4 and 5 specify the time that the message should be erased. Finally, word 6 is the address of the text string to be displayed. The number of elements in the table is restricted only by the number of clock ticks in a 24 hour period, the amount of memory one wants to allocate to MJCLOK and by the user's imagination. The event table must be terminated with a word containing a zero value. One word of caution, the elements of the event table should be sorted in order of advancing time of day. Page 6 User defined messages should have the same structure as the examples provided in the program. First, issue XOFF and the terminal's save cursor position command. The text should be routed one line above the scrolling region (symbol BGNSCL defines the first line of the scrolling region). The cursor position must be restored at the end of the message and the character XON inserted before the octal 200 byte string terminator. I've written MJCLOK assuming that the terminal will normally be used in 80 character per line format, although 132 character messages are feasible with the VT100 display. In the examples given, the text string is displayed in reverse video, centered on the line and two bell tones are output as the message is written. Remember any VT100 character attribute turned on within the message must also be turned off again within the same text string. Defining symbol JBWTCH selects the Background job watch function. This routine is the first code executed each time MJCLOK re-awakens. The filename of the current Background job is tested against each of the filenames stored in the MJCLOK job table. The table begins at symbol JOBTBL:. When a match is made MJCLOK goes back to sleep without updating the time display, and will execute only the job watch routine until the match fails. The first complete scan through the job table that does not result in a match causes the program to re-initialize the screen and resume normal output. Elements of the job table are three words in length and must be stored in RAD50 format. The first two words represent the job name, the last one is the job type. There is no defined limit to the number of data elements in the table, but it must terminate with a zero word. 5.0 USING MJCLOK Since the demonstration version (MJCLOK.REL) has been built to use NHD code it should execute properly on any RT-11 FB or XM system equipped with a VT100 terminal. Note that for the program to be useful, the line time clock (LTC) on the processor must be enabled. This program will execute as a Foreground or System job. In fact if it is relinked as a "SAV" file, it will run as a Background job. To start it type: .FRUN MJCLOK or .SRUN MJCLOK.REL Page 7 Please remember that you must turn off the automatic carriage return - line feed feature of the RT-11 console terminal handler. You accomplish this by entering the command: .SET TT: NOCRLF before executing MJCLOK. Failure to do so will result in the terminal appearing to occasionally misplace one of the display fields. Display field updating can be suspended with the "S" command and the display refreshed through use of the "R" command. Remember you must change job input context by preceding commands to MJCLOK with CONTROL_F or CONTROL_X. To return to addressing your input to the Background job type CONTROL_B. The RT-11 command SUSPEND will perform the same function as the "S" command when MJCLOK is executing as a Foreground job but RESUME, ofcourse, only continues rather than repaints the screen. If you have modified the source file, for example to change a display message or to add a new file specification to the job table, the program will have to be regenerated. Use the following RT-11 commands to do so. .MACRO MJCLOK.MAC .LINK/FOREGROUND MJCLOK The newly generated program can then be executed as described above. 6.0 ACKNOWLEDGEMENTS I would like to thank Peter Dodd of Saint Mary's University in Nova Scotia for suggesting the inclusion of terminal flow control commands and the option of single line double width character displays. The former makes MJCLOK much more useful to users with the slower LSI-11 & LSI-11/2 processors, the latter leaves an additional free line to the terminal's scrolling region.