Ml variables: Difference between revisions

From Color 64 BBS Wiki
← Older edit
No edit summary
No edit summary
 
(9 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:


All ML variables invoke address $4E21 for ML processing.
!XX,value


In the example above, the following occurs:
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.
* 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.  


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
! Description
! Description
|-
|-
| !00  
| !00
| <strong>Carrier detect mode.</strong>
| <strong>Carrier detect mode</strong>
 
If less than 128, carrier timeout is enabled. If 128 or greater, carrier timeout is disabled. See !11.
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.  
|-
| !01
| <strong>Status variable</strong> (Read-Only) 
Status after input commands (.00, .02, @8).   
0 = OK 
1 = Aborted (CTRL/P) 
3 = Pause (CTRL/S) 
4 = Aborted (CTRL/X) 
255 = Carrier lost
|-
| !02
| <strong>General input/output character</strong> 
Holds character returned by .00 or .07. Otherwise contains undefined data.
|-
| !03
| <strong>Maximum column for word wrap</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
| <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
|-
| !05
| <strong>Translation mode</strong> 
0 = ASCII translation 
1 = Graphics mode (Commodore/ANSI) 
2 = Simulated ASCII (graphics input restricted)  
See also !18.
|-
| !06
| <strong>Uppercase input constraint</strong> 
If non-zero, alphabetic input (.02 or @8) is forced to uppercase.
|-
|-
| !01
| !07
| <strong>Status variable. </strong>
| <strong>Word wrap mode</strong>
 
If non-zero, word wrap is enabled. See !03.
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.  
|-
|-
| !02
| !08
| <strong>General input/output character. </strong>
| <strong>Wrap/Width Threshold</strong>
 
See [[Undocumented_8.1_commands#bang8|Undocumented features: !8]].
Contains the character returned by commands like the .00 and .07 commands.  Any other time, this will contain random data.  
|-
|-
| !03
| !09
| <strong>Maximum column number for word wrap. </strong>
| <strong>Character output 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).
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.  
|-
|-
| !04
| !10
| <strong>End of line character. </strong>
| <strong>Line feed mode</strong>
 
Active only in ASCII translation mode. If non-zero, ASCII 10 follows ASCII 13. See !05.
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.  
|-
|-
| !05
| !11
| <strong>Translation mode. </strong>
| <strong>Carrier timeout flag</strong>
 
0 = Timer suspended  
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.  
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.
|-
|-
| !06
| !12
| <strong>Case constraints on input.</strong>
| <strong>Local mode</strong>
 
1 = disables modem I/O (local mode - no information is outputted to modem)  
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 = enables modem I/O.
|-
|-
| !07
| !13
| <strong>Word wrap mode. </strong>
| <strong>Inactivity timeout flag</strong>
 
Non-zero value indicates inactivity timeout has occurred (~2 minutes of inactivity).
If this is not zero, word wrap mode is engaged for line input. See !03
|-
|-
| !08
| !14
| <strong>Reserved for future use. </strong>
| <strong>Disk input file number</strong>
Used by .01, @5, .12 and other disk routines.
|-
|-
| !09
| !15
| <strong>Character output mask.</strong>
| <strong>End-of-line override mode</strong>
 
If non-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 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
| !16
| <strong>Line feed mode. </strong>
| <strong>SEQ file abort disable</strong>
 
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.
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.  
|-
|-
| !11
| !17
| <strong>Carrier timeout flag. </strong>
| <strong>Pager line count</strong>
 
0 disables pager. 
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 sets pause interval (lines) during .12 sequential reads.
|-
|-
| !12
| !18
| <strong>Local mode. </strong>
| <strong>ANSI mode</strong>
 
Active only in Graphics translation mode.   
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.  
If non-zero, ANSI translation is enabled. See !05.
|-
|-
| !13
| !19
| <strong>Inactivity timeout flag. </strong>
| <strong>MCI disable flag</strong>
 
If non-zero, MCI processing is disabled for one output line. Automatically resets after output.
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.  
|-
|-
| !14
| !20
| <strong>File number for disk input. </strong>
| <strong>Caller log buffer status</strong> (Read-Only) 
 
0 = Empty 
This used for many disk commands and functions including .01, @5, and .12.
1 = Contains data 
>1 = Full (requires disk write)
|-
|-
| !15
| !21
| <strong>End of line mode.  </strong>
| <strong>Variable Stack Number</strong> (Read-Only)
 
Current .18 stack level. 0 if no active stacks.
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.  
|-
|-
| !16
| !22
| <strong>Seq file abort disable.  </strong>
| <strong>Network transfer timeout</strong>
 
Set to 128 + minutes when network file transfer initiated (starts timer).
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 timer.   
Transfer aborts if timer expires.
|-
|-
| !17
| !23
| <strong>Number of pager pauser lines.</strong>
| <strong>Non-SwiftLink BPS timer table</strong>
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. 


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.  
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).
|-
|-
| !18
| !24
| <strong>ANSI mode. </strong>
| <strong>Carrier type</strong>
 
Hardware comparison value for carrier detection (set by Setup).
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.  
|-
|-
| !19
| !25
| <strong>MCI disable mode.  </strong>
| <strong>Carrier status</strong> (Read-Only) 
 
Non-zero if carrier detected.
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.  
|-
|-
| !20
| !26
| <strong>Caller log buffer status flag.</strong>
| <strong>SwiftLink flag</strong> (Read-Only) 
 
0 = Non-SwiftLink  
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. 
1 = SwiftLink system
|-
|-
| !21
| !27
| <strong>Variable-killer stack number. </strong>
| <strong>Term buffer mode</strong>
 
If this is not zero, then all characters printed to the screen will also be put into the term buffer.   
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.
• Parameters of the buffers are established by the !28, !29, and !30 variables.
• Output is diverted to file number 3 (normally screen output). 
• Used by the Plusterm program.
|-
|-
| !22
| !28
| <strong>Network file transfer timeout timer. </strong>
| <strong>Term buffer pointer</strong>
 
This is a 16-bit address in low byte, high byte format which points to the next open character in the term buffer.  
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.  
• !28(0) is the low byte, and !28(1) is the high byte.   
• Used by the Plusterm program.
|-
|-
| !23
| !29
| <strong>Non-SwiftLink BPS timer table.</strong>
| <strong>Term buffer bottom pointer</strong>
 
16-bit address of first byte of buffer.
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).  
Used by the Plusterm program.
|-
|-
| !24
| !30
| <strong>Carrier type. </strong>
| <strong>Term buffer top pointer</strong>
 
16-bit address of last valid byte.
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.  
Used by the Plusterm program.
|-
|-
| !25
| !31
| <strong>Carrier status. </strong>
| <strong>Current BPS rate</strong> (Read-Only) 
 
0=300, 1=1200, 2=2400, 3=4800, 4=9600, 5=14400, 6=19200, 7=38400
This read-only variable will be non-zero if carrier is detected, and zero if there is no carrier. 
|-
|-
| !26
| !32
| <strong>SwiftLink/Non-SwiftLink flag. </strong>
| <strong>Modem Input buffer empty flag</strong> (Read-Only) 
 
0 = Empty 
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
Non-zero = Characters pending
|-
|-
| !27
| !33
| <strong>Term buffer mode.</strong>
| <strong>X-Modem ASCII conversion mode</strong>
 
If non-zero, converts ASCII to PETSCII during transfer.
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.  
|-
|-
| !28
| !34
| <strong>Term buffer pointer. </strong>
| <strong>X-Modem CRC retry count</strong>
 
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.
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.  
|-
|-
| !29
| !35
| <strong>Term buffer bottom pointer. </strong>
| <strong>Punter block size</strong>
 
Sets the Block size in bytes for Punter protocol.
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.  
|-
|-
| !30
| !36
| <strong>Term buffer top pointer. </strong>
| <strong>Transfer file type</strong>
 
1 or 3 = PRG 
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.
2 = SEQ
|-
|-
| !31
| !37
| <strong>Current BPS rate. </strong>
| <strong>Current protocol</strong> (Read-Only)  
 
0 = Punter 
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. 
1 = X-Modem
|-
|-
| !32
| !38
| <strong>Input buffer empty flag. </strong>
| <strong>Transfer timeout flag</strong>
 
Non-zero after transfer complete indicates carrier or network timeout during transfer.
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.  
|-
|-
| !33
| !39
| <strong>X-Modem file conversion mode.</strong>
| <strong>Transfer abort status</strong>
 
Non-zero indicates aborted transfer.
If this is not 0, then the file being transferred will be converted from standard ASCII to PET ASCII.  
|-
|-
| !34
| !40
| <strong>Number of tries for X-Modem CRC mode.</strong>
| <strong>Input character count</strong>
 
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.
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.  
|-
|-
| !35
| !41
| <strong>Punter block size. </strong>
| <strong>Alternate output mode</strong>
 
If non-zero, BBS output is diverted to file #3.
This sets the number of bytes for the Punter file transfer blocks.  
* Affects BBS output only (BASIC PRINT commands unaffected).
|-
|-
| !36
| !42
| <strong>File type for transfer.</strong>
| <strong>Day of month</strong> (Read-Only) 
 
Updated by @16 function.
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.  
|-
|-
| !37
| !43
| <strong>Current protocol type.</strong>
| <strong>Month of year</strong> (Read-Only) 
 
Updated by @16 function.
The current protocols set this read-only value to 0 for Punter, and 1 for X-Modem.  
|-
|-
|!38
| !44
| <strong>File transfer timeout flag.</strong>
| <strong>AM/PM flag</strong> (Read-Only) 
 
0 = AM 
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 = PM
|-
|-
| !39
| !45
| <strong>End of transfer status.</strong>
| <strong>Current hour</strong> (Read-Only) 
 
Holds values 1–12, updated by @11.
If this is not zero at the end of the transfer, it means the transfer was aborted.  
|-
|-
| !40
| !46
| <strong>Number of input characters.</strong>
| <strong>Scratch register</strong>
 
General-purpose read/write variable. 
For keyboard input (.02 or @8) or disk input (.01 or @5), this value is the number of characters read in during input.  
See [[Undocumented_8.1_commands#bang46|Undocumented features: !46]].
|-
|-
| !41
| !47
| <strong>Alternate output file mode.</strong>
| <strong>Character output delay</strong>
 
May be used to slow output of the system for slower systems.
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.
0 = No delay  
255 = Maximum delay
|-
|-
| !42
| !48
| <strong>Day of the month. </strong>
| <strong>Fast garbage collect mode</strong>
 
If non-zero, enables fast string garbage collection. 
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.  
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.
|-
|-
| !43
| !49
| <strong>Month of year. </strong>
| <strong>Boot device numbers</strong> (Read-Only) 
 
A 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.
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
| !50
| <strong>PM/AM Flag. </strong>
| <strong>Boot drive numbers</strong> (Read-Only) 
 
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.
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.
|-
|-
| !45
| !51
| <strong>Current time hour. </strong>
| <strong>Disk swapping flag</strong> (Read-Only)
 
Defined by BOOTMAKER program.
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.  
0 = No swap required  
Non-zero = Disk swap required
See also !49, !50, and the function @30.
|-
|-
| !46
| !52
| <strong>Not used </strong>
| <strong>Most recent find location</strong> (Read-Only) 
Holds location result of @2 or @25 find functions.
|-
|-
| !47
| !53
| <strong>Character output delay. </strong>
| <strong>2 MHz FGC flag</strong>
 
If 1, C128 attempts 2 MHz mode during fast garbage collect. No effect on C64.
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.  
Automatically set for C128 users.
|-
|-
| !48
| !55
| <strong>Fast garbage collect mode. </strong>
| <strong>Message record delimiter flag</strong>
 
See [[Undocumented_8.1_commands#dot31|Undocumented features: .31]].
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).  
|-
|-
| !49
| !56
| <strong>Boot device numbers. </strong>
| <strong>Message editor command state</strong>
 
Indicates editor command mode.   
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.  
See [[Undocumented_8.1_commands#bang56|Undocumented features: !56]].
|-
|-
| !50
| !57
| <strong>Boot drive numbers.  </strong>
| <strong>Editor prefix trigger</strong>
 
Defines key entering editor command mode.   
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.  
See [[Undocumented_8.1_commands#bang57|Undocumented features: !57]].
|-
|-
| !51
| !58
| <strong>Disk swapping flag. </strong>
| <strong>Editor variable (Undocumented)</strong>
 
Under investigation.   
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.  
See [[Undocumented_8.1_commands#bang58|Undocumented features: !58]].
|-
|-
| !52
| !59
| <strong>Most recent find location. </strong>
| <strong>Text-entry mode flag (Editor)</strong>
 
Non-zero indicates text-entry-only state.   
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.
See [[Undocumented_8.1_commands#bang59|Undocumented features: !59]].
|-
|-
| !53
| !60
| <strong>Flag - 2Mhz during Fast Garbage Collect.</strong>
| <strong>Editor menu selection</strong>
 
Stores selected editor menu item.   
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.  
See [[Undocumented_8.1_commands#bang60|Undocumented features: !60]].
|}
|}
<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:01, 28 February 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 Description
!00 Carrier detect mode

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

!01 Status variable (Read-Only)

Status after input commands (.00, .02, @8). 0 = OK 1 = Aborted (CTRL/P) 3 = Pause (CTRL/S) 4 = Aborted (CTRL/X) 255 = Carrier lost

!02 General input/output character

Holds character returned by .00 or .07. Otherwise contains undefined data.

!03 Maximum column for word wrap

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 End-of-line character

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

!05 Translation mode

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

!06 Uppercase input constraint

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

!07 Word wrap mode

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

!08 Wrap/Width Threshold

See Undocumented features: !8.

!09 Character output 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 Line feed mode

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

!11 Carrier timeout flag

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 Local mode

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

!13 Inactivity timeout flag

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

!14 Disk input file number

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

!15 End-of-line override mode

If non-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.

!16 SEQ file 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 Pager line count

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

!18 ANSI mode

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

!19 MCI disable flag

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

!20 Caller log buffer status (Read-Only)

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

!21 Variable Stack Number (Read-Only)

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

!22 Network transfer timeout

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

!23 Non-SwiftLink BPS timer table

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 Carrier type

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

!25 Carrier status (Read-Only)

Non-zero if carrier detected.

!26 SwiftLink flag (Read-Only)

0 = Non-SwiftLink 1 = SwiftLink system

!27 Term buffer mode

If this is not zero, then all characters printed to the screen will also be put into the term buffer. • Parameters of the buffers are established by the !28, !29, and !30 variables. • Output is diverted to file number 3 (normally screen output). • Used by the Plusterm program.

!28 Term buffer pointer

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. • Used by the Plusterm program.

!29 Term buffer bottom pointer

16-bit address of first byte of buffer. Used by the Plusterm program.

!30 Term buffer top pointer

16-bit address of last valid byte. Used by the Plusterm program.

!31 Current BPS rate (Read-Only)

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

!32 Modem Input buffer empty flag (Read-Only)

0 = Empty Non-zero = Characters pending

!33 X-Modem ASCII conversion mode

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

!34 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 Punter block size

Sets the Block size in bytes for Punter protocol.

!36 Transfer file type

1 or 3 = PRG 2 = SEQ

!37 Current protocol (Read-Only)

0 = Punter 1 = X-Modem

!38 Transfer timeout flag

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

!39 Transfer abort status

Non-zero indicates aborted transfer.

!40 Input character count

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

!41 Alternate output mode

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

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

Updated by @16 function.

!43 Month of year (Read-Only)

Updated by @16 function.

!44 AM/PM flag (Read-Only)

0 = AM Non-zero = PM

!45 Current hour (Read-Only)

Holds values 1–12, updated by @11.

!46 Scratch register

General-purpose read/write variable. See Undocumented features: !46.

!47 Character output delay

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

!48 Fast garbage collect 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 Boot device numbers (Read-Only)

A 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.

!50 Boot drive numbers (Read-Only)

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 Disk swapping 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 Most recent find location (Read-Only)

Holds location result of @2 or @25 find functions.

!53 2 MHz FGC flag

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

!55 Message record delimiter flag

See Undocumented features: .31.

!56 Message editor command state

Indicates editor command mode. See Undocumented features: !56.

!57 Editor prefix trigger

Defines key entering editor command mode. See Undocumented features: !57.

!58 Editor variable (Undocumented)

Under investigation. See Undocumented features: !58.

!59 Text-entry mode flag (Editor)

Non-zero indicates text-entry-only state. See Undocumented features: !59.

!60 Editor menu selection

Stores selected editor menu item. See Undocumented features: !60.

Next Section: ML Functions

Programming Features

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