Rappture/Fortran? API
Currently in development are the fortran bindings to the Rappture Development Toolkit.
Function and Subroutine Index:
-- Rappture I/O --
integer rp_lib (character path)
call rp_lib_element_comp (integer handle, character path, character retText)
call rp_lib_element_id (integer handle, character path, character retText)
call rp_lib_element_type (integer handle, character path, character retText)
integer rp_lib_element_obj (integer handle, character path)
integer rp_lib_children (integer handle, character path, character prevChildHandle)
call rp_lib_get (integer handle, character path, character retText)
call rp_lib_get_str (integer handle, character path, character retText)
double rp_lib_get_double (integer handle, character path)
integer rp_lib_get_integer (integer handle, character path)
integer rp_lib_get_boolean (integer handle, character path)
call rp_lib_put_str (integer handle, character path, character value, integer append)
call rp_lib_put_data (integer handle, character path, character bytes, integer nbytes, integer append)
call rp_lib_put_file (integer handle, character path, character fileName, integer compress, integer append)
call rp_lib_node_comp (integer handle, character retText)
call rp_lib_node_type (integer handle, character retText)
call rp_lib_node_id (integer handle, character retText)
call rp_lib_xml (integer handle, character retText)
call rp_result (integer handle)
-- Rappture Units --
integer rp_define_unit (character unitName, integer basisName)
integer rp_find (character searchName)
call rp_get_units (integer unitRefVal, character retText)
call rp_get_units_name (integer unitRefVal, character retText)
integer rp_get_exponent (integer unitRefVal, double retExponent)
integer rp_get_basis (integer unitRefVal)
integer rp_units_convert_dbl (character fromVal, character toUnitsName, double convResult)
integer rp_units_convert_str (character fromVal, character toUnitsName character retText)
integer rp_units_add_preset (character presetName)
-- Rappture Utils --
integer rp_utils_progress (integer percent, character message)
Code Synopsis & Examples:
integer rp_lib (character path)
Purpose:
Retrieve an object reference (handle) to the file pointed to by path for accessing member functions of Rappture
Input Arguments:
- character path - non-null c style string providing the path to an xml file
Return Value:
User reference (handle) to the Rappture library
Notes:
- User must request a handle to Rappture before accessing any member functions of the library.
- On success the return value will be a positive integer
- path must be a non-null c-style string
integer handle, rp_lib
handle = rp_lib("tool.xml")
print *,handle
c Result:
c 1
call rp_lib_element_comp (integer handle, character path, character retText)
Purpose:
This method searches the Rappture Library Object handle for the
node at the location described by path and returns its
component name, a concatination of the type, id, and index.
If path is an empty string, the root of the node is used. handle
is the handle representing the instance of the RpLibrary? object.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- character retText - component name of the path being searched.
Return Value:
None.
Notes:
None.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 path,retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
call rp_lib_element_comp(libHandle,path,retText)
print *,retText
c Result:
c number(temperature)
call rp_lib_element_id (integer handle, character path, character retText)
Purpose:
This method searches the Rappture Library Object handle for the
node at the location described by path and returns its id attribute.
If path is an empty string, the root of the node is used. handle
is the handle representing the instance of the RpLibrary? object.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- character retText - component name of the path being searched.
Return Value:
None.
Notes:
None.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 path,retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
call rp_lib_element_id(libHandle,path,retText)
print *,retText
c Result:
c temperature
call rp_lib_element_type (integer handle, character path, character retText)
Purpose:
This method searches the Rappture Library Object handle for the
node at the location described by path and returns type of node being searched.
If path is an empty string, the root of the node is used. handle
is the handle representing the instance of the RpLibrary? object.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- character retText - component name of the path being searched.
Return Value:
None.
Notes:
None.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 path,retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
call rp_lib_element_type(libHandle,path,retText)
print *,retText
c Result:
c number
integer rp_lib_element_obj (integer handle, character path)
Purpose:
This method searches the Rappture Library Object handle for the
node at the location described by path and returns an integer handle to the node.
If path is an empty string, the root of the node is used. handle
is the handle representing the instance of the RpLibrary? object.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
Return Value:
The integer handle that is returned will be a non-zero value on success. A zero valued
handle may indicate that the path being searched does not exists, the specific node
being searched does not exists or there was some error in processing the request.
Notes:
None.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 path
integer rp_lib_element_obj, newHandle
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
newHandle = rp_lib_element_obj(libHandle,path)
print *,newHandle
c Result:
c 1
integer rp_lib_children (integer handle, character path, character prevChildHandle)
Purpose:
This method searches the Rappture Library Object handle for the
node at the location described by path and returns its
children. If 'prevChildHandle' = 0, then the
first child is returned, else, the next child is retrieved.
If 'prevChildHandle' is an invalid child handle, an error value will be returned.
Subsequent calls to rpLibChildren() should use previously
returned values for it 'prevChildHandle' argument.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- integer prevChildHandle - index of the child being requested. Useful when a list of children are returned and you want to iterate through all of the children.
Return Value:
On successful, a positive integer will be returned, representing the handle of the next returned handle. On failure, zero will be returned denoting that either no more children are available or there was an error in processing the request.
Notes:
- path must be a non-null c-style string.
- In the rappture-linux-i686-20051107.tar.gz package, there is a bug that does not allow this function to work properly. The problem has been fixed in the svn repository and will be availabile in all future releases.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c <number id="height">
c <units>m</units>
c <default>2.2m</default>
c <current>3.4m</current>
c </number>
c <number id="weight">
c <units>kg</units>
c <default>0.3kg</default>
c <current>0.3kg</current>
c </number>
c </input>
c </run>
character*100 retText
integer rp_lib_children, childHandle, prevChildHandle
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
prevChildHandle = 0
childHandle = -1
10 continue
childHandle =
+ rp_lib_children(libHandle,"input",prevChildHandle)
if (childHandle .gt. 0) then
call rp_lib_node_comp(childHandle,retText)
print *,"component name: ",retText
endif
prevChildHandle = childHandle
if (childHandle .gt. 0) goto 10
c Result:
c component name: number(temperature)
c component name: number(height)
c component name: number(weight)
call rp_lib_get (integer handle, character path, character retText)
Purpose:
Retrieve the element path, which is associated with the document handle, and return the data it encapsulates, placing the text into the retText.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- character retText - character array where text of the tail element in the requested path is stored on a successful return.
Return Value:
On success, the data held within the path element will be written to retText.
Notes:
- path must be a non-null string. path may be an empty string ("").
- Returned text will be truncated if retText does not have the capacity to hold the whole string.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 path,retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature).current"
call rp_lib_get(libHandle,path,retText)
print *,retText
c Result:
c 300K
integer rp_lib_get_integer (integer handle, character path)
Purpose:
Retrieve the element path, which is associated with the document handle, and return the integer value it encapsulates.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
Return Value:
On success, the integer data held within the path element will be returned to the user.
Notes:
- path must be a non-null string. path may be an empty string ("").
c Example contents of driver.xml file
c <run>
c <input>
c <integer id="nodes">
c <min>0</min>
c <max>10</max>
c <default>3</default>
c <current>5</current>
c </integer>
c </input>
c </run>
character*100 path
integer rp_lib, rp_lib_get_integer
integer libHandle, myNodes
libHandle = rp_lib("driver.xml")
path = "input.integer(nodes).current"
myNodes = rp_lib_get_integer(libHandle,path)
print *,myNodes
c Result:
c 5
integer rp_lib_get_boolean (integer handle, character path)
Purpose:
Retrieve the element path, which is associated with the document handle, and return the boolean value it encapsulates as an integer.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
Return Value:
On success, the integer data representing the boolean value held within the path element will be returned to the user.
A value of 1 is returned for true, yes, on, and non-zero values that represent a boolean true. A value of 0 is returned for false, no, off, and zero values that represent a boolean false.
Notes:
- path must be a non-null string. path may be an empty string ("").
c Example contents of driver.xml file
c <run>
c <input>
c <boolean id="nodes">
c <default>true</default>
c <current>true</current>
c </boolean>
c </input>
c </run>
character*100 path
integer rp_lib, rp_lib_get_boolean
integer libHandle, myNodes
libHandle = rp_lib("driver.xml")
path = "input.boolean(nodes).current"
myNodes = rp_lib_get_boolean(libHandle,path)
print *,myNodes
c Result:
c 1
call rp_lib_put_str (integer handle, character path, character value, integer append)
Purpose:
Place the data value at location path inside the document associated with handle. If the append flag is set to 1, then append the data value to data that may already be present in path. If the append flag is set to 0, then overwrite any data that may be present.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character path - xml DOM object path.
- character value - data to be held at location path.
- integer append - flag denoting whether to overwrite (0) or append (1) value to the data at path.
Return Value:
None.
Notes:
- path must be a non-null string. path may be an empty string ("") to specify the root node.
- Returned text will be truncated if retText does not have the capacity to hold the whole string.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*500 path,retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature).min"
call rp_lib_put_str(libHandle,path,"10",0)
call rp_lib_xml(libHandle,retText)
print *,retText
c Result:
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c <min>10</min>
c </number>
c </input>
c </run>
call rp_lib_node_comp (integer handle, character retText)
Purpose:
Returns the component name of the node identified by handle and copies the text to retText.
The component name is a concatination of the type, id, and index.
Input Arguments:
- integer handle - user reference to the Rappture library node.
- character retText - character array where component name text will be stored on succesful return.
Return Value:
None
Notes:
- handle must be a positive integer identifier of a library object.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 retText,path
integer rp_lib_element_obj, newHandle
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
newHandle = rp_lib_element_obj(libHandle,path)
call rp_lib_node_comp(newHandle,retText)
print *,retText
c Result:
c number(temperature)
call rp_lib_node_type (integer handle, character retText)
Purpose:
Returns the type of the node identified by handle and copies the text to retText.
Input Arguments:
- integer handle - user reference to the Rappture library node.
- character retText - character array where node type will be stored on succesful return.
Return Value:
None
Notes:
- handle must be a positive integer identifier of a library object.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 retText,path
integer rp_lib_element_obj, newHandle
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
newHandle = rp_lib_element_obj(libHandle,path)
call rp_lib_node_type(newHandle,retText)
print *,retText
c Result:
c number
call rp_lib_node_id (integer handle, character retText)
Purpose:
Returns the id of the node identified by handle and copies the text to retText.
Input Arguments:
- integer handle - user reference to the Rappture library node.
- character retText - character array where id will be stored on succesful return.
Return Value:
None
Notes:
- handle must be a positive integer identifier of a library object.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 retText,path
integer rp_lib_element_obj, newHandle
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
path = "input.number(temperature)"
newHandle = rp_lib_element_obj(libHandle,path)
call rp_lib_node_id(newHandle,retText)
print *,retText
c Result:
c temperature
call rp_lib_xml (integer handle, character retText)
Purpose:
Get the xml text of the document associated with handle. Xml text will be stored in retText.
Input Arguments:
- integer handle - user reference to the Rappture library.
- character retText - character array where xml text will be stored on succesful return.
Return Value:
None
Notes:
- handle must be a positive integer identifier of a library object.
- retText must not be NULL. On successful return, retText will hold the xml text of the library associated with handle
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*500 retText
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
call rp_lib_xml(libHandle,retText)
print *,retText
c Result:
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
call rp_result (integer handle)
Purpose:
Usually the last call of the program, this function signals to the gui
that processing has completed and the output is ready to be
displayed
Input Arguments:
- integer handle - user reference to the Rappture library.
Return Value:
None.
Notes:
On Success, a unique run.xml file will be generated holding the inputs and outputs of
the simulation. Also a signal will be sent to the gui. The gui will retieve the signal
and generate output graphs as necessary
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
integer libHandle, rp_lib
libHandle = rp_lib("driver.xml")
call rp_result(libHandle)
c Result:
c unique run.xml file is written
c signal sent to gui stating processing has completed.
integer rp_define_unit (character unitName, integer basisName)
Purpose:
define a unit by the symbol of unitName which has basis identified by the integer unit handle basisName.
Input Arguments:
- character unitName - character array of the unit symbol.
- integer basisName - user (handle) reference to the Rappture defined unit representing the basis.
Return Value:
Integer handle representing the unit just defined.
Notes:
- a basisNmae of zero (0) represents no basis for the unit.
integer rp_find (character searchName)
Purpose:
Retrieve a handle for a Rappture Units Object.
Input Arguments:
- character searchName - character array of symbols representing the Rappture Unit being searched for.
Return Value:
Integer value holding a handle for the Rappture Units Object being searched for.
Notes:
- Repeat calls of rp_find with the same searchName will not produce the same return value. A new handle will be allocated.
call rp_get_units (integer unitRefVal, character retText)
Purpose:
retrieve the text portion of the symbol representing the Rappture Units Object whose handle is unitRefVal.
Input Arguments:
- integer unitRefVal - handle for a RapptureUnits? Object.
- character retText - character array where the text portion of the symbol representing the Rappture Units Object will be stored.
Return Value:
None
Notes:
- retText must not be NULL. On successful return, retText will hold the text portion of the symbol of the Rappture Units Object associated with unitRefVal
call rp_get_units_name (integer unitRefVal, character retText)
Purpose:
retrieve the whole symbol representing the Rappture Units Object whose handle is unitRefVal.
Input Arguments:
- integer unitRefVal - handle for a RapptureUnits? Object.
- character retText - character array where the whole symbol representing the Rappture Units Object will be stored.
Return Value:
None
Notes:
- retText must not be NULL. On successful return, retText will hold the whole symbol of the Rappture Units Object associated with unitRefVal
integer rp_get_exponent (integer unitRefVal, double retExponent)
Purpose:
Retrieve the exponent portion of the symbol of the Rappture Units Object represented by the handle unitRefVal.
Input Arguments:
- integer unitRefVal - handle for a RapptureUnits? Object.
Return Value:
Double value representing the exponential portion of the symbol of the Rappture Units Object represented by the handle unitRefVal.
Notes:
None
integer rp_get_basis (integer unitRefVal)
Purpose:
Get the basis for the Rappture Units Object represented by the handle unitRefVal.
Input Arguments:
- integer unitRefVal - handle for a RapptureUnits? Object.
Return Value:
Integer handle representing the unit just defined.
Notes:
None
integer rp_units_convert_dbl (character fromVal, character toUnitsName, double convResult)
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. A double precision value is placed into the variable provided by convResult. An error code is return from the function call, a value of 0 represents success, any other value is failure.
Input Arguments:
- character fromVal - String representing the numeric value and units you want ot convert from.
- character toUnitsName - String representing the name of the units you want to convert to.
- double convResult - Holds the conversion result as a double precision value. This value is populated by the function
Return Value:
On return, the variable convResult is populated with the conversion result and an error code is returned. An error code of 0 represents success, any other value represents failure.
Notes:
For this function, units are not displayed in the resultant value retText.
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 strVal, path
integer rp_lib, rp_units_convert_dbl
integer libHandle, ok
double precision T
libHandle = rp_lib("driver.xml")
path = "input.number(temperature).current"
call rp_lib_get(libHandle,path,strVal)
ok = rp_units_convert_dbl(strVal,"F",T)
print *,T
c Result:
c T = 80.33F
ok = rp_units_convert_dbl("78F","K",T)
print *,T
c Result:
c T = 298.706
integer rp_units_convert_str (character fromVal, character toUnitsName character retText)
Purpose:
Convert the numeric value and units found in the string fromVal to the units named in toUnitsName. A string value is placed into the variable provided by retText. An error code is return from the function call, a value of 0 represents success, any other value is failure.
Input Arguments:
- character fromVal - String representing the numeric value and units you want ot convert from.
- character toUnitsName - String representing the name of the units you want to convert to.
- character retText - Holds the conversion result as a string value. This value is populated by the function
Return Value:
On return, the variable retText is populated with the conversion result and an error code is returned. An error code of 0 represents success, any other value represents failure.
Notes:
Units are always displayed in the return value retText
c Example contents of driver.xml file
c <run>
c <input>
c <number id="temperature">
c <units>K</units>
c <default>300K</default>
c <current>300K</current>
c </number>
c </input>
c </run>
character*100 strVal, T
integer rp_lib_get, rp_lib, rp_units_convert_str
integer libHandle, ok
libHandle = rp_lib("driver.xml")
call rp_lib_get(libHandle,path,strVal)
call rp_lib_get(driver,"input.number(temperature).current", strVal)
ok = rp_units_convert_str(strVal,"K",T)
print *,T
c Result:
c T = 80.33F
ok = rp_units_convert_str("78F","K",T)
print *,T
c Result:
c T = 298.706
