.!
.!	To extract the information from this manual
.!	use the utility program INDEX.
.!
.V General procedure, macro reference and utility manual
.C General information
.T Disclamer
 
 
 
 
 
 
 
 
 
 
 
	***********************************************************
	*                                                         *
	*       DIGITAL EQUIPTMENT COMPUTER USERS SOCIETY,        *
	*             DIGITAL EQUIPMENT CORPORATION               *
	*          AND THE SUPPLIERS OF SUCH PROGRAMS             *
	*   DISCLAIM ALL WARRANTIES ON THE PROGRAMS INCLUDING     *
	*     WITHOUT LIMITATION, ALL IMPLIED WARRANTIES OF       *
	*        MERCHANTABILITY AND FITNESS FOR PURPOSE.         *
	*                                                         *
	***********************************************************
 
.T Introduction





	The routines described in this document were developed to :-



(1)	Simplify I/O techniques for new users and to reduce program
	writing for experienced programmers.

(2)	Introduce character/text handling facilities which CORAL and
	MACRO.

(3)	Produce simplified/compatable ASCII/binary binary/ASCII conversion
	routines working in any base from 2 to 36.

(4)	Enable software to be written quickly when using the XY plotter
	and allow the plotter to be available to languages which have
	no plotter commands.

	The MACRO software was developed to enable fast program writing
	and to incorporate high level English language type commands
	to be available to the MACRO assembler.

	In general the reference numbers indicate the filenames used
	the extention will be either .COR or .MAC ; for example
	REFNO/MODULE L13A can be found in file L13A.COR note single
	digit numbers will have leading zeros always attached.

	Procedure types are indicated as so :-
	INT indicates an 'INTEGER''PROCEDURE'
	BYTE indicates a 'BYTE''PROCEDURE;
	FLO  indicates a 'FLOATING''PROCEDURE'

	All modules starting with the letters MCnn and the CORAL
	procedures with the same name are functionally identical but
	the MCnn modules are in general smaller or faster but usually
	both.


.F
.I BASLIB
.I MAC.OLB
.I MAC.MLB
.I CONFIG
.I GENDEF
.I MACBIO
.I MG0
.I RSX
.I RT-11
.I IAS





For RT-11 users please ignore all references to CORAL as this is
not an option with RT-11 systems.For an RT-11 system filenames
the same but in some cases may have been reduced to 6 letters.

All the CORAL procedures mentioned in this document can be found
in the library			[200,25]BASLIB.OLB (IAS/RSX)

All the MACRO procedures mentioned in this document can be found
in the library			[200,25]MAC.OLB (IAS/RSX)
					MAC.OLB (RT-11)

All CORAL macros required for CORAL library procedures may be
found in file			[200,25]MACBIO.COR

All CORAL definitions required for CORAL library procedures
may be found in file		[200,25]GENDEF.COR
All MACRO macros required for MACRO library procedures may be
found in library		[200,25]MAC.MLB (IAS/RSX)
					MAC.MLB (RT-11)

Most MACRO definitions and presets can be found in the file/s
				[200,25]MG0.MAC (IAS/RSX) or
				[200,25]CONFIG.MAC (IAS/RSX)
					MG0.MAC or CONFIG.MAC (RT-11)

All Sources may be located on magnetic tapes 150 and 151 the volume
identity for these tapes is COMMON. (CAA ATCEU only)
ie. to load tape :-
MESS PLEASE LOAD MAGNETIC TAPE 150 OR 151  FOR READ ACCESS
MOUNT/PROC:MM0ACP MM: COMMON







.C CORAL PROCEDURES
.T CORAL general information

.I BAS
Library declaration for CORAL macros is as follows
'LIBRARY' BAS;

	(Any procedure reference number marked with a * symbol)
	(indicates the sources are written in both MACRO and CORAL.)
 
.I GENDEF
To avoid confusion with general reply the file GENDEF.COR has
been created for CORAL programmes therfore the replys will in
the future be related to the macro reply name rather than the
actual value. Some of the CORAL procedures now give a status
reply as well performing the original function to assist with
programme development and error detection.


.T CORAL String functions.
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I LEN
.I L01
LEN 	L01*	INT	This procedure will reply with the length
			of then named character string
			USAGE	X:=LEN(STRING);
 
.I COMPARE
.I L02
.I SAME
COMPARE	L02*	INT	This procedure compares two character strings
			and then answer given are :-
			-1 if first string less than  second string or shorter
			0  if first string same as     second string
			+1 if first string greater than second string or longer
			usage  'IF' COMPARE (STRING1,STRING2) CONDITION
				'THEN' ACTION;
			The MACRO reply SAME may be used.
 
.I SEG
.I L03
SEG	L03*	INT	This procedure presents a segment of a character
			string.
			The parameters of the procedure are :-
			SEG(STRING,START POS,END POS);
			First parameter string to be accessed.
			Second parameter start access position.
			Third parameter end of access position.
			This procedure replies with the address of the segment
			of the master input string.
			USAGE 'IF' COMPARE (SEG(STRING,START,END),CHECKSTRING)
				CONDITION 'THEN' ACTION;
			USAGE COPY (SEG(STRING,START,END),STRING SEGMENT);
 
.I LSEG
.I L03A
LSEG	L03A*	INT	As per L3 but internal local use only.
 
.I COPY
.I L04A         
.I SUCCESS
.I ERROR
COPY	L04*	INT	This procedure copies one string to another
			string location.
			Note automatic bounds checking takes place when
			copying	strings therefore writing past the end
			of a string not possible and excess characters
			will be lost the limit is specified when the
			string is initially made.
				N.B.  The very first two bytes hold the length
				of the array. second two bytes hold the
				number of characters in the string, this
				is also where the string address is
				referenced to.
			usage COPY(FROM STRING,TO STRING);
			The MACRO replys ERROR or SUCCESS are given.

.F
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I POS
.I L05
POS	L05*	INT	This procedure checks if a sub string exists
			within a master string. If the sub string is
			not present within master string then the procedure
			will reply zero. If the sub string does exit
			within the master string then this procedure
			will answer with the position of the first
			occurrence of the sub string.
			usage 'IF' POS(MASTER STRING,SUB STRING,STARTPOSITION)
				condition 'THEN' action;
			usage  X:=POS(MASTER STRING,SUB STRING,STARTPOSITION);
 
.I LPOS
.I L05A
LPOS	L05A*	INT	As per L5 but local internal use only.
.I COMSORT
.I L28 
.I COMPARE

COMSORT L28	INT	This procedure behaves in a similar way to the
			COMPARE procedure.
			It has been designed to allow the user to compare
			character strings of differing length.
			The shortest string length specifies the length of
			comparison  area + one character which is set
			as zero for decision purposes when all characters
			in the comparison area are the same.
			Usage	as per compare procedure 
 
.T CORAL String alter or modify.
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I ADD
.I L06
ADD	L06	INT	This procedure adds(appends) one string to another
			string the answer given is the address of the
			combined string if new string exceeds 255 characters
			end characters are lost.
			usage  X:=ADD(MASTER STRING,ADD ON STRING);
 
 
.I ADD TO
.I L16
.I SUCCESS
.I ERROR
ADD TO 	L16*	INT	This procedure appends the second string to 
			first string loading the resulting string into
			the first string
			usage 	ADD TO (MASTER STRING,ADD ON STRING);
				master string now equals master string
				plus add on string
			The MACRO reply ERROR or SUCCESS may be used. 
 
.I FILL
.I L19
.I SUCCESS
.I ERROR
FILL	L19	INT	This procedure fills a string to a pre set point
			with the character specified in parameter list
			usage FILL(STRING,19,WITH CHARACTER);
			example fill a string with spaces to tab point 25
				FILL(A STRING,25,A SPACE);
			The MACRO reply ERROR or SUCCESS may be used. 
 

         
.I CLEAR
.I L21
.I SUCCESS
.I ERROR
CLEAR	L21*	INT	This procedure resets a string to a length of
			of zero characters and resets all characters in
			string to zero.
			Note count is taken from max buffer parameter in
			string
			usage  CLEAR(ADOLLAR);
			The MACRO reply ERROR or SUCCESS may be used. 
 
.I TABMOD
.I L37
TABMOD	L37		This procedure replaces all tabulation characters
			in a string with the correct number of space
			characters.

			USAGE TABMOD (string to modify);
.F
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I TABLOAD
.I L24
TABLOAD L24	INT	This procedure acts as a special string which allows
			the user to load characters into any position within
			the string.
			Parameters:- tab load(position,character string);
			the procedure offers the following facilities
				(A) The address of the internal held string.
				(B) The ability to alter the internally
				    held strings length.
				(C) The insertion of chars into the string.
				(D) The ability to fill the internally held
				    string with spaces.
			information about this procedure
			(1)	If position =-1 the procedure answers with the
				address of the internally held string.
			(2)	If position is 0 the internal string
				is set to all spaces.
			(3)	If position is -2 then the value of
				character string is now used as an integer
				to specify the length of the internal string
				the value is limited to the range 1 to 255.
			(4)	Normal mode is when position = access position
				in the character string to be accessed.
				and character string is the address of a
				character string.
			NOTE	If character string parameter is not required
				it should be set to either -1  or 0.
 
 
			USAGE
				X:=TAB LOAD(-1,0); (X = ADDRESS OF STRING)
				TAB LOAD(-2,127); (CHAR STRING LENGTH = 127)
				TAB LOAD(0,-1);   (CHAR STRING NOW ALL SPACES)
				TAB LOAD(9,"ABCD");(ABCD LOADED INTO STRING)
						   (FROM POSITION 9)
 
 
 
.F

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I CHARVER
.I L29
.I SUCCESS
CHARVER L29	INT	This procedure checks that all the characters in the
			slave string exist in the master string.
			Note:- charver means 'CHARACTER VERIFY'
			If all character exist then the procedure answers +0
			if any character in the slave string does not exist
			in the master string then the procedure answers with
			a negative value corresponding to the position of the
			failed value.
				NB. -6 would indicate that the character in
				position 6 is in error and caused the check
				to fail.
			USAGE
			Example check if all characters read from an input
				message are valid.
			ie:	Valid numeric character for ASCII
				numeric conversion
				'IF' CHARVER("0123456789.E",INPUT STRING)
				= SUCCESS
				'THEN' NUMERIC STRING IS VALID
				'ELSE' ASK TO REINPUT STRING AGAIN;
			GENERAL FORMAT
			RESULT:=CHARVER(MASTER STRING,SLAVE STRING);
				'IF' CHARVER(MASTER STRING,SLAVE STRING)
				     CONDITION
				'THEN' ACTION;
 
.I MULS
.I L30
 
MULS	L30	INT	This procedure will present a string containing a
			number of repeats a sub set string.
			this procedure can hold a maximum of 255 characters,
			excess characters will be lost during the string
			multiplication.
			FORMAT		MULS(SUBSTRING,NUMBER OF REPEATS);
			USAGE
				COPY(MULS("*",12),STRING1);
				WITH THIS EXAMPLE STRING1 = ************

.F

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I SRP
.I L32
SRP	L32	INT	This procedure replaces one string for another string
			located in a master string a number of times.
			The new string generated is then passed to the answer.
			parameters :-
			ANSWER:=SRP(MASTER,CHANGE FROM,CHANGE TO,N TIMES);
			usage:-
			ANSWER=SRP(AAA,BBB,CCC,NNN);
			IF NNN <0 NO ACTION TAKES PLACE.
			IF NNN =0 CHANGE ALL OCCURRENCES OF BBB TO CCC IN AAA.
			IF NNN >0 CHANGE BBB TO CCC IN AAA NNN TIMES.
			X:=SRP("ABCCCCDE","C","?",0); (X="AB????DE")
			X:=SRP("ABCCCCCDE","C",-1,4); (X="ABCDE")
			note -1 may be used as a void field;
.I CYPHER
.I L33

CYPHER	L33	INT	This procedure allows the user to convert a character
			string from one code set to another code set.
			Uses of this procedure could be say converting upper
			case characters to lower case characters or maybe
			some sort of security arrangement to stop other users
			being able to read the contents of each character
			string.
			Parameters
			REPLY STRING:=CYPHER(FROM,TO,ITEM TO CODE);
			Usage X:=CYPHER("ABCDE","12345","ABACF");
			X WOULD = 1213F
			NOTE UNFOUND CHARACTERS NOT CONVERTED.
 
.I SHIFT
.I L34 
 
SHIFT	L34		Ths procedure is not yet written


.F

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I SPLIT
.I L35
SPLIT	L35	INT	This procedure extracts sub fields in character
			strings any number of characters may be used as the
			field splitting delimiters.
			The procedure will reply SUCCESS if a character string
			has been extracted and ERROR if the operation has
			failed.
			Usage STATUS:=SPLIT(master,split reply,seperator);
			Where 'master'  is the character string containing
			a number of sub fields.
			      'split reply' is the group of characters
			extracted from the master character string.
			NOTE the 'split reply' will be removed from the 
			'master' character string along with the seperator
			character group of characters.
			      'seperator/s' are the character/s used to 
			terminate a sub character group in a master
			character string.


.I SPLITS
.I L35A
SPLITS	L35A	INT	This procedure extracts sub fields within
			character strings.
			This procedure differs from SPLIT in that
			the seperator character string consists of
			a series individual seperator characters
			each character will be checked in turn to
			locate where the sub character group is to
			be split and the delimiter character nearest
			to the start of the main character string will
			be chosen as the delimiter.
			The delimiter and sub character group will both
			be deleted from the master string
			EXAMPLE of use
			where MASTER contains the following characters
				A,B;C.D;E
			      SEP contains the following characters
				.;,
			instruction SPLITS(MASTER,ANS,SEP);
				Content of strings
			MASTER		ANS		SEP 	REPEAT
			B,C.D;E		A		.;,	1
			C.D;E		B		.;,	2
			D;E		C		.;,	3
			E		D		.;,	4
					E		.;,	5


.T CORAL General function procedures.

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
 
.I CLOCK
.I L23
CLOCK	L23	INT	This procedure works as a stop watch
			***********************
			NOT PRESENTLY AVAILABLE
			***********************


.I ASK
.I L36
ASK	L36	INT	This procedure enables the user to ask a question
			with a selected number of replys and until one
			of the selected replys is entered the procedure
			will continue to re-prompt.
			The formal parameters are :-
			'INTEGER''PROCEDURE'
			ASK ('INTEGER''ARRAY','VALUE''INTEGER');
			The integer array should take the form
			'IA" anslist [0:n]:=<string reply>,<answer value>
			terminated by 0,0;
			eg. 'IA' axx [0:5]:="yes",1,"no",2,0,0;
			USAGE REPLY := ASK(anslist,"Run again YES/NO");

.T CORAL TERMINAL I/O ROUTINES         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I VDU
.I L07/A/B 
VDU   L07/A/B*	INT		PART ONE OF TWO
			This procedure uses QIO transfer procedures to
			access vdu display and vdu keyboard.
			The first parameter specifies the mode of working:=
			ie; "O" = output a string of characters.
			    "I" = input a string of characters.
			   "I@" = input with no echo.
			   "I-" = input with no prompt.
		     "(NUMBER)" = read number characters only.
			   "NL" = output a newline at end of output
			  "PRE" = output a preceding newline before string.
			  "END" = ending newline same as "NL".
			"CLEARS"=clear screen cursor set to top lefthand side.
			"CLEARL"= clear all character to end of line
			"CLEARE"= clear all character to end of screen.
			   "CR" = output a carriage return no line feed.
			   "LF" = line feed but no carriage return.
			  "REF" = set cursor to top left hand side of screen.
			  "RET" = as per "CR"  but after output of string.
			  "SHUT"= Deallocates the lun from the vdu.
			or any combination maybe used ie; "IO" "IONL" "INL"
			"PREOINL" "PRE,O,I,END" "END  I O,PRE" ETC.
			Note spaces and other separators used for
			readability only.
 
 
			Second parameter holds the address of output string
			if it is set to 0 or -1 then string is assumed
			that it does not exist therefore 0 or -1 should be
			used when it is a dummy parameter.
 
 
			SEQUENCE OF EVENTS.
			------------------
			The system allocates the vdu channel if dealocated
			Then the order of events is fixed and are either:-
				special cursor control.
			Or any one from each of the following lines:-
				clears,cleare,clearl.
				Set cursor to reference home position.
				Output a preceding newline.
				Output a string.
				Input a string with control variations.
				Output an ending newline.
				Output an ending carriage return.
				Shut dealalocates the vdu channel.
.F
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I VDU
.I L07/A/B
VDU	L07/A/B* INT		PART TWO OF TWO
 
			Special cursor control allow the user to access
			any position on the VDU screen.
			Parameters are :-
			VDU("SETCUR",COLUMN VALUE *256 +LINE VALUE);
			An alternative method is:-
			'INTEGER' REFERENCE;
			'OVERLAY' REFERENCE 'WITH' 'BYTE' 'ARRAY' LC[0:1];
			'OVERLAY' LC[0] 'WITH' 'BYTE' LINE;
			'OVERLAY' LC[1] 'WITH' 'BYTE' COLUMN;
			then for use .....
				LINE := 5; COLUMN := 65;
				VDU("SETCUR",REFERENCE);
			Will cause the cursor to be moved to line    5
			Will cause the cursor to be moved to column  65
			Note in this mode a string cannot be output
			But a string may be input after cursor movement.

			Usage  VDU(CONTROL STRING,TRANSFER STRING);
			Usage  X:=VDU(CONTROL STRING,TRANSFER STRING);
			Usage  X:=VDU(CONTROL STRING,-1 OR 0);(INPUT ONLY)
			Usage  VDU(CONTROL STRING,CURSOR POSITION);
			Usage  X:=VDU(CONTROL STRING,CURSOR POSITION);
 
 
.I VDULUN
.I L07G 
 

VDULUN	L07G	INT	This procedure allows the user to redefine the
			logical unit number associated with the vdu/terminal
			If a LUN is already allocated to the terminal the
			LUN will be released , this procedure will then
			allocate the specified lun number to the terminal.
			This procedure may also be used to interrogate
			which lun is allocated to the terminal.
			usage	X:=VDULUN(0);  This request the lun number.
			usage	VDULUN(5); This allocates lun 5 to the VDU.

.F
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I VDUSP
.I L07D
VDUSP	L07D	INT	This procedure will perform the same actions as
			the VDU procedure but the following extra options
			are available:-
				These options only effect the input
				sequence.
 
				"I*" This allows input, but the procedure
				     does not wait for the input to occur.
				     to check if the input has occured the
				     following method must be used.
				        X:=VDU("?",-1);
				        note if input not occurred answer is-1
					     if input has occurred answer is
					        the address if the string
				        'IF' X=-1 'THEN' NO INPUT
					'IF' X<>-1'THEN' X:=ADDRESS OF STRING
				     Please note that the "?" mode inhibits
				     all other mode of operation.
				usage:
					VDUSP("I* O","INPUT CHAR TO STOP");
					LOOP: PERFORM OPERATION;
					'IF' VDUSP("?",-1)=-1 'THEN''GOTO'LOOP
.I SYS
.I L07S
 
SYS	L07S	INT	This procedure allows the user to read the
			value of a single character from the users 
			terminal. This procedure will not echo the
			character to the terminal.
			Usage A:=SYS(1);
			Note the parameter value (1) is used to indicate
			what type of function is required.
			Note only value (1) is allowed.

 
.I INKEYS
.I L07I
INKEYS	L07I	INT	This procedure allows the user to read a characters
			from the users terminal with character echo. This
			procedure will not wait as with the SYS (1) function
			and unlike the SYS(1) function this procedure answers
			in string format. If no character has been recieved
			on the users terminal then this procedure will
			reply with a string with no charcters in it.
			USAGE A:=INKEYS;   (HOLD STRING ADDRESS)
			USAGE
				'IF' LEN(INKEYS)=0 'THEN' ... 'ELSE' ...

.F
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I TERMINAL
.I L27
TERMINAL L27		This procedure allows special options to be set on the
			VDU terminal.
			the options are as follows:-
				"UCO"   UPPER CASE OUTPUT
				"LCO"   LOWER CASE OUTPUT
				"UCI"   UPPER CASE INPUT
				"LCI"   LOWER CASE INPUT
				"HD"    HALF DUPLEX MODE
				"FD"    FULL DUPLEX MODE
			the default options are "UCO,UCI,HD".
			this procedure allows you to do the same action as
			a set terminal operation under PDS control.
			Usage
				TERMINAL(CONTROL STRING);
				WHERE (CONTROL STRING) may be any one or more
				of the above options seperated by a comma if
				more than one option required.
			eg;	TERMINAL("LCO,LCI,FD");
 
.T CORAL General device procedures.
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I RT04
.I L07C/E/B
RTO4	L07C/E/B INT	This procedure has a similar function to the VDU
			procedure but rather than accessing your VDU it will
			drive any RTO4 channel of your choice.
			At the time of writing we have two choices of RTO4
			device, to be able to select which version of RTO4
			we wish to use (type0) is the old version and
			(type1) the new style RTO4.
			We must be able to distinguish because they have
			different code sets on some of the special functions.
			Any mode offered by the VDU procedure is permissable
			with the RTO4 procedure.
			This procedure has the following extra facilities :-
			MODE=			ACTION
			"ASSIGN"	Assign RTO4 channel where string holds
					the device name ie; "TT51:".
					it is at this point that we select
					which type of RTO4 we wish to use ie;
					"ASSIGN TYPE0"  OR "ASSIGN TYPE1"
					"ASSIGN TYPE0" is the default option.
					ie; "ASSIGN" = "ASSIGN TYPE0".
			"ASSIGN INPUT" device for input only.
			"ASSIGN OUTPUT"device for output only.
					The above modes used when input and
					output required on different channels.
			"OVER"		This option used with "ASSIGN" it
					stops the display being initialised.
			"CB"	Cursor begin.
			"CE"	Cursor end.
			"FB"	Flash begin.
			"FE"	Flash end.
		       "DSB"	Double size begin.   (type0 only)
		       "DSE"    Double size end.     (type0 only)
		       "RVB"    Reverse video begin. (type1 only)
		       "RVE"    Reverse video end.   (type1 only)
		       "FLASH"  Output string flashing at start.
				flashing stops at end.
 
		       NOTE1 IF "DSB" OR "DSE" USED WITH TYPE1 RTO4 THIS
				procedure assumes you required reverse video
				option likewise with "RVB" AND "RVE" type0
				RTO4 assumes double size characters required.
			NOTE2	As with the VDU procedure the special set
				cursor or assign device modes of operation
				no other function is allowed.
			NOTE3	With type1 RTO4s 4 pages are available to
				select which page to use when using
				"SETCUR" command.
				second parameter = column*256+page*64+line.
				usage as per VDU procedure.
 
			Formal parameters of RTO4 procedure.
			INPUT REPLY:=RTO4(CONTROL MODE,OUTPUT STRING);
.T CORAL String numeric conversion routines.

NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I STR
.I L08
STR	L08	INT	This procedure produces a string result from
			a floating point number in either a fixed
			format or unformated.
			Note 0 or -1 as control format means unformat option.
			format string take same form as
				CORAL PROCEDURE FCHAR IE. "F10.3".
			Usage	X:=STR(FORMAT STRING,FLOATING VALUE);
			Usage	X:=STR(-1,21.4);
			Usage	X:=STR("F10.3",99.8E-2);
 
.I VAL
.I L10 
VAL 	L10*	FLO	This procedure converts a string into a floating
			point number using any base from 2 to 36, the default
			assumed to be base 10.
			The following values are all considered to be valid by
			this procedure using base 10 :-
			.01	0.01E-1 +0.01	-0.01	-1E+5	+1E-5	5.2
			-.5	5	+.5	ETC.

			To use other bases the base required is enclosed
			in (brackets) and appended to the string to be
			converted as so :-
				OCTAL	1767(8)
				HEX	AB01F(16)
				DECIMAL 55.09(10)	or 55.09 by default
				BINARY	10011(2)
			Note the base value always described using base 10.
			Note the use of a non base 10 value does not inhibit
			the use of either the + sign - sign or fractional
			point operator,
			ie. these are valid numbers +10.11(2) -EF.C(22)
			Usage	X:=VAL(STRING);
 
.T CORAL String to non numeric convert procedures.

NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
 
.I ASC
.I L09
ASC	L09	BYTE	This procedure replys with the value of the
			first character held in specified string
			usage	X:=ASC(STRING);
			Usage	C:=ASC("B");	(INTEGER C = 66)

.I RADASC
.I L25
RADASC	L25	INT	This procedure converts three ASCII chars
			into a signed integer in RAD50 code
			answer to this procedure take the form
			bit 0 set char 1 is not permissable RAD50 character
			bit 1 set char 2 is not permissable RAD50 character
			bit 2 set char 3 is not permissable RAD50 character
			ie; if answer value =7  all chars not converted
		            if answer value =5 chars 1 and 3 not converted
			    if answer value =0 then operation successful
			usage:-
				RADASC(CHAR1,CHAR2,CHAR3,RESULT);
				'IF' RADASC(4 PRAMS)=0 'THEN' OPERATION OK
				'ELSE' BIT INDICATES INVALID CHAR;
			Note this procedure also can be found in CORALIOPROCS

.I R50ASC
.I L25A 
R50ASC	L25A	INT	This procedure converts three ASCII characters in
			the form of a string into a signed integer in
			RAD50 code.
			If any of the characters in the string are not
			valid RAD50 characters this procedure replies
			with the value -1 which is a non translateable
			RAD50 code.
			If the input string exceeds 3 characters only
			the first 3 characters are used.
			Usage A:=R50ASC("ABC");

.I ASCRAD
.I L26
ASCRAD  L26	INT	This procedure converts a signed integer (RAD50 CODE)
			into three ASCII characters.
			If answer not zero then translation not performed
			correctly all characters must be suspect
			usage:-
				ASCRAD(CHAR1,CHAR2,CHAR3,TRANS VALUE);
				'IF' ASCRAD(4 PRAMS)<>0'THEN' OP FAILED
				'ELSE' OPERATION OK;
			Note this procedure also can be found in CORALIOPROCS
 
.I ASCR50
.I L26A
ASCR50	L26A	INT	This procedure converts a signed integer in RAD50
			code into three ASCII character. If the input value
			cannot be translated correctly this procedure answers
			with the value -1 a correct translation this procedure
			answers with the address of the converted string.
			Usage A:=ASCR50(RAD50 code);

.T CORAL String convert Binary to ASCII.

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I CVT
.I L31
CVT	L31	INT	This procedure converts a floating point number into
			ASCII code. Its action is similar to FCHAR procedure
			in CORALIOPROCS but with this procedure you have the
			option of selecting what base you wish to work in.
			The base range is 2 to 36 the default base is
			assumed to be 10.
			sequence 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ.
 			ie. base 16 = 0123456789ABCDEF.
			The parameter of this procedure are as follows :-
				CVT(FORMAT STRING,NUMBER TO BE CONVERTED)
			the format string is declared as follows :-
			select base to work in		(base)
			output format			####.###
				Note 1  # sign indicates where a converted
					character is to be placed.
					decimal point specifies where decimal
					point is to be placed.
					If the number input is negative you
					will need an extra # for the - sign.
					if the number input will not fit in
					the specified format string all
					numeric slots will be filled with
					* characters.
					Spaces will be filled into any unused
					slots in integer part of format string
					zeros will be filled into any unused
					fraction slots.
					If a 0 character is places in the
					format string unused slots preceding
					first integer will be filled
					with zeros.
			USAGE X:=CVT("(2)############",NUMBER);
			number converted to base 2 field width 12 characters
			usage X:=CVT("(2)0######.##",15.5);
			output would be 001111.10 base 2 zero precede.
			usage X:=CVT("(2)######.##",15.5);
			output would be   1111.10 base 2 space precede.
 
.T CORAL File device control routine.

NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I FILE
.I L15
.I SUCCESS
.I ERROR

FILE	L15	INT		PART ONE OF TWO

			This procedure will open/close or close all
			files opened by this procedure
			if this procedure answers -1 operation requested
			has failed to be performed, an error report will
			also be generated by default with the procedure
			waiting for an input indicating the report has
			been acknowledged.
			The files that can be opened/closed have
			a range 3 to 14 at time of writing although
			this range may be extended at a later date.
			parameters :-  (file lun number) (mode)(name)
			mode :-
				"SHUTDOWN" WILL CLOSE ALL OPEN FILES.
					   LUN and NAME may be defaulted
					   using -1.
				"CLOSE" WILL CLOSE FILE SPECIFIED BY LUN.
				"KILL"  WILL DESTROY FILE IF THE FILE IS
					OPEN.
					If the file is closed and a name
					is specified then this procedure will
					open the file then destroy it.
					If the file is closed and no name
					is specified then the procedure will
					request you to input a filename then
					the procedure will destroy the file
					that you have specified.
				"?"	This option allows you to check
					if a file is open or closed.
					reply answers as follows :-
.I ALLOCATED
.I FREE
						FREE	  = file closed
						ALLOCATED = file open
				"NOSTOP"	If this mode is selected the
					procedure will not wait for an input
					after an error report has been output.
				"NORPT" 	If this mode is selected
					neither the internal error reporting
					system or the wait after error
					condition will be performed.
				"OPEN INPUT"
					Will open a file for input
				"OPEN OUTPUT" or
				"OPEN OUTPUT FIXED(30)"
					Will open a file for output. If fixed
					is used output records fixed at
					length in brackets (IE 30).


.F

NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------
.I FILE
.I L15
.I SUCCESS
.I ERROR

FILE	L15	INT		PART TWO OF TWO
.I DEVICE
.I UIC
.I FILENAME
			NAME :-	Is the 'DEVICE' : 'UIC' 'FILENAME' of the
				device to be used when opening for output
			sequence of events :-
				shutdown or close or open
			the effects of shutdown or close
				close
				release
				exit
			the effects of open
				deflun
				open/create
				exit
			The MACRO's SUCCESS and ERROR indicate if the
				procedure has operated corectly.
			Usage	FILE(UNIT NUMBER,MODE STRING,FILENAME);
			Usage  'IF' FILE(FILE NUMBER,MODE,FILENAME)
				<> SUCCESS 'THEN'
				ASSUME OPERATION HAS FAILED;

.T CORAL File device input/output routines.
         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I FILEIN
.I L11
.I ERROR
.I ERR
.I EOF
FILEIN L11	INT	This procedure reads a record from a device
			set up by the file procedure
			and converts it into a valid string variable.
			possible answers from this procedure:-
					address of string
					EOF if end of file
					ERR or ERROR if other errors
			usage 	X:=FILEIN(FILE NUMBER);
 
.I LFILEIN
.I L11A
.I ERROR
.I ERR
.I EOF 
LFILEIN L11A	INT	This procedure works in a similar manner to filein
			but rather than using an internal data area the
			receiver data area is specified as a parameter.
			possible answers from this procedure:-
					EOF if end of file.
					ERR or ERROR if other errors.
			PARAMETERS	X:=LFILEIN(FILE NUMBER,STRING NAME);
			USAGE	X:=LFILEIN(FILE NUMBER,STORE AREA);
				   LFILEIN(FILE NUMBER,STORE AREA);

.I COPY
.I FILEIN
			NOTE LFILEIN(3,AS) SAME AS COPY(FILEIN(3),AS);

.I BLOCKIN
.I L11B
.I ERR
.I ERROR
.I EOF
BLOCKIN	L11B	INT	This procedure reads a block from a device
 			set up by the file procedure
			and converts it into a valid string variable.
			Possible answers from this procedure:-
					Address of string
					EOF If end of file
					ERR or ERROR for other errors
			Usage X:=BLOCKIN(device number);

.I LBLOCKIN
.I L11C
.I ERROR
.I ERR
.I EOF
LBLOCKIN L11C	INT	This procedure works in a similar manner to blockin
			but rather than using an internal data area the
			receiver data area is specified as a parameter.
			Possible answers from this procedure:-
					 0 if success
					EOF if end of file.
					ERR or ERROR for other errors.
			Parameters	X:=LBLOCKIN(devicenumber,string name);
			Usage X:=LBLOCKIN(device number,store area);
			      LBLOCKIN(device number,store area); (no checks)
			Note  LBLOCKIN(3,AS) same as COPY(BLOCKIN(3),AS);

.I FILEOUT
.I L12
.I SUCCESS
.I ERROR
FILEOUT  L12	INT	This procedure transfers a string in record
			form to output device set up by procedure file.
			The MACRO's SUCCESS or ERROR indiacte if the
			operation succeded.
			Usage  FILEOUT(FILE NUMBER,STRING TO TRANSFER);
 
.I BLOCKOUT
.I L12A
.I SUCCESS
.I ERROR
BLOCKOUT L12A	INT	This procedure transfers a string in block
			form to output device set up by procedure file.
			The MACRO's SUCCESS or ERROR indiacte if the
			operation succeded.
			Usage   BLOCKOUT(DEVICE NUMBER,STRING TO TRANSFER);

.T CORAL STRING PRESET ROUTINES         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I CHR
.I L13
CHR	L13	INT	This procedure presents a 'VALUE''BYTE' as
			a string of length 1
			Usage  X:=CHR(ASCII CHARACTER VALUE);
			Usage  CHR(12) =  (FORM FEED CHARACTER)
 
.I QUOTE
.I L14
 
 
QUOTE	L14	INT	This procedure presents a string of length 1
			and its contents is a quote (') character
			as it is difficult to insert a (') char in
			a literal string
			usage use instead of a ' CHARACTER
 
 
.I A SPACE
.I L17
 
A SPACE	L17	INT	This procedure replies with the address of a string
			containing a single space
			usage  practical example
				ADD TO (MASTER STRING,A SPACE);
			now master string equals master string plus a space
 
.I A TAB
.I L18
A TAB    L18	INT	This procedure replies with the address of a string
			containing a single tab
			usage as per 	(A SPACE) procedure
 
 
.I CRLF
.I L20 
CRLF     L20	INT	This procedure replies with the address of a string
			containing a cr plus a lf
			usage as per (A SPACE) procedure
 
 
.I DAT
.I L22 
DAT      L22	INT	This procedure presents a character string of the
			date in the form day/month/year
			usage as per (A SPACE) procedure
.I UIC
.I L22A
 
UIC	L22A	INT	This procedure present a character string of the
			user identity code in the form [group,member]
			that you are presently logged into.
			Usage as per (A SPACE) procedure.

.I CLK
.I L23 
CLK	L23	INT	This procedure presents a character string of the
			time in the form  hours:minutes:seconds
			usage as per (A SPACE) procedure
 
.T CORAL XY Plotter routines.

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I TXT
.I P01
TXT	P01		This procedure plots the contents of a character
			string to the XY PLOTTER.
			Usage TXT(angle of text,size of text,text);
			Where size of text is an integer value in the
			range 1 to 12. The size number refers to a
			multiplying factor of size times 0.7 cms for
			height and width of the characters.
			The angle of text specifies what angle the characters
			will be drawn at.

.I MOV
.I P02

MOV	P02		This procedure moves the XY PLOTTER pen to the
			X,Y position relative to the origin which is fixed
			as X=0 and Y=0 ie the bottom left hand corner of
			the paper.  All X and Y values in cms.
			If the X value is negative then rather than an
			XY position being specified this procedure assumes
			the coordinates are RADIUS/THETA movement relative
			to the present pens position.
			Note a negative X is forced to a positive radius
			value in cms and Y value assumed to be degrees.
.I PLT
.I P03

PLT	P03		This procedure works in a similar manner to the
			MOV procedure but rather than just moving the
			pen this procedure draws a line between the
			pens start position and the parameter X,Y values.

.I CIR
.I P04
CIR	P04		This procedure draws a circle about the position
			is complete
			Usage CIR(radius in cms);
.I RED
.I P05

RED	P05		This procedure selects the red pen for plotting.
			Usage RED;
.I BLK
.I P06

BLK	P06		This procedure selects the black pen for
			plotting.
			Usage BLK;

.I RTH
.I P07
RTH	P07		This procedure converts R/THETA values to
			X,Y values.
			Local internal use only.

.F

         
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I DTOR
.I P08
DTOR	P08		This procedure converts degrees to radians
			Local internal use only.

.I ARC
.I P09
ARC	P09		This procedure draws a segment of a circle around
			the position the pen is initially positioned
			and returns the pen to the centre of the arc
			when the drawing is complete.
			Usage ARC(arc radius,center angle,width in degrees);

.I DEV
.I P10
DEV	P10		This procedure draws the outline to scale of
			number of semiconductor devices.
			ie 8 pin ICs 14 pin DIL transistor cases
			resistors and capacitors.
			*********************
			NOT YET AVAILABLE
			*********************
.I ARR
.I P11

ARR	P11		This procedure draws an arrow head, suitable
			for dimensioning diagrams.
			USAGE  ARR(size,angle arrow head points);

.I SQR
.I P12
SQR	P12		This procedure draws a square centred about
			the position the pen is initially positioned
			on completion of the drawing the pen is
			returned to the initial position.
			USAGE  SQR(length of a side);
.I PLS
.I P13

PLS	P13		This procedure draws a plus symbol or crossing
			axis.
			USAGE  PLS(size of symbol);

.I CRS
.I P14

CRS	P14		This procedure draws a cross symbol.
			USAGE  CRS(size of symbol);

.I CCT
.I P16
CCT	P15		This procedure draws a sketch of a piece of
			vero-board with matrix 0.1 inches, the output
			can be used to plan the layout of circuits.
			USAGE  CCT(width of board,length of board);
			************************
			NOT YET AVAILABLE
			************************

.I SIZE
.I P16
SIZE	P16		This procedure allows the user to enlarge
			or reduce the size of the plot being output.
			USAGE  SIZE(multiplication factor);

.I NEWFRM
NEWFRM			This procedure causes the plotter to form
			feed to a new page to plot on.
			This procedure is part of the system main
			plotter library.
			USAGE  NEWFRM;

.C CORAL Debug and Error procedures.
.T Introduction

	These routines are written in MACRO 11 to interface and
	be used with CORAL 66 programmes run under the IAS system.
	The INTEGER/STRING routines are aimed to be used for
	error reporting and quick diagnostics prompts but only
	introducing minimal code overheads as compared with the
	TIDEF group of instructions ie. SINPUT IINPUT SPRINT IPRINT
	use approx octal 400 bytes + 100 bytes in PSECT $$DEVT in total
	where as TIDEF group will use 200 bytes in PSECT $$DEVT
	in PSECT $FSCR1 2040 and in PSECT $$IOBF will use 430 bytes
	this excludes any store requirement used by the code itself
	it can therfore be seen that when store space is at a preimum
	these routines will be very useful.
	A further set of routines have been developed to analyise the
	status of memory management data arrays and report the status
	of the DSW in plain language.
	For convenence these routines are held in the library
	[200,25]BASLIB but before you use them you must make the formal
	declarations in your programme to these procedures.

.I BASLIB
.I CORAL 66
.I MACRO 11
.I SINPUT
.I IINPUT
.I SPRINT
.I IPRINT
.I TIDEF
.I PSECT
.I $FCSR1
.I $$IOBF
.I $$DEVT
.I DSW
.T Procedure facilities.

NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I SPRINT
.I M04
SPRINT	M04		This procedure displays a character string onto the
			users terminal.
			PARAMETERS
			SPRINT ('VALUE''INTEGER','VALUE''INTEGER');
			SPRINT (LUN,STRING TEXT);
			USAGE SPRINT (1,"HAPPY DAYS ARE HERE AGAIN");

.I IPRINT
.I M04
IPRINT	M04		This procedure displays a signed integer result
			on the users terminal.
			PARAMETERS
			IPRINT ('VALUE''INTEGER','VALUE''INTEGER');
			IPRINT (LUN,VALUE TO DISPLAY);
			USAGE IPRINT (2,44);
			USAGE IPRINT (1,AN INTEGER);

.F
NAME	REFNO.	TYPE		DESCRIPTION
----	-----	----		-----------

.I SINPUT
.I M04
SINPUT	M04	INT	This procedure reads a character string from the
			users terminal and replys with the address of the
			character string. A maximum of 80 characters is
			allowed on any entry tho the string may be terminated
			by either the escape or return keys.
			PARAMETERS
			'INTEGER''PROCEDURE' SINPUT ('VALUE''INTEGER');
			'INTEGER''PROCEDURE' SINPUT (LUN);
			USAGE
			STRING ADDRESS := SINPUT (1);

.I IINPUT
.I M04
IINPUT	M04	INT	This procedure read a character string from the
			users terminal the converts the string into a
			signed integer value illegal characters are
			ignored and no status replys given for overflow
			etc.
			'INTEGER''PROCEDURE' IINPUT ('VALUE''INTEGER');
			'INTEGER''PROCEDURE' IINPUT (LUN);
			USAGE
			VALUE INTEGER := IINPUT (1);


.C MACRO Routines.
.T STRING CHECK AND LOCATE GROUP

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$POS 
.I MR05
R$POS3		MR05	This procedure locates the position of a search
			string within a master string starting from a
			requested character position.


			ENTRY POINTS
			+0		Match characters exact
			+2		Match same for upper/lower case

			ENTRY CONDITIONS
			R1 ->	MASTER STRING
			R2 ->	SEARCH STRING
			R0 =	START POSITION OF SEARCH

			EXIT CONDITIONS
			SEE R$POS

.I R$POS2
.I MR05
R$POS2		MR05	This procedure locates the position of a search
			string within a master string always starting
			from the first character in the master string.


			ENTRY POINTS
			+0		Match characters exact
			+2		Match same for upper/lower case

			ENTRY CONDITIONS
			R1 ->	MASTER STRING
			R2 ->	SEARCH STRING

			EXIT CONDITIONS
			SEE R$POS

.I R$POS
.I MR05
R$POS		MR05	This procedure is a common routine for R$POS3 and
			R$POS2 it locates the position of one string within
			another string.

			ENTRY CONDITIONS
			R3 R4 AND R5 MUST BE SAVED
			R1 ->	MASTER STRING ADDRESS
			R2 ->	SEARCH STRING ADDRESS
			R0 =	START POINT IN STRING TO SEARCH FROM

			EXIT CONDITIONS
			R0 =	POSITION OF FIRST CHARACTER
				IF MATCH FOUND
			R0 =	ZERO IF NO MATCH FOUND
			EXITSUCCESS IF MATCH FOUND
			EXITERROR   IF MATCH NOT FOUND

.F


NAME		MODULE			DESCRIPTION
----		------			-----------
.I R$COMPARE
.I MR11 

R$COMPARE	MR11	This procedure compares the contents of two character
			strings and indicates if the strings are the same or
			how they differ.

			ENTRY POINTS
			+0		Match characters exact
			+2		Match assume upper/lower case same

			ENTRY CONDITIONS
			R1 ->	STRING A
			R2 ->	STRING B

			EXIT CONDITIONS
			IF (STRING A) IS LESS THAN OR SHORTER
			THAN (STRING B)	R0=-1
			IF (STRING B) IS LESS THAN OR SHORTER
			THAN (STRING B)	R0=1
			IF BOTH STRINGS ARE THE SAME
			R0 = 0
			THE STATUS INDICATOR ALSO INDICATES IF THE STRINGS
			ARE THE SAME
			EXITSUCCESS IF STRINGS THE SAME.
			EXITERROR   IF STRINGS DIFFERENT.




.T Character string alter modify group

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$ADDTO
.I MR12 
R$ADDTO		MR12	This procedure appends(adds) one string to
			a master string.

			ENTRY CONDITIONS
			R1 ->	MASTER CHARACTER STRING
			R2 ->	STRING TO APPEND

			EXIT CONDITIONS
			R1 ->	MASTER CHARACTER STRING
			R2 ->	STRING THAT HAS BEEN APPENDED

.I R$CLEAR
.I MR13
R$CLEAR		MR13	This procedure clears out a character string.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING

			EXIT CONDITIONS
			STATUS = SUCCESS IF OPERATION IS SUCCESS
.I R$DELETE
.I MR04
R$DELETE	MR04	This procedure deletes a number of characters in a
			string

			ENTRY CONDITIONS
			R1 ->	MASTER STRING
			R2 =	THE START POSITION WHERE DELETION IS TO START
			R3 =	THE NUMBER OF CHARACTERS TO DELETE

			EXIT CONDITIONS
			R1 ->	THE MODIFIED MASTER STRING
.I R$REVERSE
.I MR07


R$REVERSE	MR07	This procedure reverses all the characters held
			in a character string.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING TO BE REVERSED

			EXIT CONDITIONS
			R0 ->	CHARACTER STRING



.F


NAME		MODULE			DESCRIPTION
----		------			-----------
.I R$SEG
.I MR14
 
R$SEG		MR14	This procedure extracts a segment of a character
			string minimum size one character to maximum size
			of the string being processed.

			ENTRY CONDITIONS
			R1 ->	INPUT STRING
			R2 =	START POSITION
			R3 =	END   POSITION
			R4 ->	OUTPUT STRING

			EXIT CONDITIONS
			R4 ->	THE EXTRACTED STRING
			(NOTE THE INPUT STRING IS LEFT UNMODIFIED)


.I R$WEDGE
.I MR06
R$WEDGE		MR06	This procedure inserts/wedges one string into
			a second string.

			ENTRY CONDITIONS
			R1 ->	MASTER STRING
			R2 ->	STRING TO INSERT
			R3 =	THE CHARACTER POSITION TO INSERT THE
				STRING AFTER

			EXIT CONDITIONS
			R1 ->	THE MODIFIED MASTER STRING
 
.I R$PAD
.I MR16

R$PAD		MR16	This procedure pads out a string with a spec-
			-ified character and by a specified number of
			characters. Alternatively if the character
			count is '0' then it with fill up the remain
			-der of the string

			ENTRY CONDITIONS

			R0 ->	ADDRESS OF STRING.
			R1 =	NUMBER OF CHARS TO PAD WITH.
			R2 = 	CHARACTER TO PAD WITH.

			EXIT CONDITIONS

			Success or error.


.T Character string shift routines

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I R$SHRE
.I MR08
R$SHRE		MR08	This procedure shifts the contents of a character
			string one character right end around.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS

			EXIT CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS


.I R$SHR
.I MR10
R$SHR		MR10	This procedure shifts the contents of a character
			string one character place right.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS
			R3 =	FILLER CHARACTER

			EXIT CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS

.I R$SHL
.I MR10
R$SHL		MR10	This procedure shifts the contents of a character
			string one character place left.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS

			EXIT CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS

.I R$SHLE
.I MR09
R$SHLE		MR09	This procedure shifts the contents of a character
			string one character left end around.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS

			EXIT CONDITIONS
			R0 ->	CHARACTER STRING ADDRESS


.T Preset routines

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$CLK
.I MR20
R$CLK		MR20	This procedure replies with a character string
			giving the time of day in the following format
			HH:MM:SS .

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	STRING ADDRESS HOLDING THE TIME

.I R$DAT
.I MR20
R$DAT		MR20	This procedure replies with a character string
			giving the date in the following format
			DD-MM-YY .

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	STRING ADDRESS HOLDING THE DATE

.I R$UIC
.I MR19
R$UIC		MR19	This procedure replies with a character string
			giving the default UIC the present running is
			working under in the following format
			[ggg,mmm] .

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	STRING ADDRESS HOLDING THE UIC

.T Binary value to character string convert routines

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I R$BBIN
.I MR02
R$BBIN		MR02	This procedure converts a sixteen bit binary word into
			a significant zero string of ASCII characters using
			base two.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE		WORD ENTRY +0
							BYTE ENTRY +2
			EXIT CONDITIONS
			R0 ->	CONVERTED STRING

.I R$BDEC
.I MR01
R$BDEC		MR01	This procedure converts a sixteen bit binary word into
			a signed significant zero string of ASCII characters
			using base ten.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE

			EXIT CONDITIONS
			R0 ->	CONVERTED STRING

.I R$BHEX
.I MR02
R$BHEX		MR02	This procedure converts a sixteen bit binary word into
			a significant zero string of ASCII characters using
			base sixteen.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE		WORD ENTRY +0
							BYTE ENTRY +2
			EXIT CONDITIONS
			R0 ->	CONVERTED STRING

.I R$BINB
.I MR03
R$BINB		MR03	This procedure converts a character string into
			a signed sixteen bit word the input is assumed
			to be in base two.

			ENTRY CONDITIONS
			R0 ->	ASCII STRING ADDRESS

			EXIT CONDITIONS
			R0 =	CONVERTED VALUE
				IF STATUS = SUCCESS

.I R$BOCT
.I MR02
R$BOCT		MR02	This procedure converts a sixteen bit binary word into
			a significant zero string of ASCII characters using
			base eight.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE		WORD ENTRY +0
							BYTE ENTRY +2
			EXIT CONDITIONS
			R0 ->	CONVERTED STRING

.T Character string to binary value convert routines.


NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$HEXB
.I MR03
R$HEXB		MR03	This procedure converts a character string into
			a signed sixteen bit word the input is assumed
			to be in base sixteen.

			ENTRY CONDITIONS
			R0 ->	ASCII STRING ADDRESS

			EXIT CONDITIONS
			R0 =	CONVERTED VALUE
				IF STATUS = SUCCESS

.I R$OCTB
.I MR03
R$OCTB		MR03	This procedure converts a character string into
			a signed sixteen bit word the input is assumed
			to be in base eight.

			ENTRY CONDITIONS
			R0 ->	ASCII STRING ADDRESS

			EXIT CONDITIONS
			R0 =	CONVERTED VALUE
				IF STATUS = SUCCESS

.I R$DECB
.I MR03
R$DECB		MR03	This procedure converts a character string into
			a signed sixteen bit word the input is assumed
			to be in base ten.

			ENTRY CONDITIONS
			R0 ->	ASCII STRING ADDRESS

			EXIT CONDITIONS
			R0 =	CONVERTED VALUE
				IF STATUS = SUCCESS

.I R$STRB
.I MR03
R$STRB		MR03	This procedure converts a character string into
			a signed sixteen bit word.

			ENTRY CONDITIONS
			R0 =	ADDRESS OF CHARACTER STRING

			EXIT CONDITIONS
			R0 =	CONVERTED STRING VALUE
				IF STATUS = SUCCESS

.T Numeric character string tidy routines.

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$NTDY
.I MR21
R$NTDY		MR21	This procedure tidies a numeric character string
			created in the form <sign><numbers> the output
			result being in the value is negative the sign
			is retained and leading zeros removed.


			ENTRY POINTS
 
		(+0)	REMOVE LEADING ZEROS AND SIGN IF IT IS A PLUS
		(+2)	CONVERT LEADING ZEROS TO SPACES
		(+4)	REMOVE SIGN CHARACTER IF IT IS A PLUS

			ENTRY CONDITIONS
			R0 ->	NUMERIC CHARACTER STRING

			EXIT CONDITIONS
			R0 ->	MODIFIED STRING

.T Character string to non numeric format convert routines

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$BASC
.I MR18
R$BASC		MR18	This procedure converts a binary value into
			printable ASCII characters. Non printable ASCII
			characters are designated as so :-
			characters with values below decimal 32 are
			assumed to be control characters and are displayed
			^control character. The erase character is displayed
			as ^? .
			ie. character code 3 will be displayed as ^C

			ENTRY CONDITIONS
			R0 =	BINARY VALUE

			EXIT CONDITIONS
			R0 ->	ADDRESS OF STRING

.I R$BR50
.I MR15
R$BR50		MR15	This procedure converts a binary value into three
			radix 50 ascii characters in string format.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE

			EXIT CONDITIONS
			R0 ->	ASCII STRING
				IF STATUS = SUCCESS

.I R$R50L
.I MR17
R$R50L		MR17	This procedure converts ASCII characters
			to radix 50 code load data sequentially
			into store.

			ENTRY POINTS	+0 NORMAL
					+2 INITIALISATION ENTRY

			ENTRY CONDITIONS
			R0 =	ASCII CHARACTER (ENTRY +0 ONLY)
			R4 ->	OUTPUT STORAGE AREA

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR
			R4 ->	LAST LOADED RADIX 50 WORD

.T Character manipulation routines.

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I R$ADDC
.I MRC03
R$ADDC		MRC03	This procedure appends/adds a character to a
			character string.

			ENTRY CONDITIONS
			R0 HOLDS CHARACTER TO ADD TO STRING
			R4 ->	CHARACTER STRING

			EXIT CONDITIONS
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED.

.I R$ADDS
.I MRC12
R$ADDS		MRC12	This procedure appends/adds a character string to a
			character string.

			ENTRY CONDITIONS
			R0 ->	CHARACTER STRING TO ADD TO STRING
			R4 ->	CHARACTER STRING

			EXIT CONDITIONS
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED.

.I R$CMPC
.I MRC09
R$CMPC		MRC09	This procedure compares to characters and checks if
			they are the same uppercase/lowercase characters
			are assumed to have the same value.

			ENTRY CONDITIONS
			R1 ->	THE ADDRESS OF CHARACTER (A)
			R2 ->	THE ADDRESS OF CHARACTER (B)

			EXIT CONDITIONS
			IF CHARACTERS SAME	STATUS = SUCCESS
			IF CHARACTERS DIFFER	STATUS = ERROR

.I R$CR50
.I MRC08
R$CR50		MRC08	This procedure converts a character to its
			radix 50 code.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO CONVERT

			EXIT CONDITIONS
			R0 =	CONVERTED CHARACTER
				IF STATUS = SUCCESS
			R0 =	-1 IF STATUS = ERROR

.I R$DELC
.I MRC05
R$DELC		MRC05	This procedure deletes a character within a character
			string at a specified position.

			ENTRY CONDITIONS
			R1 ->	STRING ADDRESS
			R2 =	CHARACTER POSITION TO DELETE

			EXIT CONDITIONS
			R1 ->	STRING ADDRESS
			R2 =	CHARACTER POSITION TO DELETE
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED

.F


NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I R$GETC
.I MRC01
R$GETC		MRC01	This procedure extract a character from a character
			string from a requested position.

			ENTRY CONDITIONS
			R1 ->	STRING ADDRESS
			R2 ->	CHARACTER POSITION TO EXTRACT

			EXIT CONDITIONS
			R0 HOLDS EXTRACTED CHARACTER
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED

.I R$INSC
.I MRC04
R$INSC		MRC04	This procedure inserts a character after a noted
			position in a string.

			ENTRY CONDITIONS
			R0 =	THE CHARACTER TO INSERT
			R1 ->	STRING ADDRESS TO HAVE CHARACTER INSERTED
			R2 =	THE POSITION AFTER WHICH THE CHARACTER
				IS INSERTED

			EXIT CONDITIONS
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED

.I R$LCUC
.I MRC10
R$LCUC		MRC10	This procedure converts a lowercase alpha to
			an uppercase alpha all other characters remain
			unchanged.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO CONVERT

			EXIT CONDITIONS
			R0 =	CONVERTED CHARACTER

.I R$MODC
.I MRC02
R$MODC		MRC02	This procedure modifies/overwrites a character
			within a character string at a requested position.


			ENTRY CONDITIONS
			R1 ->	STRING ADDRESS
			R2 ->	CHARACTER POSITION TO EXTRACT
			R0 =	REPLACEMENT CHARACTER

			EXIT CONDITIONS
			EXITERROR IF INVALID CONDITIONS OR OPERATION FAILED



.F


NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I R$MOVC
.I MRC07
R$MOVC		MRC07	This procedure removes the first character out of
			a string and reduces the string length
			by one character.

			ENTRY CONDITIONS
			R1 ->	STRING ADDRESS

			EXIT CONDITIONS
			R0 =	EXTRACTED CHARACTER
				IF STATUS = SUCCESS

.I R$POSC
.I MRC06
R$POSC		MRC06	This procedure locates a character within a character
			string.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO LOCATE
			R1 ->	CHARACTER STRING
			R2 =	START POSITION FOR LOCATE TO START

			EXIT CONDITIONS
			R2 =	POSITION OF CHARACTER
				IF STATUS = SUCCESS

.I R$POSS
.I MRC06
R$POSS		MRC06	This procedure locates a character within a character
			string.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO LOCATE
			R1 ->	CHARACTER STRING

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.I R$R50C
.I MRC08
R$R50C		MRC08	This procedure converts a radix 50 code to an
			ASCII character.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO CONVERT

			EXIT CONDITIONS
			R0 =	CONVERTED CHARACTER
				IF STATUS = SUCCESS
			R0 =	-1 IF STATUS = ERROR

.I R$UCLC
.I MRC11
R$UCLC		MRC11	This procedure converts an uppercase alpha to
			a lowercase alpha all other characters remain
			unchanged.

			ENTRY CONDITIONS
			R0 =	CHARACTER TO CONVERT

			EXIT CONDITIONS
			R0 =	CONVERTED CHARACTER

.T File and Block control routines

NAME		MODULE			DESCRIPTION
----		------			-----------

.I F$NAME
.I MF01
F$NAME		MF01	This procedure validates a filename and
			sets up an internal default filename
			descriptor block (DFNB).

			ENTRY CONDITIONS
			R0 ->	FILENAME STRING ADDRESS

			EXIT CONDITIONS
			R0 ->	DEFAULT FDB
				IF STATUS = SUCCESS

.I F$GETR
.I MF02
.I F$FDB
F$GETR		MF02	This procedure reads a record from the
			file specified by the FBD pointed at
			by the location F$FDB. The record length
			and data buffer information is taken from
			the string address.

			ENTRY CONDITIONS
			R0 ->	STRING BUFFER TO BE LOADED

			EXIT CONDITIONS
			R0 ->	LOADED STRING
				IF STATUS = SUCCESS

.I F$SHUT
.I MF03
.I F$FDB
F$SHUT		MF03	This procedure closes down the file specified
			by the FDB pointed at by the location F$FDB.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS FLAG ONLY

.I F$PUTR
.I MF04
.I F$FDB
F$PUTR		MF04	This procedure writes a record to the
			file specified by the FDB pointed at
			by the location F$FDB. Information about the
			record is taken from the string for output.

			ENTRY CONDITIONS
			R0 ->	STRING TO BE OUTPUT

			EXIT CONDITIONS
			STATUS FLAG ONLY

.F
NAME		MODULE			DESCRIPTION
----		------			-----------

.I F$OPEN
.I F$FDB
.I MF05
F$OPEN		MF05	This procedure opens the file specified by the
			FDB pointed at by the location F$FDB.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS FLAG ONLY

.I F$SETUP
.I F$FDB
.I MF06
.I F$TYPE
F$SETUP		MF06	This procedure sets up the FDB controlled by
			the flags set in location F$TYPE.

			ENTRY CONDITIONS
			R0 ->	STRING HOLDING DEFAULT FILENAME BLOCK

			EXIT CONDITIONS
			STATUS FLAGS ONLY


.I F$DIAG
.I MF07
.I F$FDB
F$DIAG		MF07	This procedure output the state of the present
			FDB (file descripter block) and the DFNB
			(default filename block) onto the terminal.
			The location F$FDB points to the FDB that will
			be processed.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			NONE

.I F$SWITCH
.I F$LUN
.I F$FDB
.I MF08
F$SWITCH	MF08	This procedure uses the location F$LUN to switch
			the FDB (file descriptor block) address in location
			F$FDB ie. this is the channel switch routine.

			ENTRY CONDITIONS
			F$LUN MUST BE VALID

			EXIT CONDITIONS
			NONE

.T General purpose routines

NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$ADDRESS
.I MG01
R$ADDRESS	MG01	This procedure checks that a string address is
			a valid address.

			ENTRY CONDITIONS
			R0 =	STRING ADDRESS

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.I R$BITSET
.I MG06
R$BITSET	MG06	This procedure sets up a bit mask.

			ENTRY CONDITIONS
			R1 =	POSITION OF BIT TO BE SET

			EXIT CONDITIONS
			R1 =	BIT MASK

.I R$BITPOS
.I MG07
R$BITPOS	MG07	This procedure indicates the position of the
			lowest positioned bit set in a bit pattern.

			ENTRY CONDITIONS
			R1 =	BIT PATTERN/MASK

			EXIT CONDITIONS
			R1 =	POSITION
				IF STATUS = SUCCESS

.I R$PARITY
.I MG13
R$PARITY	MG13	This procedure checks the parity state of a
			binary value and also counts the number of
			bits set.

			ENTRY CONDITIONS
			R0 =	BIT PATTERN

			EXIT  CONDITIONS
			-8.(SP) = ONE'S COUNT OF R0
			STATUS  = SUCCESS IF PARITY = EVEN
			STATUS  = ERROR   IF PARITY = ODD

.I R$SAVE
R$SAVE		MG14	This procedure saves the registers R0 to R5
			on the stack. It has no entry or exit condi
			-tions.

.I R$UNSAVE
R$UNSAVE	MG14	This procedure is the converse of R$SAVE and
			unsaves registers R0 to R5 from the stack.It
			has no entry or exit conditions.

.T Queue manipulation routines



NAME		MODULE			DESCRIPTION
----		------			-----------

.I R$QADD
.I MR23
R$QADD		MR23	This procedure adds/appends a character to
			queue ring buffer.

			ENTRY CONDITIONS
			R0 =	THE CHARACTER TO LOAD INTO THE QUEUE
			R4 ->	THE ADDRESS OF THE QUEUE BUFFER

			EXIT  CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY


.I R$QREM
.I MR24
R$QREM		MR24	This procedure extracts/removes a character
			from a queue ring buffer.

			ENTRY CONDITION
			R1 ->	THE ADDRESS OF THE QUEUE BUFFER

			EXIT  CONDITIONS
			R0 =	EXTRACTED CHARACTER
				IF STATUS = SUCCESS


.I R$QTST
.I MR25
R$QTST		MR25	This procedure tests that there is enough
			room in the queue to allow another character
			to be added to the buffer.
 
			ENTRY CONDITIONS
			R4 ->	THE ADDRESS OF THE QUEUE BUFFER
 
			EXIT CONDITIONS
			STATUS OR ERROR ONLY  ERROR = NO FREE SPACE
 
.T Terminal input/output routines
.I V$LUN
.I TI0:

	The following procedures automatically assigns logical unit V$LUN
	assigned to TI0:


NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I V$IO
.I MG02
.I L7A
.I VDU
V$IO		MG02	This procedure performs both input and output
			operation on the terminal TI0: where the mode
			string controls a series of screen operations.
			(See VDU module L7A for information on the format)
			(of the mode string)

			ENTRY CONDITIONS
			R1 ->	MODE STRING
			R2 ->	DATA STRING

			EXIT CONDITIONS
			R0 ->	REPLY STRING

.I V$TX
.I MG04
V$TX		MG04	This procedure transmits the character string
			address held in R0 to the terminal TI0: .

			ENTRY CONDITIONS
			R0 ->	DATA STRING FOR OUTPUT

			EXIT CONDITIONS
			CHARACTERS ARE DISPLAYED ON THE TERMINAL TI0:

.I V$INPUT
.I MG03
V$INPUT		MG03	This procedure reads a character string from the
			terminal TI0: .

			ENTRY CONDITIONS
			ENTRY ADDRESS +0 READ WITH ECHO
			ENTRY ADDRESS +2 READ NO   ECHO

			EXIT CONDITIONS
			R0 ->	THE INPUTTED DATA STRING

.F
 
 
NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I V$ON
.I MG08
.I V$LUN
V$ON		MG08	This procedure assigns V$LUN to the terminal.
 
			ENTRY CONDITIONS
			NONE
 
			EXIT  CONDITIONS
			STATUS = SUCCESS OR ERROR
 

.I V$OFF
.I MG08
V$OFF		MG08	This procedure deassigns the terminal lun.
 
			ENTRY CONDITIONS
			NONE
 
			EXIT  CONDITIONS
			STATUS = SUCCESS OR ERROR
 
 

.I VDU
.I V$TERMINAL
.I MG08
V$TERMINAL	MG08	This procedure switches the VDU channel back
			to the users terminal.

			ENTRY	CONDITIONS
			NONE

			EXIT	CONDITIONS
			If the operation fails the programme will HALT

.I V$CHANNEL
.I V$DUNT
.I MG08
V$CHANNEL	MG08	This procedure set up the location V$DUNT to
			the device channel required to be exchanged
			for the VDU channel.

			ENTRY	CONDITIONS
			R0 =	THE DEVICE CHANNEL NUMBER

			EXIT	CONDITIONS
			NONE

.F
 
 
NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I V$DUNT
.I V$DDEV
.I V$CHANNEL
.I V$DEVICE
.I MG08
V$DEVICE	MG08	This procedure switches the VDU channel to a
			device selected by the locations V$DUNT the
			device unit number and the locations V$DDEV
			the device code letters. The standard default
			code letters are "TT" and the unit number is
			zero the unit number may be altered by the
			procedure V$CHANNEL.
			To prepare channel TT56: the following sequence
			would be used :-
			MOV #56,R0		;Hold channel number
			CALL V$CHANNEL		;Load new channel number
			CALL V$DEVICE		;Switch the channel
			Note once the channel number has been set up
			there should be no need to reuse the procedure
			V$CHANNEL unless the channel is to be changed.

			ENTRY	CONDITIONS
			LOCATIONS V$DUNT AND V$DDEV ARE SET UP

			EXIT	CONDITIONS
			STATUS = SUCCESS OR ERROR
			IF STATUS =	ERROR THEN THE CHANNEL IS RETURNED
					BACK TO THE VDU CHANNEL

.I V$SWITCH
.I MG08
V$SWITCH	MG08	This procedure reassigns the terminal channel
			to some other peripherial as specified by the
			locations V$UNIT and V$DEV .
 
			ENTRY CONDITIONS
			NONE
 
			EXIT  CONDITIONS
			STATUS = SUCCESS OR ERROR

.F



NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I V$TXA
.I MG09
.I V$TX
V$TXA		MG09	This proceduure enables an alternative method
			of passing data to the V$TX procedure.
			The format of this call is :-
				CALL V$TXA
				Address of string to be output

			ENTRY CONDITIONS
			STRING ADDRESS FOLLOWS CALL

			EXIT CONDITIONS
			DATA OUTPUT TO TERMINAL

.I V$TX
.I V$TXB
.I MG10
V$TXB		MG10	This procedure enables an alternative method
			of passing data to the procedure V$TX.
			The format of this call is :-
				CALL V$TXB
				length of character string
				character string

			ENTRY CONDITIONS
			STRING DATA FORMAT FOLLOWS THE CALL STATEMENT

			EXIT CONDITIONS
			CHARACTERS ARE DISPLAYED ON THE TERMINAL.

.I V$TXC
.I MG11
V$TXC		MG11	This procedure enables repeats of a character
			to be sent to the terminal. The data follows
			the call to this procedure.
			The format of this call is :-
				CALL V$TXC
				.BYTE repeat count value in range 1 to 255
				.BYTE character to be transmitted to the
				      terminal.

			ENTRY CONDITIONS
			DATA FOLLOWS PROCEDURE CALL

			EXIT CONDITIONS
			CHARACTERS ARE DISPLAYED ON THE TERMINAL.

.I V$TXD
.I MG12
.I V$TX
V$TXD		MG12	This procedure enables an alternative method
			of passing data to the procedure V$TX.
			The format of this call is :-
				CALL V$TXD
				maximun string length (protection word)
				length of character string
				character string

			ENTRY CONDITIONS
			STRING DATA FORMAT FOLLOWS THE CALL STATEMENT

			EXIT CONDITIONS
			CHARACTERS ARE DISPLAYED ON THE TERMINAL.
.C CHARACTER/STRING MANIPULATION ROUTINES USING CD.DIC.
.T INTRODUCTION
.I CD.DIC
.I CD.SRC (source)
.I CD.DST (destination)
.I CD.CHR (character)
.I CD.CNT (count)
.I CD.POS (position)
.I CD.RES (result)
.I CD.KEY (table key)
.I COMMON DICTIONARY.
.I MGD03 (CD.DIC)

	These subroutines use labels in which to pass the parameters. All
registers are saved across the call.

	The locations are all words and are found in Module MGD03. They
are as follows:-

	CD.SRC	Address of main string (source) or table entry address.
	CD.DST	Address of secondary string (destination).
	CD.CHR	Contains the fill or operation character.
	CD.CNT	Contains the last input numeric count.
	CD.POS	Holds the character or string position to find or found.
	CD.RES	Contains the result of a previous macro (eg- COMPARE).
	CD.KEY	Holds the last table key entry that was accessed.

	The above locations are known as the COMMON DICTIONARY (CD.DIC)
and may be modified as required.

	NOTE:-	that the  table macros also use the COMMON DICTIONARY, and
		that after saving and setting the registers these routines
		call the appropriate register routine.

		Thus L$GETC calls R$GETC.

.T CHARACTER PROCEDURES USING COMMON DICTIONARY.

NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$GETC
.I MLC01
L$GETC		MLC01	EXTRACT A CHARACTER FROM A STRING.

				ENTRY CONDITIONS

			CD.SRC	->	STRING TO PROCESS.
			CD.POS	=	CHARACTER POSITION TO EXTRACT.

				EXIT CONDITIONS

			CD.CHR	=	EXTRACTED CHARACTER.

			EXITERROR IF INVALID CONDITIONS.




.I L$MODC
.I MLC02
L$MODC		MLC02	REPLACE A CHARACTER IN A STRING.

				ENTRY CONDITIONS

			CD.CHR	=	REPLACEMENT CHARACTER
			CD.SRC	->	CHARACTER STRING ADDRESS
			CD.POS	=	CHARACTER POSITION TO MODIFY

				EXIT CONDITIONS

			EXITERROR IF INVALID CONDITIONS.




.I L$ADDC
.I MLC03
L$ADDC		MLC03	APPEND A CHARACTER TO A STRING.

				ENTRY CONDITIONS

			CD.CHR	=	CHARACTER TO ADD TO STRING.
			CD.SRC	->	CHARACTER STRING.

				EXIT CONDITIONS.

			ERROREXIT IF INVALID CHARACTER.




.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$INSC
.I MLC04
L$INSC		MLC04	INSERT A CHARACTER IN A STRING.

				ENTRY CONDITIONS.

			CD.CHR	=	CHARACTER TO INSERT
			CD.SRC	->	STRING ADDRESS.
			CD.POS	=	CHARACTER POSITION.

				EXIT CONDITIONS.

			ERROREXIT IF INVALID CONDITIONS.




.I L$DELC
.I MLC05
L$DELC		MLC05	DELETE A CHARACTER WITHIN A STRING.

				ENTRY CONDITIONS

			CD.SRC	->	STRING ADDRESS
			CD.POS	=	CHARACTER POSITION TO DELETE

				EXIT CONDITIONS

			ERROREXIT IF INVALID CONDITIONS.



.I L$POSC
.I MLC06
L$POSC		MLC06	LOCATE POSITION OF CHARACTER IN STRING.
	
				ENTRY CONDITIONS

			CD.CHR	=	CHARACTER TO LOCATE.
			CD.SRC	->	ADDRESS OF STRING.
			CD.POS	=	START POSITION TO START SEARCH 
					IN STRING.

				EXIT CONDITIONS

			CD.POS	=	UNCHANGED IF CHARACTER NOT 
					FOUND (EXITERROR).
			CD.POS	=	CHARACTER POSITION 
					(EXITSUCCESS).




.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$MOVC
.I MLC07
L$MOVC		MLC07	EXTRACT A CHARACTER FROM A STRING.

				ENTRY CONDITIONS

			CD.SRC	->	STRING ADDRESS

				EXIT CONDITIONS

			CD.CHR	=	CHARACTER IF STATUS EQUALS
					SUCCESS.


.I L$CMPC
.I MLC09
L$CMPC		MLC09	COMPARE TWO CHARACTERS.

				ENTRY CONDITIONS.

			CD.CHR	 =	FIRST CHARACTER (BYTE)
			CD.CHR+1 =	SECOND CHARACTER (BYTE)

				EXIT CONDITIONS.

			SUCCESS IF CHARACTERS ARE THE SAME.


.I L$ADDS
.I MLC12
L$ADDS		MLC12	ADD ONE STRING TO ANOTHER STRING.

				ENTRY CONSITIONS.

			CD.SRC	->	CHARACTER STRING TO ADD.
			CD.DST	->	CHARACTER STRING TO BE ADDED TO.

				EXIT CONDITIONS.

			ERROREXIT IF INVALID CONDITIONS.

	
.I L$DELETE
.I ML04
L$DELETE	ML04	CHARACTER DELETE WITHIN A STRING.

				ENTRY CONDITIONS

			CD.SRC	->	STRING TO PROCESS
			CD.POS	=	START POSITION WHERE DELETING 
					IS TO START.
			CD.CNT	=	NUMBER OF CHARACTERS TO DELETE.

				EXIT CONDITIONS

			NONE
.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$POS3
.I ML05
L$POS3		ML05	POSITION ROUTINE, 3 PARAMETERS.

				ENTRY CONDITIONS.

			CD.SRC	->	MASTER STRING
			CD.DST	->	SEARCH STRING
			CD.POS	=	START POSITION OF SEARCH.

				EXIT CONDITIONS

			CD.POS	=	POSITION OF FIRST CHARACTER 
					IF MATCH FOUND.(SUCCESS)
			CD.POS	=	'0' IF NO MATCH FOUND.	
					(ERROR)





.I L$POS2
.I ML05
L$POS2		ML05	POSITION ROUTINE, 2 PARAMETERS.

				ENTRY CONDITIONS.

			CD.SRC	->	MASTER STRING
			CD.DST	->	SEARCH STRING

				EXIT CONDITIONS

			CD.POS	=	POSITION OF FIRST CHARACTER 
					IF MATCH FOUND.(SUCCESS)
			CD.POS	=	'0' IF NO MATCH FOUND.(ERROR)





.I L$WEDGE
.I ML06
L$WEDGE		ML06	WEDGE ONE STRING WITHIN ANOTHER STRING.

				ENTRY CONDITIONS

			CD.DST	->	MASTER STRING ADDRESS.
			CD.SRC	->	WEDGE STRING ADDRESS.
			CD.POS	=	POSITION WHERE INSERT MUST START.

				EXIT CONDITIONS.

			NONE





.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$REVERSE
.I ML07
L$REVERSE	ML07	STRING REVERSAL PROCEDURE.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING TO BE REVERSED.

				EXIT CONDITIONS

			NONE


.I L$SHRE
.I ML08
L$SHRE		ML08	CHARACTER SHIFT RIGHT END AROUND.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.

				EXIT CONDITIONS

			NONE


.I L$SHLE
.I ML09
L$SHLE		ML09	CHARACTER SHIFT LEFT END AROUND.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.

				EXIT CONDITIONS

			NONE


.I L$SHR
.I ML10
L$SHR		ML10	SHIFT CHARACTER STRING ONE PLACE RIGHT.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.
			CD.CHR	=	FILLER CHARACTER.

				EXIT CONDITIONS

			NONE
.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$SHL
.I ML10
L$SHL		ML10	SHIFT CHARACTER STRING ONE PLACE RIGHT.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.

				EXIT CONDITIONS

			NONE






.I L$COMPARE
.I ML11
L$COMPARE	ML11	COMPARE TWO CHARACTER STRINGS.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.
			CD.DST	->	CHARACTER STRING ADDRESS.
		
				EXIT CONDITIONS

			IF BOTH STRING IDENTICAL
				CD.RES = ZERO	(SUCCESS)
			IF SOURCE STRING LARGEST
				CD.RES = POSITIVE	(ERROR)
			IF DESTINATION STRING LARGEST
				CD.RES = NEGATIVE	(ERROR)

	NOTE:-	WHEN STRINGS OF DEFFERING LENGTHS ARE SUPPLIED THE
		CHARACTERS ARE COMPARED OVER THE LENGTH OF THE
		SHORTEST STRING, IF ALL CHARACTERS ARE THE SAME THE
		SHORTEST STRING IS ASSUMED TO BE THE SMALLER.





.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$ADDTO
.I ML12
L$ADDTO		ML12	ADD ONE STRING TO ANOTHER.

				ENTRY CONDITIONS

			CD.SRC	->	STRING TO APPEND.
			CD.DST	->	CHARACTER STRING TO BE APPENDED TOO.

				EXIT CONDITIONS

			NONE






.I L$CLEAR
.I ML13
L$CLEAR		ML13	CLEAR OUT A CHARACTER STRING.

				ENTRY CONDITIONS

			CD.SRC	->	CHARACTER STRING ADDRESS.

				EXIT CONDITIONS

			NONE





.I L$SEG
.I ML14
L$SEG		ML14	EXTRACT SEGMENT OF A CHARACTER STRING.

				ENTRY CONDITIONS

			CD.SRC	->	INPUT STRING ADDRESS.
			CD.POS	->	START POSITION.
			CD.CNT	->	NUMBER OF CHARACTERS.
			CD.DST	->	OUTPUT CHARACTER STRING ADDRESS.

				EXIT CONDITIONS

			CD.DST ->	OUTPUT STRING ADDRESS.





.F
NAME		MODULE		DESCRIPTION
----		------		-----------

.I L$PAD
.I ML16
L$PAD		ML16	PAD A CHARACTER STRING.

				ENTRY CONDITIONS

			CD.SRC	->	INPUT STRING ADDRESS.
			CD.CNT	=	NUMBER OF CHARACTERS TO PAD 
					WITH OR '0' FOR REST OF STRG.
			CD.CHR	=	CHARACTER TO PAD WITH.

				EXIT CONDITIONS

			NONE

.C Node manipulation routines
.T Introduction







	A node in this context is a block of memory which may be
	accessed as a fixed or variable length data area controlled
	within a limited area of program memory.
	The node software is suitable as the basis for editors
	interpreters screen formatting and sorting programs and
	various other data manipulation software.


.T Node routines
NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I N$DIAG
.I MN01
N$DIAG		MN01	This procedure prints onto the terminal the state
			of the control nodeblock data table.

			ENTRY CONDITIONS
			LUN ONE ASSIGNED TO THE TERMINAL

			EXIT CONDITIONS
			NONE

.I N$DUMP
.I MN02
N$DUMP		MN02	This procedure prints onto the terminal the contents
			of the present node the next sequential nodes as
			specified by a count value in R0.

			ENTRY CONDITIONS
			LUN ONE ASSIGNED TO THE TERMINAL
			R0 =	NUMBER OF SEQUENTIAL NODES TO DUMP

			EXIT CONDITIONS
			NONE

.I N$INIT
.I MN03
N$INIT		MN03	This procedure sets up the node control block to
			access a new node table. If a node table is being
			processed the old data is copied back to old node
			table before new data copied in.

			ENTRY CONDITIONS
			R0 ->	ADDRESS OF NODE TABLE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.I N$CREATE
.I MN09
N$CREATE	MN09	This procedure will try to create a node in the
			node table.

			ENTRY CONDITIONS
			R0 =	SIZE IN BYTES REQUIRED BY NODE
			R1 =	MARKERS TO LOCATE NODE WITH

			EXIT CONDITIONS
			R0 ->	NEW NODE ACCESS ADDRESS
				IF STATUS = SUCCESS
.F


NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I N$DELETE
.I MN06
N$DELETE	MN06	This procedure will try to delete a node in the node
			table.

			ENTRY CONDITIONS
			R1 =	MARKER TO LOCATE NODE WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NEXT NODE
				IF STATUS = SUCCESS

.I N$PROTECT
.I MN08
N$PROTECT	MN08	This procedure disables the delete procedure from
			deleting a node and when a node is used as a character
			string the string is marked write protect.

			ENTRY CONDITIONS
			R1 =	MARKER OF NODE TO PROTECT

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF PROTECTED NODE
				IF STATUS = SUCCESS

.I N$UNPROTECT
.I MN08
N$UNPROTECT	MN08	This procedure removes any protect flags set on a node.

			ENTRY CONDITIONS
			R1 =	MARKERS TO LOCATE NODE WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NODE
				IF STATUS = SUCCESS

.I N$SEEK
.I MN04
N$SEEK		MN04	This procedure locates the position in the node
			table of a specified node.

			ENTRY CONDITIONS
			R1 =	MARKERS TO LOCATE NODE WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NODE
				IF STATUS = SUCCESS

.I N$SQUEEZE
.I MN10
N$SQUEEZE	MN10	This procedure compresses the node table removing
			any nodes marked for delete.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY



.F


NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I N$FIRST
.I MN05
N$FIRST		MN05	This procedure locates the first node in the
			node table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF FIRST NODE
				IF STATUS = SUCCESS

.I N$LAST
.I MN05
N$LAST		MN05	This procedure locates the last node in the
			node table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS

			R0 ->	ACCESS ADDRESS OF LAST NODE
				IF STATUS = SUCCESS

.I N$PRESENT
.I MN05
N$PRESENT	MN05	This procedure locates the position of the node
			presently being pointed at in the node table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF PRESENT NODE
				IF STATUS = SUCCESS

.I N$SETUP
.I MN05
.I N$INIT
N$SETUP		MN05	This procedure verifys that the node table has been
			set up by the N$INIT routine.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.I N$NEXT
.I MN07
N$NEXT		MN07	This procedure steps onto the next node in the
			node table, nodes are assumed to end wrap around
			no checks are made regarding the state of the
			node.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NEXT NODE
				IF STATUS = SUCCESS


.T Node table generation MACRO and data formats
.I NODEBLOCK

NODEBLOCK [number of bytes in table]
			This macro is used at least twice. The macro
			is specified once without the number of
			bytes being specified this macro then expands
			all the global symbols required for the correct
			operation of the node control software.
			All further uses of the NODEBLOCK macro are
			used to create node tables.


		NODE FORMAT
		-----------

BYTES 0,1		Location of marker word
			BIT 15 indicates the node is deleted.
BYTES 2,3		Maximum size in bytes of the node.
			BIT 15 SET indicates this node is protected
BYTES 4,5		Free byte or indicates length when node is a
			string.
BYTES 6->		User workspace in node


.C Table manipulation routines
.T Introduction







	A table in this context is a block of memory which may be
	accessed as a fixed or variable length data area controlled
	within a limited area of program memory.
 
	It differs from the node software in that the key is held in
	sorted order in an internal string, thus all table lookups and
	creates are automatically put in key order.
.I KEYS 
	NOTE:-	1. no key may be greater than 32766 (Octal 77776).
		2. an allowance must be made in the length declaration
		   for the sort string of approximately 12 bytes for
		   each required string.
 
	The table software is suitable as the basis for editors
	interpreters screen formatting and sorting programs and
	various other data manipulation software.

.T Table routines

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I T$DIAG
.I MT01
T$DIAG		MT01	This procedure prints onto the terminal the state
			of the control data table.

			ENTRY CONDITIONS
			LUN ONE ASSIGNED TO THE TERMINAL

			EXIT CONDITIONS
			NONE

.I T$DUMP
.I MN02
T$DUMP		MN02	This procedure prints onto the terminal the contents
			of the present entry the next sequential entrys as
			specified by a count value in R0.

			ENTRY CONDITIONS
			LUN ONE ASSIGNED TO THE TERMINAL
			R0 =	NUMBER OF SEQUENTIAL ENTRYS TO DUMP

			EXIT CONDITIONS
			NONE

.I T$INIT
.I MT03
T$INIT		MT03	This procedure sets up the entry control block to
			access a new table. If a entry table is being
			processed the old data is copied back to old entry
			table before new data copied in.

			ENTRY CONDITIONS
			R0 ->	ADDRESS OF TABLE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY
.F

 
NAME		MODULE			DESCRIPTION
----		------			-----------

.I T$CREATE
.I MT09
T$CREATE	MT09	This procedure will try to create an entry in the
			table.

			ENTRY CONDITIONS
			R0 =	SIZE IN BYTES REQUIRED BY ENTRY
			R1 =	MARKERS TO LOCATE ENTRY WITH

			EXIT CONDITIONS
			R0 ->	NEW ENTRY ACCESS ADDRESS IF STATUS = SUCCESS
 
.I T$CREATE
.I T$SCHK
.I MT09
T$SCHK		MT09	This procedure is used by T$CREATE to check if sort
			table string can be inserted.
 
			DO NOT USE.
 
.I T$CREATE
.I T$IKEY
.I MT09
T$IKEY		MT09	This procedure is NOT TO BE USED  on its own. It is
			used by T$CREATE to insert an item in the sort string
 
			ENTRY CONDITIONS
			R0 =	ADDRESS OF STRING.
 
			EXIT CONDITIONS
			R0 =	ACCESS ADDRESS IF SUCCESS.
 
.I T$DELETE
.I MT06
T$DELETE	MT06	This procedure will try to delete an entry in the
			table.

			ENTRY CONDITIONS
			R1 =	MARKER TO LOCATE ENTRY WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NEXT ENTRY
				IF STATUS = SUCCESS
 
.I T$DELETE
.I T$DKEY
.I MT06
T$DKEY		MT06	This procedure is NOT TO BE USED on its own. It is used
			by T$DELETE to remove item from the sort string
 
			ENTRY CONDITIONS
			(set up by T$DELETE)
 
			EXIT CONDITIONS
			(same as T$DELETE)

.F

 
NAME		MODULE			DESCRIPTION
----		------			-----------

.I T$PROTECT
.I MT08
T$PROTECT	MT08	This procedure disables the delete procedure from
			deleting an entry and when an entry is used as a
			character string the string is marked write protect.

			ENTRY CONDITIONS
			R1 =	MARKER OF ENTRY TO PROTECT

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF PROTECTED ENTRY
				IF STATUS = SUCCESS

.I T$UNPROTECT
.I MT08
T$UNPROTECT	MT08	This procedure removes any protect flags
			set on an entry.

			ENTRY CONDITIONS
			R1 =	MARKERS TO LOCATE ENTRY WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF ENTRY
				IF STATUS = SUCCESS
 
.I T$SEEK
.I MT04
T$SEEK		MT04	This procedure locates the position in the entry
			table of a specified entry.

			ENTRY CONDITIONS
			R1 =	MARKERS TO LOCATE ENTRY WITH

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF ENTRY
				IF STATUS = SUCCESS

.I T$SQUEEZE
.I MT10
T$SQUEEZE	MT10	This procedure compresses the table removing
			any entrys marked for delete, and rebuilds the
			sort string.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.I T$SORT
.I MT10
T$SORT		MT10	This procedure compresses the table removing
			any entrys marked for delete, and rebuilds the
			sort string.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.F

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I T$FIRST
.I MT05
T$FIRST		MT05	This procedure locates the first sorted entry in the
			table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF FIRST SORTED
				ENTRY IF STATUS = SUCCESS

.I T$LAST
.I MT05
T$LAST		MT05	This procedure locates the last sorted entry in the
			table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS

			R0 ->	ACCESS ADDRESS OF LAST SORTED ENTRY
				IF STATUS = SUCCESS

.I T$PRESENT
.I MT05
T$PRESENT	MT05	This procedure locates the position of the entry
			presently being pointed at in the table.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF PRESENT ENTRY
				IF STATUS = SUCCESS

.I T$SETUP
.I MT05
.I T$INIT
T$SETUP		MT05	This procedure verifys that the entry table has been
			set up by the T$INIT routine.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			STATUS = SUCCESS OR ERROR ONLY

.F

NAME		MODULE			DESCRIPTION
----		------			-----------
 
.I T$NEXT
.I MT07
T$NEXT		MT07	This procedure steps onto the next entry in the
			table. If the routine attempts to step beyond the
			last entry, it will exit with an error and the
			address of the last entry.

			ENTRY CONDITIONS
			NONE

			EXIT CONDITIONS
			R0 ->	ACCESS ADDRESS OF NEXT ENTRY
				IF STATUS = SUCCESS
			R0 ->	ACCESS ADDRESS OF LAST ENTRY
				IF STATUS = ERROR.
 
.I T$PREVIOUS
.I MT07
T$PREVIOUS	MT07	This procedure steps back to the previous entry in the
			table.If the routine attempts to step beyond the first
			entry  it  will  exit with an error and the address of
			the first entry.
 
			ENTRY CONDITIONS.
			none
 
			EXIT CONDITIONS.
			R0 ->	ACCESS ADDRESS OF PREVIOUS ENTRY
				IF STATUS = SUCCESS
			R0 ->	ACCESS ADDRESS OF FIRST ENTRY
				IF STATUS = ERROR

.I T$RSEQ
.I MT11
T$RSEQ		MT11	This procedure resequences the keys in a table.
			Thus if the  resequence  point is '3' then keys
			'1' and '2' will remain untouched, key '3' will
			become '4' and '4' will become '5' etc.

			If  the  resequence point is '0', then all keys
			will  be  sequentially  resequenced starting at
			'1'.

				ENTRY CONDITIONS

			R0 ->	ADDRESS OF RESEQUENCE POINT IN SORT STRG.
				    MOV TPRESENT,R0	;makes hole.
				    CLR	R0		;complete resequence.

				EXIT CONDITIONS

			EXITSUCCESS ONLY.

.T Entry table generation MACRO and data structures
.I TABLEBLOCK
.I ENTRYBLOCK
.I TABLE [bytes]

TABLEBLOCK 
			This macro sets up the common 'TABLE/NODE' area
			and must only be specified once within a 
			program. When specified this macro then expands
			all the global symbols required for the correct
			operation of the entry control software.
			All further uses of the ENTRYBLOCK macro are
			used to create entry tables.

			NOTE:-	It is important to realise that
				'TABLEBLOCK' is the same as 'NODEBLOCK'
				(with no size param), their action is
				identical and only one or other should 
				be specified once.

TABLE	[Total number of bytes required in table]
			This macro defines the size of the Table, and
			is called once for each table required. It must
			be preceeded by a label with which it can be
			referenced


		ENTRY FORMAT
		-----------

BYTES 0,1		Location of marker word,
			MUST BE LESS THAN 32766 (O'77776).
			BIT 15 indicates the entry is deleted.
BYTES 2,3		Maximum size in bytes of the entry.
			BIT 15 SET indicates this entry is protected
BYTES 4,5		Free byte or indicates length when entry is a
			string.


BYTES 6->		User workspace in entry


.C Device channel routines
.T Magnetic tape routines	General information

			GENERAL INFORMATION
			===================

		Use of the magnetic tape controller
		-----------------------------------

	This software uses a series of reserved data locations to indicate
	which magnetic tape controller is to be used.
	These locations may be altered or examined to switch channels
	or to observe the effects of data transfer error etc..

.T Magnetic tape routines	Data area functions

NAME		MODULE			FUNCTION
----		------			--------

.I MT$UNIT
.I MMTD0
.I OPEN
MT$UNIT		MMTD0	This location indicates which controller
			is to be opened by the OPEN call.
			[default = unit number 0 ie. MM0: ]


.I MT$LUN
.I MMTD0
MT$LUN		MMTD0	This location indicates which logical
			unit will be assigned to the magnetic tape
			controller.
			[default = lun 2]


.I MT$EFN
.I MMTD0
MT$EFN		MMTD0	This location indicates which event flag
			will be used for I/O operations etc.
			[default = event flag 2]


.I MT$DSW
.I MMTD0
MT$DSW		MMTD0	This location hold the status of the last
			I/O operation.


.I MT$ISB
.I MMTD0
MT$ISB		MMTD0	This is the address of the INPUT/OUTPUT
			STATUS block.

.T Magnetic tape routines	Procedure functions

NAME		MODULE			DESCRIPTION
----		------			-----------

.I MT$EXIT
.I MMT01
.I DSW
MT$EXIT		MMT01	This procedure is the general exit routine
			for the magnetic tape input output control
			routines.

			ENTRY CONDITIONS
			This routine is entered via a jump or branch
			order just after an I/O operation has occured
			in order to save the DSW and return to the
			calling program.

			EXIT CONDITIONS
			status flag = success or error


.I MT$GET
.I MMT02
MT$GET		MMT02	This procedure reads a block of data from
			the magnetic tape controller.

			ENTRY CONDITIONS
			R0 ->	string address

			EXIT  CONDITIONS
			status = success or error


.I MT$SHUT
.I MMT03
MT$SHUT		MMT03	This procedure closes down the magnetic
			tape channel being used.

			ENTRY CONDITIONS
			none

			EXIT CONDITIONS
			status = success or error


.I MT$PUT
.I MMT04
MT$PUT		MMT04	This procedure writes a block of data to
			the magnetic tape controller.

			ENTRY CONDITIONS
			R0 ->	string address

			EXIT CONDITIONS
			status = success or error



.F

NAME		MODULE			DESCRIPTION
----		------			-----------


.I MT$OPEN
.I MMT05
MT$OPEN		MMT05	This procedure opens up a magnetic tape
			controller channel.

			ENTRY CONDITIONS
			none

			EXIT  CONDITIONS
			Status = success or error

.I MT$FIND
.I MMT06
MT$FIND		MMT06	This procedure finds the next end of file
			marker on the magnetic tape.

			ENTRY CONDITIONS
			none

			EXIT  CONDITIONS
			Status = success or error

.I MT$BACK
.I MMT07
MT$BACK		MMT07	This procedure requests the magnetic tape
			controller to backspace one block on the
			present magnetic tape.

			ENTRY CONDITIONS
			none

			EXIT  CONDITIONS
			Status = success or error


.I MT$REWIND
.I MMT08
MT$REWIND	MMT08	This procedure requests the magnetic tape
			controller to rewind the present magnetic
			tape.

			ENTRY CONDITIONS
			none

			EXIT  CONDITIONS
			Status = success or error

.I MT$MARK
.I MMT09
MT$MARK		MMT09	This procedure marks the tape with an end of
			file mark.

			ENTRY CONDITIONS
			none

			EXIT  CONDITIONS
			Status = success or error

.C Message checking routines.
.T Introduction and routines.

	These routines macros were developed to check and validate
	input messages with as little software effort as possible.


NAME		MODULE			DESCRIPTION
----		------			-----------
.I M$CHECK
.I MMC01

M$CHECK		MMC01	This procedure compares an input message with
			a selected message table and reply -1 if the
			message/keyword is not found.

			ENTRY CONDITIONS
			R0 ->	MESSAGE TO BE VALIDATED
			R1 ->	ADDRESS OF A MESSAGE TABLE

			EXIT CONDITIONS
			R0 =	-1 IF MESSAGE/KEYWORD NOT FOUND
			R0 =	REPLY VALUE IF MESSAGE/KEYWORD FOUND

.I M$HUNT
.I MMC02
.I REPORT
M$HUNT		MMC02	This procedure uses the data structure set up
			by the macro REPORT to use a binary value to
			ascociate it with a text message hence giving
			a simple method of relating error reports to
			plain language messages.

			ENTRY CONDITIONS
			R0 =	BINARY VALUE TO BE LOCATED
			R1 ->	ADDRESS OF A REPORT TABLE

			EXIT CONDITIONS
			IF STATUS = SUCCESS	R0 = ADDRESS OF TEXT
			IF STATUS = ERROR	R0 = 0


.T Data structures and generation macros.

		Message table generating macro.
		-------------------------------


MODULE	NAME				DESCRIPTION
------	----				-----------
.I MESSAGE
.I MX02

MX02	MESSAGE	[minimum characters for match,reply value,check string]
			This macro set up an entry in a message table.
			If no parameter is specified this indicates the
			message table terminator.
			The reply value can be any integer value except
			the value -1. This field could be set up to
			contain a series of switch jump values
			to enable automatics command line processing.
			The minimum characters for match field enables
			this routine to distinguish between say the
			words XXXz and XXXy when only three characters
			have been input.
			The string is the group of characters you wish
			to locate as an answer.

			Note the start of the message table is indicated
			by setting a label just before the first occurance
			of the macro MESSAGE.  for example
			TABSTART:	MESSAGE 1,55,"RUBBISH"
					MESSAGE			;END OF TABLE

.I MX02
.I REPORT
MX02	REPORT	[CONTROL CODE, HUNT VALUE, TEXT STRING]
			This macro sets up an entry in the REPORT table.
			If no parameter is specified this acts as the
			report table terminator and must be used once
			at the end of every report table.
			The HUNT VALUE may be any value including symbolic
.I DSW
			offsets and DSW error reports in symbolic form.
			The CONTROL CODE is normally defaulted as this
			is only used to create text strings that exceede
			one printed line. When an extended string is
			generated the macro automaticaly inserts a line
			feed , carriage return at the start of each
			continuation line and on the last line.
			The permisiable CONTROL CODES are
			FIRST	CONT	LAST
.I FIRST
.I CONT
.I LAST
			The code FIRST indicates the start of the message
			CONT indicates a continuation line and LAST is the
			last line of the report text.
			example report table generation.
			REPORT ,IE.SUC,<"Success status">
			REPORT START,207.,<"Oh Dear">
			REPORT CONT,,<"Something has gone wrong">
			REPORT LAST,,<"try pressing the RETURN key">
			REPORT		;REPORT TERMINATOR

.C Stand alone Serial line device handler/driver.
.T Introduction
.I SERIO

	SERIO MACRO	SERial Input Output controler routine.
	================***====*=====*========================

	This is a customed designed general purpose serial line device
driving routine created by a common MACRO 11 macro.
	The SERIO macro enables the user to develop an absolute application
device driver from a single line of MACRO code.

	SERIO allows you to specify the following options :-
Option	Default		Remarks
(1)	none	The interupt vector address.
(2)	none	The base control and status registers address.
(3)	none	A one or two letter/number identifier for multiply routines.
(4)	STRING	The mode of transfer of the output section.
(5)	CHAR	The mode of transfer of the input  section.
(6)	8	The number of characters allowed in the read ahead buffer
(7)	0	The number of filler character to follow a line feed sequence.
(8)	strip	The condition of the parity bit on input.
(9)	ON	Auto-matic character echo option
(10)	YES	Input  code required ?
(11)	YES	Output code required ?
(12)	TERM	If handler to behave as terminal or device.
(13)	SMART	If smart (VDU) erase option required.
(14)	ESC	If ESCAPE is allowed to terminate a string (if selected).
(15)	0	Size of input string buffer.

.T Building and usage

	SERIO	Created routines have :-

Three entry points
	Entry point +0		Output a string/character
	Entry point +2		Input  a string/character
	Entry point +4		Initialise package

Start address +6 contains the control flagword and the flags may be
accessed to observe the state of the control handler.
Where :-
	The following flags may be of use
BIT			Function
0  = 1		Handler requires re-initialising.
3  = 1		Disable the output section.
6  = 1	*	Transmitter section is busy
7  = 1	*	Input characters have been lost.
8  = 1	*	Escape character terminated the last string
12 = 1	*	This handler is a terminal handler
13 = 1		Smart scope is enabled.
14 = 1		Read no echo function enabled.
15 = 1		Do not strip input parity bit.

	Treat all flags marked with an * character as READ ONLY
	setting or clearing other flags may cause unpredictable results
	other than those indicated above.

At location Start address +8 (Only when string input selected) holds a
count of maximum number of characters to be read to terminate string if
an escape or line feed sequence is not detected. By default this value
is set to input string maximum size.

.F
	How to use the SERIO macro.

	.MCALL SERIO

	SERIO p1,p2,p3,<p4>,p5,p6,p7,p8

Where :-

p1	Is the channel identifier		ie. 01 or AA
p2	Is the base CSR    address		ie. 176500
p3	Is the base Vector address		ie.    300
p4	Is a multiple parameter field where
	some or all of the following options
	may be selected seperated by commas.
	NOECHO		disable auto echo option
	NOESCAPE	disable escape sequence option
	NOSCOPE		disable smart scope function
	NOIN		remove input  code generation
	NOOUT		remove output code generation
	NOPAR		disable parity stripping option
	DEVICE		remove terminal handling functions
	STRING		indicate input section recives data in string form
	OCHAR		indicate output section recives data in character form
p5	Is the read-ahead buffer size
p6	Is the input string buffer size
p7	Is the number of filler characters after line feed sequence
p8	Is the output buffer size (NOT incorporated)

USAGE:-
-----
	CALL SINP**		;(** - is the channel identifier)

	IF SUCCESS	-character mode.	R0 =  ascii character.
			-string mode.		R0 -> string address.

	IF ERROR	-no input.		(buffer empty)

	CALL SOUT**

			-character mode.	R0 =  ascii character.
	!!!		-string mode.		R0 -> string address. 

!!! 	'DON'T' alter the buffer until output finished (check bit 6).

.C SUPER-MAC REFERENCE GUIDE - VERSION 47.
.T SUPER-MAC HEADER.




	LDM 106
	DOC #130-380-007-00
















			      SUPER-MAC
			      =========
			   REFERENCE GUIDE
			   ===============
			      VERSION 47
			      ==========




.T SUPER-MAC DISCLAIMER.



COPYRIGHT (C) 1975	(SUPER-MAC)


DIGITAL EQUIPMENT CORPORATION


The information in this document is subject to change  without  notice
and  should  not  be  construed  as  a commitment by Digital Equipment
Corporation.  Digital Equipment Corporation assumes no  responsibility
for any errors that may appear in this manual.

The software described in this document is furnished to the  purchaser
under  a license for use on a single computer system and can be copied
(with inclusion of DIGITAL's copyright notice) only for  use  in  such
system, except as may otherwise be provided in writing by DIGITAL.

Digital Equipment Corporation assumes no responsibility for the use or
reliability  of  its  software  on  equipment  that is not supplied by
DIGITAL.

NOTE:-

Since the appearance of SUPER-MAC in the public domain, numerous enha-
ncements have been made which improve both the applicability and port-
ability  of  SUPER-MAC  source  code.  During this enhancement process 
every  effort  has been made to maintain compatability for source code
generated under earlier version of SUPER-MAC.

				       Arthur P. Gaughan, JR. 5-dec-78

This manual documents Super-Mac version 47.

In addition the following changes have been made.

	'SOB' to 'SOJ'		(to avoid MACRO-11 conflict)
	TRACE FACILITY in 'PROCEDURE' and 'ENTRYPOINT'.
	'SAVE' macro call in 'PROCEDURE'.
	Listing error correction.
	'LIST' and 'NOLIST' implementation.
						J.S.Clifton. 31-Dec-81


.T SUPER-MAC INTRODUCTION.
.I SUPER-MAC.
	Introduction
	============

SUPER-MAC is a  set  of  structured  programming  macros  that  allows
programs  to  be  written in a high level, easily understood language.
It is assumed that the user is familiar with  macros  in  general  and
with MACRO-11 in particular.

The language statements and clauses within this guide are divided into
three  categories:   Assignment  statement, Conditional statements and
Miscellaneous statement.  The Conditional category  of  statements  is
further  divided  into  Conditional Execution type statements and Loop
Control statements.

There are three branch type statements:  LEAVE, GOTO and JUMPTO.   The
LEAVE  and GOTO statements are cased special branches used with the IF
statement.  They are, therefore, included in the conditional category.
The JUMPTO statement is included in the Miscellaneous category.

As a general  rule,  most  SUPER-MAC  statements  can  be  single-line
statements  or multiple-line (nested) block statements.  A single-line
statement must be completed on one source line;  no continuation lines
are  allowed.  Single-line statements should be as short and simple as
possible.  Comments may also be included on a source  line.   All  the
general  rules,  conditions,  etc.,  that  govern MACRO-11 also govern
SUPER-MAC.  Spacing on a source lne is very important.   The  elements
should  be separated by a comma or a space.  Tabs should never be used
for  spacing.   For  example:   The  expression  A+B  is   interpreted
different than A + B.

All the conditional statements can be written as multiple-line  nested
blocks.   Each level of nesting within a block must be terminated with
an associated END statement.  Each level of nesting should be indented
two spaces.

User written macros or assembly language instructions may be  included
in  a  program if desired.  All  programs  must  begin  with the macro 
call  supmac.  This  call  initializes  SUPER-MAC and TABMAC.MAC. This 
guide contains examples of all statements. In nested  block  examples,
the END statements associated  with  a particular statement are noted.   
When an example includes assembly language instructions, that instance 
is pointed out.  A list of possible error codes is included as well as 
an  assembled  listing  of  some  typical examples.   All legal PDP-11 
source and destination operands are legal in SUPER-MAC.


.T ASSIGNMENT STATEMENT.
.I ASSIGNMENT STATEMENT.
	Assignment Statement
	====================

LET is the only assignment statement contained in SUPER-MAC.

.I LET statement.
	LET STATEMENT
	=============

The  LET  statement  is  an  arithmetic  assignment   or   replacement
statement.

The form of the statement is:

          LET [Destination] <assignment operator> expression
              [Operand   ]

expression is in the form:

          (unary operator) operand  (binary  operator  operand  binary
operator...)

Where:

          (     ) means optional

.I LET statement warning.
                                 NOTE
				 ====

Care must be taken in the  construction  of  a  LET  statement.   Some
constructions   (where  the  destination  operand  type  modifies  the
register used on the formation of the destination address)  appear  to
be  what  the programmer desired, but the assembler will generate code
that is different from the intent.

Example:-
=========

     The statement

          LET (R5)+ := R1 + R2

     will generate the code   MOV R1,(R5)+
                              ADD R2,(R5)+

     not the desired          MOV R1,(R5)
                              ADD R2,(R5)+

In order to get the desired  result,  the  following  construction  is
necessary:

     LET (R5) := R1           ;MOV R1,(R5)
     LET (R5)+ := (R5)+ + R2  ;ADD R2,(R5)+

.F
SUPER-MAC recognizes all the special characters accepted  by  MACRO-11
as  well  as  some  additional assignment/replacement characters.  The
additional assignment or replacement characters are listed below:

.I :=
.I :W=
          := OR :W=           ;These are assignment or replacement
                              ;characters that imply WORD movement.

Example:-
=========

     LET R0 := .PSTPT

Moves the WORD represented by .PSTPT into R0.

.I :B=
.I :==
          :B= OR :==          ;These are assignment or replacement
                              ;characters that imply BYTE movement.

Example:-
=========

     LET R0 :B= @.PSTPT

In this case, the BYTE that is pointed to by PSTPT is moved to R0.

SUPER-MAC has some special operators that are used for bit set and bit
clear operations.  The operators are listed below:

.I LET - bit operators.
.I BIT OPERATORS.
	BIT CLEAR OPERATORS           INSTRUCTION GENERATED
	===================	      =====================

.I NAND
	NAND                          BIC

.I OFF.BY
	OFF.BY                        BIC

	Either can be used since they produce the same code.

	BIT SET OPERATORS             INSTRUCTION GENERATED

.I SET.BY
	SET.BY                        BIS

.I OR
	OR                            BIS

	Either one can be used since they produce the same code.

Examples:-
==========

     LET T.FLAG(R2) := T.FLAG(R2) SET.BY #TP.ENB

     LET T.FLAG(R2) := T.FLAG(R2) OFF.BY #TP.ENB

     LET $SYSCL := $SYSCL OFF.BY #CL.NER

     LET (R2) := (R2) NAND R1
.F

SUPER-MAC accepts all the symbols recognized by MACRO-11.  The special
symbols utilized by SUPER-MAC are listed below:

     SYMBOL                   DESCRIPTION
     ======		      ===========

.I CARRY
     CARRY                    C BIT (carry bit)

.I PUSH
     PUSH                     Keyword destination for pushing on
                              to stack

.I POP
     POP                      Keyword for popping off of stack.

.I TOP
     TOP                      Keyword for top of stack.


The legal binary operators for use in SUPER-MAC are described in Table
1-1.   Table  1-1  shows  the  relationships  that  can be established
between expression terms through the use of binary operators and  also
shows the machine instruction generated when the macro is assembled.

.I LEGAL BINARY OPERATORS.
                              Table 1-1
			      *********
                        Legal Binary Operators
			**********************

  BINARY     EXPLANATION         EXAMPLE              MACHINE
  ======     ===========	 =======	      =======
OPERATION                                           INSTRUCTION
=========					    ===========

.I +
     +       Addition            A + B                  ADD
.I -
     -       Subtraction         A - B                  SUB
.I *
     *       Multiplication      R0 * #2                MUL
.I /
     /       Division            R0 / #2                DIV
.I L.SHIFT
L.SHIFT      Arithmetic
             Left Shift          R0 L.SHIFT1*           ASL
.I R.SHIFT
R.SHIFT      Arithmetic
             Right Shift         R0 R.SHIFT 1*          ASR
.I L.ROTATE
L.ROTATE     Left Rotate         R0 L.ROTATE 1*         ROL
.I R.ROTATE
R.ROTATE     Right Rotate        R0 R.ROTATE 1*         ROR
.I SHIFT
SHIFT        Shift
             Arithmetically      R0 SHIFT #2            ASH
.I C.SHIFT
C.SHIFT      Arithmetic Shift
             Combined            R0 C.SHIFT #3          ASHC
.I XOR
XOR          Exclusive OR        A XOR R5               XOR
.I NAND
NAND         Not AND             (R2) NAND R1           BIC
.I OFF.BY
OFF.BY                           (R2) OFF.BY R1         BIC
.I SET.BY
SET.BY       Inclusive OR        (R2) SET.BY R1         BIS
.I OR inclusive.
OR                               (R2) OR R1             BIS

* = Number designates the number of times the instruction is repeated;
i.e., the number of shifts.

.T UNARY OPERATORS.
.I UNARY OPERATORS.
The legal unary operators are:-
===============================
.I NOT
.I NEG
.I COM
.I -

        -    Negation            NEG
        NOT  Complement          COM

If the assignment operator in a LET statement is not a legal SUPER-MAC
operator, an error message will be generated.
.I LET examples.

Examples:-
==========

     LET (R2) := (R2) - #1              ;This generates DEC (R2)

     LET (R2) := (R2) - #01             ;This generates SUB #01,(R2)

     LET (R2) := (R2) OR R1

     LET R2 := #0                       ;This generates CLR R2

     LET R2 := R1

     LET T.VAL(R2) := $VAL2

     LET R0 := R0 L.SHIFT 3

     LET R1 := R1 + #1                  ;This generates an INC R1

     LET R1 := R1 + #01                 ;This generates an ADD #01,R1

     LET R0 := R0 + CARRY               ;This generates on ADC R0


.T CONDITIONAL EXECUTION STATEMENTS.
.I CONDITIONAL statements.
	Conditional Statements
	**********************

This category of SUPER-MAC statements  is  subdivided  into  Condition
Execution statements and Loop Control statements.



	Condition Execution Statements
	******************************
.I IF statement.
.I IFB statement

		IF STATEMENT
		============
		IFB STATEMENT
		=============

An IF statement causes a conditional transfer or statement  execution.
The IFB statement forces a byte operation.

IF statements can be either a single-line statement or a multiple-line
(block) statement.  The single-line statement takes the form:

.I GOTO statement.
.I LEAVE statement.
.I THEN statement.
.I TEST statement form.
.I GOTO statement.
.I LEAVE statement.
.I THEN statement.
     IF <TEST>      [GOTO ]   SUPER-MAC statement
                    [LEAVE]
                    [THEN ]

The test portion of the IF statement takes the form:

.I CC
                    [CC]
.I CS
                    [CS]
.I EQ
                    [EQ]
.I GE
                    [GE]
.I GT
                    [GT]
.I HI
                    [HI]
.I HIS
Source              [HIS] Destination
.I LE
Operand             [LE] Operand
.I LO
                    [LO]
.I LOS
                    [LOS]
.I LT
                    [LT]
.I MI
                    [MI]
.I NE
                    [NE]
.I PL
                    [PL]
.I VC
                    [VC]
.I VS
                    [VS]

(Note:  these are the MACRO-11 branch instructions  without  the  "B".
GE not BGE.)

A single line  statement  may  have  as  many  arguments  as  desired,
provided that all arguments can be completed on the single line.
IF $NVAL HI #2 GOTO REJ1
.F
.I IF AND statement.
.I IF ANDB statement.
.I AND statement.
.I ANDB statement.

		IF AND STATEMENT
		================
		IF ANDB STATEMENT
		=================

The AND statement is a logical conjunction.  The  expression  is  true
if,  and  only if, both A and B are true.  The ANDB statement forces a
byte operation.  AND can only be used with the IF.  The form is:

     A AND B

Example:-
=========

     IF (R2) EQ (R1) AND 2(R2) EQ 2(R1) THEN RETURN/$RETURN NOERROR

.I IF OR statement.
.I IF ORB statement.
.I OR statement.
.I ORB statement.
		IF OR STATEMENT
		===============
		IF ORB STATEMENT
		================

The OR statement is a logical disjunction.  The expression is true if,
and only if, either A or B, or both is true.  The ORB statement forces
a byte operation.  The OR can only be used with an IF statement.   The
form of the OR is:

     A OR B

Example:-
=========

     IF A EQ #0 OR A NE C THEN LET A := D

The block IF statement requires an END and takes the form:

.I IF block statement.
.I IF ELSE END.
.I END statement.
     IF...........
       coding
          .
          .
          .
          .
          .
        coding
     END

Example:-
=========

     IF A EQ #0
          LET $VAL2 := T.VAL(R2)
     END

.F
.I ELSE statement.
		ELSE CLAUSE
		===========

The ELSE clause is only used with an IF  block.   Used  in  any  other
statement, an error message will be generated.  ELSE must stand on its
own line with no arguments.

Example:-
=========

     IF RESULT IS EQ
       LET $VAL2 := T.VAL(R2)
     ELSE
       LET $VAL1 := R2 + #T.VAL
     END

.I IF statement (nesting).
Multiple IF statements can be nested.  Each multiple-line IF statement
within the nest requires an END.

Example:-
=========

     IF .PNUMH EQ #0
       LET $NVAL := $NVAL + #1
       IF $NVAL LOS #2
         IF RESULT IS EQ
           LET $VAL2 := .PNUMB
         ELSE
           LET $VAL1 := .PNUMB
         END
       END
     END
Special cases of the IF statement perform bit tests.  One  case  tests
to  determine  if the bits are set and the other tests to determine if
the bits are CLEAR.

Examples:-
==========

     IF A SET.IN B THEN...
     IF A OFF.IN B THEN...

.F
Another special case IF statement is a test for zero.

Example:-
=========

     IF A GT #0 THEN...

A third special case is a test  of  current  condition  code  setting.
This is indicated by RESULT IS.
.I IF RESULT IS .. statement
.I SUCCESS
.I ERROR

	NOTE:-	that  SUCCESS  and  ERROR can follow an IS which tests
		the state of the C bit.

		IF RESULT IS SUCCESS THEN .......
		IF RESULT IS ERROR THEN ......

Example:-
=========

.I ON.ERROR
.I ON.NOERROR
     IF RESULT IS EQ THEN...

		ON.ERROR STATEMENT
		==================
		ON.NOERROR STATEMENT
		====================

Both of these statements are special case IF statements that check the
condition  of the C bit.  The ON.ERROR statement tests to determine if
the C bit is set and the ON.NOERROR statements tests to  determine  if
the  C  bit is cleared.  Both statements require an END statement if a
multiple line procedure is required to rectify the  problem  indicated
by the condition of the C bit.  Both statements result in an IF RESULT
IS type statement.

.F
Examples:-
==========

     ON.ERROR
       IF #CL.NER OFF.IN $SYSCL
         CALL/$CALL  $MGOUT
       END
       $POSYM
       CLC                    ;Macro instruction
     ELSE
       $POSYM
       CLC
     END

     ON.ERROR LEAVE SETBLK

     ON.ERROR
       $PUSH #STSPT
       CALL/$CALL  $FCSYM
       INC (SP)+              ;Macro instruction
       ON.ERROR
         LET 16(SP) := 16(SP) + #2
       END
     END

     ON.ERROR
       LET PUSH := T.VAL(R2)
       CALL/$CALL  $RPREG
       CALL/$CALL  @(SP)+
       CALL/$CALL  $SPREG
     END

     ON.NOERROR THEN LET T.FLAG(R2) := T.FLAG(R2)


	LEAVE STATEMENT
	===============
	GOTO STATEMENT
	==============

.I LEAVE statement.
.I GOTO statement.
These statements are similar in that  they  transfer  program  control
from one point to another point.  Their use and purpose are different.

The LEAVE statement is used when it is necessary to transfer out of  a
program  block  or loop due to some condition within the block or loop
that can be tested.  The test is usually made with an IF expression.

.F
.I BEGIN/END named block.
Example:-
=========

     BEGIN ALPHA
          .
          .
       IF RESULT IS NE LEAVE ALPHA
          .
          .
     END ALPHA

In this example, the result of a previous action is  tested.   If  the
result  does  not  equal  zero,  program control is transferred to the
expression that follows the END.
.I WHILE statement.

     WHILE A NE B
          .
          .
         coding
     IF C EQ #0 LEAVE LOOP
          .
          .
     coding
     END <WHILE LOOP>

In this example, if C is equal to zero,  the  LEAVE  will  generate  a
branch outside of the WHILE loop.

The GOTO statement also creates a branch instruction.  The pointer  of
the  branch instruction is the value of the symbolic name given by the
programmer.  The form is:

.I GOTO statement.
     GOTO name

Examples:-
==========

     GOTO SETCM

     IF A EQ B GOTO SETCM

Program control transfers to a routine labelled SETCM.


.I THEN statement.
	THEN CLAUSE
	===========
	
The THEN clause is used in conjunction  with  other  statements.   The
first  statement  performs  a  designated  action  and THEN performs a
second action.  The THEN clause takes the following form:

     THEN arguments

Example:-
=========

     IF (R2) EQ (R1) AND (R2) EQ 2(R1) THEN RETURN/$RETURN NOERROR
.T LOOP CONTROL STATEMENTS.

	Loop Control Statements
	***********************

		FOR STATEMENT
		=============
.I FOR
.I TO
.I DOWNTO
.I BY
.I END
The FOR statement is a means of controlling  loop  execution  used  to
change  the  value  of  an  operand by a designated amount until a set
limit is reached.  The FOR statement is used with the TO,  DOWNTO  and
BY statements.  The form of the FOR statement is:
.I LIMIT
.I INCREMENT

     FOR operand [TO    ] limit [BY increment (optional)]
                 [DOWNTO]
     END

The default condition of the increment is one.  The FOR statement must
contain  an  END statement unless the statement is a single-line entry
followed by a THEN statement.  The THEN statement must be followed  by
arguments:

Example 1:-
===========

     FOR A := B TO C BY D
          .
          .
        coding
     END  .

This example causes B to be moved to A, D is added to A and A compared
with C.  If the comparison fails, the loop process continues until the
comparison passes.  The FOR statement is a  WORD  operation  statement
only.

Example 2:-
===========

     FOR A := B DOWNTO C BY D
          .
          .
        coding
     END

This examples causes B to be moved to A, D is subtracted from A and  A
is  compared  with  C.  If the comparison fails, the process continues
until the comparison passes.

Example 3:-
===========

     FOR R0 := R1 TO R2 THEN LET R4 := R4 / #2

This example causes the contents  of  R1  to  be  moved  to  R0.   The
contents  of  R4  are divided by two and R0 is incremented.  R0 and R2
are compared.  If the comparison fails, the  process  continues  until
the comparison passes.

.F
Example 4:-
===========

     FOR R0 := R1 DOWNTO R2
     LET R4 := R4 * #2
     END

This causes the contents of R1 to be moved to R0.  R4 is multiplied by
two  and  R0  is decremented.  The contents of R0 and R2 are compared.
If the comparison fails, the process continues  until  the  comparison
passes.


		REPEAT STATEMENT
		================
		UNTIL STATEMENT
		===============
		UNTILB STATEMENT
		================

.I REPEAT statement.
.I UNTIL statement.
.I UNTILB statement.

The REPEAT statement  causes  a  procedure  to  be  repeated  until  a
specified  condition  is  met.   The  REPEAT  statement  executes  the
procedures, tests the specified condition and stops  the  repeat  loop
when   the  desired  condition  is  met.   REPEAT  statements  can  be
single-line statement or multiple line  statements.   The  single-line
REPEAT takes the form:

     REPEAT UNTIL condition

Example:-
=========

     REPEAT UNTIL (R0)+ EQ (R1)+

This example can best be illustrated by examination  of  the  assembly
code generated.  The assembler generated the following code:

     B1;;;;;;;
          CMP (R0)+,(R1)+
          BNE B1
     E1;;;;;;;

As can be seen the comparison is repeated until it  passes,  then  the
action stops.

There are two types of multiple-line  REPEAT  statements.   The  first
type  repeats  a  procedure  until  a specified condition is met.  The
second type is an infinite repeat (repeat loop) and is termiated by an
END statement.

.F
.I REPEAT statement.
.I UNTIL statement.
.I UNTILB statement.
Examples:-
==========

     REPEAT
          CALL/$CALL  C,<R0,R2>
     UNTIL R4 NE, R0

The next examples contains a LEAVE statement and was  coded  within  a
BEGIN block.

     BEGIN ALPHA
          .
          .
          .
     REPEAT
       CALL/$CALL  F <FOO,BAR>
       IF RESULT IS NE LEAVE ALPHA
          .
          .
     END <REPEAT LOOP>
          .
          .
     END ALPHA

The UNTIL statement can only be used within a REPEAT  statement.   The
UNTIL  statement  defines  the  condition(s) that stop the REPEAT from
looping.  The UNTILB forces a byte operation.  An error  message  will
be generated if UNTIL is used in a statement other than a REPEAT.

		THRU STATEMENT
		==============

.I THRU statement.
.I END statement.
The THRU statement is used  to  control  loops.   The  statement  must
contain an END statement.

The  THRU  statement  generates  an  SOB  (subtract  one  and  branch)
instruction.  The statement takes the form:

     THRU arguments
     END

The first argument must be a register or an expression  (LET)  with  a
register as the destination.  If the first argument is not a register,
an error message will be generated.  The register  contains  a  number
that represents the number of times the action must loop.

.F
Example 1:-
===========

     IF R2 HI # 6 THEN LET R2 := #6
     THRU R2
          MOVB (R0)+,(R1)+ ;Note macro instruction
     END

In this example, R2 contains an integer between 1 and  6.   Each  time
the  MOVB  instruction  is  executed,  the  SOB subtracts one from the
contents of R2.  When R2 becomes zero, the loop is left.

		WHILE STATEMENT
		===============
		WHILEB STATEMENT
		================

.I WHILE statement.
.I WHILEB statement.

The WHILE statement establishes a condition  that  permits  (controls)
action  from  other  statements.  As long as the condition exists, the
action(s) will be permitted.  The form of the statement is:

     WHILE condition
       coding
          .
          .
          .
       coding
     END

The WHILEB statement forces a byte operation.

Example:-
=========

     LET R5 := (R4)+                    ;Get start addr of table
     WHILE R5 LO (R4)
       CALL/$CALL  DTBL                       ;Go display entry
       LET R5 := R5 + #S.SYCT           ;Get next entry
     END

		$$END STATEMENT
		===============

.I $$END

The $$END statement supplies an END if those  statements  are  missing
within  nested  blocks.   The  $$END  prints a message on the assembly
listing for the missing END(S).  The user should check the source code
to determine if the assembled code will execute as intended.  $$END is
intended for  the  detection  of  user  "error"  (i.e.,  missing  END)
conditions.



.T MISCELLANEOUS SUPER-MAC STATEMENTS.
	Miscellaneous Statements
	************************

	BEGIN/END STATEMENT
	===================

.I BEGIN statement.
.I END statement.

The BEGIN/END statement provides  a  mechanism  for  escaping  from  a
routine  in  case some problem develops.  The block of code associated
with the BEGIN statement is terminated with the  END  statement.   The
statement takes the form:

     BEGIN name                         ;Begins a contiguous block
                                        ;of code known as 'name'
     IF RESULT ... LEAVE name           ;A conditional method of
                                        ;escape
                                        ;from 'name'. The Branch
                                        ;pointer points to END name.
     ON.ERROR LEAVE name                ;Another method of escape
     END name                           ;End of block.


Following are two examples of the BEGIN/END statement:

Example 1:-
===========

     BEGIN SETBLK
       $PHSYM                           ;PUSH symbols (macro call)
       CALL/$CALL  $SCHLT                     ;Search table.
       ON.ERROR
         LET...
         CALL/$CALL ...
         ON.ERROR LEAVE SETBLK          ;Escape if C bit set.
         IF...
          LET...
         ELSE
          LET...
         END
         LET...
         LET...
         LET...
       END                              ;END of ON.ERROR
       LET
       $POSYM                           ;POP of symbols (macro call)
       RETURN/$RETURN
     END SETBLK                         ;END of SETBLK

.F
Example 2:-
===========

     BEGIN ALPHA
            IF...GT...B THEN CALL/$CALL ...   ;One line IF statement
            REPEAT UNTIL...             ;One line REPEAT
            REPEAT                      ;Multiple line REPEAT

              CALL/$CALL ...
            UNTIL...EQ...               ;Terminate condition
            CALL/$CALL 
            REPEAT                      ;REPEAT loop

            CALL/$CALL ...
            IF RESULT...LEAVE ALPHA     ;One line IF and a LEAVE

            WHILE...IS...THEN...
            END <REPEAT LOOP>           ;End of the REPEAT loop
     END ALPHA                          ;End of the Alpha block



.F
	CALL/$CALL  STATEMENT  (USE CALL FOR -11D/IAS AND $CALL FOR -11M)
	=====================

.I CALL statement.
.I CALL$ statement.

The ($) CALL statement is used to transfer control (via a JSR PC) from
one  program  unit to another.  It may also be used to pass parameters
in the registers (R0-R5) between those program units.  Upon completion
of  the  call,  execution  is  returned to the statement following the
CALL/$CALL .  The form of the CALL/$CALL statement is:

     CALL/$CALL  NAME, <ARGS>

NAME is the symbolic name of the program unit being  called  and  ARGS
are parameters.  ARGS is optional and if used must be in brackets.  If
ARGS is used without brackets, an error  message  will  be  generated.
The  ARGS  may  have  six  parameters.  The position of the parameters
within the ARGS brackets indicate the register that will contain  that
particular  parameter.   Register designations are from left to right,
with R0 as the first.  If more  than  6  parameters  are  included,  a
warning message will be generated.

Examples:-
==========

     CALL/$CALL  $SCHLT <#$DYNTB,R1>

     CALL/$CALL  $FLSYM

     CALL/$CALL  DTBL

     CALL/$CALL  F <FOO,BAR>

In the last example, FOO is moved to R0, BAR is moved to R1 and a  JSR
PC  is  generated to F.  In the next example, #X is moved to R0, #Y is
moved to R1, Z is moved to R2 and the JSR PC is to E.

     CALL/$CALL  E <#X,#Y,Z>

When macros are nested, ARGS must have multiple brackets, for example:

     IF A EQ B THEN CALL/$CALL  C <<<R0,#D>>>

The example shown uses one bracket pair for each statement,  one  pair
for the IF, one for the THEN and one for the CALL/$CALL.

.F
	CALLG STATEMENT
	===============

.I CALLG statement.
.I FORTRAN PARAMETER BLOCK

The  CALLG statement (call with general arguments) is used to transfer
control  from  one  program  unit to another and to pass parameters to 
program  unit  via a FORTRAN COMPATIBLE PARAMETER BLOCK. The parameter
block  is built at runtime and follows the FORTRAN convention for null
arguments  (C.F.  The FORTRAN IV and the FORTRAN IV+ USER'S GUIDE) and
arguments  count.  General purpose register R5 is first saved, used to
point  to the head of the parameter block on the call out of line, and
then restored on return. No other registers are used/preserved - it is
the  user's responsibility to save/restore registers as necessary. The
.I FORTRAN LIBRARY CALLS.
CALLG statement may be used to call either FORTRAN LIBRARY SUBROUTINES
which  expect  an  R5 call or any MACRO-11 subroutine which is FORTRAN
CALLABLE.

N.B!!!!!

In either of these cases care must be used in formatting the parameter
list  in the CALLG statement to ensure that "CALL BY NAME" is employed
rather  than  "CALL  BY  VALUE".  In  most  cases this will mean using
immediate mode addressing (mode 2 - register 7). However, the require-
ment simply stated is as follows:-

The  parameter  list must be a list of "ADDRESSES" of arguments rather 
than the arguments themselves!

The  CALLG  statement  may also be used to call NON-FORTRAN compatible
MACRO-11  subroutines  in  which  case  the resolution of the "CALL BY
NAME"  - "CALL BY VALUE" conflict is at the discretion of the program-
mer. In all calls the nesting rules described for $CALL apply.

Examples:-
==========
	CALLG	SPLAT		;No arguments  -  use only for FORTRAN 
				;type  compatability,  else use $CALL/
				;CALL.

	CALLG	SPLAT	<#ARG1,,#ARG3>

	CALLG	SPLAT	<#ARG1,,R0,,STIPL>

.F
	RETURN/$RETURN 	(USE RETURN FOR -11D/IAS AND $RETURN FOR -11M)
	==============
.I RETURN statement.
.I $RETURN statement.

The RETURN statement is used to return control from a subprogram  unit
to  the  calling  program  unit.   The  statement allows a return with
status, with a register or both.  The statement takes the form:

     RETURN/$RETURN STA,REG

Examples: -                    Machine Instructions
==========

RETURN/$RETURN WITH R5                RTS R5

.I ERROR
RETURN/$RETURN ERROR R2               SEC
	                              RTS R2

.I NOERROR
RETURN/$RETURN NOERROR R5             CLC
	                              RTS R5

RETURN/$RETURN ERROR                  SEC
	                              RTS PC

RETURN/$RETURN NOERROR                CLC
	                              RTS PC

.I STAT
RETURN/$RETURN STAT R5                MOVB STAT,-(SP)
	                              ROLB (SP)+
	                              RTS R5

RETURN/$RETURN R4                     MOVB R4,-(SP)
	                              ROLB (SP)+
	                              RTS PC

RETURN/$RETURN ,R5                    RTS R5


.F
	POP Statement
	=============

.I POP statement.

The POP statement is used for popping word data  off  the  stack.  The
statement takes the form:

     $POP P1,P2,P3,...P10

The  argument(s)  (P1,P2...) can be any legal destination WORD operand
of  they  may be TOP in which case the TOP (WORD) element on the stack
is POPPED into never-never land.

Example: -                     Generated Code
=========

	POP R0,R4              MOV (SP)+,R0
                               MOV (SP)+,R4

.I TOP
	POP R0,TOP	       MOV (SP)+,R0
			       MOV (SP),(SP)+	

The  user  will  note that since MOV instructions are used throughout,
the CARRY BIT is preserved across all POPS.

	POPB Statement
	==============
.I POPB statement.

The  POPB  statement  provides  a similar facility fo BYTE dat as that
provided by POP. The arguments (P1,P2...) can be any legal destination
BYTE  operand. However, they may NOT be TOP. The POPBed byte is always
the  low-order  byte  on  the  top  of  the stack. Remember, each BYTE
POPBed  from  the  stack  actually  pops  one WORD from the top of the 
stack.

	PUSH Statement
	==============

.I PUSH statement.

The  PUSH  statement provides a method for pushing WORD data on to the 
stack. The statement takes the form:

     PUSH P1,P2,P3...P10

Example:-                     Generated Code
=========

     PUSH R4,R0               MOV R4,-(SP)
                              MOV R0,-(SP)

	PUSHB Statement
	===============

.I PUSHB statement.
The  PUSHB  statement  provides  a method for pushing BYTE data on the 
stack.  The  argument(s)  (p1,p2...)  can  be  any  legal  source BYTE
operand. The  PUSHed operand always occupies the low-order byte on the
top  of  the  stack  with  the high-order byte on the top of the stack
CLEAR.  Remember,  each byte  PUSHed actually reserves one WORD on the
stack.
.F
	JUMPTO Statement
	================

.I JUMPTO statement.

The JUMPTO statement creates a jump (JMP) instruction with the pointer
pointing to a symbolic name given by the programmer.  The form is:

     JUMPTO name



	CASE(B) Statement
	=================

.I CASEB statement.
.I CASE statement.

CASE(B)  are  statement(s) that will issue a call to a subroutine that
can  be selected  by a variable.  CASE(B) must be terminated by an END 
statement.
The form of the CASE(B) statement is:

     CASE(B) variable

     Routine 0
     Routine 1
     Routine 2
     Routine 3
        .
        .
     Routine n
     END

where:  variable is 0,1,2,3...n
.I TOP

The  selector  variable  can  be any legal BYTE (CASEB) or WORD (CASE)
operand  that  contains  the  desired  number  or  it can be TOP.  TOP
signifiies  either  the  low-order  BYTE (CASEB) or WORD (CASE) on top 
of  the stack. If TOP is used, the TOP WORD/BYTE entry on the stack is
altered.

Example:-
=========

     LET R0 := #2
     CASE R0             or        CASE #2
       ADDVAL
       SUBVAL
       ORVAL

     END

Upon  completion  of the CASE(B) (END), control will be transferred to 
the ORVAL subroutine.  When the ORVAL has finished, i.e., has executed
a RETURN, execution will be resume at the statement following the END.
The  programmer  must be careful to validate the range of the variable
for  use  with the CASE(B) statement. (Note: CASE(B) does not generate 
PIC position independent code).

.F
	PROCEDURE Statement.
	====================

.I PROCEDURE statement.

PROCEDURE  is  a  statement  which allows the programmer to implicitly
establish an entry point for a subroutine (procedure). The form of the
PROCEDURE statement is:-

	PROCEDURE	NAME,TYPE,SAVE

Where  NAME  is  any legal MACRO-11 label. TYPE may be assigned either 
the  keyword  LOCAL  or  GLOBAL. If TYPE is unspecified the default is
LOCAL. If type is unrecognised the default is GLOBAL. SAVE may be used
as a savereg by calling the appropriate macro.

	ENTRYPOINT Statement
	====================

.I ENTRYPOINT statement.

ENTRYPOINT  is  a  statement which allows the programmer to implicitly
establish  an  alternate  entry  point label for a procedure. The form
of the ENTRYPOINT statement is:-

	ENTRYPOINT	NAME,TYPE

Where  NAME  is  any legal MACRO-11 label. Type may be assigned either 
the  keyword  LOCAL  of  GLOBAL. If TYPE is unspecified the default is
LOCAL. If TYPE is unrecognised the default is GLOBAL.

	PROBE and PROBEB Statement
	==========================

.I PROBE statement.
.I PROBEB statement.

PROBE  and  PROBEB  enable the programmer to generate an inline TST or 
TSTB  instruction and thus set up the condition codes for a subsequent
IF RESULT IS ... conditional test.



.T SUPER-MAC ERROR MESSAGES.
.I ERROR MESSAGES, SUPMAC.
	ERROR MESSAGES
	==============

Listed below are the error messages generated by SUPER-MAC.

     STACK UNDERFLOW!!!

     IF SYNTAX ERROR --- IS

     ELSE SEEN IN OTHER THAN IF BLOCK

     UNTIL SEEN IN OTHER THAN REPEAT BLOCK

     --- MUST BE A REGISTER

     --- STRANGE SUPER-MAC STACK VALUE

     --- ...ARGS MUST BE WITHIN <>

     --- NOT A LEGAL ASSIGNMENT OPERATOR

     6 ARG MAX (R0-R5)

     --- NOT A LEGAL OPERATOR



.C DECISION TABLES - REFERENCE GUIDE.
.I CAA DISCLAIMER.
 
 
 
 

COPYRIGHT (C) 1981 (TABLE-MAC)
 
 
CIVIL AVIATION AUTHORITY
 
 
The  information  in this document is subject to change without notice
and  should  not  be  contrued  as  a commitment by the CIVIL AVIATION 
AUTHORITY  who assume no responsibility for any error which may appear
in this manual.
 
 
 
 

	AUTHOR:-     	      J.S.Clifton
		       Civil Aviation Authority.
		      Air Traffic Evaluation Unit.
			     Hurn Airport,
			     Christchurch.
			        Dorset.
			        England.




.T DECISION TABLES IN MACRO - 11.
.I DECISION TABLE THEORY.
 
 
 
 
 
 
	DECISION TABLES IN MACRO - 11, THEORY
	=====================================
     

.I FLOW DIAGRAM.
Decision  tables  may  be  considered  to  be  an affective substitute
for,  or  an  auxiliary  aid  to the flow diagram as well as a program
in their own right.
     
The  decision  table  provides  information  concerning  problems  and
solutions   in  a  concise  tabular  format  that  is easy to read and
understand.   This  tabular  approach  is  particularly useful in sit-
uations involving complex logic.
     
The  basic  structure  of  the  table  forces the  person concerned to
formulate  a  clear  statement  of conditions  and actions and to con-
sider ALL POSSIBLE LOGICAL combinations of the conditions.
       
.T DECISION TABLE ELEMENTS.
.I DECISION TABLE ELEMENTS.
 
 
 
 
 
 
	BASIC ELEMENTS
	==============
              
.I CONDITION STUB.
.I CONDITION ENTRY.
	CONDITION STUB          CONDITON ENTRY.
	==============          ===============
     
	List of relevant	All combinations of conditions
	conditions              that must be considered seperately


      
.I ACTION STUB.
.I ACTION ENTRY.
	ACTION STUB		ACTION ENTRY
	===========		============
	Actions to be taken	Actions to be taken for each 
	in all circumstances	particular set of conditions.
      
Example:-
=========
       
We  wish  to  play  golf on Saturday.  It will depend on two things  -
whether  or  not  the grass  needs cutting and the weather.  VIZ, - if
the  weather  is  fine  and  the grass needs cutting, cut the grass in
the  morning  and  play golf in  the afternoon. If the weather is fine
but  the  grass  does  not  need  cutting, play golf in the moring. If
its raining do neither.

      						R1  R2  R3  R4

	C1	Is the weather fine.		Y   Y   N   N
	C2      Does the grass need cutting.	Y   N   Y   N
 
	A1	Cut the grass Sat. a.m. 	X
	A2	Play golf     Sat. a.m.             X
	A3	Play golf     Sat. p.m.		X
       

.T TYPES OF DECISION TABLE.
 
 
 
 
 
 
	TYPES OF DECISION TABLE.
	========================

There are 3 types of Decision table.
       
.I LIMITED ENTRY.
		LIMITED ENTRY.
		==============         
        
The  previous  table  falls, into  this  category. The  condition stub
specifies  completely  the  question  and  the  condition  entries are
YES(Y),  NO(N)  or  Not  Applicable  (-).  Logically,  question  order 
doesn't  matter  but  practically  it could be important when it comes
to condensing.
         
.I EXTENDED ENTRY.
		EXTENDED ENTRY.
		===============
      
Suitable  for  initial  problem  definition as it gives greater flexi-
bility  in  expressing  each  condition and action.  In this form only
part  of  the  condition  is contained in the stub, the rest appearing 
in the entry area.
       
Example:-
=========
	STUB		ENTRY
        ----            -----
        age             under 21   over 21   over 25   over 25
      
.T DASH RULE/NESTING OF.
 
 
 
 
 
 
.I MIXED ENTRY.
		MIXED ENTRY.
		============
        
A  combination   of  (a) and (b). The most flexible form for manual or
program  use.  It  can  be used  to  represent  the single and complex 
case with equal ease.

       
.I THE DASH RULE.
	THE DASH RULE.
	==============
      
Enables   the   tables   to   be  considerably  condensed  in  certain 
circumstances.
     
In certain  situations, when one of the major conditions is satisfied, 
the  motion specified is independent of the minor conditions.
       
In this case the minor condition entries are replaced by dashes.
	(see Problem 2).
       

.I NESTING TABLES.
	NESTING TABLES.
	===============
      
If  there  are  so many conditions that the decision table becomes too
large  to  handle,  the  problem  may be easily segmented. This can be 
achieved  by  defining  some  of the actions so that control is trans-
ferred to another table.
         
Example:-
=========

	GOTO Table 2.
        
.I GOTO   
.I OPEN AND CLOSED TABLES.
	OPEN AND CLOSED TABLES.
	=======================
       
.I GOTO
A  table  is  said  to be  'open' if the last action is  GOTO  another 
table  name.  In  a  closed  table the  final action does not  specify 
entry  to  another  table.  If  the  closed  table  is  to represent a 
subroutine of  a  program  then  control  will  return  to  the master
table.
        
         
.T DECISION TABLE CONVERSION INTO OPERATIONAL COMPUTER PROGRAMS.
 
 
 
 
 
 
	CONVERSION INTO OPERATIONAL COMPUTER PROGRAMS.
	==============================================
       
	FOUR MAIN WAYS:-
	----------------
      
	1. By a programmer, using accepted conversion techniques.
      
.I PRE-PROCESSOR.
	2. By  a   Pre-processor,  a  software  program  that works on 
	Tables  where  Condition  and Action statements have been  ex-
	pressed  in,  say,  COBOL or FORTRAN and produce a program  in
	that language.
       
.I DIRECT COMPILER.
	3. By a Direct Compiler, producing machine Code programs.
       
.I INTERPRETATIVE PROCESSOR.
	4. By  an  Interpretive   Processor, an object  program loaded 
	into  the   computer,  which  both  interprets  and  processes 
	data at runtime.
             
          
.T ADVANTAGES CLAIMED FOR USE OF DECISION TABLES.
.I ADVANTAGES CLAIMED FOR.
 
 
 
 
 
 
	ADVANTAGES CLAIMED FOR USE OF DECISION TABLES.
	==============================================
        
            
	1. The  person  concerned is  forced to make a clear and comp-
	lete statement of the problem.

	2. The table is easy to read and use.

	3. Decision  tables  allow  a  problem  to  be segmented, each 
	segment being represented by a separate table.
      
	4. Condition  tests  are  separated from  actions to be taken, 
	making  it  easy  to isolate the set of conditions which hold.
       
	5. The  table  presents  a  standard  format which immediately 
	shows up any anomalies.
         
	6. Tables are easy to modify and maintain.
                
	7. A  table  can readily provide input to a program which will 
	permit direct coversion to a computer program.
      
	8. The  decision  table permits a problem to be fully recorded 
	without  imposing  a  particular sequence of operations on its 
	solution.
      
      
A  computer  consultant  who has used Decision tables rather than flow
charts  as  a  means of communication between Analysts and programmers 
makes the following claims:-
         
	        
	1. Provide  clear  communication  of  the  requirements to the 
	programmer.
        
	2. Clear  connection  between the program written and the sys-
	tem required.
      
	3. Simplicity  of  coding decreasing the work load on the dep-
	leted programming staff.
       
	4. Ease of checking logic of program written.
      
	5. Capability of splitting long programs into modules.

        
.T DECISION TABLE IMPLEMENTATION IN MACRO - 11.
 
 
 
 
 
 
	DECISION TABLE IMPLEMENTATION.
	==============================
         
     
	INTRODUCTION.
	=============
        
The  decision  table  facility  in  MACRO-11 allows the user to define 
program logic in a concise yet powerful manner.
       
              
.I FACILITIES AND USES.
	FACILITIES AND USES OF DECISION TABLES IN MACRO-11.
	===================================================
      
MACRO-11 can process limited or extended entry decision tables.
       
.I SUPERMAC.
.I IF
.I CALL
.I REPEAT
.I EXIT
Multiple  decision  tables  may be specified and mixed with 'SUPERMAC'
procedures  and  statements  as  well  as  basic macro-11 instructions 
and  linkage  may  be  carried  out  from  conditions  (via IF or CALL 
verbs) or actions (via CALL,GOTO,REPEAT,EXIT verbs).
        
Supermac  statements,  actions  and   conditions  may  be mixed in any 
order in  decision   tables  but  decision  tables  cannot  be  nested 
within  each  other,  though  a decision table can be nested within an 
IF,THEN,ELSE statement.
.I THEN
.I ELSE
         
All  'MACRO-11'  and  'SUPERMAC'  arithmetic  operations  can be perf-
ormed (LET statement).
       
Else rules can be defined.
        
      
.T INTERPRETATION OF MACRO-11 DECISION TABLES.
.I DETAB INTERPRETATION.
 
 
 
 
 
 
	INTERPRETATION OF MACRO-11 DECISION TABLES.
	===========================================
        
.I RULE MASK TECHNIQUE.
.I DETAB
.I CONDITION CHECKS.
Decision  tables  in  MACRO-11  are  interpreted  using  a  rule  mask 
technique. When  the  DETAB MACRO is defined it sets  up 2 words,  one
which  sets  the else rule and one with all bits set, whose bits  will
be  cleared  as  the  results  of condition checks. Each condition  is
evaluated   serially  and  actions corresponding to the rule or  rules
satisfied  are  carried  out  in  turn.  It  is important to note that
MACROS  will  process  decision  tables in which more than one rule is
satisfied. Consider the following decision table.
            
	C.	IF    SEX    EQ    MALE   [   Y   -   ELSE
     
	C.	IF    AGE    GT    #21    [   -   Y    -
       
                   
	A.	LET COLUMNS:=  SPACE      [   X   X    X
                
	A.	LET COL1 := "*"           [   X   -    -
     
	A.	LET COL2 := "*"           [   -   X    -
     
	A.	LET COL3 := "*"           [   -   -    X
        
            
Assuming the data presented consists of:-
                
		NAME -	Edwards     sex - male     age - 18
			Thomas            female         30
			Jones             female         16
			Jenkins           male           35
        
- then the output produced is as follows:-
          
		NAME        COL1        COL2        COL3
               
		Edwards      *
		Thomas                   *
		Janes                                *
		Jenkins      *           *
        
        
.F
.I ELSE rule.
 
 
 
 
 
 
Having  evaluated  the  two  conditions for 'Edwards' MACRO would find
that  only  rule  1  can be satisfied. For 'Thomas' and 'James' rule 2
and  the  ELSE  rule  are  satisfied  respectively,  in  the  case  of
'Jenkins'  after  evaluating  the  two  conditions  it  is  found that 
rules   1  and  2  are  both satisfied. This is a situation where more 
than  one  rule  is  satisfied. MACRO processes the actions by working 
serially  through  the  actions  and  carrying  out  any actions which 
have  at  least   one X specified  in a satisfied rule. Thus the first 
action  to  spacefill  the  columns  is  performed. Then an * is moved 
to  column  1  and  an  *  is  also  moved to column 2. Note that this 
method  implies  only  one  pass through the table;  i.e. Macro decis-
ion  tables  does  NOT  process  the conditions and actions for rule 1 
(if satisfied) --- and  then  return  to  the  start  of  the table to 
process  the  conditions   and  actions  for  rule 2.  It is important 
that  the  reader  appreciates  that  MACRO decision tables are inter-
preted in this way.
         
.I RELEVANCE TESTING.
Relevance  testing  has  been  incorparated  for  all  decision  table 
verbs and macros.
         
          
.T INCOMPLETE DECISION TABLES.
.I INCOMPLETE DECISION TABLES.
 
 
 
 
 
 
	INCOMPLETE DECISION TABLES.
	===========================
           
An  incomplete  discision  table  is  one  in  which  not all possible
combinations of conditions are catered for.
           
Example:-
=========

		C.   IF RECTYPE EQ #20      [   Y    Y    Y
                 
		C.   IF PRODCODE EQ #121    [   Y    N    N
      
		C.   IF PRODGP EQ #2        [   -    Y    N
      
		A.   GOTO TABA              [   X    X    -
      
		A.   GOTO TABB              [   -    -    X
       
The  above  table  is  incomplete  as  the  rule  for  the  case where 
RECTYPE  is  not  equal  to  20 has been omitted. An incomplete decis-
ion table can always be completed by the addition of an ELSE rule.
.I ELSE
.I IGNORE RULE.
.I IMPLIED ELSE.
      
Decision  table  MACROS  will  process an incomplete decision table by
always  providing  an  ELSE  rule  which is entered when no other rule 
is  satisfied.   Reaction  IGNORE  is  supplied by the MACROS for this 
implied  ELSE  rule.   The  above  decision table is interpreted as if 
it were.
        
		C.   IF RECTYPE EQ #20      [   Y    Y    Y   ELSE
     
		C.   IF PRODCODE EQ #121    [   Y    N    N     -
     
		C.   IF PRODGP EQ #2        [   -    Y    N     -
     
		A.   GOTO TABA              [   X    X    -     -
     
		A.   GOTO TABB              [   -    -    X     -
      
		A.   IGNORE                 [   -    -    -     X
       
         
The  rule  supplied  by  MACRO  for  any  incomplete decision table is
known as the implied ELSE/IGNORE action.
       
.I DETEND
The  results,  when  the  implied  ELSE rule is satisfied in the above
example  is  to  by-pass  the actions to the next in-line instruction.
If  the  DETEND  macro  is used then the 'error bit' will be set and a
RETURN generated.
       

.T MACRO DECISION TABLE FORMATS.
.I DECISION TABLE FORMATS.
 
 
 
 
 
 
	MACRO DECISION TABLE FORMATS.
	=============================
       
This  section  describes  the  format  and  rules governing the use of
decision  tables  in  MACRO.  Basically these  consists of four MACROS
(DETAB / C. / A. /DETEND)
.I C.
.I A.
.I DETEND
       
.I DETAB  name,global/local
		DETAB  name,global/local
		-----
       
Each  decision  table  is  introduced  by  this directive in the above
format.  Name  is  optional  and  may  be  any  MACRO-11 valid format, 
type  may  be  either  local  or global and if not specified, local is 
assumed.
       
'DETAB' also sets up the appropriate mask words and repeat label.
      
Following  the  DETAB  macro  the  user  may  specify  other   macros, 
instructions, conditions or actions.
     
.I INITIAL ACTIONS.
.I GENERAL ACTIONS.
Macros  and  macro  instructions  will  be actioned regardless and can
be considered as INITIAL or GENERAL actions.
      
There  is  no  limit  to the  number of details which may be specified
as initial actions, conditions or actions.
      
There  is  a  limit  to  the number of rules which may be specified in
a  MACRO  decision  table.   No  more  than 16 rules may be specified,
including an explicit or implicit ELSE rule.
.I EXPLICIT ELSE
.I IMPLICIT ELSE
       
Comments  may  be  made  in the standard MACRO way, namely following a
semi-colon.
       
        
.T ......CONDITIONS.
.I CONDITIONS.
.I C. test [ rules
 
 
 
 
 
 
		CONDITIONS.
		===========
      
		Format:-	C.  test    [   rules.
        
The  'test'  will  normally be  done with a SUPMAC 'IF' statement such 
as  IF  R0  EQ  R1,  or  it can be a Procedure, Detab or Label 'call'; 
or  a  macro  that  returns SUCCESS or ERROR. Note that IF may be used 
in place of CALL.

.I Delimiter '['         
The  '['  is  a  delimiter  used  in  both  conditions  and actions to
seperate the test or action from the rules.
        
The  following  items  may  appear  in  the rules section of a limited
entry MACRO decision table.
.I Y(es)
.I S(uccess)
.I T(rue)
.I N(o)
.I E(rror)
.I F(alse)
       
		Y, S, T      for  YES, Success or True.
   
		N, E, F      for  NO,  Error or False.
      
		-  or .      for  irrelevant or immaterial.
       
		ELSE         for  the ELSE rule.
           
ELSE  may  only  appear  in  the last rule of the first condition and
only - or . may  appear  in  this  rule  for  the remaining condition
entries.
       

.T ......ACTIONS/DETEND.
.I ACTIONS.
.I A. actions [ rules
 
 
 
 
 
 
		ACTIONS.
		========
        
	Format:-	A.  action  [  rules.
         
	             
The  'action'  can  consist  of  any  standard  macro  instruction  or 
macro with a limit of 5 additional parameters.
.I Delimiter '['         
        
After  the  delimiter  ([)  the items  allowed  in  the rules  (action 
entry) of a limited entry MACRO decision table are.

        
	X    	for	perform the action.
    
	- or .  for	do not perform the action.
        
If  the  entry  is blank the action macro assumes an X is required for 
every rule.
         
           
.I DETEND.
		DETEND.
		=======
         
This  is  an  optional  terminator  for  a  decision table, if  one or 
more  rules,  other  than  ELSE  are  true, then  its sets the success 
flag  and  issues  a  RETURN  or  if  ELSE  it sets the error flag and 
issues a RETURN.
.I RETURN
.I EXITING (detabs).
         

Exiting can be programmed by using the following macros.
      
	EXITTRUE / EXITSUCCESS / EXIT T / EXIT S  -  success return.
		
	EXITFALSE / EXITERROR / EXIT F / EXIT E   -  error return.
   
	GOTO  name	-  unconditional branch.
    
	REPEAT          -  control returns to start of present detab.
.I REPEAT
.I GOTO
      

.T ......EXTENDED ENTRIES.
.I EXTENDED ENTRIES.
 
 
 
 
 
 
	EXTENDED ENTRIES.
	=================
      
A  facility  included in  MACRO-11 decision tables is that of extended
entries,  where  in  both  conditions and actions one parameter can be
extended  into the rules section. Consider the following table.
      
        
	C.	IF    R0    EQ    #1    [  Y    -    -    ELSE
       
	C.	IF    R0    EQ    #2    [  -    Y    -      -
     
	C.	IF    R0    EQ    #3    [  -    -    Y      -
     
	A.	CALL ONE		[  X    -    -      -
     
	A.	CALL TWO		[  -    X    -      -
      
	A.	CALL THREE		[  -    -    X      -
       
In extended entry form this may be re-written as follows.
      
	C.	IF   R0     EQ ?	[  #1   #2    #3   ELSE
    
	A.	CALL  ?			[  ONE  TWO  THREE   -
        
	 
In  the  condition,  only  the  true test is made, for example compare 
the  two  tables. In  an  extended  macro  or call validity checks are 
made  first,  even  in  a  condition,  thus  all conditions may not be
actioned.  Only  one  (but  any)  parameter,  may  be  extended and is 
marked by a question mark.
       

.T DECISION TABLE EXAMPLE.
.I DECISION TABLE EXAMPLE.
 
 
 
 
 
 
	EXAMPLE.
	========
         
This  is  not  a  practicle  example  but  attempts  to show all macro
formats. Consider as possible statements.
       
        
DETAB	FIRST,GLOBAL.
        
	SAVE	R1,R2,R3
       
C.	IF    R0    EQ    #1		[   Y    Y    -    -    ELSE
     
C.	IF    R0    EQ    ?		[   -    -    #2   #3     -
     
	SAVE  R0
       
A.	LET   R0    :=    ?		[   #4   #5   #6    #7    -
     
C.	CALL ONE			[    -    Y    Y    -     -
     
C.	IF ONE				[    -    Y    Y    -     -
    
C.	IF  ?				[   ONE  TWO THREE FOUR   .
        
A.	TLOOKUP  R0,DSPMEM		[    X    X    X    X     .
     
A.	CALL  INITIALISE		[    .    X    .    .     .
    
A.	MOV  ?, R0			[    R1   R2   R3   .     .
       
	UNSAVE  R1,R2,R3,R0
      
DETEND.


.T DEBUGGING & TRACING FACILITIES.
.I DEBUGGING FACILITIES
 
 
 
 
 
 
	DEBUGGING FACILITIES
	====================
 
	THESE CAN ALSO BE USED IN 'SUPER-MAC' AND OTHER MACROS.

.I LISTING FACILITIES
		LISTING FACILITIES
		==================

.I LIST
.I NOLIST
		By using the word LIST and NOLIST around sections of program
	will cause the actual Macro generated code to be output to the list-
	ing file. Consider it as a Switch.

.I TRACING FACILITIES
		TRACING FACILITIES
		==================
.I TRACE
.I NOTRACE
		By using the terms TRACE and NOTRACE around program modules
	at run time the label will be printed on the VDU every time that  -
	LABEL is passed. In the case of a Decision Table then the LABEL name
	will be given when the first action is reached and the rules true at
	that time will be printed.


.C STRING HANDLING MACROS.
.T INTRODUCTION.

STRING HANDLING MACROS.
=======================
     
	The  following  macros  allow for easy manipulation of strings
and the  following  notes  should  be  born in mind. To make parameter 
passing easy from one macro to another a number of locations have been 
defined. Macro parameters are loaded into these locations and if a par
-ameter is a location it can be defaulted by the use of a '-'. In  add
-ition  the  results  of any macro action will also be loaded in these
locations  and  the 'C' bit appropriatly set. Thus the programmer does 
not have to bother about registers as all register values are retained 
when these MACROS are used.
	The  parameter passing locations may be accessed seperatly and 
those loaded or used are given for each macro. All locations use 'CD.'
(COMMON DICTIONARY) for  the  first  three characters.  All parameters 
must be defined or on error will result.
 

.I COMMON DICTIONARY
.I CD.
.I CD.SRC
.I CD.DST
.I CD.CHR
.I CD.CNT
.I CD.RES
.I CD.POS
.I CD.KEY    
.I LABEL parameter
.I SOURCE parameter
.I DESTINATION parameter
.I CHARACTER parameter
.I COUNT parameter
.I POSITION parameter

    LABEL parameter 	   _	string label or register holding a 
				string address.
				(CD.SRC/CD.DST)

    SOURCE parameter 	   _	a source string defined the same as
				label.
				(CD.SRC)

    DESTINATION parameter  _ 	a destination string defined the
				same as label.
				(CD.DST)

    CHARACTER parameter    _	number, register or label defining
				an ascii character.
				(CD.CHR)

    COUNT parameter        _	a number, register or label holding
				a numeric count
				(CD.CNT)

    POSITION parameter     _	a number, register or label holding
				a number giving a character position
				within a string.(or table KEY).
				(CD.POS/CD.KEY)

	In order to obtain a parameter from the Common Dictionory a
dash (-) must be used for that parameter. No parameter must be left 
undefined or an error will result.

.T STRING MACROS

ZPAD.  label,count
----
.I ZPAD [label]

	This macro fills up the remainder of a string with nulls, or
appends the number of spaces specified in 'COUNT'. It does not clear 
the string first.

	Parameter locations:-
	-------------------

	CD.SRC   holds the string address.
	CD.CHR   := #0
	CD.CNT   := characters inserted or "#0" for whole string.
						success/error

SPPAD  label,count
-----
.I SPPAD [label]

	This macro fills up the remainder of a string with spaces, or
appends the number of spaces specified in 'COUNT'.  It does not clear 
the string first.

        Parameter Locations:-
	-------------------

	CD.SRC    holds the string address.
	CD.CHR    := #40 (space)
	CD.CNT    := characters inserted or "#0" for whole string.
						success/error 


PAD     label,character,count
--- 
.I PAD [lab],[char],[cnt]

	This macro pads out a string with the number of specified 
characters,  or  appends  the  number  of characters specified as 
defined in count. It does not clear the string first.


        Parameter locations:-
	-------------------

	CD.SRC    holds the string address.
	CD.CHR    holds the ascii character value.
	CD.CNT    holds the number of characters to pad with.

						success/error
.F
ADDSTRING  source, destination
---------
.I ADDSTRING [src],[dest]

         This macro appends the source string to the destination 
string or as much as there is room for, the source string remains 
unaltered.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the source string address.
	CD.DST    holds the destination string address.

						success/error

CLRSTRING  label
---------
.I CLRSTRING [label]

	This macro fills the string with nulls and clears the string
 count.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the string address
						success/error
MOVSTRING.    source, destination.
----------
.I MOVSTRING [src],[dest]

	This macro is a combination of the CLRSTRING and ADDSTRING,
macrosIt clears the destination string and moves the source string to 
the destination string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the source string address.
	CD.DST    holds the destination string address.

						success/error

.F
CMPSTRING   source, destination
---------
.I CMPSTRING [src],[dest]

	This macro compares  two strings exact and the status bits are 
set dependant on the result.

NOTE:- If the strings are of different lengths then the characters are 
compared over the length of the shortest string. If all characters are 
the same the shortest string is considered smaller.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the source string address.
	CD.DST    holds the destination string address.


	Result Locations:-
	----------------

	CD.RES    holds the result
 
 	If CD.RES  = 0 (success)	- both strings identical

		   = positive (error)	- source string largest

		   = negative (error)	- destination string largest


	Alternative result testing (SUPERMAC) :-
	-------------------------------------

	IF RESULT IS SUCCESS	(both strings identical)
 
	IF RESULT IS ERROR	(strings are not the same)

	IF RESULT IS GT     (source string largest)

	IF RESULT IS LT     (destination string is largest)

	IF RESULT IS EQ	    (strings not identical - but the length
			    is the same)

						success/error


.F
ROLSTRING   label
---------
.I ROLSTRING [src]

	This macro shifts a string one place to the left (ROLL LEFT).
	The last character in the string is moved to the start of the 
	string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.
 
 						success/error

RORSTRING   label
---------
.I RORSTRING [src]

	This macro shifts a string one place to the right (ROLL RIGHT)
The first character in the string is moved to the end of string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

 						success/error

SHLSTRING   label
---------
.I SHLSTRING [src]

	This macro shifts a string one place to the left, removing the 
first character. 

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	Result Locations:-
	----------------

	CD.CHR    holds the first character removed

 						success/error
.F
SHRSTRING   label,character 
---------
.I SHRSTRING [src],[char]

         This macro shifts a string one place to the left, putting the 
defined character in the vacated first character slot.

	Parameter Locations:-
	-------------------

	CD.SRC   holds the label string address.

	CD.CHR   holds the ascii character.

 						success/error

SUBSTRING   source, destination 
---------
.I SUBSTRING [src],[dest]

	This macro locates the source string within the destination 
string and if there it subtracts it from the destination string. 
The source string remains untouched.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the source string address.

	CD.DST    holds the destination string address.

	Result Locations:-
	----------------

	CD.POS    holds the position in destination string where the 
		  source was found

	CD.CNT    holds the number of characters deleted.

						success/error.

.F
SWABSTRING  label
----------
.I SWABSTRING [src]

	This macro swaps or reverses all the characters held in a 
	string.

	Parameter Locations:-
	-------------------

	CD.SRC   holds the label string address.

						success/error.

TSTSTRING  label
---------
.I TSTSTRING [src]

	This macro allows a string lenght to be acted upon by 
appropriatly setting the status word condition codes.

	Parameter Locations:-
	-------------------

	CD.SRC   holds the label string address.

	Result Locations:-
	----------------

	CD.RES   holds the string lenght.


.T CHARACTER / STRING MACROS

THE FOLLOWING MACROS DEAL WITH CHARACTERS WITHIN STRINGS.
=========================================================


ADDCHRSTRG   character, label
----------
.I ADDCHRSTRG [char],[src]

	This macro adds or appends a character to a string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	CD.CHAR   holds the character to be added.
           

INSCHRSTRG   character, position, label
----------
.I INSCHRSTRG [char],[pos],[src]

	This macro inserts a character within a string at a given 
position (insert after).

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	CD.CHR    holds the character to be inserted.

	CD.POS    holds the position to be inserted after.

						success/error.

MODCHRSTRG   character, postiion, label
----------
.I MODCHRSTRG [char],[pos],[src]

	This macro modifies a character within a string at a given 
	position.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	CD.CHR    holds the character which is modifying.

	CD.POS    holds the position of character to be modified.


						success/error.

.F
DELCHRSTRG   position, label
----------
.I DELCHRSTRG [pos],[src]

	This macro deletes or removes a character from a given 
position within a string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	CD.POS    holds the position where character is or has been
deleted.

						success/error.

POPCHRSTRG   label
----------
.I POPCHRSTRG [src]

	This macro removes the first character from a string and 
leaves it in CD.CHR.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	Results Locations:-
	-----------------

            CD.CHR    holds the first character removed.

						success/error.

PUSHCHRSTRG   character, label
-----------
.I PUSHCHRSTRG [char],[src]
	This macro inserts a character ( byte ) at the begining of a 
string.

	Parameter Locations:-
	-------------------

	CD.SRC    holds the label string address.

	CD.CHR    holds the character to be inserted.

	Result Locations:-
	----------------

	CD.POS    becomes equal to #0


.C General purpose macros
.T Print macros
 
		MACROS TO BE FOUND IN MAC/LIB
		-----------------------------

	Note parameters in [square brackets] are optional.



MODULE	NAME				DESCRIPTION
------	----				-----------
 
.I MX08
.I PRINT
MX08	PRINT [label],[character string]
				Output a character string to the terminal
				If the character string is not specified
				the string for output is assumed to be
				pointed at by R0.
	eg.	PRINT ,<"DEMO TEXT">	;PRINT TEXT
		PRINT XX,<"DEMO 1">	;PRINT TEXT, LAB XX: APPENDED TO TEXT
		PRINT XX		;PRINT TEXT AT LABEL XX

.I PRINTA
MX08	PRINTA	[label/location],[BYTE]
				This macro outputs either the contents
				of R0 (by default) or contents of label
				to the terminal in ASCII representation.
				All bytes/characters decsribed by two
				ASCII characters to cover non-printing
				characters NB. 1 would be displayed as
				^A and the erase character as ^% all
				printing characters preceded by a space.
	eg.	PRINTA XX	;CONTENTS OF XX DISPLAYED AS 4 CHARACTERS


.I PRINTC
MX08	PRINTC [character],[BYTE]
				Output a character to the terminal. If
				the character is not specified the
				character for output is assumed to be
				held in R0.
	eg.	PRINTC #65.	;PRINT THE CHARACTER "A"
	eg.	PRINTC @#ODDADDRESS,BYTE
.F



NAME		MODULE			DESCRIPTION
----		------			-----------


.I PRINTB
.I MX08
MX08	PRINTB	[label/location],[BYTE]
				This macro outputs either the contents of
				R0 (by default) or the contents of the
				lable to the terminal in BASE 2 ASCII
				converted form.
	eg.	PRINTB #-1	;output = 1111111111111111
	eg.	PRINTB #-1,BYTE	;output = 00000000

.I PRINTD
MX08	PRINTD	[label/location],[BYTE]
				This macro outputs either the contents of
				R0 (by default) or the contents of the 
				label to the terminal in DECIMAL form.
	eg.	PRINTD #65.	;PRINTS THE VALUE IN FORM +00065
	eg.	PRINTD @R0,BYTE	;R0 POINTS TO AN ODD ADDRESS

.I PRINTH
MX08	PRINTH	[label/location],[BYTE]
				This macro outputs either the contents of
				R0 (by default) or the contents of the
				lable to the terminal in BASE 16 ASCII
				converted form.
	eg.	PRINTH #-1	;output = FFFF
	eg.	PRINTH #-1,BYTE	;output = FF

.I PRINTO
MX08	PRINTO	[label/location],[BYTE]
				This macro outputs either the contents of
				R0 (by default) or the contents of the
				label to the terminal in OCTAL form.
	eg.	PRINTO #101	;PRINTS THE VALUE IN THE FORM 000101
	eg.	PRINTO (R2)+,BYTE

.I PRINTR
MX08	PRINTR	[label/location]
				This macro outputs either the contents of
				R0 (by default) or the contents of the
				label to the terminal in RADIX 50 form.
	eg.	PRINTR #^RABC	;PRINTS THE VALUE IN THE FORM CCC

.I REPCHAR
.I V$TXC
MX08	REPCHAR character,repeat count
				This macro set up the data in the form
				suitable to be processed by the procedure
				V$TXC.
	eg.	REPCHAR <SPACE>,33	;OUTPUT 33 SPACE CHARACTERS

.I PTEXT
.I V$TXB

MX08	PTEXT string
				This macro set up the string in the form
				suitable to be processed by the procedure
				V$TXB.
	.eg	PTEXT <<CR><LF>"HAVE A NICE day">;SEND TEXT TO TERMINAL


 
 
.T Input / read macros

MODULE	NAME				DESCRIPTION
------	----				-----------
 
.I MX10
.I INPUT
MX10	INPUT [string]
				Read a character string from the terminal
				the address of the characters string is
				placed in R0 by default or the named string.
	eg.	INPUT A$	;READ CHARS FROM TERMINAL AND PUT IN STRING A$

.I INPUTNE
MX10	INPUTNE [string]
				Read a character string from the terminal
				with the no echo option. The address of the
				character string is placed in R0 by default
				or the character are copied into the string.
	.eg	INPUTNE A$	;AS INPUT BUT CHARS NOT ECHOED ON TERMINAL

.T Initialisation and Terminaltion macros


MODULE	NAME				DESCRIPTION
------	----				-----------

.I INITIALISE
.I MX07
MX07	INITIALISE [Lun number],[VDU event flag number]
				This must be the first macro to be used
				it initialises the terminal input output
				software. If file handling software is being
				used the default lun (one) can be set to any
				value, likewise the vdu event flag default
				(one) can also be altered.

.I TERMINATE
MX07	TERMINATE [status reply]
				This should be the last instruction in
				the program it closes down the terminal
				channel in an orderly manner.
				The valid status replys are :-
				SUC	indicating success
				WAR	indicating a warning
				ERR	indicating an error has occured
				SEV	indicating a severe error has occured
	eg.	TERMINATE SUC	;INDICATE JOB SUCSESSFUL


.T General utility macros

MODULE	NAME				DESCRIPTION
------	----				-----------
 
.I MX04
.I SAVE
MX04	SAVE [list of registers locations]
				This macro in the default mode saves
				the following registers on the stack
				R0,R1,R2,R3,R4 and R5. (R$SAVE)
				Otherwise the named registers will be
				saved on the stack.
	eg.	SAVE R0,R3,R5	;SAVE REGISTERS ON STACK

.I UNSAVE
MX04	UNSAVE [list of registers/locations]
				This macro performs the reverse operation
				of the macro SAVE ie. if no register/locations
				specified then registers R0,R1,R2,R3,R4
				and R5 (R$UNSAVE) will be restored.
				Otherwise the named registers/locations
				will be restored from the stack.
				Note the order for the parameters of 
				The macros SAVE and UNSAVE must be the same.
	eg.	UNSAVE R0,R3,R5	;RESTORE REGISTERS IN ORDER R5,R3,R0

.I STRING
.I MX01
.I FIRST
.I CONT
.I LAST
MX01	STRING Text,Label[,Control]
				This macro reserves a text string associated
				with the label and with write access denied.
				It has been found that sometimes a string
				is required that exceded that that can easily
				be typed onto a single line therfore a
				continuation option is allowed using the
				control parameter. The following control
				words are allowed FIRST indicating the start
				of the string, CONT indicating a continuation
				of the string but not the last segment and
				LAST used to terminate the string.
				Note that the Location/Register field may
				be ignored when using CONTROL = CONT or
				CONTROL = LAST.

	eg.	STRING <"LOAD THESE CHARACTERS INTO STRING A$">,A$
	eg.	STRING <"First line">,B$,FIRST
		STRING <"continuation line">,,CONT
		STRING <"further continuation">,,CONT
		STRING <"at last the end">,,LAST

.I RESERVE
MX01	RESERVE Size,Label
				This macro reserves a blank string associated
				with the label set with read/write access
				and limited to maximum number of characters
				size.
	eg.	RESERVE 100.,A$	;SAVE SPACE FOR STRING A$ 100 CHARS LONG

.F

MODULE	NAME				DESCRIPTION
------	----				-----------
 
.I MOVTEXT
.I FIRST
.I CONT
.I LAST
MX01	MOVTEXT String,Location/Register[,Control]
				This macro enable the programmer to assign
				a character string to a register or load
				the string address into a location.
				The [,Control] option allows you to create
				strings that would normally exceede the
				length of a 80 column line and so distort
				the MACRO 11 compiler listings.
				The [,Control] may be one of three words
				allowed FIRST indicating the start
				of the string, CONT indicating a continuation
				of the string but not the last segment and
				LAST used to terminate the string.
				Note that the Location/Register field may
				be ignored when using CONTROL = CONT or
				CONTROL = LAST.
 
	eg.	MOVTEXT <"Have a nice day">,R0
	eg.	MOVTEXT <"First line"<CR><LF>>,R2,FIRST
		MOVTEXT <"continuation line   "<10.><13.>>,,CONT
		MOVTEXT <"further continuation"<12><15>>,,CONT
		MOVTEXT <"at last the end">,,LAST
 
 
.I QUEBUF
MX01	QUEBUF	size,label
				This macro reserves a data area in queue
				buffer format with the label associated
				with the data area.
 
	eg.	QUEBUF	100.,A.	;SAVE SPACE FOR QUEUE CALLED A. 100 CHARS LONG
 
 
.F


NAME		MODULE			DESCRIPTION
----		------			-----------


.I MX01
.I PRESET
MX01	PRESET	Size,label[,aa][,bb][,cc]
				This macro reserves a preset string.
				Note the parameter size may be overwritten
				by the effect of parameters [aa],[bb],[cc].
				The parameter label is the label by which
				the character string is to be accessed.

					Three parameters specified
					--------------------------
				The parameter [aa] is the string to
				be loaded into the preset area.

					Four parameters specified
					-------------------------
				The parameter [aa] is the string to
				be loaded into the preset area and
				parameter [bb] is the number of repeats
				of string [aa] required.

					Five parameters specified
					-------------------------
				The parameter [aa] is now a value NOT
				A STRING , parameter [bb] is the repeat
				count and parameter [cc] is a step value
				on the entry value [aa].



.T Utility Terminal format  presentation macros


MODULE	NAME				DESCRIPTION
------	----				------------
 
.I MX09
.I NEWLINE
MX09	NEWLINE  [Number of newlines]
				This macro causes a newline to be displayed
				on the terminal.

.I SPACES
MX09	SPACES   [Number of spaces]
				This macro causes a number of spaces to
				be displayed on the terminal.

.I DUMP
.I MX11
MX11	DUMP Comment,value	
				This macro prints out a newline followed by
				the specified comment and the value entry
				printed both in decimal and octal.

.I DEBUG
MX11	DEBUG	Comment,[errlab],[level]
				This macro in not yet available.
.T MX12 modules


	COMMON INFORMATION for MX12 modules.
	------------------------------------

	The parameter SIZE indicates the number of bytes to be processed
	and may be any one of the following values 1,2,4,6
	The parameter FORMAT may be any one of the following symbols
	RAD for radix 50 display, ASC for ascii representation
	DEC for decimal display or OCT for an OCTAL display.
	All these MACRO's may require the use of the register R4.

.I MX12
.I DMPOFF
MX12	DMPOFF	OFFSET,SIZE,[FORMAT]
				This macro displays the OFFSET and the
				contents of the location pointed at by
				(R4 + the OFFSET) to the display in the
				format specified. The default format is OCTAL.

.I DMPSYM
MX12	DMPSYM	SYMBOL,SIZE,[FORMAT]
				This macro displays the SYMBOL and the
				contents of the symbol in the format
				specified. The default format is OCTAL.
				The parameter SIZE is limited to 1,2 only.

.I DMPBIT
MX12	DMPBIT	FLAG,[mask]
				This macro displays the FLAG and the logical
				state of the flag. The mask option allow a
				controlled area to be checked.
				The flag bits are required to be held in
				register R4.
				Usage	MOV @DATA,R4
					DMPBIT TF.RNE
					DMPBIT TF.TMO
.T Status control macros

MODULE	NAME				DESCRIPTION
------	----				-----------

.I SETERROR
.I MX06
MX06	SETERROR [branch label]
				This macro set the C bit indicating an
				error condition. If branch label is
				specified a branch will take place
				to the specified label.

.I SET SUCCESS
.I C BIT
MX06	SETSUCCESS [branch label]
				This macro clears the C bit indicating
				a successful operation. If branch label
				is specified a branch will take place
				to the specified label.

.I EXIT
.I EXITERROR
MX06	EXITERROR
				This macro sets the C bit and then
				returns to the calling routine via RTS PC.

.I EXITSUCCESS
MX06	EXITSUCCESS
				This macro clears the C bit and then
				returns to the calling routine via RTS PC.

.I IFERROR
.I RETURN
MX06	IFERROR label
				This macro tests the C bit and if it is
				set a branch to label takes place.
				The symbol label may be replaced by the word
				RETURN if RTS required on error condition.

.I IFSSUCCESS
MX06	IFSUCCESS label
				This macro tests the C bit and if it is
				clear a branch to label takes place.
				The symbol label may be replaced by the
				word RETURN if RTS required if successfull
				operation.
.I EXIT T/F/S/E
 
	NOTE:-		EXIT T		[EXITSUCCESS]
			EXIT F		[EXITERROR]
			EXIT S		[EXITSUCCESS]
			EXIT E		[EXITERROR]

.C Module Reference Tables.
.T MACRO modules

MODULE		contents		MODULE		contents
------		--------		------		--------

MG0	common macros only		MG01	R$ADDRESS
MG02	V$IO				MG03	V$INPUT
MG04	V$TX				MG05	R$SWAP
MG06	R$BITSET			MG07	R$BITPOS
MG08	V$ON	V$OFF			MG09	V$TXA
MG10	V$TXB				MG11	V$TXC
MG12	V$TXD				MG13	R$PARITY

MGD1	VDU common data areas		MGD2	VDU fixed data areas


MR01	R$BDEC				MR02	R$BOCT
MR03	R$BINB	R$DECB	R$HEXB	R$OCTB
	R$STRB				MR04	R$DELETE
MR05	R$POS3	R$POS2	R$POS		MR06	R$WEDGE
MR07	R$REVERSE			MR08	R$SHRE
MR09	R$SHLE				MR10	R$SHR	R$SHL
MR11	R$COMPARE			MR12	R$ADDTO
MR13	R$CLEAR				MR14	R$SEG
MR15	R$BR50				MR16
MR17	R$R50L				MR18	R$BASC
MR19	R$UIC				MR20	R$CLK	R$DAT
MR21	R$NTDY				MR22
MR23	R$QADD				MR24	R$QREM
MR25	R$QTST				MR26	R$BHEX
MR27	R$BBIN				MR28

MRC01	R$GETC				MRC02	R$MODC
MRC03	R$ADDC				MRC04	R$INSC
MRC05	R$DELC				MRC06	R$POSC	R$POSS
MRC07	R$MOVC				MRC08	R$CR50	R$R50C
MRC09	R$CMPC				MRC10	R$LCUC
MRC11	R$UCLC				MRC12
MRC13					MRC14
MRC15					MRC16


.F




MODULE		contents		MODULE		contents
------		--------		------		--------


MN01	N$DIAG				MN02	N$DUMP
MN03	N$INIT				MN04	N$SEEK
MN05	N$FIRST	N$LAST	N$PRESENT
MN05	N$SETUP				MN06	N$DELETE
MN07	N$NEXT				MN08	N$PROTECT	N$UNPROTECT
MN09	N$CREATE			MN10	N$SQUEEZE
MN11					MN12
MN13					MN14
 
 
MT01	T$DIAG				MN02	T$DUMP
MT03	T$INIT				MT04	T$SEEK
MT05	T$FIRST	T$LAST	T$PRESENT	
MT05	T$SETUP				MT06	T$DELETE  T$DKEY
MT07	T$NEXT	T$PREVIOUS		MT08	T$PROTECT T$UNPROTECT
MT09	T$CREATE T$SCHK	T$IKEY		MT10	T$SORT	  T$SQUEEZE


MF01	F$NAME				MF02	F$GETR
MF03	F$SHUT				MF04	F$PUTR
MF05	F$OPEN				MF06	F$SETUP
MF07	F$DIAG				MF08	F$SWITCH

MFD1	FCS COMMON DATA AREAS

MX01	STRING	PRESET	RESERVE
	MOVTEXT	QUEBUF			MX02	MESSAGE	MFUNCTION REPORT
MX03	NODEBLOCK	TABLEBLOCK	MX04	SAVE	UNSAVE
MX05	FLODEF	BITDEF	FNAMDEF	FILEFUN	MX06	SETERROR	SETSUCCESS
						EXITERROR	EXITSUCCESS
						IFERROR		IFSUCCESS
MX07	INITIALISE	TERMINATE	MX08	REPCHAR	PTEXT	PRINT
						PRINTA	PRINTC	PRINTD
						PRINTO	PRINTR
MX09	NEWLINE	SPACES			MX10	INPUT	INPUTNE
MX11	DUMP	DEBUG			MX12	DMPOFF	DMPSYM	DMPBIT
MX13	TABMAC (ALL)			MX14	SUPERMAC MACROS (ALL)
MX15	TABLE ACCESS MACROS		MX16	STRING MACROS AND GENMAC
MX17	SERIAL I/O MACRO		MX18	RT-11 MACROS (ALL)

.F


MODULE		contents		MODULE		contents
------		--------		------		--------

MMC01	M$CHECK


MCC01	C$DECINT


MC01	LEN				MC02	COMPARE
MC03	SEG
MC03A	LSEG				MC04	COPY
MC05	POS	LPOS			MC06
MC07	VDU				MC08
MC09					MC10	VAL
MC11					MC12
MC13					MC14
MC15					MC16	ADDTO
MC17					MC18
MC19					MC20
MC21	CLEAR

MMTD1	MAGTAPE COMMON DATA AREAS

MMT01	MT$EXIT				MMT02	MT$GET
MMT03	MT$SHUT				MMT04	MT$PUT
MMT05	MT$OPEN				MMT06	MT$FIND
MMT07	MT$BACK				MMT08	MT$REWIND
MMT09	MT$MARK				MMT10



.T CORAL Procedures called by section. 

REF		NAME		PROCEDURES CALLED
L01		LEN
L02		COMPARE		L01
L03		SEG		L01
L03A		LSEG		L01
L04		COPY		L01
L05		POS		L01	L02
L05A		LPOS		L01 	L02
L06		ADD		L01	L04
L07		VDU		L03A	L05A	L07A	L10	QIO	WAITEF
L07A		VDUOUT		L05A	L7B	L7G
L07B		VDUTX		L07G	Q10	WAITEF
L07C		RTO4		L03A	L05A	L07E	L10	QIO	WAITEF
				DEFLUN RELEASE
L07D		VDUSP		L03A	L05A	L07A	L07G	L10	QIO
				QIOAST	WAITEF	[VDUAST]
L07E		RTOUT		L05A	L07B
L07G		VDULUN		L07L	DEFLUN	RELEASE
		VDUFLG
L07L		LUNTEST
		LUNBOOK
		LUNFREE
L07S		SYS		QIO	VDUFLG	VDULUN	WAITEF
L08		STR		FCHAR	AINT
L09		ASC
L10		VAL		L01
L11		FILEIN		READREC
L11A		LFILEIN		READREC
L12		FILEOUT		L01	WRITEREC
L13		CHR
L14		QUOTE
L15		FILE		L01	L03A	L04	L05A	L07	L08
				L10	L16
				DEFLUN	CREATE	DELETE	OPEN	CLOSE	RELEASE
L16		ADD TO		L01
L17		A SPACE
L18		A TAB
L19		FILL		L01	L03A	L16
L20		CRLF
L21		CLEAR
L22		DAT		L04	L08	L16	L17	GETTIM
L23		CLK		L04	L08	L16	L17	GETTIM
L24		TABLOAD		L01
L25		RADASC
L26		ASCRAD
L27		TERMINAL	L05A
L28		COMSORT		L01
L29		CHARVER		L01
L30		MULS		L16
L31		CVT		L01	L03A	L04	L05A	L06	L10	L13
				L16	L21	L29	L30	L32	AINT
L32		SRP		L01	L03A	L05A	L16	L21
L33		CYPHER		L01	L03A	L04	L05A	L16	L21
.T CORAL procedures used by section
 
REF		NAME			USED BY PROCEDURE
L01		LEN		L02	L03	L03A	L04	L05	L05A	L06
				L10	L12	L16	L19	L24	L28	L29
				L31	L32	L33
L02		COMPARE		L05
L03		SEG
L03A		LSEG		L07	L07D	L19	L31	L32	L33
L04		COPY		L06	L15	L22	L23	L31	L33
L05		POS
L05A		LPOS		L07	L07A	L07D	L15	L27	L31
				L32	L33
L06		ADD		L31
L07		VDU		L15
L07A		VDUOUT		L07	L07D
L07B		VDUTX		L07A	L07E
L07C		RTO4
L07D		VDUSP
L07E		RTOUT		L07C
L07G		VDUFLG		L07A	L07B	L07D
		VDULUN
L07L		LUNBOOK		L07G
		LUNFREE
		LUNTEST
L07S		SYS
L08		STR		L15	L22	L23
L09		ASC
L10		VAL		L07	L07D	L31
L11		FILEIN
L12		FILEOUT
L13		CHR
L14		QUOTE
L15		FILE
L16		ADD TO		L15	L19	L22	L23	L30	L31
				L32	L33
L17		A SPACE		L22	L23
L18		A TAB
L19		FILL
L20		CRLF
L21		CLEAR		L31	L32	L33
L22		DAT
L23		CLK
L24		TAB LOAD
L25		RADASC
L26		ASCRAD
L27		TERMINAL
L28		COMSORT
L29		CHARVER		L31
L30		MULS		L31
L31		CVT
L32		SRP		L31
L33		CYPHER
 
 
	NOTE:-  STRING DATA AREA PROCEDURES USED BY USERS PROGRAMS ONLY.
.T MACRO symbol reference tables
 
MODULE	<-------GLOBAL------->	<---------------CALLED/USED----------------->
NAME	SYMBOL	SYMBOL	SYMBOL			  SYMBOLS

MGD1	R$ADDRESS
MGD2	V$IO			R$POS2	V$S20	V$00	V$09	V$08
				V$TX	V$LST	V$S16	V$STR	V$FUN
				V$S12	V$S13	V$CNT	V$S14	V$S15
				R$POS3	C$DECINT V$S17 V$LUN	V$EFN
				V$ISB	V$S18	V$01
MG03	V$INPUT			V$FUN	V$ON	V$LUN	V$EFN
				V$ISB	V$STR	V$CNT	V$TX
MG04	V$TX			R$ADDRESS	V$ON	V$LUN	V$EFN
MG05	R$SWAP
MG06	R$BITSET
MG07	R$BITPOS
MG08	V$ON	V$OFF		V$STA	V$LUN
MG09	V$TXA			V$TX
MG10	V$TXB			V$TX
MG11	V$TXC			V$TX
MG12	V$TXD			V$TX
MG13	R$PARITY
MGD1	V$STA	V$LUN	V$EFN		
	V$CNT	V$FUN	V$ISB
	V$STR
MGD2	V$LST	V$00	V$01 
	V$02	V$03
	V$04	V$05	V$06
	V$07	V$08	V$09
	V$S01	V$S02	V$S03
	V$S04	V$S05	V$S06
	V$S07	V$S08	V$S09
	V$S10	V$S11	V$S12
	V$S13	V$S14	V$S15
	V$S16	V$S17	V$S18
	V$S19	V$S20
MF01	F$NAME			F$DFNB	R$POSS	F$MAXC	F$FLG1	R$RSOL	F$FLG0
				F$FLGO	R$CR50
MF02	F$GETR			F$FDB	.GET
MF03	F$SHUT			F$FDB	.CLOSE
MF04	F$PUTR			F$FDB	.PUT
MF05	F$OPEN			F$FDB	.OPEN
MF06	F$SETUP			F$FDB	F$LUN	F$TYPE	F$SIZE

.F
 
MODULE	<-------GLOBAL------->	<---------------CALLED/USED----------------->
NAME	SYMBOL	SYMBOL	SYMBOL			  SYMBOLS

MMTD1	MT$UNIT	MT$LUN	MT$EFN
	MT$DSW	MT$ERR	MT$ISB

MMT1	MT$EXIT			$DSW	MT$DSW	MT$ISB
MMT2	MT$GET			QIOW$S	IO.RLB	MT$LUN	MT$EFN	MT$ISB	MT$EXIT
MMT3	MT$SHUT			ALUN$S	$DSW	MT$DSW
MMT4	MT$PUT			QIOW$S	IO.WLB	MT$LUN	MT$EFN	MT$ISB	MT$EXIT
MMT5	MT$OPEN			ALUN$S	MT$LUN	MT$UNIT	$DSW	MT$DSW
MMT6	MT$FIND			QIOW$S	IO.SPF	MT$LUN	MT$EFN	MT$ISB	MT$EXIT
MMT7	MT$BACK			QIOW$S	IO.SPB	MT$LUN	MT$EFN	MT$ISB	MT$EXIT
MMT8	MT$REWIND		QIOW$S	IO.RWD	MT$LUN	MT$EFN	MT$ISB	MT$EXIT
MMT9	MT$MARK			QIOW$S	IO.EOF	MT$LUN	MT$EFN	MT$ISB	MT$EXIT

.F
MODULE	<-------GLOBAL------->	<---------------CALLED/USED------------------>
NAME	SYMBOL	SYMBOL	SYMBOL			  SYMBOLS

MFD1	F$SIZE	F$TYPE	F$FLG0
	F$FLG1	F$MAXC	F$LUN
	F$USED	F$FDB	F$DFNB
	F$FDBS
MR01	R$BDEC			R$REVERSE
MR02	R$BOCT			R$REVERSE
MR03	R$OCTB	R$DECN	R$STRB	R$HEXB	R$BINB
MR04	R$DELETE
MR05	R$POS3	R$POS2	R$POS
MR06	R$WEDGE
MR07	R$REVERSE
MR08	R$SHRE
MR09	R$SHLE
MR10	R$SHR	R$SHL		R$SHRE	R$GETC	R$ADDC	R$MODC
MR11	R$COMPARE
MR12	R$ADDTO
MR13	R$CLEAR
MR14	R$SEG			R$GETC	R$ADDC
MR15	R$BR50			R$R50C
MR16
MR17	R$R50L			R$CR50
MR18	R$BASC
MR19	R$UIC			R$BOCT
MR20	R$DAT	R$CLK		R$BDEC
MR21	R$NTDY			R$DELC	R$SHL
MR22
MR23	R$QADD
MR24	R$QREM
MR25	R$QTST
MR26	R$BHEX			R$REVERSE
MR27	R$BBIN			R$REVERSE

MRC01	R$GETC
MRC02	R$MODC
MRC03	R$ADDC
MRC04	R$INSC
MRC05	R$DELC
MRC06	R$POSC	R$POSS
MRC07	R$MOVC
MRC08	R$CR50	R$R50C		R$POSC	R$GETC
MRC09	R$CMPC		 	R$LCUC
MRC10	R$LCUC
MRC11	R$UCLC
 
MCC1	C$DECINT
 
MC01	LEN			R$ADDRESS
MC02	COMPARE			R$ADDRESS 	R$COMPARE
MC03	SEG			R$ADDRESS
MC03A	LSEG			R$ADDRESS
MC04	COPY			R$ADDRESS	R$ADDTO
MC05	POS	LPOS		R$ADDRESS	R$POS3
MC07	VDU			R$ADDRESS	V$IO
MC10	VAL			R$ADDRESS	R$POS2	R$POS3	R$DECINT
MC16	ADDTO			R$ADDRESS	R$ADDTO
MC21	CLEAR			R$ADDRESS	R$CLEAR

.C Utility program	XY Plotter emulator.
.T Introduction

	This program emulates the following X Y PLOTTER procedures :-

	TXT	MOV	PLT	CIR	RED	BLK	ARC	ARR
	SQR	PLS	CRS	SIZE	NEWFRM

	The procedure parameters are passed in the following form :-
	Procedurename<delimiter>parameter<delimiter>.....

	The valid delimiters are a space, a comma, a semi-colen or
	a oblique stroke. (Note multiple delimiters are assumed to be
	a single delimiter)

	To use the emulator first construct a text file of the
	commands required. After the emulator has been run a file
	call PLOTXY.TMP will have been created which then can be
	submitted to the XY PLOTTER.


.C Utility program	Indexer program.
.T Introduction


	This program has been produced to enable a user to
produce a cross-referenced indexed manual with minimal effort.
This program will allow the user to control the position of
form feeds, to include a Volume title, Chapter titles and Topic
titles within each chapter, all these items are build into
precedding indexes heading the data they refer too. It is also
posible with this program to produce a Global index to item refered
to throughout the volume being produced, this index is sorted and
appended to the end of the volume with reference page numbers for
easy access. This program will start each page with a header
containing the page number and a tile. All line will be truncted
to 75 characters any remaining text will spill onto the next line.
This program uses the SORT-11 sort package.


.T Data structures

	All commands for the indexer program are preceded by a
single full stop followed by a control function character.
NOTE the full stop must be the very first character on the line.
ie. .T would produce an entry in the topic index.
	The commands that are allowed are :-
	.V <volume title>		This is normally the first
					entry in the data file
	.C <chapter title>		This enters the chapter title
					into volume index and starts a
					new chapter index and contents
					file
	.T <topic title>		The enters the title into the
					chapter index and forces a new
					page header.
	.I <global index item>		This enters the item into the
					global index file. NOTE no more
					than 40000 items are allowed in
					the Global index.
					NOTE index items truncated to 31
					characters
	.F				This command causes a new page
					header to be produced.
	.B				This command causes a page number
					to be reserved for future
					insertions so as not to effect
					the overall page numbering.
	.! <comment>			This command allows comments to
					inserted in the text be not output
					on the main file.

.C Utility program	Simple Upper/Lower case EDITOR
.T Commands

 
	When using the character editor a special option has been fitted
	into this program so as to allow you to monitor the possible
	commands allowed, when the message COMMAND > appears on the screen
	you may type the character Z. This character is not used as an
	editor command therfore the diognostic section will give you a
	summary of all the posible commands.
	The following character are the only ones that will perform a
	legal editing action :-
		A B C D E F H I L M N P R S T U
	All commands must be terminated by either a space or by pressing
	the return key.
	
	COMMAND				ACTION
	  A	    Append a series of characters to the end of the present
		    line. The (append) series of characters is terminated by
		    pressing the return key.
	  B	    Move the line pointer to the bottom of the text
		    being edited. This would be used when quick access
		    to the end of the edited text is required.
	  C	    This option would be selected when a mistake or
		    correction is required in a piece of text.
		    You may correct one or any number of characters on
		    the present line. If you wish to delete a character
		    or number of characters on the line, you would select
		    the characters for deletion and change then to
		    a void input.
		    Void input is an input containing no characters created
		    by pressing return key alone.
	  D	    Delete the present line of text and move the line
		    pointer to the next line and print that line.
	  E	    Exit from editor program ie used when you have finished
		    your editing job.
	  F	    One of the limitations of this editor is that you
		    cannot go back a line therfore the FRONT command
		    has been introduced to allow you to insert a line 
		    a line of text in front of the present line.
		    Note this action does not disturb the present line.
	  H	    This command is used in conjunction with the M command
		    by inserting all information held in the move file
		    below the present line. Note H stands for insert HERE.
	  I	    This command allows you to insert a new line of text
		    below the present line.

.F

	COMMAND				ACTION
	  L	    This command allows you to locate a character or
		    group of characters in any line following the present
		    line.
		    If the location is succesful then the line the
		    characters have been found on becomes the present line.
	  M	    This option allows you to move lines of text to
		    other locations within your file being edited.
		    Note the move file may contain any number of lines
		    and they are held in the order they are entered.
		    Please note that the H command does not remove one
		    line at a time but all lines that have been put in
		    the move file.
	  N	    Move line pointer to the next line. This option
		    may also be performed by pressing the return key
		    without any characters being typed.
		    Note the new line will be print on the VDU when this
		    operation has been performed.
	  P	    This command allows you see what is on the present
		    line by printing then present line.
	  R	    This command allows you to replace the present line
		    with the text you will be requested to type in.
	  S	    This command allows you show the whole contents of
		    the file/section you are editing.
		    When this operation is complete the line pointer will
		    be at the start of the file/section.
	  T	    This command allow you to reposition the line pointer
		    back to the start of the file/section being edited.
		    ie back to TOP of the buffer.
	  U	    This command allows you insert a number of line of
		    text into a file/section, you can contine inserting
		    line of text UNTIL the return key is pressed alone
	
	
.C Utility program	Tidy and Document program.
.T General information.
	
	
	
	
GENERAL INFORMATION ON EXPAND AND TIDY LAYOUT AND DOCUMENT PROGRAMS
-------------------------------------------------------------------
 
 
ACTION REQUIRED TO USE THIS PACKAGE.
ENTER AFTER PDS> THE FOLLOWING INFORMATION AS SO :-
 
PDS> TDY
     ---
 
Now we have the option of selecting the
tdy program or document program, when the
following message is output.
 
WHICH PROGRAM DO YOU WISH TO RUN OPTIONS
AVAILABLE 'EXPAND AND TIDY' OR 'DOCUMENT'
PLEASE REPLY TDY/DOC ?
 
		'If you reply TDY continue as below'
		'Otherwise follow DOC instructions'
INDENTS AFTER BEGINS YES/NO ?
 
		(This message allows you to specify where the
		(text after will start ie. 'BEGIN'
		(			       TEXT DATA
		(is an example of indents after begins
		(if the answer was no to this question then the
		(output would be 'BEGIN'
		(		 TEXT DATA etc.
 
IS A DOCUMENTATION COPY TO LINEPRINTER WANTED YES/NO ?
 
		(If reply is YES then a copy of program is sent
		(lineprinter with each line numbered
 
EXPANSIONS YES/NO ?
 
		(The reply to this question determines if
		(the expansions are to be used
MONITOR YES/NO ?
 
		(This facility allows the user to monitor the
		(progress of program and will assist if any error
		(reports are generated.
 
INPUT FILE  ?
OUTPUT FILE ?
		(Default options for input and output is your
		(own UIC and .COR. ie. an input of TDY is assumed
		(to be TDY.COR.  If the monitor is not being used
		(the next message output will be
 
PLEASE WAIT
 
		(At end of program the following message will
		(be output
 
DO YOU WISH TO RERUN PROGRAM
PLEASE REPLY         YES/NO ?
 
		(If the reply is YES the program will restart
		(if the reply is SAME the program will restart
		(at message 'INPUT FILE'
		(If the reply is NO the program will output the
		(following message and return you to PDS>
 
GOODBYE
.T FACILITIES OF THE TIDY LAYOUT PROGRAM
 
 
 
FACILITIES OF THE EXPAND TIDY AND LAYOUT PROGRAM
 
(1)	The program will layout coral source code/s.
	procedures will be preceded by two newlines, comments
	will be preceded by one newline
	Begins and ends will be aligned and will be indented
	across the page as they are nested within the program
	and will be started on a newline. If there is an excess of
	BEGINS or ENDS an error message will be generated to
	inform the user.

(2)	Special action words
	'CHANGE' will cause the program to request a new output file
		 for the output coral code to be sent to
	'IGNORE' will cause the program to stop transferring
		 coral code to the output file
	'RESTART'will cause the program to resume transferring
		 the coral code to the output file
 
(3)	Expansion facility
	When the expansion facility is required an abreviated form 
	of CORAL(66) may be presented to this program which will be
	then expanded into a coral source code suitable for the 
	PDP11/70 coral compiler.
 
(4)	General information
	The program will always remove any ASCII character with a code
	value of less than 32 ie. non printing characters hence
	hopefully reducing compiling errors
 
(5)	The following language words are checked for validity
	AND	ABSOLUTE	ANSWER	ARRAY	BEGIN	BITS	BYTE
	CODE	COMMENT		COMMON	CORAL	DEFINE	DELETE	DIFFER
	DO	DOUBLE  END	ELSE	EXTERNAL	ENTER	FIXED
	FINISH	FLOATING	FOR	GOTO	IF	INCLUDE	INTEGER
	LABEL	LIBRARY LIST	LITERAL	LOCATION	NOLIST	OCTAL
	OVERLAY	OR	MASK	PRESET	PROCEDURE	RECURSIVE
	RAD50	STEP	SEGMENT	SWITCH	TABLE	TEST	THEN	UNION
	UNSIGNED UNTIL	WHILE	WITH
	
(6)	Error reporting system
	If the program suspects that a language word is in error
	the program allows the option of changing the source text
	directly from the keyboard and inserting the new data in the
	output file.  Note this is a very limited checking procedure
	and therefore it is possible for genuine error to bypass this
	error checking section
	Other checks that are performed are a count of all () [] brackets
	ensuring that they all match up.  There is also a count of 'GOTO'
	statements though this is for the users benefit only.
	Other checks performed are :-
		Matching of 'FOR' 'DO'       language words
		Matching of 'OVERLAY''WITH'  language words.
		Matching of 'IF' 'THEN'      language words.
		Matching of 'BEGIN' 'END'    language words.
	and syntax of 'LITERAL' CONSTANTS.
	If this program suspects it has found a error you will be given
	the option to destroy the output file this sometimes can avoid you
	getting into a mess with version numbers.
	Note: If the batch command option is selected and errors found the
	output file is deleted automatically as you may have decided
	to run this program without wishing to watch the display.
 
(7)	Highlight mode
	Should you wish to identify special characters or groups of characters
	eg. TIDEF TNEW etc.
	When processing your program/s if you have selected the documentation
	copy option you will be allowed to select the highlight mode.
	If you select the highlight mode every time the program detects a
	occurrence of your identify character/s these character/s will be
	underlined on the documentation copy which is sent to the lineprinter.
	If you have selected to use highlights the message identify > will
	come on your terminal.  You can select to a maximum of 5 character
	groups of maximum 50 characters to identify.
		Note: If you required only two character groups to identify
	the remaining three identify groups would be terminated by
	pressing the return key these would then become void fields.
 
(8)	Command batch controller
	If you have many programs which require tidying up then when
	the message INPUT FILE? appears you can submit a command file
	by preceding the command file name with an @ character.
		Note: When the @ character is detected the command
	file default option is assumed ie.  .CMD and your own UIC
	See Topic for special file control characters.
		Note: Filenames read by the command controller are assumed to
	be your own UIC and .cor as this program is only suitable for coral
	programs.
 
.T SINGLE EXPANSIONS
 
 
SINGLE EXPANSIONS DATA GROUP
 
'A'	CONVERTS TO	'AND'
'ABS'	CONVERTS TO	'ABSOLUTE'
'ANS'	CONVERTS TO	'ANSWER'
'AR'	CONVERTS TO	'ARRAY'
'B'	CONVERTS TO	'BEGIN'
'BY'	CONVERTS TO	'BYTE'	
'BEG'	CONVERTS TO	'BEGIN'
'COM'	CONVERTS TO	'COMMENT'
'CMN'	CONVERTS TO	'COMMON'
'COR'	CONVERTS TO	'CORAL'
'D'	CONVERTS TO	'DO'
'DEF'	CONVERTS TO 	'DEFINE'
'DEL'	CONVERTS TO	'DELETE'
'E'	CONVERTS TO	'END'
'EL'	CONVERTS TO	'ELSE'
'EX'	CONVERTS TO	'EXTERNAL'
'ENT'	CONVERTS TO	'ENTER'
'F'	CONVERTS TO	'FOR'
'FIN'	CONVERTS TO	'FINISH'
'FLO'	CONVERTS TO	'FLOATING'
'G'	CONVERTS TO	'GOTO'
'I'	CONVERTS TO	'INTEGER'
'INC'	CONVERTS TO	'INCLUDE'
'L'	CONVERTS TO	'LONG'
'INT'	CONVERTS TO	'INTEGER'
'LAB'	CONVERTS TO	'LABEL'
'LIB'	CONVERTS TO 	'LIBRARY'
'LIT'	CONVERTS TO 	'LITERAL'
'LOC'	CONVERTS TO	'LOCATION'
'O'	CONVERTS TO	'OCTAL'
'OVR'	CONVERTS TO 	'OVERLAY'
'M'	CONVERTS TO	'MASK'
'P'	CONVERTS TO	'PROCEDURE'
'PR'	CONVERTS TO	'PRESET'
'PROC'	CONVERTS TO	'PROCEDURE'
'REC'	CONVERTS TO	'RECURSIVE'
'S'	CONVERTS TO	'STEP'
'SEG'	CONVERTS TO	'SEGMENT'
'SW'	CONVERTS TO	'SWITCH'
'T'	CONVERTS TO	'THEN'
'TE'	CONVERTS TO	'TEST'
'TAB'	CONVERTS TO 	'TABLE'
'VAL'	CONVERTS TO	'VALUE'
'U'	CONVERTS TO	'UNTIL'
'W'	CONVERTS TO	'WITH'
'WI'	CONVERTS TO 	'WHILE'
 
.T  MULTIPLE EXPANSIONS	
 
MULTIPLE EXPANSION DATA GROUP
 
'BA'	CONVERTS TO	'BYTE''ARRAY'
'DA'	CONVERTS TO	'DOUBLE''ARRAY'
'FA'	CONVERTS TO	'FLOATING''ARRAY'
'LA'	CONVERTS TO	'LONG''ARRAY'
'IA'	CONVERTS TO	'INTEGER''ARRAY'
'LB'	CONVERTS TO	'LOCATION''BYTE'
'LD'	CONVERTS TO	'LOCATION''DOUBLE'
'LF'	CONVERTS TO 	'LOCATION''FLOATING'
'LI'	CONVERTS TO	'LOCATION''INTEGER'
'LL'	CONVERTS TO	'LOCATION''LONG'
'VB'	CONVERTS TO	'VALUE''BYTE'
'VD'	CONVERTS TO	'VALUE''DOUBLE'
'VF'	CONVERTS TO 	'VALUE''FLOATING'
'VL'	CONVERTS TO	'VALUE''LONG'
'VI'	CONVERTS TO	'VALUE''INTEGER'
'BP'	CONVERTS TO	'BYTE''PROCEDURE'
'DP'	CONVERTS TO 	'DOUBLE''PROCEDURE'
'FP'	CONVERTS TO	'FLOATING''PROCEDURE'
'IP'	CONVERTS TO	'INTEGER''PROCEDURE'
'LP'	CONVERTS TO	'LONG''PROCEDURE'
 
.T Document program general information.
 
 
GENERAL INFORMATION ON DOCUMENT PROGRAM
---------------------------------------
 
 
DOCUMENTATION COPY PROGRAM
--------------------------
 
DO YOU WISH TO USE IDENTIFY HIGHLIGHT MODE YES/NO ?
 
		(If you reply YES you may now select up to five
		(character strings which you wish to identify.  After each
		(line is printed out, if the characters you have selected
		(occur in the line they will be underlined on the output
		(hard copy.
 
SOURCE FILE ?
 
		(At this point you type in the name of the file
		(you wish to be presented to the lineprinter
		(the default options are
		(Your UIC and the extension .COR
 
DO YOU WISH TO RERUN THIS PROGRAM
PLEASE REPLY              YES/NO ?
	
 		(If you reply YES the program will restart
		(If you reply SAME program will restart
		(as message SOURCE FILE?
		(YES and NO reply may be shortened to Y or N
		(but for YES YE is not acceptable.
		(If your reply is NO or N the program returns
		(you back to PDS.
 
.T Facilities of document program.
 
FACILITIES OF DOCUMENT PROGRAM
 
 
(1)	This program presents to the lineprinter a header which will tell you
	which file has been processed the time of day and the date and a note
	that the documentation program presented the data.
 
(2)	This program has the option of numbering each line of data as so:-
	  EDITOR PAGE NUMBER	LINE IN PAGE	SEQUENTIAL LINE NUMBER COUNT
	If this option is not required precede the source filename with
	a minus		eg.	-DOC
	When this option is selected 8 spaces will precede each line of data.
 
(3)	When a number of files are required for printing you can present a
	batch command source to this program in the following manner:-
	   SOURCE FILE?   @MANYFILES.CMD
	The program will now scan through the file manyfiles.cmd processing
	Each file with a new header.
	  Note:  .CMD is assumed when first character is @ and your own UIC.
	structure of command file is:-
	  (MINUS OPTION)(FILENAME .COR AND OWN UIC STILL ASSUMED IF MISSING)
	eg.
	  -DOC.CMD
	  DOC
	  TDY
	  -TDY.CMD
	Note:  No terminator required on command file
	When all files processed program will check if any files
	to be processed.
 
.T common information to both TIDY and DOCUMENT programs
 
COMMON INFORMATION
-------------------
 
        FILE CONTROL CODES.
 
	If a filename is preceded by a * character the file is assumed to be
	a void file and the file is not processed.  If a filename is preceded
	by a - character the file is not modified but if lineprinter is
	selected it is copied out to lineprinter through the Document
	program without line numbering facility.
	If a filename is preceded by a # character if you are using the
	document program the # is ignored.  If you are using the
	TDY program comments are left in the form you typed them
	in ie.  # = don't format comments.
 
 
 
		
.C GENERAL INFORMATION AND REVISION LIST
.T GENERAL INFORMATION
.I CORAL STRINGS

 
			CHARACTER STRINGS
			-----------------
 
	STANDARD FORM OF PROCEDURE STRINGS
				BYTES 0,1	STRING BUFFER LENGTH
				BYTES 2,3	NUMBER OF CHARACTERS IN STRING
				BYTES 4,+	STORED CHARACTERS
	STRING ADDRESS RELATED TO BYTE [2]


	STANDARD FORM OF CORAL STRING
				BYTES 0,1	NUMBER OF CHARACTERS IN STRING
				BYTES 2,+	STORED CHARACTERS
	STRING ADDRESS RELATED TO BYTE [0]
 
 
	THE FOLLOWING PROCEDURE STRINGS ARE AVAILABLE FOR CORAL.
		STRING NAME		MAX LENGTH
		AS			256
		BS			256
			UNTIL
		YS		  	256
		ZS			256
		BIGS			1996
 
 
.I CORAL MACROS
.I CORAL INTEGERS
.I CORAL FLOATING REGISTERS 
 
 
		INTEGER AND FLOATING REGISTERS FOR GENERAL USE
		----------------------------------------------
 
	THE MACRO (INTEGER REGISTERS)  WILL DECLARE 26 INTEGERS NAMED A TO Z.
	THE MACRO (FLOATING REGISTERS) WILL DECLARE 26 FLOATING LOCATIONS
	NAMED FA TO FZ.
 
 





			AUTHORS
			=======

J. S. Clifton.				R. J. Spriggs.
13th May 1982				3rd September 1981
Telephone Christchurch 472352		Telephone Christchurh 472395




.T REVISION LIST
.I R$POS
.I R$COMPARE

			Revision list
			-------------
Date		Area			Remarks
----		----			-------
22/10/81	R$POS R$COMPARE		Enable upper/lower case matching
22/10/81	Cross reference		Insertion of macro symbol
					reference table
13/12/81	Device control		New section for device routines.
13/12/81	Table routines		New section Tables similar to Nodes.
13/12/81	Queue routines		New section Queue processing routines.
13/12/81	Macros			Usage description appended.
22/04/82	String conversions	More routines added
11/05/82	All			Manual reformated for index program
					utility programs incorporated.
13/05/82	Supermac and Tabmac	New Sections.
25/06/82	String macros		New Sections.


