home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Fish 'n' More 2
/
fishmore-publicdomainlibraryvol.ii1991xetec.iso
/
dirs
/
rxgen_459.lzh
/
Rxgen
/
rxgen.doc
< prev
next >
Wrap
Text File
|
1991-02-18
|
6KB
|
180 lines
TABLE OF CONTENTS
rxgen.library/GenOpenLib
rxgen.library/GenCloseLib
rxgen.library/GenACall
rxgen.library/Function Description Format
rxgen.library/GenOpenLib rxgen.library/GenOpenLib
NAME
GenOpenLib -opens an exec library from Arexx
SYNOPSIS
call GenOpenLib("library name",version)
FUNCTION
REQUIREMENTS: the ARexx variables
LIBS.libname
LIBS.libname.OPENCOUNT
should be properly initialized when you open the library for
the first time.
For example, if you want to open exec.library, use the
following clauses:
LIBS.EXEC = '0000 0000'x
LIBS.EXEC.OPENCOUNT = 0
Opens the specified library, using the specified version number.
If the library can be opened, its base will be stored in LIBS.libname,
and the open count (for GenOpenLib calls in the current program only)
will be incremented in LIBS.libname.OPENCOUNT
Failure to open the library will raise an ERROR
INPUTS
"library name" is the name of the library you want to open
(without .library suffix)
version is an integer
RESULT
You're not interested in the result (it is the opencount at this time,
but this is subject to change).
See above for side effects
EXAMPLE
LIBS.intuition = '0000 0000'x
LIBS.intuition.OPENCOUNT = 0
call GenOpenLib("intuition",0)
BUGS
Use of version not really tested.
Multiple uses with different version numbers are not supported.
rxgen.library/GenCloseLib rxgen.library/GenCloseLib
NAME
GenCloseLib -close a library from Arexx
SYNOPSIS
call GenCloseLib("libname")
FUNCTION
REQUIREMENTS: same as GenOpenLib, it is also better if the
library has been opened...
Closes a library that has been opened by GenOpenLib.
Will fail if the opencount of the library is <= 0, otherwise,
the library will be closed, and the opencount decremented. If the count
gets null, then the base of the library will be set to 0.
INPUTS
"libname" : the name of the library you want to close (what else ?)
RESULT
You're not interested in the result (it is the opencount at this time,
but this is subject to change).
See above for side effects
EXAMPLE
call GenCloseLib("intuition")
BUGS
Maybe.
rxgen.library/GenACall rxgen.library/GenACall
NAME
GenACall - call a function from ARexx
SYNOPSIS
something = GenACall("libname","fname",par,...)
FUNCTION
REQUIREMENTS:
the library should have been opened (see GenOpenLib)
the function fname should be defined by
LIBS.libname.fname = <description>
the format of the description is described later.
GenACall will check the base of the library, convert your parameters
following the description, and return (hopefully) the result.
If the library base is 0, the function will abort (ERROR).
If GenACall can't find the function description, it will abort.
INPUTS
"libname" the name of the library your function belongs to
"fname" the name of the function
par,... parameters for the real function call. Many types allowed,
check the format of the description
RESULT
A 32 bit word, hopefully a correct one...
EXAMPLE
pointer = GenACall("exec","FindPort",'FOO BAR')
BUGS
Surely. None found.
rxgen.library/Function Description Format
Description of the format:
Let's take an example to fix the ideas
LIBS.exec.FindPort='FE7A'x||S||'200A'x
Thus, the format is a string containing:
- two bytes for the offset of the function in the library
- a variable number of characters that describe the type of
conversion to be applied to the parameters
- a SPACE (here obtained by '20'x)
- a coding of the registers in which the parameters will be passed.
You don't have to find all this by yourself.
The FD2rxFD utility provided in this distribution is able to compute a
partial description from the FD.FILES (to be found on Extras disk).
Check the two directory variables in the program, and run
1> rx fd2rxfd exec
This will generate a file containing all (partial) function definitions
for the Exec library.
In this examples, the information given by the FD.FILES is
LIBS.exec.FindPort='FE7A'x||?||'200A'x
The question mark (?) is to be replaced by the proper type description.
Technical digression: the problem lies in the fact that datas in ARexx are
not typed. They all are represented by strings, with no way to determine
safely and systematically if a particular data is a "real" string, or
an integer, or a pointer.
You will have to find by yourself (consulting the proper docs) which kind
of conversion is needed.
In this version (1.0), the supported conversion are:
I the ARexx data represents an integer
It will be converted internally to a 32bit integer with the AREXX
function CVa2i().
Valid data examples: Invalid data:
1 'foobar'
324
S the ARexx data represents a string.
No conversion is applied. The pointer to the string is used as
an argument
Valid data: any
A the ARexx data represents a pointer.
It MUST be a 4-byte long string, containing the value of the
pointer (usual convention for pointers in AREXX).
The "raw" value of the data will be used.
Valid data examples:
'00 00 00 00'x
'00 00 06 76'x
In the example, the parameter is a port name, so the conversion should be S.
Register coding is
D0 D1 D2 D3 D4 D5 D6 D7 A0 A1 A2 A3 A4 A5 A6 A7
01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E ** **
A6 is reserved for library base
A7 is SP. Don't dare to use it.