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 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.