# 3. Commands

## 3.1 Syntax Conventions

The syntax for Chaprola commands is straightforward. Except for a statement number, a Chaprola verb must be the first word encountered in a line. The rest of the command must follow the syntax for that verb.

```
[Number] ::= A number, e.g. 25, 10.45, 1E7
[Text]   ::= An alphanumeric string, e.g. abcdefg, 4.x
[Ri]     ::= The R-variables of the Chaprola Language (R1--R50)
[Vi]     ::= A number or an R-variable
[Start]  ::= A number truncated to an integer, specifying a starting character position
[Length] ::= A number truncated to an integer, specifying the length of a character string
[SNi]    ::= A statement number between 1 and 1999
```

## 3.2 R-Variables

The R-variable is a set of fifty registers, initially set to 0, usable for calculations. The variables are the letter "R" followed by a number between 1 and 50 (e.g., R27). An R-variable's value can be changed at any time but can only contain a number. R-variables are 64-bit quantities.

## 3.3 Statement Numbers

Statement numbers are not necessary for execution or compilation. They are used as line markers for CALL or GOTO statements. Rules:
- Must be the first characters encountered in a line
- Must be followed by a valid Chaprola verb
- Each number can only be used once per program (no duplicates)
- Range: 1 to 1999

## 3.4 Comments

A comment starts with a blank space, a period, and then a blank space (` . `). Anything following the comment flag to the end of the line is ignored. A command cannot follow a comment on a line. Even comment-only lines are counted for error reporting.

## 3.5 Command Reference

### 3.5.1 CALL

```
CALL [Statement Number]
```

Jumps to a subroutine at the specified statement number. When RETURN is reached, execution resumes after the CALL. Up to nine CALLs can be nested without a RETURN, but there must be one RETURN for every CALL.

**Example:**
```
   CALL 100
   STOP
100 [Any Number of Commands]
   RETURN
```

### 3.5.2 DEBUG

```
DEBUG ON
DEBUG OFF
```

Aids in debugging by tracking R-variables. When DEBUG is ON, the debug file records the program line number, variable name, equals sign, and value in exponential form.

**Note:** For line numbers to appear in the debug output, CHAPCOMP must be run with an `x` in the third word position during compilation. This slows execution; recompile without the option once debugging is complete. Default status is OFF.

### 3.5.3 FIND

```
FIND [Rj] FROM [Start 1] [Length] USING [Start 2]
```

Searches through records in the secondary data file looking for a specific string of characters.

- `[Start 1]` -- location within the Secondary Data File being searched
- `[Length]` -- length of both strings (must be equal)
- `[Start 2]` -- reference string location (typically in the primary file)
- `[Rj]` -- receives the record number of the match

**Rules:**
- The secondary file must be sorted on the field being searched.
- Strings must be identical for a match.
- The computer does not necessarily find the first match in chronological order.

**Example:**
```
FIND R20 FROM -25 10 USING 15
```

### 3.5.4 GET

```
GET [Rj] FROM [Starting Location] [Length]
```

Retrieves numerical data from a memory location into an R-variable. The location must contain only blanks or a valid number; an error occurs otherwise. GET is optimized as a single-cycle operation.

**Example:**
```
GET R7 FROM 26 6
```

### 3.5.5 GOTO

```
GOTO [Statement Number]
```

Transfers execution to the specified statement number. Everything between the GOTO and the target is skipped.

**Example:**
```
GOTO 17
```

### 3.5.6 IF

```
IF [condition] [command(s)] ;
```

Compares values and conditionally executes commands. The IF statement is terminated by a semicolon (`;`). There must always be a space before the semicolon.

#### Numeric Comparisons

```
IF [Vi] [operator] [Vj] [command(s)] ;
```

Operators: `LT` (less than), `GT` (greater than), `LE` (less or equal), `GE` (greater or equal), `EQ` (equal), `NE` (not equal).

#### IF LEGAL

```
IF LEGAL [Start] [Length] [command(s)] ;
```

Tests if a character string is a valid number. If legal, the commands execute; otherwise, execution skips to the next semicolon.

**Example:**
```
IF LEGAL 20 7 GET R27 FROM 20 7 ;
```

#### IF BLANK / IF NOT BLANK

```
IF BLANK [Start] [Length] [command(s)] ;
IF NOT BLANK [Start] [Length] [command(s)] ;
```

Tests if a field is empty (all blanks) or contains any character.

**Examples:**
```
IF BLANK 100 25 GOTO 100 ;
IF NOT BLANK 26 1 MOVE "7    1SCRATCH SCRATCH SCRATCH " 6023 32 ;
```

#### IF EQUAL

```
IF EQUAL [Start 1] [Start 2] [Length] [command(s)] ;
IF EQUAL "[text]" [Start] [Length] [command(s)] ;
```

Compares two character strings. Strings must be exactly identical for a match.

**Examples:**
```
IF EQUAL 25 -50 25 WRITE 32000 ;
IF EQUAL "F" 26 1 GOTO 1200 ;
```

#### IF FOERR

```
IF FOERR [command(s)] ;
```

Tests the file-open error flag, set when OPEN encounters a problem.

**Example:**
```
IF FOERR RETURN ;
```

#### IF EOF

```
IF EOF [command(s)] ;
```

Tests the end-of-file flag, set when a READ encounters no such record or reaches the end of the file.

**Example:**
```
IF EOF GOTO 120 ;
```

### 3.5.7 INSERT

```
INSERT [Character Value] [Start]
```

Inserts an ASCII character (1--255) at a memory location. Takes one character position.

Common codes:
- 10 -- Line Feed
- 12 -- Form Feed
- 13 -- Return

**Example:**
```
INSERT 12 5079
PRINT 0 1
```

### 3.5.8 LET

```
LET [Rj] = [Vi] [operator] [Vk]
```

Assigns a value or performs one arithmetic operation. Operators: `+`, `-`, `*`, `/`.

Complex expressions must be broken into a series of single-operation LET statements.

**Examples:**
```
LET R12 = 6.25
LET R12 = 0.625E+1
LET R16 = R12 * 4.0

. Complex: (R3*(R1-R2)/R4)+R5 stored in R6
LET R7 = R1 - R2
LET R8 = R3 * R7
LET R9 = R8 / R4
LET R6 = R9 + R5
```

### 3.5.9 MOVE

#### Memory-to-Memory

```
MOVE [Start 1] [Start 2] [Length]
```

Copies `[Length]` characters from `[Start 1]` to `[Start 2]`. All four memory areas are accessible. `[Start 1]` may be an R-variable holding a position.

**Examples:**
```
MOVE 12 -30 8
MOVE R3 5001 20
```

#### Literal String to Memory

```
MOVE "[text]" [Start] [Length]
```

**Examples:**
```
MOVE "7" 6023 1
MOVE "TESTFILETESTFILETESTFILE" 6031 24
```

#### MOVE BLANKS

```
MOVE BLANKS [Start] [Length]
```

Fills a memory region with blank characters.

**Examples:**
```
MOVE BLANKS 48 1
MOVE BLANKS 1 48
```

#### Menu Generation Pattern

The following combined MOVE sets IVAL to 7, record to 1, and changes all three files:
```
MOVE "7    1TESTFILETESTFILETESTFILE" 6023 32
```

### 3.5.10 OPEN

```
OPEN "[Filename]" [Length]
```

Opens a Secondary Data File. The file must already be defined and must have a fixed record length specified by `[Length]`. If the length is unknown, set to 0 (the computer determines the length, but this is slower).

**Special operations:**
- `OPEN "+[filename]" [length]` -- defines (creates) a new file
- `OPEN "-[filename]" [length]` -- deletes a file

If a file opening error occurs, FOERR is set to true.

**Examples:**
```
OPEN "TESTFILE" 0
OPEN "TESTFILE" 96
```

### 3.5.11 PRINT

```
PRINT 0 [Length]
PRINT 1 [Length]
PRINT 2 [Length]
```

- **PRINT 0** -- Takes information from location 5001 for `[Length]` characters and places it in the print file. A line feed is appended.
- **PRINT 1** -- Prints to the operator's console and waits for a keystroke. Break key terminates the program; any other key continues. *CHAPRPG only.*
- **PRINT 2** -- Prints to console and waits for a line of input (up to 80 characters) from the keyboard, which overwrites location 5001. *CHAPRPG only.*

### 3.5.12 PUT

```
PUT [Rj] INTO [Start] [Length] [Format] [Digits]
```

Places an R-variable value into a memory location as a formatted character string.

**Format codes:**

| Code | Name | Description | Example (R3 = 4673.224) |
|------|------|-------------|------------------------|
| `D` | Dollar | Dollar sign, commas, decimal point | `$4,673.22` |
| `F` | Floating | Fixed-point decimal | `4673.224` |
| `I` | Integer | Integer (0 in Digits) or scientific notation (>0 in Digits) | `4673` or `4.67E+3` |
| `E` | Exponential | Scientific notation | `1.2575E+02` |

The `I` format with `[Digits]` = 0 gives an integer with leading blanks. With `[Digits]` = 1, the number is preceded with leading zeros. With `[Digits]` = 2 or more, the output is in scientific notation.

**Examples:**
```
PUT R3 INTO 5028 9 D 2     . $4,673.22
PUT R3 INTO 1019 9 F 3     . 4673.224
PUT R3 INTO -305 9 I 0     . 4673
PUT R3 INTO 200 9 I 2      . 4.67E+3
```

### 3.5.13 READ

```
READ [Record Number]
READ [R-variable]
```

Reads a record from the Secondary Data File into the secondary memory area. The secondary file must be open. The record number may be a literal or an R-variable.

**Examples:**
```
READ 7
READ R6
```

### 3.5.14 RETURN

```
RETURN
```

Returns execution to the line following the most recent CALL.

### 3.5.15 STOP

```
STOP
```

Designates the end of the program. Useful for separating the main program from subroutines accessed via CALL.

### 3.5.16 WRITE

```
WRITE [Record Number]
WRITE [R-variable]
WRITE 32000
```

Writes the secondary memory area to the Secondary Data File. To append a new record to the end of the file, use a record number larger than the actual number of records (maximum file size is 32,000 records; using `WRITE 32000` appends to the end).

**Examples:**
```
WRITE 32000
WRITE R7
WRITE 38
```

## 3.6 Command Summary

| Command | Description |
|---------|-------------|
| `CALL` | Jump to subroutine (up to 9 levels deep) |
| `DEBUG` | Toggle R-variable debugging ON/OFF |
| `FIND` | Search secondary file for matching record |
| `GET` | Read number from memory into R-variable |
| `GOTO` | Jump to statement number |
| `IF` | Conditional execution (LT/GT/LE/GE/EQ/NE, LEGAL, BLANK, NOT BLANK, EQUAL, FOERR, EOF) |
| `INSERT` | Insert ASCII character at memory location |
| `LET` | Assign or compute R-variable values |
| `MOVE` | Copy characters between memory locations |
| `MOVE BLANKS` | Fill memory with blanks |
| `OPEN` | Open/create/delete secondary data file |
| `PRINT` | Send user buffer to print file or console |
| `PUT` | Format R-variable to memory (D/F/I/E) |
| `READ` | Read record from secondary file |
| `RETURN` | Return from CALL |
| `STOP` | End program |
| `WRITE` | Write secondary memory to file |

---

*Previous: [Memory Model](02-memory-model.md) | Next: [Bytecodes](04-bytecodes.md)*