THIS DOCUMENT DESCRIBES THE USER INTERFACE TO THE 'RMSFTN' RUN-TIME SYS- TEM. IT IS PRESUMED THAT THE PROSPECTIVE USER IS WELL ACQUAINTED WITH RMS CON- CEPTS AS WELL AS THE RMS-MACRO INTERFACE AS DESCRIBED IN THE RMS-11 MACRO PRO- GRAMMER'S REFERENCE MANUAL. THE 'RMSFTN' RUN-TIME SYSTEM IS WRITTEN IN SUPERMAC. THE CALLS ARE VANILLA FLAVORED FORTRAN WITH ALL ARGUMENTS BEING PASSED AS PARAMETERS IN THE CALL LIST. THE 'RMSFTN' RUN-TIME SYSTEM SUPPORTS ONLY THE RMS INDEXED FILE ORGANIZATION AND ALL OPERATIONS ARE SYNCHRONOUS. ALTHOUGH RMS SUP- PORTS MULTIPLE ACCESS STREAMS TO A SINGLE FILE, THIS VERSION OF THE 'RMSFTN' IN- TERFACE SUPPORTS ONLY A SINGLE RECORD ACCESS STREAM PER FILE. THIS ARISES BE- CAUSE OF THE ASSOCIATION OF A RECORD ACCESS STREAM WITH A LUN AND THE INTERNAL ASSOCIATION OF A RECORD ACCESS BLOCK WITH A FILE ACCESS BLOCK. IN ORDER FOR THE USER TO IMPLEMENT THE CALLS LISTED BELOW HE SHOULD KNOW IN ADVANCE THE NUMBER OF INDEXED-SEQUENTIAL FILES THAT HIS (FORTRAN) TASK WILL ACCESS AS WELL AS THE IMPORTANT CHARACTERISTICS OF THESE FILES. ONCE THIS INFORMATION IS IN HAND HE SHOULD THEN CREATE A TAILORED VERSION OF RMSFTN.OLB FOR HIS TASK BY COPYING THE INTERACTIVE COMMAND FILE RMSFTN.CMD FROM [1,10] TO HIS DIRECTORY AND THEN INVOKING IT: >@RMSFTN . THIS COMMAND FILE WILL PROMPT THE USER FOR THE FILE CHARACTERISTICS NECESSARY TO TAILOR THE RUN-TIME LIBRARY. THE FILE RELATED QUESTIONS ARE AS FOLLOWS: 1) SUPPLY THE NUMBER OF RMS FILES TO BE OPEN SIMULTANEOUSLY 2) SUPPLY THE TOTAL NUMBER OF DEFINED KEYS ACROSS THESE FILES 3) SUPPLY THE SIZE IN BYTES OF THE LARGEST KEY ACROSS THESE FILES 4) SUPPLY THE TOTAL NUMBER OF CHANGEABLE KEYS ACROSS THESE FILES 5) SUPPLY THE MAXIMUM LUN ASSIGNED FOR THE TARGET TASK THE FORTRAN CALLS TO THE 'RMSFTN' RUN-TIME SYSTEM ARE AS FOLLOWS: CALL RMSOPE(LUN,FILSPC,IFAC,ISHR,ISTAT) OPEN THE SPECIFIED FILE CALL RMSCLO(LUN,ISTAT) CLOSE THE FILE - ANY CONNECTED RECORD ACCESS STREAM WILL BE AUTOMATICALLY DISCONNECTED PRIOR TO CLOSING THE FILE CALL RMSCON(LUN,KEYNUM,MODE,RECBUF,RECSIZ,ISTAT) CONNECT A RECORD ACCESS STREAM CALL RMSDIS(LUN,ISTAT) DISCONNECT RECORD ACCESS STREAM CALL RMSGET(LUN,IRFA,ISTAT) GET A RECORD CALL RMSPUT(LUN,IRFA,ISTAT) PUT A RECORD CALL RMSFND(LUN,IRFA,ISTAT) FIND A RECORD CALL RMSUPD(LUN,IRFA,ISTAT) UPDATE A RECORD CALL RMSDEL(LUN,ISTAT) DELETE A RECORD CALL RMSRWD(LUN,ISTAT) REWIND THE FILE CALL RMSRAC(LUN,MODE,ISTAT) SPECIFY RMS ACCESS MODE CALL RMSKEY(LUN,KEYNUM,KEYBUF,KEYSIZ,IROP,ISTAT) SPECIFY RMS KEY OF REFERENCE/ SPECIFY RMS KEY BUFFER & SIZE/ SPECIFY APPROXIMATE MATCH CALL RMSFRE(LUN,ISTAT) FREE A LOCKED BUCKET CALL RMSFLS(LUN,ISTAT) FLUSH AN I/O BUFFER THE SUPERMAC* CALLS TO THE 'RMSFTN' RUN-TIME SYSTEM ARE AS FOLLOWS: CALLG RMSOPE <#LUN,#FILSPC,#IFAC,#ISHR,#ISTAT> OPEN THE SPECIFIED FILE CALLG RMSCLO <#LUN,#ISTAT> CLOSE THE FILE - ANY CONNECTED RECORD ACCESS STREAM WILL BE AUTOMATICALLY DISCONNECTED PRIOR TO CLOSING THE FILE CALLG RMSCON <#LUN,#KEYNUM,#MODE,#RECBUF,#RECSIZ,#ISTAT> CONNECT A RECORD ACCESS STREAM CALLG RMSDIS <#LUN,#ISTAT> DISCONNECT RECORD ACCESS STREAM CALLG RMSGET <#LUN,#IRFA,#ISTAT> GET A RECORD CALLG RMSPUT <#LUN,#IRFA,#ISTAT> PUT A RECORD CALLG RMSFND <#LUN,#IRFA,#ISTAT> FIND A RECORD CALLG RMSUPD <#LUN,#IRFA,#ISTAT> UPDATE A RECORD CALLG RMSDEL <#LUN,#ISTAT> DELETE A RECORD CALLG RMSRWD <#LUN,#ISTAT> REWIND THE FILE CALLG RMSRAC <#LUN,#MODE,#ISTAT> SPECIFY RMS ACCESS MODE CALLG RMSKEY <#LUN,#KEYNUM,#KEYBUF,#KEYSIZ,#IROP,#ISTAT> SPECIFY RMS KEY OF REFERENCE/ SPECIFY RMS KEY BUFFER & SIZE/ SPECIFY APPROXIMATE MATCH CALLG RMSFRE <#LUN,#ISTAT> FREE A LOCKED BUCKET CALLG RMSFLS <#LUN,#ISTAT> FLUSH AN I/O BUFFER * SUPERMAC V46 OR HIGHER IS REQUIRED VARIABLE DEFINITIONS ARE AS FOLLOWS: LUN INTEGER*2 VARIABLE SPECIFYING THE LOGICAL UNIT NUMBER - MUST BE SUPPLIED FOR ALL CALLS. FILSPC BYTE ARRAY(MAX = 30.) CONTAINING THE FILESPEC AND TERMINATED BY A NULL BYTE. MUST BE SUPPLIED. IFAC INTEGER*2 VARIABLE SPECIFYING THE FILE ACCESS RIGHTS DESIRED IFAC = 0 READ ONLY ACCESS (GET AND FIND) = 1 EXTEND ACCESS (GET, FIND, AND PUT) = 2 MODIFY ACCESS (GET, FIND, AND UPDATE) = 3 WRITE ACCESS (GET, FIND, PUT, UPDATE, AND DELETE) IF THE ARGUMENT IS NULL, THEN THE RESULT IS THE SAME AS IFAC = 0. ISHR INTEGER*2 VARIABLE SPECIFYING THE SHARED ACCESS FLAG. ISHR = 0 NO SHARED ACCESS DESIRED = 1 SHARED ACCESS DESIRED IF THE ARGUMENT IS NULL, THEN THE RESULT IS THE SAME AS ISHR = 0. ISTAT INTEGER*2 VARIABLE FOR STATUS RETURNS - MUST BE SUPPLIED FOR ALL CALLS. POSSIBLE STATUS RETURNS ARE: 1) -1 NO LUN SPECIFIED 2) -2 FILE ALREADY OPENED/CLOSED 3) -3 INTERNAL ALLOCATION ERROR - PROBABLY TO MANY FILES OPEN 4) -4 ACCESS STREAM ALREADY CONNECTED/DISCONNECTED 5) -5 ILLEGAL KEY NUMBER FOR THIS FILE 6) -6 NO OPERATION POSSIBLE - NULL ARGUMENT OUT OF CONTEXT 7) -7 PUT OPERATION IN RFA MODE (IS ILLEGAL) 8) -8 ILLEGAL RECORD ACCESS MODE (PROBABLY BAD MODE PARAMETER) 9) -9 ILLEGAL (UNRECOGNIZED) FILE ACCESS RIGHTS REQUESTED 10) -10 ILLEGAL RECORD PROCESSING OPTION REQUESTED 11) ALL POSSIBLE RMS STATUS RETURNS (APPENDIX A, RMS-11 MACRO PROGRAMMER'S REFERENCE MANUAL) RECBUF BYTE ARRAY TO SERVE AS THE RMS RECORD BUFFER. MUST BE SUPPLIED. RECSIZ INTEGER*2 VARIABLE SPECIFYING THE SIZE (IN BYTES) OF RECBUF. MUST BE SUPPLIED. IRFA INTEGER*2 ARRAY DIMENSIONED @ 3 TO EITHER SUPPLY OR RECEIVE THE RECORD'S FILE ADDRESS DEPENDING ON CONTEXT. IN CERTAIN CONTEXTS THIS ARGUMENT MAY BE NULL: KEYED ACCESS OPERATIONS (MODE = 1). MODE INTEGER*2 VARIABLE SPECIFYING THE RECORD ACCESS MODE: 0 = SEQUENTIAL; 1 = RANDOM(KEY); 2 = RFA. IF THE ARGUMENT IS NULL IN THE CALL TO 'RMSCON', THE DEFAULT IS RANDOM(KEY) ACCESS. THE ARGUMENT MUST BE SUPPLIED IN THE CALL TO 'RMSRAC'. KEYNUM INTEGER*2 VARIABLE SPECIFYING THE KEY NUMBER OF REFERENCE, E.G. - 0 = PRIMARY; 1 = 1ST ALTERNATE; ETC.ETC. IF THIS ARGUMENT IS NULL IN THE CALL TO 'RMSCON', THE KEY OF REFERENCE WILL BE THE PRIMARY KEY BY DEFAULT. IF THIS ARGUMENT IS NULL IN THE CALL TO 'RMSKEY', THE KEY OF REFERENCE WILL BE UNCHANGED. KEYBUF BYTE ARRAY TO SERVE AS THE KEY BUFFER - MAY BE EQUIVALENCED IN RECBUF. MUST BE SUPPLIED. KEYSIZ INTEGER*2 VARIABLE SPECIFYING THE SIZE (IN BYTES) OF KEYBUF. MUST BE SUPPLIED. IROP INTEGER*2 VARIABLE SPECIFYING THE MATCH FACILITY DESIRED. IF THIS ARGUMENT IS NULL, THEN THE MATCH OPTION WILL BE UNCHANGED. IROP = 0 EXACT MATCH (DEFAULT) = 1 APPROXIMATE MATCH, .GT. = 2 APPROXIMATE MATCH, .GE. IN THOSE SITUATIONS WHERE NO STATUS RETURN IS POSSIBLE (INCORRECTLY FORMATTED CALL) THE 'RMSFTN' RUN-TIME SYSTEM WILL TAKE AN INTERNAL SST FAULT VIA A TRAP OR EMT INSTRUCTION. IN ORDER TO USE THE 'RMSFTN' RUN-TIME SYSTEM IT IS FIRST NECESSARY TO BUILD THE 'RMSFTN.OLB' BASE LIBRARY. THIS IS ACCOMPLISHED WITH THE INTERACTIVE COMMAND FILE 'RMSFTN.MAK'. THIS COMMAND FILE WILL ASSEMBLE ALL BASE LEVEL 'RMSFTN' COMPONENTS AND CREATE THE BASE LEVEL LIBRARY. THIS PROCESS REQUIRES THAT 'SUPERMAC' BE PRESENT IN LB:[1,1]RSXMAC.SML. 'SUPERMAC' V51 IS AVAILABLE ON THE DECUS TAPES IN [321,3]. SINCE 'RMSFTN' SUPPORTS ONLY THE INDEXED ORGANIZATION IT IS NECESSARY THAT THE PROSPECTIVE USER HAVE PURCHASED A LICENSE FOR 'RMS-11K' FROM DEC AND INSTALLED 'RMS-11K' IN HIS SYSTEM. WITH THE APPEARANCE OF DEC SUPPLIED RMS SUPPORT IN FORTRAN IV PLUS, IT SHOULD BE EMPHASIZED THAT 'RMSFTN' WAS ORIGINALLY INTENDED TO CO-EXIST WITH THE FCS BASED F4POTS IN THE FORTRAN IV PLUS ENVIRONMENT. THE DEC SUPPLIED FORTRAN IV PLUS RMS SUPPORT REQUIRES THAT THE USER SEL- ECT EITHER FCS OR RMS BASED FILE I/O. AT THIS JUNCTURE IT IS RECOM- MENDED THAT THE USER WHO CONTEMPLATES USING 'RMSFTN' SELECT THE FCS BASED FORTRAN IV PLUS OTS. IN ORDER TO LINK THE 'RMSFTN' RUN-TIME SYSTEM TO YOUR TASK IT IS NECESSARY TO HAVE A TAILORED RMSFTN.OLB IN YOUR DIRECTORY AND TO INCLUDE A REFERENCE TO THIS LIBRARY IN YOUR TASKBUILD COMMAND FILE. IN ORDER TO FACILITATE THE PROCESS OF TASKBUILDING YOUR TASK, SEVERAL PROTOTYPE TASKBUILD COMMAND FILES ARE AVAILABLE. MYPROG.CMD IS A PROTOTYPE TASKBUILD COMMAND FILE WHICH YOU MAY COPY INTO YOUR DIRECTORY FROM [1,10] AND EDIT ACCORD- ING TO THE INSTRUCTIONS CONTAINED IN THE FILE. THIS COMMAND FILE WILL BUILD YOUR TASK WITH AN UNOVERLAID RMS RUN-TIME SYSTEM WHICH WILL BE VERY FAST BUT SOMEWHAT WASTEFUL OF CORE. SUCH A TASK IS LIMITED TO APPROXIMATELY 18K WORDS BECAUSE THE RMS RUN-TIME SYSTEM AND THE FCS CORE RESIDENT LIBRARY (OPTIONAL) TAKE APPROXIMATELY 14K. OVERLAY.CMD IS A PROTOTYPE TASKBUILD COMMAND FILE WHICH YOU MAY COPY FROM [1,10] AND EDIT ACCORDING TO THE INSTRUCTIONS CONTAINED IN THE FILE. THIS COMMAND FILE WILL BUILD YOUR TASK WITH AN OVERLAID RMS RUN-TIME SYSTEM WHICH IS VARIABLE IN SIZE DEPENDING UPON WHICH DEC SUPPLIED RMS OVERLAY DESCRIPTOR FILE THAT YOU CHOOSE. IN ADDITION THERE IS THE OPTION OF OVERLAYING BOTH THE FCS COMPONENT AND THE 'RMSFTN' COMPONENT TO SAVE EVEN MORE VIRTUAL ADDRESS SPACE. THE FILES NECESSARY TO IMPLEMENT THESE VARIOUS OPTIONS ARE DETAILED BELOW: RMS11.ODL - DEC SUPPLIED RMS OVERLAY DESCRIPTOR (TAILORABLE) RMS11X.ODL - DEC SUPPLIED RMS OVERLAY DESCRIPTOR RMS12X.ODL - DEC SUPPLIED RMS OVERLAY DESCRIPTOR RMSFTN.ODL - OVERLAY DESCRIPTOR FOR 'RMSFTN' COMPONENTS FCS11M.ODL - OVERLAY DESCRIPTOR FOR FCS IN ORDER TO UTILIZE THESE OPTIONS IT IS NECESSARY TO COPY OVERLAY.CMD AND OVERLAY.ODL FROM [1,10] INTO YOUR DIRECTORY AND EDIT THEM ACCORDING TO THE INSTRUCTIONS CONTAINED IN THE FILES. IN ADDITION, IF YOU DESIRE TO OVERLAY 'RMSFTN' ITSELF, YOU SHOULD COPY RMSFTN.ODL INTO YOUR DIRECTORY AND EDIT IT TO ESTABLISH THE OVERLAY STRUCTURE FOR 'RMSFTN'. APG 4/21/80