Color 64 BBS Wiki

Undocumented 8.1 commands

Revision as of 16:24, 23 February 2026 by Admin (talk | contribs)

At the time of this revision for Color 64 v8.1a, there are notably several ML related commands and variables that are not documented from the original 8.0 manuscript, as well as some basic shortcuts and appear to have been introduced from the 8.1 upgrade. A lot of reverse engineering was done by comparing 8.1 code to the predecessor versions.

Below are some of my notes and observations of what the code was in 8.0 or 7.37, and the observed shortcuts implemented in 8.1.

Please note it is a work-in-progress and this part of the wiki gets updated frequently! Some of my observations may still be without conclusion as they are under active investigation! That said, getting to understand some of the modified BASIC can be easy. If you have the ML loaded into your system (loading and running +SHELL), you can write your own program to test out the modified BASIC by having your first line call the ML routine: SYS49923 

10 SYS49923
20 #"Test of program"
30 etc....

Topics:

General Programming

Topic Notes
Simple Addition All overlays

Color 64 allows simple addition without using < var >=< same var >+< value >

So a=a+12 can alternately just be: a+12. This only works with numbers (not strings) and success with this has not been consistent. Use with caution.

Topic Notes
Branch Shortcuts All Main Overlays
Example 8.0 8.1
1
2
3
4

Conclusion: “[“ and “@” are used for loops with “[“ being the starting position and “@” being the condition that will cause the function to return to the starting point of the loop. Also note in line 8220 how the “RETURN” statement moved from line 8230 up into the 8220 loop in version 8.1 (example 2), indicating that it will execute the return if a$ <> “” and a$ <> home key.

[ starts loop (the anchor)
@ loop condition – goes back to the last anchor
@[x] jump back if x is non-zero
“]” is the Color 64 BASIC conditional action delimiter: it separates an IF test from the statement list executed when the test is true.

This is heavily used with status:

  • @[SR] means: if SR<>0 then jump back to the last [ anchor.
  • If SR is 0, it falls through and the loop ends naturally.

So you will see in numerous places:

  1. do read / set SR=ST
  2. @[SR] to continue while status says “keep going”
Topic Notes
"THEN" with IF All Main Overlays
8.0 8.1

Conclusion: “then” statements are not required for “if/then” – if <condition> <action> is legal in most cases.

Topic Notes
if...£ √bbs.msgs
Example 8.0 8.1
1

Observation: Observe the 8.1 authors reversed the checks in variable comparisons as the conditions, with end-result being the same.

Conclusion: Serves as an “not” function “(lv is not less than cm%(2,2) and lv not less than cm%(29,2) and fr does not equal 1, then print (P)rivate)”

Another example:


Topic Notes
@ √bbs.msgs
Example 8.0 8.1
1

Conclusion: Seems to serve as an “if” keyword - but testing this theory in a traditional sense resulted in a syntax error.

Topic Notes
[var$] √bbs.msgs
Example 8.0 8.1
1

Conclusion: Can serve as an empty variable check (null)

ML Commands

Topic Notes
.8 All Main Overlays

.8 - Session/Input Poll)

Previously documented in 8.0 documentation as "Equivalent of the "%" command…", this appears to be rewritten in version 8.1 - and is particularly noticeable in bbs.msgs where comparing the two show that .8 has replaced the gosub110 routine (which in 7.37 called sysc(4) or in 8.0, .00.

7.37 8.1

and routine at 110....

No use of routine at 110...

Polls for typed input (non-blocking, local or remote), normalizes transient input-status states, and refreshes session status. Typically used inside scrolling output/file display loops and before slow operations. Side effects include updating P (0 OK, 1 user abort, 255 carrier lost/timeout) and possibly the same underlying status/character registers used by .00.

While further testing is required, theoretically this should fully replace use of gosub110

Topic Notes
.9 All Main Overlays

Previously documented in 8.0 documentation as a "do not use" command that replaces "&" function, this appears to be repurposed for single key command input replacing the traditional "gosub110" routine.

.9 – Single-Key Command Input Poll

Overview

The .9 command polls for a single keypress and stores the result into the BASIC string variable A$. It is used at the command prompt to capture one-character command input from either the local keyboard or remote modem connection.

Previous iterations of Color 64 used gosub110 in the same areas.

When a key is pressed:

  • A$ is set to the key pressed
  • The character is stored in high-bit PETSCII format
  • Example:
    • Pressing "X" → ASC(A$)=216
    • Pressing "O" → ASC(A$)=207
(Standard ASCII value + 128)

When no key is pressed:

  • A$="" (empty string)
  • The command does not block execution

Examples (bbs.msgs):

Bare Poll 
110 .9:RETURN
995 .9:IF A$<>NU$ OR P=1 THEN 995:RETURN (loop until a key appears or abort)
Filtered Keys 
1020 .9,"YN":RETURN (only accept Y/N)
3715 .9,"12345"+CR$:IF P ... (menu choices plus Enter)
Space-as-abort convention 
9132 .9:IF A$=" " THEN P=1
(and several more spots do the same)

So .9 is essentially the modern ML command that replaced the old sysc(4) “get typed character” behavior, with a nice extra: it can be told “only accept these characters”.

Topic Notes
.31 and !55 √bbs.msgs
Example 8.0 8.1
1

Conclusion: .31 – Message-Aware Disk Input (Version 8.1)

Earlier documentation listed the ML command .31 as "not used." Analysis of Version 8.1 confirms this is incorrect. In Color 64 v8.1, the .31 command is actively used within message-handling overlays (notably BBS.MSGS) and functions as a specialized form of disk input. It replaces the earlier .01 disk input command used in Version 8.0 when scanning and reading private messages.

Comparison: Version 8.0 vs Version 8.1

8.0 8.1
Message scanning used: .01

After each read, BASIC code manually checked for a message delimiter: IF @0 = CHR$(14) THEN .... The byte {0E} (CHR$(14)) acted as the message record separator. When this character was encountered, the system incremented or decremented message counters, control flow moved to the next message record, and the loop continued scanning until completion. The delimiter (end of message) detection was handled explicitly in BASIC.

In Version 8.1, .01 is replaced in message routines by: .31.

The .31 command performs the disk input operation and internally detects the message delimiter. Instead of BASIC checking @0 = CHR$(14), Version 8.1 uses the ML variable IF !55 THEN .... When !55 becomes non-zero, the system has reached the end of the current message record, message counters are updated, and control moves to the next message or exits the loop. Delimiter detection is now handled inside the ML routine rather than in BASIC.

!55 – Message Record Delimiter Flag !55 is an ML variable introduced in Version 8.1 that serves as a message record boundary flag. It is set automatically by .31 when the message delimiter byte (previously tested as CHR$(14) in Version 8.0) is encountered.

!55 = 0 → No delimiter encountered
!55 ≠ 0 → End of message record reached

When !55 is detected:

  • The current message scan loop updates counters
  • The system transitions to the next message record
  • Display or processing routines advance accordingly

Topic Notes
.36 √bbs.init
Example 8.0 8.1
1

.36 – Prompt-Cycle Housekeeping (Behavior Unconfirmed)

Category: ML Command Seen in: All Main Overlays (prompt printing routine)

Overview

The .36 command is called immediately after printing the command prompt and just before entering the main command input polling loop (.9).

In testing within the live BBS environment, removing .36 did not alter normal command prompt behavior, local keyboard input, or remote input handling. This suggests .36 is either redundant in v8.1, reserved for edge cases, or included for compatibility with earlier ML builds.

Observed Call Pattern

  • Prompt is printed (PETSCII-dependent)
  • .36 executes unconditionally
  • Return into the .9 command polling loop

Testing Notes

  • With .36 present:
    • Pressing a command key results in A$ being set to high-bit PETSCII
    • P variable functions normal (remains 0) at command prompt operations
  • With .36 removed:
    • No visible change under normal BBS operation
    • .9 functioned normally.

Working Hypothesis

.36 likely performs a defensive reset of internal prompt/input state (e.g., clearing a latch, normalizing editor mode, or handling rare typeahead / carrier-transition conditions). No definitive functional effect has been confirmed under standard test conditions.

Summary

.36 is executed as part of the prompt cycle in v8.1 but does not appear necessary for normal command entry. Further testing under stress conditions (typeahead flooding, carrier transitions, mode switching) may reveal its purpose.

Topic Notes
.38 / .39 / .40 / .41 and “;” variables √bbs.msgs
Example 8.0 8.1
1 (current message vs high message):
(current message vs high message):
2 (reading message):
(reading message):
3 (storing message):
(storing message):

Message Relink Commands in v8.1

Command Purpose
.38 Initialize / bind relink iterator operands
.39 Perform iterator scan step
.40 Advance iterator (skip / continue)
.41 Finalize relink process

.38 – Relink Iterator Initialization (v8.1)

The .38 command was introduced in Color64 v8.1 as part of the internal message relinking system and is the entry point of the entire process. It does not perform file I/O directly and does not read or write messages itself. Instead, it initializes and binds internal machine-language structures used by the message relinking iterator.

It is designed to be used as the first step in a command sequence:

.38 → .39 → .40 / .41

This sequence replaces the more BASIC-driven record scanning logic found in v8.0.

What .38 Does

  • Binds specific BASIC variables/arrays to ML-side descriptors
  • Registers operands for the relink iterator
  • Initializes scratch registers used by subsequent .39 operations
  • Prepares the ML environment for scanning and linking old message records

In BBS.MSGS, this binding typically associates:

Slot 0 → MN (message number)
Slot 1 → MR% (message read flags array)

The ML iterator then uses internal scratch registers such as:

;0K
;1K
;0F

These are later examined by BASIC to determine loop control and branching.

In v8.0, message scanning and linking logic was performed directly in BASIC, including character comparisons and explicit loop control.

In v8.1, this logic was moved into machine language for speed and structural cleanliness. BASIC now acts primarily as a decision layer while ML handles the iteration mechanics.

Important Notes

  • .38 must precede .39 in relink routines
  • .38 does not itself advance or scan records
  • It prepares the ML environment used by the iterator
  • It is not a general-purpose file command
  • It is specific to the message relinking system

Summary

The .38 command initializes the v8.1 message relink iterator by binding BASIC variables to ML-side structures. It marks the transition from the BASIC-driven record scanning model of v8.0 to the ML-driven iterator model of v8.1.

It should be understood as a setup command rather than an action command.

ML Variables

Topic Notes
!8 Wrap/Width Threshold

The !8 was originally documented in 8.0 "reserved for future use" but is now utilized in some sections where it is used to check if a string is less then the value of !8 and decides how to print the string based on that check.

Example: if len(a$)<!8 then #:£$

In the example above, if a line is shorter than !8, they force an explicit newline behavior; if it’s longer, they let natural wrapping do the work.

Topic Notes
!46 Scratch Register

The !46 was originally documented in 8.0 as being unused; however the 8.1 version has disk operations using this in all overlays at the disk routine lines 710-740 as well as the log routine lines 8003-8040.

In those routines, !46 holds a temporary value (lines 710 save a disk channel number while the lines at 8000 use it to store a variable value temporarily)


Topic Notes
!55 !55 – Message Record Delimiter Flag

Refer to .31 command above.

Topic Notes
!56 !56 - Message Editor Command State (True/False) (Editor)

Used in conjunction with !57 and !60, when true this monitors for !57 to invoke a command state.

See !57 and !60 for more information.

Topic Notes
!57 !57 - Prefix Trigger Assignment (Editor)

This works in concert with !56 and !60 for the message editor commands. In the unmodified code of 8.1, the prefix trigger assignment is 47 (equates to "/") that makes that our command while in the message editor to trigger a command when !56 is true. The command value is stored in !60.

See !56 and !60 for more information.

Topic Notes
!58 !58 - ?? (Editor)

Present in editor functions - specifically during text entry (after hitting RETURN on a line), but overall function / use of this ML variable is unknown. Only resides in bbs.msgs at a subroutine starting at line 310.

Topic Notes
!59 !59 - Text-entry mode flag (Editor)

Present in editor functions - this is set as high by ML routines while in text entry to bypass any code dealing with command menu.

Topic Notes
!60 !60 - Menu Selection Holder (Editor)

Overview

In Color 64 v8.1, !60 acts as a state variable for the message editor command interface. It is used to control (and dispatch) the editor's slash-command / CMD> menu behavior, and it appears to be treated as a small integer "mode / selection" value.

This logic does not exist in the v8.0 editor flow, indicating it was introduced or substantially expanded in v8.1.

Observed behavior in bbs.msgs (v8.1)

The editor command prompt section sets up a list of command keywords, reads user input, and then stores the selected command number into !60. Later code uses ON !60 GOTO to jump to the appropriate command handler.

Key excerpt (v8.1, around 2930–2939): 

 2931 !60,.:II$="divider,rap,elete,dit,end,merge":&"...CMD> ..."
 2932 [.9,I$: ... :IF!60THEN&@3(DE$,LG)
 2933 ... ]2935:\!60,II: ...  (stores selection into !60)
 2936 IFII<11 !60,.:!56,-(II=9):!57,47
 2937 I$="":II$="":RETURN

Important notes:

  • !60,. is used to clear/reset the state (set to 0).
  • \!60,II stores the selected menu item index (II) into !60.
  • The prompt offers 6 commands: divider, wrap, delete, edit, end, merge.

Dispatcher usage

v8.1 uses !60 as the selector in a computed jump: 

 1302 ON!60 GOTO 1314,1305,1306,1365,1310,1312:!60,1:@

This strongly indicates:

  • !60 holds a value in the range 1–6 to represent the selected command.
  • After the command handler runs, code commonly resets !60 back to 1 (default state).

Based on the command list order (from line 2931), the implied mapping is:

!60 Value Command Notes
1 DIVIDER Insert or manage message divider
2 WRAP Wordwrap toggle/behavior
3 DELETE Delete operation (line/section)
4 EDIT Edit operation
5 END End editor / finish
6 MERGE Merge behavior (message/text merge)

Slash-command prefix interaction ("/")

!60 is also used as a boolean-style flag to enable slash-style command entry behavior. One observed usage: 

 311 II=GO(!60,47,.)

Where:

  • 47 is ASCII "/" (slash).
  • This suggests that when !60 is "active" (non-zero), "/" is used as the command-prefix character used by the editor logic.

This supports the interpretation that !60 is not merely a one-shot selection, but the editor command mode state that can be:

  • cleared (0) while collecting/editing input or performing screen cleanup, and
  • set (1..6) when a command has been selected and needs to be dispatched.

Additional references in the editor flow

Line 1300 demonstrates !60 being initialized prior to the editor loop and used with other state variables: 

 1300 !7,FM:A=I:!60,1:[GOSUB311:IFP]...

Line 2885/2888 show the same "set !60, then dispatch, then reset" pattern: 

 2885 ... :!60,1:[GOSUB311:IFP]...
 2888 ON!60 GOTO 2890,1305,2889,2895:!60,1:@

Working conclusion

In Color 64 v8.1, !60 is a message editor command state / selector variable:

  • It enables slash-command style operation ("/" prefix) when active.
  • It holds the selected editor command index (1..6).
  • It is used in ON-GOTO dispatch tables to jump to the correct handler.
  • It is frequently reset back to 1 after a handler executes.

Open questions

  • Whether !60 is also modified by the .9 input routine (or other ML routines) to signal screen-edit cleanup (e.g., controlling the delete-echo behavior at 2932).
  • Whether !60 has additional meanings beyond editor-related command selection.

This is also used in conjunction with !56 and !57.

ML Functions

Topic Notes
@31 @31 – Sequential Read (Enhanced)

Overview: @31 is a machine language function introduced in later Color 64 versions that replaces the older @5 + !40 sequential line-read pattern of version 8.0. It retrieves the next logical record from an open sequential file and updates ST as a side effect.

Higher-Level Replacement for @5

  • Encapsulates record retrieval and length handling internally.
  • Reduces BASIC-level string churn.
  • Improves performance and garbage-collection stability.

It is used prominently in merge message routines within BBS.MSGS.

Behavior:

  • Returns a string (typically assigned to I$)
  • Updates ST (disk/file status)
  • Designed for use inside ST-controlled loops
  • Commonly paired with @9 (enhanced FRE) for memory safety


Example Usage (v8.1a): 

2330 T=@9:[I$=@31:II=ST:GOSUB2400
2335 T=T-LEN(I$):A$(A)=I$:A+:@[II] AND A<ML+4 AND T>=CM%(7,.):GOTO505


Functional Characteristics:

1) Sequential File Read

  • Retrieves the next record/line from the currently open sequential file.
  • Replaces the older @5 + !40 logic.
  • ST must be checked after each call.

2) Status-Driven Looping

Typical pattern:
I$=@31
II=ST
@[II]
Loop continues while ST indicates valid read.

Frequently paired with the enhanced FRE function @9 and number of max lines in message CM%(7,.) as it is used in the merge message function of bbs.msgs starting at line 2330.

In comparison:

8.0 8.1
2330 i$=@5:if!40<len(tx$)theni$=i$+cr$ 2330 t=@9:[i$=@31:ii=st:gosub2400

Notes:

  • @31 is not a pure function.
    • Requires an open file context.
    • Updates ST.
    • Should be used within the BBS runtime environment.

Conclusion:

@31 is an enhanced sequential-record read function used primarily in message handling and merge routines. It streamlines record retrieval, updates ST for loop control, and is typically combined with @9-based memory budgeting safeguards.

Topic Notes
@32 @32(2,2) – Return Block Count

The @32 ML function is used with an open directory listing (the "$" directory stream) to read and parse a directory entry. It returns a numeric value and advances the internal "current directory entry" pointer so subsequent calls read the next entry.

In Color 64 v8.1, @32 is commonly used as a fast replacement for the older BASIC parsing method where a program would GET# fields from a "$" listing and use @6(low$,high$) to build a 16-bit value. In practice, @32 is used to obtain the directory entry's block count (file size in blocks) as an integer.

Syntax: A = @32(2,2)

Return Value: Returns the current/next directory entry's block count (file size in blocks) as an integer.

Status / End-of-List Behavior: @32 works as an iterator over directory entries. When there are no more matching entries (end of directory stream), BASIC's ST is set. Code typically tests ST immediately after calling @32.

Typical pattern: 

 A = @32(2,2)
 IF ST THEN ...   :rem end of directory (or no match)

Common Usage Patterns

1) Check if a file exists (or get its size) - Open a filtered directory listing and attempt to read the first match. - If ST is set after the call, the file was not found. 

 OPEN 8,DV,8,"$"+DR$+F$+"*"
 GOSUB 770          :rem read/skip directory header (implementation-specific)
 A = @32(2,2)
 IF ST THEN ER=62:A$="NOT IN DIRECTORY: "+F$:GOTO <error handler>

2) Display a directory-style listing (blocks + filename) - Call @32 repeatedly until ST is set. - The returned value is typically printed as the "blocks" column. - The filename is commonly retrieved via @5 after each call (since @32 updates the current entry). 

 B=-3
 B=B+1
 C=@32(2,2)
 IF ST THEN PRINT B;" FILES SELECTED":RETURN
 PRINT C;TAB(6);@5

3) Maintenance checks based on file size (example: caller log trimming) - Compare @32's returned block count against a configured maximum. - Also used in free-space safety checks to avoid dropping below MU (minimum blocks required for uploads). 

 F$="✓CALLER LOG":GOSUB 710
 P=A-CM%(8,.)
 P=-P*(P>.)
 :rem P is positive only when the file exceeds the configured limit

Notes

  • @32(2,2) is always used in conjunction with an open "$" directory stream. The parameters (2,2) are used in v8.1 code for directory entry parsing; other parameter combinations (if any) are currently undocumented and not used.
  • @32 is generally paired with other ML functions that return fields for the "current directory entry" (commonly @5 for filename). @32 updates that "current entry" context each time it is called.

8.0 Comparison

Version Typical Technique Result
8.0 Parse "$" listing using GET# and build a 16-bit value using @6(low$,high$) File block count as an integer
8.1 Read/parse directory entry directly using @32(2,2) File block count as an integer (faster, no manual GET# parsing)

Topic Notes
@33 @33 - Return Chr$(0) Null

The @33 is used exclusively in the editor portion of message composure and appears a function of when the user is utilizing the "/" command within the editor where @33 is part of the removal of the prompt from the editing screen. It returns a string length of 1 with a chr$(0).

There is no comparative code from earlier versions of Color 64.

Retrieved from "https://www.color64wiki.itchybutt.org/index.php?title=Undocumented_8.1_commands&oldid=845"