READING AN ERROR REPORT

Everybody’s programs go wrong, and the first programs go wrong the most. When satellite cannot run something, it never guesses and never goes quiet. It stops and prints a SATELLITE CRITICAL ERROR REPORT that says what happened, where, and usually what to do about it. Learning to read one takes a minute and saves hours.

The parts of a report

Here is a small mistake: the program uses pears but never declared it.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number apples = 3
    satellite.console.display(apples + pears)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S201: NAME_NOT_DECLARED
satl(check): in satellite.main, pears has no satellite.variable line declaring
it

directory: fruit.satl:6
syntax: satellite.console.display(apples + pears)
        /\

this name was used and no satellite.variable line ever declared it. A name has
to be given a type before it can hold anything.
machine code 25 name_not_declared -- satl exits with this.

--------------------------------------------------------------------------------

Read it from the top:

1. The S-code and its name, S201: NAME_NOT_DECLARED. The code is short to search for, and the name says it in words.
2. What happened, in this program. It starts with where satl was when it noticed. satl(check) means satl found the problem while checking the whole program, before a single line ran. satl(run) means it happened while the program was running. satl.file(check) is about the file as a whole.
3. directory: is the file and the line number: line 6 of fruit.satl.
4. syntax: is that line, exactly as you wrote it, with a caret /\ under the place the problem was found.
5. A paragraph explaining that kind of problem in general.
6. The machine code, here 25. This is the exit status satl hands back to your shell.

The report goes to standard error, so it never mixes into the output you save from a program.

Checked first, or found while running

Most mistakes are caught by the check, before anything runs. Some can only be found while running, because they depend on values. Dividing by a number that turns out to be zero is one:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.number people = 4
    satellite.console.display(10 / people)
    satellite.variable.number nobody = people - 4
    satellite.console.display(10 / nobody)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S401: DIVISION_BY_ZERO
satl(run): the / of 10 and 0 is a division by zero

directory: halves.satl:8
syntax: satellite.console.display(10 / nobody)
                                     /\

a divisor worked out to 0. There is no number this could answer, so it answers
nothing rather than something.
machine code 22 division_by_zero -- satl exits with this.

--------------------------------------------------------------------------------

This one says satl(run), and the caret points at the / itself. Line 6 had already run, so its answer was printed before the report. A report from the check means nothing ran at all.

When the whole file is wrong

A few reports are about the shape of the file rather than one line. Every program needs three things: satellite.include(satellite) at the top, a satellite.main capsule, and satellite.return(satellite). Leave one out and there is no line to point at, so the report has no caret. Instead, it shows you what to type:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.console.display("hello")
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S103: FILE_HAS_NO_RETURN
satl.file(check): this file has no satellite.return -- execution ends inside
main

directory: forgetful.satl

execution ends inside main, and main has to say so. Add this as main's last
line, just before its closing }:

    satellite.return(satellite)
machine code 12 satl_file_missing_satellite_return_satellite -- satl exits with
this.

--------------------------------------------------------------------------------

What the number tells you

The hundreds digit of an S-code says what kind of trouble it is, and the numbers climb with how serious it is:

• S1xx: something simple, like a missing line, a typo in a word, or text that is not a number.
• S2xx: a name, such as one never declared, declared twice, or a word not built yet.
• S3xx: two kinds of value that do not go together.
• S4xx: arithmetic and positions, like dividing by zero.
• S5xx: files and folders.
• S6xx: settings.
• S7xx: the machine, threads and windows.
• S8xx: something from outside the program, like Ctrl-C or input that ran out.
• S9xx: satl itself is in trouble. S999, the top of the scale, means the machine would not give satl any memory.

Not everything stops a program. A notice is a single line starting [satellite], and the run carries on.

The exit status

When satl stops, its exit status is the machine code from the report, and 0 means the program ran to the end. Scripts can check it. Here the report is sent away with 2> /dev/null, so only the status shows:

satl fruit.satl 2> /dev/null
echo $?

25

A code below 0 or above 254 exits as 255, and the full number is written on standard error. Ctrl-C exits 130, as it does for other programs.

The common ones

• S101, S102, S103 (exits 10, 11, 12): the file has no satellite.include(satellite), no satellite.main, or no satellite.return(satellite).
• S110 LINE_NOT_UNDERSTOOD (13): satellite has no meaning for the line. Look for a misspelled word, like dispaly, or the wrong number of arguments.
• S120 NUMBER_NOT_READ (3): .number was asked of text that is not a whole number.
• S201 NAME_NOT_DECLARED (25) and S202 NAME_DECLARED_TWICE (26): a name used with no declaration, or declared twice in one capsule.
• S210 NOT_BUILT_YET (14): the word is real, but what it asks for is not built yet.
• S301 TYPES_DO_NOT_MEET (27): two kinds of value that do not go together, like "n = " + n with a number n. Write the conversion out: n.to_string().
• S401 DIVISION_BY_ZERO (22).
• S501 LINE_PAST_THE_END (47) and S503 FILE_NOT_OPEN (45): see FILES.
• S730 NO_DISPLAY (50): a window was asked for on a machine with no screen.
• S810 INTERRUPTED (130): you pressed Ctrl-C.
• S830 INPUT_ENDED (55): the program asked for input and there was none left.

Where next

The FULL REFERENCE lists every word, so a report’s word can be looked up there. Your first reports will probably come from YOUR FIRST SATELLITE PROGRAM, and the satl command’s own options are in THE SATL COMMAND.