Ml functions

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