.COMMENT TSXLIB.RNO	NAB	7-MAY-81/02-MAR-83.
.COMMENT
.COMMENT 04-JUN-82  This article has been taken from the TSXLIB
.COMMENT	    Users Guide document.
.COMMENT 07-JUN-82  Revised tail end of the introductory section
.COMMENT	    and the references.
.COMMENT 15-DEC-82  Udated for publication in "The DEC Professional"
.COMMENT	    and presentation at the DECUS Symposium in St.
.COMMENT	    Louis.
.COMMENT 02-MAR-83  Reformatted for the DECUS Proceedings.
.COMMENT
.PAPER SIZE 60,72
.UPPER CASE
.SUBTITLE;########*
.LEFT MARGIN 8
.RIGHT MARGIN 58
.FILL
.JUSTIFY
.FLAGS HYPHENATE
.FIGURE 4
.CENTER;TSXLIB -- A FORTRAN CALLABLE IMPLEMENTATION
.CENTER;OF THE TSX-PLUS EMTS
.BLANK 2
.CENTER;N.#A.#Bourgeois, Jr.
.CENTER;Sandia National Laboratories
.CENTER;Albuquerque, NM
.BLANK 4
.PARAGRAPH
Like RT-11, TSX-Plus offers the MACRO programmer a number of system
services via programmed requests or EMTs.  RT-11 makes its system
services available to the FORTRAN programmer through the system
subroutine library, SYSLIB.  TSX-Plus also honors most RT-11 programmed
requests.  TSXLIB makes the TSX-Plus EMTs available to the FORTRAN
programmer as a library of callable routines.  The code in TSXLIB
is all reentrant.
.BLANK 4
.RIGHT MARGIN 51
.TEST PAGE 4
.CENTER;INTRODUCTION
.PARAGRAPH
The TSX-Plus library routines provide facilities to support detached
jobs, file structured device mounting and dismounting, =communication
between running programs, program performance =analysis, real time
program execution, shared run time system, shared files, system
status information, =communication
between running programs and a terminal, program control of the
terminal, ODT activation mode, and several miscellaneous EMTs.
The system status information routines require the use of TSX-Plus
Version 2.2 [3].  Several of the real time support routines require
TSX-Plus Version 3.0 [5].  All other routines require TSX-Plus Version
2.0 or later.
.PARAGRAPH
TSXLIB [1] is available from the DECUS/US Chapter Program Library.  The
kit includes the MACRO source modules for all =groups of routines, a
complete user's manual, a cross reference chart, an indirect command
file to build the library, and the implemented library.  The cross
reference chart lists for each routine the page number in the user's
manual and the page number in the "TSX-Plus Reference Manual" [2].
.PARAGRAPH
The standard FORTRAN subroutine calling sequence shown below may be
used to access all of the routines in TSXLIB.
.BLANK
.CENTER;CALL SUBRTN ( ARG1, ... ,ARGn )
.PARAGRAPH
Those routines that return only one value are also callable as FORTRAN
functions.  This is as follows:
.BLANK
.CENTER;IRET _= RTNAME ( ARG1, ... ,ARGn )
.PARAGRAPH
The "TSX-Plus Reference Manual" describes how the EMTs implemented in
TSXLIB are accessed from a MACRO program.  However, the FORTRAN/MACRO
interface =described in the "RT-11 Programmer's Reference Manual" [4]
may also be used to access the routines in the library.  The TSXLIB
(as well as SYSLIB) routines are also available to the "C" programmer
via the DECUS "C" [6] library function, "call(...)".
.BLANK 2
.TEST PAGE 4
.CENTER;DETACHED JOB SUPPORT
.PARAGRAPH
Table 1 lists the routines that provide detached job support from
within an executing program.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 7
.INDENT -8
ISTDJ###Get the status of a detached job.
.INDENT -8
KLDTJB##Kill a detached job.
.INDENT -8
STDTJB##Start a detached job.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Detached Job Support.
.CENTER
Table 1.
.BLANK 2
.TEST PAGE 4
.CENTER;DEVICE MOUNTING AND DISMOUNTING
.PARAGRAPH
It is possible to mount and dismount a file structured device for
directory caching from within a running program.  The routines listed
in Table 2 provide these capabilities.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 6
.INDENT -8
DISMNT##Dismount a file structured device.
.INDENT -8
MOUNT###Mount a file structured device.
.BLANK
.LEFT MARGIN -10
.RIGHT MARGIN +2
.CENTER
Device Mounting and Dismounting.
.CENTER
Table 2.
.BLANK 2
.TEST PAGE 4
.CENTER;INTERPROGRAM MESSAGE COMMUNICATION
.PARAGRAPH
TSX-Plus provides an optional facility that allows running programs to
communicate with each other.  Table 3 lists the routines that support
this interprogram message =communication.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 8
.INDENT -8
MSGSND##Send a message to another job.
.INDENT -8
RCVMSG##Try to receive a message from another job.
.INDENT -8
RCVMSW##Wait for a message from another job.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Interprogram Message Communication.
.CENTER
Table 3.
.PARAGRAPH
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.
.PARAGRAPH
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 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.
.PARAGRAPH
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.
.BLANK 2
.TEST PAGE 4
.CENTER;PERFORMANCE ANALYSIS SUPPORT
.PARAGRAPH
For many applications the keyboard monitor level performance =analysis
control provided by TSX-Plus is adequate.  However, in cases such as
analyzing the performance of an overlayed program it is necessary to
have control over the performance =analysis feature from the running
program.  The routines listed in Table 4 provide just this
capability.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 9
.INDENT -8
INITPA##Initialize for a performance =analysis.
.INDENT -8
ISPPA###Stop a performance =analysis.
.INDENT -8
ISTPA###Start a performance =analysis.
.INDENT -8
TERMPA##Terminate from a performance =analysis.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Performance Analysis Support.
.CENTER
Table 4.
.BLANK 2
.TEST PAGE 4
.CENTER;REAL TIME PROGRAM SUPPORT
.PARAGRAPH
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 facility are listed
in Table 5.
.PARAGRAPH
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.
.PARAGRAPH
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.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 29
.INDENT -8
CNVAPA##Convert a virtual address to a physical address.
.INDENT -8
IBICIO##Bit clear a value into the I/O page.
.INDENT -8
IBISIO##Bit set a value into the I/O page.
.INDENT -8
ICNINT##Connect an interrupt vector to a completion routine.
.INDENT -8
IPEKIO##Peek at a value in the I/O page.
.INDENT -8
IPOKIO##Poke a value into the I/O page.
.INDENT -8
IRLINT##Release an interrupt vector connection.
.INDENT -8
IUNLKM##Unlock a job from memory.
.INDENT -8
LKANMY##Lock a job into any memory.
.INDENT -8
LKLOMY##Lock a job into low memory.
.INDENT -8
MPIOPS##Map the I/O page into the program space.
.INDENT -8
MPRMPS##Map the simulated RMON into the program space.
.INDENT -8
TKCTL###Take exclusive control of the system.
.INDENT -8
RLCTL###Relinquish exclusive control of the system.
.INDENT -8
STPRLV##Set the user mode processor priority level.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Real Time Program Support.
.CENTER
Table 5.
.PARAGRAPH
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.
.PARAGRAPH
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 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.
.PARAGRAPH
An execution priority may be specified for each completion routine.
This is not the same as the hardware selected priority of the
interrupt.  All completion routines are synchronized with the job and
run at hardware priority level zero.  The 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
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.
.PARAGRAPH
Completion routine priorities one through seven are real time
priorities.  They are higher than the priorities given to time sharing
jobs and will always preempt the time sharing jobs.  Completion
routine priority zero is not a real time priority but rather a very
high normal priority.  Such zero priority completion routines are time
sliced in the normal fashion.  If a completion routine enters a wait
state it relinquishes its real time priority.  Jobs that have real
time, interrupt driven completion routines need not be locked in memory.
.PARAGRAPH
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.
.PARAGRAPH
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.
.BLANK 2
.TEST PAGE 4
.CENTER;SHARED RUN TIME SYSTEM SUPPORT
.PARAGRAPH
TSX-Plus provides a facility that allows shared run time systems or
data areas to be mapped into the address spaces of multiple time
sharing jobs.  Table 6 lists the routines that support this feature.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 7
.INDENT -8
IASRNT##Associate/disassociate a shared run time system with a job.
.INDENT -8
MAPRNT##Map a shared run time system into a job's region.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Shared Run Time System Support.
.CENTER
Table 6.
.PARAGRAPH
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.
.BLANK 2
.TEST PAGE 4
.CENTER;SHARED FILE SUPPORT
.PARAGRAPH
Table 7 lists the routines that offer access to the shared file
record locking facility provided by TSX-Plus.  This is useful in
situations where programs being run from several terminals wish to
update a common file.  Through the record locking facility a program
may gain exclusive access to one or more blocks in a shared file by
locking those blocks.  Other users attempting to lock the same blocks
will be denied access until the first user releases the locked blocks.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 12
.INDENT -8
ICKWTS##Check for writes to a shared file.
.INDENT -8
IDCLSF##Declare a file to be shared.
.INDENT -8
ISVST###Save the status of a shared file.
.INDENT -8
IUALBK##Unlock all locked blocks.
.INDENT -8
IUSPBK##Unlock a specific block.
.INDENT -8
LKBLK###Try to lock a block.
.INDENT -8
LKBLKW##Wait for a block to lock.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Shared File Support.
.CENTER
Table 7.
.PARAGRAPH
The recommended procedure for updating a shared file being accessed by
several users is as follows:
.LEFT MARGIN +6
.RIGHT MARGIN -2
.BLANK
.INDENT -4
1.##Open the file.
.INDENT -4
2.##Declare the file to be shared.
.INDENT -4
3.##Lock all blocks which contain the desired record.
.INDENT -4
4.##Read the locked blocks into memory.
.INDENT -4
5.##Update the record.
.INDENT -4
6.##Write the updated blocks to the file.
.INDENT -4
7.##Unlock the blocks.
.INDENT -4
8.##Repeat steps three through seven as required.
.INDENT -4
9.##Close the file.
.LEFT MARGIN -6
.RIGHT MARGIN +2
.BLANK 2
.TEST PAGE 4
.CENTER;SYSTEM STATUS INFORMATION
.PARAGRAPH
Information typical of that returned by the SYSTAT keyboard command is
made available to a running program by the routines listed in Table 8.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 16
.INDENT -8
ICONTM##Determine the connect time for a job.
.INDENT -8
ICPUTM##Get the CPU time used by a job.
.INDENT -8
IEXSTS##Get a job's execution status.
.INDENT -8
ILNSTS##Check the status of a line.
.INDENT -8
IPGNAM##Get the name of the program being run by a job.
.INDENT -8
IPPNUM##Get the project-programmer number for a job.
.INDENT -8
MEMPOS##Determine the position of a job in memory.
.INDENT -8
MEMUSE##Determine the amount of memory used by a job.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
System Status Information.
.CENTER
Table 8.
.BLANK 2
.TEST PAGE 4
.CENTER;TERMINAL COMMUNICATION SUPPORT
.PARAGRAPH
The routines that allow a running program to communicate with a
terminal are listed in Table 9.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 9
.INDENT -8
TRMIN###Accept a string of characters from the terminal.
.INDENT -8
TRMMSG##Send a message to another terminal.
.INDENT -8
TRMOUT##Send a string of characters to the terminal.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Terminal Communications Support.
.CENTER
Table 9.
.BLANK 2
.TEST PAGE 4
.CENTER;TERMINAL CONTROL SUPPORT
.PARAGRAPH
The several terminal control support routines are listed in Table 10.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 16
.INDENT -8
BRKCTL##Establish break sentinal control.
.INDENT -8
HIEFOF##Turn off the high efficiency terminal mode.
.INDENT -8
HIEFON##Turn on the high efficiency terminal mode.
.INDENT -8
IACTCH##Check for pending activation characters.
.INDENT -8
ITRERR##Check for terminal input er- rors.
.INDENT -8
ITRTYP##Determine the terminal type.
.INDENT -8
TIMOUT##Set the terminal read time out value.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Terminal Control Support.
.CENTER
Table 10.
.BLANK 2
.TEST PAGE 4
.CENTER;MISCELLANEOUS EMT SUPPORT
.PARAGRAPH
Table 11 lists the routines that support the several miscellaneous
EMTs provided by TSX-Plus.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 11
.INDENT -8
ISPBLK##Determine the number of free blocks in the spool file.
.INDENT -8
ISPY####Return values from within the simulated RMON (SYSLIB rou-
tine).
.INDENT -8
ITSLIC##Determine the TSX-Plus license number.
.INDENT -8
ITSLIN##Determine the TSX-Plus line number.
.INDENT -8
MEMSET##Set the memory allocation.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
Miscellaneous EMT Support.
.CENTER
Table 11.
.BLANK 2
.TEST PAGE 4
.CENTER;ODT ACTIVATION MODE SUPPORT
.PARAGRAPH
ODT activation mode may be turned on and off from within a running
program.  Table 12 lists the routines that support this feature.
In this mode TSX-Plus considers all characters to be activation
characters except the digits, the comma, the dollar sign and the
semicolon.
.LEFT MARGIN +10
.RIGHT MARGIN -2
.BLANK
.TEST PAGE 5
.INDENT -8
RSRODT##Reset normal activation mode.
.INDENT -8
SETODT##Set ODT activation mode.
.LEFT MARGIN -10
.RIGHT MARGIN +2
.BLANK
.CENTER
ODT Activation Mode Support.
.CENTER
Table 12.
.BLANK 2
.TEST PAGE 7
.CENTER;REFERENCES
.BLANK 1
.LEFT MARGIN 12
.INDENT -4
1.##N.#A.#Bourgeois,#Jr., "TSXLIB -- A Library Implementation of the
TSX-Plus Programmed Requests", 11-490, DECUS/US Chapter Program
Library, Marlboro, MA, October 1982.
.BLANK
.TEST PAGE 3
.INDENT -4
2.##S#_&#H Computer Systems, Inc., "TSX-Plus Reference Manual",
Nashville, TN, December 1980.
.BLANK
.TEST PAGE 3
.INDENT -4
3.##S#_&#H Computer Systems, Inc., "TSX-Plus Version 2.2 System
Release Notes", Nashville, TN.
.BLANK
.TEST PAGE 3
.INDENT -4
4.##Digital Equipment Corporation, "RT-11 Programmer's Reference
Manual", AA-H378A-TC, Maynard, MA, March 1980.
.BLANK
.TEST PAGE 3
.INDENT -4
5.##S#_&#H Computer Systems, Inc., "TSX-Plus Version 3.0 System
Release Notes", Nashville, TN.
.BLANK
.TEST PAGE 4
.INDENT -4
6.##Robert B.#Denny, et al, "C Language System for RT-11", 11-513,
DECUS/US Chapter Program Library, Marlboro, MA, January 1982.
.BREAK