ML Functions

From Color 64 BBS Wiki

Programming Features - ML Functions

The ML functions provide operations that are more flexible than ML commands or ML variables. In practice, they behave like built-in BASIC functions: some execute an ML routine and then return a computed value. Functions can return either numeric or string results (including string values that cannot be returned through ML variables).

All ML functions begin with an "@" followed by one or two digits (the function number). Functions are either STRING or NUMERIC, as indicated in the table. Some functions accept required and/or optional parameters, which are placed in parentheses after the function number.

Example: 

1000 a$=@5:sr=st:a=val(a$):ifa<>0thenprint@1(a)
1010 ifsr=.then1000

In this example:

  • @5 reads a line from disk (like .01) and returns it as a string.
  • VAL() is used to test whether the returned line is numeric; if so, @1 prints the number without the leading space added by STR$ for positive values.
  • The loop continues until end-of-file (as indicated by ST).

All ML functions (@##) invoke address $4E21 for ML processing.

The table below lists the ML Functions and descriptions.

ML Function Descriptions
Function Format and Description
@0 Input Buffer Slice (TX$/!40)

Format: @0 : STRING
Equivalent to LEFT$(TX$,!40). Commonly used after disk input (.01) or keyed input (.02) when the input buffer is TX$ and the character count is in !40.
Example: .01:A$=@0

@1 STR$ Without Leading Space

Format: @1( <number> ) : STRING
Returns the equivalent of STR$(<number>) without the leading blank for positive numbers. Negative values retain the minus sign.
Examples:
@1(500) returns "500"
@1(-10) returns "-10"

@2 Find Substring (Forward)

Format: @2( <string1> , <string2> [ , <number> ] ) : NUMERIC
Searches for <string1> within <string2> from left to right and returns the 1-based position. Returns 0 if not found.
Optional <number> behavior:

  • If omitted: return position of first occurrence
  • If <number> > 0: return position of the <number>th occurrence
  • If <number> = 0: return the count of occurrences of <string1> in <string2>

Examples:

  • @2("b","abc") returns 2
  • @2("b","def") returns 0
  • @2("b","abcdabc",2) returns 6
  • @2("b","bobby",0) returns 3

The !52 variable stores the most recent find position (0 if the count form was used).

@3 Repeat First Character

Format: @3( <string> , <number> ) : STRING
Returns a string made of the first character of <string> repeated <number> times.
Example: @3("A",5) returns "AAAAA"
<number> range: 0–255. If <string> is null, returns null.

@4 Modem GET Character

Format: @4 : STRING
Modem input character (GET-style). Returns one character if available; otherwise returns a null string.
Example: A$=@4

@5 Read Disk Line (Returns String)

Format: @5 : STRING
Performs a disk line read (.01) and returns the resulting line as a string. Similar to @0, but executes the read first.
Example: A$=@5:SR=ST:PRINT#9,A$;

@6 Extended ASC / 16-bit Extract

Format: @6( <string1> [ , <string2> ] ) : NUMERIC
Extended ASC for 8-bit and 16-bit extraction. Behavior depends on argument form:

  • One string, length 0–1: returns PETSCII of first character; returns 0 if null string (no error).
 Example: GET#8,A$:I=@6(A$)
  • One string, length 2: returns 16-bit value from the first two characters (low byte = 1st char, high byte = 2nd char).
 Example: IF LEN(I$)=2 THEN L=@6(I$)
  • Two strings: treats first character of each as low/high bytes and returns a 16-bit value. Null strings are treated as 0.
 Example: GET#8,A$,B$:L=@6(A$,B$)
@7 Extended CHR$ (16-bit to 2 Bytes)

Format: @7( <number> ) : STRING
Extended CHR$. Returns a 2-character string containing the low byte then high byte of <number>. Useful for relative file positioning.
Example: PRINT#15,"p"CHR$(104)@7(RN)CHR$(1)

@8 Read Keyed Line (Returns String)

Format: @8 : STRING
Performs keyed line input (.02) and returns the resulting line as a string.
Example: I$=@8:P=!01:IF P=0 THEN RETURN

@9 Enhanced FRE()

Format: @9 : NUMERIC
Enhanced FRE(). Returns free memory as a positive value and does not force garbage collection; uses an internal calculation routine.
Example: I=@9:IF I>3000 THEN RETURN

@10 Strip Control/Graphics Codes

Format: @10( <string> [ , <number> ] ) : STRING
Returns <string> with graphics/control characters removed. Optional <number> returns only the first <number> characters (LEFT$-style).
<number> range: 0–255.
Example: A$=@10(@0,15)

@11 Get Time String

Format: @11 : STRING
Returns current time as "HH:MM am" or "HH:MM pm". Updates !45 (hour) and !44 (AM/PM flag: 0=AM, non-zero=PM).

@12 Overlay String / Replace at Position

Format: @12( <string1> , <string2> , <number> ) : STRING
Overlays <string1> onto <string2> starting at position <number> (1–255), replacing existing characters. Pads with spaces if needed.
Examples:

  • @12("there","Hello",7) returns "Hello there"
  • @12("*","++++++++",4) returns "+++*++++"

Special replace mode: if <number>=0, uses the most recent find position from @2 or @25. If that value is 0 (or if @2/@25 was used in count mode), an ILLEGAL QUANTITY error will occur.
Example (replace all "." with "/"):
1000 IF @2(".",I$)>0 THEN I$=@12("/",I$,0):GOTO 1000

@13 Capture Crash Error

Format: @13 : STRING
Crash routine helper: returns the BASIC error message text associated with the crash.

@14 Capture Crash Line Number

Format: @14 : STRING
Crash routine helper: returns the BASIC error line number as a string.

@15 Convert Date to ADN

Format: @15( <year> , <month> , <day> ) : NUMERIC
Returns an ADN (absolute day number) from year/month/day. Returns -1 if any parameter is invalid.

@16 Convert ADN to Year (Sets Month/Day)

Format: @16( <number> ) : NUMERIC
Converts ADN in <number> to a date and returns the year. Updates !43 (month) and !42 (day). Invalid ADN yields undefined results.

@17 Convert ADN to Day of Week

Format: @17( <number> ) : NUMERIC
Returns day-of-week from ADN in <number>: 0–6 for Sunday–Saturday.

@18 Convert ADN to Date String

Format: @18( <number> ) : STRING
Returns date string "MM/DD/YYYY" from ADN in <number>. If ADN is invalid, returns "--/--/----".

@19 Convert Date String to ADN

Format: @19( <string> ) : NUMERIC
Converts date string "MM/DD/YYYY" to ADN. Returns -1 if invalid.

@20 Current Overlay Filename

Format: @20 : STRING
Returns the filename of the BASIC overlay currently in memory (used by crash routines).

@21 Alpha-Only, Lowercase Filter

Format: @21( <string> ) : STRING
Returns <string> with all non-alphabetic characters removed and converts letters to lowercase.
Example: @21("This Is A Test") returns "thisisatest"

@22 Compress Number for Disk

Format: @22( <number> ) : STRING
Returns a compressed numeric string for disk storage by packing two digits per byte (approximately half-length of STR$ output). Uses a special encoding to avoid producing a carriage return character.
Example: PRINT#8,@22(I)

@23 Uncompress Number from Disk

Format: @23( <string> ) : NUMERIC
Inverse of @22: uncompresses a number stored in <string>. Invalid strings yield undefined results.
Example: INPUT#8,I$:I=@23(I$)

@24 Pad/Terminate Relative Record

Format: @24( <string> , <number> ) : STRING
Pads/truncates a record to length <number> for relative file use.

  • If <string> is shorter than <number>, pads with carriage returns to reach <number>.
  • If <string> is >= <number>, truncates to <number>-1 and appends a carriage return.

Null strings or <number><2 may yield undefined results.
Example: F$=F$+@24("name",15)

@25 Find Substring (Reverse)

Format: @25( <string1> , <string2> [ , <number> ] ) : NUMERIC
Same as @2, but searches from right to left (end of <string2> toward the beginning).

@26 Get Delimited Field

Format: @26( <string1> , <string2> , <number> ) : STRING
Returns the <number>th section of <string2> separated by the delimiter in <string1>.
Example: @26("!","cp6!i6!cd//directory",2) returns "i6"
<number> must be non-zero.

@27 Calendar Age from ADNs

Format: @27( <number1> , <number2> ) : NUMERIC
Returns calendar age in years between two ADNs: from <number2> to <number1>.
Example: AGE=@27(DA,BD)

@28 Find String in Array

Format: @28( <string> , <array> ) : NUMERIC
Searches a one-dimensional string array for an exact match to <string> and returns the index. Returns -1 if not found.
<Array> is the array name without "$" or parentheses (for example, pass A for A$()). Errors if array is missing or not 1-D.
Example: I=@28(A$,A):IF I<0 THEN #"not found!"

@29 Read N Characters

Format: @29( <number> ) : STRING
Reads <number> characters (GET#-style). Does not stop at EOF and does not stop at the end-of-line character in !04.

@30 Boot Drive Init Command

Format: @30( <number> ) : STRING
This function is used in conjunction with the variables !49, !50, and !51. It returns the drive init command for one of the three boot drives: 0=Boot drive, 1=Program drive, 2=External drive.

@31 Sequential Read (Enhanced)

Format: @31 : (Undocumented)
Newer function (not documented in the v8.0 manuscript). See Undocumented features: @31.

@32 Retrieve File Block Count

Format: @32 : (Undocumented)
Newer function (not documented in the v8.0 manuscript). See Undocumented features: @32.

@33 Return 1-Byte Null String

Format: @33 : (Undocumented)
Newer function (not documented in the v8.0 manuscript). Returns a single-byte null string (CHR$(0)). See Undocumented features: @33.

Next section: Basic Variables Table

Programming Features

Retrieved from "https://www.color64wiki.itchybutt.org/index.php?title=Ml_functions&oldid=910"