A Library Implementation of Programmed Requests for TSX/TSX-Plus N. A. Bourgeois, Jr. Sandia National Laboratories Systems Engineering Division 1738 P. O. Box 5800 Albuquerque, NM 87185 Abstract A library of FORTRAN callable subroutines that implement EMT's provided by TSX/TSX-Plus is described. Calling sequences, library building procedures and source codes are given. 80j13b Page 1 16 Oct 80 This document is issued by Sandia National Laboratories, operated for the United States Department of Energy by Sandia Corporation. Notice This document was 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 sponsored and funded by: Headquarters, ESD / OCB / Stop 36 Hanscom Air Force Base, MA 01731 Page 2 16 Oct 80 Introduction When application programs are executed under a time sharing executive, such as TSX or TSX-Plus [1,2], certain capabilities become desirable if not absolutly essential. These capabilities relate to requirements for such things as hardware dependent I/O, shared files and inter-program communication. Both TSX and TSX-Plus provide a number of programmed requests or EMT's for this purpose. This paper describes a number of FORTRAN callable subroutines and their calling sequences that implement these EMT's. All of the routines are written in MACRO-11 [3]. They provide facilities that permit files to be shared, that allow running programs to communicate with each other, that determine the TSX line number and that determine the amount of free space available in the spool file. Procedures for building a library of these routines are also presented [4]. Source code is given in the appendix. Communication Subroutines MSGCOM.MAC Three subroutines provide the facilities that allow running programs to communicate with each other. These message communication facilities allow programs to send messages through named channels, check to see if any messages are pending and to suspend execution until a message is received. Suitable error codes are returned as required. The calling sequence is as follows: CALL XXXXXX (CHNAME,MSGBUF,MSGSIZ,IERR) Where: XXXXXX Subroutine name as follows: SNDMSG Send a message. RCVMSG Receive a message, return if none pending. RCVMSW Receive a message, wait for one if none pending. Page 3 16 Oct 80 CHNAME Six ASCII character name of the message channel. Must be six characters, backfill with spaces if necessary. MSGBUF Name of the string array containing the message. MSGSIZ Message length in characters. IERR Error code returned as follows: 0 No error. 1 All message channels busy. 2 Maximum allowed number of messages. 3 No message is pending on the named channel. 4 Message was too long and was truncated to maximum length. Shared Files RCDLOK.MAC Four subroutines provide record locking facilities that are useful in situations where programs being run from several terminals wish to update a common file. Through these record locking facilities a program may gain exclusive access to one or more blocks in a file. Other programs attempting to lock the same block(s) will be denied access until the first program releases the locked block(s). Suitable error codes are returned as required. The calling sequence is as follows: CALL XXXXXX (ICHN[,IBLK],IERR) Where: XXXXXX Subroutine name as follows: SHRFIL Declare a shared file. LKBLK Lock a block, return if already locked. LKBLKW Lock a block, wait if already locked. UNLBLK Unlock all locked blocks. ICHN Channel number open to the file. Page 4 16 Oct 80 IBLK Number of the block to be locked. Required for LKBLK and LKBLKW only. IERR Error code returned as follows: 0 No error. 1 Channel not open to a file. 2 Too many channels opened to shared files. 3 Too many shared files opened. 4 Channel not open to a shared file. 5 Request to lock too many blocks. 6 Requested block is locked by another user. Miscellaneous Subroutines TSXMSC.MAC The first of these subroutines is used to determine if TSX is running and if so the TSX line number. It returns a single positive integer value to the calling program. If TSX is not running the value returned is zero. If TSX is running the value returned is the TSX line number. The second subroutine determines the integer value of the number of free blocks available in the spool file. Neither routine returns any error codes. The calling sequence is as follows: CALL XXXXXX (IVAL) Where: XXXXXX Subroutine name as follows: TSXTST Determine the TSX line number. SPLBLK Determine the number of free blocks. IVAL The integer value returned. Page 5 16 Oct 80 Library Building TSXLIB.COM The following outlines the procedures to build and use the several subroutines in a library format. RT-11 command strings to assemble the routines and build them into a library are given. Also shown are command strings to compile an application program and link it with the library. .RUN MACRO *MSGCOM[,LP:/C]