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	Unused Non-functional.
.07	Unused Non-functional.
.08	Session/Input Poll Polls for typed input (non-blocking, local or remote) and updates P status It is typically used inside scrolling output or file-display loops and before slow operations. Resulting P status can be: 0 = OK 1 = User Abort 3 = Pause State 4 = User Aborted with CTRL-X 255 = Carrier Lost / Timeout
.09	Single-Key Command Input Poll The .9 command polls for a single keypress and stores the result in the BASIC string variable A$. It is used at the command prompt to capture one-character command input from either the local keyboard or the remote modem connection. The command can include a preset list of valid characters for acceptance: Example: .09,"YN" will only permit "Y" or "N" (or User Abort) as valid values. The ML Variable !52 will hold the result as well as A$. In the case of !52, the value is based on character position within the permitted string. So for the example above for "YN", if "Y" were selected, !52 would hold a value of 1. If "N" were selected, !52 would hold value of 2. A$ is set to the key pressed The character is stored in high-bit PETSCII format Example: Pressing "X" gives ASC(A$)=216 Pressing "O" gives ASC(A$)=207 (standard ASCII value + 128) When no key is pressed: A$="" The command does not block execution
.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	Install Relocatable ML Extension .15 will load ºbbs.trmml at the address held in A, then executes. There is no comma separation between the ".15" command and the value provided. This will also install the routines for .42, .43, .44 and .45 at the offset address based on the value provided in the .15 command.
.16	Remove Extension Output Hook</strong This routine is called by the terminal overlay program prior to reloading BBS.INIT.
.17	Append 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. Managed by the Terminal overlay. 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). Used by the Terminal overlay. DTR is a line to the modem which indicates the readiness of the computer to send and receive data. .21 = Activate .22 = Deactivate
.23	Unused Non-operational.
.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. Used in the Messages overlay when an abort command is received.
.26	Clear input buffer. Will clear all data holding in the modem input buffer. Discard all characters currently waiting in the resident modem input buffer, used in the Terminal overlay after file-transfer cleanup.
.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	Reset Page Counters (from !17) Used in the Messages overlay, this will reload the active pager counters from the configured !17 page length.
.37	Clear resident TX$ length	.38-.41 (high level)	Generic Bound-Array Register Engine These commands allow Color 64 BASIC to bind resident ML slots to ordinary BASIC arrays. After an array is bound, the ML can access an element through a short semicolon expression such as: 0F 1K 4L without asking BASIC to parse and calculate the array subscript every time. The engine is generic. BBS.MSGS uses it for message relinking, but the commands themselves are not limited to messages. The bound slots and typed offsets are accessed through the semicolon syntax. Examples: 0F 1K 0F=;0G 1K=II The syntax is: <slot><field> where: <slot> is the bound-array slot; <field> selects the offset register and required data type. Details of each specific command are below.
.38	Bind Basic Array to Resident Slot Examples from BBS.MSGS include: .38,0MN,1LK%,2MF%,3CA%,4MR% and: .38,0CA%,1NC% The digit identifies the resident slot. The following BASIC array name identifies the array to bind.
.39	Set Typed Array Offset Register Examples: .39,F1,G2,K1,L2 or: .39,KM Each field letter identifies an offset register. The numeric expression following it identifies the array element index.
.40	Advance Typed Array Offset Register .40FGKL No commas are required between the field letters. For each field, the command adds that field’s element size to its offset register. Examples: F advances by 5 G advances by 5 K advances by 2 L advances by 2 This is equivalent to advancing each selected register by one array element.
.41	Retreat Typed Array Offset Register 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.
.42	Terminal Mode Extension command installed by bbs.trmnl
.43	Terminal-Buffer Dump Extension command installed by bbs.trmnl
.44	Reserved Extension Entry Extension command installed by bbs.trmnl
.45	Reserved Extension Entry Extension command installed by bbs.trmnl

Next Section: ML Variables

Programming Features