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 or block of data from disk. Uses the logical file number stored in !14. Input is stored in TX$ !40 is set to the number of characters read. The maximum number of characters that may be read is controlled by !08. The behavior of the end-of-line character in !04 is controlled by !15: Use of !15 If !15 is nonzero, input ends when the character stored in !04 is encountered. The ending character is consumed from the file but is not included in TX$. If !15 is zero, the character stored in !04 is ignored. Input continues until the maximum number of characters specified by !08 is read or the file status indicates the end of the file or another input condition. The normal settings for reading carriage-return-delimited lines are: !04,13:!15,1 Example: 1000 !04,13:!15,1 1010 .01 1020 IF !40<5 THEN 1010 This example reads carriage-return-delimited lines and repeats the read when fewer than five characters were returned. To read a block of data without stopping at the end-of-line character: !15,0:.01:!15,1 This temporarily disables end-of-line detection, performs the read, and then restores normal delimiter processing. Setting !04 to zero does not disable end-of-line processing. When !15 is nonzero, it makes a zero byte the ending character. 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	Input a Fixed Number of Bytes from a File Format: .03,<count>[,<skip>] Reads a fixed number of bytes from the logical file specified by !14 and stores them in TX$. <count> is the number of bytes to return and must be from 1 to 255. <skip> is optional. When specified, that number of bytes is read and discarded before the requested data is stored. !40 is set to <count>. The file remains open after the command. The current file status remains available through ST. Unlike .01, this command is not line-oriented: .01 reads until the end-of-line character in !04, the maximum length in !08, or a file-status condition. .03 ignores !04, !08, and !15. .03 does not stop at a carriage return or any other character. .03 always returns the requested number of bytes. If the file ends or another file-status condition occurs before all requested bytes are read, the remaining positions in TX$ are filled with CHR$(0). ST remains nonzero so the program can detect that the requested data was not completely available from the file. Do not use a count of zero. A zero count causes the internal byte counter to wrap and may overwrite memory. Example: 1000 !14,8 1010 .03,6 1020 A$=@0 This reads six bytes from logical file 8 into TX$ and places those six bytes in A$. Example with skipped bytes: 1000 .03,2,2 1010 A$=@0 This discards the first two bytes and returns the following two bytes.
.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	Display an open sequential file. Displays the contents of an already-open sequential file using the logical file number stored in !14. The file is sent through the normal Color 64 output system, including terminal translation, color and MCI processing, character velocity, and the page pauser controlled by !17. The caller may abort the display by pressing the spacebar or CTRL/P. In either case, !01 returns a value of 1. Set !16 to a non-zero value before using .12 to prevent these keys from aborting the display. !16 automatically resets to zero when .12 finishes. A negative value in !01, normally 255, indicates that the display ended because the carrier was lost or another terminal condition occurred. A value of zero indicates normal completion. The file remains open after .12 returns. Programs should use !01, rather than ST, to determine the result of the display. Example: OPEN8,DV,8,DR$+F$ !14,8 .12 P=!01 CLOSE8
.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. Example: 100 A=1:B$="OLD":DIM C$(10) 110 .18 120 D=4:E$="TEMP":DIM F$(20) 130 A=99 140 .19 After .19: A still equals 99 B$ still exists C$() still exists D no longer exists E$ no longer exists F$() no longer exists
.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-Record Line Reader and Delimiter Detector This routine is a wrapper around the .01 disk-input reader. It adds two message-oriented services: Detects a message-record divider consisting of a line whose only data byte is PETSCII $0E, Control-N. Appends a carriage return to ordinary records when the input buffer has room. The file must already be open under the logical file number stored in !14. For normal message record reading, expected inputs are !04,13 and !15,1 For .31 message scanning, !04 should normally remain carriage return. Output result is recorded in !55.
.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 If the specified BASIC line does not exist, .32 returns without changing the current DATA pointer. When .32 is used without a line number, place it at the end of the BASIC line rather than before a colon-separated statement.
.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 one to eight color control characters. These 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