WRITTEN BY: PAUL D. CLAYTON REPUBLIC MANAGEMENT SYSTEMS ONE NESHAMINY INTERPLEX , SUITE 306 TREVOSE, PA. 19044 Subj: Users Guide for the Simulated Tape Interface With Fortran IV Programs in the S-3A Software Generation Facility (SGF). Ref: (a) Multi-user Computing Facility-11 (MCF-11) Program Description Document (PDD) (b) Task Builder Reference Manual for RSX-11D 1. Discussion. The S-3A is tasked to support existing S-3A + ___________ operational and supporting software. This S-3A software requires the use of UYK-7 Compiler Monitor System (CMS-2Y). The PDP 11/70 interface software (MCF-11) allows CMS-2Y to store and retrieve emulated tape files on the PDP 11/70. In order to speed development of programs to manipulate these files resident on the PDP 11/70, a software interface program (SIMTAP) was written. This interface allows PDP 11/70 programs to perform all primary tape functions available in MCF-11 to CMS-2Y on these tape files. These operations can be done on up to five (5) unique tape files concurrently. This provides the capability to process CMS-2Y emulated tapes solely within the PDP 11/70 using any programming language resident on the PDP 11/70 supporting the Digital Equipment Corp. (DEC) standard calling sequence. 2. Conclusions. The development and execution times associated + ____________ with programs to manipulate emulated tape files is reduced by the multi-user and multi-tasking abilities of the PDP 11/70. Prepared By: Paul D. Clayton RMS TABLE OF CONTENTS + _____ __ ________ 1. System Description 1.1 Introduction 2. Capabilities 3. Using SIMTAP 3.1 Responsibilities of the User Program 3.2 Calling Sequence 3.3 Command Request Definitions 3.4 Returned Status Value Definitions 4. Opening Tape Files 5. Reducing Data Buffer Size on Tape Reads 6. Rewinding Tape Files 7. Error Reporting and Recovery 8. Reducing Size of SIMTAP When PDP 11/70 Program Task Size is Critical 9. Considerations When Task Building User Programs on the PDP 11/70 10. Receiving a Simulated Tape File Specification 11. Overlay Version of SIMTAP APPENDIX: A. Format of DEC Calling Sequence B. Logical Unit Usage By SIMTAP 1. System Description + ______ ___________ 1.1 Introduction + ____________ The interface program, named SIMTAP, is written in DEC Macro-11 assembly language. SIMTAP is linked in when the user program is task built to create a runnable task image. Command requests are sent to SIMTAP for execution and a status is returned indicating the success/failure in performing the request. Any emulated tape correctly created by the user will be readable through MCF-11 for further processing by CMS-2Y. 2. Capabilities + ____________ SIMTAP can access up to five emulated tape files concurrently. Any one of the five files can be opened for read or write. When reading or writing data records the maximium number of bytes per record is 2,147,483,647. The number of individual records within a tape file is unlimited for both read and write. When creating an emulated tape file the total size of the file depends on the amount of free storage on the disk volume. When reading an emulated tape file their is no restriction on the total size of the file. 3. Using SIMTAP + _____ ______ Fortran IV-PLUS is the primary installation language in the SGF. Therefore all referances to SIMTAP will be using the syntax and rules of Fortran IV-PLUS. Do not confuse SIMTAP logical unit numbers with PDP logical units. Refer to Appendix B for details. 3.1 Responsibilities of the User Program + ________________ __ ___ ____ _______ The user must determine ahead of time the maximum data buffer size for reading and writing records, and allocate the needed space within his/her program. The user must also remember the standard CMS-2Y sequence for ending a tape file, namely that two (2) tape marks (TM) followed by an end of tape (EOT) mark is needed on tapes being created for reading by CMS-2Y. The minimum ending sequence is an EOT mark to ensure that MCF-11 will maintain program integrety when reading your tape file. SIMTAP automatically writes an EOT mark when the tape file is closed. 3.2 Calling Sequence + _______ ________ To request a function of SIMTAP, the user program statement takes the following form. CALL SIMTAP (COM,LU,BUF,TYP,CNT) All five parameters in the list of passed variables must be specified for all requests even though they may not contain valid data. The variables must be passed even if they are in common storage within the user program. Paramaters passed to SIMTAP are defined below. The variable type for each parameter must be adhered to without exception. Parameter Type and Function + _________ ____ ___ ________ COM I*2; Each command request has an associated ID number, defined in section 3.3. This parameter must be valid on all requests. LU I*2; Identifies which of the five tape files the operation is to performed on. In the standard configuration this parameter can have values of 1 to 5 inclusive. This parameter must be valid on all requests. BUF Any varaible type is valid; Specifies the address where the data is to be read into or written from. This parameter does not have to be valid on all requests. TYP I*2; Informs the requestor of the success/failure and error conditions in performing the request. This parameter is always valid on return from SIMTAP. CNT I*4; Specifies the number of bytes to be read or written from/to the buffer specified in "BUF" parameter. See section 5. for special use of "CNT" when reading tapes. Upon return the number of bytes read/written is passed back to the requestor. This parameter does not have to be valid for all rquests. 3.3 Command Request Definitions + _______ _______ ___________ The command request ID is passed to SIMTAP in the "COM" parameter. Following is a table of the valid request ID numbers and their function, also included is a list of parameters that must be valid before calling SIMTAP. ID Number Function + __ ______ ________ 0 Open tape file for read only. See section 4. for specifics. Valid Parameters (VP)=COM,LU,BUF ID Number Function + __ ______ ________ 1 Open tape file for write only. See section 4. for specifics. VP=COM,LU,BUF 2 Read record from tape file. See section 5. for special use of this command VP=COM,LU,BUF,CNT 3 Write data record to tape file. VP=COM,LU,BUF,CNT 4 Write tape mark to tape file. VP=COM,LU 5 Write physical end of tape mark (EOT) to tape file. VP=COM,LU 6 Close tape file and keep it for future use. VP=COM,LU 7 Close tape file and delete it from the disk volume. VP=COM,LU 8 Back-up one record in tape file. See section 6. for specifics. VP=COM,LU 9 Return a complete file specification in the user buffer for a logical unit. See section 10 for specifics. VP=COM,LU,BUF 3.4 Returned Status Value Definitions + ________ ______ _____ ___________ A status is returned to the user in the "TYP" parameter. These status values can indicate if SIMTAP was successful in processing the request or if it failed. On failure the value will show a general cause of failure. A table listing the values that are returned, their meaning and the valid parameters on return is below. ID Number Meaning + __ ______ _______ 0 FATAL error on file access. Refer to + _____ section 7. for details of error recovery. Valid Parameters (VP)=COM,LU,TYP 1 Tape mark (TM) was detected on read request. No data is put into the buffer specified in the "BUF" parameter. VP=COM,LU,TYP ID Number Meaning + __ ______ _______ 2 Data record was read from tape file. Data is in buffer specified in the "BUF" parameter. Refer to section 5. for special use of the read request. VP=COM,LU,BUF,TYP,CNT 3 Physical end of tape (EOT) was read on tape file. VP=COM,LU,TYP 4 Tape file is opened. It could be for read or write access. VP=COM,LU,TYP 5 Tape file is closed. The file may have been kept or deleted depending on the request. VP=COM,LU,TYP 6 Tape write was successful. This covers the writing of TM, EOT and data records to the tape file. VP=COM,LU,TYP 7 Illegal logical unit number was specified in the request. No action is taken on any tape file. VP=COM,BUF,TYP,CNT 8 Illegal command request ID number specified in the request. The ID number is not defined in SIMTAP. No action is taken on the tape file specified. VP=LU,TYP,BUF,CNT 9 Error in file name specification on open tape file request. Refer to section 4. for details of opening tape files. VP=COM,LU,BUF,TYP,CNT 10 Tape file already open for access on the logical unit specified in the "LU" parameter. No action is taken on the tape file. VP=LU,BUF,TYP,CNT 11 Beginning of tape (BOT) mark was detected on tape back-up request. Further back-up requests will return with the BOT status. VP=COM,LU,BUF,TYP,CNT ID Number Meaning + __ ______ _______ 12 NON-FATAL file access error. Trying to + _________ write to a file opened for read or vice versa will result in this error. Refer to section 7. for recovery. VP=COM,LU,TYP 13 File specification is in the "BUF" parameter. See section 10 for details. VP=COM,LU,BUF,TYP,CNT 4. Opening Tape Files + _______ ____ _____ The file name is user specified in a buffer of the users choice. The file name itself must be followed by at + ____ least one ASCII space (040 octal). The default file specification is DB0:[201,201]TEMP.TAP;X where X is the highest version number when the file is opened. An example of the Fortran statements to read a file spec. from a terminal and open a tape file is as follows: C SET UP THE ARRAY TO HOLD THE FILE NAME. THE MAX. C SIZE OF THE FILE SPEC IS 33 CHARACTERS. C IE. DB2:[201,201]MSIZEFORT.CMD;377777 C INTEGER*4 NAME(9) C C CLEAR OUT THE NAME ARRAY TO ALL BLANKS C DO 10 I=1,9 10 NAME(I)=' ' C C NOW READ IN THE FILE SPEC FROM TERMINAL C READ (5,15)NAME 15 FORMAT(9A4) C C NOW OPEN UP THE SIMULATED TAPE FILE C CALL SIMTAP (0,1,NAME,STAT,BYTES) C C IF THE FILE OPEN IS IN ERROR GOTO ERROR ROUTINE C IF (STAT.NE.4) GOTO 900 C C OTHERWISE CONTINUE PROCESSING C . . . . After the file has been opened the file name is no longer needed for any command request including the close tape file request, which only needs the "COM" and "LU" parameters to be valid. If the user does not need the file name after the request to open, the buffer which contains the file name can be the buffer which is used for read/write data requests. This technique saves memory space if task size is critical. When opening tape files for read or write the file pointer points to the first record of the file. A read request is needed to determine the type of the first record if the file is opened for read access. If a tape file is opened for write then the first write requested becomes the first record in the tape file. If a non-fatal error, returned status of 12, occurs on the open request, the disk file is not opened for access. The SIMTAP logical unit number is available for reuse. If a fatal error occurs, returned status of 0, the SIMTAP logical unit number is unusable. See section 7. for details of error recovery. If a write is requested on a tape file opened for read only or vice versa, a returned status of 12, non-fatal file access error, is put in the "TYP" parameter. No action is taken on the file itself. Further requests of the correct class can be performed on the file without any impact from this error. 5. Reducing Data Buffer Size on Tape Reads + ________ ____ ______ ____ __ ____ _____ When reading data records, the value in the "CNT" parameter can help reduce the size of the buffer needed to hold the data. When the user program is developed, the size of the buffer to contain the data should be made only as large as required to obtain the data needed from the data records. For example, if the data you need is in the first 500 bytes of the data records, dimension the data buffer to the size needed, INTEGER*2 DATA(250). Before SIMTAP is called to read the data records, set the "CNT" parameter to 500. This way if the data record is 2000 bytes long, the first 500 bytes will be placed in the user buffer specified in the "BUF" parameter. The remaining 1500 bytes are skipped over and the file is readied for the next command request. If the data record contains only 250 bytes, these are placed in the user buffer and the "CNT" parameter is adjusted to show the true count of bytes transfered, 250. "CNT" should always be set to the maximium number of bytes that will fit in the user buffer BEFORE calling SIMTAP. + ______ This insures that the needed data is read into the user buffer and that the data does not overrun the size of the buffer causing data/program corruption. 6. Rewinding Tape Files + _________ ____ _____ When using the backup one record request the type of record skipped over is returned to the user in the "TYP" parameter. The three possible values are TM, BOT and data records. If a read record request follows a backup record request, the read will be of the record just skipped over. The diagram below shows the file pointer AFTER each step in the following sequence of requests to SIMTAP. REQUEST RETURNED STATUS 1) read record data 2) read record TM 3) read record data 4) backup one record data 5) backup one record TM 6) read request TM ------------------------------------------------------------------ DATA |TM | DATA |TM | DATA |TM | ------------------------------------------------------------------ ^ ^ ^ ^ starting pt. 1 2 3 of file ptr. 5 4 6 7. Error Reporting and Recovery + _____ _________ ___ ________ There are two (2) classes of errors associated with SIMTAP, Fatal & Non-Fatal. Non-Fatal errors are those that have no impact on future requests to SIMTAP on the logical unit in error. Examples of non-fatal errors would be sending an illegal logical unit number to SIMTAP, or writing to a tape file opened for read access. The recovery for non-fatal errors is for the user to correct the parameter in error and resubmit the request to SIMTAP. Fatal errors are those associated with SIMTAP trying to read/write the tape file on disk. When a fatal error occurs a message stating the problem and the file specification the error occured on is printed to the terminal that invoked the user program. For example, the error message would appear as FILE WAS NOT PROPERLY CLOSED FPC=-38 DB0:[201,201]TEMP.TAP;2 It is up to the user, and the help of SGF cognizant personel if needed, to determine the cause and remidy for the problem. As for recovery within the user program on fatal errors, trying to close the tape file is the only option. If the close was successful the returned status is 5. The disk file still has problems but SIMTAP has seperated itself from the file and the logical unit can be reused for another file. If the close was unsuccessful, the returned status is 0. At this point the file is still associated with SIMTAP on the logical unit number. The logical unit number becomes unavailable for further use. The PDP 11/70 operating system will seperate the file from SIMTAP when the user program ends processing and exits memory. 8. Reducing Size of SIMTAP When PDP 11/70 Program Task Size is + ________ ____ __ ______ ____ ___ _____ _______ ____ ____ __ Critical + ________ The limit on a task image size in the PDP 11/70 is 64k bytes. The standard SIMTAP object module is about 8.7k bytes in size. If the task size is over the limit, SIMTAP can be reduced in size. This reduction should be done by someone with Macro-11 experience only. Following is the order in which the reduction should take place and the memory storage freed. A) Eliminate logical units that are not used. For example, if your program deals with two tape files, eliminate logical unit numbers 3,4 and 5. The storage saved is approximately 600 bytes per logical unit. The parameters that have to be changed in SIMTAP are as follows: 1) MAXLU - Adjusted to new maximium logical unit number. 2) Comment out LUFDB macros for unused logical units. 3) Remove entries in FDBPTR table for LUFDB macros commented out. B) Eliminate full error processor. This affects the output of fatal error messages to the terminal. For example, FILE WAS NOT PROPERLY CLOSED FPC=-38 DB0:[201,201]TEMP.TAP;2 would no longer appear. The fatal error status will still be returned to the user program. Storage saved is approx. 3.2K bytes. The modifications to SIMTAP are as follows: 1) Comment out "MSSG:" routine, replacing it with a program stub. For instance, MSSG: RETURN ;DO IMMEDIATE RETURN 2) Comment out the file name routine "FILNAM:" 3) Comment out the error message table "ERRMSG:" 9. Considerations When Task Building User Programs + ______________ ____ ____ ________ ____ ________ The number of active files and the maximium number of logical unit numbers must be increased above the defaults if all 5 tape files are used in SIMTAP. The number of active files is determined by adding the number of standard FORTRAN files, including the line printer as a file, with the number of files being used by SIMTAP. For example, if the Fortran program was using the logical units 1,2,5,6 and SIMTAP was using logical units 1,2,3 and 4, then the statement in the command file for the number of active files would be: ACTFIL=8 Normally, each active file has its own logical unit number associated with it. Using the example above then, the statement presented to the task builder is: UNITS=8 Refer to the Task Builder Reference Manual for further details of the options available. Appendix B contains the PDP logical unit assignments used in SIMTAP. An example of a task build command file is as follows. SIMTST,SIMTST/-SP=SIMTST,[11,206]SIMTAP,[1,1]F4POTS/LB / ACTFIL=8 UNITS=8 // These constraints apply to the example above. 1) SIMTST is the object module for the user program created by the FORTRAN IV-PLUS compiler. It is also the name given to the task image and mapp file. 2) SIMTAPE is the object module for the SIMTAPE program created by using the MACRO-11 assembler. 3) [1,1]F4POTS/LB is the FORTRAN IV-PLUS object time system. If F4P is the default FORTRAN than this parameter can be left out. 10. Receiving a Simulated Tape File Specification + _________ _ _________ ____ ____ _____________ A simulated tape file must be open on the logical unit specified. The file spec. placed in the user buffer will be in the following format. DB2:[350,351]ADP1.OBJ;5 The length of the file spec. in bytes (characters) is placed in the "CNT" parameter upon return. Asking for a file spec. on a logical unit that does not have an opened tape file associated with it results in a returned status of 12 (non-fatal file error). There is no impact on the file pointers by this command request under any conditions and can be issued any time the tape file is open. 11. Overlay Version of SIMTAP + _______ _______ __ ______ If reducing the size of SIMTAP following the procedures outlined in section 8 does not yield the necessary size reduction, using overlays may be the answer. SIMTAP has been broken into two (2) segments for use in overlays. Segment 1 = SIMTRT - Root segment Segment 2 = SIMTBR - Branch segment SIMTRT contains all data structures for processing requests and MUST be in the root segment. SIMTBR contains + ____ the code required to process the command requests. SIMTBR can be placed in a branch of your choice. Advance planning must be taken when placing the buffer specified in the "BUF" parameter in the root segment or in the same branch as SIMTBR. If the buffer is in a branch, it may be overwritten by another branch being loaded in to execute. If the buffer is in the root segment, the size of the root segment may be large enough to cause address overflow when the branches are linked in with the root segment at task build. SIMTRT and SIMTBR, together, have the same capabilities as SIMTAP. Reducing the size of SIMTRT and SIMTBR can be accomplished following the procedures in section 8. This reduction should only be done by someone with MACRO-11 experience. APPENDIX A + ________ _ Format of DEC Calling Sequence Register 5 is used as a stack pointer to a table of addresses for the parameters passed to a subroutine. For example the call statement: CALL SIMTAP (COM,LU,BUF,TYP,CNT) would result in register 5 pointing to a table constructed as follows: address of "CNT" parameter address of "TYP" parameter address of "BUF" parameter address of "LU" parameter address of "COM" parameter R5> number of items passed = 5 (octal) All entries are addresses to each parameter except for the first, and all entries are one (1) word in length. Any programming language can use SIMTAP as long as register 5 is set up in the format shown above. APPENDIX B + ________ _ Logical Unit Usage By SIMTAP The following PDP 11/70 logical unit numbers are used in SIMTAP. SIMTAP Logical Unit No. -- PDP 11/70 Logical Unit No. 1 7 2 8 3 9 4 10 5 11