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 a Fixed-Length String from a File Format: @29(<count>[,<skip>]) Reads and returns a string containing a fixed number of bytes from the logical file specified by !14. <count> is the length of the returned string and must be from 1 to 255. <skip> is optional. When specified, that number of bytes is read and discarded before the returned data is collected. The returned string is always exactly <count> bytes long. !40 is not changed by this function. The file remains open after the function. The current file status remains available through ST. The function does not use !04, !08, or !15, and does not stop at carriage returns or other delimiter characters. If the file ends or another file-status condition occurs before the requested number of bytes is available, the remainder of the returned string is filled with CHR$(0). Check ST when it is necessary to determine whether all bytes came from the file. Do not use a count of zero. Examples: A$=@29(6) Returns the next six bytes from the file. A$=@29(2,2) Discards two bytes and returns the following two bytes.
@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	Read File Bytes and Convert Them to a Numeric Value Format: @32(<count>[,<skip>]) Performs the same fixed-length file read as @29, then converts the returned byte string to a numeric value using the same internal conversion performed by @6. It is functionally equivalent to @6(@29(<count>[,<skip>])) but performs the read and conversion as one function. <count> is the number of bytes to read and must be from 1 to 255. <skip> is optional. When specified, that number of bytes is discarded before the bytes used for the numeric result are read. The logical file is selected by !14. !40 is not changed. The file remains open after the function. The current file status remains available through ST. Missing bytes following an end-of-file or other file-status condition are treated as zero bytes. Do not use a count of zero. Example: A=@32(2,2) This discards the first two bytes of a disk-directory record, reads the following two bytes, and returns their numeric value. This is commonly used to obtain the block count from a Commodore disk-directory entry. The same operation could be written as: A=@6(@29(2,2))
@33	Return Saved Input Color Returns a one-character string containing the PETSCII foreground-color control byte that was active when the most recent ML line-input operation began. It is used by the message editor to restore the input color after deleting temporary command prompts.

Next section: Basic Variables Table

Programming Features