.Fortran
Call a Fortran or C Routine
Description
Returns the values of objects after the call to the Fortran or
C subroutine.
Usage
.Fortran(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING)
.C(.NAME, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING)
Arguments
| .NAME |
a character string giving the name of a Fortran or C routine to be called
as it is stored in the export table of the dll where the rotuine resides.
Fortran names should be lowercase without underscore, however with .Fortran
TIBCO Enterprise Runtime for R will attempt some extended name matching to account for possible Fortran
compiler name case and underscore mangling.
|
| ... |
arguments to the subroutine.
There must be exactly as many such arguments as the subroutine
expects. They must agree in storage mode and length with the
arguments to the Fortran or C subroutine as written. See the
Details section below for more information. A mismatch
may lead to undefined behavior. TIBCO Enterprise Runtime for R does not limit the number
of arguments that can be passed to a .C or .Fortran call on most
platforms.
Arguments can have any name except NAOK, DUP,
PACKAGE, or ENCODING which are reserved (see below).
Arguments can be of any class that contains the desired vector,
in particular, they can be matrices or multi-way arrays.
The returned components retain these attributes, although
the C or Fortran subroutine called will be ignorant of them.
|
| NAOK |
a logical flag. If FALSE (the default), an error is
generated if any missing values or NaN (Not a Number)
or Inf (Infinite) values are found in any argument before
calling the subroutine. If TRUE, these values are allowed
in the arguments passed to the C or Fortran subroutine.
Use is.nan to distinguish between Not a Number
and standard missing values.
|
| DUP |
a logical flag. If TRUE (the default), a copy of each argument's data
vector is made before it is passed to the subroutine, so the subroutine
can modify the contents without modifying the exisitng object data.
If FALSE, the arguments are not copied, thus saving memory, however
care must be exercised when using this setting; as FALSE may potentially
affect other evaluations. An error is generated if this argument is FALSE,
and any data argument is a string vector.
|
| PACKAGE |
a character string.
The name of a package which contains the specified C or Fortran routine.
The search for the routine will be limited to the package.
|
| ENCODING |
a single character string specifying the encoding of character strings.
The value of this argument is currently ignored. The name is reserved and
may be used in the future. It is provided for compatibility with R.
|
Details
The storage modes correspond to the C types and Fortran types
as follows:
|
| Storage Modes | | C Types | Fortran Types |
|
| logical | | int * | logical, |
|
| character | | char ** | character*(*) |
|
| integer | | int * | integer |
|
| single | | float * | real |
|
| double | | double * | double precision |
|
| complex | | struct {double re,im;} * | double complex
|
(
double complex is a complex datum composed of double
precision parts and might not be available on some older Fortran
compilers.)
The calling function must coerce the arguments to the required data types,
calling coercion functions such as as.double.
The return value (if any) of a C or Fortran function is not transmitted back to the caller
of .C or .Fortran, so C routines should be of type void, and Fortran routines should be
implemented as subroutines. All returned data must be transmitted back via the argument list.
Value
returns a list of the actual arguments to the C or Fortran routine
with any changes it makes to the data vectors. Normally the subroutine
will overwrite some of the data to return the results if its
computations. The returned components retain the class of the original
argument. For example, a supplied matrix is returned as a matrix
with the same structure, but possibly with modified data values.
The names attribute of the list is the names
of the "..." arguments.
Warning
These functions do not use normal S function argument matching.
The named arguments are listed above for convenience, but these
functions would more appropriately have a signature of
....
The differences from the normal argument matching rules are:
- The first argument must be the name of the Fortran
or C subroutine. If the first argument is named with anything other
than 'name' or a prefix of 'name', an error is
generated.
- The other named arguments in the function signature
(NAOK, and so on) can each appear more than once in the
function call. If one of these arguments is given more than once,
a warning is generated and the last specified value is used.
Limitations
Only the first element of a vector of character strings can be passed to Fortran
subroutines. String argument handling in Fortran is also compiler specific, e.g.
hidden arguments are used for handling string lengths, and passing string arguments
to Fortran routines should be done with care, generally avoiding it where possible.
SDifferences between TIBCO Enterprise Runtime for R and Open-source R
The argument "ENCODING" is reserved and may be used in the future in TIBCO Enterprise Runtime for R.
See Also
Examples
# a function that calls a Fortran subroutine that takes a double
# precision array and its length
function(x) {
z <- .Fortran("mycalc", ans=x, length(x))
return(z$ans)
}