Ml command set

Programming Features - ML Command Set

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: 1000 .01:ifleft$(tx$,1)<>"*"then1000

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:

Color 64 v8.1.0a Overlays

CMD	Details
.00	Get a typed character. ASCII value is returned in ML Variable !02 (ASCII Value will be 0 (nu$) if no key was pressed All alphabetic characters are converted to uppercase (A through Z) Status is returned in ML Variable !01 Polls both local keyboard and remote connection for keypress Example: .00:P=!01:A$=CHR$(!02)
.01	Input a line of data from disk. 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: .01:SR=ST:A$=@0
.02	Input a line of text from the user. Reads from keyboard or remote user. Input ends with CR, CTRL/X, or CTRL/P. Returns: • Status in !01 • Character count in !40 • Text stored in TX$. May also use @0 or skip with @8. Example: .02:I$=@0
.03	Equivalent of the "$" command… Expression to be printed must follow the command after a " , " comma.
.04 / .05	Activate / Deactivate protected mode. .04 disables the RUN/STOP Key When in this condition, the program can only be stopped by holding down SHIFT/COMMODORE/CONTROL on the local keyboard. In the event of a system crash, a GOTO9991 which contains the code to reinitialize. The .05 command disables protected mode.
.06	Equivalent of the "#" command… … but the expression to be printed must follow the command after a " , " comma.
.07	Activate terminal mode. Invokes a basic terminal program (Plusterm) on the local system. 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. 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	Session/Input Poll Polls for typed input (non-blocking, local or remote) See Undocumented features/commands: .8
.09	Single-Key Command Input Poll Polls keyboard for a single keypress and returns value to A$ (with high-order bit). See Undocumented features/commands: .9
.10 / .11	Activate / Deactivate carrier-detect checking interrupt. .10 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. .11 deactivates the interrupt.
.12	Output a sequential file. The file number is stored in variable !14 and the file must already be opened. Set !16 to 1, to prevent user from aborting output; If set to zero, the output can be aborted by pressing the space bar or by typing CTRL/P. Set !17 to a non-zero value to activate page-pausing, where the value of !17 is the number of lines.
.13	Dump caller log buffer to disk. Dumps the temporary caller log buffer to disk file number 98 and clears the buffer. Intended to be used only by the normal BBS caller log routines.
.14	Set level parameters for MCI commands. Format: .14,<msg level>,<variable level> Uses the value of LV (user access level) for the current user's level, which is why LV must be one of the first variables defined. <msg level> = level for the message MCI's (£a0, £a1, etc.) Add a value of 128 to <msg level> to disable DD$ message MCI (£a6) printing <variable level> = level for the variable MCI command (£[) use
.15 / .16	Set the "Chat Begin" text. Not implemented in versions 8.1 or 8.10a.
.17	Put text into caller log buffer. Format: .17,<string> <string> = Text to be put in the temporary caller log buffer (usually the string is LG$). Used in conjunction with the variable !20 and the .13 command to handle caller log functions. Intended to be used only by the normal BBS caller log routines.
.18 / .19	Variable Stack / Killer Saves the current BASIC variable memory environment so it can later be restored with the .19 command. This command operates as a stack. Each time .18 is executed, the entire current variable state is pushed onto an internal stack and a new working environment becomes active. The previous environment remains preserved on the stack while the new environment may be freely modified. The .19 command pops the most recently saved environment off the stack and restores all variable values to that state. Up to eight stacked environments may exist simultaneously. Attempting a ninth consecutive .18 will generate an error. Variable Stack Example Stack Level Description A$ Value 1 Initial BBS environment after startup "Dog" 2 .18 executed, A$ modified "Cat" 3 .18 executed again, A$ modified "Dead Cat" Example Behavior: At Stack Level 1, variables are in their normal initialized state. Executing .18 saves this state and creates Stack Level 2. Variables may now be changed without affecting Level 1. Executing .18 again creates Stack Level 3. Stack Level 2 is now preserved on the stack. Variables may now be changed without affecting Levels 1 or 2. Executing .19 restores Stack Level 2 (A$ becomes "Cat"). Executing .19 again restores Stack Level 1 (A$ becomes "Dog"). Each .18 pushes a complete variable snapshot. Each .19 restores the most recently saved snapshot.
.20	Set BPS rate for computer to modem communications. Format: .20,<value> Values: 0–2 (non-SwiftLink) or 0–7 (SwiftLink) Maps to 300–38400 baud. Do not change during active session. Notes: • 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 / .22	Activate DTR (Data Terminal Ready). DTR is a line to the modem which indicates the readiness of the computer to send and receive data. .21 = Activate .22 = Deactivate
.23	Dump buffer contents. 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. Used by Plusterm.
.24	Wait for end of modem transmit. Ensures output buffer is empty. Used for non-Swiftlink systems.
.25	Cancel modem output. Cancel output and clear output buffer immediately.
.26	Clear input buffer. Will clear all data holding in the modem input buffer.
.27 / .28	Receive / Transmit a file using current protocol. Used by the BBS file transfer routines.
.29 / .30	Receive / Transmit a header block (multi punter). Used by the BBS file transfer routines.
.31 (& !55)	Message-Aware Disk Input Not documented in the original version 8.0 documentation. See Undocumented features/commands: .31 and !55 for more useless information.
.32	Set DATA Statement Line Number Functions similarly to the BASIC RESTORE command, but allows explicit control over the line number from which DATA statements will be read. If used by itself (.32), the DATA pointer is set to the current line. If used in the form .32,<number>, where <number> is a BASIC line number, the DATA pointer is set to begin reading DATA statements from that specified line. Example: .32,20000
.33	Activate Extra Variable Memory Mode By default, BASIC variable memory begins immediately after the last byte of the "√bbs.init" overlay. This fixed location allows other overlays to be loaded without disturbing variables. The .33 command relocates the start of BASIC variable memory to immediately after the last byte of the currently loaded overlay. This effectively increases available variable space by the size difference between the current overlay and "√bbs.init". This command must be used carefully. It should be paired with the variable stack commands (.18 / .19). When .34 is later executed, the variable area is moved back to its original location. If insufficient free space exists at that time, system data or string variables may be overwritten. See .34 for additional details.
.34	Deactivate Extra Variable Memory Mode Restores the normal variable memory location established by "√bbs.init", reversing the effect of .33. A .18 should precede each .33, and a corresponding .19 should precede each .34. This ensures variables are preserved and memory is safely returned to its original configuration. If .34 is not executed before "√bbs.init" is reloaded, a LOAD OVERFLOW error will occur. If insufficient free memory exists when .34 is executed, string variables may be overwritten.
.35	Set System Rainbow Mode Color List Defines the color sequence used by the system’s standard rainbow mode (such as the colors cycled by the F1 and F5 keys). Format: .35,<string> <string> must contain exactly eight color control characters. These eight characters determine the rainbow color rotation order.
.36	Unknown See Undocumented features/commands: .36 for more useless information.
.38	Bind / Declare / Register operands (Set up an ML-side descriptor for upcoming operations) Used in conjunction with .39-.40 for performing old-to-new message linking. Slot 0 points to MN, slot 1 points to MR%. ;0K, ;1K, ;0F, are scratch registers used. ;1K = Read flag for message. ;0F = Message number compared. See Undocumented features/commands: .38 for more information.
.39	Run an iterator/scan using the binding Used in conjunction with .38, .40 and .41 for performing old-to-new message linking. This populates the ";" scratch registers (;0F, ;1K, etc.) that the program loops test. See Undocumented features/commands: .38 for more information.
.40	Commit/Update step for the scan Used in conjunction with .38, .39 and .41 for performing old-to-new message linking. Invoked when a record should be skipped (read already or wrong category), “Advance/commit scan state for K" See Undocumented features/commands: .38 for more information.
.41	Finalize/Flush Step Used in conjunction with .38-.40 for performing old-to-new message linking. Wraps up the relink process. See Undocumented features/commands: .38 for more information.

Next Section: ML Variables

Programming Features