How to handle code specific parameters

Step 1: Extraction - XML Schema

In a first step, you should extract the structure of the code specific parameters (i.e. names, types, structures, dimensions, allowed choices and ranges, etc.) into a separate file, the so-called W3C XML Schema.
The tool CREATE_SCHEMA in the project xmllib may help you to automatically generate a skeleton XML schema from a simple ASCII list of your code parameters.

Advantages:

• no format specific read subroutines needed anymore
• all tools can be made generic
• all code specific information stored in one single external file or XML string
• creation of the schema is a 'once-in-a-code's-lifetime' event
• later changes very simple through changing the schema
• enables input checking before running the code
• schema serves as minimum documentation for input

Step 2: Conversion - XML File

In a second step, you should convert your former input files containing the code parameters into XML input files like the one shown in the section Why XML?. These XML input files are instances of the XML schema of the code.
No tools to assist you with this conversion yet exist but tools to generate empty XML input files as well as to convert Fortran namelist files into XML input files are currently under development.

Advantages:

• text input files easier to understand by user
• same advantage as namelist: input does not have to be complete
• free order of input parameters as long as structure is not changed
• possibility to define beginner's and expert's settings
• input checks possible
• XML can be used for namelist input as well as any other format

Step 3: Assignment Function

In the third step, you need to create the so called assignment function. This function assigns the values from your XML input file to the corresponding variables in your code. Since compiler languages like Fortran or C/C++ do not know introspection, this function cannot be created in a generic way. It's specific shape depends on the structure of the specific code.
It can however be automatically generated for simple W3C XML schemas using the CREATE_ASSIGN tool (so far only for Fortran90 modules) of the project xmllib.

Advantages:

• generic tools have to be developed only once and can be used for any code
• generic tools as separate library - easier to maintain
• GUI development or use of existing GUIs become possible (e.g. xforms in a browser)
• users do not need to know about XML at all
• developers need to know only very little about XML

Fortran90

Lightweight Fortran90 parser for XML documents:

• compact (~500 lines Fortran90), efficient, fast parser
• parses XML documents with arbitrary depth and complexity (except for attributes)
• based on W3C XML Schemas (can be used to validate XML documents)
• uses tree-like lists with parent, child, and sibling pointers
• tag names and value lists of arbitrary length (dynamical memory allocation)
• available as module euitm_xml_parser
• first parses the code specific W3C schema, then parses the entire XML document sequentially like SAX
• comes with useful subroutines in xml_tools.f90 and string_manipulation_tools.f90

Tree Structure

euitm_xml_parse:

• input parameter of type type_param contains the XML schema in string array schema and the XML string for the code parameters in string array parameters
• parses the schema and builds an empty tree with the structure described by the schema: associates the corresponding pointers, allocates the tag names cname and fills in the tag names
• parses the actual XML document and fills the parsed values cvalue into the tree
• returns the complete tree in parameter_list and the number of successfully parsed parameters nparm

For information on how to call the Fortran90 XML parser please refer to the section on CREATE_ASSIGN.

check out project xmllib

svn co https://gforge6.eufus.eu/svn/xmllib target_dir

The Fortran90 XML Parser can be found in trunk/src/.

C/C++

under construction

Fortran90

The tool CREATE_SCHEMA uses the previously defined list parameter_list.txt and the generated schema w3c_schema.xsd to automatically generate a Fortran90 subroutine assign_code_parameters.f90 which can be used to assign the code parameters read from the XML string to the internal variables of your module.
To generate the assignment subroutine first check out project xmllib

svn co https://gforge6.eufus.eu/svn/xmllib target_dir

The tool CREATE_ASSIGN can be found in branches/toolbox/assignment_generator/.

Run CREATE_ASSIGN

• move parameter_list.txt into input/
• move w3c_schema.xsd into input/
• gmake -f makefile_pgi in obj/
• ./create_assign.e in run/
• generates assign_code_parameters.f90 in output/

CREATE_ASSIGN generates the Fortran90 subroutine assign_code_parameters.f90 which if called will do everything which is needed to read the XML schema, parse the XML string, and assign the values found in the XML string to the corresponding variables in the code. In most cases, no or very little manipulation of this subroutine is needed, for instance in the case of deep structures (more than 2 levels) and arrays. Please refer to existing schemas and assignment routines, like those for the HELENA module, for guidance.

The tool CREATE_ASSIGN assumes that the variable names in your code agree with the names which you have chosen for the code parameters.

If this is not the case, you will have to edit the names in the assignment statements or calls to char2num by hand to match your internal variables.

The assignment routine receives the parameter code_parameters of type type_param which holds both the XML schema as well as the actual XML string (see above).
It calls the ITM-TF Fortran90 Parser euitm_xml_parse on the structure code_parameters (see Fortran90 Parser) which returns the tree of stacked code parameters from the XML schema together with the values found in the XML string as a single connected list in parameter_list. The remaining loop together with the select structure then steps through the tree and assigns all values which it finds to the corresponding internal variables.

assign_code_parameters:

• sets pointer to head of list parameter_list%first
• assigns values to in-code variables by stepping through the tree and using select case constructs and the interfaces in string_manipulation_tools.f90
• finally destroys the tree

The figure below demonstrates how to call the assignment routine from your module.

Make sure that the assignment subroutine can access the required internal variables through use statements or other ways.

assign_code_parameters uses the ITM standard itm_types for its variable declarations.

C/C++

Development of the tool for C/C++ is still pending.

Validating your XML

To validate your XML and XSD files, you may use xmlstar ( path: $SWITMDIR/xmlstar/bin/ ):
usage:

xml val -w file.xml

or

xml val -s file.xsd file.xml

The first validates an XML file (could also be a schema) and is very useful for detecting syntactic errors.
The second validates the schema (file.xsd) and the XML file (file.xml) against the schema.

Creating default XML

The data going into the actor has to be stored in an xml-file that follows the data-structure defined by the xml-schema. An automated way to generate this xml file can be stored in the directory xmllib/branches/toolbox/xml_generator/. Generate the xml-file place a schema in xmllib/branches/toolbox/xml_generator/input and then run make in xmllib/branches/toolbox/xml_generator/obj/. The output xml-file will then be generated in the directory xmllib/branches/toolbox/xml_generator/output/.

Creating XML and parameter-list.txt from namelists

Under Construction

To generate the xml and the parameter-list.txt first check out project xmllib

svn co https://gforge6.eufus.eu/svn/xmllib xmllib

The conversion is done by first placing the namelist in the directory xmllib/branches/toolbox/namelists/input/. Then run make in the directory xmllib/branches/toolbox/namelists/.

Automated creation of XML/XSD/assign_codeparam.f90

An automated proceedure has been installed to generate all files needed to install code-parameters in a Fortran code. The procedure require that you first put you file parameter_list.txt in the directory xmllib/branches/toolbox/schema_generator/input/ and then type make in the directory xmllib/branches/toolbox/. All output file are then stored in xmllib/branches/toolbox/output/.

Online

• XML.com
  The web site http://www.xml.com is one of the most complete and timely sources of XML information and news around.
• XML.org
  Sponsored by OASIS, http://www.xml.org has XML news and resources, including the XML Catalog, a guide to XML products and services.
• DocBook
  OASIS, the maintainers of DocBook, have a web page devoted to the XML application at http://www.docbook.org.
• W3C
  The World Wide Web Consortium at http://www.w3.org oversees the specifications and guidelines for the technology of the World Wide Web. Check here for information about CSS, DOM, (X)HTML, MathML, XLinks, XML, XPath, XPointer, XSL, and other web technologies.

ITM-TF

Join project XMLLIB under Gforge.
(see How to join a Gforge project)

Fortran90 XML Parser:
https://gforge6.eufus.eu/svn/xmllib/trunk/parser

Schema Generator CREATE_SCHEMA:
https://gforge6.eufus.eu/svn/xmllib/branches/create_schema

Generate assign_code_parameters.f90 with CREATE_ASSIGN:
https://gforge6.eufus.eu/svn/xmllib/branches/create_assign

XForms

Use browser to interface XML documents based on W3C schema

XForms: 'XML application that represents the next generation of forms for the Web. By splitting traditional XHTML forms into three parts - XForms model, instance data, and user interface - it separates presentation from content...' (W3C)

• use a W3C XML schema to generate the fields in the form
• use an XML document to fill data into the fields (default values possible)
• XForm is an XHTML file created from the XML schema using a stylesheet (done only once)
• existing extensions to Firefox 2 and 3 required

(by courtesy of G. Huysmans)