Ml variables: Difference between revisions

From Color 64 BBS Wiki
← Older edit
No edit summary
No edit summary
 
(6 intermediate revisions by the same user not shown)
Line 2: Line 2:
[[programming features|Programming Features]] - <strong>ML Variables</strong>
[[programming features|Programming Features]] - <strong>ML Variables</strong>


The ML Variables are a way for BASIC to get certain information about the BBS environment, as well as to define the way the BBS operates.  Thus, you can read the information in these variables, as well as assign values to them.  
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. They can be used in expressions just like BASIC variables. Assigning a value to an ML variable follows the same format as the POKE command; the format is "!XX,value".  The range of possible values for all ML variables is 0 to 255.  If the program tries to set an ML variable to a value outside of this range, an error will result.  Some variables are READ ONLY, as will be indicated in the following listing.  And finally, some variables have multiple elements and are addressed like BASIC arrays, and an error will result if an index outside of the allowable range is used. 
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.


Example: <strong>1000 !04,0:.01:!04,13:if!40<5then1000 </strong>
Values are assigned using the format:


In the example above, the following occurs:
!XX,value
* Set ML Variable !04 to 0, where !04 is the end-of-line character used when reading in from the disk. 
* Perform the .01 command, (reads in a disk line). 
* The second !04 then sets the End of Line character back to the normal carriage return character. 
* The line then tests !40, which is the number of characters read in during the last disk input, to see if at least 5 characters were read in.  If not, then the loop repeats.


All ML variables invoke address $4E21 for ML processing.
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.


The table below summarizes the ML Variables: 
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.


{| class="wikitable
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:
 
{| class="wikitable"
|-
|-
|+ML Variable Summary  
|+ ML Variable Summary
! Var
! Var
! Type
! Description
! Description
|-
|-
| !00  
| !00
| <strong>Carrier detect mode.</strong>
| Read/Write
 
| <strong>Carrier detect mode</strong>
If this is less than 128, then the regular carrier detect timeout is enabled (i.e. the timeout timer will run).  Otherwise, the carrier detect timeout is disabled. See the !11 variable for information on the carrier timeout.  
If less than 128, carrier timeout is enabled. If 128 or greater, carrier timeout is disabled. See !11.
|-
| !01
| Status Output
| <strong>Input and Session Status</strong> (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
| <strong>Most Recent Character Value</strong> 
Holds character returned by .00 - Otherwise contains undefined data.
|-
| !03
| Read/Write
| <strong>Word-Wrap Column</strong> 
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.
|-
|-
| !01
| !04
| <strong>Status variable. </strong>
| Read/Write
| <strong>File-Input Delimiter</strong>
Sets the character used to end .01 and @5 file input when !15 is nonzero. The default value is 13, the carriage-return character.


Contains the status after input commands like .00 and .02 (also the @8 function).  The values are as follows: 0 = OK, 1 = aborted by CTRL/P, 3 = pause by CTRL/S, 4 = aborted by CTRL/X, and 255 = carrier lost.
When the specified character is encountered, it is consumed from the input file but is not included in TX$ or counted in !40.
|-
| !02
| <strong>General input/output character. </strong>


Contains the character returned by commands like the .00 and .07 commands.  Any other time, this will contain random data.  
This setting is ignored when !15 is zero.
|-
|-
| !03
| !05
| <strong>Maximum column number for word wrap. </strong>
| Read/Write
 
| <strong>Translation mode</strong>
When the user is typing in a line and the cursor goes beyond this column number, a word wrap will engage if word wrap mode is on. A word that is wrapped (up to 15 characters) is placed in a special word wrap buffer and will be "typed in" by the computer at the next input.  
0 = ASCII translation 
1 = Graphics mode (Commodore/ANSI)  
2 = Simulated ASCII (graphics input restricted)
See also !18.
|-
|-
| !04
| !06
| <strong>End of line character. </strong>
| Read/Write
 
| <strong>Uppercase Input Mode</strong>
The .01 command or the @5 function will read in a line of data until this character is reached, unless the maximum line length is reached, or !15 is set.  See also .01 and !15.  
If non-zero, alphabetic input (.02 or @8) is forced to uppercase.
|-
|-
| !05
| !07
| <strong>Translation mode. </strong>
| Read/Write
 
| <strong>Word-Wrap Enable</strong>
This is used to set the translation mode of the BBS. If it is set to 0, then the current mode is ASCII translation.  When in ASCII mode, the system uses the most basic set of characters for input and output and performs the necessary conversion from ASCII to PET ASCII and vice versa.  Setting this variable to 1 means Graphics mode (either Commodore or ANSI) will be used.  This mode takes advantage of all color and graphics on the system. Setting this variable to 2 means simulated ASCII mode (i.e. if in Graphics mode, any input will be limited to alphabetic, numeric, and common ASCII symbol characters).  Setting this variable to 2 will allow you to keep Graphics users from entering color control characters and special graphics.  See the !18 variable for information on ANSI mode.  
If non-zero, word wrap is enabled. See !03.
|-
|-
| !06
| !08
| <strong>Case constraints on input.</strong>
| Read/Write
 
| <strong>Maximum Input Length</strong>
If this is set to a non-zero value, then all alphabetic characters entered (when .02 or @8 is used) will be converted to uppercase.  
Sets the maximum number of bytes accepted or returned by several resident input routines.
|-
|-
| !07
| !09
| <strong>Word wrap mode. </strong>
| Read/Write
 
| <strong>Input Echo Mask</strong>
If this is not zero, word wrap mode is engaged for line input.  See !03
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).
|-
|-
| !08
| !10
| <strong>Wrap/Width Threshold </strong>
| Read/Write
 
| <strong>ASCII Line-Feed Mode</strong>
See [[Undocumented_8.1_commands#bang8|Undocumented features/commands: !8]]
Active only in ASCII translation mode. If non-zero, ASCII 10 follows ASCII 13. See !05.
|-
|-
| !09
| !11
| <strong>Character output mask.</strong>
| Read/Write/Status
 
| <strong>Carrier Timeout Counter</strong>
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).  
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.
|-
|-
| !10
| !12
| <strong>Line feed mode. </strong>
| Read/Write
 
| <strong>Local Communications Mode</strong>
This is active only for ASCII translation mode.  If this is not zero, then a line feed (ASCII 10) will be printed after each carriage return (ASCII 13).  See the !05 variable for information on the translation mode.  
1 = disables modem I/O (local mode - no information is outputted to modem)  
0 = enables modem I/O.
|-
|-
| !11
| !13
| <strong>Carrier timeout flag. </strong>
| Status Output
 
| <strong>Inactivity Timeout Flag</strong>
If this is set to zero, then the carrier detect timeout timer will be on hold.  If set to 1, then the timer will count to 255 if carrier is not detected.  Since the carrier is checked every 1/60 of a second, a timeout will occur after approximately 4.25 seconds of no carrier.  This variable will contain 255 if a timeout has occurred.  
Non-zero value indicates inactivity timeout has occurred (~2 minutes of inactivity).
|-
|-
| !12
| !14
| <strong>Local mode. </strong>
| Read/Write
 
| <strong>Disk Input Logical File</strong>
Setting this to 1 will disable all modem input and output. This allows the BBS to be used in local mode without characters being sent to the modem. Setting this to 0 allows modem input/output to continue.  
Used by .01, @5, .12 and other disk routines.
|-
|-
| !13
| !15
| <strong>Inactivity timeout flag. </strong>
| Read/Write
| <strong>File-Input Delimiter Enable</strong>
Controls whether .01 and @5 recognize the end-of-line character stored in !04.


If this is not zero, then it means that a timeout occurred because of inactivity on the part of the user.  A user gets approximately 2 minutes before a timeout will occur.  
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.
| !14
| <strong>File number for disk input. </strong>


This used for many disk commands and functions including .01, @5, and .12.  
The normal value is 1.
|-
|-
| !15
| !16
| <strong>End of line mode.  </strong>
| Read/Write/Autoclear
 
| <strong>Sequential-Display Abort Disable</strong>
If this variable is not zero then the disk input routine will ignore the !04 end of line character and will fill the input buffer until the end of the file is reached, or until the maximum number of characters (length of TX$) has been reached.  
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.
|-
|-
| !16
| !17
| <strong>Seq file abort disable.  </strong>
| Read/Write
 
| <strong>Pager Line Interval</strong>
If this is not zero, then the next sequential file read (with the .12 command) will not be abortable by either the spacebar or CTRL/P keys.  After the file is read, this will be reset to zero.  
0 disables pager. 
Non-zero sets pause interval (lines) during .12 sequential reads.
|-
|-
| !17
| !18
| <strong>Number of pager pauser lines.</strong>
| Read/Write
 
| <strong>ANSI Translation Enable</strong>
If this is zero, then the page-pauser will not be active.  If not zero, then this value is used during a sequential file read (the .12 command) as the number of lines for the page-pauser.  For example, if !17 is set to 15, then the BBS will pause and wait for a character after every 15 lines printed when the .12 command is used.  
Active only in Graphics translation mode. 
If non-zero, ANSI translation is enabled. See !05.
|-
|-
| !18
| !19
| <strong>ANSI mode. </strong>
| Read/Write/Autoclear
 
| <strong>One-Line MCI Disable</strong>
This is only active for Graphics translation mode.  If this is set to a non-zero value, then ANSI translation mode is enabled.  See the !05 variable for information on the translation mode. When in ANSI mode, the system acts just as if the system is running in Commodore Graphics mode, except that all output is converted to the appropriate ANSI codes.  
If non-zero, MCI processing is disabled for one output line. Automatically resets after output.
|-
|-
| !19
| !20
| <strong>MCI disable mode.  </strong>
| Read Only
 
| <strong>Caller-Log Buffer State</strong> (Read-Only) 
If this is not zero, then MCI's will be disabled for one line of output. This is always reset to 0 after every output command.
0 = Empty 
1 = Contains data  
>1 = Full (requires disk write)
|-
|-
| !20
| !21
| <strong>Caller log buffer status flag.</strong>
| Read Only
 
| <strong>Variable-Table Stack Depth</strong> (Read-Only)  
This read-only variable indicates the status of the caller log temporary buffer. If it is zero, then the buffer is empty.  If it is 1, then the buffer has some contents in it. If it is greater than 1, then the buffer is full and needs to be dumped to disk. This is for use only be the regular caller log routines.
Current .18 stack level. 0 if no active stacks.
|-
|-
| !21
| !22
| <strong>Variable-killer stack number. </strong>
| Read/Write
 
| <strong>Network Transfer Timeout</strong>
This read-only variable indicates the current level of "nested" variable kills.  If no .18 commands are currently in effect, then this will be set to 0.  As each .18 command is issued, then this will increase by one. 
Set to 128 + minutes when network file transfer initiated (starts timer).   
0 disables timer.   
Transfer aborts if timer expires.
|-
|-
| !22
| !23
| <strong>Network file transfer timeout timer. </strong>
| Read/Write
| <strong>Non-SwiftLink Timing Table (indexed)</strong>
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. 


When a network file transfer is initiated, this is to be set to 128 plus the number of minutes for the timeout timer.  The timer will start as soon as the variable is set. Setting this variable to zero turns off the timer. If the timer runs for the full length of time, then the current file transfer will be aborted.  
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).
|-
|-
| !23
| !24
| <strong>Non-SwiftLink BPS timer table.</strong>
| Read/Write
 
| <strong>Carrier Comparison Value</strong>
This 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), and of the 6 bytes there are 2 bytes each for the output bit time, input bit time, and half-bit time, respectively.  Each of the two bytes is a 16-bit value arranged in low byte, high byte order.  Thus, 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).  
Hardware comparison value for carrier detection (set by Setup).
|-
|-
| !24
| !25
| <strong>Carrier type. </strong>
| Read Only
 
| <strong>Carrier Present Flag</strong> (Read-Only) 
Holds the value which is compared to the computer's hardware register to see if the carrier is detected.  This value is determined by Setup when you set the carrier type.  
Non-zero if carrier detected.
|-
|-
| !25
| !26
| <strong>Carrier status. </strong>
| Read Only
 
| <strong>SwiftLink Hardware Flag</strong> (Read-Only) 
This read-only variable will be non-zero if carrier is detected, and zero if there is no carrier. 
0 = Non-SwiftLink 
1 = SwiftLink system
|-
|-
| !26
| !27
| <strong>SwiftLink/Non-SwiftLink flag. </strong>
| Read/Write
 
| <strong>Terminal State Block</strong>
Read-only variable; If this is 0, then the system is a Non-SwiftLink system. If it is 1, then the system is using the SwiftLink cartridge
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
|-
|-
| !27
| !28
| <strong>Term buffer mode.</strong>
| Read/Write
 
| <strong>Terminal Buffer Write Pointer</strong>
If this is not zero, then all characters printed to the screen will also be put into the term buffer. The parameters of the buffers are established by the !28, !29, and !30 variables.  Output is diverted to file number 3 (normally screen output).  This is used by the Plusterm program.  
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.  
<nowiki>!28 or !28(0) is the low byte, and !28(1) </nowiki>is the high byte.
|-
|-
| !28
| !29
| <strong>Term buffer pointer. </strong>
| Read/Write
 
| <strong>Term buffer bottom</strong>
This is a 16-bit address in low byte, high byte format which points to the next open character in the term buffer. !28(0) is the low byte, and !28(1) is the high byte.  This is used by the Plusterm program.  
Points to the first byte of the terminal capture buffer.
16-bit address of first byte of buffer.
<nowiki>!29 or !29(0) is the low byte, and !29(1)</nowiki> is the high byte.
|-
|-
| !29
| !30
| <strong>Term buffer bottom pointer. </strong>
| Read/Write
 
| <strong>Term Buffer Limit</strong>
This is a 16-bit address in low byte, high byte format which is the address of the first byte of the term buffer. This is used by the Plusterm program.  
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.
<nowiki>!30 or !30(0) is the low byte, and !30(1)</nowiki> is the high byte.
|-
|-
| !30
| !31
| <strong>Term buffer top pointer. </strong>
| Read Only
 
| <strong>Current BPS Index</strong> (Read-Only) 
This is a 16-bit address in low byte, high byte format which is the address of the last possible byte of the term buffer (i.e. the buffer pointer cannot go beyond this point).  This is used by the Plusterm program.  
0=300, 1=1200, 2=2400. With SwiftLink, 3=4800, 4=9600, 5=14400, 6=19200, and 7=38400.
|-
|-
| !31
| !32
| <strong>Current BPS rate. </strong>
| Status Output
 
| <strong>Modem Input Pending Flag</strong> (Read-Only)  
This read-only value in the range 0 to 7 indicates the current BPS rate of computer to modem communication. Possible values are: 0 = 300, 1 = 1200, 2 = 2400, 3 = 4800, 4 = 9600, 5 = 14400, 6 = 19200, 7 = 38400. 
0 = Empty 
Non-zero = Characters pending
|-
|-
| !32
| !33
| <strong>Input buffer empty flag. </strong>
| Read/Write
 
| <strong>Transfer ASCII Conversion</strong>
If this read-only variable is 0, then the modem input buffer is currently empty.  Otherwise, there are still characters waiting in the modem input buffer.  
If non-zero, converts ASCII to PETSCII during transfer.
|-
|-
| !33
| !34
| <strong>X-Modem file conversion mode.</strong>
| Read/Write
 
| <strong>X-Modem CRC retry count</strong>
If this is not 0, then the file being transferred will be converted from standard ASCII to PET ASCII.  
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.
|-
|-
| !34
| !35
| <strong>Number of tries for X-Modem CRC mode.</strong>
| Read/Write
 
| <strong>Punter block size</strong>
This 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.  
Sets the Block size in bytes for Punter protocol.
|-
|-
| !35
| !36
| <strong>Punter block size. </strong>
| Read/Write
 
| <strong>Transfer file type</strong>
This sets the number of bytes for the Punter file transfer blocks.
1 or 3 = PRG 
2 = SEQ
|-
|-
| !36
| !37
| <strong>File type for transfer.</strong>
| Read Only
 
| <strong>Active Transfer Protocol</strong> (Read-Only) 
This value is the file type of the current file transfer.  If it is 1 or 3, then the file is a PRG file.  If it is 2, then the file is a SEQ file.
0 = Punter 
1 = X-Modem
|-
|-
| !37
| !38
| <strong>Current protocol type.</strong>
| Status Output
 
| <strong>Transfer Timeout Flag</strong>
The current protocols set this read-only value to 0 for Punter, and 1 for X-Modem.  
Non-zero after transfer complete indicates carrier or network timeout during transfer.
|-
|-
|!38
| !39
| <strong>File transfer timeout flag.</strong>
| Status Output
 
| <strong>Transfer Completion Status</strong>
If this is not zero at the end of a transfer, then it means a carrier-detect timeout occurred during the transfer.  Also, it could mean a Network file transfer timeout.  
Non-zero indicates aborted transfer.
|-
|-
| !39
| !40
| <strong>End of transfer status.</strong>
| Status Output
 
| <strong>Resident TX$ Length</strong>
If this is not zero at the end of the transfer, it means the transfer was aborted.  
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.
|-
|-
| !40
| !41
| <strong>Number of input characters.</strong>
| Read/Write
 
| <strong>Alternate Output Destination</strong>
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.  
If non-zero, BBS output is diverted to file #3.
* Affects BBS output only (BASIC PRINT commands unaffected).
|-
|-
| !41
| !42
| <strong>Alternate output file mode.</strong>
| Read Only
 
| <strong>Day of month</strong> (Read-Only)   
If this is not zero, then screen output for the BBS is diverted to file number 3 (usually the screen or the printer). Only the regular BBS output commands are affected, so the BASIC PRINT command will not be affected.  
Updated by @16 function.
|-
|-
| !42
| !43
| <strong>Day of the month. </strong>
| Read Only
 
| <strong>Month of year</strong> (Read-Only)  
This read-only variable will contain the day of the month calculated from the most recent @16 function. See the @16 function for more information.  
Updated by @16 function.
|-
|-
| !43
| !44
| <strong>Month of year. </strong>
| Read Only
 
| <strong>AM/PM flag</strong> (Read-Only) 
This read-only variable will contain the month of the year calculated from the most recent @16 function.  See the @16 function for more information.
0 = AM 
Non-zero = PM
|-
|-
| !44
| !45
| <strong>PM/AM Flag. </strong>
| Read Only
 
| <strong>Current hour (12hr)</strong> (Read-Only) 
When the @11 function is used to get the time, this read-only variable will be 0 if the time is currently AM, otherwise the time is PM.
Holds values 1–12, updated by @11.
|-
|-
| !45
| !46
| <strong>Current time hour. </strong>
| Read/Write
 
| <strong>Scratch register</strong>
When the @11 function is used to get the time, this read-only variable will contain the hour (1 to 12).  See the @11 function for more information.  
Public temporary byte used when a routine must preserve another ML variable.
|-
|-
| !46
| !47
| <strong>Not used </strong>
| Read/Write
| <strong>Character output delay</strong>
May be used to slow output of the system for slower systems.
0 = No delay 
255 = Maximum delay
|-
|-
| !47
| !48
| <strong>Character output delay. </strong>
| Read/Write
 
| <strong>Fast Garbage Collection Mode</strong>
This sets the delay between characters to allow slower systems to keep up with the output of Color 64.  A value of 0 means no delay, while 255 means maximum delay.  
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.
|-
|-
| !48
| !49
| <strong>Fast garbage collect mode. </strong>
| Read Only
 
| <strong>Boot Device Table</strong> (Indexed) 
Garbage collection is the term used for the computer's method of managing the memory used by string variables.  As each new string is added to memory, it is simply plopped into memory at the next open space.  As strings are removed from memory, though, the space they occupied just sits there unused.  Because of this the amount of open space for new strings slowly decreases, and the computer will eventually have to "collect" all the garbage strings just sitting in memory.  This process can take up to a couple minutes on a system with lots of variables, so this mode was designed to allow an alternative (and faster) routine to be used.  Fast garbage collect mode is turned on by setting !48 to a non-zero value.  Before executing each command, the computer will automatically check to see how much memory is open for strings.  If it drops below 256 bytes, the routine will execute a fast version of the garbage collection routine used by the computer.  Garbage collection delays which could have lasted minutes will last only seconds.  The fast garbage collect can handle a maximum of 2048 strings, and if there are more the !48 variable will be set back to 0.  This is to avoid lengthy delays by having two conflicting garbage collection routines working at the same time.  You should have !48 on when using routines that read in a lot of string data (the directory regenerate routine uses this variable).  
Valid entries are 0 through 2: <strong>!49(0)</strong> to <strong>!49(2)</strong>, which holds the device numbers for the Boot drive, Program drive, and External drive, respectively.  See also !50, !51, and the function @30.
|-
|-
| !49
| !50
| <strong>Boot device numbers. </strong>
| Read Only
 
| <strong>Boot Drive Table</strong> (Indexed) 
A read-only table of 3 values, !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.  
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.
|-
|-
| !50
| !51
| <strong>Boot drive numbers.  </strong>
| Read Only
 
| <strong>Disk-Swap Required Flag</strong> (Read-Only) 
This is a read-only 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.  
Defined by BOOTMAKER program.
0 = No swap required  
Non-zero = Disk swap required
See also !49, !50, and the function @30.
|-
|-
| !51
| !52
| <strong>Disk swapping flag. </strong>
| Read Only/Status
| <strong>Most Recent Search Position</strong> (Read-Only) 
Holds the one-based result position returned by @2, @25, and accepted-character operations such as .09,"YN".


This is a read-only flag defined through the boot maker programs when you answer the question for if you need to swap the Program and Boot disks for floppy drive systems. If this is 0, then no disk swapping is necessary, otherwise this will be non-zero.  See also !49, !50, and the function @30.  
For .09,"YN", Y sets !52 to 1 and N sets !52 to 2.
|-
|-
| !52
| !53
| <strong>Most recent find location. </strong>
| Read/Write
 
| <strong>C128 Fast-GC 2 MHz Flag</strong>
This read-only variable will contain the value of the most recent @2 or @25 find function executed. This can be used to avoid having to assign the value of the function to a temporary variable. This will be 0 if you use the find functions to find the actual number of finds, rather than the location of a find.
If 1, C128 attempts 2 MHz mode during fast garbage collect. No effect on C64.
Automatically set for C128 users.
|-
|-
| !53
| !54
| <strong>Flag - 2Mhz during Fast Garbage Collect.</strong>
| N/A
 
| Reserved
The setting of this variable determines whether the system will attempt to enter 2-megahertz mode on 128 computers when doing the Fast Garbage Collect (FGC) routine.  This variable is set in line 150 of the √sys.loadml program when the ML is installed.  If it is 1, then the computer will try to use 2Mhz mode when in the FGC routine.  This has no effect for C64 users or systems using the TurboMaster CPU, but this feature will automatically be used for C128 users.  If you notice that this setting is causing a problem when the system is running, then you may need to change the √sys.loadml program to set this variable to 0.  This way, the system will never attempt to enter 2Mhz mode.  Also, regardless of the setting of this variable the screen will always be blanked during a FGC.  See also the variable !48 for more information on Fast Garbage Collect.
|-
|-
| !55
| !55
| <strong>Message Record Delimiter Flag</strong>
| Read Only
This is a newer function undocumented in the version 8.0 manuscript.  
| <strong>Message Divider Flag</strong>
 
Used for mailbox counting, message seeking, and end-of-message detection.
See [[Undocumented_8.1_commands#dot31|Undocumented features/commands: .31]] for more information.
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
| !56
| <strong>Message Editor Command State</strong>
| Read/Write
This is a newer function undocumented in the version 8.0 manuscript. This flag determines if the Message Editor is in a Command State or in normal editing.
| <strong>Editor Command State</strong>
Used by the message editor when a command-mode selection has been made.


See [[Undocumented_8.1_commands#bang56|Undocumented features/commands: !56]] for more information.
BBS.MSGS sets !56 according to the selected editor command before returning to the shared input routine.
|-
|-
| !57
| !57
| <strong>Prefix Trigger Assignment (Editor)</strong>
| Read/Write
This is a newer function undocumented in the version 8.0 manuscript. This determines the key-command that will enter the command state when in the editor.
| <strong>Editor Prefix Character</strong>
 
BBS.MSGS assigns: !57,47
See [[Undocumented_8.1_commands#bang57|Undocumented features/commands: !57]] for more information.
Decimal 47 is the slash character used to introduce editor commands.
|-
|-
| !58
| !58
| <strong>?? (Editor)</strong>
| Read/Write
This is a newer function undocumented in the version 8.0 manuscript. Under investigation.
| <strong>Editor Input Control Byte</strong>
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
| <strong>Editor Text-Entry State</strong> 
Read after @8 to determine whether the editor remains in text-entry mode or must process an editor command.


See [[Undocumented_8.1_commands#bang58|Undocumented features/commands: !58]] for more useless information.
BBS.MSGS tests !59 immediately after its input call.
|-
|-
| !60
| !60
| <strong>Editor Menu Selection</strong>
| Read/Write
This is a newer function undocumented in the version 8.0 manuscript. This ML Variable stores the selected Menu item when in the message editor.
| <strong>Editor Menu Selection</strong>
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
|
| <strong>Reserved</strong> 
|-
| !62
| Read/Write
| <strong>XMODEM Receive Padding-Strip Mode</strong>
<nowiki>!62</nowiki> is a confirmed public variable used by BBS.TERM during XMODEM receive setup.


See [[Undocumented_8.1_commands#bang60|Undocumented features/commands: !60]] for more information.
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
|
| <strong>Reserved</strong> 
|}
|}
<nowiki>**</nowiki> Note that there are additional undocumented ML variables in use. See “Undocumented / Unknown ML Variables, Commands and Basic Shortcuts” in the Appendices.


Next Section: [[ml functions|ML Functions]]
Next Section: [[ml functions|ML Functions]]


[[programming features|Programming Features]]
[[programming features|Programming Features]]

Latest revision as of 23:52, 30 July 2026

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"