	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
