	T21LIB.HLP -  Description of the procedures held in T21.LIB
	___________________________________________________________


Last updated : 	9-Jun-81   by  Andy Patrick.

Last amendments (brief) :
	Note about DISPLY.HLP added. AP 9-Jun-81
	BINDEC added to library by PMR, 8th June 81.
	INPUT P & OWTPUT added, 2-Jun-81

All the display routines have been duplicated in a form to drive a NEWBURY VDU
or a VT100 VDU and can be called by the same names.  See DISPLY.HLP

NB. Many of these procedures make use of ISIS, PLM80 and monitor routines, so
     SYSTEM.LIB and PLM80.LIB must be included at LINK time.

Procedures in this library :
ALTOLP$P
APRINT
ASCBIN$P
ATYPE
BACKSPACE
BINASC
BINDEC
CLEAR$REST$OF$SCREEN
CLEAR$SCREEN
CONMON$P
CONVERT
CURSOR$ABS
DEFEXT
DISPLAY
INPUT$P
OWTPUT
RECEIVE$BS4421$DATA
SEND$BS4421$DATA



ALTOLP$P	Written by Andy Patrick, 19-Dec-79,  modified 19-Nov-80.
	ALTOLP$P:PROCEDURE BYTE EXTERNAL;
		 END ALTOLP$P;
	This procedure checks IO assignments, if the LIST device is not :LP: then
	the console is questioned.  Answering with Y(RETURN) will set list=:LP:
	It calls CONMON$P.
	The calling program should clear the command line by READing CI before doing
	STATUS=ALTOLP$P;  /* STATUS = an ISIS error number */


APRINT	Written by Andy Patrick,  14-Aug-80.
	Just like ATYPE but the string is sent to the list device.


ASCBIN$P    Written by Phil Rawlins, 10-Jun-80.
	ASCBIN$P: PROCEDURE (TERM$CHAR$PNTR,STATUS$PNTR) BYTE PUBLIC;
	DECLARE (TERM$CHAR$PNTR,STATUS$PNTR) ADDRESS;
	END ASCBIN$P;
	Uses the MONITOR routine CI (console input) to read the ASCII eqivalent
	of a hexadecimal number in the range 0-0FFH from the console and return
	the value in one byte to the calling routine (the character is echoed
	to the console ). TERM$CHAR$PNTR is the address of a terminating
	character for the typed string. E.g. if the byte at TERM$CHAR$PNTR
	contained the ASCII code for 'space', then calling ASCBIN$P and typing
	on the console 'AA ' would cause the 8-bit pattern 10101010 (AAH) to be
	returned to the calling routine in one byte.
	Any error will be indicated by a return of a non zero status and a
	value of zero will be returned to the calling routine.
	A status of 01 indicates a non HEX character has been typed in the
	first position.
	A status of 02 indicates a non HEX character has been typed in the
	second position.
	A status of 03 indicates three HEX characters have been typed.
	Using the procedure BACKSPACE with the STATUS from BINASC as
	the input parameter, correction of wrongly input characters can be
	easily dealt with on the screen.


ATYPE	Written by Andy Patrick,   6-Jun-80.
	ATYPE:PROCEDURE (STRING$ADDRESS) EXTERNAL;
		DECLARE STRING$ADDRESS ADDRESS;
		END ATYPE;
	STRING$ADDRESS is the address of a character string to be transferred
	to the console.  Terminate the string with a 0 to generate a CR LF,
	or with 80H.


BACKSPACE   Written by Phil Rawlins, 12-Feb-81.
	BACKSPACE: PROCEDURE (NO$OF$CHARS) PUBLIC;
	DECLARE NO$OF$CHARS BYTE;
	END BACKSPACE;
	Moves the cursor NO$OF$CHARS to the left from its current position.



BINASC	Written by Phil Rawlins, 10-Jun-80.
	BINASC: PROCEDURE (ARRAY$PNTR,NO$OF$ELEMENTS$TO$TYPE) EXTERNAL;
	DECLARE ARRAY$PNTR ADDRESS, NO$OF$ELEMENTS$TO$TYPE BYTE;
	END BINASC;
	Types hex values of an array on the screen as ASCII characters.
	The array is output as pairs of hex characters separated by a single
	space with up to 20 pairs per line on the screen.
	ARRAY$PNTR is the address of the array to be typed and
	NO$OF$ELEMENTS$TO$BE$TYPED is what the label suggests - this need not
	be the length of the array, e.g if ARRAY$PNTR is the address of a byte
	variable, then NO$OF$ELEMENTS.... can be set to 1, also if the array
	is 100 bytes laong and NO$OF$ELEMENTS.... is set to 5, only the first
	five bytes will be converted and printed.
	A carriage return, line feed sequence is output after the last char.
	Note: If NO$OF$ELEMENTS.... is zero then no data is dispalyed and
	      no error message is returned.


BINDEC  Written by Phil Rawlins, 8-Jun-81.
	BINDEC: PROCEDURE (BINARY$NUMBER,BUFFER$PNTR) EXTERNAL;
	DECLARE BINARY$NUMBER BYTE, BUFFER$PNTR ADDRESS;
	END BINDEC;
	Converts a binary number held in a byte location, with a value
	0 to 0FFH inc. to three ASCII characters representing the number
	in decimal form. The ASCII chars. are placed in the array referenced
	by BUFFER$PNTR, most significant digit first. The receiving array
	may be more than three bytes long but NOT LESS THAN THREE BYTES LONG.
	Leading zeroes are placed in the receiving array and will be printed
	as an ASCII zero when the array is output to the console.


CLEAR$REST$OF$SCREEN  Written by Phil Rawlins, 27-Oct-80.
	CLEAR$REST$OF$SCREEN: PROCEDURE (XPOSN,YPOSN) EXTERNAL;
	DECLARE (XPOSN,YPOSN) BYTE;
	END CLEAR$REST$OF$SCREEN;
	Clears the display screen from the specified position where :
	XPOSN is the number of chars accross from the lhs of the screen
								     (0 to 79),
	YPOSN is the number of lines down from the top of the screen (0 to 23).


CLEAR$SCREEN  Written by Phil Rawlins, 27-Oct-80.
	CLEAR$SCREEN: PROCEDURE EXTERNAL;
	END CLEAR$SCREEN;
	Clears the whole screen when called and positions the cursor in
	the top left hand corner (position 0,0).


CONMON$P	Written by Andy Patrick,  14-Dec-79, modified 6-Mar-81.
	CONMON$P:PROCEDURE BYTE EXTERNAL;
		END CONMON$P;
	Do CHARACTER=CONMON$P; If a key has not been pressed on the console then
	CONMON$P returns immediately with a value 0.  If ^C was pressed then it
	will echo ^C and force an ISIS EXIT.  ^S will cause CONMON$P to echo ^S
	and wait for a ^Q before returning the value 11H.  Otherwise the value
	of the key pressed is returned.  Modified on 6-Mar-81 to ignore any
	parity bit, however the value returned may have parity set, depending on
	the console.


CONVERT	Written by Phil Rawlins, 10-Jun-80.
	CONVERT: PROCEDURE(HEX$BYTE,HIGH$ASC$PNTR,LOW$ASC$PNTR) EXTERNAL;
	DECLARE HEX$BYTE BYTE, (HIGH$ASC$PNTR,LOW$ASC$PNTR) ADDRESS;
	END CONVERT;
	Converts an eight bit byte into two printable ASCII characters
	which are returned in locations pointed to by HIGH$ASC$PNTR and
	LOW$ASC$PNTR. There are NO error messages.


CURSOR$ABS   Written by Phil Rawlins, 27-Oct-80.
	CURSOR$ABS: PROCEDURE (XPOSN,YPOSN) EXTERNAL;
	DECLARE (XPOSN,YPOSN) BYTE;
	END CURSOR$ABS;
	Positions the cursor at the absolute co-ordinate XPOSN,YPOSN prior
	to displaying data on the screen. Position (0,0) is at the top left
	hand side of the screen. XPOSN is the character position (max 79),
	YPOSN is the line position (max 23).
	NOTE: If XPOSN > max then the text will appear on the next line down,
	      if YPOSN > max then the screen will go into roll mode and the top
	      line(s)  will be lost.


DEFEXT	Written by Andy Patrick, 13-Jun-80.
	Adds a default extension to a filename.
	DEFEXT:PROCEDURE(BUFFER$ADDRESS,EXTENSION$ADDRESS,COUNT,STATUS$ADDRESS)EXTERNAL;
		DECLARE (BUFFER$ADDRESS,EXTENSION$ADDRESS,STATUS$ADDRESS) ADDRESS;
		DECLARE (COUNT) BYTE;
		END DEFEXT;
	BUFFER ADDRESS is the address of the first byte of an array containing
	the text to be modified.  EXTENSION ADDRESS points to the first byte of
	the string to be appended onto the buffer.  COUNT is the number of bytes
	to be appended.  STATUS ADDRESS is the address where DEFEXT will put the
	16 bit error number.
		DEFEXT searches the buffer for a '.' if it is not followed by a
	text character it is replaced by a space.  If the '.' is followed by a text
	character the buffer remains unchanged.  If an unprintable character is
	found before a '.' then it is replaced by a '.' and COUNT bytes are taken
	from the extension array and inserted into the buffer.
		STATUS is set to 0 unless the buffer length of 120 is exceeded
	or a CR or LF is found before any text characters, in these cases STATUS
	is set to 123.


DISPLAY   Written by Phil Rawlins, 27-Oct-80.
	DISPLAY: PROCEDURE (XPOSN,YPOSN,TEXT$ADDR) EXTERNAL;
	DECLARE (XPOSN,YPOSN) BYTE, TEXT$ADDR ADDRESS;
	END DISPLAY;
	Moves the cursor to the co-ordinate (XPOSN,YPOSN) on the screen and
	writes the text given by the address TEXT$ADDR. The top left hand
	corner has co-ordinate (0,0). Bottom right hand corner has co-ordinate
	(79,23). If the text string is terminated by a null byte - 00H - then
	<CR,LF> is output after the string. If it is terminated by the value
	80H then no other characters are output (uses ATYPE - see above).

INPUT$P	  Written by Andy Patrick, 2-Jun-81.
	INPUT$P: PROCEDURE (PORT$NUMBER) BYTE EXTERNAL;
	DECLARE PORT$NUMBER BYTE;
	END INPUT$P;
	  A large CASE statement which returns the value latched on the port
	identified by PORT$NUMBER.  If the port does not exist the system may
	halt!


OWTPUT	  Written by Andy Patrick, 2-Jun-81.
	OWTPUT: PROCEDURE (PORT$NUMBER, VALUE) EXTERNAL;
	DECLARE (PORT$NUMBER, VALUE) BYTE;
	END OWTPUT;
	  A large CASE statement which sends the number VALUE to the port
	identified by PORT NUMBER.


RECEIVE$BS4421$DATA	Written by Phil Rawlins, 19-Nov-80.
	RECEIVE$BS4421$DATA: PROCEDURE (ARR$ADDR,STAT$PNTR) ADDRESS EXTERNAL;
	DECLARE (ARR$ADDR,STAT$PNTR) ADDRESS;
	END RX4421;
	Receives data under the BS4421 handshaking conventions from another
	terminal which is sending 8 bit parallel data using TX4421 (see below).
	ARR$ADDR is the pointer to a receiving buffer which must be large
	enough to accomodate all the incoming data. STAT$PNTR is the pointer
	to a byte variable which contains the status on return to the calling
	routine. STATUS = 0 for no error, STATUS=5 if the other terminal is
	trying to receive at the same time (this avoids lock ups). A status of
	6,7 or 8 indicates a timeout error, any data already received may
	be invalid.
	Bytes are sequentially stored in the data buffer until the last byte
	is received. The total no. of bytes received is then returned to the
	calling routine (this is an ADDRESS value). Port 2 is used to transfer
	data and Port 3 is used for handshake control lines.
	NOTE: Bit 4 (10H) is at software logic 1 when the other end is trying
	      to send data (SOURCE OPERABLE TRUE).

SEND$BS4421$DATA	Written by Phil Rawlins, 19-Nov-80
	SEND$BS4421$DATA: PROCEDURE (ARR$ADDR,NO$OF$BYTES,STAT$PNTR) EXTERNAL;
	DECLARE (ARR$ADDR,NO$OF$BYTES,STAT$PNTR) ADDRESS;
	END SEND$BS4421$DATA;
	Transmits 8 bit parallel data to another terminal under BS4421 hand-
	shaking conventions. The receiving terminal must have the 
	RECEIVE$BS4421$DATA procedure running (see above). ARR$ADDR is a
	pointer to the array containing the data to be transferred. NO$OF$BYTES
	is an address variable giving the number of bytes to be transferred 
	(if ARR$ADDR points to a BYTE variable then NO$OF$BYTES should be 1).
	STAT$PNTR is a pointer to a STATUS byte which is updated on return to
	the calling routine. STATUS = 0, no error. STATUS = 1, other end trying
	to send at the same time, STATUS = 2,3 or 4 time out has occurred
	during the send operation. In the case of a time out error, some data
	may have been sent to the receiver although this cannot be guaranteed.

