SAND 80-2464 81h04a A Library Implementation of Programmed Requests for TSX-Plus N. A. Bourgeois, Jr. Systems Engineering Division 1738 Sandia National Laboratories P. O. Box 5800 Albuquerque, NM 87185 (505) 844-8088 Abstract A library of FORTRAN callable routines that implement the EMTs provid- ed by TSX-Plus is described. Descriptions, calling sequences, exam- ples of use, library building pro- cedures, and source codes are given. TSX-Plus Library PAGE 2 This document is issued by Sandia Na- tional Laboratories, operated for the United States Department of Energy by Sandia Corporation. Notice This document was sponsored by the Unit- ed States Government. Neither the Unit- ed States Government nor the United States Department of Energy, nor any of their employees, nor any of their con- tractors, subcontractors, or their em- ployees makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, com- pleteness or usefulness of any informa- tion, apparatus, product or process dis- closed, or represents that its use would not infringe privately owned rights. This work was sponsored and funded by: Headquarters, ESD / OCB / Stop 36 Hanscom Air Force Base, MA 01731 TSX-Plus Library PAGE 3 Acknowledgments The author wishes to thank S & H Com- puter Systems Inc. for its permission to reprint parts of their "TSX-Plus Reference Manual" in this document. The author wishes also to thank W. L. Jacklin for his assistance in reviewing this document and particularly for his help with the many FORTRAN examples in the third chapter. *********** * CAUTION * *********** Much of both the MACRO-11 source codes and the FORTRAN examples described in this document are as yet untried. There have been some routine name changes from prior releases of the TSX-Plus library. TSX-Plus Library PAGE 4 Introduction 1. Introduction When application programs are executed under a time sharing executive such as TSX-Plus * [1,2] certain capa- bilities become desirable if not absolutely essential. These capabilities relate to requirements for such things as hardware dependent I/O, shared files, inter- program communication, and others. TSX-Plus provides a number of programmed requests or EMTs for these pur- poses. This document describes a number of FORTRAN call- able 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 func- tions. The routines are written in MACRO-11 [3]. The code is completely reentrant and, therefore, shareable under TSX-Plus. The next section offers a general description of the several groups of routines. It describes the pro- cess for linking the routines to the FORTRAN application program. The general calling sequences are also des- cribed. The third section gives a detailed description of each of the individual routines. The descriptions in- clude both the calling sequences and, in most cases, ex- amples. Procedures for constructing the library from the several source modules are given in the fourth section. Appendix A contains a table of the routines listed in functional groups. A description of the distribution kit is contained in Appendix B. * TSX-Plus is a registered trademark of S & H Com- puter Systems Inc., Nashville, TN. TSX-Plus Library PAGE 5 General Description 2. General Description These TSX-Plus library routines provide facilities to support detached jobs, file structured device mount- ing and dismounting, communication between running pro- grams, program performance analysis, real time program execution, shared run time system, shared files, communication between running programs and a terminal, program control of the terminal, ODT activation mode, and several miscellaneous EMTs. The standard FORTRAN 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 fol- lows: .RUN SY:FORTRAN *MYPROG=MYPROG *^C Then the routines are linked with the application program as shown below: .RUN SY:LINK *MYPROG=MYPROG,TSXLIB/F *^C or .RUN SY:LINK *MYPROG=MYPROG,TSXLIB,SYSLIB,FPULIB *^C The application program is now ready for execution. .RUN DK:MYPROG The "TSX-Plus Reference Manual" [1] describes how the EMTs implemented in this TSX-Plus library are ac- cessed from a MACRO-11 program. However, the FORTRAN/MACRO interface described in the "RT-11 Pro- grammer's Reference Manual" [5] may also be used to ac- cess the routines in the library. TSX-Plus Library PAGE 6 General Description Detached Job Support Table 2-1 lists the routines that provide detached job support from within an executing program. ISTDJ Get the status of a detached job. KLDTJB Kill a detached job. STDTJB Start a detached job. Detached job support. Table 2-1. Device Mounting and Dismounting It is possible to mount and dismount a file struc- tured device for directory caching from within a running program. The routines listed in Table 2-2 provide these capabilities. DISMNT Dismount a file structured device. MOUNT Mount a file structured device. Device mounting and dismounting. Table 2-2. Interprogram Message Communication TSX-Plus provides an optional facility that allows running programs to communicate with each other. Table 2-3 lists the routines that support this interprogram message communication. MSGSND Send a message to another job. RCVMSG Try to receive a message from another job. RCVMSW Wait for a message from another job. Interprogram message ãommunication. Table 2-3. 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 mes- sage 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 message channel TSX-Plus Library PAGE 7 General Description is active when messages are being held in the queue as- sociated with the channel or if a program is waiting for a message from the channel. When message channels be- come 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 re- move any pending messages. This allows one program to leave a message for another program that will be run at a later time. Performance Analysis Support For many applications the keyboard monitor level performance analysis control provided by TSX-Plus is adequate. However, in cases such as analyzing the per- formance 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-4 pro- vide just this capability. INITPA Initialize for a performance analysis. ISPPA Stop a performance analysis. ISTPA Start a performance analysis. TERMPA Terminate from a performance analysis. Performance analysis support. Table 2-4. Real Time Program Support The real time program support provided by TSX-Plus allows multiple real time programs to be run concurrent- ly with normal time sharing operations. The basic func- tions provided by this facility are listed in Table 2-5. A program must have operator privilege to use any of the real time routines. The real time facilities are available to both normal jobs controlled by time sharing lines and to detached jobs. Detached jobs started by time sharing users have operator privilege only if the user starting them does. A basic facility required by many real time pro- grams is the ability to access the I/O page which con- tains 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. TSX-Plus Library PAGE 8 General Description CNVAPA Convert a virtual address to a physical address. IBICIO Bit clear a value into the I/O page. IBISIO Bit set a value into the I/O page. ICNINT Connect an interrupt vector to a comple- tion routine. IPEKIO Peek at a value in the I/O page. IPOKIO Poke a value into the I/O page. IRLINT Release an interrupt vector connection. ISPY Return values from within the simulated RMON (SYSLIB 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. MPRMPS Map the simulated RMON into the program space. Real time program support. Table 2-5. A real time program can access the I/O page in one of two ways: it can map the I/O page into the program's space; or it can leave the simulated RMON mapped into the program's space and perform peek, poke, bit set, and bit clear operations into the I/O page. It is much more efficient to directly access the device registers by mapping the I/O page into the program's space than to use the routines to perform each individual access. However, this technique will not work if the program must also directly access offsets into RMON. The cor- rect way to access offsets into RMON is with the SYSLIB routine, ISPY, which will work even if the I/O page is mapped into the program's space. The TSX-Plus real time support facility allows a program to connect a real time interrupt to a completion routine. If this is done, the completion routine is ex- ecuted 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 ille- gal for more than one job to connect to the same inter- rupt vector. An execution priority may be specified for each completion routine. This is not the same as the hardware selected priority of the interrupt. All com- pletion routines are synchronized with the job and run at hardware priority level zero. The completion routine priority is used to schedule the completion routines for execution. The available priority levels are zero through seven. The execution of a real time completion routine for one job will be interrupted and suspended if an interrupt occurs that causes a higher priority com- pletion routine for another job to be queued for execu- TSX-Plus Library PAGE 9 General Description tion. 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 com- pletion routine is pending. Completion routine priorities one through seven are real time priorities. They are higher than the priori- ties 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 nor- mal 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. 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-6 lists the routines that support this feature. IASRNT Associate/disassociate a shared run time system with a job. MAPRNT Map a shared run time system into a job's region. Shared run time system support. Table 2-6. 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. Shared File Support Table 2-7 lists the routines that offer access to the shared file record locking facility provided by TSX-Plus. This is useful in situations where programs being run from several terminals wish to update a common TSX-Plus Library PAGE 10 General Description file. Through the record locking facility a program may gain exclusive access to one or more blocks in a shared file by locking those blocks. Other users attempting to lock the same blocks will be denied access until the first user releases the locked blocks. ICKWTS Check for writes to a shared file. IDCLSF Declare a file to be shared. ISVST Save the status of a shared file. IUALBK Unlock all locked blocks. IUSPBK Unlock a specific block. LKBLK Try to lock a block. LKBLKW Wait for a block to lock. Shared file support. Table 2-7. 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 re- cord. 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. Terminal Communications Support The routines that allow a running program to com- municate with a terminal are listed in Table 2-8. TRMIN Accept a string of characters from the terminal. TRMMSG Send a message to another terminal. TRMOUT Send a string of characters to the ter- minal. Terminal ãommunications support. Table 2-8. Terminal Control Support The terminal control support routines are listed in Table 2-9. TSX-Plus Library PAGE 11 General Description BRKCTL Establish break sentinal control. HIEFOF Turn off the high efficiency terminal mode. HIEFON Turn on the high efficiency terminal mode. IACTCH Check for pending activation characters. ITRERR Check for terminal input errors. ITRTYP Determine the terminal type. TIMOUT Set the terminal read time out value. Terminal control support. Table 2-9. Miscellaneous EMT Support Table 2-10 lists the routines that support the sev- eral miscellaneous EMTs provided by TSX-Plus. ISPBLK Determine the number of free blocks in the spool file. ITSLIC Determine the TSX-Plus license number. ITSLIN Determine the TSX-Plus line number. MEMSET Set the memory allocation. Miscellaneous EMT support. Table 2-10. ODT Activation Mode Support ODT activation mode may be turned on and off from within a running program. Table 2-11 lists the routines that support this feature. In this mode TSX-Plus con- siders all characters to be activation characters except the digits, the comma, the dollar sign and the semi- colon. RSRODT Reset normal activation mode. SETODT Set ODT activation mode. ODT activation mode support. Table 2-11. TSX-Plus Library PAGE 12 Routine Descriptions 3. Routine Descriptions This section presents all of the TSX-Plus routines in alphabetical order and provides a detailed descrip- tion 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 in- formation is available in the "TSX-Plus Reference Manu- al" [1] and the "RT-11 Programmer's Reference Manual" [5]. Some of these TSXLIB routines require calls to various SYSLIB routines. 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 termi- nal 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 user. If a break routine was previously speci- fied, it is cancelled when a new break routine is de- clared. If a value of zero is specified for the name of the completion routine, CPLRTN, any previously specified break routine is cancelled. TSX-Plus Library PAGE 13 Routine Descriptions The following example first declares the completion routine as an external, then establishes break sentinel control using the letter H, and later cancells the con- trol. EXTERNAL CPLRTN IBRKCH = 72 . . CALL BRKCTL ( IBRKCH,CPLRTN ) . . CALL BRKCTL ( 0,0 ) . . CNVAPA This routine is used to convert a virtual address into a physical address. This is necessary when con- trolling devices that do direct memory access transfers. The program should lock itself into memory before exe- cuting this routine. The calling sequence is as follows: CALL CNVAPA ( IVADR,IPADR [ ,IERR ] ) 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. IERR is negative or the following: 0 real time support is not available or this job does not have operator privilege. The low order sixteen bits of the physical address are returned in the first element of the buffer, IPADR, and the high order two bits of the physical address are returned in bit positions four and five of the second element of the buffer. The following example first locks itself into memo- ry then converts a virtual address to a physical ad- dress. The program is halted if the error condition is returned. DIMENSION IPADR ( 2 ) CALL LKANMY CALL CNVAPA ( "54720,IPADR,IERR ) TSX-Plus Library PAGE 14 Routine Descriptions IF ( IERR .EQ. 0 ) STOP . . 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: CALL DISMNT ( IDVNAM ) where: IDVNAM is the RAD50 value of the file struc- tured 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 ) . . 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: TSX-Plus Library PAGE 15 Routine Descriptions 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 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 recog- nizing 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 spec- ified activation character must be declared if high ef- ficiency 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 no activation character is pending. 1 at least one activation character is pending. 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 se- quences 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. TSX-Plus Library PAGE 16 Routine Descriptions 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 par- ticular 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 previous- ly mapped into the job's region, that mapping is unaf- fected 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 dif- ferent 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 disassoci- ated from the job and reestablishes normal memory map- ping 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 opera- tion 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: TSX-Plus Library PAGE 17 Routine Descriptions 0 real time support is not available or this job does not have operator privilege. 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 re- turned. IERR = IBICIO ( "176500,"100 ) IF ( IERR .EQ. 0 ) STOP . . 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 operator privilege. 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 . . ICKWTS This routine is used to determine if any other user has written to a shared file. The calling sequences are as follows: TSX-Plus Library PAGE 18 Routine Descriptions CALL ICKWTS ( ICHAN [ ,IERR ] ) or IERR = ICKWTS ( ICHAN ) where: ICHAN is the I/O channel open to the shared file. IERR is one of the following: 0 no writes have been performed. 2 writes have been performed. This routine can be used to advantage in a situa- tion 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. CALL ASSIGN ( 33,'RK3:THIS.DAT' ) ICHAN = ( 33 ) CALL IDCLSF ( ICHAN,5 ) . . IERR = ICKWTS ( ICHAN ) IF ( IERR .EQ. 2 ) 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 zero to seven. IERR is negative or one of the following: TSX-Plus Library PAGE 19 Routine Descriptions 0 real time support is not available or this job does not have operator privilege. 1 the maximum number of interrupts are already in use. 2 some other job is already connected to this interrupt vector. The vector remains connected to the completion routine until the program terminates or until the routine, IRLINT, is executed. 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 . . 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 one of the following: TSX-Plus Library PAGE 20 Routine Descriptions 0 no error. 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 ex- ists. 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 re- quire 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 de- clares exclusive/update protection/access. If an error condition is returned the program aborts. CALL ASSIGN ( 40,'DK:FILE.DAT' ) ICHAN = ILUN ( 40 ) IERR = IDCLSF ( ICHAN,2 ) IF ( IERR .NE. 0 ) STOP . . 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 fol- lows: 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. TSX-Plus Library PAGE 21 Routine Descriptions 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 . . 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 se- quence 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. 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 operator privilege. 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 . . TSX-Plus Library PAGE 22 Routine Descriptions IPOKIO This routine is used to deliver a value into a word in the I/O page without requiring the job's virtual ad- dress region to be mapped to the I/O page. The calling sequences are as follows: 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 operator privilege. 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 . . IRLINT This routine releases the connection of an inter- rupt vector and a completion routine. The connection must have been made by previously executing the routine, ICNINT. The calling sequences are as follows: CALL IRLINT ( IVEC [ ,IERR ] or IERR = IRLINT ( IVEC ) where: IVEC is the interrupt vector address. IERR is negative or the following: 0 real time support is not available or this job does not have operator privilege. The following example first declares the completion routine as an external, then connects it to a vector, and finally breaks the connection. TSX-Plus Library PAGE 23 Routine Descriptions EXTERNAL CPLRTN CALL ICNINT ( "320,CPLRTN,0 ) . . CALL IRLINT ( "320 ) . . 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. 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 . . TSX-Plus Library PAGE 24 Routine Descriptions ISPY This is a SYSLIB routine that is used to return the value located at a specific offset into the simulated RMON. TXS-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 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 is nonprivileged or one if privileged. -8 zero if PAR 7 is mapped to the simu- lated 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. 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 de- tached 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. TSX-Plus Library PAGE 25 Routine Descriptions 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 . . 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 per- formance 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 . . ISVST This routine is used to save the status of a shared file. The effect of this routine is to suspend the con- nection between the shared file table and the I/O chan- nel. Any blocks that are currently 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 SYS- TSX-Plus Library PAGE 26 Routine Descriptions LIB routine, PURGE. The calling sequence is as follows: CALL ISVST ( ICHAN ) where: ICHAN is the I/O channel number open to the shared file. When using a single channel number to access sever- al shared files it is for each file convenient to ini- tially 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 re- moved 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. CALL ASSIGN ( 30,'DK:SOME.FIL' ) ICHAN = ( 30 ) CALL IDCLSF ( ICHAN,4 ) . . CALL ISVST ( ICHAN ) . . 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 er- rors and aborts the program if one has occurred. . . IERR = ITRERR () TSX-Plus Library PAGE 27 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 se- quences 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. 8 Qume. ITSLIC This routine is used to determine the TSX-Plus li- cense number. The calling sequences are as follows: CALL ITSLIC ( IRET ) or IRET = ITSLIC () where: IRET is the requested TSX-Plus license number. 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: TSX-Plus Library PAGE 28 Routine Descriptions CALL ITSLIN ( IRET ) or IRET = ITSLIN () where: IRET is zero if RT-11 is running or the re- quested line number if TSX-Plus is run- ning. The following example aborts if RT-11 is running or continues if TSX-Plus is running. IRET = ITSLIN () IF ( IRET .EQ. 0 ) STOP . . 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 one of the following: 0 no error. 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 re- leased 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. CALL ASSIGN ( 40,'DK:FILE.DAT' ) ICHAN = ILUN ( 40 ) CALL IDCLSF ( ICHAN,1 ) DO 10 IBLK = 4,6 CALL LKBLKW ( ICHAN,IBLK ) 10 CONTINUE . . TSX-Plus Library PAGE 29 Routine Descriptions 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 [ IERR ] or IERR = IUNLKM () where: IERR is negative or as follows: 0 real time support is not available or this job does not have operator privilege. The following example first locks itself into memo- ry 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 un- locked. IERR is one of the following: 0 no error. 1 the channel is not open to a shared file. TSX-Plus Library PAGE 30 Routine Descriptions The following example opens a file, declares the file to be shared, locks all blocks in the file and then unlocks a specific block in the file. The program is stopped if an error condition is returned. CALL ASSIGN ( 30,'DL0:THAT.DAT' ) ICHAN = ( 30 ) CALL IDCLSF ( ICHAN,2 ) CALL LKBLKW ( ICHAN,-1 ) IERR = IUSPBK ( ICHAN,7 ) IF ( IERR .NE. 0 ) 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 one of the following: 0 no error. 1 invalid job number. The following example first starts a detached job and then later kills the detached job. If an error con- dition 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. The calling sequences are as follows: TSX-Plus Library PAGE 31 Routine Descriptions CALL LKANMY [ IERR ] or IERR = LKANMY () where: IERR is negative or the following: 0 real time support is not available or this job does not have operator privilege. 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 termi- nates 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 one of the following: 0 no error. 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 TSX-Plus Library PAGE 32 Routine Descriptions 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. CALL ASSIGN ( 40,'DY1:JUNK.DAT' ) ICHAN = ( 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 one of the following: 0 no error. 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 re- quests 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. TSX-Plus Library PAGE 33 Routine Descriptions CALL ASSIGN ( 40,'DK:FILE.DAT' ) ICHAN = ( 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 rela- tively slow and should be done only if the job is to re- main locked for a long period of time. The calling se- quences are as follows: CALL LKLOMY [ IERR ] or IERR = LKLOMY () where: IERR is negative or the following: 0 real time support is not available or this job does not have operator privilege. 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: 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 ad- dress register (PAR) that is to be used TSX-Plus Library PAGE 34 Routine Descriptions 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 cor- respondence 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 re- gion. 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 re- gion, multiple PAR regions are automati- cally 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 associat- ed 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 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 vir- tual address space to a shared run time system neither increases nor decreases the size of memory occupied by TSX-Plus Library PAGE 35 Routine Descriptions 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 be- comes 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 nor- mally 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 disas- sociates 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 ) . . MEMSET This routine is used to set the amount of memory that will be allocated for the job. The calling se- quences 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 alloca- tion is less than the request. DATA IARG/"120000/ IRET = MEMSET ( IARG ) IF ( IRET .LT. IARG ) STOP . TSX-Plus Library PAGE 36 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 com- mand. 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 mount- ed. The program is halted if an error condition is re- turned. 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 sequence is as follows: CALL MPIOPS The mapping set up by this routine remains in ef- fect until the routine, MPRMPS, is executed or the pro- gram terminates. Operator privilege is required to exe- cute this routine. MPRMPS This routine is used to map a simulated RMON into the program space between the octal addresses of 160000 and 177777. The calling sequence is as follows: TSX-Plus Library PAGE 37 Routine Descriptions CALL MPRMPS Operator privilege is required to execute this routine. 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 contain- ing the message. MSGSIZ is the length of the message in characters. IERR is one of the following: 0 no error. 1 all message channels are busy. 2 the maximum allowed number of mes- sages are being held in the message queues. 4 the transmitted message was too long and was truncated to the maximum al- lowed length. 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 ) TSX-Plus Library PAGE 38 Routine Descriptions IERR = MSGSND ( ICHNAM,MSGBUF,12 ) IF ( IERR .NE. 0 ) STOP . . 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 one of the following: 0 no error. A message was received. 3 no message was queued on the named channel. 4 the message was longer than the re- ceiving buffer. 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. 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 . . TSX-Plus Library PAGE 39 Routine Descriptions 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 one of the following: 0 a message has been received. 1 all message channels are busy. 4 the message was longer than the re- ceiving buffer. 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 . . RSTODT This routine is used to reset or clear the ODT ac- tivation 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: TSX-Plus Library PAGE 40 Routine Descriptions 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 one of the following: 0 no error. 1 no detached job line is available. If a free detached job line is available, the spec- ified command file, JOBNAM, is initiated as a detached job and the number of the detached job is returned in the variable, JOBNUM. 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 ter- minated 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 . . TERMPA This routine is used to conclude a performance an- alysis. It has the effect of returning into a user sup- plied 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 TSX-Plus Library PAGE 41 Routine Descriptions 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: 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 perfor- mance 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 . . TSX-Plus Library PAGE 42 Routine Descriptions 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 con- trolled. 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. . . CALL TIMOUT ( 40,24 ) . . 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 re- ceive the string. IBFSIZ is the length of the receiving buffer in characters. ICOUNT is the number of characters actually re- ceived. IERR is one of the following: 0 no error. TSX-Plus Library PAGE 43 Routine Descriptions 1 the specified buffer overflowed. This routine causes a program to wait until an ac- tivation character is entered on the terminal and then returns all characters received up to and including the last activation character. This routine is substancial- ly more efficient than doing a series of the SYSLIB routine, ITTINR. It is particularly well suited for ac- cepting 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. 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 sequence is as follows: CALL 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. The message must be terminated with a null character. The following example sends a message to the termi- nal connected to line 14. LOGICAL*1 IMSGBF ( 30 ) CALL SCOPY ( ' THIS IS THE MESSAGE',IMSGBF,20 ) CALL TRMMSG ( 14,IMSGBF ) . . 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 TSX-Plus Library PAGE 44 Routine Descriptions 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 ) . . TSX-Plus Library PAGE 45 Building the Library 4. Building the Library The sources for the TSX-Plus Library consist of the eleven MACRO-11 modules listed in Table 4-1. The pro- cess of constructing the library file, TSXLIB.OBJ, is the same when accomplished under both RT-11 [4] and under TSX-Plus. Module Content DETJBS Detached job support. 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. TRMCOM Terminal communication. TRMCTL Terminal control. TSXMSC Miscellaneous EMTs. TSXODT ODT activation mode support. TSXLIB MACRO-11 source modules. Table 4-1. First the MACRO-11 modules are assembled as follows: .RUN SY:MACRO *DETJBS=DETJBS *MNTDEV=MNTDEV *MSGCOM=MSGCOM *PRFANL=PRFANL *RELTIM=RELTIM *RUNTIM=RUNTIM *SHRFIL=SHRFIL *TRMCOM=TRMCOM *TRMCTL=TRMCTL *TSXMSC=TSXMSC *TSXODT=TSXODT *^C Next the library file is constructed as follows: TSX-Plus Library PAGE 46 Building the Library .RUN SY:LIBR *TSXLIB=DETJBS,MNTDEV,MSGCOM// *PRFANL,RELTIM,RUNTIM,SHRFIL *TRMCOM,TRMCTL,TSXMSC,TSXODT *// *^C The command file, TSXLIB.COM, in Appendix B will accomplish the construction of the library file, TSXLIB.OBJ. It will also delete the several temporary files. TSX-Plus Library PAGE 47 References References 1. S & H Computer Systems, Inc., "TSX-Plus Reference Manual", Nashville, TN, December 1980. 2. S & H Computer Systems, Inc., "TSX-Plus version 2.0 System Release Notes", Nashville, TN. 3. Digital Equipment Corporation, "PDP-11 MACRO-11 Language Reference Manual", AA-5075B-TC, Maynard, MA, January 1980. 4. Digital Equipment Corporation, "RT-11 System User's Guide", AA-5279B-TC, Maynard, MA, March 1980. 5. Digital Equipment Corporation, "RT-11 Programmer's Reference Manual", AA-H378A-TC, Maynard, MA, March 1980. TSX-Plus Library PAGE 48 Appendix A Appendix A This appendix lists all of the TSXLIB routines in functional groups. Detached Job Support ISTDJ Get the status of a detached job. KLDTJB Kill a detached job. STDTJB Start a detached job. Device Mounting and Dismounting DISMNT Dismount a file structured device. MOUNT Mount a file structured device. Interprogram Message Communication MSGSND Send a message to another job. RCVMSG Try to receive a message from another job. RCVMSW Wait for a message from another job. Performance Analysis Support INITPA Initialize for a performance analysis. ISPPA Stop a performance analysis. ISTPA Start a performance analysis. TERMPA Terminate from a performance analysis. Real Time Program Support CNVAPA Convert a virtual address to a physical address. IBICIO Bit clear a value into the I/O page. TSX-Plus Library PAGE 49 Appendix A IBISIO Bit set a value into the I/O page. ICNINT Connect an interrupt vector to a comple- tion routine. IPEKIO Peek at a value in the I/O page. IPOKIO Poke a value into the I/O page. IRLINT Release an interrupt vector connection. IUNLKM Unlock a job from memory. LKANMY Lock a job into any memory. LKLOMY Lock a job into low memory. MPIOPS Map the I/O page into the program space. MPRMPS Map the simulated RMON into the program space. Shared Run Time System Support IASRNT Associate/disassociate a shared run time system with a job. MAPRNT Map a shared run time system into a job's region. Shared File Support 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. Terminal Communications Support TRMIN Accept a string of characters from the terminal. TRMMSG Send a message to another terminal. TSX-Plus Library PAGE 50 Appendix A TRMOUT Send a string of characters to the ter- minal. Terminal Control Support BRKCTL Establish break sentinal control. HIEFOF Turn off the high efficiency terminal mode. HIEFON Turn on the high efficiency terminal mode. IACTCH Check for pending activation characters. ITRERR Check for terminal input errors. ITRTYP Determine the terminal type. TIMOUT Set the terminal read time out value. Miscellaneous EMT Support ISPBLK Determine the number of free blocks in the spool file. ISPY Return values from within simulated RMON. ITSLIC Determine the TSX-Plus license number. ITSLIN Determine the TSX-Plus line number. MEMSET Set the memory allocation. ODT Activation Mode Support RSRODT Reset normal activation mode. SETODT Set ODT activation mode. TSX-Plus Library PAGE 51 Appendix B Appendix B The TSXLIB distribution kit consists of the MACRO-11 source modules listed in Table 4-1 and the fol- lowing files: TSXLIB.COM TSXLIB builder. TSXLIB.CRF A cross reference chart. TSXLIB.DOC This document. TSXLIB.OBJ The implemented library.