Chapter Thirteen

External Data I/O Statements

The external data I/O statements allow data which is not part of the BASIC source program to flow into and out of BASIC. External data can come from the keyboard, a disk, or a cassette. BASIC can also create external information by sending data to external devices such as the screen, a printer, or a disk. The INPUT and GET statements are the primary statements used for obtaining information from external devices. The PRINT and PUT statements are the primary statements for sending data to external devices. XIO, LPRINT, OPEN, CLOSE, NOTE, POINT and STATUS are specialized I/O statements. LPRINT is used to print a single line to the "P:" device. The other statements assist in the I/O process. XINPUT ($B316) The execution of the INPUT statement starts at )(INPUT ($B316). Getting the Input Line. The first action of XINPUT is to read a line of data from the indicated device. A line is any combination of up to 255 characters terminated by the EOL character ($9B). This line will be read into the buffer located at $580. If the INPUT statement contained was followed by #<expression>, the data will be read from the IOCB whose number was specified by <expression>. If there was no #<expression>, IOCB 0 will be used. IOCB 0 is the screen editor and keyboard device (E:). If IOCB 0 is indicated, the prompt character (?) will be displayed before the input line request is made; otherwise, no prompt is displayed. Line Processing. Once the line has been read into the buffer, processing of the data in that line starts at XINA ($B335). The input line data is processed according to the tokens in the INPUT (or READ) statements. These tokens are numeric or string variables separated by commas. 95

Chapter Thirteen Processing a Numeric Variable. If the new token is a numeric variable, the CVAFP routine is called to convert the next characters in the input line to a floating point number. If this conversion does not report an error1 and if the next input line character is a comma or an EOL, the floatixig point value is processed. The processing of a valid numeric input value consists of calling RTNVAR to return the variable and its new value to the Variable Value Table. If there is an error, INPUT processing is aborted via the ERRINP routine. If there is no error, but the user has hit BREAK, the process is aborted via XSTOP. If there is no abort, XINX ($B389) is called to continue with INPUT's next task. Processing a String Variable. If the next statement token is a string variable, it is processed at XISTR ($B35E). This routine is also used by the READ statement. If the calling statement is INPUT, then all input line characters from the current character up to but not including the EOL character are considered to be part of the input string data. If the routine was called by READ, all characters up to but not including the next comma or EOL are considered to be part of the input string. The process of assigning the data to the string variable is handled by calling RISASN ($B386). If RISASN does not abort the process because of an error like DIMENSION TOO SMALL, XINX is called to continue with INPUT's next task. XINX. The XINX ($B389) routine is entered after each variable token in an INPUT or a READ statement is processed. If the next token in the statement is an EOL, the INPUT/READ statement processing terminates at XIRTS ($B3A1). XIRTS restores the line buffer pointer ($80) to the RAM table buffer. It then restores the enter device to IOCB 0 (in case it had been changed to some other input device). Finally, XIRTS executes an RTS instruction. If the next INPUT/READ statement token is a comma, more input data is needed. If the next input line character is an EOL, another input line is obtained. If the statement was INPUT, the new line is obtained by entering XINO ($B326). If the statement was READ, the new lineis obtained by entering XRD3 ($B2D0). The processing of the next INPUT/READ statement variable token continues at XINA. 96
Chapter Thirteen XGET ($BC7F) The GET statement obtains one character from some specified device and assigns that character to a scalar (non-array) numeric variable. The execution of GET starts at XGET ($BC7F) with a call to GIODVC. GIODVC will set the I/O device to whatever number is specified in the #< expression> or to IOCB zero if no #<expression> was specified. (If the device is IOCB 0 (E:), the user must type RETURN to force E: to terminate the input.) The single character is obtained by calling 103. The character is assigned to the numeric variable by calling ISVAR1 ($BD2D). ISVAR1 also terminates the GET statement processing. PRINT The PRINT statement is used to transmit text data to an external device. The arguments in the PRINT statement are a list of numeric and/or string expressions separated by commas or semicolons. If the argument is numeric, the floating point value is converted to text form. If the argument is a string, the string value is transmitted as is, If an argument separator is a comma, the arguments are output in tabular fashion: each new argument starts at the next tab stop in the output line, with blanks separating the arguments. If the argument separator is a semicolon, the transmitted arguments are appended to each other without separation. The transmitted line is terminated with an EOL, unless a semicolon or comma directly precedes the statement's EOL or statement separator (:). XPRINT ($B3B6). The PRINT routine begins at XPRINT ($B3B6). The tab value is maintained in the PTABW ($C9) cell. The cell is initialized with a value of ten during BASIC's cold start, so that commas in the PRINT line cause each argument to be displaced ten positions after the beginning of the last argument. The user may POKE PTABW to set a different tab value. XPRINT copies PTABW to SCANT ($AF). SCANT will be used to contain the next multiple-of-PTABW output line displacement - the column number of the next tab stop. COX is initialized to zero and is used to maintain the current output column or displacement. 97
Chapter Thirteen XPRO. XPRINT examines the next statement token at XPRO ($B3BE), classifies it, and executes the proper routine. # Token. If the next token is #, XPRIOD ($B437) is entered. This routine modifles the list device to the device specified in the # <expression>. XPRO is then entered to process the next token. , Token. The XPTAB ($B419) routine is called to process the , token. Its job is to tab to the next tab column. If COX (the current column) is greater than SCANT, we must skip to the next available tab position. This is done by continuously adding PTABW to SCANT until COX is less than or equal to SCANT. When COX is less than SCANT, blanks ($20) are transmitted to the output device until COX is equal to SCANT. The next token is then examined at XPRO. EOL and: Tokens. The XPEOS ($B446) routine is entered for EOL and tokens. If the previous token was a; or, token, PRINT exits at XPRTN ($B458). If the previous token was not a; or, token, an EOL character is transmitted before exiting via XPRTN. ; Token. No special action is taken for the; token except to go to XPRO to examine the next token. Numbers and Strings. If the next token is not one of the above tokens, Execute Expression is called to evaluate the expression. The resultant value is popped from the argument stack and its type is tested for a number or a string. If the argument popped was numeric, it will be converted to text form by calling CVFASC. The resulting text is transmitted to the output device from the buffer pointed to by INBUFF ($F3). XPRO is then entered to process the next token. If the argument popped was a string, it will be transmitted to the output device by the code starting at :XPSTh ($B3F8). This code examines the argument parameters to determine the current length of the string. When the string has been transmitted, XPRO is entered to process the next token. XLPRINT ($8464) LPRINT, a special form of the PRINT statement, is used to print a line to the printer device (P:). 98
Chapter Thirteen The XLPRINT routine starts at $B464 by opening IOCB 7 for output to the P: device. XPRINT is then called to do the printing. When the XPRINT is done, IOCB 7 is closed via CLSYS1 and LPRINT is terminated. XPUT ($BC72) The PUT statement sends a single byte from the expression in the PUT statement to a specified external device. Processing starts at XPUT ($BC72) with a call to GIODVC. GIODVC sets the I/O device to the IOCB specified in #<expression>. If a #< expression> does not exist, the device will be set to IOCB zero (E:). The routine then calls GETINT to execute PUT's expression and convert the resulting value to a two-byte integer. The least significant byte of this integer is then sent to the PUT device via PRCX. PRCX also terminates the PUT processing. XXIO ($BBE5) The XIO statement, a general purpose I/O statement, is intended to be used when no other BASIC I/O statement will serve the requirements. The XIO parameters are an IOCB I/O command, an IOCB specifying expression, an AUXi value, an AUX2 value, and finally a string expression to be used as a filespec parameter. XIO starts at XXIO ($BBE5) with a call to GIOCMD. CIOCMD gets the IOCB command parameter. XIO then continues at XOP1 in the OPEN statement code. XOPEN ($BBEB) The OPEN statement is used to open an external device for input and/or output. OPEN has a # <expression>, the open type parameter (AUX1), an AUX2 parameter, and a string expression to be used as a filespec. OPEN starts at XOPFN at $BBEB. It loads the open command code into the A register and continues at XOP1. XOP1. XOP1 continues the OPEN and XIO statement processing. It starts at $BBED by storing the A register into the IOCMD cell. Next it obtains the AUX1(open type) and AUX2 values from the statement. The next parameter is the filespec string. In order to insure that the filespec has a proper terminator, SETSEOL is called to place a temporary EOL at the end of the string. 99
Chapter Thirteen The XIO or OPEN command is then executed via a call to IO1. When IO1 returns, the temporary EOL at the end of the string is replaced with its previous value by calling RSTSEOL. OPEN and XIO terminate by calling TOTEST to insure that the command was executed without error. XCLOSE ($BC1B) The CLOSE statement, which closes the specified device, starts at XCLOSE ($BCIB). It loads the IOCB close command code into the A register and continues at GDVCIO. GDVCEO. GDVCIO ($BC1D) is used for general purpose device I/O. It stores the A register into the IOCMD cell, calls GIODVC to get the device from # <expression>, then calls IO7 to execute the IO0. When IO7 returns, IOTEST is called to test the results of the I/O and terminate the routine. XSTATUS ($BC28) The STATUS statement executes the IOCB status command. Processing starts at XSTATUS ($BC28) by calling GIODVC to get the device number from # <expression>. It then calls IO8 with the status command in the A register. When IO8 returns, the status returned in the IOCB status cell is assigned to the variable specified in the STATUS statement by calling ISVARI. ISVAR1 also terminates the STATUS statement processing. XNOTE ($BC3G) The NOTE statement is used specifically for disk random access. NOTE executes the Disk Device Dependent Note Command, $26, which returns two values representing the current position within the file for which the IOCB is open. NOTE begins at XNOTE at $BC36. The code loads the command value, $26, into the A register and calls GDVCIO to do the I/O operation. When GDVCIO returns, the values are moved from AUX3 and AUX4 to the first variable in the NOTE statement. The next variable is assigned the value from AUX5. XPOINT ($8C4D) The POINT statement is used to position a disk file to a previously NOTEd location. Processing starts at XPOINT ($BC4D). This routine conyerts the first POINT parameter to an integer and stores the value in AUX3 and AUX4. The second parameter is then converted to an integer and its value stored 100
Chapter Thirteen in AUX5. The POINT command, $25, is executed by calling GDIO1, which is part of GDVCIO. Miscellaneous I/O Subroutines IOTEST. IOTEST($BCB3) is a general purpose routine that examines the results of an I/O operarion. If the I/O processing has returned an error, IOTEST processes that error. IOTEST starts by calling LDIOSTA to get the status byte from the IOCB that performed the last I/O operation. If the byte value is positive (less than 128), IOTEST returns to the caller. If the status byte is negative, the I/O operation was abnormal and processing continues at SICKIO. If the I/O aborted due to a BREAK key depression, BRKBYT ($11) is set to zero to indicate BREAK. If a LOAD was in progress when BREAK was hit, exit is via COLDSTART; otherwise IOTEST returns to its caller. If the error was not from IOCB 7 (the device BASIC uses), the error status value is stored in ERRNUM and ERROR is called to print the error message and abort program execution. If the error was from IOCB 7, then IOCB 7 is closed and ERROR is called with the error status value in ERRNUM - unless ENTER was being executed, and the error was an end- of-file error. In this case, IOCB 7 is closed, the enter device is reset to IOCB 0, and SNX2 is called to return control to the Program Editor. I/O Call Routine. All I/O is initiated from the routine starting at IO1 ($BD0A). This routine has eight entry points, IO1 through IO8, each of which stores predetermined values in an IOCB. All IOn entry points assume that the X register contains the IOCB value, times 16. IO1 sets the buffer length to 255. IO2 sets the buffer length to zero. IO3 sets the buffer length to the value in the Y register plus a most-significant length byte of zero. IO4 sets the buffer length from the values in the Y,A register pair, with the A register being the most-significant value. IO5 sets the buffer address from the value in the INBUFF cell (sF3). IO6 sets the buffer address from the Y,A register pair. The A register contains the most significant byte. 101
Chapter Thirteen IO7 sets the 1/0 command value from the value in the IOCMD cell. IO8 sets the I/O command from the value in the A register. All of this is followed by a call to the operating system CIO entry point. This call executes the I/O. When CIO returns, the general I/O routine returns to its caller. 102

<-Chapter 12Chapter 14->