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.

There are 22 string-returning functions & 12 numeric-returning functions.

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	Resident Input Buffer 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	Number to String 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	Forward Substring Search 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 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	Character Input Format: @4 : STRING Input character (GET-style). Returns one character if available; otherwise returns a null string. Example: A$=@4
@5	Read Disk Record 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	Byte or Word Extraction 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	Word to Two-Byte String 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	Interactive Line Input 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	Free Memory Without Garbage Collection 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 and Graphics Characters 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	Current 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 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	Crash Error Message Format: @13 : STRING Crash routine helper: returns the BASIC error message text associated with the crash.
@14	Crash Error Line Number Format: @14 : STRING Crash routine helper: returns the BASIC error line number as a string.
@15	Date to Absolute Day Number Format: @15( <year> , <month> , <day> ) : NUMERIC Returns an ADN (absolute day number) from year/month/day. Returns -1 if any parameter is invalid.
@16	Absolute Day Number 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	Absolute Day Number to Day of Week Format: @17( <number> ) : NUMERIC Returns day-of-week from ADN in <number>: 0–6 for Sunday–Saturday.
@18	Absolute Day Number to to Date String Format: @18( <number> ) : STRING Returns date string "MM/DD/YYYY" from ADN in <number>. If ADN is invalid, returns "--/--/----".
@19	Date String to Absolute Day Number 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	Alphabetic 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 Storage 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	Expand Compressed Number 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	Format Relative-File 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	Reverse Substring Search Format: @25( <string1> , <string2> [ , <number> ] ) : NUMERIC Same as @2, but searches from right to left (end of <string2> toward the beginning).
@26	Extract 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	Calculate Calendar Age Format: @27( <number1> , <number2> ) : NUMERIC Returns calendar age in years between two ADNs: from <number2> to <number1>. Example: AGE=@27(DA,BD)
@28	Search One-Dimensional String 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 Fixed-Length Byte String 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	Build Boot-Drive Initialization 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	Enhanced Message-Record Read Format: @31 : (Undocumented) Newer function (not documented in the v8.0 manuscript). See Undocumented features: @31.
@32	Read Fixed-Length 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 This command accepts no arguments and 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. Useful for character deletion, cursor movement, backward color-state reconstruction, prompt removal, and redisplay of edited text.

Next section: Basic Variables Table

Programming Features