Fortran Interface

The functions described in this section are either unique to the Fortran interface or facilitate the mixing of C/C++ and Fortran within a single application interacting with a Silo file. Note that when Silo was originally written, the vision was that only visualization/post-processing tools would ever attempt to read the contents of Silo files. Therefore, the Fortran interface has never included all the companion functions to read objects. That said, it is possible to write simple Fortran callable wrappers to the C functions much like the write interface already implemented. Have a look in the source file silo_f.c for examples.

---

dbmkptr()

• Summary: create a pointer-id from a pointer

• C Signature:

  integer function dbmkptr(void p)
  

• Arguments:

  Arg name	Description
  p	pointer for which a pointer-id is needed

• Returned value:

  the integer pointer id to associate with the pointer

• Description:

  In cases where the C interface returns to the application a pointer to an abstract Silo object, in the Fortran interface an integer pointer-id is created and returned instead. In addition, in cases where the C interface would accept an array of pointers, such as in DBPutCsgvar(), the Fortran interface accepts an array of pointer-ids. This function is used to create a pointer-id from a pointer.

  A table of pointers is maintained internally in the Fortran wrapper library. The pointer-id is simply the index into this table where the associated object’s pointer actually is. The caller can free up space in this table using dbrmptr()

---

dbrmptr()

• Summary: remove an old and no longer needed pointer-id

• Fortran Signature:

     integer function dbrmptr(ptr_id)
  

• Arguments:

  Arg name	Description
  ptr_id	the pointer-id to remove

• Returned value:

  always 0

---

dbset2dstrlen()

• Summary: Set the size of a ‘row’ for pointers to ‘arrays’ of strings

• Fortran Signature:

     integer function dbset2dstrlen(int len)
     integer len
  

• Arguments:

  Arg name	Description
  len	The length to set

• Returned value:

  Returns the previously set value.

• Description:

  A number of functions in the Fortran interface take a char* argument that is really treated internally in the Fortran interface as a 2D array of characters. Calling this function allows the caller to specify the length of the rows in this 2D array of characters. If necessary, this setting can be varied from call to call.

  The default value is 32 characters.

---

dbget2dstrlen()

• Summary: Get the size of a ‘row’ for pointers to ‘arrays’ of character strings

• Fortran Signature:

     integer function dbget2dstrlen()
  

• Arguments:

  None

• Returned value:

  The current setting for the 2D string length.

---

DBFortranAllocPointer()

• Summary: Facilitates accessing C objects through Fortran

• Fortran Signature:

  int DBFortranAllocPointer (void *pointer)
  

• Arguments:

  Arg name	Description
  pointer	A pointer to a Silo object for which a Fortran identifier is needed

• Returned value:

  DBFortranAllocPointer returns an integer that Fortran code can use to reference the given Silo object.

• Description:

  The DBFortranAllocPointer function allows programs written in both C and Fortran to access the same data structures. Many of the routines in the Fortran interface to Silo use an “object id”, an integer which refers to a Silo object. DBFortanAllocPointer converts a pointer to a Silo object into an integer that Fortran code can use. In some ways, this function is the inverse of DBFortranAccessPointer.

  The integer that DBFortranAllocPointer returns is used to index a table of Silo object pointers. When done with the integer, the entry in the table may be freed for use later through the use of DBFortranRemovePointer.

  See DBFortranAccessPointer and DBFortranRemovePointer for more information about how to use Silo objects in code that uses C and Fortran together.

  For example, if you have a DBfile* pointer for a Silo database file and wish to pass this object to some Fortran function(s), the coding pattern would look like the following…

  DBfile *db = DBOpen("foo.silo", DB_UNKNOWN, DB_APPEND);
  /*
  .
  . C/C++ code operates on db `pointer`
  .
  */
  
  /* create entry in Fortran wrappers for this Silo Object */
  int dbid = DBFortranAllocPointer(db);
  
  /* pass dbid to any Fortran code to interact with file */
  
  /* free up Fortran wrapper resources for this Silo object */
  
  DBFortranRemovePointer(dbid);
  

---

DBFortranAccessPointer()

• Summary: Access Silo objects created through the Fortran Silo interface.

• C Signature:

  void *DBFortranAccessPointer (int value)
  

• Arguments:

  Arg name	Description
  value	The value returned by a Silo Fortran function, referencing a Silo object.

• Returned value:

  DBFortranAccessPointer returns a pointer to a Silo object (which must be cast to the appropriate type) on success, and NULL on failure.

• Description:

  The DBFortranAccessPointer function allows programs written in both C and Fortran to access the same data structures. Many of the routines in the Fortran interface to Silo return an “object id”, an integer which refers to a Silo object. DBFortranAccessPointer converts this integer into a C pointer so that the sections of code written in C can access the Silo object directly.

  See DBFortranAllocPointer and DBFortranRemovePointer for more information about how to use Silo objects in code that uses C and Fortran together.

---

DBFortranRemovePointer()

• Summary: Removes a pointer from the Fortran-C index table

• C Signature:

  void DBFortranRemovePointer (int value)
  

• Arguments:

  Arg name	Description
  value	An integer returned by DBFortranAllocPointer

• Returned value:

  Nothing

• Description:

  The DBFortranRemovePointer function frees up the storage associated with Silo object pointers as allocated by DBFortranAllocPointer.

  Code that uses both C and Fortran may make use of DBFortranAllocPointer to allocate space in a translation table so that the same Silo object may be referenced by both languages. DBFortranAccessPointer provides access to this Silo object from the C side. Once the Fortran side of the code is done referencing the object, the space in the translation table may be freed by calling DBFortranRemovePointer. See DBFortranAccessPointer and DBFortranAllocPointer for more information about how to use Silo objects in code that uses C and Fortran together.

---

dbwrtfl()

• Summary: Write a facelist object referenced by its object_id to a silo file

• C Signature:

  dbwrtfl(dbid, name, lname, object_id, status)
  

• Arguments:

  Arg name	Description
  dbid	The identifier for the Silo database to write the object to.
  name	The name to be assigned to the object in the file.
  lname	The length of the name argument.
  object_id	The identifier for the facelist object, obtained via dbcalcfl.
  status	Return value indicating success or failure of the operation; 0 on success, -1 on failure.

• Returned value:

  Nothing

• Description:

  This function is designed to go hand-in-hand with dbcalcfl, the function used to calculate an external facelist. When dbcalcfl is called, an object identifier is returned in object_id for the newly created facelist. This call can then be used to write that facelist object to a Silo database.

---