This routine gets a byte of data off the serial bus using full handshaking. The data is returned in the accumulator.

To prepare for this routine the TALK routine must be called first to command the device on the serial bus to send data through the bus. If the input device needs a secondary command, it must be sent by using the TKSA routine before calling this routine.

Errors are returned in the status word. The READST routine is used to read the status word.

Any logical file number that has been created by the OPEN routine can be defined as an input channel. Of course, the device you intend opening a channel to must be an input device. Otherwise, an error will occur, and the routine will be aborted.

If you are getting data from anywhere other than the keyboard, this routine must be called before using either the CHRIN or the GETIN routines for data input. If you want to use the input from the keyboard, and no other input channels are opened, then the calls to this routine, and to the OPEN routine are not needed.

Any logical file number that has been created by the OPEN routine can be defined as an output channel. Of course, the device you intend opening a channel to must be an output device. Otherwise, an error will occur, and the routine will be aborted.

This routine must be called before any data is sent to any output device unless you want to use the screen as your output device. If screen output is desired, and there are no other output channels already defined, then calls to this routine, and to the OPEN routine are not needed.

This routine gets a byte of data from a channel already set up as the input channel by the CHKIN routine. If CHKIN has NOT been used to define another input channel, then all your data is expected from the keyboard.

The data byte is returned in the accumulator. The Y index register is unchanged and is usually used in a loop to store received characters.

The channel remains open after the call.

Reading from the Keyboard

Input from the keyboard is handled in a special way. First, the cursor is turned on, and blinks until a carriage return is typed on the keyboard. All characters on the line can be retrieved one at a time by calling this routine once for each character. When the carriage return is retrieved, the entire line has been processed. The next time this routine is called, the whole process begins again, i.e., by flashing the cursor.

Example:

.readLine   LDY #0              ; Prepare Y register to store data
.readLoop   JSR CHRIN           ; Get next character
            STA BUF,Y           ; Store in BUF (0x200 89 byte basic input buffer)
            INY
            CMP #0x0D           ; Carriage Return
            BNE readLoop        ; Loop back for next character
            RTS

Reading from other devices

Here you need to call OPEN and CHKIN first before calling CHRIN.

This routine outputs a character to an already opened channel. Use the OPEN and CHKOUT routines to set up the output channel before calling this routine. If this call is omitted, data is sent to the default output device (number 3, the screen).

The data byte to be output is loaded into the accumulator, and this routine is called. The data is then sent to the specified output device. The channel is left open after the call.

This routine sets up the VIC-II chip, clear the screen, set the cursor pointer and the screen editor.

Normally, this routine is called as part of the initialization process of a Commodore 64 program cartridge.

This routine is used to send information to devices on the serial bus. A call to this routine will put a data byte onto the serial bus using full serial handshaking.

Before this routine is called, the LISTEN routine must be used to command a device on the serial bus to get ready to receive data. If a device needs a secondary address, it must also be sent by using the SECOND routine.

The accumulator is loaded with a byte to handshake as data on the serial bus. A device must be listening or the status word will return a timeout.

This routine always buffers one character. (The routine holds the previous character to be sent back.) So when a call to the UNLSN routine is made to end the data transmission, the buffered character is sent with an End Or Identify (EOI) set. Then the UNLSN command is sent to the device.

This routine closes all open files. When this routine is called, the pointers into the open file table are reset, closing all files.

Also, the CLRCHN routine is automatically called to reset the I/O channels.

This routine is used to close a logical file after all I/O operations have been completed on that file. This routine is called after the accumulator is loaded with the logical file number to be closed - the same number used when the file was opened using the OPEN routine.

This routine is called to clear all open channels and restore the I/O channels to their original default values.

It is usually called after opening other I/O channels like a tape or disk drive and using them for input/output operations. The default input device is 0 (keyboard). The default output device is 3 (screen).

This routine is automatically called when the CLALL routine is executed.

This routine clears the line pointed to by X.

This routine sets up the screen line link table (0x00D9…0x00F2). It then clears the screen line by line using the CLRLN routine. Once that's completed, it then homes the cursor to the top left.

If the input channel is the keyboard, this subroutine removes one character from the keyboard queue and returns it as an ASCII value in the accumulator. If the queue is empty, the value returned in the accumulator will be zero.

Characters are put into the queue automatically by an interrupt driven keyboard scan routine which calls the SCNKEY routine. The keyboard buffer can hold up to ten characters. After the buffer is filled, additional characters are ignored until at least one character has been removed from the queue.

If the channel is RS-232, then only the A register is used and a single character is returned. See READST to check validity.

If the channel is serial, cassette, or screen, call BASIN routine.

See also

CHKIN, OPEN, READST

This routine sets the X and Y registers to the address of the memory section where the memory mapped 110 devices are located. This address can then be used with an offset to access the memory mapped I/O devices in the Commodore 64. The offset is the number of locations from the beginning of the page on which the I/O register you want is located. The X register contains the low order address byte, while the Y register contains the high order address byte.

This routine exists to provide compatibility between the Commodore 64, VIC-20, and potential future models of the Commodore 64. If the I/O locations for a machine language program are set by a call to this routine, they should still remain compatible with future versions of the Commodore 64, the KERNAL and BASIC.

For the C64 the value returned is 0xDC00 - address of CLA #1

For the C128 the value returned is 0xD000 - address of the VIC chip

This routine initializes all input/output devices and routines.

It is normally called as part of the initialization procedure of a Commodore 64 program cartridge.

This routine will command a device on the serial bus to receive data. The accumulator must first be loaded with a device number between 0 and 31. When called, this routine then ORs bit by bit to convert this device number to a talk address. The specified device will then go into listen mode, and be ready to accept information.

This routine LOADs data bytes from any input device directly into the memory. It can also be used for a verify operation, comparing data from a device with the data already in memory, while leaving the data stored in RAM unchanged.

To use, you first need to call SETLFS to set the device to save to. Then SETNAM must be called to set the filename.

The accumulator must be set to 0 for a load or 1 for a verify operation.

If the input device is opened with a secondary address of 0, the header information from the device is ignored. In this case the X & Y registers must contain the starting address for the load.

With a secondary address of 1 the data is loaded into memory starting at the location specified by the header.

This routine returns the highest address of the data loaded on exit.

This routine reads or writes the bottom of memory.

When the Carry flag is set then the bottom memory address is read into the X, Y index registers.

When the Carry flag is clear then the bottom memory address is set to the address in the X, Y index registers.

The value is stored in the MEMSTR variable at 0x281.

Default values

This routine reads or writes the top of memory.

When the Carry flag is set then the top memory address is read into the X, Y index registers.

When the Carry flag is clear then the top memory address is set to the address in the X, Y index registers.

The value is stored in the MEMSIZ variable at 0x283.

This routine is used to OPEN a logical file. Once the logical file is set up, it can be used for input/output operations.

Most of the I/O routines call on this routine to create the logical files to operate on. No arguments need to be set up to use this routine, but both the SETLFS and SETNAM routines must be called before using this routine.

This routine either reads or sets the text cursor's location.

Reading cursor location

A call to this routine with the accumulator carry flag set loads the current position of the cursor on the screen (in X,Y coordinates) into the Y and X registers. Y is the column number of the cursor location (0-39), and X is the row number of the location of the cursor (0-24).

Setting cursor location

A call with the carry bit clear moves the cursor to X,Y as determined by the Y and X registers.

Example:

This routine is used to test RAM and set the top and bottom of memory pointers accordingly.

It clears locations &00 to &0101 and &0200 to &03FF. It then allocates the cassette buffer, and sets the screen base to $0400.

Normally, this routine is called as part of the initialization process of a Commodore 64 program cartridge.

This routine is used to read the system clock. The clock's resolution is a 60th of a second. Three bytes are returned by the routine. The accumulator contains the most significant byte, the X index register contains the next most significant byte, and the Y index register contains the least significant byte.

This routine returns the current status of the I/O devices in the accumulator. The routine is usually called after new communication to an I/O device. The routine gives you information about device status, or errors that have occurred during the I/O operation.

The bits returned in the accumulator contain the following information:

This routine restores the default values of all system vectors used in KERNAL and BASIC routines and interrupts.

See the Memory Map for the default vector contents.

The VECTOR routine is used to read and alter individual system vectors.

This routine saves a section of memory to a device.

To use, you first need to call SETLFS to set the device to save to. Then SETNAM must be called to set the filename.

Finally you store the start address in 2 bytes of zero page memory, set X & Y to point to the address immediately after the data to save, and A to the offset within zeropage where the start address was stored.

Any errors are reported via the READST routine.

This routine scans the Commodore 64 keyboard and checks for pressed keys. It is the same routine called by the interrupt handler. If a key is down, its ASCII value is placed in the keyboard queue. This routine is called only if the normal IRQ interrupt is bypassed.

This routine returns the format of the screen, e.g., 40 columns in X and 25 lines in Y. The routine can be used to determine what machine a program is running on. This function has been implemented on the Commodore 64 to help upward compatibility of your programs.

This routine transmits a secondary address on the serial bus for a LISTEN device. The routine sends this number as a secondary address command over the serial bus. This routine can only be called after a call to the LISTEN routine. It will not work after a TALK.

This routine sets the logical file number, device address, and secondary address (command number) for other KERNAL routines.

The logical file number is used by the system as a key to the file table created by the OPEN file routine. Device addresses can range from 0 to 31. The following codes are used by the Commodore 64 to stand for the CBM devices listed below:

Device numbers 4 or greater automatically refer to devices on the serial bus.

A command to the device is sent as a secondary address on the serial bus after the device number is sent during the serial attention handshaking sequence. If no secondary address is to be sent, the Y index register should be set to 255.

This routine controls the printing of error and control messages by the KERNAL. Either print error messages or print control messages can be selected by setting the accumulator when the routine is called. FILE NOT FOUND is an example of an error message. PRESS PLAY ON CASSETTE is an example of a control message.

Bits 6 and 7 of this value determine where the message will come from.

If bit 7 is 1, one of the error messages from the KERNAL is printed.

If bit 6 is set, control messages are printed.

If this is set to 0 then all kernal messages are disabled.

This routine is used to set up the file name for the OPEN, SAVE, or LOAD routines.

The accumulator must be loaded with the length of the file name. The X and Y registers must be loaded with the address of the file name, in standard 6502 low-byte/high-byte format.

The address can be any valid memory address in the system where a string of characters for the file name is stored.

If no file name is desired, the accumulator must be set to 0, representing a zero file length. The X and Y registers can be set to any memory address in that case.

A system clock is maintained by an interrupt routine that updates the clock every 1/60th of a second (one "jiffy"). The clock is three bytes long, which gives it the capability to count up to 5,184,000 jiffies (24 hours). At that point the clock resets to zero.

Before calling this routine to set the clock, the accumulator must contain the most significant byte, the X index register the next most significant byte, and the Y index register the least significant byte of the initial time setting (in jiffies).

This routine sets the timeout flag for the IEEE bus. When the timeout flag is set, the Commodore 64 will wait for a device on the IEEE port for 64 milliseconds. If the device does not respond to the Commodore 64's Data Address Valid (DAV) signal within that time the Commodore 64 will recognize an error condition and leave the handshake sequence. When this routine is called when the accumulator contains a 0 in bit 7, timeouts are enabled. A 1 in bit 7 will disable the timeouts.

This routine checks for either the RUN/STOP key or certain other keys are pressed.

Check for RUN/STOP key pressed

If the key was pressed during a UDTIM call, this call returns the z flag set. In addition, the channels will be reset to default values.

In the above example if the STOP key is pressed we jump to the method stopDown. This method could reset your application, cancelling some lengthy operation.

Check for other keys

If the stop key is not pressed then the z flag will be clear and the accumulator will be set to one of the following keys located on the same keyboard column as the stop key:

If no key is down in the STOP column, the routine returns 0xFF on both machines.

To use this routine the accumulator must first be loaded with a device number between 0 and 31.

When called, this routine then ORs bit by bit to convert this device number to a talk address. Then this data is transmitted as a command on the serial bus.

If a secondary address is required then the TKSA routine must be called immediately after this one.

This routine transmits a secondary address on the serial bus for a TALK device. This routine must be called with a number between 0 and 31 in the accumulator. The routine sends this number as a secondary address command over the serial bus. This routine can only be called after a call to the TALK routine. It will not work after a LISTEN.

This routine updates the system clock. Normally this routine is called by the normal KERNAL interrupt routine every 1/60th of a second. If the user program processes its own interrupts this routine must be called to update the time. In addition, the <STOP> key routine must be called, if the <STOP> key is to remain functional.

This routine commands all devices on the serial bus to stop receiving data. Calling this routine results in an UNLISTEN command being transmitted on the serial bus. Only devices previously commanded to listen are affected. This routine is normally used after the Commodore 64 has finished sending data to external devices. Sending the UNLISTEN commands the listening devices to get off the serial bus, so it can be used for other purposes.

This routine commands all devices on the serial bus to stop sending data. Calling this routine results in an UNTALK command being transmitted on the serial bus. Only devices previously commanded to talk are affected.

This routine manages all system vector jump addresses stored in RAM.

Calling this routine with the the accumulator carry bit set stores the current contents of the RAM vectors in a list pointed to by the X and Y registers.

When this routine is called with the carry clear, the user list pointed to by the X and Y registers is transferred to the system RAM vectors.

The RAM vectors are listed in the memory map.