* TSXLIB -- A FORTRAN CALLABLE IMPLEMENTATION OF THE TSX-PLUS EMTS N. A. Bourgeois, Jr. Sandia National Laboratories Albuquerque, NM Like RT-11, TSX-Plus offers the MACRO pro- grammer a number of system services via programmed requests or EMTs. RT-11 makes its system services available to the FORTRAN programmer through the system subroutine library, SYSLIB. TSX-Plus also honors most RT-11 programmed requests. TSXLIB makes the TSX-Plus EMTs available to the FORTRAN programmer as a library of callable routines. The code in TSXLIB is all reentrant. INTRODUCTION The TSX-Plus library routines provide facilities to support detached jobs, file structured device mounting and dismounting, communication between running programs, program performance analysis, real time program execution, shared run time system, shared files, system status information, communication between running programs and a terminal, program control of the termi- nal, ODT activation mode, and several miscellaneous EMTs. The system status information routines require the use of TSX-Plus Version 2.2 [3]. Several of the real time support routines require TSX-Plus Version 3.0 [5]. All other routines require TSX-Plus Version 2.0 or later. TSXLIB [1] is available from the DECUS/US Chapter Program Library. The kit includes the MACRO source modules for all groups of routines, a complete user's manu- al, a cross reference chart, an indirect command file to build the library, and the implemented library. The cross reference PAGE 2 * chart lists for each routine the page number in the user's manual and the page number in the "TSX-Plus Reference Manual" [2]. The standard FORTRAN subroutine cal- ling sequence shown below may be used to access all of the routines in TSXLIB. CALL SUBRTN ( ARG1, ... ,ARGn ) Those routines that return only one value are also callable as FORTRAN func- tions. This is as follows: IRET = RTNAME ( ARG1, ... ,ARGn ) The "TSX-Plus Reference Manual" describes how the EMTs implemented in TSXLIB are accessed from a MACRO program. However, the FORTRAN/MACRO interface described in the "RT-11 Programmer's Refer- ence Manual" [4] may also be used to access the routines in the library. The TSXLIB (as well as SYSLIB) routines are also available to the "C" programmer via the DECUS "C" [6] library function, "call(...)". DETACHED JOB SUPPORT Table 1 lists the routines that pro- vide detached job support from within an executing program. ISTDJ Get the status of a detached job. KLDTJB Kill a detached job. STDTJB Start a detached job. Detached Job Support. Table 1. DEVICE MOUNTING AND DISMOUNTING It is possible to mount and dismount a file structured device for directory cach- ing from within a running program. The routines listed in Table 2 provide these capabilities. PAGE 3 * DISMNT Dismount a file structured dev- ice. MOUNT Mount a file structured device. Device Mounting and Dismounting. Table 2. INTERPROGRAM MESSAGE COMMUNICATION TSX-Plus provides an optional facility that allows running programs to communicate with each other. Table 3 lists the routines that support this interprogram message communication. MSGSND Send a message to another job. RCVMSG Try to receive a message from another job. RCVMSW Wait for a message from another job. Interprogram Message Communication. Table 3. Messages are transferred between pro- grams by using named message channels. A message channel accepts a message from a sending program, stores the message in a queue associated with the channel, and delivers the message to a receiving program on its request for a message on the chan- nel. Message channels are separate from I/O channels. Each active message channel has asso- ciated with it an ASCII character name that is used by both the sending and receiving programs to identify the channel. The names associated with the channels are defined dynamically by the running pro- grams. A message channel is active when messages are being held in the queue asso- ciated with the channel or if a program is waiting for a message from the channel. When message channels become inactive they are returned to a free pool and may then be reused. Once a message is queued on a channel, that message will remain in the queue until some program receives it. A program's exiting to the keyboard monitor does not remove any pending messages. This allows one program to leave a message for another PAGE 4 * program that will be run at a later time. PERFORMANCE ANALYSIS SUPPORT For many applications the keyboard monitor level performance analysis control provided by TSX-Plus is adequate. However, in cases such as analyzing the performance of an overlayed program it is necessary to have control over the performance analysis feature from the running program. The routines listed in Table 4 provide just this capability. INITPA Initialize for a performance analysis. ISPPA Stop a performance analysis. ISTPA Start a performance analysis. TERMPA Terminate from a performance analysis. Performance Analysis Support. Table 4. REAL TIME PROGRAM SUPPORT The real time program support provided by TSX-Plus allows multiple real time pro- grams to be run concurrently with normal time sharing operations. The basic func- tions provided by this facility are listed in Table 5. A program must have operator privilege to use any of the real time routines. The real time facilities are available to both normal jobs controlled by time sharing lines and to detached jobs. Detached jobs started by time sharing users have operator privilege only if the user starting them does. A basic facility required by many real time programs is the ability to access the I/O page which contains the peripheral dev- ice registers. A normal time sharing job does not have this access. It is instead mapped to a simulated RMON. This allows programs that directly access offsets into RMON to run correctly. PAGE 5 * CNVAPA Convert a virtual address to a physical address. IBICIO Bit clear a value into the I/O page. IBISIO Bit set a value into the I/O page. ICNINT Connect an interrupt vector to a completion routine. IPEKIO Peek at a value in the I/O page. IPOKIO Poke a value into the I/O page. IRLINT Release an interrupt vector connection. IUNLKM Unlock a job from memory. LKANMY Lock a job into any memory. LKLOMY Lock a job into low memory. MPIOPS Map the I/O page into the pro- gram space. MPRMPS Map the simulated RMON into the program space. TKCTL Take exclusive control of the system. RLCTL Relinquish exclusive control of the system. STPRLV Set the user mode processor priority level. Real Time Program Support. Table 5. A real time program can access the I/O page in one of two ways: it can map the I/O page into the program's space; or it can leave the simulated RMON mapped into the program's space and perform peek, poke, bit set, and bit clear operations into the I/O page. It is much more efficient to directly access the device registers by mapping the I/O page into the program's space than to use the routines to perform each individual access. However, this technique will not work if the program must also directly access offsets into RMON. The correct way to access offsets into RMON is with the SYSLIB routine, ISPY, which will work even if the I/O page is mapped into the program's space. The TSX-Plus real time support facili- ty allows a program to connect a real time interrupt to a completion routine. If this is done, the completion routine is executed each time the specified interrupt occurs. It is possible for several interrupt vec- tors to be connected to the same completion PAGE 6 * routine in a job but it is illegal for more than one job to connect to the same inter- rupt vector. An execution priority may be specified for each completion routine. This is not the same as the hardware selected priority of the interrupt. All completion routines are synchronized with the job and run at hardware priority level zero. The comple- tion routine priority is used to schedule the completion routines for execution. The available priority levels are zero through seven. The execution of a real time com- pletion routine for one job will be interrupted and suspended if an interrupt occurs that causes a higher priority com- pletion routine for another job to be queued for execution. However, a comple- tion routine for a given job will never be interrupted to run another completion routine for the same job even if a higher priority completion routine is pending. Completion routine priorities one through seven are real time priorities. They are higher than the priorities given to time sharing jobs and will always preempt the time sharing jobs. Completion routine priority zero is not a real time priority but rather a very high normal priority. Such zero priority completion routines are time sliced in the normal fashion. If a completion routine enters a wait state it relinquishes its real time priority. Jobs that have real time, inter- rupt driven completion routines need not be locked in memory. In time critical, real time applica- tions where a program must respond to an interrupt with minimum delay, it may be necessary for the job to lock itself in memory to avoid the time consumed in pro- gram swapping. This facility should be used with caution since if a number of large programs are locked in memory there may not be enough space left to run other programs. A running program may gain exclusive access to the system to perform some time-critical task. The program may then relinquish this exclusive access when it is not needed. PAGE 7 * SHARED RUN TIME SYSTEM SUPPORT TSX-Plus provides a facility that allows shared run time systems or data areas to be mapped into the address spaces of multiple time sharing jobs. Table 6 lists the routines that support this feature. IASRNT Associate/disassociate a shared run time system with a job. MAPRNT Map a shared run time system into a job's region. Shared Run Time System Support. Table 6. Memory space can be conserved by hav- ing several jobs access a common copy of a run time system rather than having to allo- cate space within each job. Shared run time systems are never swapped out of memo- ry. When a job is associated with a run time system, a portion of the job's virtual memory is mapped so as to allow access to the run time system. SHARED FILE SUPPORT Table 7 lists the routines that offer access to the shared file record locking facility provided by TSX-Plus. This is useful in situations where programs being run from several terminals wish to update a common file. Through the record locking facility a program may gain exclusive access to one or more blocks in a shared file by locking those blocks. Other users attempting to lock the same blocks will be denied access until the first user releases the locked blocks. ICKWTS Check for writes to a shared file. IDCLSF Declare a file to be shared. ISVST Save the status of a shared file. IUALBK Unlock all locked blocks. IUSPBK Unlock a specific block. LKBLK Try to lock a block. LKBLKW Wait for a block to lock. Shared File Support. Table 7. PAGE 8 * The recommended procedure for updating a shared file being accessed by several users is as follows: 1. Open the file. 2. Declare the file to be shared. 3. Lock all blocks which contain the desired record. 4. Read the locked blocks into memory. 5. Update the record. 6. Write the updated blocks to the file. 7. Unlock the blocks. 8. Repeat steps three through seven as required. 9. Close the file. SYSTEM STATUS INFORMATION Information typical of that returned by the SYSTAT keyboard command is made available to a running program by the routines listed in Table 8. ICONTM Determine the connect time for a job. ICPUTM Get the CPU time used by a job. IEXSTS Get a job's execution status. ILNSTS Check the status of a line. IPGNAM Get the name of the program being run by a job. IPPNUM Get the project-programmer number for a job. MEMPOS Determine the position of a job in memory. MEMUSE Determine the amount of memory used by a job. System Status Information. Table 8. TERMINAL COMMUNICATION SUPPORT The routines that allow a running pro- gram to communicate with a terminal are listed in Table 9. PAGE 9 * TRMIN Accept a string of characters from the terminal. TRMMSG Send a message to another ter- minal. TRMOUT Send a string of characters to the terminal. Terminal Communications Support. Table 9. TERMINAL CONTROL SUPPORT The several terminal control support routines are listed in Table 10. BRKCTL Establish break sentinal con- trol. HIEFOF Turn off the high efficiency terminal mode. HIEFON Turn on the high efficiency terminal mode. IACTCH Check for pending activation characters. ITRERR Check for terminal input er- rors. ITRTYP Determine the terminal type. TIMOUT Set the terminal read time out value. Terminal Control Support. Table 10. MISCELLANEOUS EMT SUPPORT Table 11 lists the routines that sup- port the several miscellaneous EMTs provided by TSX-Plus. ISPBLK Determine the number of free blocks in the spool file. ISPY Return values from within the simulated RMON (SYSLIB rou- tine). ITSLIC Determine the TSX-Plus license number. ITSLIN Determine the TSX-Plus line number. MEMSET Set the memory allocation. Miscellaneous EMT Support. Table 11. PAGE 10 * ODT ACTIVATION MODE SUPPORT ODT activation mode may be turned on and off from within a running program. Table 12 lists the routines that support this feature. In this mode TSX-Plus con- siders all characters to be activation characters except the digits, the comma, the dollar sign and the semicolon. RSRODT Reset normal activation mode. SETODT Set ODT activation mode. ODT Activation Mode Support. Table 12. REFERENCES 1. N. A. Bourgeois, Jr., "TSXLIB -- A Library Implementation of the TSX-Plus Programmed Requests", 11-490, DECUS/US Chapter Program Library, Marlboro, MA, October 1982. 2. S & H Computer Systems, Inc., "TSX-Plus Reference Manual", Nashville, TN, December 1980. 3. S & H Computer Systems, Inc., "TSX-Plus Version 2.2 System Release Notes", Nashville, TN. 4. Digital Equipment Corporation, "RT-11 Programmer's Reference Manual", AA-H378A-TC, Maynard, MA, March 1980. 5. S & H Computer Systems, Inc., "TSX-Plus Version 3.0 System Release Notes", Nashville, TN. 6. Robert B. Denny, et al, "C Language System for RT-11", 11-513, DECUS/US Chapter Program Library, Marlboro, MA, January 1982.