Reading Line Input

Introduction

Previously, you learned how to capture a single key press. That was an important first step, but most real programs need to read more than one character at a time. They need to accept full words, commands, or even sentences typed by the user.

In this lesson, you’ll learn how to read a complete line of text from the keyboard, store it in memory, and process it. This forms the foundation for building menus, command interfaces, text parsers, and text-driven games.

How Line Input Works

When the user types on the keyboard, each character is converted into an ASCII code by the system. We could read these one at a time, but that would quickly become complicated. Instead, we can use a built-in system routine that does all the work for us:

• MCAL 157 – ZGETLIN
  Waits for the user to type a line of text and press ENTER.
  • It stores the characters in memory, starting at the address you provide in register pair DE.
  • It automatically echoes what the user types to the screen.
  • It finishes by writing a 0 byte to mark the end of the text.

With this routine, your program doesn’t need to worry about individual key presses — it simply waits until the line is complete and then works with the result.

Step-by-Step: Reading and Echoing a Line

The program below shows the simplest possible example of reading a line of input and printing it back to the screen. Every part of it is essential, but nothing more.

       ORG 256

start:
       ; --- Read input line into buffer ---
       LD DE, input_buffer
       RST 8
       DEFB 157            ; Call ZGETLIN - read a line of text into buffer

       ; --- Print the line back ---
       LD HL, input_buffer ; HL points to start of text

echo_loop:
       LD A, (HL)          ; Load next character
       CP 0                ; End of string?
       JP Z, done          ; If null terminator, stop
       RST 8
       DEFB 158            ; Print the character
       INC HL              ; Move to next character
       JP echo_loop        ; Repeat

done:
       JP start            ; Go back and do it again

; --- Reserve input buffer ---
input_buffer:
       DEFS 64             ; 64-byte buffer for user input


Walkthrough

1. Reserve a Buffer
   The program needs a block of memory to store the typed text. We create one with DEFS 64, which reserves 64 bytes.
2. Read the Input
   • Load the address of the buffer into DE.
   • Call ZGETLIN using RST 8 / DEFB 157.
   • The system waits for the user to press ENTER and stores their text in the buffer.
3. Echo the Text
   • HL is set to point at the start of the buffer.
   • The program reads one character at a time.
   • If the character is 0, that marks the end of the string and the loop stops.
   • Otherwise, it prints the character and moves to the next one.
4. Repeat
   • After printing, the program jumps back to start and waits for new input.

Key Points to Understand

• Buffer Size Matters: Always reserve enough memory for the longest input you expect. If the user types more characters than the buffer can hold, the extra text will overwrite memory beyond the buffer.
• Null Terminator: The 0 byte at the end of the text tells your program where the string stops.
• Automatic Echo: ZGETLIN automatically displays characters as the user types them. You don’t need to write separate code for this.

Exercises

Exercise 9.1 — Simple Echo

Modify the program so that it prints a message like You typed: before echoing the text.

Exercise 9.2 — Input Length

Change the program so that instead of echoing the text, it counts the number of characters typed and prints the total.

Exercise 9.3 — Basic Check

Write a version of the program that prints HELLO only if the user types the word HELLO, and prints UNKNOWN COMMAND otherwise.

Summary

• ZGETLIN (MCAL 157) reads a complete line of text and stores it in memory.
• The text is null-terminated, meaning a 0 byte marks the end.
• You can easily process the text by reading characters from memory until you reach that terminator.
• This approach is ideal for building command input, text interfaces, and interactive games.

With this knowledge, your programs can now handle full words and phrases — a crucial capability for building command-driven systems or text-based adventures.

‍