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 MM:[311,6] 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 LINK THE 'RMSFTN' RUN-TIME SYSTEM TO YOUR TASK IT IS NECESSARY TO HAVE A TAILORED RMSFTN.OLB IN YOUR DIRECTORY AS DESCRIBED ABOVE 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 TASK- BUILD COMMAND FILES ARE AVAILABLE. MYPROG.NOV IS A PROTOTYPE TASKBUILD COM- MAND FILE WHICH YOU MAY COPY INTO YOUR UIC FROM MM:[311,6] 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 TAKE APPROXIMATELY 14K. MYPROG.BLD IS A PROTOTYPE TASKBUILD COMMAND FILE WHICH YOU MAY COPY FROM MM:[311,6] AND EDIT ACCORDING TO THE INSTRUCTIONS CON- TAINED IN THE FILE. THIS COMMAND FILE WILL BUILD YOUR TASK WITH AN OVER- LAID RMS RUN-TIME SYSTEM WHICH IS 6K IN SIZE AND SOMEWHAT SLOWER IN EXECU- TION. IN ORDER TO UTILIZE THIS COMMAND FILE IT IS NECESSARY TO COPY MYPROG.ODL AND RMS11M.ODL FROM MM:[311,6] INTO YOUR DIRECTORY AND TO EDIT MYPROG. ODL ACCORDING TO THE INSTRUCTIONS CONTAINED IN THE FILE. TASKS WHICH USE THIS TASKBUILD COMMAND FILE ARE LIMITED TO APPROXIMATELY 22K AGAIN BECAUSE OF THE SIZE OF THE RMS RUN-TIME SYSTEM AND THE FCS CORE RESIDENT LIBRARY. APG 6/5/78