earthrexx.library/InterfaceRexx NAME InterfaceRexx - Extract parameters from a RexxMsg SYNOPSIS Result = InterfaceRexx(RexxMsg,Format,Function) d0 d0 a0 a1 FUNCTION Extract the message arguments from a RexxMsg. This will usually (though not necessarily) be a function invokation message. Then call a user supplied function using the extracted parameters. INPUTS struct RexxMsg *RexxMsg This is the address of the message whose arguments you wish to extract. BYTE *Format This is the address of a null-terminated format string. This string controls the manner by which the message arguments are converted and mapped. See below for details on the legal syntax for this format string. APTR Function This is the address of a user-supplied function which will be called once the arguments have been extracted. RESULTS LONG Result If user function was called then this is a copy of the return value from that function. In this case machine code programmers will find the zero flag set. If the user function was NOT called (for instance, because the format string was syntactically invalid) then Result will contain -1. In this case machine code programmers will find the zero flag reset. ADDITIONAL INFORMATION The user-supplied format string controls the manner in which function arguments are mapped to machine code registers or C variables. The main elements of a format string are two-character escape sequences which begin with the percent symbol (%). These sequences are case-insensitive, so you can use either upper or lower case as you please. The complete list of such escape sequences are as follows: Message extraction escape sequences: %S The next argument is a string pointer. Copy this pointer. %P The next argument is a packed 4-byte argstring. Unpack into a LONG value. %I The next argument is the ASCII decimal representation of an integer. Convert to integer. %X The next argument is the ASCII hexadecimal representation of an integer. Convert to integer. %B The next argument is the ASCII binary representation of an integer. Convert to integer. Additional escape sequences: %M The address of the message itself. %N The number of function arguments. The message arguments are scanned from rm_Args[1] onwards, since rm_Args[0] is the function name. Let's take machine code programmers first: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is an example of a legal format string for machine code users: "a0=%s,a1=%p,d2=%i,d0=%i" The meaning of this string is almost self-evident. Specifically, it tells us that the first argment (rm_Args[1]) is a string, whose address is to be placed in machine code register a0; that the second argument (rm_Args[2]) is a packed 4-byte argstring whose unpacked value is to be placed in register a1; that rm_Args[3] is a decimal number stored as a string of ASCII characters, and that the value of this number is to be placed in d2; and finally that rm_Args[4] is also a decimal number - this one to be placed in register d0. Some parts of a format string can be omitted, in which case defaults are used. For instance, if the parameter type is omitted, then that argument is assumed to be a string (%S). So the above example could have been written: "a0,a1=%p,d2=%i,d0=%i" Furthermore, the register names can themselves be omitted, if your function conforms to Amiga standards - namely that address parameters are passed in A registers from a0 upwards, and that data parameters are passed in D registers from d0 upwards. For the record, %S, %P and %M are considered address parameters, while the remaining escape sequences are considered data parameters. So the above example could also have been written: ",%p,d2=%i,%i" Only the d2 register needed to be explicitly stated, since it occurred in the format string out of sequence. Any register not defined by the format string will be passed on to the user function unmodified. The function is allowed to corrupt ALL registers, as d2-d7/a2-a6 will be restored by the library. The value returned by your function in d0 will be passed on as the return value of InterfaceRexx(). In the current version of the library, spaces are not allowed in a format string. This may change in later versions. Now for C programmers: ~~~~~~~~~~~~~~~~~~~~~~ C programmers do not have access to machine code registers, so the library places the extracted parameters on the stack, ready for use by your function. To specify that your function was written in C, you must supply a format string whose first character is semi-colon (;). Aside from this opening semicolon, your format string will simply consist of a list of escape sequences, separated by commas. For example: ";%s,%p,%i,%i" The meaning of this string is equally self-evident. Specifically, it tells us that the first argment (rm_Args[1]) is a string, whose address is to be topmost on the stack; that the second argument (rm_Args[2]) is a packed 4-byte argstring whose unpacked value is to be placed next on the stack; that rm_Args[3] is a decimal number stored as a string of ASCII characters, and that the value of this number is to be placed third on the stack; and finally that rm_Args[4] is also a decimal number, to be placed fourth on the stack. Arguments are considered as string (%S) by default, so you can omit all %S escape sequences if you like. So the above example could also have been written: ";,%p,%i,%i" You could then declare your function like this: LONG userfunction(string,pointer,num1,num2) BYTE *string; APTR pointer; LONG num1; LONG num2; Your function then gets called with the parameters extracted from the message in the appropriate C variables. The value returned by your function will be passed on as the return value of InterfaceRexx(). In the current version of the library, spaces are not allowed in a format string. This may change in later versions. CAVEATS Each occurance of comma (,) in the format string advances the message argument number UNLESS the immediately preceeding escape sequence was %M or %N. In these cases the message argument number is not advanced. SEE ALSO userfuncs/UserFuncHandler()