Ml variables: Difference between revisions

From Color 64 BBS Wiki
← Older edit
No edit summary
No edit summary
 
(11 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 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.
|-
| !04
| 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.
 
When the specified character is encountered, it is consumed from the input file but is not included in TX$ or counted in !40.


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.  
This setting is ignored when !15 is zero.
|-
| !05
| Read/Write
| <strong>Translation mode</strong> 
0 = ASCII translation 
1 = Graphics mode (Commodore/ANSI) 
2 = Simulated ASCII (graphics input restricted) 
See also !18.
|-
| !06
| Read/Write
| <strong>Uppercase Input Mode</strong> 
If non-zero, alphabetic input (.02 or @8) is forced to uppercase.
|-
| !07
| Read/Write
| <strong>Word-Wrap Enable</strong> 
If non-zero, word wrap is enabled. See !03.
|-
| !08
| Read/Write
| <strong>Maximum Input Length</strong> 
Sets the maximum number of bytes accepted or returned by several resident input routines.
|-
| !09
| Read/Write
| <strong>Input Echo Mask</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).
|-
|-
| !01
| !10
| <strong>Status variable. </strong>
| Read/Write
 
| <strong>ASCII Line-Feed Mode</strong>
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.  
Active only in ASCII translation mode. If non-zero, ASCII 10 follows ASCII 13. See !05.
|-
| !11
| Read/Write/Status
| <strong>Carrier Timeout Counter</strong>  
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
| <strong>Local Communications Mode</strong> 
1 = disables modem I/O (local mode - no information is outputted to modem)
0 = enables modem I/O.
|-
| !13
| Status Output
| <strong>Inactivity Timeout Flag</strong> 
Non-zero value indicates inactivity timeout has occurred (~2 minutes of inactivity).
|-
|-
| !02
| !14
| <strong>General input/output character. </strong>
| Read/Write
 
| <strong>Disk Input Logical File</strong>
Contains the character returned by commands like the .00 and .07 commands.  Any other time, this will contain random data.  
Used by .01, @5, .12 and other disk routines.
|-
|-
| !03
| !15
| <strong>Maximum column number for word wrap. </strong>
| Read/Write
| <strong>File-Input Delimiter Enable</strong>
Controls whether .01 and @5 recognize the end-of-line character stored in !04.


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 – 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.
| !04  
| <strong>End of line character. </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.  
The normal value is 1.
|-
|-
| !05
| !16
| <strong>Translation mode. </strong>
| Read/Write/Autoclear
 
| <strong>Sequential-Display Abort Disable</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, 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.
|-
|-
| !06
| !17
| <strong>Case constraints on input.</strong>
| Read/Write
 
| <strong>Pager Line Interval</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.  
0 disables pager. 
Non-zero sets pause interval (lines) during .12 sequential reads.
|-
|-
| !07
| !18
| <strong>Word wrap mode. </strong>
| Read/Write
 
| <strong>ANSI Translation Enable</strong>
If this is not zero, word wrap mode is engaged for line input. See !03
Active only in Graphics translation mode. 
If non-zero, ANSI translation is enabled. See !05.
|-
|-
| !08
| !19
| <strong>Reserved for future use. </strong>
| Read/Write/Autoclear
| <strong>One-Line MCI Disable</strong>
If non-zero, MCI processing is disabled for one output line. Automatically resets after output.
|-
|-
| !09
| !20
| <strong>Character output mask.</strong>
| Read Only
 
| <strong>Caller-Log Buffer State</strong> (Read-Only) 
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 = Empty 
1 = Contains data  
>1 = Full (requires disk write)
|-
|-
| !10
| !21
| <strong>Line feed mode. </strong>
| Read Only
 
| <strong>Variable-Table Stack Depth</strong> (Read-Only) 
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.  
Current .18 stack level. 0 if no active stacks.
|-
|-
| !11
| !22
| <strong>Carrier timeout flag. </strong>
| Read/Write
 
| <strong>Network Transfer Timeout</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.  
Set to 128 + minutes when network file transfer initiated (starts timer).   
0 disables timer.   
Transfer aborts if timer expires.
|-
|-
| !12
| !23
| <strong>Local mode. </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. 


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.  
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).
|-
|-
| !13
| !24
| <strong>Inactivity timeout flag. </strong>
| Read/Write
 
| <strong>Carrier Comparison Value</strong>
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.  
Hardware comparison value for carrier detection (set by Setup).
|-
|-
| !14
| !25
| <strong>File number for disk input. </strong>
| Read Only
 
| <strong>Carrier Present Flag</strong> (Read-Only) 
This used for many disk commands and functions including .01, @5, and .12.  
Non-zero if carrier detected.
|-
|-
| !15
| !26
| <strong>End of line mode.  </strong>
| Read Only
 
| <strong>SwiftLink Hardware Flag</strong> (Read-Only) 
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.
0 = Non-SwiftLink 
1 = SwiftLink system
|-
|-
| !16
| !27
| <strong>Seq file abort disable.  </strong>
| Read/Write
 
| <strong>Terminal State Block</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.  
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
|-
|-
| !17
| !28
| <strong>Number of pager pauser lines.</strong>
| Read/Write
 
| <strong>Terminal Buffer Write Pointer</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.
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.
|-
|-
| !18
| !29
| <strong>ANSI mode. </strong>
| Read/Write
 
| <strong>Term buffer bottom</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.  
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.
|-
|-
| !19
| !30
| <strong>MCI disable mode.  </strong>
| Read/Write
 
| <strong>Term Buffer Limit</strong>
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.  
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.
|-
|-
| !20
| !31
| <strong>Caller log buffer status flag.</strong>
| Read Only
 
| <strong>Current BPS Index</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.
0=300, 1=1200, 2=2400. With SwiftLink, 3=4800, 4=9600, 5=14400, 6=19200, and 7=38400.
|-
|-
| !21
| !32
| <strong>Variable-killer stack number. </strong>
| Status Output
 
| <strong>Modem Input Pending Flag</strong> (Read-Only)  
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.  
0 = Empty  
Non-zero = Characters pending
|-
|-
| !22
| !33
| <strong>Network file transfer timeout timer. </strong>
| Read/Write
 
| <strong>Transfer ASCII Conversion</strong>
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.  
If non-zero, converts ASCII to PETSCII during transfer.
|-
|-
| !23
| !34
| <strong>Non-SwiftLink BPS timer table.</strong>
| Read/Write
 
| <strong>X-Modem CRC retry count</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).  
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.
|-
|-
| !24
| !35
| <strong>Carrier type. </strong>
| Read/Write
 
| <strong>Punter block size</strong>
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.  
Sets the Block size in bytes for Punter protocol.
|-
|-
| !25
| !36
| <strong>Carrier status. </strong>
| Read/Write
 
| <strong>Transfer file type</strong>
This read-only variable will be non-zero if carrier is detected, and zero if there is no carrier. 
1 or 3 = PRG 
2 = SEQ
|-
|-
| !26
| !37
| <strong>SwiftLink/Non-SwiftLink flag. </strong>
| Read Only
 
| <strong>Active Transfer Protocol</strong> (Read-Only) 
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
0 = Punter  
1 = X-Modem
|-
|-
| !27
| !38
| <strong>Term buffer mode.</strong>
| Status Output
 
| <strong>Transfer Timeout Flag</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.  
Non-zero after transfer complete indicates carrier or network timeout during transfer.
|-
|-
| !28
| !39
| <strong>Term buffer pointer. </strong>
| Status Output
 
| <strong>Transfer Completion Status</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.  
Non-zero indicates aborted transfer.
|-
|-
| !29
| !40
| <strong>Term buffer bottom pointer. </strong>
| Status Output
 
| <strong>Resident TX$ Length</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.  
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.
|-
|-
| !30
| !41
| <strong>Term buffer top pointer. </strong>
| Read/Write
 
| <strong>Alternate Output Destination</strong>
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.  
If non-zero, BBS output is diverted to file #3.
* Affects BBS output only (BASIC PRINT commands unaffected).
|-
|-
| !31
| !42
| <strong>Current BPS rate. </strong>
| Read Only
 
| <strong>Day of month</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.
Updated by @16 function.
|-
|-
| !32
| !43
| <strong>Input buffer empty flag. </strong>
| Read Only
 
| <strong>Month of year</strong> (Read-Only)  
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.  
Updated by @16 function.
|-
|-
| !33
| !44
| <strong>X-Modem file conversion mode.</strong>
| Read Only
 
| <strong>AM/PM flag</strong> (Read-Only) 
If this is not 0, then the file being transferred will be converted from standard ASCII to PET ASCII.
0 = AM 
Non-zero = PM
|-
|-
| !34
| !45
| <strong>Number of tries for X-Modem CRC mode.</strong>
| Read Only
 
| <strong>Current hour (12hr)</strong> (Read-Only)
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.  
Holds values 1–12, updated by @11.
|-
|-
| !35
| !46
| <strong>Punter block size. </strong>
| Read/Write
 
| <strong>Scratch register</strong>
This sets the number of bytes for the Punter file transfer blocks.  
Public temporary byte used when a routine must preserve another ML variable.
|-
|-
| !36
| !47
| <strong>File type for transfer.</strong>
| Read/Write
 
| <strong>Character output delay</strong>
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.
May be used to slow output of the system for slower systems.
0 = No delay  
255 = Maximum delay
|-
|-
| !37
| !48
| <strong>Current protocol type.</strong>
| Read/Write
 
| <strong>Fast Garbage Collection Mode</strong>
The current protocols set this read-only value to 0 for Punter, and 1 for X-Modem.  
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.
|-
|-
|!38
| !49
| <strong>File transfer timeout flag.</strong>
| Read Only
 
| <strong>Boot Device Table</strong> (Indexed) 
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.  
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.
|-
|-
| !39
| !50
| <strong>End of transfer status.</strong>
| Read Only
 
| <strong>Boot Drive Table</strong> (Indexed) 
If this is not zero at the end of the transfer, it means the transfer was aborted.  
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.
|-
|-
| !40
| !51
| <strong>Number of input characters.</strong>
| Read Only
 
| <strong>Disk-Swap Required Flag</strong> (Read-Only)
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.  
Defined by BOOTMAKER program.
0 = No swap required 
Non-zero = Disk swap required
See also !49, !50, and the function @30.
|-
|-
| !41
| !52
| <strong>Alternate output file mode.</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".


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.  
For .09,"YN", Y sets !52 to 1 and N sets !52 to 2.
|-
|-
| !42
| !53
| <strong>Day of the month. </strong>
| Read/Write
 
| <strong>C128 Fast-GC 2 MHz Flag</strong>
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.  
If 1, C128 attempts 2 MHz mode during fast garbage collect. No effect on C64.
Automatically set for C128 users.
|-
|-
| !43
| !54
| <strong>Month of year. </strong>
| N/A
 
| Reserved
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.
|-
|-
| !44
| !55
| <strong>PM/AM Flag. </strong>
| Read Only
 
| <strong>Message Divider Flag</strong>
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.
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.
|-
|-
| !45
| !56
| <strong>Current time hour. </strong>
| Read/Write
| <strong>Editor Command State</strong>
Used by the message editor when a command-mode selection has been made.


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.  
BBS.MSGS sets !56 according to the selected editor command before returning to the shared input routine.
|-
|-
| !46
| !57
| <strong>Not used </strong>
| Read/Write
| <strong>Editor Prefix Character</strong>
BBS.MSGS assigns: !57,47
Decimal 47 is the slash character used to introduce editor commands.
|-
|-
| !47
| !58
| <strong>Character output delay. </strong>
| Read/Write
 
| <strong>Editor Input Control Byte</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.  
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.
|-
|-
| !48
| !59
| <strong>Fast garbage collect mode. </strong>
| 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.


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).  
BBS.MSGS tests !59 immediately after its input call.
|-
|-
| !49
| !60
| <strong>Boot device numbers. </strong>
| Read/Write
| <strong>Editor Menu Selection</strong>
Stores the selected editor operation and controls how the following input call is interpreted.


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.
BBS.MSGS:
|-
| !50
| <strong>Boot drive numbers.  </strong>


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.  
initializes !60;
reads it for editor dispatch;
sets it from the accepted menu position;
clears it when command processing is complete.
|-
|-
| !51
| !61
| <strong>Disk swapping flag. </strong>
|
 
| <strong>Reserved</strong>   
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. 
|-
|-
| !52
| !62
| <strong>Most recent find location. </strong>
| 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.


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. 
0       = preserve received padding
|-
nonzero = strip transfer padding
| !53
| <strong>Flag - 2Mhz during Fast Garbage Collect.</strong>


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.  
BBS.TERM clears the flag, displays its state, and toggles it when the user selects the asterisk option.
|-
|-
| !55
| !63
| <strong>Message Record Delimiter Flag</strong>
|
See [[Undocumented_8.1_commands#dot31|Undocumented features/commands: .31]] for more information.
| <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"