ML Variables

From Color 64 BBS Wiki

Programming Features - ML Variables

The ML Variables provide an interface between BASIC and the internal Color 64 machine language environment. They allow BASIC programs to read system status information and control various aspects of BBS operation.

All ML variables begin with an exclamation point (!) followed by two digits (for example, !04). They may be used in numeric expressions just like BASIC variables.

Values are assigned using the format:

!XX,value

This syntax is similar to the BASIC POKE command. All ML variables accept values in the range 0–255. Attempting to assign a value outside this range will generate an error.

Some ML variables are read-only, as indicated in the table below. Others are structured as multi-element variables and are accessed using array-style indexing (for example, !23(0)). An out-of-range index will generate an error.

Example:

1000 !04,0:.01:!04,13:if!40<5then1000

In this example:

  • !04 is set to 0, changing the disk input end-of-line character.
  • .01 reads a line from disk.
  • !04 is restored to 13 (carriage return).
  • !40 (number of characters read) is tested. If fewer than 5 characters were read, the loop repeats.

All ML variable references invoke ML processing at address $4E21.

The table below summarizes the ML Variables:

ML Variable Summary
Var Type Description
!00 Read/Write Carrier detect mode

If less than 128, carrier timeout is enabled. If 128 or greater, carrier timeout is disabled. See !11.

!01 Status Output Input and Session Status (Read-Only)

Status returned by input and session routines including .00, .02, .08, .09, .12, and @8. 0 = OK 1 = Aborted (CTRL/P) 3 = Pause (CTRL/S) 4 = Aborted (CTRL/X) 255 = Carrier lost

!02 Status Output Most Recent Character Value

Holds character returned by .00 - Otherwise contains undefined data.

!03 Read/Write Word-Wrap Column

When input exceeds this column and word wrap mode is enabled, wrapping occurs. Wrapped word (up to 15 characters) is buffered and reinserted at next input.

!04 Read/Write File-Input Delimiter

Sets the character used to end .01 and @5 file input when !15 is nonzero. The default value is 13, the carriage-return character.

When the specified character is encountered, it is consumed from the input file but is not included in TX$ or counted in !40.

This setting is ignored when !15 is zero.

!05 Read/Write Translation mode

0 = ASCII translation 1 = Graphics mode (Commodore/ANSI) 2 = Simulated ASCII (graphics input restricted) See also !18.

!06 Read/Write Uppercase Input Mode

If non-zero, alphabetic input (.02 or @8) is forced to uppercase.

!07 Read/Write Word-Wrap Enable

If non-zero, word wrap is enabled. See !03.

!08 Read/Write Maximum Input Length

Sets the maximum number of bytes accepted or returned by several resident input routines.

!09 Read/Write Input Echo Mask

If not 0, this character will be printed instead of what is typed when inputting a line (the .02 command or the @8 function). This is used when the password is entered (asterisks are printed).

!10 Read/Write ASCII Line-Feed Mode

Active only in ASCII translation mode. If non-zero, ASCII 10 follows ASCII 13. See !05.

!11 Read/Write/Status Carrier Timeout Counter

0 = Timer suspended 1 = Timer active (counts to 255 if no carrier) Carrier is checked at 1/60 second intervals (~4.25 seconds timeout). Will hold value of 255 if timed out.

!12 Read/Write Local Communications Mode

1 = disables modem I/O (local mode - no information is outputted to modem) 0 = enables modem I/O.

!13 Status Output Inactivity Timeout Flag

Non-zero value indicates inactivity timeout has occurred (~2 minutes of inactivity).

!14 Read/Write Disk Input Logical File

Used by .01, @5, .12 and other disk routines.

!15 Read/Write File-Input Delimiter Enable

Controls whether .01 and @5 recognize the end-of-line character stored in !04.

0 – Ignore the character stored in !04. Input ends only when the maximum length in !08 is reached or the file status indicates the end of the file or another input condition. Nonzero – Stop input when the character stored in !04 is encountered. The ending character is consumed but is not included in the returned data.

The normal value is 1.

!16 Read/Write/Autoclear Sequential-Display Abort Disable

If non-zero, then the next sequential file read (with the .12 command) cannot be aborted by either the spacebar or CTRL/P keys. Resets to zero after completion of file read.

!17 Read/Write Pager Line Interval

0 disables pager. Non-zero sets pause interval (lines) during .12 sequential reads.

!18 Read/Write ANSI Translation Enable

Active only in Graphics translation mode. If non-zero, ANSI translation is enabled. See !05.

!19 Read/Write/Autoclear One-Line MCI Disable

If non-zero, MCI processing is disabled for one output line. Automatically resets after output.

!20 Read Only Caller-Log Buffer State (Read-Only)

0 = Empty 1 = Contains data >1 = Full (requires disk write)

!21 Read Only Variable-Table Stack Depth (Read-Only)

Current .18 stack level. 0 if no active stacks.

!22 Read/Write Network Transfer Timeout

Set to 128 + minutes when network file transfer initiated (starts timer). 0 disables timer. Transfer aborts if timer expires.

!23 Read/Write Non-SwiftLink Timing Table (indexed)

Valid inputs are 0-17 Table of 18 bytes; holds the timer values used by the Non-SwiftLink systems when sending and receiving the individual bits of data.

  • There are 6 bytes for each BPS rate (300, 1200, and 2400 respectively),
  • For each of the 6 bytes there are 2 bytes for the output bit time, input bit time, and half-bit time
  • Each of the two bytes is a 16-bit value arranged in low byte, high byte order.

The table is as follows: 300 BPS output bit time, 300 BPS input bit time, 300 BPS half-bit time, 1200 BPS output bit time, etc. To access any individual byte of the table, just index !23 like an array (i.e. !23(0) would be byte 0 of the table).

!24 Read/Write Carrier Comparison Value

Hardware comparison value for carrier detection (set by Setup).

!25 Read Only Carrier Present Flag (Read-Only)

Non-zero if carrier detected.

!26 Read Only SwiftLink Hardware Flag (Read-Only)

0 = Non-SwiftLink 1 = SwiftLink system

!27 Read/Write Terminal State Block

Variety of uses dependent on how it is used:

  • !27 - Terminal capture-buffer enable flag
  • !27(1) - Terminal input/translation mode
  • !27(2) - Function-key code returned by .42
!28 Read/Write Terminal Buffer Write Pointer

Points to the next byte available in the terminal capture buffer. This is a 16-bit address in low byte, high byte format which points to the next open character in the term buffer. !28 or !28(0) is the low byte, and !28(1) is the high byte.

!29 Read/Write Term buffer bottom

Points to the first byte of the terminal capture buffer. 16-bit address of first byte of buffer. !29 or !29(0) is the low byte, and !29(1) is the high byte.

!30 Read/Write Term Buffer Limit

Points to the exclusive upper limit of the terminal capture buffer. When the write pointer reaches this address, no additional character is stored and capture is disabled. !30 or !30(0) is the low byte, and !30(1) is the high byte.

!31 Read Only Current BPS Index (Read-Only)

0=300, 1=1200, 2=2400. With SwiftLink, 3=4800, 4=9600, 5=14400, 6=19200, and 7=38400.

!32 Status Output Modem Input Pending Flag (Read-Only)

0 = Empty Non-zero = Characters pending

!33 Read/Write Transfer ASCII Conversion

If non-zero, converts ASCII to PETSCII during transfer.

!34 Read/Write X-Modem CRC retry count

Sets the number of times that the system will attempt to engage CRC (Cyclical Redundancy Check) at the beginning of an X-Modem file transfer.

!35 Read/Write Punter block size

Sets the Block size in bytes for Punter protocol.

!36 Read/Write Transfer file type

1 or 3 = PRG 2 = SEQ

!37 Read Only Active Transfer Protocol (Read-Only)

0 = Punter 1 = X-Modem

!38 Status Output Transfer Timeout Flag

Non-zero after transfer complete indicates carrier or network timeout during transfer.

!39 Status Output Transfer Completion Status

Non-zero indicates aborted transfer.

!40 Status Output Resident TX$ Length

For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.

!41 Read/Write Alternate Output Destination

If non-zero, BBS output is diverted to file #3.

  • Affects BBS output only (BASIC PRINT commands unaffected).
!42 Read Only Day of month (Read-Only)

Updated by @16 function.

!43 Read Only Month of year (Read-Only)

Updated by @16 function.

!44 Read Only AM/PM flag (Read-Only)

0 = AM Non-zero = PM

!45 Read Only Current hour (12hr) (Read-Only)

Holds values 1–12, updated by @11.

!46 Read/Write Scratch register

Public temporary byte used when a routine must preserve another ML variable.

!47 Read/Write Character output delay

May be used to slow output of the system for slower systems. 0 = No delay 255 = Maximum delay

!48 Read/Write Fast Garbage Collection Mode

If non-zero, enables fast string garbage collection. Triggered automatically when free string space < 256 bytes. Supports up to 2048 strings; disables if exceeded. Screen blanks during execution. Recommended for string-intensive routines.

!49 Read Only Boot Device Table (Indexed)

Valid entries are 0 through 2: !49(0) to !49(2), which holds the device numbers for the Boot drive, Program drive, and External drive, respectively. See also !50, !51, and the function @30.

!50 Read Only Boot Drive Table (Indexed)

A table of 3 values, !50(0) to !50(2), which holds the drive numbers for the Boot drive, Program drive, and External drive, respectively. See also !49, !51, and the function @30.

!51 Read Only Disk-Swap Required Flag (Read-Only)

Defined by BOOTMAKER program. 0 = No swap required Non-zero = Disk swap required See also !49, !50, and the function @30.

!52 Read Only/Status Most Recent Search Position (Read-Only)

Holds the one-based result position returned by @2, @25, and accepted-character operations such as .09,"YN".

For .09,"YN", Y sets !52 to 1 and N sets !52 to 2.

!53 Read/Write C128 Fast-GC 2 MHz Flag

If 1, C128 attempts 2 MHz mode during fast garbage collect. No effect on C64. Automatically set for C128 users.

!54 N/A Reserved
!55 Read Only Message Divider Flag

Used for mailbox counting, message seeking, and end-of-message detection. Set by the .31 command. A value of 1 indicates that the most recent disk input record contained exactly one character, CHR$(14), which is the message-divider character used in private mail and Network message files. The CHR$(14) must occupy the entire record; CHR$(14) characters embedded within a longer record do not set this flag. A value of 0 indicates that the record was not a message divider. This variable is updated after every .31 command and is READ ONLY.

!56 Read/Write Editor Command State

Used by the message editor when a command-mode selection has been made.

BBS.MSGS sets !56 according to the selected editor command before returning to the shared input routine.

!57 Read/Write Editor Prefix Character

BBS.MSGS assigns: !57,47 Decimal 47 is the slash character used to introduce editor commands.

!58 Read/Write Editor Input Control Byte

BBS.MSGS sets this to decimal 47 while an editor menu state is active. It is set to zero otherwise. The assignment occurs immediately before calling @8.

!59 Read Only Editor Text-Entry State

Read after @8 to determine whether the editor remains in text-entry mode or must process an editor command.

BBS.MSGS tests !59 immediately after its input call.

!60 Read/Write Editor Menu Selection

Stores the selected editor operation and controls how the following input call is interpreted.

BBS.MSGS:

initializes !60; reads it for editor dispatch; sets it from the accepted menu position; clears it when command processing is complete.

!61 Reserved
!62 Read/Write XMODEM Receive Padding-Strip Mode

!62 is a confirmed public variable used by BBS.TERM during XMODEM receive setup.

0 = preserve received padding nonzero = strip transfer padding

BBS.TERM clears the flag, displays its state, and toggles it when the user selects the asterisk option.

!63 Reserved

Next Section: ML Functions

Programming Features

Retrieved from "https://www.color64wiki.itchybutt.org/index.php?title=Ml_variables&oldid=1003"