Ml variables

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