	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,ISTAT)	SPECIFY RMS KEY OF REFERENCE/
						SPECIFY RMS KEY BUFFER & SIZE
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,#ISTAT> SPECIFY RMS KEY OF REFERENCE/
						   SPECIFY RMS KEY BUFFER & SIZE
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.
 
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) ALL POSSIBLE RMS STATUS RETURNS (APPENDIX A, RMS-11 MACRO
		   PROGRAMMER'S REFERENCE MANUAL)
 
RECBUF	BYTE ARRAY TO SERVE AS THE RMS RECORD BUFFER.
 
RECSIZ	INTEGER*2 VARIABLE SPECIFYING THE SIZE (IN BYTES) OF RECBUF.
 
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.
 
KEYSIZ	INTEGER*2 VARIABLE SPECIFYING THE SIZE (IN BYTES) OF KEYBUF.

 
 
 
 
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 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
TAKE APPROXIMATELY 14K. MYPROG.BLD IS A PROTOTYPE TASKBUILD COMMAND FILE
WHICH YOU MAY COPY FROM [1,10] 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 [1,10] 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
