RXFUNCADD | Make an external function available to be called. |
RXFUNCDROP | Make an external function no longer available. |
RXFUNCQUERY | Check if an external function is available to be called. |
RXFUNCERRMSG | Fetch an error message for the last error of RXFUNCADD(). |
Makes an external function available to be called.
result = RXFUNCADD(REXXname, DLLname, FUNCTIONname)
REXXname is the desired name that you would like to use when you call the function in your script. The name you use to call the function does not need to be the same as the real name of the function. It is recommended that you use all upper-case for this name. Be sure to enclose the name in quotes if you're directly supplying it to RXFUNCADD().
DLLname is the name of the DLL that contains the function. You do not need to put any .dll extension upon the name, although you may optionally do so for some operating systems. Upon some operating systems, DLLname may be case-sensitive. (ie, A DLL name of "Blort" is not the same as "blort"). If you know exactly where the DLL is located upon the system, you can supply the full pathname (ie, 'C:\MyDir\Blort"). Otherwise, the DLL must be located in a place where the operating system can find it. Be sure to enclose the name in quotes if you're directly supplying it to RXFUNCADD().
FUNCTIONname is the real name of the function. Upon some operating systems, this may be case-sensitive. (ie, A function name of "Blort" is not the same as "blort"). Be sure to enclose the name in quotes if you're directly supplying it to RXFUNCADD().
0 if the function is successfully made available to be called. If an error, a non-zero value is returned as so:
Value Meaning 10 There is already a function registered with REXXname. You cannot use the same REXXname for more than 1 function. Each must have a unique REXXname. 20 Couldn't get enough memory needed to perform this operation. 40 The DLLname you provided can't be found/loaded. Check the spelling you used. Upon some operating systems, letters may be case-sensitive. Also check that the DLL is located where the operating system can find it easily. If necessary, include the full path on the DLL name. 50 The FUNCTIONname you provided doesn't actually exist in the DLL. Check the spelling you used. Remember that letters are case-sensitive.
Before you can call a function in a DLL, it must be made available to be called either by calling RXFUNCADD(), or sometimes, a DLL will register some or all of its own functions thus bypassing the need for you to call RXFUNCADD() upon each function in that DLL you wish to call. Many DLLs will have one function that you must RXFUNCADD(), but when you call this one function, it automatically registers all of the other functions in that DLL. After a function has been made available to be called, you may call it just like any built-in function.
If an error occurs, the RXFUNCERRMSG() built-in will return an error message describing a detailed reason for the error. Reginald also raises a FAILURE condition if an error occurs. CONDITION('E') will return an error/sub-error number of 81.xx where xx is one of the error values shown above.
For every function that you RXFUNCADD(), you should also RXFUNCDROP() that function.
Some interpreters do not have this function.
RXFUNCADD('BLORT', 'mydll', 'myfunction') |
0 /* If successfully adds 'myfunction' in DLL 'mydll' to be called as BLORT() */ |
Makes an external function no longer available.
result = RXFUNCDROP(REXXname)
REXXname is the name that you used when you RXFUNCADD'ed this function.
0 if the function is successfully dropped. If an error, a non-zero value is returned as so:
Value Meaning 30 The function was not registered. (It may already have been dropped).
It is generally safe to attempt to drop a function that has not been RXFUNCADD'ed, or a function that has already been RXFUNCDROP'ed. But RXFUNCQUERY can be called first to see if a function is already available before attempting to drop it.
Some interpreters do not have this function.
RXFUNCDROP('BLORT') |
0 /* If successfully drops a function called as BLORT() */ |
Checks if an external function is available to be called.
result = RXFUNCQUERY(REXXname)
REXXname is the name that you used when you RXFUNCADD'ed this function.
0 if the function is currently available. Otherwise, a non-zero value is returned as so:
Value Meaning 30 The function is in the process of being registered, or has been dropped. 40 The function is not registered.
Some interpreters do not have this function.
RXFUNCQUERY('BLORT') |
0 /* If the BLORT() function is available to be called */ |
Fetch an error message for the last error of RXFUNCADD().
message = RXFUNCERRMSG()
None.
An error message associated with a preceding call for RXFUNCADD() or CHDIR(), or an empty string if there was no error.
This error message is gotten from the operating system, so it specifically identifies the reason why a call to RXFUNCADD() failed. The exact wording of the error message will vary on different operating systems.
For Reginald, RXFUNCERRMSG() can also be used to fetch an error message if an auto-loading Subcom Handler fails to auto-load.
Some interpreters do not have this function.