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. Polls both the local keyboard and remote connection for a keypress. The resulting character value is returned in ML Variable !02. If no key was pressed, !02 is zero. Alphabetic characters are converted to uppercase. Input status is returned in ML Variable !01. Example: .00:P=!01:A$=CHR$(!02))
.01	Input a line or block of data from disk. Reads data from the logical file number stored in !14 and places it in the resident TX$ buffer. The maximum number of characters that may be returned is controlled by !08. The number of characters actually returned is stored in !40. 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 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 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 delimiter detection, performs the read, and then restores normal delimiter processing. Setting !04 to zero does not disable delimiter processing. When !15 is nonzero, a zero byte becomes the ending character. If !40 is less than the maximum input length in !08, the read normally ended because the !04 delimiter was encountered or file status became nonzero before the maximum length was reached. The returned data may be accessed through TX$ or the @0 function: .01=ST$=@0 The @5 function may also be used when disk data is to be assigned directly to a BASIC string variable without first executing .01.
.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
.09	Single-Key Command Input Poll The .09 command polls for a single keypress and stores the result in the BASIC string variable A$. Without an acceptance string, the command is nonblocking: .09 If no character is available, A$ is set to a null string. The command may also include a list of accepted characters: .09,"YN" When an acceptance string is supplied, .09 continues polling until an accepted character is received or an abort, timeout, or carrier-loss condition occurs. A$ contains the accepted character. !52 contains the one-based position of that character within the acceptance string. For example, with: .09,"YN" Y returns !52=1 and N returns !52=2. The character stored in A$ is normally in high-bit PETSCII form. For example, pressing X may return ASC(A$)=216.
.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 BBS.TERM loads ºbbs.trmml at the address held in A, then executes: .15A There is no comma between the .15 command and the address expression. The .15 command does not load the extension file. It relocates and installs an extension that has already been loaded into memory. For ºbbs.trmml, it installs: !27 through !30 .42 through .45 It then transfers control to the extension’s initialization routine.
.16	Remove Extension Output Hook Restores the normal Color 64 output path after the relocatable terminal extension has been used. BBS.TERM calls .16 before reloading BBS.INIT. The command removes the active output hook but does not erase the loaded extension code or clear its command-table entries.
.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 & Array Table Stack .18 records the current sizes of the BASIC scalar-variable and array tables. .19 removes variables and arrays created since the matching .18 and compacts the retained tables. Existing variables that were modified after .18 keep their modified values. The commands do not save or restore complete copies of variable contents. The commands operate as a stack and support up to eight nested levels. Attempting a ninth consecutive .18 generates an OUT OF MEMORY 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 / Deactivate DTR (Data Terminal Ready). Used by the Terminal overlay. DTR, or Data Terminal Ready, is the modem-control line used by the computer to indicate that it is ready for communications. .21 activates DTR. .22 deactivates DTR and clears related resident modem state.
.23	Unused Non-operational.
.24	Wait for end of modem transmit. Waits until the currently active modem transmission has completed. This command does not discard queued output and does not contain its own timeout. It is primarily used by non-SwiftLink communication routines.
.25	Cancel modem output. Discards modem output that is still waiting in the transmit queue. After clearing the queued output, the command waits for any byte already being transmitted to finish. Used by overlays when a user aborts an output operation.
.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 Sets the active resident TX$ length to zero. This also makes !40 equal zero and causes @0 to return a null string. The old bytes in the resident TX$ memory area are not erased, but they are no longer considered part of the active string.
.38-.41 (high level)	Generic Bound-Array Register Engine These commands allow Color 64 BASIC to bind resident ML slots to ordinary BASIC arrays and access their elements without repeatedly calculating BASIC array subscripts. Bound array elements are accessed with the semicolon syntax: ;0F ;1K ;4L Assignment examples: ;0F=;0G ;1K=II The syntax is: ;<slot><field> The slot identifies the bound BASIC array. The field identifies a resident offset register and its expected array type.
.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 Registers Format: .39,<field><index expression>[,<field><index expression>...] Examples: .39,F1,G2,K1,L2 .39,K5 .39,KM Each field letter identifies a resident offset register. The numeric expression following the letter identifies the desired array element index. The ML converts that element index into a byte offset according to the field’s predefined element size: A through E: string descriptors, 3 bytes F through J: floating-point values, 5 bytes K through O: integer values, 2 bytes For example, .39,K5 sets register K to the byte offset for integer-array element 5.
.40	Advance Typed Array Offset Registers Format: .40<field list> Example: .40FGKL No commas are placed between the field letters. Each field letter identifies a resident offset register. The letter also selects a predefined element size: A through E: 3 bytes F through J: 5 bytes K through O: 2 bytes The values 3, 5, and 2 are stored in an internal ML table. They are not written in the .40 command. For each listed field, .40 adds that field’s predefined element size to its current byte offset. This advances the field register by one array element. Therefore: F advances by 5 bytes G advances by 5 bytes K advances by 2 bytes L advances by 2 bytes Example: .39,F1,G2,K1,L2 .40FGKL After .40FGKL: F moves from element 1 to element 2 G moves from element 2 to element 3 K moves from element 1 to element 2 L moves from element 2 to element 3
.41	Retreat Typed Array Offset Registers Format: .41<field list> Example: .41FGKL No commas are placed between the field letters. .41 uses the same internal element-size table as .40, but subtracts the selected field’s element size from its current byte offset. Therefore: F retreats by 5 bytes G retreats by 5 bytes K retreats by 2 bytes L retreats by 2 bytes This moves each selected field register backward by one array element. .41 does not finalize or commit an array operation. Message-relinking routines use it when scanning backward through bound arrays, but the command itself is a generic typed-offset operation.
.42	Terminal Mode Extension command provided by ºbbs.trmml and installed through .15. Runs the terminal extension’s interactive local and remote character loop.
.43	Terminal-Buffer Dump Extension command provided by ºbbs.trmml and installed through .15. Writes the captured terminal buffer to the output file selected by BBS.TERM.
.44	Reserved Extension Entry Reserved command entry provided by ºbbs.trmml and installed through .15. The supplied terminal extension directs this command to an RTS instruction.
.45	Reserved Extension Entry Reserved command entry provided by ºbbs.trmml and installed through .15. The supplied terminal extension directs this command to an RTS instruction.

Next Section: ML Variables

Programming Features