View source for Ml command set

[[programming features|Programming Features]] - <strong>ML Command Set</strong>

The ML commands are a way for BASIC to access the faster and more powerful subroutines built into the Color 64 ML.  Some of these commands do complex things and are very useful (such as getting a line of typed input), while others aren't used very often (enabling and disabling interrupts).  

All ML commands begin with " . " period character, followed by two digits. Some commands require additional parameters, which follow the command after a " , " comma.    

Example: <strong>1000 .01:ifleft$(tx$,1)<>"*"then1000 </strong>

In this example, the .01 command reads a line of input in from disk, then if the input line did not begin with an asterisk, it would loop back and read another line.  This is also an example of how some of the input commands use TX$ as a buffer for input. The table below provides a summarized listing of all the ML commands:  

{| class="wikitable
|-
|+Color 64 v8.1.0a Overlays
! CMD
! Details
|-
| .00 
| <strong>Get a typed character. </strong>

This command does not wait for a key to be pressed but looks to see if a character has been typed.  Input is accepted from the BBS system keyboard or from the user currently online.  The ASCII value of the character is returned in !02, and the status is returned in !01.  The ASCII value will be 0 (nu$) if no character has been typed.  All alphabetic characters are converted to uppercase (A through Z).   

Example: <strong>.00:P=!01:A$=CHR$(!02) </strong>
|-
| .01 
| <strong>Input a line of data from disk. </strong>

The file number in !14 used.  End of line (EOL) is reached if:  
* Maximum number of characters (length of TX$) is read in or  
* The character stored in !04 is reached (usually set to a carriage return), unless !15 is set to non-zero, then !04 will not end input.  

Data is stored in TX$ starting at the first character.  The number of characters input is stored in !40.  If EOL was reached at the !04 character, such character will not be included in TX$ (e.g. a carriage return will not be part of the input line).  If !40 is less than the length of TX$, then the line was terminated with the !04 character or the end of file was reached before another !04 character.       

You can access the information by using TX$, the @0 function, or you can use the @5 function if you want to assign disk data directly to a variable (and skip the .01 command).  
Example: <strong> .01:SR=ST:A$=@0 </strong>
|-
| .02 
| <strong>Input a line of text from the user. </strong>

Input is accepted from the BBS system keyboard or from the user currently online.  The maximum number of characters to input is the length of TX$.  Input is terminated with a carriage return, or by pressing CTRL/X or CTRL/P.  The status is returned in !01.  The number of characters typed is returned in !40. The information is stored in TX$ starting at the first character.  If !40 is less than the length of TX$, then the line was terminated with a carriage return.  Otherwise, input was ended because the maximum number of characters was reached.  You can access the text by using TX$, the @0 function, or you can use the @8 function to skip the .02 command. 

Example: <strong> .02:I$=@0 </strong>
|-
| .03 
| Equivalent of the "$" command… 

… but the expression to be printed must follow the command after a " , " comma.  
|-
| .04 
| <strong>Activate protected mode. </strong>

RUN/STOP will be disabled, and the program can only be stopped by holding down SHIFT/COMMODORE/CONTROL.  If the system crashes, a GOTO9991 will be initiated.  Line 9991 should contain the code to execute after a system crash.  The .05 command disables protected mode. 
|-
| .05 
| <strong>Deactivates protected mode. </strong>

See the .04 command for more information. 
|-
| .06 
| <strong>Equivalent of the "#" command… </strong>

… but the expression to be printed must follow the command after a " , " comma.  
|-
| .07 
| <strong>Activate terminal mode. </strong>

Terminal mode (or Term mode) is a basic terminal program which allows the Sysop to dial out to other systems. Term mode will end if the Sysop presses any of the function keys (F1 through F8).  The ASCII value of the function key pressed is return in !02.  The Plusterm program makes use of the built-in buffer functions (see .23, !27, !28, !29, and !30).  Local mode (!12) must not be on, and DTR must be enabled. 
|-
| .08 
| <strong>Equivalent of the "%" command…  </strong>

… but the expression to be printed must follow the command after a " , " comma. 
|-
| .09 
| <strong>Equivalent of the "&" command… </strong>

… but the expression to be printed must follow the command after a " , " comma.  
|-
| .10 
| <strong>Activate carrier-detect checking interrupt.   </strong>

This activates an interrupt (a program which is executed every 1/60 of a second), which performs the functions necessary to check the status of the modem's carrier detect line.  It also handles the Network file transfer timeout, the carrier detect timeout, and the inactivity timeout.  Related variables are !13, !22, !00, !11, !24, and !25.  The .11 command disables the interrupt. 
|-
| .11 
| <strong>Deactivate carrier interrupt.  </strong>

See the .10 command for more information. 
|-
| .12 
| <strong>Output a sequential file. </strong>

The file number is stored in !14 and the file must already be opened.  If !16 is set to 1, the file cannot be aborted. If !17 is set to non-zero, then the page-pauser will be active and !17 is the number of lines.  The file can be aborted by pressing the space bar or by typing CTRL/P. 
|-
| .13 
| <strong>Dump caller log buffer to disk. </strong>

This will dump the temporary caller log buffer to disk file number 98 and clear the buffer.  This command is intended to be used only by the normal BBS caller log routines, and the system could crash if this command is used outside of this routine. 
|-
| .14 
| <strong>Set level parameters for MCI commands. </strong>

This command sets the levels for the use of the MCI commands.  The system uses the value of LV for the current user's level, which is why LV must be one of the first variables defined.  The command is in the format .14,<number1>,<number2> where <number1> is the level for the message MCI's (£a0, £a1, etc.), and <number2> is the level for the variable MCI command (£[).  If <number1> has 128 added to it, then the DD$ message MCI (£a6) is disabled (i.e. will not print anything). 
|-
| .15 
| <strong>Set the "Chat Begin" text.  </strong> 

This is not functional in versions 8.1 or 8.10a.
|-
| .16 
| <strong>Set the "Chat End" text. </strong>

This is not functional in versions 8.1 or 8.10a.
|-
| .17 
| <strong>Put text into caller log buffer.</strong>

This command is in the form .17,<string>, where <string> is the text to be put in the temporary caller log buffer (usually the string is LG$).  This command is used in conjunction with the !20 variable and the .13 command to handle caller log functions.  This command is intended to be used only by the normal BBS caller log routines, and the system could crash if this command is used outside of these routines. 
|-
| .18 
| <strong>Set up variable-killer. </strong>

This command causes the current variable memory configuration to be "memorized" by the system.  Later, when you use the .19 (Activate variable-killer) command, this information will be used to kill all new variables added to memory since the .18 command was used.  If you use more than one .18 before another .19, then the memory configurations will be "stacked" so that an .18/.19 pair can be "nested" inside another .18/.19 pair.  This allows a subroutine to use temporary variables and discard them without disrupting another routine's temporary variables.  Up to eight .18 commands can be stacked, and an error will result if a 9th consecutive .18 command is issued. 
|-
| .19 
| <strong>Activate variable-killer.</strong>

Kills all the variables added since an .18 command.  See the .18 command description for information on how the variable killer works. 
|-
| .20 
| <strong>Set BPS rate for computer to modem communications.</strong>

This command is in the format .20,<number> where <number> is a value from 0 to 2 for non-SwiftLink systems or 0 to 7 for SwiftLink systems.  The values correspond to the BPS rates 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400 respectively.  For non-SwiftLink systems, the BPS rate will be set to 2400 if any value above 2 is used.  For SwiftLink systems, the BPS rate will be set to 38400 if a value above 7 is used.  Once a BPS rate is set when a user is online, it should not be changed until the user disconnects. 
|-
| .21 
| <strong>Activate DTR (Data Terminal Ready).</strong>

DTR is a line to the modem which indicates the readiness of the computer to send and receive data.  If DTR is active, then all input/output functions are normal.  This is used in conjunction with .22 to control the DTR line. 
|-
| .22 
| <strong>Deactivate DTR.</strong>

Turning off DTR can have varying effects.  The most favorable effect is to cause the modem to hang up if on-line and return to command state (ready for AT commands).  In this case, it is best to have the DTR question in Setup set to YES.  Otherwise, the modem may just ignore the DTR signal, reset, or even something else depending on how the modem is set up.  99% of the time, though, the .22 command has a beneficial effect (there have not been any major problems).  Since disabling DTR on a SwiftLink system also disables all input and output, the DTR line is switched off momentarily. 
|-
| .23 
| <strong>Dump buffer contents.</strong>

This function dumps the contents of the Term mode buffer to file number 3.  The Sysop can press the space bar or CTRL/P to abort if output is directed to the screen.  See for more information.  This command is used by the Plusterm program. 
|-
| .24 
| <strong>Wait for end of modem transmit.</strong>

On non-SwiftLink systems, there is an output buffer which stores characters waiting to be sent over the modem. This command will wait for the buffer to be completely emptied, thus ensuring that no data will be lost if some other type of modem command is to be issued.  SwiftLink systems don't use an output buffer. 
|-
| .25 
| <strong>Cancel modem output. </strong>

Unlike the above command, which waits for the output buffer to clear, this will cancel the output immediately and clear the buffer. 
|-
| .26 
| <strong>Clear input buffer.</strong>

Will clear all data holding in the modem input buffer.  Ensures a clean slate for another input command. 
|-
| .27 
| <strong>Receive a file using current protocol.</strong>

Used by the BBS file transfer routines. 
|-
| .28 
| <strong>Transmit a file using current protocol.</strong>

Used by the BBS file transfer routines. 
|-
| .29
| <strong>Receive a header block (multi punter).</strong>

Used by the BBS file transfer routines. 
|-
| .30 
| <strong>Transmit a header block (multi punter).</strong>

Used by the BBS file transfer routines. 
|-
| .31 
| <strong>Used, but undocumented.</strong> 

See “Undocumented / Unknown ML Variables, Commands and Basic Shortcuts” section in the Appendices. 
|-
| .32 
| <strong>Set DATA statement line number. </strong>

Acts as a RESTORE command but allows you to set the line from which DATA statements will be read.  If used by itself, the DATA pointer will be set to the current line.  If used in the form .32,<number> where <number> is a line number, then the DATA pointer will be set to that line.  

Example: <strong>.32,20000 </strong>
|-
| .33 
| <strong>Activate extra variable memory mode.</strong>

Most of the time, system memory is set up so that BASIC variables always begin at the same place while the BBS program is running.  This place is located after the end of the last byte of the "√bbs.init" overlay, which allows other overlays to be loaded without overwriting variable memory.  The .33 command will cause the variables section to be moved to after the last byte of the current overlay in memory.  This means that if the current program is 10000 bytes smaller than "√bbs.init", there will be 10000 more bytes of free variable memory opened up after the .33 command.  This command should be used in conjunction with the variable-killer commands, because the .34 command will close this extra space and if there is not enough space free, a lot of system information could be overwritten.  See the .34 command for more information. 
|-
| .34 
| <strong>Deactivate extra variable memory mode.</strong>

This closes the extra memory opened by the .33 command.  A .18 should precede every .33 command, and a .19 should precede every .34 command.  This will ensure that memory is returned to its original state.  If the .34 command is not issued before the "√bbs.init" overlay is loaded, then a LOAD OVERFLOW error will occur.  If there is not enough space free before the .34 command is issued, then string variables will be overwritten. 
|-
| .35 
| <strong>Set system rainbow mode color list.</strong>

This command sets the colors that the system will use for the standard rainbow colors (i.e. the ones used by the F1 and F5 characters).  The format of the command is .35,<string> where <string> is a string of 8 color control characters. 
|}

Next Section: [[#ml variables|ML Variables]]

[[programming features|Programming Features]]