TSXLIB A Library Implementation of Programmed Requests for TSX-Plus V6.40a DECUS #11-490 N. A. Bourgeois, Jr. NAB Software Services, Inc. PO Box 20009 Albuquerque, NM 87154 Abstract A library of FORTRAN callable routines that implement the EMTs provided by TSX-Plus is described. Complete descriptions, calling sequences, examples of use, and library building procedures are given. [89e18a] TSXLIB V6.40a PAGE 2 The information in this document is subject to change without notice and should not be construed as a commitment by NAB Software Services, Inc. NAB Software Services, Inc. assumes no responsibility for any errors that may appear in this document. This document was originally issued by Sandia National Laboratories, operated for the United States Department of Energy by Sandia Corporation. Notice This document was originally sponsored by the United States Government. Neither the United States Government nor the United States Department of Energy, nor any of their employees, nor any of their contractors, subcontractors, or their employees makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness or usefulness of any information, apparatus, product or process disclosed, or represents that its use would not infringe privately owned rights. This work was originally funded by: Headquarters, ESD / OCB / Stop 36 Hanscom Air Force Base, MA 01731 TSXLIB V6.40a PAGE 3 The Reader's Comment form on the last page of this document requests the user's critical evaluation to assist NAB Software Services, Inc. in preparing future documentation. Acknowledgment The author wishes to thank S & H Computer Systems, Inc. for its permission to reprint parts of their "TSX-Plus Reference Manual" in this document. *********** * CAUTION * *********** Much of both the MACRO-11 source codes and the FORTRAN examples described in this document are as yet untried. TSXLIB V6.40a PAGE 4 Table of Contents Table of Contents 1. Introduction . . . . . . . . . . . . . 8 2. General Description . . . . . . . . . 9 Communication Line Support . . . . . . 10 Detached Job Support . . . . . . . . . 10 Device Allocating and Deallocating . . 10 Device Mounting and Dismounting . . . 11 Interprogram Message Communication . . 11 Job Privileges Control . . . . . . . . 12 Job Status Monitoring . . . . . . . . 12 Miscellaneous EMT Support . . . . . . 12 ODT Activation Mode Support . . . . . 13 Performance Analysis Support . . . . . 13 Real Time Program Support . . . . . . 13 Shared Run Time System Support . . . . 16 Shared File Support . . . . . . . . . 17 Special File Information . . . . . . . 18 Spooler Support . . . . . . . . . . . 18 Subprocess Control . . . . . . . . . . 19 System Status Information . . . . . . 19 Terminal Communication Support . . . . 20 Terminal Control Support . . . . . . . 20 User Name Support . . . . . . . . . . 20 Windowing Support . . . . . . . . . . 21 3. Routine Descriptions . . . . . . . . . 22 BRKCTL . . . . . . . . . . . . . . . . 22 CHPGN . . . . . . . . . . . . . . . . 23 CLRGNS . . . . . . . . . . . . . . . . 24 CNVAPA . . . . . . . . . . . . . . . . 24 DISMNT . . . . . . . . . . . . . . . . 24 DSMNTA . . . . . . . . . . . . . . . . 25 GETREG . . . . . . . . . . . . . . . . 25 GTJBNM . . . . . . . . . . . . . . . . 26 GTPGN . . . . . . . . . . . . . . . . 26 GTUNAM . . . . . . . . . . . . . . . . 27 HIEFOF . . . . . . . . . . . . . . . . 27 HIEFON . . . . . . . . . . . . . . . . 27 IACTCH . . . . . . . . . . . . . . . . 28 IALOC . . . . . . . . . . . . . . . . 28 IAQFLC . . . . . . . . . . . . . . . . 29 IASRNT . . . . . . . . . . . . . . . . 30 IBICIO . . . . . . . . . . . . . . . . 31 IBISIO . . . . . . . . . . . . . . . . 32 IBSTCH . . . . . . . . . . . . . . . . 32 TSXLIB V6.40a PAGE 5 Table of Contents ICALOC . . . . . . . . . . . . . . . . 33 ICKWTS . . . . . . . . . . . . . . . . 33 ICLRST . . . . . . . . . . . . . . . . 34 ICLXF . . . . . . . . . . . . . . . . 35 ICNINT . . . . . . . . . . . . . . . . 36 ICNMCN . . . . . . . . . . . . . . . . 37 ICNRTN . . . . . . . . . . . . . . . . 37 ICNTSP . . . . . . . . . . . . . . . . 38 ICONTM . . . . . . . . . . . . . . . . 39 ICPUTM . . . . . . . . . . . . . . . . 40 ICRWND . . . . . . . . . . . . . . . . 40 IDALOC . . . . . . . . . . . . . . . . 42 IDCLSF . . . . . . . . . . . . . . . . 43 IDFRGN . . . . . . . . . . . . . . . . 44 IDLWND . . . . . . . . . . . . . . . . 45 IDMALD . . . . . . . . . . . . . . . . 46 IDMLD . . . . . . . . . . . . . . . . 46 IESMCN . . . . . . . . . . . . . . . . 47 IEXSTS . . . . . . . . . . . . . . . . 48 IFLINF . . . . . . . . . . . . . . . . 49 IGNPIC . . . . . . . . . . . . . . . . 50 ILDTR . . . . . . . . . . . . . . . . 50 ILNSTS . . . . . . . . . . . . . . . . 51 INITPA . . . . . . . . . . . . . . . . 52 INITSP . . . . . . . . . . . . . . . . 52 IPEKIO . . . . . . . . . . . . . . . . 53 IPGNAM . . . . . . . . . . . . . . . . 54 IPOKIO . . . . . . . . . . . . . . . . 54 IPPNUM . . . . . . . . . . . . . . . . 55 IPRIV . . . . . . . . . . . . . . . . 56 IPRPAN . . . . . . . . . . . . . . . . 58 IPRWND . . . . . . . . . . . . . . . . 59 IRDRCL . . . . . . . . . . . . . . . . 59 IRDTR . . . . . . . . . . . . . . . . 60 IRLINT . . . . . . . . . . . . . . . . 61 IRSWND . . . . . . . . . . . . . . . . 61 IRXOFF . . . . . . . . . . . . . . . . 61 ISLWND . . . . . . . . . . . . . . . . 62 ISPBLK . . . . . . . . . . . . . . . . 63 ISPCTL . . . . . . . . . . . . . . . . 63 ISPFLC . . . . . . . . . . . . . . . . 64 ISPFLP . . . . . . . . . . . . . . . . 64 ISPLN . . . . . . . . . . . . . . . . 65 ISPPA . . . . . . . . . . . . . . . . 66 ISPUSE . . . . . . . . . . . . . . . . 66 ISPWND . . . . . . . . . . . . . . . . 66 ISPY . . . . . . . . . . . . . . . . . 67 ISTDJ . . . . . . . . . . . . . . . . 68 ISTFTM . . . . . . . . . . . . . . . . 68 ISTLD . . . . . . . . . . . . . . . . 69 ISTPA . . . . . . . . . . . . . . . . 70 ISTPRV . . . . . . . . . . . . . . . . 70 ISVST . . . . . . . . . . . . . . . . 70 ISWESP . . . . . . . . . . . . . . . . 71 ITCRTN . . . . . . . . . . . . . . . . 72 TSXLIB V6.40a PAGE 6 Table of Contents ITRAP . . . . . . . . . . . . . . . . 72 ITRCTL . . . . . . . . . . . . . . . . 73 ITRERR . . . . . . . . . . . . . . . . 73 ITRTYP . . . . . . . . . . . . . . . . 74 ITRYEL . . . . . . . . . . . . . . . . 74 ITRYMS . . . . . . . . . . . . . . . . 75 ITRYSP . . . . . . . . . . . . . . . . 76 ITSLIC . . . . . . . . . . . . . . . . 77 ITSLIN . . . . . . . . . . . . . . . . 77 ITSNAM . . . . . . . . . . . . . . . . 77 IUALBK . . . . . . . . . . . . . . . . 78 IUNLKM . . . . . . . . . . . . . . . . 79 IUSPBK . . . . . . . . . . . . . . . . 79 IYELL . . . . . . . . . . . . . . . . 80 JOBPRI . . . . . . . . . . . . . . . . 81 KILJOB . . . . . . . . . . . . . . . . 81 KLDTJB . . . . . . . . . . . . . . . . 82 LKANMY . . . . . . . . . . . . . . . . 82 LKBLK . . . . . . . . . . . . . . . . 83 LKBLKW . . . . . . . . . . . . . . . . 84 LKLOMY . . . . . . . . . . . . . . . . 85 MAPRNT . . . . . . . . . . . . . . . . 85 MEMPOS . . . . . . . . . . . . . . . . 87 MEMSET . . . . . . . . . . . . . . . . 88 MEMUSE . . . . . . . . . . . . . . . . 88 MNTLD . . . . . . . . . . . . . . . . 89 MOUNT . . . . . . . . . . . . . . . . 90 MPIOPS . . . . . . . . . . . . . . . . 90 MPRGN . . . . . . . . . . . . . . . . 91 MPRMPS . . . . . . . . . . . . . . . . 92 MSGREQ . . . . . . . . . . . . . . . . 92 MSGSND . . . . . . . . . . . . . . . . 93 NONINT . . . . . . . . . . . . . . . . 94 RCVMSG . . . . . . . . . . . . . . . . 95 RCVMSW . . . . . . . . . . . . . . . . 96 RLCTL . . . . . . . . . . . . . . . . 97 RSTODT . . . . . . . . . . . . . . . . 97 SETODT . . . . . . . . . . . . . . . . 97 STDTJB . . . . . . . . . . . . . . . . 97 STPRLV . . . . . . . . . . . . . . . . 98 STUNAM . . . . . . . . . . . . . . . . 98 TERMPA . . . . . . . . . . . . . . . . 99 TIMOUT . . . . . . . . . . . . . . . 100 TKCTL . . . . . . . . . . . . . . . 101 TRMIN . . . . . . . . . . . . . . . 101 TRMMSG . . . . . . . . . . . . . . . 102 TRMOUT . . . . . . . . . . . . . . . 103 TTCRTN . . . . . . . . . . . . . . . 103 4. Building the Library . . . . . . . . 105 References . . . . . . . . . . . . . . . 107 TSXLIB V6.40a PAGE 7 Table of Contents Appendix A: KWIK Index . . . . . . . . 108 Appendix B: Distribution Kit . . . . . 118 Appendix C: Test Record . . . . . . . . 119 TSXLIB V6.40a PAGE 8 Introduction 1. Introduction When application programs are executed under a time sharing executive such as TSX-Plus [1,2,8,9] certain capabilities become desirable if not absolutely essential. These capabilities relate to requirements for such things as hardware dependent I/O, shared files, interprogram communication, and others. TSX-Plus provides a number of programmed requests or EMTs for these purposes. This document describes a number of FORTRAN [6,7] callable routines and their calling sequences that implement these EMTs. All of the routines are callable as FORTRAN subroutines and some are also callable as FORTRAN functions. The routines are written in MACRO-11 [3]. The next chapter offers a general description of the several groups of routines. It describes the process for linking the routines to the FORTRAN application program. The general calling sequences are also described. The third chapter gives a detailed description of each of the individual routines. The descriptions include both the calling sequences and, in most cases, FORTRAN examples. Procedures for constructing the library from the several source modules are given in the fourth chapter. Appendix A contains a key-word-in-context (KWIK) index of the routines. A description of the distribution kit is contained in Appendix B. Appendix C contains the current test status of the TSXLIB routines. NOTE TSX-Plus is a registered trademark of S & H Computer Systems Inc., Nashville, TN. TSXLIB V6.40a PAGE 9 General Description 2. General Description These TSX-Plus library routines provide facilities to support communication lines, detached jobs, device allocating and deallocating, file structured device mounting and dismounting, communication between running programs, job privileges control, job status monitoring, ODT activation mode, program performance analysis, real time program execution, shared run time systems, shared files, special files information, spooler control, subprocess control, system status information, communication between running programs and a terminal, program control of the terminal, user name control, windowing, and several miscellaneous EMTs. The standard FORTRAN [6,7] subroutine calling sequence shown below may be used to access all of the routines in the TSX-Plus library. CALL RTNAM ( ARG1,...,ARGn ) Those routines that return only one value are also callable as FORTRAN functions. This is as follows: IRET = RTNAM ( ARG1,...,ARGn ) The application program is first compiled as follows: .RUN SY:FORTRAN *MYPROG=MYPROG *^C Then the routines are linked with the application program as shown below: .RUN SY:LINK *MYPROG=MYPROG,SY:TSXLIB/F *^C or .RUN SY:LINK *MYPROG=MYPROG,SY:TSXLIB,FPULIB *^C The application program is now ready for execution. .RUN DK:MYPROG The "TSX-Plus Programmer's Reference Manual" [1] describes how the EMTs implemented in this TSX-Plus library are accessed from a MACRO-11 program. However, the FORTRAN/MACRO interface described in the "RT-11 Programmer's Reference Manual" [5] may TSXLIB V6.40a PAGE 10 General Description also be used to access the routines in the library from a MACRO-11 program. In the sections that follow, the name of the MACRO-11 source file containing the listed routines is given in the title of each of the tables. Communication Line Support Table 2-1 lists the TSXLIB routines that offer certain communication line support from within a running program. ICNTSP Control the speed of a communication or timesharing line. ILDTR Lower a communication or timesharing line's DTR status. IRDRCL Redirect a communication or timesharing line. IRDTR Raise a communication or timesharing line's DTR status. IRXOFF Reset a communication or timesharing line's XOFF status. Communication line support. CLLINE.MAC Table 2-1. Detached Job Support Table 2-2 lists the routines that provide detached job support from within an executing program. ISTDJ Get the status of a detached job. KILJOB Kill any job. KLDTJB Kill a detached job. STDTJB Start a detached job. Detached job support. DETJBS.MAC Table 2-2. Device Allocating and Deallocating System services are available to allow a running program to control the allocation of a device for exclusive use. Table 2-3 lists these routines. Once a device has been allocated to a job, no other job is allowed to access the device. A device allocated to a primary line or associated virtual line may be accessed by any of the associated lines. TSXLIB V6.40a PAGE 11 General Description IALOC Allocate a device. ICALOC Check the allocation status of a device. IDALOC Deallocate a device. Device allocating and deallocating. DVALOC.MAC Table 2-3. Device Mounting and Dismounting It is possible to mount and dismount both logical and physical file structured devices for directory caching from within a running program. The routines listed in Table 2-4 provide these capabilities. DISMNT Dismount a file structured device. DSMNTA Dismount all file structured devices. IDMALD Dismount all logical devices. IDMLD Dismount a specific logical device. ISTLD Check the status of a logical device. MNTLD Mount a logical device. MOUNT Mount a file structured device. Device mounting and dismounting. MNTDEV.MAC Table 2-4. Interprogram Message Communication TSX-Plus provides an optional facility that allows running programs to communicate with each other. Table 2-5 lists the routines that support this interprogram message communication. MSGREQ Post a read request for a message. 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. MSGCOM.MAC Table 2-5. Messages are transferred between programs 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 channel. Message channels are separate from I/O channels. Each active message channel has associated 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 programs. A TSXLIB V6.40a PAGE 12 General Description message channel is active when messages are being held in the queue associated 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 program that will be run at a later time. Job Privileges Control Table 2-6 lists the routines that permit an executing program to determine and make certain changes in its own executing environment. IPRIV Determine or change the job privilege sets. ISTPRV Set the current job's priority value. NONINT Set the [non]interactive job status. Job Privileges Control JBPRIV.MAC Table 2-6. Job Status Monitoring A facility is available for one job to monitor the status of one or more other jobs. Once a job has declared to monitor another job, a completion routine is executed in the monitoring job whenever a change of status occurs in the job being monitored. The services provided for job monitoring are listed in Table 2-7. IBSTCH Broadcast a job status change. ICNMCN Cancell a job status monitoring connection. IESMCN Establish a job status monitoring connection. Job status monitoring. JBSTMN.MAC Table 2-7. Miscellaneous EMT Support Table 2-8 lists the routines that support the several miscellaneous EMTs provided by TSX-Plus. TSXLIB V6.40a PAGE 13 General Description GETREG Get the word and byte values stored in a processor register. ISPLN Get a subprocess line number. ISPY Return values from within the simulated RMON (SYSLIB routine). ITSLIC Determine the TSX-Plus license number. ITSLIN Determine the TSX-Plus line number. ITSNAM determine the TSX-Plus licensee name. MEMSET Set the memory allocation. Miscellaneous EMT support. (TSLBID,TSXMSC).MAC Table 2-8. ODT Activation Mode Support ODT activation mode may be turned on and off from within a running program. Table 2-9 lists the routines that support this feature. In this mode TSX-Plus considers all characters to be activation characters except the digits, the comma, the dollar sign and the semicolon. RSTODT Reset normal activation mode. SETODT Set ODT activation mode. ODT activation mode support. TSXODT.MAC Table 2-9. Performance Analysis Support For many applications the keyboard monitor level performance analysis control provided by TSX-Plus is adequate. Specifically, 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 2-10 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. PRFANL.MAC Table 2-10. Real Time Program Support The real time program support provided by TSX-Plus allows multiple real time programs to be run concurrently with normal time sharing operations. The basic functions provided by this TSXLIB V6.40a PAGE 14 General Description facility are listed in Table 2-11. CNVAPA Convert a virtual address to a physical address. IBICIO Bit clear a value in the I/O page. IBISIO Bit set a value in the I/O page. ICNINT Connect an interrupt vector to a completion routine. ICNRTN Connect a service routine to an interrupt vector. 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. ITCRTN Trigger a completion routine from an interrupt service routine. 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 program space. MPRGN Map a region of virtual memory to a specified region of physical memory. MPRMPS Map the simulated RMON into the program space. RLCTL Relinquish exclusive control of the system. STPRLV Set the user mode processor priority level. TKCTL Take exclusive control of the system. Real time program support. RELTIM.MAC Table 2-11. A program must have one or more of the several real time related privileges to use 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 a time sharing user have the same privileges as does the user starting them. A basic facility required by many real time programs is the ability to access the I/O page which contains the peripheral device 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. 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. TSXLIB V6.40a PAGE 15 General Description The TSX-Plus real time support facility provides two methods to connect real time interrupts to TSX-Plus jobs. The first of these methods uses the mechanism of completion routines to perform the connection. The second method provides a more direct connection between interrupts and service routines in TSX-Plus jobs. Once a connection is established the routine, completion or service, is executed each time the specified interrupt occurs. It is possible for several interrupt vectors to be connected to the same completion routine in a job but it is illegal for more than one job to connect to the same interrupt vector. With the first method an interrupt causes a completion routine to be queued for the job that was connected to the interrupt vector. This method is very general and allows the completion routine to call for system services (execute EMTs). Also the job does not have to be locked in memory. On entry to the completion routine, R0 contains the address of the vector that caused the completion routine to be entered. The second method sets up conditions for the job being called and enters the interrupt service routine. This approach minimizes the overhead in entering the service routine. Hence, the service routine method can process interrupts at a greater rate than can be processed using the completion routine method. There are restrictions imposed on a program using the service routine method. Specifically, the following conditions must be met to directly connect to an interrupt: 1. The job must be locked in memory before connecting it to the interrupt vector and must remain locked in memory as long as the interrupt connection is in effect. 2. The processing done by the service routine should not be very lengthy since other interrupts may be queued up during execution of the service routine. 3. Only two system services may be legally called from within the service routine. They are the SYSLIB routine, RESUME, and the TSXLIB routine, ITCRTN. The interrupt service routine runs in user mode and uses memory mapping that has been established for the job before the interrupt occurs. Access to the I/O page via the MPIOPS routine is possible provided this mapping has been set up in the mainline code before the interrupt occurs. If an interrupt service routine needs to perform a system service other than the RESUME call listed above, it should trigger a completion routine via a call to ITCRTN and have the completion routine call for the required system service(s). An execution priority may be specified for each completion routine. This is not the same as the hardware selected priority TSXLIB V6.40a PAGE 16 General Description of the interrupt. All completion routines are synchronized with the job and run at hardware priority level zero. The completion routine priority is used to schedule completion routines for execution. The available priority levels are 0 through 127. The execution of a real time completion routine for one job will be interrupted and suspended if an interrupt occurs that causes a higher priority completion routine for another job to be queued for execution. However, a completion 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 and larger 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, interrupt driven completion routines need not be locked in memory. In time critical, real time applications 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 program 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. A running program may also set the user mode priority level and map a region of virtual memory to a specified region of physical memory. 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 2-12 lists the routines that support this feature. Memory space can be conserved by having several jobs access a common copy of a run time system rather than having to allocate space within each job. Shared run time systems are never swapped out of memory. 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. TSXLIB V6.40a PAGE 17 General Description CLRGNS Clear region definitions for fast map. IASRNT Associate/disassociate a shared run time system with a job. IDFRGN Define a region for fast map. ITRAP Perforn a fast region map. MAPRNT Map a shared run time system into a job's region. Shared run time system support. RUNTIM.MAC Table 2-12. The following sequence of operations must be performed to define and fast map regions: 1. Associate a shared runtime system with the job by use of the IASRNT routine. This does not cause any portion of the runtime system to be mapped into the job's address space but simply specifies which runtime system is being referenced by subsequent routines. 2. Use the IDFRGN routine to define the regions of the shared runtime system. This simply defines the characteristics of the regions, it does not cause them to be mapped into the job's address space. Define regions in different shared runtime systems by associating a different system prior to the use of the IDFRGN routine. 3. When ready to map a region into the job's address space, use the ITRAP routine with the index number of the desired region as the argument. The ITRAP routine uses the TRAP instruction. Hence, the TRAP instruction may not be used for other purposes while shared runtime regions are defined. Shared File Support Table 2-13 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. TSXLIB V6.40a PAGE 18 General Description 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. SHRFIL.MAC Table 2-13. 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. Special File Information TSX-Plus allows a running program to obtain certain status information about a file and to set the creation time of a file. Table 2-14 lists the routines that support this facility. IFLINF Obtain some information about a file. ISTFTM Set the creation time of a file. Special file information. TSFILS.MAC Table 2-14. Spooler Support Table 2-15 lists the routines that provide spooler support available to an executing program. TSXLIB V6.40a PAGE 19 General Description ISPBLK Determine the number of free blocks in the spool file. ISPCTL Control the release time of a spooled file. ISPFLC Control the centering of a flag page. ISPFLP Control the presence of a flag page. ISPUSE Determine the number of blocks used in the spool file. Spooler Support. SPOLER.MAC Table 2-15. Subprocess Control The routines listed in Table 2-16 allow a running program to switch terminal control between subprocesses as if a CTRL-W-digit sequence had been typed. The routines initiate new subprocesses and/or switch terminal control between subprocesses. INITSP Initialize a new or switch to an existing subprocess. ISWESP Switch to an existing subprocess. ITRYSP Try to initialize a new subprocess. Subprocess Control SUBPRO.MAC Table 2-16. 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 2-17. GTJBNM Get the name for a job. 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. IPRPAN Determine a job's primary and parent process numbers. JOBPRI Get the priority 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. SYSTAT.MAC Table 2-17. TSXLIB V6.40a PAGE 20 General Description Terminal Communications Support The routines that allow a running program to communicate with a terminal are listed in Table 2-18. ITRYEL Try to override the TT-GAG option. ITRYMS Try to send a message to another terminal. IYELL Override the TT-GAG option. TRMIN Accept a string of characters from the terminal. TRMMSG Send a message to another terminal. TRMOUT Send a string of characters to the terminal. Terminal communications support. TRMCOM.MAC Table 2-18. Terminal Control Support The terminal control support routines are listed in Table 2-19. BRKCTL Establish break sentinel control. HIEFOF Turn off the high efficiency terminal mode. HIEFON Turn on the high efficiency terminal mode. IACTCH Check for pending activation characters. IGNPIC Get number of pending input characters. ITRCTL Perform lead-in character type terminal control functions. ITRERR Check for terminal input errors. ITRTYP Determine the terminal type. TIMOUT Set the terminal read time out value. TTCRTN Establish a terminal completion routine. Terminal control support. TRMCTL.MAC Table 2-19. User Name Support An executing program may set and change the user name for the connected job. The routines for this facility are listed in Table 2-20. CHPGN Change the program name. GTPGN Get the program name. GTUNAM Get the user name associated with the current job. STUNAM Set the user name associated with the current job. User name support. USRNAM.MAC Table 2-20. TSXLIB V6.40a PAGE 21 General Description Windowing Support TSX-Plus offers a full screen process windowing system that allows the system to remember the contents and status of the terminal display. A running program may redisplay windows on demand. The routines for this facility are listed in Table 2-21. When windowing is used, the system monitors all characters sent to the terminal and maintains an updated screen image display in memory. Terminal attributes such as line width, reverse/norman video, application keypad mode, and etc. are saved along with line attribures (double wide, double high) and character attributes. The attributes retained for each character consist of blinking, bold, underlined, reverse video, and character set information (ASCII, UK, DEC supplemental, or graphics). The most common use of windows is to completely refresh the display when switching among subprocesses to avoid the confusion of mixed displays. For some program applications, it may be useful to utilize multiple windows from the same job. ICRWND Create a window. IDLWND Delete a window. IPRWND Print the contents of a window. IRSWND Resume window processing. ISLWND Select a window. ISPWND Suspend window processing. Windowing Support WINDOW.MAC Table 2-21. TSXLIB V6.40a PAGE 22 Routine Descriptions 3. Routine Descriptions This chapter presents all of the TSX-Plus routines in alphabetical order and provides a detailed description of each one. The FORTRAN calling sequence and where appropriate an example of each call in a FORTRAN program is given. The user should be thoroughly familiar with the general description of this TSX-Plus library given in the previous section of this document. Additional information is available in the "TSX-Plus Programmer's Reference Manual" [1] and the "RT-11 Programmer's Reference Manual" [5]. Some of these TSXLIB routines require calls to various SYSLIB routines. CAUTION An "Invalid EMT" error message may result when attempting to execute any of the following routines with a prior version of TSX-Plus. This occurs when the underlying EMT is not implemented in the version of TSX-Plus being used. In the following descriptions, arguments enclosed in square brackets, [], are optional. BRKCTL This routine is used to declare a completion routine that will be triggered when the BREAK key or a declared key on the terminal is pressed. The calling sequence is: CALL BRKCTL ( IBRKCH,CPLRTN ) where: IBRKCH is the value of the character that is to be used for the break control. CPLRTN is the name of the completion routine to be executed when the break character is pressed. The specified completion routine will be entered when either the BREAK key or the declared key is pressed. If no declared key is wanted, specify a value of zero for IBRKCH. On some systems the console terminal BREAK key causes entry into console ODT and for this reason requires a declared key value. Only one break routine may be specified at a time for each TSXLIB V6.40a PAGE 23 Routine Descriptions user. If a break routine was previously specified, it is cancelled when a new break routine is declared. If a value of zero is specified for the name of the completion routine, CPLRTN, any previously specified break routine is cancelled. The following example first declares the completion routine as an external, then establishes break sentinel control using the letter H, and later cancels the control. EXTERNAL CPLRTN IBRKCH = 72 . . CALL BRKCTL ( IBRKCH,CPLRTN ) . . CALL BRKCTL ( 0,0 ) . . CHPGN This routine is used to change the reported name of the program executiong on the current line. The calling sequences are as follows: CALL CHPGN ( PRGNAM [ ,IERR ] ) or IERR = CHPGN ( PRGNAM ) where: PRGNAM is the name of the two word buffer that contains the new program name in RAD50 format. IERR is negative or the following: 2 the new program name was not specified in RAD50. This routine changes the program name reported by the SHOW JOBS, SYSTAT and WHO commands, and by the IPGNAM routine, not the directory name of the executable program. The following example aborts if the error condition is encountered. CALL CHPGN ( PRGNAM,IERR ) IF ( IERR .EQ. 2 ) STOP . . TSXLIB V6.40a PAGE 24 Routine Descriptions CLRGNS This routine is used to clear all definitions of runtime system fast map regions. The calling sequence is as follows: CALL CLRGNS CNVAPA This routine is used to convert a virtual address into a physical address. This is necessary when controlling devices that do direct memory access transfers. The program should lock itself into memory before executing this routine. The calling sequence is as follows: CALL CNVAPA ( IVADR,IPADR ) where: IVADR is the virtual address that is to be converted. IPADR is the name of the two element buffer into which the physical address is to be returned. The low order sixteen bits of the physical address are returned in the first element of the buffer, IPADR, and the high order bits of the physical address are returned in bit positions four through nine of the second element of the buffer. CAUTION If the specified virtual address is above the top of the job or is a PAR7 address mapped either to the simulated RMON or to the I/O page, then the routine will return without error but the value returned will probably be in error. The following example first locks itself into memory then converts a virtual address to a physical address. DIMENSION IPADR ( 2 ) CALL LKANMY CALL CNVAPA ( "54720,IPADR ) . . DISMNT This routine is used to dismount a file structured device. This causes TSX-Plus to stop doing directory caching of the device. The effect of this routine is the same as the TSX-Plus DISMOUNT keyboard command. The calling sequence is as follows: TSXLIB V6.40a PAGE 25 Routine Descriptions CALL DISMNT ( IDVNAM ) where: IDVNAM is the RAD50 value of the file structured device name. The following example uses the SYSLIB routine, IRAD50, to convert the ASCII value of the device name, DL:, to its RAD50 value. It then mounts the device and later dismounts it. CALL IRAD50 ( 3,'DL ',IDVNAM ) CALL MOUNT ( IDVNAM ) . . CALL DISMNT ( IDVNAM ) . . DSMNTA This routine is used to dismount all mounted file structured devices. The calling sequence is as follows: CALL DSMNTA GETREG This routine is used to get the word and byte values stored in the specified processor register. The calling sequence is as follows: CALL GETREG ( IREG,IRET [ ,IERR ] ) where: IREG is the number of the processor register in the range of zero to three whose values are to be returned. IRET is a three-element integer array that is to receive the values returned. The first element receives the word value stored in the specified processor register. The second element receives the low byte value and the third element receives the high byte value. IERR is one of the following: 0 no error. 1 an invalid processor register number was specified. TSXLIB V6.40a PAGE 26 Routine Descriptions NOTE There are no restrictions on where this routine may be called. It may be called from the main line code, from a subroutine, from a completion routine, or from any where else. The following example returns the values stored in processor register one. DIMENSION IRET(3) . . CALL GETREG (1,IRET,IERR) . . GTJBNM This routine is used to get the ASCII name of a job. The calling sequence is as follows: CALL GTJBNM ( LINUM,JOBNAM [ ,IERR ] ) where: LINUM is the number of the line whose job name is to be obtained. JOBNAM is the name of the twelve-byte array that is to receive the ASCII name of the job. IERR is negative or one of the following: 0 the line is not currently logged on. 1 an invalid line number was specified. The following example aborts if the line is not logged on. . . LOGICAL*1 JOBNAM(12) CALL GTJBNM ( LINUM,JOBNAM,IERR ) IF ( IERR .EQ. 0 ) STOP . . GTPGN This routine is used to obtain the name of the program executing on the current line. The calling sequence is as follows: TSXLIB V6.40a PAGE 27 Routine Descriptions CALL GTPGN ( PRGNAM ) where: PRGNAM is the name of the two word buffer that is to receive the program name in RAD50. GTUNAM This routine is used to get the user name associated with the current job. The calling sequence is as follows: CALL GTUNAM ( USRNAM ) where: USRNAM is the name of the twelve-character array that is to receive the user name ASCII string. The following example declares the byte array and then gets the user name. LOGICAL*1 USRNAM(18) CALL GTUNAM ( USRNAM ) . . HIEFOF This routine is used to turn the high efficiency terminal mode off. The calling sequence in as follows: CALL HIEFOF The following example first turns high efficiency terminal mode on and later turns it off. CALL HIEFON . . CALL HIEFOF . . HIEFON This routine is used to turn the high efficiency terminal mode on. The calling sequence is as follows: CALL HIEFON TSX-Plus offers a high efficiency mode of terminal operation that eliminates a substantial amount of system overhead for terminal character processing by reducing the amount of processing that is done on each character. When in high efficiency mode, characters are sent directly to the TSXLIB V6.40a PAGE 28 Routine Descriptions terminal with minimum handling by TSX-Plus. Operations such as expanding tabs to spaces and form feeds to line feeds are omitted as well as input processing such as echoing characters and recognizing control characters such as rubout, control-U and control-C. The only characters treated specially on input are user defined activation characters and the user specified break character. At least one user specified activation character must be declared if high efficiency mode is to be used. This form of terminal I/O is designed to facilitate high speed machine to machine communication. It can be used effectively with buffered mode terminals. IACTCH This routine is used to determine if any activation characters have been received by the line but not yet accepted by the program. The calling sequences are as follows: CALL IACTCH ( IRET ) or IRET = IACTCH () where: IRET is one of the following: 0 at least one activation character is pending. 1 no activation character is pending. IALOC This routine is used to allocate a device for the exclusive use of a job. The calling sequence is as follows: CALL IALOC ( DEVPTR,IRET [ ,IERR ] ) where: DEVPTR is the name of the four element integer array which contains the device name in RAD50 form in the first element and zeros in the other three elements. IRET is undefined, or the number of the job to which the device is currently allocated if IERR = 1, or the job which is currently using the device if IERR = 4. IERR is negative or one of the following: 1 the device is already allocated to another user. 2 an invalid device has been specified. TSXLIB V6.40a PAGE 29 Routine Descriptions 3 the device allocation table is full. 4 the device is currently being used by another user. 5 the job does not have ALLOCATE privilege (IPRIV 1/14). The following example sets up for and allocates a device. If the device is already allocated or busy, the program loops back for another try. If any other error condition prevails, the program aborts. INTEGER DEVPTR(4) DATA DEVPTR /3RDY1,0,0,0/ . . 100 CONTINUE CALL IALOC ( DEVPTR,IRET,IERR ) IF ( IERR .LT. 0 ) GO TO 110 IF ( IERR .EQ. 1 ) GO TO 100 IF ( IERR .EQ. 2 ) STOP IF ( IERR .EQ. 3 ) STOP IF ( IERR .EQ. 4 ) GO TO 100 110 CONTINUE . . IAQFLC This routine is used to allow the running program to acquire the file context of another job. The calling sequences are as follows: CALL IAQFLC ( JOBNUM [ ,IERR ] ) or IERR = IAQFLC ( JOBNUM ) where: JOBNUM is the number of the job whose file context is to be acquired. IERR is negative or one of the following: 0 the job is not peivileged to use this routine. 1 the specified job number is invalid or is not logged on. GETCXT privilege (IPRIV 2/7) is required for a job to use this routine except in the case where the job being accessed is the parent job of the job executing this routine. This routine allows a job to perform file service TSXLIB V6.40a PAGE 30 Routine Descriptions operations for other jobs that it may be servicing. When this routine is executed, the following actions occur: 1. All channels for the job that are opened to files on logical disks are purged. 2. All devices mounted by the job are dismounted. 3. The following items are copied from the job being accessed, replacing the previous information for the job executing this routine: a) ASSIGN commands. b) ACCESS command restrictions. c) Logical disk information. d) Mounted device information. The following example first determines the job number of the parent process and then acquires the file context of that process. If the job is the primary one the program aborts. JOBNUM = ISPY ( -30 ) IERR = IAQFLC ( JOBNUM ) IF ( JOBNUM .EQ. 0 ) STOP . . IASRNT This routine is used to associate a shared run time system with a job. It is also used to disassociate all shared run time systems from a job. The calling sequences are as follows: CALL IASRNT ( IRNTIM [ ,IERR ] ) or IERR = IASRNT ( IRNTIM ) where: IRNTIM is the six character RAD50 value of the name of the shareable run time system. IERR is one of the following: 0 no error. 1 run time system name not recognized. The effect of this routine is to associate a particular shareable run time system with the job. However, this routine does not affect the memory mapping for the job or make the run time system visible to the job. That is done by the MAPRNT routine described later. If some other run time system has been TSXLIB V6.40a PAGE 31 Routine Descriptions previously mapped into the job's region, that mapping is unaffected by this routine. Thus it is possible to have multiple run time systems mapped into the job's region by associating and mapping them one at a time into different regions of the job's virtual memory space. If the name pointer, IRNTIM, is set to zero, this routine causes all run time systems to become disassociated from the job and reestablishes normal memory mapping for the job. The following example uses the SYSLIB routine, IRAD50, to declare the name of the run time system and then associates it with the job. If the error condition is returned the program is halted. DIMENSION IRNTIM ( 2 ) CALL IRAD50 ( 6,'TSXLIB',IRNTIM ) IERR = IASRNT ( IRNTIM ) IF ( IERR .EQ. 1 ) STOP . . IBICIO This routine is used to perform a bit clear operation into a word in the I/O page without requiring the job's virtual address region to be mapped to the I/O page. The calling sequences are as follows: CALL IBICIO ( IADR,IVAL [ ,IERR ] ) or IERR = IBICIO ( IADR,IVAL ) where: IADR is the address of the word in the I/O page to be accessed. IVAL is the value to be bit cleared into the I/O page. IERR is negative or the following: 0 real time support is not available or this job does not have MEMMAP privilege (IPRIV 1/10). The following example bit clears a value in the register at the octal address 176500 in the I/O page. The program is stopped if the error condition is returned. IERR = IBICIO ( "176500,"100 ) IF ( IERR .EQ. 0 ) STOP . . TSXLIB V6.40a PAGE 32 Routine Descriptions IBISIO This routine is used to perform a bit set operation into a word in the I/O page without requiring the job's virtual address region to be mapped to the I/O page. The calling sequences are as follows: CALL IBISIO ( IADR,IVAL [ ,IERR ] ) or IERR = IBISIO ( IADR,IVAL ) where: IADR is the address of the word in the I/O page to be accessed. IVAL is the value to be bit set into the I/O page. IERR is negative or the following: 0 real time support is not available or this job does not have MEMMAP privilege (IPRIV 1/10. The following example bit sets a value into the register at the octal address 176500 in the I/O page. The program is stopped if the error condition returns. IERR = IBISIO ( "176500,"100 ) IF ( IERR .EQ. 0 ) STOP . . IBSTCH This routine is used to broadcast a status change to all jobs that are monitoring the status of the broadcasting job. The calling sequences are as follows: CALL IBSTCH ( IVAL [ ,IERR ] ) or IERR = IBSTCH ( IVAL ) where: IVAL is the 16-bit status code value that is to be broadcast. IERR is negative or the following: 0 no jobs are monitoring the job making this call. On entry to the completion routine in the monitoring job(s), the status value is in processor register R1, the number of the job issuing this call is in the low-order byte of R0, and the high-order bit of R0 is set to one. The GETREG routine may be used to recover the values stored in R0 and R1. TSXLIB V6.40a PAGE 33 Routine Descriptions In the following example the job aborts if no other job is monitoring its status. IERR = IBSTCH ( IVAL ) IF ( IERR .EQ. 0 ) STOP . . ICALOC This routine is used to check the allocation status of a device. The calling sequence is as follows: CALL ICALOC ( DEVPTR,JBNUM,IRET ) where: DEVPTR is the name of the four element integer array which contains the device name in RAD50 form in the first element and zeros in the other three elements. JBNUM is undefined, or the number of the job to which the device is currently allocated if IRET = 1, of the number of the job which is currently using the device if IERR = 4. IRET is negative or one of the following: 1 the device is allocated to another user. 2 an invalid device has been specified. 4 the device is currently being used by another user. In the following example, the program aborts if an invalid device has been specified. INTEGER DEVPTR(4) DATA DEVPTR /3RMT3,0,0,0/ . . CALL ICALOC ( DEVPTR,JBNUM,IRET ) IF ( IRET .EQ. 2 ) STOP . . ICKWTS This routine is used to determine if any other user has written to a shared file. The calling sequence is as follows: TSXLIB V6.40a PAGE 34 Routine Descriptions CALL ICKWTS ( ICHAN [ ,IERR ] ) or IERR = ICKWTS ( ICHAN ) where: ICHAN is the I/O channel open to the shared file. IERR is negative or one of the following: 0 the job does not have RLOCK privilege (IPRIV 2/9), or shared file support is not available on the system, or the channel is not opened to a shared file. 2 writes have been performed. This routine can be used to advantage in a situation where data from some block in the file is being held in a buffer and it is desired to determine if the data is valid or if it may be invalid because some other user might have altered it by writing to the file. The following example opens a file, declares the file to be shared and then checks for writes to the shared file. If writes have been performed to the file the program is halted. OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'RK3:THIS.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 1 * ) ICHAN = ILUN (1) CALL IDCLSF ( ICHAN,5 ) . . IERR = ICKWTS ( ICHAN ) IF ( IERR .EQ. 2 ) STOP . . ICLRST This routine is used to reset a CL unit. The functions performed are: empty both the input silo and the output ring buffer, stop sending any break, clear an XOFF received flag, transmit an XON, clear an end-of-file status, and reset the line and column numbers. The calling sequences are: TSXLIB V6.40a PAGE 35 Routine Descriptions CALL ICLRST ( ICLNO [ ,IERR ] ) or IERR = ICLRST ( ICLNO ) where: ICLNO is the CL unit number (CL0 is 0, C17 is 15., etc). IERR is negative or one of the following: 1 the job issuing the request does not have TERMINAL (IPRIV 2/15) privilege. 2 an invalid CL unit number was specified. 7 the specified CL unit is not assigned to a line. 8 the job issuing the request does not have BYPASS (IPRIV 1/9) privilege. The following example resets CL unit number ten (C12), aborting on an error condition. IERR = ICLRST ( 10 ) IF ( IERR .GE. 0 ) STOP . . ICLXF This routine clears a CL unit's XOFF received flag and transmits an XON. The calling sequences are as follows: CALL ICLXF ( ICLNO [ ,IERR ] ) or IERR = ICLXF ( ICLNO ) where: ICLNO is the CL unit number (CL0 is 0, C17 is 15., etc). IERR is negative or one of the following: 1 the job issuing the request does not have TERMINAL (IPRIV 2/15) privilege. 2 an invalid CL unit number was specified. 7 the specified CL unit is not assigned to a line. 8 the job issuing the request does not have BYPASS (IPRIV 1/9) privilege. The following example clears the XOFF received flan and TSXLIB V6.40a PAGE 36 Routine Descriptions transmits XON for CL unit number 1 (CL1). It aborts if an error condition is encountered. CALL ICLXF ( ICLNO,IERR ) IF ( IERR .GE. 0 ) STOP . . ICNINT This routine is used to connect a completion routine to an interrupt vector. The calling sequences are as follows: CALL ICNINT ( IVEC,CPLRTN,IPRI [ ,IERR ] ) or IERR = ICNINT ( IVEC,CPLRTN,IPRI ) where: IVEC is the interrupt vector address. CPLRTN is the six ASCII character name of the completion routine. IPRI is the priority for the completion routine in the range of 0 to 127. IERR is negative or one of the following: 0 real time support is not available or this job does not have REALTIME privilege (IPRIV 1/6). 1 the maximum number of interrupts are already in use. 2 some other job is already connected to this interrupt vector. 3 the job is not locked into memory. The vector remains connected to the completion routine until the program terminates or until the routine, IRLINT, is executed. On entry to the completion routine, R0 contains the address of the vector that caused the completion routine to be executed. The GETREG routine may be used to obtain the value stored in R0. The following example declares the completion routine as an external and connects an interrupt vector to the completion routine. The program is halted if an error condition is returned. EXTERNAL CPLRTN IERR = ICNINT ( "320,CPLRTN,3 ) IF ( IERR .GE. 0 ) STOP TSXLIB V6.40a PAGE 37 Routine Descriptions . . ICNMCN This routine is used to cancel the job monitoring connection(s) for the calling job. The calling sequences are as follows: CALL ICNMCN ( JBNUM [ ,IERR ] ) or IERR = ICNMCN ( JBNUM ) where: JBNUM is the number of the job for which status monitoring is to be cancelled. If JBNUM = zero, all job status monitoring requests for the job making this call are cancelled. IERR is negative or the following: 1 an invalid job number was specified. All job monitoring requests issued by a job are cancelled by the system when the job terminates, chains, or issues either a hard or soft reset request. The following example program aborts if an invalid job number is specified. CALL ICNMCN ( JBNUM,IERR ) IF ( IERR .EQ. 1 ) STOP . . ICNRTN This routine is used to connect a service routine to an interrupt vector. The calling sequences are as follows: CALL ICNRTN ( IVEC,SVCRTN,0 [ ,IERR ] ) or IERR = ICNRTN ( IVEC,SVCRTN,0 ) where: IVEC is the interrupt vector address. SVCRTN is the six ASCII character name of the service routine. IERR is negative or one of the following: 0 real time support is not available or this job does not have REALTIME privilege (IPRIV 1/6). TSXLIB V6.40a PAGE 38 Routine Descriptions 1 no interrupt control blocks are available 2 some other job is connected to the vector. 3 the job is not locked in memory. The vector remains connected to the service routine until the program terminates or until the routine, IRLINT, is executed. The only system services (EMTs) permissible from within the service routine are the SYSLIB routine, RESUME, and the TSXLIB routine, ITCRTN. If other system services are required, they must be called from a completion routine which has been triggered by ITCRTN. The "0" argument is required. The following example declares the service routine as an external, locks the job in memory, and then connects an interrupt vector to the service routine. The program is halted if an error condition is returned. EXTERNAL SVCRTN IERR = ICNRTN ( IVEC,SVCRTN,IZERO ) CALL LKANMY IF ( IERR .GE. 1 ) STOP . . ICNTSP This routine is used to set the transmit/receive speed or baud rate of a of a communication or timesharing line. The calling sequencs are as follows: CALL ICNTSP ( LINUM,ISPCD [,IERR ] ) or IERR = ICNTSP ( LINUM,ISPCD ) where: LINUM is the number of the line for which the speed is to be controlled. If the line number is zero, the speed is set for the line on which the calling program is executing. ISPCD is one of the following: 0 50 baud. 1 75 baud. 2 110 baud. 3 134.5 baud. 4 150 baud. 5 300 baud. TSXLIB V6.40a PAGE 39 Routine Descriptions 6 600 baud. 7 1200 baud. 8 1800 baud. 9 2000 baud. 10 2400 baud. 11 3600 baud. 12 4800 baud. 13 7200 baud. 14 9600 baud. 15 19200 baud. IERR is negative or one of the following: 1 the job does not have TERMINAL privilege (IPRIV 2/15). 2 the specified line number was invalid. This routine is only functional for lines connected to hardware controllers that support programmable baud rates. The following example sets the speed of the line on which the program is running to 9600 baud. CALL ICNTSP ( 0,14 ) . . ICONTM This routine is used to return the connect time of a job to the calling program. The calling sequence is as follows: CALL ICONTM ( LINUM,IRET [ ,IERR ] ) where: LINUM is the TSX-Plus line for which connect time is to be returned. IRET is the returned connect time in minutes. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. TSXLIB V6.40a PAGE 40 Routine Descriptions In the following example the connect times of the logged on lines are returned in the variable, IRET. LINUM = 0 10 CONTINUE LINUM = LINUM + 1 CALL ICONTM ( LINUM,IRET,IERR ) IF ( IERR .EQ. 0 ) GO TO 10 IF ( IERR .EQ. 2 ) GO TO 20 . . GO TO 10 20 CONTINUE ICPUTM This routine is used to return a job's CPU time to the calling program. The calling sequence is as follows: CALL ICPUTM ( LINUM,ITIME [ ,IERR ] ) where: LINUM is the TSX-Plus line for which CPU time is to be returned. ITIME is the CPU time returned in clock ticks. The variable, ITIME, is a two element array where the first element will receive the high order 16 bits and the second element will receive the low order 16 bits of the CPU time returned. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. The CPU time of line five is returned in the following example. The program aborts if an error condition prevails. DIMENSION ITIME(2) . . CALL ICPUTM ( 5,ITIME,IERR ) IF ( IERR .GE. 0 ) STOP . . ICRWND This routine is used to create a window. The calling sequences are as follows: TSXLIB V6.40a PAGE 41 Routine Descriptions CALL ICRWND ( ID,IFLG,IWDTH,ISCRL,IDCPY,JBCPY [ ,IERR ] ) or IERR = ICRWND ( ID,IFLG,IWDTH,ISCRL,IDCPY,JBCPY ) where: ID is is a window identification number in the range of 1 to 26 which identifies the window for this job. IFLG is one of the following: 0 the window is a temporary window and will be deleted when the program exits to the keyboard monitor. 1 the window is a permanent window and is only deleted when explicitly requested (by the IDLWND routine, or the SET WINDOW OFF keyboard command) or when the job logs off. IWDTH is the width of the window in columns and should not exceed 132. ISCRL is the maximum number of lines which are allowed to scroll off the window during a time when the window is disconnected from the terminal. Specify 0 to disallow any scrolling. Specify 1 to allow unlimited scrolling. IDCPY is the window identification number of the window from which to copy certain window characteristics. If 0, no information is copied. If in the range of 1 to 26, the following characteristics are copied: 1) The number of columns per line. 2) The maximum allowed number of lines to be scrolled while switched to a different process. 3) 80 or 132 column mode. 4) Light or dark video mode. JBCPY is the job number of the job from which to copy certain window characteristics. If 0, the current job is assumed. IERR is negative or one of the following: 0 Window management is not included in the system. 1 Maximum allowed number of windows are already in use. TSXLIB V6.40a PAGE 42 Routine Descriptions 2 Unable to create the window. Job may not have SYSGBL privilege (IPRIV 2/8) or sufficient memory may not be available. The following example creates a permanent 72 column wide window with an identification number of 13 and allows up to 20 lines to scroll off the window. The program aborts if an error condition is returned. IERR = ICRWND ( 13,1,72,20,0,0 ) IF ( IERR .GE. 0 ) STOP . . IDALOC This routine is used to deallocate a device. The calling sequence is as follows: CALL IDALOC ( DEVPTR,IRET, [ IERR ] ) where: DEVPTR is the name of the four element integer array which contains the device name in RAD50 form in the first element and zeros in the other three elements. IRET is undefined, or the number of the job to which the device is currently allocated if IERR = 1, or the number of the job which is currently using the device if IERR = 4. IERR is negative or one of the following: 1 the device is allocated to another user. 2 an invalid device has been specified. 4 the device is currently in use by another job. 5 the job does not have ALLOCATE privilege (IPRIV 1/14). The following example program aborts if the device is allocated to another user. INTEGER (4) DATA /3RDX0,0,0,0/ . . CALL IDALOC ( DEVPTR,IRET,IERR ) IF ( IERR .EQ. 1 ) STOP . . TSXLIB V6.40a PAGE 43 Routine Descriptions IDCLSF This routine is used to declare an open file to be shared. The calling sequences are as follows: CALL IDCLSF ( ICHAN,IACES [ ,IERR ] ) or IERR = IDCLSF ( ICHAN,IACES ) where: ICHAN is the I/O channel number open to the shared file. IACES is one of the following protection/access codes: 0 exclusive/input. 1 exclusive/update. 2 protected/input. 3 protected/update. 4 shared/input. 5 shared/update. IERR is negative or one of the following: 0 shared file support is not available on the system or the job does not have RLOCK privilege (IPRIV 2/9). 1 the I/O channel has not been opened to a file. 2 attempted to open too many channels to shared files. 3 attempted to open too many shared files. 4 a file protection/access conflict exists. The protection/access code specifies two things, the type of protection (exclusive, protected, shared) that you are claiming on your use of the file and the type of access (input or update) that you intend to make to the file. Exclusive protection means that you require exclusive access to the file and will allow no other users to access the file in any fashion. Protected protection means that you will allow other users to open the file for input but wish to prohibit any from opening the file for update. Shared protection means that you are willing to allow other users to open the file for both input and update. The following example opens a file and then declares TSXLIB V6.40a PAGE 44 Routine Descriptions exclusive/update protection/access. If an error condition is returned the program aborts. OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'RK3:FILE.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 1 * ) ICHAN = ILUN (1) REWIND 40 IERR = IDCLSF ( ICHAN,2 ) IF ( IERR .NE. 0 ) STOP . . IDFRGN This routine is used to define runtime regions for fast mapping. The calling sequences are as follows: CALL IDFRGN ( IPAR,IOFSET,ISIZ,IRGN [ ,IERR ] ) or IERR = IDFRGN ( IPAR,IOFSET,ISIZ,IRGN ) where: IPAR is the page address register (PAR) number through which the region is to be mapped. IOFSET is the offset in 64-byte blocks from the beginning of the shared runtime system where the region is to start. ISIZ is the size in 64-byte blocks of the region to be defined. IRGN is the index number in the range of 0 to 39 for the region to be defined. IERR is negative or one of the following: 1 no shared runtime system has been associated with the job. 2 the region index number is invalid. 3 the specified size is greater than 128 units of 64-bytes (8 kb). 5 the specified offset is beyond the end of the runtime system. TSXLIB V6.40a PAGE 45 Routine Descriptions The following example first associates a runtime system and then defines two regions for fast mapping. It then fast maps to the regions. Finally, it clears the region definitions and disassociates from the runtime system. The example aborts on any error condition encountered. IERR = IASRNT ( IRNTIM ) IF ( IERR .GE. 1 ) STOP IERR = IDFRGN ( IPAR1,IOFS1,ISIZ1,0 ) IF ( IERR .GE. 1 ) STOP IERR = IRFRGN ( IPAR2,IOFS2,ISIZ2,1 ) IF ( IERR .GE. 1 ) STOP . . IERR = ITRAP ( 1 ) IF ( IERR .NE. -1) STOP . . IERR = ITRAP ( 0 ) IF ( IERR .NE. -1) STOP . . CALL CLRGNS CALL IASRNT ( 0 ) . . IDLWND This routine is used to delete one or more windows that were created with the ICRWND routine. The calling sequences are as follows: CALL IDLWND ( ID [, IERR ]) or IERR = IDLWND ( ID ) where: ID is the window identification number of the window that is to be deleted. IERR is negative or one of the following: 0 window management support is not included in the system. 3 unable to locate the window with the specified window identification number. If the window identification number is zero, then all of the temporary windows for the job are deleted. If the window identification number is 255, then all the temporary and permanent windows for the job are deleted. This routine requires the SYSGBL privilege (IPRIV 2/8). TSXLIB V6.40a PAGE 46 Routine Descriptions IDMALD This routine dismounts all currently mounted logical devices. The calling sequences are: CALL IDMALD ( IERR ) or IERR = IDMALD () where: IERR is negative or the following: 3 a channel is open to a logical disk. The following example proceeds if the error condition is not encountered. IERR = IDMALD () IF ( IERR .EQ. -1 ) GO TO 100 . . 100 CONTINUE . . IDMLD This routine is used to dismount a logical device (LD). The calling sequences are as follows: CALL IDMLD ( LDNUM [ ,IERR ] ) or IERR = IDMLD ( LDNUM ) where: LDNUM is the LD unit number in the range of zero through seven. IERR is negative or one of the following: 0 the specified LD unit is not associated with a file. 1 an invalid LD unit number was specified. 3 some channel is open to a file on the specified LD. The following example aborts if the LD is in use by another job. . . IERR = IDMLD ( LDNUM ) IF ( IERR .EQ. 3 ) STOP . TSXLIB V6.40a PAGE 47 Routine Descriptions . IESMCN This routine is used to establish a job monitoring connection between the calling job and another job. The calling sequences are as follows: CALL IESMCN ( JBNUM,CPLRTN [ ,IERR ] ) or IERR = IESMCN ( JBNUM,CPLRTN ) where: JBNUM is the number of the job to be monitored. If zero is specified as the number of the job to be monitored, all jobs are monitored (including those that are not currently logged on). CPLRTN is the name of the completion routine to be entered when the status of the monitored job changes. IERR is negative or one of the following: 1 an invalid job number was specified. 2 there are no free job monitoring control blocks available. The specified completion routine will be entered each time the status of the monitored job changes or the monitored job broadcasts a status change. On entry to the completion routine, the low-order byte of processor register R0 contains the number of the job whose status change is being reported. The high-order bit of R0 is zero if the status report was generated by the system and is one if the status report was generated by a program broadcasting a status change. The status value is contained in processor register R1. The values stored in R0 and R1 may be recovered with the GETREG routine. The system generated status values are listed below: 1 The job has been initialized. 2 The job logged on using the LOGON program. 3 The job began running a program. 4 The job returned control to KMON. 5 The job has logged off. The following example program establishes a job status monitoring connection. If there are no control blocks available, it loops back for another try. The program aborts if an invalid job number has been specified. TSXLIB V6.40a PAGE 48 Routine Descriptions EXTERNAL CPLRTN . . 100 CONTINUE IERR = IESMCN ( JBNUM,CPLRTN ) IF ( IERR .EQ. 2 ) GO TO 100 IF ( IERR .EQ. 1 ) STOP . . IEXSTS This routine is used to return the execution state of a TSX-Plus line. The calling sequence is as follows: CALL IEXSTS ( LINUM,ISTAT [ ,IERR ] ) where: LINUM is the number of the line for which execution state is returned. ISTAT is the one of the following execution state values: 1 high priority run state. 2 normal priority run state. 3 low priority run state. 4 waiting for terminal input. 5 waiting to write terminal output. 6 doing a timed wait. 7 suspended by SUSPND or .SPND. 8 waiting to access a shared file. 9 waiting for a message. 10 waiting for access to the USR. 11 waiting for I/O to finish. 12 waiting to access spool file. 13 Interactive high priority run state. 14 Fixed high priority run state. 15 Waiting for memory expansion. IERR is negative or one of the following: TSXLIB V6.40a PAGE 49 Routine Descriptions 0 line is not currently logged on. 2 invalid line number. The program in the following example halts if line 2 is doing a timed wait. CALL IEXSTS ( LINUM,ISTAT ) IF ( ISTAT .EQ. 6 ) STOP . . IFLINF This routine obtains some information about a file. The calling sequence is as follows: CALL IFLINF ( ICHAN,IDEV,INFO [ ,IERR ] ) where: ICHAN is a channel number in the range of zero through sixteen that is currently not in use. IDEV is the name of a four-word array that contains the file specification in RAD50. INFO is the name of the seven-word array that is to receive the following information about the file: Word 1 is the number of 512-byte blocks contained in the file. Word 2 is zero if the file is not protected, or one if the file is protected. Word 3 is the creation date of the file in RT-11 internal format. Word 4 is the creation time of the file in three-second units. Word 5 is the starting block number of the file. Word 6 is reserved. Word 7 is reserved. IERR is negative or one of the following 0 The channel is currently in use. 1 Unable to locate the specified file. TSXLIB V6.40a PAGE 50 Routine Descriptions 2 The specified device is not file structured. The following example obtains the information about the file, DY1:STUFF.DAT. DIMENSION IDEV(4),INFO(7) ICHAN = IGETC () CALL IRAD50 ( 12,'DY1STUFF DAT',IDEV) CALL IFLINF ( ICHAN,IDEV,INFO,IERR ) IF ( IERR .GT. 0 ) STOP 'IFLINF error' . . IGNPIC This routine returns the number of pending input characters for the terminal from which the calling program is executine. The calling sequences are: CALL IGNPIC ( IRET ) or IRET = IGNPIC () where: IRET is the number of pending input characters. The program in the following example proceeds if there are no pending input characters. CALL IGNPIC ( IRET ) IF ( IRET .EQ. 0 ) GO TO 100 . . 100 CONTINUE . . ILDTR This routine is used to lower the DTR signal on a communication or a timesharing line. The calling sequences are as follows: CALL ILDTR ( LINUM [ ,IERR ] ) or IERR = ILDTR ( LINUM ) where: LINUM is the number of the line whose DTR signal is to be lowered. TERMINAL (IPRIV 2/15) is required if the line number is not the same as the one on which the job is running. IERR is negative or one of the following: TSXLIB V6.40a PAGE 51 Routine Descriptions 1 the job does not have TERMINAL (IPRIV 2/15) privilege. 2 an invalid line number was specified. This is only effective if the interface supports modem control signals. This can be useful in situations where a modem or data PBX requires the DTR signal. The following example first determines its line number and then lowers its DTR signal. . . LINUM = ITSLIN () CALL = ILDTR ( LINUM ) . . ILNSTS This routine is used to return information about the status of a line. The calling sequence is as follows: CALL ILNSTS ( LINUM,IRET [ ,IERR ] ) where: LINUM is the TSX-Plus line for which status information is returned. IRET is the value returned and contains bit-flags that indicate the status for the line. The following bit-flags are defined: 000000 physical line. 000001 virtual line. 000002 detached job line. 000100 job is locked in memory. 000200 job has operator privilege. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. The program in the example below stops if the line number is invalid. CALL ILNSTS ( LINUM,IRET,IERR ) IF ( IERR .EQ. 2 ) STOP TSXLIB V6.40a PAGE 52 Routine Descriptions . . INITPA This routine is used to set up parameters that will control a performance analysis. It does not actually begin the analysis. The calling sequences are as follows: CALL INITPA ( IBSADR,ITPADR,ICLSZ,IFLAG [ ,IERR ] ) or IERR = INITPA ( IBSADR,ITPADR,ICLSZ,IFLAG ) where: IBSADR is the base address of the region to be monitored. ITPADR is the top address of the region to be monitored. ICLSZ is the number of bytes to group into each histogram cell. IFLAG is one of the following: 0 do not include I/O wait time. 1 include I/O wait time. IERR is negative or one of the following: 0 performance analysis is already in use. 1 performance analysis feature is not included in this version of TSX-Plus. The following example initializes for a performance analysis. The program aborts if an error condition is returned. IERR = INITPA ( "2000,"5400,"100,0 ) IF ( IERR .GE. 0 ) STOP . . INITSP This routine is used to initialize a new or switch to an existing subprocess. It performs the same function as if a CTRL-W-digit sequence had been typed at the terminal. The calling sequence is as follows: CALL INITSP ( ISPN,IRPN,0,CMDFIL,IRET [ ,IERR ] ) where: ISPN indicates the subprocess number and is analogous TSXLIB V6.40a PAGE 53 Routine Descriptions to the digit typed after CTRL-W when manually switching between subprocesses. The value must be in the range of zero to MAXSEC, a TSGEN parameter. If a minus one is specified, the system locates the first unused subprocess number and uses it. IRPN indicates which process to return to when the process initiated by this routine terminates as follows: 0 specifies return to the primary process. 1 specifies return to the process which is executing this routine to initiate the subprocess. CMDFIL is the name of the string variable containing the file specification of a command file to be executed when the subprocess is initiated. This command file executes without start-up privilege following any other start-up command file specified with the SET SUBPROCESS/FILE command. If the variable is empty, no command file is executed. IRET if ISPN is too large, the TSGEN parameter, MAXSEC, is returned. If ISPN is minus one, the number of the subprocess initiated is returned. IERR is negative or one of the following: 1 the job does not have SUBPROCESS (IPRIV 2/11) privilege. 2 the specified subprocess number is too large. 3 all of the job's subprocesses are already active. 4 there is insufficient memory available for the subprocess. IPEKIO This routine is used to access or peek at a word in the I/O page without requiring the job's virtual address region to be mapped to the I/O page. The calling sequence is as follows: CALL IPEKIO ( IADR,IRET [ ,IERR ] ) where: IADR is the address of the word in the I/O page that is to be accessed. TSXLIB V6.40a PAGE 54 Routine Descriptions IRET is the value returned from the I/O page. IERR is negative or the following: 0 real time support is not available or this job does not have MEMMAP privilege (IPRIV 1/10). The following example obtains the value from the register at octal address 176502 in the I/O page. The program is aborted if the error condition is returned. CALL IPEKIO ( "176502,IRET,IERR ) IF ( IERR .EQ. 0 ) STOP . . IPGNAM This routine is used to return the name of the program being executed by a TSX-Plus line. The calling sequence is as follows: CALL IPGNAM ( LINUM,PGNAME [ ,IERR ] ) where: LINUM is the number of the line executing the returned program name. PGNAME is the two-word variable into which the RAD50 value of the program name is returned. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. The SYSLIB routine R50ASC is used to convert the returned program name to an ASCII string in the following example. LOGICAL*1 STRING(8) . . CALL IPGNAM ( LINUM,PGNAM,IERR ) IF ( IERR .GE. 0 ) STOP CALL R50ASC ( 6,PGNAM,STRING ) IPOKIO This routine is used to deliver a value into a word in the I/O page without requiring the job's virtual address region to be mapped to the I/O page. The calling sequences are as follows: TSXLIB V6.40a PAGE 55 Routine Descriptions CALL IPOKIO ( IADR,IVAL [ ,IERR ] ) or IERR = IPOKIO ( IADR,IVAL ) where: IADR is the address of the word in the I/O page to be accessed. IVAL is the value to be deposited in the I/O page. IERR is negative or the following: 0 real time support is not available or this job does not have MEMMAP privilege (IPRIV 1/10). The following example pokes a value into the register at octal address 176506 in the I/O page. The program stops if the error condition is returned. IERR = IPOKIO ( "176506,"101 ) IF ( IERR .EQ. 0 ) STOP . . IPPNUM This routine is used to return the project and programmer numbers for a TSX-Plus line. The calling sequence is as follows: CALL IPPNUM ( LINUM,IBUF [ ,IERR ] ) where: LINUM is the number of the line for which the project and programmer numbers are returned. IBUF is the two word array into which the project and programmer numbers are returned. The first word contains the project number and the second word contains the programmer number. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. The program in the following example stops if an error condition is encountered. DIMENSION IBUF(2) . . CALL IPPNUM ( LINUM,IBUF,IERR ) IF ( IERR .GE. 0 ) STOP TSXLIB V6.40a PAGE 56 Routine Descriptions . . IPRIV This routine permits the running program to determine or to change the job privilege sets. The calling sequence is as follows: CALL IPRIV ( IFUN,IPRVT,BUFFER [ ,IERR ] ) where: IFUN is one of the following function control values: 0 causes the privilege flags to be stored into the specified buffer. 1 causes the privilege flags that are set in the buffer to be cleared in the corresponding system table. 2 causes the privilege flags that are set in the buffer to be set in the corresponding system table. IPRVT indicates which of the three sets of privilege flags are to be accessed and must be one of the following values: 0 the current job privileges are selected. 1 the set privileges for the job are selected. If any privileges are changed, the current privileges are also changed. 2 the authorized privileges are selected. BUFFER is the name of the four-word buffer that is to receive or contains the privilege flags. A flag value of 1 enables the privilege and a value of 0 denies the privilege. The following list shows the privilege related to each flag (word/bit). 1/0 SYSPRV, system privilege (system manager type operations). 1/1 NFSWRITE, non-file structured read/write access. 1/2 NFSREAD, non-file-structured read access. 1/3 SETPRV, affect own privileges. 1/4 SETNAME, change user name or password. TSXLIB V6.40a PAGE 57 Routine Descriptions 1/5 SEND, sending messages between jobs (not using a named message channel). 1/6 REALTIME, real time support. 1/7 PSWAPM, change process swap mode. 1/8 OPER, operator. 1/9 BYPASS, bypass device/file access restrictions. 1/10 MEMMAP, access memory that may be significant to the system. 1/11 SPFUN, use the .SPFUN EMT. 1/12 DETACH, affect detached jobs. 1/13 DEBUG, use of the debugging facilities. 1/14 ALLOCATE, device allocation. 1/15 reserved. 2/0 UP1, user-defined privilege #1. 2/1 UP2, user defined privilege #2. 2/2 UP3, user-defined privilege #3. 2/3 UP4, user-defined privilege #4. 2/4 through 2/6 reserved. 2/7 GETCXT, get file context from another job. 2/8 SYSGBL, global regions. 2/9 RLOCK, shared file record locking. 2/10 MESSAGE, named message channels. 2/11 SUBPROCESS, use subprocesses (virtual lines). 2/12 SAME, affect jobs with the same project and programmer numbers. 2/13 GROUP, affect jobs with the same project number. 2/14 WORLD, affect any job. 2/15 TERMINAL, terminal and CL commands. TSXLIB V6.40a PAGE 58 Routine Descriptions 3/0 through 4/15 reserved. IERR is negative or the following: 1 attempt to enable privileges for which the job is not authorized. Only those privileges for which the job is authorized are set. SETPRV privilege is required to set any new privileges in the authorized privilege set. The following example returns the set of authorized job privileges to the buffer. INTEGER BUFFER(4) DATA IFUN,IPRVT /0,2/ CALL IPRIV ( IFUN,IPRVT,BUFFER ) IPRPAN This routine determines both the primary and parent process numbers for the named job. The calling sequence is as follows: CALL IPRPAN ( LINUM,IBUF [ ,IERR ] ) where: LINUM is the number of the TSX-Plus line for which the information is to be returned. IBUF is a two-element array that receives the returned information, the primary process number in element one and the parent process number in element two. IERR is negative or one of the following: 0 the named line is not currently logged on. 1 the named line number is invalid. The following example prints the primary and parent process numbers for the job running on line four. It aborts if an error condition is encountered. DIMENSION IBUF(2) CALL ( 4,IBUF,IERR ) IF ( IERR .GE. 0 ) STOP TYPE *,'Primary :',IBUF(1) TYPE *,'Parent :',IBUF(2) . . TSXLIB V6.40a PAGE 59 Routine Descriptions IPRWND This routine causes the contents of a window to be printed. The calling sequences are as follows: CALL IPRWND ( ID [ ,IERR ] ) or IERR = IPRWND ( ID ) where: ID is the window identification number of the window whose contents are to be printed. IERR is negative or one of the following: 0 Windowing support is not available on the system. 3 the specified window identification number is invalid. 4 the WINPRT program is not running. The following example aborts if an error condition is detected. IERR = IPRWND ( ID ) IF ( IERR .GE. 0 ) STOP . . IRDRCL This routine is used to redirect a dedicated communication line, CL unit, or a timesharing line. The calling sequences are as follows: CALL IRDRCL ( ICLNO,LINUM [ ,IERR ] ) or IERR = IRDRCL ( LCLNO,LINUM ) where: ICLNO is the dedicated communication line number, CLn. LINUM is the number of the timesharing line or the dedicated communication line. IERR is negative or one of the following: 1 the user making this call does not have TERMINAL privilege (IPRIV 2/15). 2 an invalid CL unit number, ICLNO, was specified. 3 an invalid line number, LINUM, was TSXLIB V6.40a PAGE 60 Routine Descriptions specified. 4 the specified line number, LINUM, is already assigned to a CL unit. 5 a timesharing user is logged onto the specified line number, LINUM. 6 the specified CL unit, ICLNO, is currently in use. The following sample program aborts if an error is returned when it attempts to redirect CL3 to line number 9. CALL IRDRCL ( 3,9,IERR ) IF ( IERR .GT. 0 ) STOP . . IRDTR This routine is used to raise the DTR signal on a communication or a timesharing line. The calling sequences are as follows: CALL IRDTR ( LINUM [ ,IERR ] ) or IERR = IRDTR ( LINUM ) where: LINUM is the number of the line whose DTR signal is to be raised. TERMINAL (IPRIV 2/15) privilege is required if the line number is not the sams as the one on which the job is running. IERR is negative or one of the following: 1 the job does not have TERMINAL (IPRIV 2/15) privilege. 2 an invalid line number was specified. This is only effective if the interface supports modem control signals. This can be useful in situations where a modem or data PBX requires the DTR signal. The following example aborts if it does not have TERMINAL (IPRIV 2/15) privilege. . . IERR = IRDTR ( LINUM ) IF ( IERR .EQ. 1 ) STOP . . TSXLIB V6.40a PAGE 61 Routine Descriptions IRLINT This routine releases the connection of an interrupt vector and a completion routine or a service routine. The connection must have been made by previously executing the routine, ICNINT or ICNRTN. The calling sequence is as follows: CALL IRLINT ( IVEC ) where: IVEC is the interrupt vector address. REALTIME privilege (IPRIV 1/6) is required to execute this routine. The following example first declares the completion routine as an external, then connects it to a vector, and finally breaks the connection. EXTERNAL CPLRTN CALL ICNINT ( "320,CPLRTN,0 ) . . CALL IRLINT ( "320 ) . . IRSWND This routine is used to resume processing of the currently selected window. The calling sequence is as follows: CALL IRSWND No operation is performed if the job has no active window. The SYSGBL privilege (IPRIV 2/8) is required to execute this routine. IRXOFF This routine is used to reset the XOFF (CTRL-S) state of a communication or a timesharing line. This only affects XOFFs received by the system from a terminal and not the XOFFs sent to the terminal by the system. The calling sequences are: CALL IRXOFF ( LINUM [ ,IERR ] ) or IERR = IRXOFF ( LINUM ) where: LINUM is the number of the line on which the XOFF state is to be reset. TERMINAL (IPRIV 2/15) privilege is required if the line to be affected is not the line on which the job is running. TSXLIB V6.40a PAGE 62 Routine Descriptions IERR is negative or one of the following: 1 the job does not have TERMINAL (IPRIV 2/15) privilege. 2 an invalid line number was specified. The following example aborts if an invalid line number is specified. . . IERR = IRXOFF ( LINUM ) IF ( IERR .EQ. 2 ) STOP . . ISLWND This routine is used to select a window that has already been created with the ICRWND routine. The calling sequences are as follows: CALL ISLWND ( ID [ ,IERR ] ) or IERR = ISLWND ( ID ) where: ID is the window identification number of the window to be selected and displayed. IERR is negative or one of the following: 0 window management support is not included in the system. 3 unable to locate the window with the specified window identification number. A window identification number of zero causes windowing to be disabled for the job. However, the contents of all existing windows are retained and may be reselected later. The SYSGBL privilege (IPRIV 2/8) is required to execute this routine. In the following example, the program aborts if an error condition prevails typing out an appropriate error message. CALL ISLWND ( ID,IERR ) IF ( IERR .EQ. 0 ) STOP 'No window support' IF ( IERR .EQ. 3 ) STOP 'Cannot find window' . . TSXLIB V6.40a PAGE 63 Routine Descriptions ISPBLK This routine is used to determine the number of free blocks in the spool file. The calling sequences are as follows: CALL ISPBLK ( IRET ) or IRET = ISPBLK () where: IRET is the number of free blocks in the spool file. ISPCTL This routine is used to control the release time of a spooled file. The calling sequences are as follows: CALL ISPCTL ( ICHAN,IFLAG [ ,IRET ] ) or IRET = ISPCTL ( ICHAN,IFLAG ) where: ICHAN is the number of the channel that is open to the file. IFLAG is an integer value as follows: 0 release the file immediately. 1 hold the release until the file is closed. IRET is a returned integer with the following meanings: <0 the device was not found or is not spooled. 0 the previous mode was nohold. >0 the previous mode was hold. This routine must be called after the file has been opened and before any data is written to the file. OPER privilege (IPRIV 1/8) is required to execute this routine. The following example causes the file to be written to the spooled line printer to be released immediately. OPEN ( UNIT=30,NAME=LP: ) ICHAN = ILUN ( 30 ) CALL ISPCTL ( ICHAN,1 ) . . TSXLIB V6.40a PAGE 64 Routine Descriptions ISPFLC This routine controls the centering of the information on flag pages on either 80 or 132 columns. The calling sequences are as follows: CALL ISPFLC ( ICHAN,IFLAG [ ,IRET ] ) or IRET = ISPFLC ( ICHAN,IFLAG ) where: ICHAN is the number of the channel that is open to the file. IFLAG is an integer value as follows: 0 center on 80 columns. 1 center on 132 columns. IRET is a returned integer value with the following meanings: <0 the device was not found or is not spooled. 0 the previous centering was on 80 columns. >0 the previous centering was on 132 columns. The following example establishes flag page centering on 132 columns. Then it restores the previous mode of centering. OPEN ( UNIT=20,NAME=LP2: ) ICHAN = ILUN ( 20 ) IRET = ISPFLC ( ICHAN,1 ) . . CALL ISPFLC ( ICHAN,IRET ) . . ISPFLP This routine is used to control the use or nonuse of flag pages with spooled devices. The calling sequences are as follows: CALL ISPFLP ( ICHAN,IFLAG [ ,IRET ] ) or IRET = ISPFLP ( ICHAN,IFLAG ) where: ICHAN is the number of the channel that is open to the file. IFLAG is an integer value as follows: TSXLIB V6.40a PAGE 65 Routine Descriptions 0 disable the use of flag pages. 1 enable the use of flag pages. IRET is a returned integer with the following meanings: <0 the device was not found or is not spooled. 0 the previous mode was disabled flag pages. >0 the previous mode was enabled flag pages. The following example enables flag pages. It aborts on an error condition. OPEN ( UNIT=10,NAME=LS: ) ICHAN = ILUN ( 10 ) IRET = ISPFLP ( ICHAN,1 ) IF ( IRET .LT. 0 ) STOP . . ISPLN This routine is used to get the line number on which the named subprocess is executing. The calling sequences are: CALL ISPLN ( IRSPN [ ,IERR ] ) or IERR = ISPLN ( IRSPN ) where: IRSPN is the relative subprocess number. IERR is negative or one of the following: 0 the specified subprocess is not active. 1 invalid subprocess number. 2 attempted to call this routine from a DETACHed job. The following example aborts if the program is running as a DETACHed job. IERR = ISPLN ( 1 ) IF ( IERR .EQ. 2 ) STOP . . TSXLIB V6.40a PAGE 66 Routine Descriptions ISPPA This routine is used to suspend the collection of data for a performance analysis. The data collection can be restarted by using the ISTPA routine described later. The calling sequences are as follows: CALL ISPPA [ IERR ] or IERR = ISPPA () where: IERR is negative or the following: 0 performance analysis has not been previously initialized. The following example initializes for a performance analysis, then starts and stops the collection of data for the analysis within a loop. CALL INITPA ( "2000,"5400,"100,0 ) DO 10 I = 1,53 CALL ISTPA . . CALL ISPPA . . 10 CONTINUE . . ISPUSE This routine determines the number of blocks that are currently in use in the spool file. The calling sequences are as follows: CALL ISPUSE ( IRET ) or IRET = ISPUSE () where: IRET is the number of blocks in use in the spool file. ISPWND This routine is used to suspend window processing of the currently selected window. The calling sequence is as follows: CALL ISPWND When window processing is suspended, characters are sent to TSXLIB V6.40a PAGE 67 Routine Descriptions the terminal without being processed by the window management system. No operation is performed if the job has no active windows. The SYSGBL privilege (IPRIV 2/8) is required to execute this routine. ISPY This is a SYSLIB routine that is used to return the value located at a specific offset into the simulated RMON. TSX-Plus has extended it to return several TSX-Plus values. Refer to the "RT-11 Programmer's Reference Manual" [5] for information on getting values from within the simulated RMON. The calling sequence is as follows: IRET = ISPY ( IOFFST ) where: IRET is the integer value returned. IOFFST is the integer offset into the simulated RMON or to return a TSX-Plus value is one of the following: -2 job number. -4 lead-in character used for terminal controlled options. -6 zero if job does not have system privilege, SYSPRIV (IPRIV 1/0), or one if job does have system privilege. -8 zero if PAR 7 is mapped to the simulated RMON or one if PAR 7 is mapped to the I/O page. -10 project number job is logged on under. -12 programmer number job is logged on under. -14 TSX-Plus license number. -16 get the job's priority level. -18 get the job's maximum allowable priority level. -20 the number of blocks per job in the file SY:TSXUCL.TSX. -22 get the job number of the primary line (0 if this is the primary line). -24 get the RAD50 name of the physical SY: device. TSXLIB V6.40a PAGE 68 Routine Descriptions -26 value of the PRILOW sysgen parameter. -28 value of the PRIHI sysgen parameter. -30 job number of the parent process (0 for the primary process). -32 get the TSX-Plus version number times 100. -34 get the job's relative subprocess number. Primary and detached lines return zero. Subprocesses return the relative subprocess number equivalent to the digit typed after a CTRL-W. The following example aborts if the job is not privileged. IRET = ISPY ( -6 ) IF ( IRET .EQ. 0 ) STOP . . ISTDJ This routine is used to check the status of a detached job. The calling sequences are as follows: CALL ISTDJ ( JOBNUM,ISTAT ) or ISTAT = ISTDJ ( JOBNUM ) where: JOBNUM is the job number of the detached job. ISTAT is one of the following: 0 the job is not active. 1 the job is active. The following example starts a detached job then checks the detached job's status until the job becomes inactive. CALL STDTJB ( JOBNAM,JOBNUM ) 10 CONTINUE ISTAT = ISTDJ ( JOBNUM ) IF ( ISTAT .NE. 1 ) GO TO 10 . . ISTFTM This routine is used to set the creation time for a file. The calling sequences are as follows: TSXLIB V6.40a PAGE 69 Routine Descriptions CALL ISTFTM ( ICHAN,IDEV,ITIME [ ,IERR ] ) or IERR = ISTFTM ( ICHAN,IDEV,ITIME ) where: ICHAN is a channel number in the range of zero through sixteen that is currently not in use. IDEV is the name of the four-word array containing the file specification in RAD50. ITIME is an integer time value in three-second units since midnight. IERR is negative or one of the following. 0 the channel is currently in use. 1 unable to locate the specified file. 2 the specified device is not file structured. The following example sets the creation time for the file, NICKS.DAT, at 300 three-second units past midnight. DIMENSION IDEV(4) DATA ICHAN,ITIME /0,300/ CALL IRAD50 ( 12,DM4NICKS DAT,IDEV) 100 CONTINUE IERR = ISTFTM ( ICHAN,IDEV,ITIME ) IF ( ICHAN .GT 16 ) STOP 'No channels' IF ( IERR .EQ. 0 ) GO TO 100 IF ( IERR .GT. 0 ) STOP 'ISTFTM error' . . ISTLD This routine is user to obtain certain status information about a logical device (LD). The calling sequence is as follows: CALL ISTLD ( LDNUM,ISTBF ) where: LDNUM is the LD unit number in the range of zero through seven. ISTBF is a five element buffer that is to receive the status information about the specified LD. If the LD is associated with a file, the first four elements will receive the RAD50 value for the dev:filnam.ext of the file. The fifth element is a flag word. If the LD is mounted for read-only access, bit zero of the flag word will be set. If the LD is not currently accessable, TSXLIB V6.40a PAGE 70 Routine Descriptions bit one of the flag word will be set. ISTPA This routine is used to begin the actual collection of performance analysis data. The INITPA routine must have been executed to set up parameters about the performance analysis before this routine is called. The calling sequences are as follows: CALL ISTPA [ IERR ] or IERR = ISTPA () where: IERR is negative or the following: 0 performance analysis has not been initialized. The following example initializes for and starts a performance analysis. The program is halted if the error condition is returned from the call to ISTPA. CALL INITPA ( "2000,"5400,"100,0 ) IERR = ISTPA () IF ( IERR .EQ. 0 ) STOP . . ISTPRV This routine is used to set the priority value for the current job. The calling sequence is as follows: CALL ISTPRV ( IPRVAL ) where: IPRVAL is an integer priority value in the range of 0 through 127. If the job attempts to set its priority level above its maximum allowed priority level, its priority level will be set to the maximum value allowed. ISVST This routine is used to save the status of a shared file. The effect of this routine is to suspend the connection between the shared file table and the I/O channel. Any blocks that are locked in the file remain locked until the channel is reopened to the file by using the SYSLIB routine, IREOPN. After return from this routine the channel may be freed by using the SYSLIB routine, PURGE. The calling sequence is as follows: TSXLIB V6.40a PAGE 71 Routine Descriptions CALL ISVST ( ICHAN ) where: ICHAN is the I/O channel number open to the shared file. The RLOCK privilege (IPRIV 2/9) is required to execute this routine. When using a single channel number to access several shared files it is for each file convenient to initially open the file, declare the file to be shared and to save the status of the file with the SYSLIB routine, ISAVES. The channel being used to access the set of files can then be switched from one file to another with the SYSLIB routines, PURGE and IREOPN. However, before doing the PURGE, TSX-Plus must be told that you wish to save the shared file status of the file (otherwise all locked blocks will be unlocked and the file will be removed from the shared file list). The following example opens a file, declares it to be shared and then saves the status of the file for TSX-Plus. OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'DK:SOME.FIL', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 30 * ) ICHAN = ILUN ( 30 ) CALL IDCLSF ( ICHAN,4 ) . . CALL ISVST ( ICHAN ) . . ISWESP This routine is used to switch terminal control to an existing subprocess. The calling sequence is as follows: CALL ISWESP ( ISPN,0,0,0,IRET [ ,IERR ] ) where: ISPN indicates the subprocess number and is analogous to the digit typed after CTRL-W when manually switching between subprocesses. The value must be in the range of zero to MAXSEC, a TSGEN parameter. IRET if ISPN is too large, the TSGEN parameter, TSXLIB V6.40a PAGE 72 Routine Descriptions MAXSEC, is returned. IERR is negative or one of the following: 1 the job does not have SUBPROCESS (IPRIV 2/11) privilege. 2 the specified subprocess number is too large. 6 the specified subprocess has not been initiated. ITCRTN This routine is used to trigger a completion routine from within an interrupt service routine. The calling sequence is as follows: CALL ITCRTN ( CPLRTN,IPRI,ID,0 ) where: CPLRTN is the six ASCII character name of the completion routine. IPRI is the execution priority for the completion routine in the range of zero to seven. ID is an integer value passed to the completion routine. The service routine that calls this ITCRTN must have been connected to an interrupt vector by executing the ICNRTN routine. The "0" argument is required. The following example declares the completion routine as an external and then triggers its execution. EXTERNAL CPLRTN CALL ITCRTN ( CPLRTN,IPRI,ID,IZERO ) . . ITRAP This routine is used to fast map to a defined region in a shared runtime system. The calling sequences are as follows: CALL ITRAP ( IRGN [ ,IERR ] ) or IERR = ITRAP ( IRGN ) where: IRGN is the index number of the region to be mapped. TSXLIB V6.40a PAGE 73 Routine Descriptions IERR is negative or the following: 0 the specified region number was invalid. See the example with the IDFRGN routine. ITRCTL This routine is used to perform all of the terminal control functions that can be performed using the "lead-in" character method. The calling sequence is as follows: CALL ITRCTL ( IFUN,IARG ) where: IFUN is an integer value that corresponds to the ASCII code for the desired function in the ranges of 65 through 70 (A-F) and 72 through 90 (H-Z). IARG is zero or an integer value as required by some functions. The following example declares the slash character (/) to be an activation character. DATA IFUN,IARG /"000104,"000057/ . . CALL ITRCTL ( IFUN,IARG ) . . ITRERR This routine is used to determine if any terminal input errors have occurred. The calling sequences are as follows: CALL ITRERR ( IERR ) or IERR = ITRERR () where: IERR is one of the following: 0 no errors have occurred. 1 an input error has occurred. The following example checks for terminal input errors and aborts the program if one has occurred. . . IERR = ITRERR () TSXLIB V6.40a PAGE 74 Routine Descriptions IF ( IERR .NE. 0 ) STOP . . ITRTYP This routine is used to determine the terminal type being used on the time sharing line. The calling sequences are as follows: CALL ITRTYP ( IRET ) or IRET = ITRTYP () where: IRET is one of the following: 0 terminal type unknown. 1 VT52. 2 VT100. 3 Hazeltine. 4 ADM3A. 5 LA36. 6 LA120. 7 Diablo and Qume. 9 VT200. ITRYEL This routine is used to try to override the SET TT GAG command. The calling sequences are as follows: CALL ITRYEL ( ILINE,CHRSTR [ ,IERR ] ) or IERR = ITRYEL ( ILINE,CHRSTR ) where: ILINE is the number of the line to which the message is to be sent. CHRSTR is the name of the buffer that contains the message. The message must be terminated with a null character. IERR is negative or one of the following: 0 the job does not have SEND (IPRIV 1/5) TSXLIB V6.40a PAGE 75 Routine Descriptions privilege. 2 no free message buffers are available. If the job does not have OPER (IPRIV 1/8) privilege, the GAG override is ignored and the routine operates the same as the ITRYMS routine. The following example proceeds if no error condition is encountered. IERR = ITRYEL ( ILINE,CHRSTR ) IF ( IERR .EQ. -1 ) GO TO 100 . . 100 CONTINUE . . ITRYMS This routine tries to send a message to the terminal on another line. The calling sequences are as follows: CALL ITRYMS ( ILINE,CHRSTR [ ,IERR ] ) or IERR = ITRYMS ( ILINE,CHRSTR ) where: ILINE is the number of the line to which the message is to be sent. CHRSTR is the name of the buffer that contains the message. The message must be terminated with a null character. IERR is negative or one of the following: 0 the job does not have SEND (IPRIV 1/5) privilege. 1 the line has SET TT GAG and is executing a program. 2 no free message buffers are available. The following example aborts if any of the error conditions prevail. CALL ITRYMS ( ILINE,CHRSTR,IERR ) IF ( IERR .GE. 0 ) STOP . . TSXLIB V6.40a PAGE 76 Routine Descriptions ITRYSP This routine is used to try to initialize a subprocess. The calling sequence is as follows: CALL ITRYSP ( ISPN,IRPN,INITO,CMDFIL,IRET [ ,IERR ] ) where: ISPN indicates the subprocess number and is analogous to the digit typed after CTRL-W when manually switching between subprocesses. The value must be in the range of zero to MAXSEC, a TSGEN parameter. IRPN indicates which process to return to when the process initiated by this routine terminates as follows: 0 specifies return to the primary process. 1 specifies return to the process which is executing this routine to initiate the subprocess. INITO controls whether the terminal connection is switched to the subprocess as shown below: 0 the subprocess is initiated (if it has not already been initiated) and terminal control is switched to the subprocess. 1 the subprocess is initiated but terminal control remains with the current process. CMDFIL is the name of the string variable containing the file specification of a command file to be executed when the subprocess is initiated. This command file executes without start-up privilege following any other start-up command file specified with the SET SUBPROCESS/FILE command. If the variable is empty, no command file is executed. IRET if ISPN is too large, the TSGEN parameter, MAXSEC, is returned. IERR is negative or one of the following: 1 the job does not have SUBPROCESS (IPRIV 2/11) privilege. 2 the specified subprocess number is too large. 3 all of the job's subprocesses are already active. TSXLIB V6.40a PAGE 77 Routine Descriptions 4 there is insufficient memory available for the subprocess. 5 the specified subprocess has already been initiated. ITSLIC This routine is used to determine the TSX-Plus license number. The calling sequences are as follows: CALL ITSLIC ( IRET ) or IRET = ITSLIC () where: IRET is the requested TSX-Plus license number or zero if the spooler is not generated into the system. ITSLIN This routine is used to determine the TSX-Plus time sharing line number to which the job is attached. The calling sequences are as follows: CALL ITSLIN ( IRET ) or IRET = ITSLIN () where: IRET is zero if RT-11 is running or the requested line number if TSX-Plus is running. The following example aborts if RT-11 is running or continues if TSX-Plus is running. IRET = ITSLIN () IF ( IRET .EQ. 0 ) STOP . . ITSNAM This routine is used to return the name of the TSX-Plus licensee. The calling sequence is as follows: CALL ITSNAM ( NAMSTR,NAMLEN ) where: NAMSTR is the name of the 46-byte word-aligned buffer that is to receive the string giving the name of the licensee. NAMLEN is the length of the name string returned, or is zero if the buffer is not word-aligned or if the TSXLIB V6.40a PAGE 78 Routine Descriptions spooler is not generated into the system. The following example prints the licensee's name or aborts if an error condition is encountered. LOGICAL*1 NAMSTR(46) CALL ITSNAM ( NAMSTR,NAMLEN ) IF (NAMLEN .EQ. 0) STOP TYPE 10,(NAMSTR(I),I=1,NAMLEN) 10 FORMAT (X,46A1) . . IUALBK This routine is used to unlock all locked blocks in a shared file. The calling sequences are as follows: CALL IUALBK ( ICHAN [ ,IERR ] ) or IERR = IUALBK ( ICHAN ) where: ICHAN is the I/O channel number that is open to a shared file. IERR is negative or one of the following: 0 the job does not have RLOCK privilege (IPRIV 2/9). 1 this channel is not open to a shared file. When this routine is executed all blocks previously locked by the user on the shared file are unlocked. Blocks locked by the user on other files are not released nor are blocks of the same file that are locked by other users. The following example first opens a file, declares it to be shared, locks some blocks, and then unlocks the blocks. The program is stopped if the error condition is returned. OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'DK:FILE.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 40 * ) ICHAN = ILUN ( 40 ) CALL IDCLSF ( ICHAN,1 ) DO 10 IBLK = 4,6 TSXLIB V6.40a PAGE 79 Routine Descriptions CALL LKBLKW ( ICHAN,IBLK ) 10 CONTINUE . . IERR = IUALBK ( ICHAN ) IF ( IERR .NE. 0 ) STOP . . IUNLKM This routine is used to unlock a job from memory. The calling sequences are as follows: CALL IUNLKM The PSWAPM privilege (IPRIV 1/7) is required to execute this routine. The following example first locks itself into memory and then unlocks itself. CALL LKANMY . . CALL IUNLKM . . IUSPBK This routine is used to unlock a specific locked block in a shared file. The calling sequences are as follows: CALL IUSPBK ( ICHAN,IBLOCK [ ,IERR ] ) or IERR = IUSPBK ( ICHAN,IBLOCK ) where: ICHAN is the I/O channel number that is open to the shared file. IBLOCK is the number of the block to be unlocked. IERR is negative or one of the following: 0 the job does not have RLOCK privilege (IPRIV 2/9) or shared file support is not available on the system. 1 the channel is not open to a shared file. The following example opens a file, declares the file to be shared, locks all blocks in the file and then unlocks a specific TSXLIB V6.40a PAGE 80 Routine Descriptions block in the file. The program is stopped if an error condition is returned. OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'DK:THAT.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 30 * ) ICHAN = ILUN ( 30 ) CALL IDCLSF ( ICHAN,2 ) CALL LKBLKW ( ICHAN,-1 ) IERR = IUSPBK ( ICHAN,7 ) IF ( IERR .NE. 0 ) STOP . . IYELL This routine is used to override the SET TT GAG command. The calling sequences are as follows: CALL IYELL ( LINUM,MSGBUF [ ,IERR ] ) or IERR = IYELL ( LINUM,MSGBUF ) where: LINUM is the line number of the terminal to which the message is to be sent. MSGBUF is the name of the buffer that contains the message. IERR is negative or the following: 0 the job does not have SEND (IPRIV 1/5) privilege. The job calling this routine must have SEND (IPRIV 1/5) privilege. If the job calling this routine does not also have OPER (IPRIV 1/8) privilege, the GAG override is ignored and the routine operates the same as the TRMMSG routine. The following example aborts if the job does not have SEND privilege. . . IERR = IYELL ( LINUM,MSGBUF ) IF ( IERR .EQ. O ) STOP . TSXLIB V6.40a PAGE 81 Routine Descriptions . JOBPRI This routine is used to get the priority for a job. The calling sequence is as follows: CALL JOBPRI ( LINUM,IPRI [ ,IERR ] ) where: LINUM is the number if the line whose job priority is to be returned. IPRI is the name of a two-element array, the first element of which will receive the job's priority value in the range of 0 to 127. IERR is negative or one of the following: 0 the line is not currently logged on. 1 an invalid line number was specified. The following example aborts if either error condition prevails. . . DIMENSION IPRI(2) CALL JOBPRI ( LINUM,IPRI,IERR ) IF ( IERR .GE. 0 ) STOP . . KILJOB This routine is used to abort any job. The calling sequences are as follows: CALL KILJOB ( JOBNUM [ ,IERR ] ) or IERR = KILJOB ( JOBNUM ) where: JOBNUM is the number of the job to be killed. IERR is negative or one of the following: 1 invalid job number. 2 Not privileged to kill the named job. Suitable privilege (DETACH 1/12, GROUP 2/13, SAME 2/12, or WORLD 2/14) is required to execute this routine. TSXLIB V6.40a PAGE 82 Routine Descriptions The following example aborts if the job does not have privilege to kill the named job. IERR = KILJOB ( JOBNUM ) IF ( IERR .EQ. 2 ) STOP . . KLDTJB This routine is used to abort a detached job. The calling sequences are as follows: CALL KLDTJB ( JOBNUM [ ,IERR ] ) or IERR = KLDTJB ( JOBNUM ) where: JOBNUM is the job number of the detached job. IERR is negative or one of the following: 1 invalid job number. 2 not privileged to kill the named detached job. The DETACH privilege (IPRIV 1/12) is required to execute this routine. The following example first starts a detached job and then later kills the detached job. If an error condition is returned the program is halted. CALL STDTJB ( JOBNAM,JOBNUM ) . . CALL KLDTJB ( JOBNUM,IERR ) IF ( IERR .EQ. 1 ) STOP . . LKANMY This routine is used to lock a job into any memory. It causes the job to become locked into the memory space it is occupying when this routine is executed. This routine executes extremely fast as compared to the routine, LKLOMY, described later. CALL LKANMY [ IERR ] or IERR = LKANMY () TSXLIB V6.40a PAGE 83 Routine Descriptions where: IERR is negative or the following: 0 job does not have PSWAPM privilege (IPRIV 1/7). The job remains locked until the program exits or the routine, IUNLKM, is executed. The following example locks the job into the memory space that it currently occupies. The program terminates if the error condition is returned. IERR = LKANMY () IF ( IERR .EQ. 0 ) STOP . . LKBLK This routine is used to try to lock a specific block in a shared file. If the requested block is not available the routine returns immediately with an error code. If the block is available it is locked for the requesting user and no error is reported. The calling sequences are as follows: CALL LKBLK ( ICHAN,IBLOCK [ ,IERR ] ) or IERR = ( ICHAN,IBLOCK ) where: ICHAN is the I/O channel number open to the shared file. IBLOCK is the number of the block to be locked. IERR is negative or one of the following: 0 job does not have RLOCK privilege (IPRIV 2/9) or system does not include shared file support. 1 this channel is not open to a shared file. 2 request is to lock too many blocks in the file. 3 the requested block is locked by another user. The following example opens a file, declares the file to be shared and tries to lock a block in the file. If the block is already locked the program loops back for another try and if an error condition is returned the program halts. OPEN TSXLIB V6.40a PAGE 84 Routine Descriptions * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'DY1:JUNK.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 40 * ) ICHAN = ILUN ( 40 ) CALL IDCLSF ( ICHAN,2 ) 10 CONTINUE IERR = LKBLK ( ICHAN,3 ) IF ( IERR .EQ. 3 ) GO TO 10 IF ( IERR .NE. 0 ) STOP . . LKBLKW This routine is used to wait for a specific block to lock in a shared file. If the requested block is locked by another job, the requesting job will be suspended until the desired block becomes available. The calling sequences are as follows: CALL LKBLKW ( ICHAN,IBLOCK [ ,IERR ] ) or IERR = LKBLKW ( ICHAN,IBLOCK ) where: ICHAN is the I/O channel number open to the shared file. IBLOCK is the number of the block to be locked. IERR is negative or one of the following: 0 job does not have RLOCK privilege (IPRIV 2/9) or system does not include shared file support. 1 this channel is not open to a shared file. 2 request is to lock too many blocks in the file. Other blocks in the file which were previously locked remain locked. A block number of minus one can be used to request that all blocks in the file be locked. If several users request the same block, access will be granted sequentially in the order that the requests are received. The following example opens a file, declares the file to be shared, and locks all of the blocks in the file. If an error condition is returned the program stops. TSXLIB V6.40a PAGE 85 Routine Descriptions OPEN * ( * ACCESS = 'DIRECT', * ASSOCIATEVARIABLE = IREC, * MAXREC = 20, * NAME = 'DK:FILE.DAT', * RECORDSIZE = 256, * TYPE = 'OLD', * UNIT = 40 * ) ICHAN = ILUN ( 40 ) CALL IDCLSF = ( ICHAN,0 ) IERR = LKBLKW ( ICHAN,-1 ) IF ( IERR .NE. 0 ) STOP . . LKLOMY This routine is used to lock a job into low memory. It causes the job to be relocated into low memory and then to become locked there. This type of lock is relatively slow and should be done only if the job is to remain locked for a long period of time. The calling sequences are as follows: CALL LKLOMY ( [ IERR ] ) or IERR = LKLOMY () where: IERR is negative or the following: 0 job does not have PSWAPM privilege (IPRIV 1/7). The job remains locked in memory until the program terminates or until the routine, IUNLKM, is executed. The following example locks the job into low memory aborting if the error condition is returned. IERR = LKLOMY () IF ( IERR .EQ. 0 ) STOP . . MAPRNT This routine is used to map a shareable run time system into a job's region. The run time system must first be associated with the job by executing the IASRNT routine described earlier. The calling sequences are as follows: TSXLIB V6.40a PAGE 86 Routine Descriptions CALL MAPRNT ( IPAR,IOFFST,MAPSIZ [ ,IERR ] ) or IERR = MAPRNT ( IPAR,IOFFST,MAPSIZ ) where: IPAR is a number in the range of zero to seven that indicates the job's page address register (PAR) that is to be used to access the run time system. The PAR number selects the region of virtual memory in the job that will be mapped to the run time system. The following correspondence exists between PAR numbers and virtual octal address regions within the job: 0 000000 - 017777 1 020000 - 037777 2 040000 - 057777 3 060000 - 077777 4 100000 - 117777 5 120000 - 137777 6 140000 - 157777 7 160000 - 177777 IOFFST specifies which portion of the run time system is to be mapped into the PAR region. It specifies the number of the 64-byte block within the run time system where mapping is to begin. This makes it possible to access different sections of a run time system at different times or through different regions. MAPSIZ is the number of 64-byte blocks to be mapped. If this value is larger than can be contained within a single PAR region, multiple PAR regions are automatically mapped as necessary to contain the entire specified section of the run time system. IERR is one of the following: 0 no error. 1 there is no run time system associated with this job. This routine affects the mapping of only the PAR region specified in IPAR and following PARs if the size so requires. It does not affect the mapping of any other PAR regions that may previously have been mapped to a run time system. Thus, a job TSXLIB V6.40a PAGE 87 Routine Descriptions may have different PAR regions mapped to different sections of the same run time system or to different run time systems. Real time programs may map PAR region number seven to the I/O page and map other PAR regions to shared run time systems. The memory size of a job is not affected by the use of the this routine. Mapping a portion of a job's virtual address space to a shared run time system neither increases nor decreases the size of memory occupied by the job. If a job's size is such that a portion of its normal memory is under a PAR region that is mapped to a run time system, that section of its normal memory becomes inaccessible to the job as long as the run time system mapping is in effect but the memory contents are not lost and may be reaccessed by disassociating all run time systems from the job. Any of the PAR regions may be mapped to a run time system including PAR region number seven which is normally not accessible to a job. The following example first uses the SYSLIB routine, IRAD50, to name the run time system, associates the run time system with the job, then maps a PAR region to a section of the run time system, and finally disassociates the run time system from the job. DIMENSION IRNTIM ( 2 ) CALL IRAD50 ( 6,'TSXLIB',IRNTIM ) CALL IASRNT ( IRNTIM ) CALL MAPRNT ( 3,1,4 ) . . CALL IASRNT ( 0 ) . . MEMPOS This routine is used to determine the position of a job in memory for a TSX-Plus line. The calling sequence is as follows: CALL MEMPOS ( LINUM,IPOS [ ,IERR ] ) where: LINUM is the number of the line for which memory position information is returned. IPOS is the 512-word block number of the start of the memory area allocated to the job. This value will be zero if the job is swapped out of memory. IERR is negative or one of the following: 0 line is not currently logged on. TSXLIB V6.40a PAGE 88 Routine Descriptions 2 invalid line number. MEMSET This routine is used to set the amount of memory that will be allocated for the job. The calling sequences are as follows: CALL MEMSET ( IARG [ ,IRET ] ) or IRET = MEMSET ( IARG ) where: IARG is the top memory address requested. IRET is the top memory address allocated. The size allocated to a job reverts to the size specified by the most recent MEMORY keyboard command when the job exits or chains. The following example requests a top memory address of 120000 (octal). The program is halted if the allocation is less than the request. DATA IARG/"120000/ IRET = MEMSET ( IARG ) IF ( IRET .LMT. IARG ) STOP . . MEMUSE This routine is used to return the amount of memory allocated to a TSX-Plus line. The calling sequence is as follows: CALL MEMUSE ( LINUM,MEMSIZ [ ,IERR ] ) where: LINUM is the number of the line about which memory allocation information is returned. MEMSIZ is the amount of memory allocated to the line in 512-word blocks. IERR is negative or one of the following: 0 line is not currently logged on. 2 invalid line number. TSXLIB V6.40a PAGE 89 Routine Descriptions MNTLD This routine is used to mount a logical device (LD). The calling sequences are as follows: CALL MNTLD ( ICHAN,LDNUM,IROFLG,FILPTR [ ,IERR ] ) or IERR = MNTLD ( ICHAN,LDNUM,IROFLG,FILPTR ) where: ICHAN is the number of the I/O channel which must be closed (available) at the time that this routine is called. LDMUM is the LD unit number in the range of zero through seven. IROFLG is the read-only flag and is zero to allow both reads and writes or one to allow reads only to the LD. FILPTR is a four word buffer containing the RAD50 value for the dev:filnam.ext that is to be associated with the LD. IERR is negative or one of the following: 0 the channel provided is already open. 1 an invalid LD unit number was specified. 2 LD support is not generated into this TSX-Plus system. 3 the LD unit is already associated with a file. 4 an invalid file specification was given. 5 invalid LD unit number nesting. 6 unable to open the specified file. The following example selects a channel number and aborts if either the channel number is greater than 15 or if the LD unit is already associated with a file. . . ICHAN = IGETC () 100 CONTINUE ICHAN = ICHAN + 1 IF ( ICHAN .GT. 15) STOP IERR = MNTLD ( ICHAN,LDNUM,IROFLG,FILPTR ) IF ( IERR .EQ. 0 ) GO TO 100 IF ( IERR .EQ. 3 ) STOP TSXLIB V6.40a PAGE 90 Routine Descriptions . . MOUNT This routine is used to mount a file structured device for directory caching. The effect of this routine is the same as the TSX-Plus MOUNT keyboard command. The calling sequences are as follows: CALL MOUNT ( IDVNAM [ ,IERR ] ) or IERR = MOUNT ( IDVNAM ) where: IDVNAM is the RAD50 value of the device name. IERR is one of the following: 0 no error. 1 no room left in the table of mounted devices. The following example uses the SYSLIB routine, IRAD50, to convert the ASCII device name, DY3, to its RAD50 value. Then the file structured device is mounted. The program is halted if an error condition is returned. CALL IRAD50 ( 3,'DY3',IDVNAM ) IERR = MOUNT ( IDVNAM ) IF ( IERR .EQ. 1 ) STOP . . MPIOPS This routine is used to map the I/O page into the program space between the octal addresses of 160000 and 177777. The calling sequences are as follows: CALL MPIOPS ( [ IERR ] ) or IERR = MPIOPS where: IERR is negative or the following: 0 the job does not have MEMMAP privilege (IPRIV 1/10) or the system does not include real time support. The mapping set up by this routine remains in effect until the routine, MPRMPS, is executed or the program terminates. TSXLIB V6.40a PAGE 91 Routine Descriptions MPRGN This routine is used to map a region of virtual memory to a specified region of physical memory. The calling sequences are as follows: CALL MPRGN ( IPAR,IPAD,ISIZ,IACS,ICBF [ ,IERR ] ) or IERR = MPRGN ( IPAR,IPAD,ISIZ,IACS,ICBF ) where: IPAR is one of the following Page Address Register (PAR) numbers indicating the beginning of the virtual region to be mapped: PAR Virtual Region 0 000000-017777 1 020000-037777 2 040000-057777 3 060000-077777 4 100000-177777 5 120000-137777 6 140000-157777 7 160000-177777 IPAD is the physical address divided by 100 (octal) to which the virtual address is to be mapped. ISIZ is the number of 100-byte (octal) pages to be mapped. If zero all PAR mapping is restored to normal. IACS indicates the read/write access of the mapped region as follows: 0 read only. 1 read and write. ICBF is a cache bypass flag and may have either of the following values: 0 cache is enabled. 1 cache is disabled. IERR is negative or the following: TSXLIB V6.40a PAGE 92 Routine Descriptions 0 real time support is not available or this job does not have MEMMAP privilege (IPRIV 1/10). MPRMPS This routine is used to map a simulated RMON into the program space between the octal addresses of 160000 and 177777. The calling sequences are as follows: CALL MPRMPS ( [ IERR ] ) or IERR = MPRMPS where: IERR is negative or the following: 0 the job does not have MEMMAP privilege (IPRIV 1/10) or the system does not include real time support. MSGREQ This routine is used to post a read request for a TSX-Plus interjob message. The calling sequences are as follows: CALL MSGREQ ( CHNL,BUFR,ISIZ,CPLRTN [ ,IERR ] ) or IERR = MSGREQ ( CNLI,BUFR,ISIZ,CPLRTN ) where: CHNL is the name of the string array containing the six character name of the message channel. BUFR is the name of the string array that is to receive the message. ISIZ is the length of the message buffer. CPLRTN is the name of the completion routine to be entered when the message is received. IERR is negative or as follows: 0 job does not have MESSAGE privilege (IPRIV 2/10) or system does not have message channel support. 1 all message channels are busy. 4 message was longer than the receiving buffer. 5 the maximum allowed number of requests are active. TSXLIB V6.40a PAGE 93 Routine Descriptions On entry to the completion routine, processor register R0 contains the number of bytes in the message that was received, and R1 contains the number of the job that sent the message. The GETREG routine may be used to recover the values stored in R0 and R1. Another call to this routine may be made from within the completion routine if it is desired to receive additional messages. The SUSPND and RESUME SYSLIB calls may be used with this facility if the program reaches a point where it must suspend its execution until a message arrives. The following sample program aborts if an error condition is returned after attempting to post a read request for a message. It later issues a SUSPND call. The associated completion routine must issue a RESUME call after processing the message. LOGICAL*1 CHNL(6),BUFR(75) DATA ISIZ /75/ EXTERNAL CPLRTN CALL SCOPY ( 'CHNL04',CHNL,6 ) . . IERR = MSGREQ ( CHNL,BUFR,ISIZ,CPLRTN ) IF ( IERR .GT. 0 ) STOP . . CALL SUSPND . . MSGSND This routine is used to queue up a message to another job on a named channel. If other messages are already pending on the channel, the new message is added to the end of the list of waiting messages. The sending program continues execution and does not wait for the message to be accepted by a receiving program. During processing the message is copied to an internal buffer, and the sending program is free to destroy its message on return from this routine. The calling sequences are as follows: CALL MSGSND ( ICHNAM,MSGBUF,MSGSIZ [ ,IERR ] ) or IERR = MSGSND ( ICHNAM,MSGBUF,MSGSIZ ) where: ICHNAM is the six ASCII character name of the message channel. MSGBUF is the name of the string array containing the message. TSXLIB V6.40a PAGE 94 Routine Descriptions MSGSIZ is the length of the message in characters. IERR is negative or one of the following: 0 job does not have MESSAGE privilege (IPRIV 2/10) or the system does not include message channel support. 1 all message channels are busy. 2 the maximum allowed number of messages are being held in the message queues. 4 the transmitted message was too long and was truncated to the maximum allowed length. 5 maximum number of message requests are already pending. The following example uses the SYSLIB routine, SCOPY, to load the string variables, MSGBUF and ICHNAM, then sends a message to the named channel, JUNK. The program aborts if an error condition is returned. LOGICAL*1 MSGBUF ( 14 ) LOGICAL*1 ICHNAM ( 8 ) CALL SCOPY ( ' HELLO THERE',MSGBUF,12 ) CALL SCOPY ( 'JUNK ',ICHNAM,6 ) IERR = MSGSND ( ICHNAM,MSGBUF,12 ) IF ( IERR .NE. 0 ) STOP . . NONINT This routine is used to schedule the running job as either an interactive job or as a non-interactive job. The calling sequence is as follows: CALL NONINT ( MODE ) where: MODE is either one of the following two values: 0 causes the job to be scheduled as non-interactive. 1 causes the job to be scheduled as interactive. Programs that do a large amount of terminal input, but that are not truly interactive jobs in the usual sense, such as file transfer programs, should use this routine to avoid excessive interference with normal interactive time sharing jobs. TSXLIB V6.40a PAGE 95 Routine Descriptions The following example first schedules the job to be non-interactive and then interactive. MODE = 0 CALL NONINT ( MODE ) . . MODE = 1 CALL NONINT ( MODE ) . . RCVMSG This routine is used to receive a message from a named channel if a message is pending on the channel. If no message is pending, an error code is returned, and the calling program is allowed to continue execution. The calling sequence is as follows: CALL RCVMSG ( ICHNAM,MSGBUF,IBUFSZ,MSGSIZ [ ,IERR ] ) where: ICHNAM is the six ASCII character name of the message channel. MSGBUF is the name of the receiving string array. IBUFSZ is the length of the receiving buffer in characters. MSGSIZ is the length of the received message in characters. IERR is negative or one of the following: 0 job does not have MESSAGE privilege (IPRIV 2/10) or the system does not include message channel support. 1 all message channels are busy. 3 no message was queued on the named channel. 4 the message was longer than the receiving buffer. 5 maximum number of message requests are pending. The following example sets up using the SYSLIB routine, SCOPY, to receive a message, and then attempts to receive a message on the named channel, JUNK. The program is stopped if an error condition is returned. TSXLIB V6.40a PAGE 96 Routine Descriptions LOGICAL*1 ICHNAM ( 8 ) LOGICAL*1 MSGBUF ( 72 ) CALL SCOPY ( 'JUNK ',ICHNAM,6) CALL RCVMSG ( ICHNAM,MSGBUF,72,MSGSIZ,IERR) IF ( IERR .NE. 0 ) STOP . . RCVMSW This routine is used to suspend the execution of a program until a message becomes available on a named channel. The calling sequence is as follows: CALL RCVMSW ( ICHNAM,MSGBUF,IBUFSZ,MSGSIZ [ ,IERR ] ) where: ICHNAM is the six ASCII character name of the message channel. MSGBUF is the name of the receiving string array. IBUFSZ is the length of the receiving array in characters. MSGSIZ is the length of the received message in characters. IERR is negative or one of the following: 0 job does not have MESSAGE privilege (IPRIV 2/10) or the system does not include message channel support. 1 all message channels are busy. 4 the message was longer than the receiving buffer. 5 maximum number of message requests pending. The following example uses the SYSLIB routine, SCOPY, to load the variable, ICHNAM, then waits for a message to arrive on the named channel. The program is stopped if an error condition is returned. LOGICAL*1 MSGBUF ( 72 ) LOGICAL*1 ICHNAM ( 8 ) CALL SCOPY ( 'JUNK ',ICHNAM,6 ) CALL RCVMSW ( ICHNAM,MSGBUF,IBUFSZ,MSGSIZ,IERR) IF ( IERR .NE. 0 ) STOP . . TSXLIB V6.40a PAGE 97 Routine Descriptions RLCTL This routine is used to allow a running program to relinquish exclusive control of the system after the program finishes performing some time-critical task. The calling sequence is as follows: CALL RLCTL REALTIME privilege (IPRIV 1/6) is required to execute this routine. RSTODT This routine is used to reset or clear the ODT activation mode. The calling sequence is as follows: CALL RSTODT SETODT This routine is used to set the ODT activation mode. The calling sequence is as follows: CALL SETODT In this mode TSX-Plus considers all characters to be activation characters except the digits, the comma, the dollar sign, and the semicolon. STDTJB This routine is used to start the execution of a detached job. The calling sequence is as follows: CALL STDTJB ( JOBNAM,JOBNUM [ ,IERR ] ) where: JOBNAM is the ASCII string, dev:filnam.ext, terminated by a null byte. JOBNUM is the returned job number. IERR is negative or the following: 1 no detached job line is available. The DETACH privilege (IPRIV 1/12) is required to execute this routine. If a free detached job line is available, the specified command file, JOBNAM, is initiated as a detached job and the number of the detached job is returned in the variable, JOBNUM. TSXLIB V6.40a PAGE 98 Routine Descriptions The following example uses the SYSLIB routine, SCOPY, to load the variable, JOBNAM, then initiates the detached job, DETJOB.COM, from device, DY2:, storing the job number in the variable, JOBNUM. The program is terminated if an error condition is returned. LOGICAL*1 JOBNAM ( 16 ) CALL SCOPY ( 'DY2:DETJOB.COM',JOBNAM,14) CALL STDTJB ( JOBNAM,JOBNUM,IERR ) IF ( IERR .EQ. 1 ) STOP . . STPRLV This routine is used to set the user mode processor priority level from a running program. This may be used when it is necessary for a real time program to block interrupts for a short period of time while it is performing some time critical operation. The calling sequence is as follows: CALL STPRLV ( IPRLVL ) where: IPRLVL is the desired user mode processor priority level in the range of zero through seven. REALTIME privilege (IPRIV 1/6) is required to execute this routine. Interrupts should not be disabled for long periods of time or system clock interrupts and character input interrupts will be lost. The following example raises the priority level to seven and later reduces it back to zero. CALL STPRLV ( 7 ) . . CALL STPRLV ( 0 ) . . STUNAM This routine is used to set the user name associated with the current job. The calling sequences are as follows: CALL STUNAM ( USRNAM [ , IERR ] ) or IERR = STUNAM ( USRNAM ) where: USRNAM is the name of the twelve-character array that contains the new user name ASCII string. IERR is negative or as follows: TSXLIB V6.40a PAGE 99 Routine Descriptions 0 the job does not have SETNAME privilege (IPRIV 1/4). The following example sets the user name to JOEBLOWHARD. INTEGER*2 STUNAM LOGICAL*1 USRNAM(14) CALL SCOPY ( 'JOEBLOWHARD',USRNAM ) IERR = STUNAM ( USRNAM ) IF ( IERR .GE. 0 ) STOP . . NOTE When STUNAM is called as a function, it must first be declared as INTEGER*2. TERMPA This routine is used to conclude a performance analysis. It has the effect of returning into a user supplied buffer the results of the analysis and freeing the performance analysis feature for use by other users. The calling sequence is as follows: CALL TERMPS ( IPARBF,IHSTBF,IHBSIZ [ ,IERR ] ) where: IPARBF is the name of a four element parameter buffer with the elements assigned as follows: 1 is the base address of the monitored region. 2 is the top address of the monitored region. 3 is the number of bytes per histogram cell. 4 is a control and status flag with bit assignments as follows: 1 I/O wait time was included. 100000 at least one of the histogram cells overflowed. IHSTBF is the name of the histogram buffer. IHBSIZ is the number of elements or cells in the histogram buffer. IERR is negative or one of the following: TSXLIB V6.40a PAGE 100 Routine Descriptions 0 this job is not doing a performance analysis. 1 area provided for the histogram count vector is too small. The histogram data returned consists of a vector of 16-bit binary values, one value for each cell in the histogram. The first value corresponds to the histogram cell that starts at the base address of the region that was monitored. The following example shows the complete performance analysis from initialization to termination. The program is stopped if an error condition is returned on termination of the analysis. DIMENSION IPARBF ( 4 ) DIMENSION IHSTBF ( 16 ) CALL INITPA ( "2000,"4000,"100,0 ) CALL ISTPA . . CALL ISPPA CALL TERMPA ( IPARBF,IHSTBF,IHBSIZ,IERR ) IF ( IERR .GE. 0 ) STOP . . TIMOUT This routine is used to set the time out value that is to be applied to the next terminal input operation. The calling sequence is as follows: CALL TIMOUT ( ITIME,IACTCH ) where: ITIME is the time out value in 0.5 second units. IACTCH is the value of the single character that is to be returned as the last or activation character of the field if a time out occurs. The value specified with this routine applies only to the next terminal input field. The time value is reset when the next field is received from the terminal or the time out occurs. A new time out value must be specified for each input field that is to be time controlled. The following example uses a time out value of twenty seconds and specifies that a control-X is to be returned if the timeout occurs. . . TSXLIB V6.40a PAGE 101 Routine Descriptions CALL TIMOUT ( 40,24 ) . . TKCTL This routine is used to allow a running program to gain exclusive access to the system to perform some time-critical task. The calling sequence is as follows: CALL TKCTL The effect of this routine is to cause the TSX-Plus job scheduler to ignore all other jobs during the interval that the calling program has exclusive control of the system. REALTIME privilege (IPRIV 1/6) is required to execute this routine. Exclusive access is relinquished when the calling program calls RLCTL, terminates, or aborts. Exclusive access is retained if the calling program chains to another program. TRMIN This routine is used to accept a string of characters from the terminal. The calling sequence is as follows: CALL TRMIN ( ICHBUF,IBFSIZ,ICOUNT [ ,IERR ] ) where: ICHBUF is the name of the buffer that is to receive the string. IBFSIZ is the length of the receiving buffer in characters. ICOUNT is the number of characters actually received. IERR is one of the following: 0 no error. 1 the specified buffer overflowed. This routine causes a program to wait until an activation character is entered on the terminal and then returns all characters received up to and including the last activation character. This routine is substancially more efficient than doing a series of the SYSLIB routin= ITTINR. It is particularly well suited for accepting input from page buffered terminals. The following example accepts a string of characters from the terminal. The program is halted if the error condition is returned. TSXLIB V6.40a PAGE 102 Routine Descriptions LOGICAL*1 ICHBUF ( 24 ) CALL TRMIN ( ICHBUF,24,ICOUNT,IERR ) IF ( IERR .EQ. 1 ) STOP . . TRMMSG This routine is used to send a message to another line's terminal. The calling sequences are as follows: CALL TRMMSG ( ILINE,IMSGBF [ ,IERR ] ) or IERR = TRMMSG ( ILINE,IMSGBF ) where: ILINE is the line number of the terminal that the message is to be sent. IMSGBF is the name of the buffer that contains the message. IERR is negative or one of the following: 0 job does not have SEND privilege (IPRIV 1/5). 1 receiving line is SET TT GAG. The message must be terminated with a null character. The following example sends a message to the terminal connected to line 14. If the job does not have SEND privilege, the program aborts. If the receiving line is SET TT GAG, the program loops until the condition changes to NOGAG. LOGICAL*1 IMSGBF ( 30 ) CALL SCOPY ( ' THIS IS THE MESSAGE',IMSGBF,20 ) 100 CONTINUE CALL TRMMSG ( 14,IMSGBF,IERR ) IF ( IERR .EQ. 0 ) STOP IF ( IERR .EQ. 1 ) GO TO 100 . . NOTE If TRMMSG is called as a function, it must first be declared as INTEGER*2. TSXLIB V6.40a PAGE 103 Routine Descriptions TRMOUT This routine is used to send a string of characters to the terminal. The calling sequence is as follows: CALL TRMOUT ( ICHSTR,ICOUNT ) where: ICHSTR is the name of the buffer containing the string of characters. ICOUNT is the number of characters in the string. This routine is much more efficient to use than a series of the SYSLIB routine, ITTOUR. It has the same efficiency as the SYSLIB routine, PRINT, but it uses a count of the number of characters to send instead of having the string terminated with a null character. The following example sends a string of characters to the terminal. LOGICAL*1 ICHSTR ( 22 ) CALL SCOPY ( ' THIS IS THE STRING.'ICHSTR,20 ) CALL TRMOUT ( ICHSTR,20 ) . . TTCRTN This routine is used to establish a completion routine which will be executed as each input character is received from the terminal. The calling sequence is as follows: CALL TTCRTN ( CPLRTN ) where: CPLRTN is the name of the completion routine that is to be entered for each input character. On entry to the completion routine, the received character is in R0. The EMT to connect the completion routine must be reexecuted each time a character is received. This should be done at the end of the completion routine after processing the last received character. The program should be running with single character activation and with bit 12 set in the job status word. The following example sets up for and calls a terminal input completion routine. A skeleton of the completion routine is also given. EXTERNAL CPLRTN CALL IPOKE ( "44,"10000 ) CALL TTCRTN ( CPLRTN ) . TSXLIB V6.40a PAGE 104 Routine Descriptions . SUBROUTINE CPLRTN . . CALL TTCRTN ( CPLRTN ) RETURN TSXLIB V6.40a PAGE 105 Building the Library 4. Building the Library The sources for the TSX-Plus Library consist of the MACRO-11 modules listed in Table 4-1. The process of constructing the library file, TSXLIB.OBJ, is the same when accomplished under either RT-11 or under TSX-Plus. Module Content CLLINE Communication line support. DETJBS Detached job support. DVALOC Device allocating and deallocating. JBPRIV Job priveleges control. JBSTMN Job status monitoring. MNTDEV Device mounting and dismounting. MSGCOM Interjob message communication. PRFANL Performance analysis support. RELTIM Real time program support. RUNTIM Shared run time system support. SHRFIL Shared file system support. SPOLER Spooler support. SUBPRO Subprocess control. SYSTAT System status information. TRMCOM Terminal communication. TRMCTL Terminal control. TSFILS Special file information. TSLBID TSXLIB identification. TSXMSC Miscellaneous EMTs. TSXODT ODT activation mode support. USRNAM User name support. WINDOW Windowing support. TSXLIB MACRO-11 source modules. Table 4-1. First the MACRO-11 modules are assembled as follows: .RUN SY:MACRO *CLLINE=CLLINE *DETJBS=DETJBS *JBPRIV=JBPRIV *JBSTMN=JBSTMN *MNTDEV=MNTDEV *MSGCOM=MSGCOM *PRFANL=PRFANL *RELTIM=RELTIM *RUNTIM=RUNTIM *SHRFIL=SHRFIL TSXLIB V6.40a PAGE 106 Building the Library *SPOLER=SPOLER *SUBPRO=SUBPRO *SYSTAT=SYSTAT *TRMCOM=TRMCOM *TRMCTL=TRMCTL *TSFILS=TSFILS *TSLBID=TSLBID *TSXMSC=TSXMSC *TSXODT=TSXODT *USRNAM=USRNAM *WINDOW=WINDOW *^C Next the library file is constructed as follows: .RUN SY:LIBR *TSXLIB=CLLINE// *DETJBS *DVALOC *JBPRIV *JBSTMN *MNTDEV *MSGCOM *PRFANL *RELTIM *RUNTIM *SHRFIL *SPOLER *SUBPRO *SYSTAT *TRMCOM *TRMCTL *TSFILS *TSLBID *TSXMSC *TSXODT *USRNAM *WINDOW *// *^C The command file, TSXLIB.COM, in the distribution kit will accomplish the construction of the library file, TSXLIB.OBJ. TSXLIB V6.40a PAGE 107 References References 1. S & H Computer Systems, Inc., "TSX-Plus Programmer's Reference Manual", Sixth Edition, First Printing, Nashville, TN, January 1988. 2. S & H Computer Systems, Inc., "TSX-Plus Version 6.3 Release Notes", Nashville, TN, December 1987. 3. Digital Equipment Corporation, "PDP-11 MACRO-11 Language Reference Manual", AA-V027A-TC, Maynard, MA, March 1983. 4. Digital Equipment Corporation, "RT-11 System User's Guide", AA-5279C-TC, Maynard, MA, March 1983. 5. Digital Equipment Corporation, "RT-11 Programmer's Reference Manual", AA-H378B-TC, Maynard, MA, March 1983. 6. Digital Equipment Corporation, "PDP-11 FORTRAN IV Language Reference Manual", AA-R953A-TK, Maynard, MA, March 1983. 7. Digital Equipment Corporation, "PDP-11 FORTRAN-77 Language Reference Manual", AA-V193A-TK, Maynard, MA, July 1983. 8. S & H Computer Systems, Inc., "TSX-Plus Version 6.31 Release Notes", Nashville, TN, January 1988. 9. S & H Computer Systems, Inc., "TSX-Plus Version 6.40 Release Notes", Nashville, TN, January 1989. TSXLIB V6.40a PAGE 108 Appendix A: KWIK Index Appendix A: KWIK Index This appendix lists the TSXLIB routines in a key-word-in- context (KWIK) index. It is meant to help the user to locate the particular routine that is needed. IFLINF Obtain some information about file. TRMIN from terminal. Accept string of characters IAQFLC another job. Acquire file context of IACTCH Check for pending activation characters. RSTODT Reset normal activation mode. SETODT Set ODT activation mode. CNVAPA address. Convert virtual address to physical CNVAPA address to physical address. Convert virtual DSMNTA devices. Dismount all file structured IUALBK Unlock all locked blocks. IDMALD Dismount all logical devices. IALOC Allocate device. ICALOC device. Check allocation status of MEMSET Set memory allocation. MEMUSE job. Determine amount of memory used by INITPA for performance analysis. Initialize ISTPA Start performance analysis. ISPPA Stop performance analysis. TERMPA from performance analysis. Terminate IASRNT system, job. [Dis] Associate shared run time GTUNAM job. Get user name associated with current STUNAM job. Set user name associated with current IDCLSF Declare file to be shared. IPGNAM Get name of program being run by job. IBICIO page. Bit clear value in I/O IBISIO Bit set value in I/O page. LKBLKW Wait for block to lock. LKBLK Try to lock block. IUSPBK Unlock specific block. ISPBLK Determine number of free blocks in spool file. ISPUSE Determine number of blocks used in spool file. IUALBK Unlock all locked blocks. BRKCTL Establish break sentinel control. IBSTCH change. Broadcast job status ICNMCN monitoring connection. Cancell job status ISPFLC Control centering of flag page. CHPGN Change program name. IPRIV Determine, change privileges for job. IBSTCH Broadcast job status change. ITRCTL functions. Lead-in character terminal control TRMIN Accept string of characters from terminal. TRMOUT Send string of characters to terminal. IACTCH for pending activation characters. Check IGNPIC number of pending input characters. Get TSXLIB V6.40a PAGE 109 Appendix A: KWIK Index ICALOC device. Check allocation status of IACTCH activation characters. Check for pending ITRERR errors. Check for terminal input ICKWTS file. Check for writes to shared ILNSTS Check status of line. ISTLD logical device. Check the status of a ICLXF Clear another job's CL XOFF condition. ICNTSP Control speed of CL line. ICLRST Reset another job's CL unit. ICLXF condition. Clear another job's CL XOFF CLRGNS for fast map. Clear region definitions IBICIO Bit clear value in I/O page. IRDRCL timesharing line.Redirect communication or ITCRTN routine. Trigger completion from interrupt ICNINT Connect interrupt vector completion routine. TTCRTN Establish terminal completion routine. ICLXF another job's CL XOFF condition. Clear ICNINT completion routine. Connect interrupt vector ICNRTN interrupt vector. Connect service routine to ICONTM Determine connect time for job. ICNMCN job status monitoring connection. Cancell IESMCN job status monitoring connection. Establish IRLINT an interrupt vector connection. Release IPRWND Print the contents of a window. IAQFLC Acquire file context of another job. ISPFLC page. Control centering of flag ISPFLP spooled file. Control flag page of ISPCTL spooled file. Control release time of ICNTSP Control speed of CL line. ITRCTL character terminal control functions. Lead-in RLCTL Relinquish exclusive control of system. TKCTL Take exclusive control of system. BRKCTL Establish break sentinel control. CNVAPA physical address. Convert virtual address to ICPUTM Get CPU time used by job. ICRWND Create a window. ISTFTM Set creation time of file. ISTPRV Set current job priority value. GTUNAM name associated with current job. Get user STUNAM name associated with current job. Set user IDALOC Deallocate device. IDCLSF Declare file to be shared. IDFRGN map. Define a region for fast CLRGNS Clear region definitions for fast map. IDLWND Delete a window. ISTDJ Get status of detached job. KLDTJB Kill detached job. STDTJB Start detached job. ITSLIC number. Determine TSX-Plus license ITSNAM name. Determine TSX-Plus licensee ITSLIN number. Determine TSX-Plus line MEMUSE used by job. Determine amount of memory ICONTM job. Determine connect time for ISPUSE used in spool file. Determine number of blocks ISPBLK blocks in spool file. Determine number of free TSXLIB V6.40a PAGE 110 Appendix A: KWIK Index MEMPOS in memory. Determine position of job IPRPAN parent job numbers. Determine primary and ITRTYP Determine terminal type. IPRIV privileges for job. Determine, change IALOC Allocate device. ICALOC allocation status of device. Check ISTLD the status of a logical device. Check IDALOC Deallocate device. DISMNT a file structured device. Dismount IDMLD Dismount a logical device. MNTLD Mount a logical device. MOUNT Mount file structured device. DSMNTA all file structured devices. Dismount IDMALD Dismount all logical devices. IASRNT time system, job. [Dis] Associate shared run DISMNT device. Dismount a file structured IDMLD Dismount a logical device. DSMNTA structured devices. Dismount all file IDMALD devices. Dismount all logical ILDTR Lower a line's DTR status. IRDTR Raise a line's DTR status. HIEFOF Turn off high efficiency terminal mode. HIEFON Turn on high efficiency terminal mode. ITRERR Check for terminal input errors. BRKCTL control. Establish break sentinel IESMCN monitoring connection. Establish job status TTCRTN completion routine. Establish terminal RLCTL system. Relinquish exclusive control of TKCTL system. Take exclusive control of IEXSTS Get job execution status. INITSP new, switch to existing subprocesInitialize ISWESP Switch to an existing subprocess. CLRGNS region definitions for fast map. Clear IDFRGN Define a region for fast map. ITRAP Perform a fast region map. IAQFLC job. Acquire file context of another DISMNT Dismount a file structured device. MOUNT Mount file structured device. DSMNTA Dismount all file structured devices. IDCLSF Declare file to be shared. ICKWTS for writes to shared file. Check ISPFLP flag page of spooled file. Control ISPCTL release time of spooled file. Control ISPUSE of blocks used in spool file. Determine number ISPBLK of free blocks in spool file. Determine number IFLINF some information about file. Obtain ISVST Save status of shared file. ISTFTM Set creation time of file. ISPFLP Control flag page of spooled file. ISPFLC Control centering of flag page. ISPBLK Determine number of free blocks in spool file. ITRCTL terminal control functions. Lead-in character ICPUTM Get CPU time used by job. ISPLN number. Get a subprocess line IEXSTS Get job execution status. TSXLIB V6.40a PAGE 111 Appendix A: KWIK Index IPGNAM run by job. Get name of program being IGNPIC characters. Get number of pending input GTPGN Get program name. IPPNUM number for job. Get project, programmer ISTDJ Get status of detached job. GTJBNM Get the name for a job. JOBPRI Get the priority for a job. GTUNAM with current job. Get user name associated GETREG processor register. Get value stored a HIEFOF mode. Turn off high efficiency terminal HIEFON mode. Turn on high efficiency terminal MPIOPS space. Map I/O page into program IBICIO Bit clear value in I/O page. IBISIO Bit set value in I/O page. IPEKIO Peek at value in I/O page. IPOKIO Poke value into I/O page. IFLINF Obtain some information about file. INITPA analysis. Initialize for performance INITSP existing subprocess. Initialize new, switch to ITRYSP subprocess. Try to initialize a new IGNPIC Get number of pending input characters. ITRERR Check for terminal input errors. ITCRTN Trigger completion from interrupt routine. ICNINT routine. Connect interrupt vector completion IRLINT connection. Release an interrupt vector ICNRTN service routine to interrupt vector. Connect IEXSTS Get job execution status. IUNLKM Unlock job from memory. MEMPOS Determine position of job in memory. LKANMY Lock job into any memory. LKLOMY Lock job into lowest memory. IPRPAN primary and parent job numbers. Determine ISTPRV Set current job priority value. MAPRNT run time system into job region. Map shared IBSTCH Broadcast job status change. ICNMCN connection. Cancell job status monitoring IESMCN connection. Establish job status monitoring NONINT Set [non]interactive job status. ICLXF Clear another job's CL XOFF condition. ICLRST Reset another job's CL unit. IAQFLC file context of another job. Acquire MEMUSE amount of memory used by job. Determine ICONTM connect time for job. Determine IPRIV change privileges for job. Determine, ICPUTM Get CPU time used by job. IPGNAM of program being run by job. Get name IPPNUM programmer number for job. Get project, ISTDJ Get status of detached job. GTJBNM Get the name for a job. JOBPRI Get the priority for a job. GTUNAM associated with current job. Get user name KILJOB Kill any job. KLDTJB Kill detached job. MSGSND Send message to another job. STUNAM associated with current job. Set user name TSXLIB V6.40a PAGE 112 Appendix A: KWIK Index STDTJB Start detached job. RCVMSG message from another job. Try to receive RCVMSW for message from another job. Wait IASRNT shared run time system, job. [Dis] Associate KILJOB Kill any job. KLDTJB Kill detached job. ITRCTL control functions. Lead-in character terminal STPRLV mode processor priority level. Set user ITSLIC Determine TSX-Plus license number. ITSNAM Determine TSX-Plus licensee name. ITSLIN Determine TSX-Plus line number. ISPLN Get a subprocess line number. ILDTR Lower a line's DTR status. IRDTR Raise a line's DTR status. IRXOFF Reset a line's XOFF status. ILNSTS Check status of line. ICNTSP Control speed of CL line. IRDRCL or timesharing line. Redirect communication LKANMY Lock job into any memory. LKLOMY memory. Lock job into lowest LKBLK Try to lock block. LKBLKW Wait for block to lock. IUALBK Unlock all locked blocks. ISTLD Check the status of a logical device. IDMLD Dismount a logical device. MNTLD Mount a logical device. IDMALD Dismount all logical devices. ILDTR Lower a line's DTR status. LKLOMY Lock job into lowest memory. MPIOPS space. Map I/O page into program MAPRNT into job region. Map shared run time system MPRMPS program space. Map simulated RMON into MPRGN to physical memory. Map virtual memory region CLRGNS definitions for fast map. Clear region IDFRGN Define a region for fast map. ITRAP Perform a fast region map. MEMSET Set memory allocation. MPRGN memory. Map virtual memory region to physical MEMUSE Determine amount of memory used by job. MEMPOS position of job in memory. Determine LKANMY Lock job into any memory. LKLOMY Lock job into lowest memory. MPRGN region to physical memory. Map virtual memory IUNLKM Unlock job from memory. RCVMSG Try to receive message from another job. RCVMSW Wait for message from another job. MSGSND Send message to another job. TRMMSG terminal. Send message to another ITRYMS terminal. Try to send a message to another MSGREQ Post read request for message. STPRLV level. Set user mode processor priority RSTODT Reset normal activation mode. SETODT Set ODT activation mode. HIEFOF high efficiency terminal mode. Turn off HIEFON high efficiency terminal mode. Turn on TSXLIB V6.40a PAGE 113 Appendix A: KWIK Index ICNMCN Cancell job status monitoring connection. IESMCN Establish job status monitoring connection. MNTLD Mount a logical device. MOUNT device. Mount file structured GTUNAM current job. Get user name associated with STUNAM current job. Set user name associated with GTJBNM Get the name for a job. IPGNAM by job. Get name of program being run CHPGN Change program name. ITSNAM TSX-Plus licensee name. Determine GTPGN Get program name. ITRYSP Try to initialize a new subprocess. INITSP subprocess. Initialize new, switch to existing NONINT Set [non]interactive job status. RSTODT Reset normal activation mode. IPPNUM Get project, programmer number for job. ISPUSE spool file. Determine number of blocks used in ISPBLK spool file. Determine number of free blocks in IGNPIC characters. Get number of pending input ITSLIC TSX-Plus license number. Determine ITSLIN Determine TSX-Plus line number. ISPLN Get a subprocess line number. IPRPAN primary and parent job numbers. Determine IFLINF about file. Obtain some information SETODT Set ODT activation mode. HIEFOF terminal mode. Turn off high efficiency ITRYEL to override the TT-GAG option. Try IYELL Override the TT-GAG option. IYELL Override the TT-GAG option. ITRYEL Try to override the TT-GAG option. MPIOPS Map I/O page into program space. ISPFLP Control flag page of spooled file. IBICIO Bit clear value in I/O page. IBISIO Bit set value in I/O page. ISPFLC centering of flag page. Control IPEKIO Peek at value in I/O page. IPOKIO Poke value into I/O page. IPRPAN Determine primary and parent job numbers. IPEKIO Peek at value in I/O page. IACTCH characters. Check for pending activation IGNPIC Get number of pending input characters. ITRAP Perform a fast region map. INITPA Initialize for performance analysis. ISTPA Start performance analysis. ISPPA Stop performance analysis. TERMPA Terminate from performance analysis. CNVAPA virtual address to physical address. Convert MPRGN virtual memory region to physical memory. Map IPOKIO Poke value into I/O page. MEMPOS Determine position of job in memory. MSGREQ message. Post read request for IPRPAN numbers. Determine primary and parent job IPRWND window. Print the contents of a JOBPRI Get the priority for a job. STPRLV Set user mode processor priority level. TSXLIB V6.40a PAGE 114 Appendix A: KWIK Index ISTPRV Set current job priority value. IPRIV Determine, change privileges for job. IRSWND Resume window processing. ISPWND Suspend window processing. STPRLV Set user mode processor priority level. GETREG Get value stored a processor register. IPGNAM Get name of program being run by job. CHPGN Change program name. GTPGN Get program name. MPIOPS Map I/O page into program space. MPRMPS Map simulated RMON into program space. IPPNUM Get project, programmer number for job. IPPNUM for job. Get project, programmer number IRDTR Raise a line's DTR status. MSGREQ Post read request for message. TIMOUT Set terminal read timeout value. RCVMSG another job. Try to receive message from IRDRCL timesharing line. Redirect communication or CLRGNS map. Clear region definitions for fast IDFRGN Define a region for fast map. ITRAP Perform a fast region map. MPRGN Map virtual memory region to physical memory. MAPRNT run time system into job region. Map shared GETREG value stored a processor register. Get IRLINT connection. Release an interrupt vector ISPCTL file. Control release time of spooled RLCTL control of system. Relinquish exclusive MSGREQ Post read request for message. IRXOFF Reset a line's XOFF status. ICLRST unit. Reset another job's CL RSTODT mode. Reset normal activation IRSWND Resume window processing. ISPY simulated RMON. Return values from within MPRMPS Map simulated RMON into program space. ISPY from within simulated RMON. Return values ICNRTN vector. Connect service routine to interrupt ICNINT vector completion routine. Connect interrupt TTCRTN terminal completion routine. Establish ITCRTN from interrupt routine. Trigger completion IPGNAM name of program being run by job. Get MAPRNT region. Map shared run time system into job IASRNT [Dis] Associate shared run time system, job. ISVST Save status of shared file. ISLWND Select a window. MSGSND job. Send message to another TRMMSG terminal. Send message to another TRMOUT to terminal. Send string of characters ITRYMS terminal. Try to send a message to another BRKCTL Establish break sentinel control. ICNRTN interrupt vector. Connect service routine to SETODT Set ODT activation mode. NONINT status. Set [non]interactive job ISTFTM Set creation time of file. ISTPRV value. Set current job priority MEMSET Set memory allocation. TSXLIB V6.40a PAGE 115 Appendix A: KWIK Index TIMOUT value. Set terminal read timeout STPRLV priority level. Set user mode processor STUNAM with current job. Set user name associated IBISIO Bit set value in I/O page. ICKWTS Check for writes to shared file. ISVST Save status of shared file. MAPRNT job region. Map shared run time system into IASRNT job. [Dis] Associate shared run time system, IDCLSF Declare file to be shared. MPRMPS space. Map simulated RMON into program ISPY values from within simulated RMON. Return MPIOPS I/O page into program space. Map MPRMPS RMON into program space. Map simulated IUSPBK Unlock specific block. ICNTSP Control speed of CL line. ISPUSE number of blocks used in spool file. Determine ISPBLK number of free blocks in spool file. Determine ISPFLP Control flag page of spooled file. ISPCTL Control release time of spooled file. STDTJB Start detached job. ISTPA Start performance analysis. IBSTCH Broadcast job status change. ICNMCN connection. Cancell job status monitoring IESMCN connection. Establish job status monitoring ISTLD Check the status of a logical device. ISTDJ Get status of detached job. ICALOC Check allocation status of device. ILNSTS Check status of line. ISVST Save status of shared file. IEXSTS Get job execution status. ILDTR Lower a line's DTR status. IRDTR Raise a line's DTR status. IRXOFF Reset a line's XOFF status. NONINT Set [non]interactive job status. ISPPA Stop performance analysis. GETREG register. Get value stored a processor TRMIN terminal. Accept string of characters from TRMOUT terminal. Send string of characters to DISMNT Dismount a file structured device. MOUNT Mount file structured device. DSMNTA Dismount all file structured devices. ISPLN Get a subprocess line number. INITSP new, switch to existing subprocess. Initialize ISWESP Switch to an existing subprocess. ITRYSP Try to initialize a new subprocess. ISPWND Suspend window processing. ISWESP subprocess. Switch to an existing INITSP subprocessInitialize new, switch to existing MAPRNT Map shared run time system into job region. IASRNT shared run time system, job. [Dis] Associate RLCTL exclusive control of system. Relinquish TKCTL exclusive control of system. Take TKCTL system. Take exclusive control of TTCRTN routine. Establish terminal completion ITRCTL Lead-in character terminal control functions. TSXLIB V6.40a PAGE 116 Appendix A: KWIK Index ITRERR Check for terminal input errors. HIEFOF Turn off high efficiency terminal mode. HIEFON Turn on high efficiency terminal mode. TIMOUT value. Set terminal read timeout ITRTYP Determine terminal type. TRMIN of characters from terminal. Accept string TRMMSG Send message to another terminal. TRMOUT string of characters to terminal. Send ITRYMS a message to another terminal. Try to send TERMPA analysis. Terminate from performance ICONTM Determine connect time for job. ISTFTM Set creation time of file. ISPCTL Control release time of spooled file. MAPRNT region. Map shared run time system into job IASRNT Associate shared run time system, job. [Dis] ICPUTM Get CPU time used by job. TIMOUT Set terminal read timeout value. IRDRCL communication or timesharing line. Redirect ITCRTN interrupt routine. Trigger completion from ITRYSP subprocess. Try to initialize a new LKBLK Try to lock block. ITRYEL option. Try to override the TT-GAG RCVMSG another job. Try to receive message from ITRYMS another terminal. Try to send a message to ITSLIC Determine TSX-Plus license number. ITSNAM Determine TSX-Plus licensee name. ITSLIN Determine TSX-Plus line number. ITRYEL Try to override the TT-GAG option. IYELL Override the TT-GAG option. HIEFOF terminal mode. Turn off high efficiency HIEFON terminal mode. Turn on high efficiency ITRTYP Determine terminal type. ICLRST Reset another job's CL unit. IUALBK Unlock all locked blocks. IUNLKM Unlock job from memory. IUSPBK Unlock specific block. MEMUSE amount of memory used by job. Determine ICPUTM Get CPU time used by job. ISPUSE number of blocks used in spool file.Determine STPRLV priority level. Set user mode processor GTUNAM current job. Get user name associated with STUNAM current job. Set user name associated with IBICIO Bit clear value in I/O page. IBISIO Bit set value in I/O page. IPEKIO Peek at value in I/O page. IPOKIO Poke value into I/O page. GETREG register. Get value stored a processor ISTPRV Set current job priority value. TIMOUT terminal read timeout value. Set ISPY simulated RMON. Return values from within ICNINT Connect interrupt vector completion routine. IRLINT Release an interrupt vector connection. ICNRTN routine to interrupt vector. Connect service CNVAPA address. Convert virtual address to physical MPRGN physical memory. Map virtual memory region to TSXLIB V6.40a PAGE 117 Appendix A: KWIK Index LKBLKW Wait for block to lock. RCVMSW another job. Wait for message from IRSWND Resume window processing. ISPWND Suspend window processing. ICRWND Create a window. IDLWND Delete a window. IPRWND Print the contents of a window. ISLWND Select a window. ICKWTS Check for writes to shared file. ICLXF Clear another job's CL XOFF condition. IRXOFF Reset a line's XOFF status. TSXLIB V6.40a PAGE 118 Appendix B: Distribution Kit Appendix B: Distribution Kit The TSXLIB distribution kit (DECUS #11-490) consists of the following files: TSXLIB.COM TSXLIB builder. ABSTRA.DOC Abstract. TSXLIB.DOC This document. CLLINE.MAC Communication line support. DETJBS.MAC Detached job support. DVALOC.MAC Device allocatind and deallocating. JBPRIV.MAC Job privileges control. JBSTMN.MAC Job status monitoring. MNTDEV.MAC Device mounting and dismounting. MSGCOM.MAC Interjob message communication. PRFANL.MAC Performance analysis support. RELTIM.MAC Real time program support. RUNTIM.MAC Shared run time system support. SHRFIL.MAC Shared file system support. SPOLER.MAC Spooler support. SUBPRO.MAC Subprocess control. SYSTAT.MAC System status information. TRMCOM.MAC Terminal communication. TRMCTL.MAC Terminal control. TSFILS.MAC Special file information. TSLBID.MAC TSXLIB identification. TSXMSC.MAC Miscellaneous EMTs. TSXODT.MAC ODT activation mode support. USRNAM.MAC User name support. WINDOW.MAC Windowing support. TSXLIB.OBJ The implemented library. NOTE See Appendix C for a list of the FORTRAN source programs and indirect command files also included in the distribution kit. TSXLIB V6.40a PAGE 119 Appendix C: Test Record Appendix C: Test Record This appendix lists the TSXLIB routine name, followed by a FORTRAN test program name, followed by the controlling indirect command file name, and the dates on which the routines were tested with either or both FORTRAN IV (F66) and FORTRAN 77 (F77). The source files for these test programs are included in the distribution kit. All of these tests were controlled with the various indirect command files which are also included in the distribution kit. The names and addresses of the test program authors are listed in the notes at the end of the following tabulation. Routine Test .COM F66 F77 Note Name Program File Test Date Test Date BRKCTL CHPGN CLRGNS CNVAPA GETADR TSTFOR 23-Feb-88 23-Feb-88 1 DISMNT DSMNTA GETREG GETRG TSTFOR 12-Feb-88 12-Feb-88 1 GETREG JOBMON TSTF77 03-Jul-88 2 GTJBNM GETJBN TSTFOR 17-May-89 17-May-89 1 GTJBNM STATUS TSTF66 11-May-89 2 GTPGN GTUNAM GETUN TSTFOR 23-Feb-88 23-Feb-88 1 HIEFOF HIEFON IACTCH IALOC IAQFLC IASRNT IBICIO IBISIO IBSTCH ICALOC ICKWTS ICLRST ICLXF ICNINT ICNMCN JOBMON TSTF77 03-Jul-88 2 ICNRTN ICNTSP ICONTM CONTIM TSTFOR 12-Feb-88 12-Feb-88 1 ICONTM STATUS TSTF66 11-May-89 2 ICPUTM CPUTIM TSTFOR 12-Feb-88 12-Feb-88 1 ICPUTM STATUS TSTF66 11-May-89 2 ICRWND WNDTST TSTF77 03-Jul-88 2 IDALOC TSXLIB V6.40a PAGE 120 Appendix C: Test Record IDCLSF SHARED SHARED 03-Jul-88 2 IDFRGN IDLWND WNDTST TSTF77 03-Jul-88 2 IDMALD IDMLD IESMCM JOBMON TSTF77 03-Jul-88 2 IEXSTS EXSTAT TSTFOR 12-Feb-88 12-Feb-88 1 IEXSTS STATUS TSTF66 11-May-89 2 IFLINF FILINF TSTFOR 12-Feb-88 12-Feb-88 1 IGNPIC ILDTR ILNSTS LNSTAT TSTFOR 12-Feb-88 12-Feb-88 1 ILNSTS STATUS TSTF66 11-May-89 2 INITPA INITSP SUBPRO TSTF77 03-Jul-88 2 IPEKIO PEEKIO TSTFOR 12-Feb-88 12-Feb-88 1 IPGNAM PRGNAM TSTFOR 15-Feb-88 15-Feb-88 1 IPGNAM STATUS TSTF66 11-May-89 2 IPOKIO IPPNUM PPNUM TSTFOR 15-Feb-88 15-Feb-88 1 IPPNUM STATUS TSTF66 11-May-89 2 IPRIV PRVSET TSTFOR 15-Feb-88 15-Feb-88 1 IPRPAN GETJBN TSTFOR 17-May-89 17-May-89 1 IPRWND IRDRCL IRDTR IRLINT IRSWND WNDTST TSTF77 03-Jul-88 2 IRXOFF ISFMR ISLWND WNDTST TSTF77 03-Jul-88 2 ISPBLK SPLBLK TSTFOR 15-Feb-88 15-Feb-88 1 ISPBLK TSXTST TSTF77 03-Jul-88 2 ISPCTL ISPFLC ISPFLP ISPLN ISPPA ISPUSE ISPWND WNDTST TSTF77 03-Jul-88 2 ISPY GVAL TSTFOR 15-Feb-88 15-Feb-88 1 ISTDJ DETJOB TSTFOR 23-Feb-88 23-Feb-88 1 ISTDJ TSXTST TSTF77 03-Jul-88 2 ISTFTM ISTLD LDSTAT TSTFOR 22-Feb-88 22-Feb-88 1 ISTPA ISTPRV ISVST ISWESP SUBPRO TSTF77 03-Jul-88 2 ITCRTN ITRAP ITRCTL ITRERR TTERR TSTFOR 22-Feb-88 22-Feb-88 1 ITRTYP TTTYP TSTFOR 22-Feb-88 22-Feb-88 1 ITRTYP TSXTST TSTF77 03-Jul-88 2 TSXLIB V6.40a PAGE 121 Appendix C: Test Record ITRYEL ITRYMS ITRYSP SUBPRO TSTF77 03-Jul-88 2 ITSLIC GETLIC TSTFOR 10-May-89 10-May-89 1 ITSLIC TSXTST TSTF77 03-Jul-88 2 ITSLIN LINUM TSTFOR 12-Feb-88 12-Feb-88 1 ITSLIN TSXTST TSTF77 03-Jul-88 2 ITSNAM GETLIC TSTFOR 10-May-89 10-May-89 1 IUALBK SHARED SHARED 03-Jul-88 2 IUNLKM MEMLOK TSTFOR 23-Feb-88 23-Feb-88 1 IUSPBK IYELL JOBPRI GETPRI TSTFOR 22-Feb-88 22-Feb-88 1 JOBPRI STATUS TSTF66 11-May-89 2 KILJOB KLDTJB DETJOB TSTFOR 23-Feb-88 23-Feb-88 1 KLDTJB TSXTST TSTF77 03-Jul-88 2 LKANMY MEMLOK TSTFOR 23-Feb-88 23-Feb-88 1 LKBLK SHARED SHARED 03-Jul-88 2 LKBLKW SHARED SHARED 03-Jul-88 2 LKLOMY MEMLOK TSTFOR 23-Feb-88 23-Feb-88 1 MAPRNT MEMPOS MEMLOK TSTFOR 23-Feb-88 23-Feb-88 1 MEMPOS STATUS TSTF66 11-May-89 2 MEMSET MEMSIZ TSTFOR 13-Jun-88 13-Jun-88 1 MEMUSE MEMLOK TSTFOR 23-Feb-88 23-Feb-88 1 MEMUSE STATUS TSTF66 11-May-89 2 MNTLD MOUNT MPIOPS MAPIOP TSTFOR 23-May-88 23-May-88 1 MPRGN MPRMPS MAPIOP TSTFOR 23-Feb-88 23-Feb-88 1 MSGREQ MSGSND 08-Jan-88 1 MSGSND SNDMSG TSTF77 03-Jul-88 2 NONINT RCVMSG 08-Jan-88 1 RCVMSG MSGRCV TSTF77 03-Jul-88 2 RCVMSW MSWRCV MSWRCV 03-Jul-88 2 RLCTL RSTODT SETODT STDTJB DETJOB TSTFOR 23-Feb-88 23-Feb-88 1 STDTJB TSTTSX TSTF77 03-Jul-88 2 STPRLV STUNAM GETUN TSTFOR 23-Feb-88 23-Feb-88 1 TERMPA TIMOUT TKCTL TRMIN TRMMSG 08-Jan-88 1 TRMOUT TTCRTN TSXLIB V6.40a PAGE 122 Appendix C: Test Record NOTES: 1. Nick Bourgeois NAB Software Services, Inc. PO Box 20009 Albuquerque, NM 87154 2. Dr. Klaus P. Schneider Perkin-Elmer Censor Schloss Strasse 5 FL-9490 Vaduz Liechtenstein TSXLIB V6.40a PAGE 123 Reader's Comments Did you find any errors in this document? If so, please specify page and describe. Did you find this document understandable, usable, and well organized? Please make suggestions for improvement. Did you find this document sufficiently complete? If not, what material is missing and where should it be placed? Name/Date: Company: Address: City/State/Zip: NAB Software Services, Inc. PO Box 20009 Albuquerque, NM 87154-0009