mirror of
https://github.com/TREX-CoE/trexio.git
synced 2024-12-26 06:15:05 +01:00
3072 lines
155 KiB
HTML
3072 lines
155 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
|
|
<head>
|
|
<!-- 2021-06-17 Thu 18:22 -->
|
|
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<title>Front end API</title>
|
|
<meta name="generator" content="Org mode" />
|
|
<meta name="author" content="TREX-CoE" />
|
|
<style type="text/css">
|
|
<!--/*--><![CDATA[/*><!--*/
|
|
.title { text-align: center;
|
|
margin-bottom: .2em; }
|
|
.subtitle { text-align: center;
|
|
font-size: medium;
|
|
font-weight: bold;
|
|
margin-top:0; }
|
|
.todo { font-family: monospace; color: red; }
|
|
.done { font-family: monospace; color: green; }
|
|
.priority { font-family: monospace; color: orange; }
|
|
.tag { background-color: #eee; font-family: monospace;
|
|
padding: 2px; font-size: 80%; font-weight: normal; }
|
|
.timestamp { color: #bebebe; }
|
|
.timestamp-kwd { color: #5f9ea0; }
|
|
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
|
|
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
|
|
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
|
|
.underline { text-decoration: underline; }
|
|
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
|
|
p.verse { margin-left: 3%; }
|
|
pre {
|
|
border: 1px solid #ccc;
|
|
box-shadow: 3px 3px 3px #eee;
|
|
padding: 8pt;
|
|
font-family: monospace;
|
|
overflow: auto;
|
|
margin: 1.2em;
|
|
}
|
|
pre.src {
|
|
position: relative;
|
|
overflow: visible;
|
|
padding-top: 1.2em;
|
|
}
|
|
pre.src:before {
|
|
display: none;
|
|
position: absolute;
|
|
background-color: white;
|
|
top: -10px;
|
|
right: 10px;
|
|
padding: 3px;
|
|
border: 1px solid black;
|
|
}
|
|
pre.src:hover:before { display: inline;}
|
|
/* Languages per Org manual */
|
|
pre.src-asymptote:before { content: 'Asymptote'; }
|
|
pre.src-awk:before { content: 'Awk'; }
|
|
pre.src-C:before { content: 'C'; }
|
|
/* pre.src-C++ doesn't work in CSS */
|
|
pre.src-clojure:before { content: 'Clojure'; }
|
|
pre.src-css:before { content: 'CSS'; }
|
|
pre.src-D:before { content: 'D'; }
|
|
pre.src-ditaa:before { content: 'ditaa'; }
|
|
pre.src-dot:before { content: 'Graphviz'; }
|
|
pre.src-calc:before { content: 'Emacs Calc'; }
|
|
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
|
|
pre.src-fortran:before { content: 'Fortran'; }
|
|
pre.src-gnuplot:before { content: 'gnuplot'; }
|
|
pre.src-haskell:before { content: 'Haskell'; }
|
|
pre.src-hledger:before { content: 'hledger'; }
|
|
pre.src-java:before { content: 'Java'; }
|
|
pre.src-js:before { content: 'Javascript'; }
|
|
pre.src-latex:before { content: 'LaTeX'; }
|
|
pre.src-ledger:before { content: 'Ledger'; }
|
|
pre.src-lisp:before { content: 'Lisp'; }
|
|
pre.src-lilypond:before { content: 'Lilypond'; }
|
|
pre.src-lua:before { content: 'Lua'; }
|
|
pre.src-matlab:before { content: 'MATLAB'; }
|
|
pre.src-mscgen:before { content: 'Mscgen'; }
|
|
pre.src-ocaml:before { content: 'Objective Caml'; }
|
|
pre.src-octave:before { content: 'Octave'; }
|
|
pre.src-org:before { content: 'Org mode'; }
|
|
pre.src-oz:before { content: 'OZ'; }
|
|
pre.src-plantuml:before { content: 'Plantuml'; }
|
|
pre.src-processing:before { content: 'Processing.js'; }
|
|
pre.src-python:before { content: 'Python'; }
|
|
pre.src-R:before { content: 'R'; }
|
|
pre.src-ruby:before { content: 'Ruby'; }
|
|
pre.src-sass:before { content: 'Sass'; }
|
|
pre.src-scheme:before { content: 'Scheme'; }
|
|
pre.src-screen:before { content: 'Gnu Screen'; }
|
|
pre.src-sed:before { content: 'Sed'; }
|
|
pre.src-sh:before { content: 'shell'; }
|
|
pre.src-sql:before { content: 'SQL'; }
|
|
pre.src-sqlite:before { content: 'SQLite'; }
|
|
/* additional languages in org.el's org-babel-load-languages alist */
|
|
pre.src-forth:before { content: 'Forth'; }
|
|
pre.src-io:before { content: 'IO'; }
|
|
pre.src-J:before { content: 'J'; }
|
|
pre.src-makefile:before { content: 'Makefile'; }
|
|
pre.src-maxima:before { content: 'Maxima'; }
|
|
pre.src-perl:before { content: 'Perl'; }
|
|
pre.src-picolisp:before { content: 'Pico Lisp'; }
|
|
pre.src-scala:before { content: 'Scala'; }
|
|
pre.src-shell:before { content: 'Shell Script'; }
|
|
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
|
|
/* additional language identifiers per "defun org-babel-execute"
|
|
in ob-*.el */
|
|
pre.src-cpp:before { content: 'C++'; }
|
|
pre.src-abc:before { content: 'ABC'; }
|
|
pre.src-coq:before { content: 'Coq'; }
|
|
pre.src-groovy:before { content: 'Groovy'; }
|
|
/* additional language identifiers from org-babel-shell-names in
|
|
ob-shell.el: ob-shell is the only babel language using a lambda to put
|
|
the execution function name together. */
|
|
pre.src-bash:before { content: 'bash'; }
|
|
pre.src-csh:before { content: 'csh'; }
|
|
pre.src-ash:before { content: 'ash'; }
|
|
pre.src-dash:before { content: 'dash'; }
|
|
pre.src-ksh:before { content: 'ksh'; }
|
|
pre.src-mksh:before { content: 'mksh'; }
|
|
pre.src-posh:before { content: 'posh'; }
|
|
/* Additional Emacs modes also supported by the LaTeX listings package */
|
|
pre.src-ada:before { content: 'Ada'; }
|
|
pre.src-asm:before { content: 'Assembler'; }
|
|
pre.src-caml:before { content: 'Caml'; }
|
|
pre.src-delphi:before { content: 'Delphi'; }
|
|
pre.src-html:before { content: 'HTML'; }
|
|
pre.src-idl:before { content: 'IDL'; }
|
|
pre.src-mercury:before { content: 'Mercury'; }
|
|
pre.src-metapost:before { content: 'MetaPost'; }
|
|
pre.src-modula-2:before { content: 'Modula-2'; }
|
|
pre.src-pascal:before { content: 'Pascal'; }
|
|
pre.src-ps:before { content: 'PostScript'; }
|
|
pre.src-prolog:before { content: 'Prolog'; }
|
|
pre.src-simula:before { content: 'Simula'; }
|
|
pre.src-tcl:before { content: 'tcl'; }
|
|
pre.src-tex:before { content: 'TeX'; }
|
|
pre.src-plain-tex:before { content: 'Plain TeX'; }
|
|
pre.src-verilog:before { content: 'Verilog'; }
|
|
pre.src-vhdl:before { content: 'VHDL'; }
|
|
pre.src-xml:before { content: 'XML'; }
|
|
pre.src-nxml:before { content: 'XML'; }
|
|
/* add a generic configuration mode; LaTeX export needs an additional
|
|
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
|
|
pre.src-conf:before { content: 'Configuration File'; }
|
|
|
|
table { border-collapse:collapse; }
|
|
caption.t-above { caption-side: top; }
|
|
caption.t-bottom { caption-side: bottom; }
|
|
td, th { vertical-align:top; }
|
|
th.org-right { text-align: center; }
|
|
th.org-left { text-align: center; }
|
|
th.org-center { text-align: center; }
|
|
td.org-right { text-align: right; }
|
|
td.org-left { text-align: left; }
|
|
td.org-center { text-align: center; }
|
|
dt { font-weight: bold; }
|
|
.footpara { display: inline; }
|
|
.footdef { margin-bottom: 1em; }
|
|
.figure { padding: 1em; }
|
|
.figure p { text-align: center; }
|
|
.inlinetask {
|
|
padding: 10px;
|
|
border: 2px solid gray;
|
|
margin: 10px;
|
|
background: #ffffcc;
|
|
}
|
|
#org-div-home-and-up
|
|
{ text-align: right; font-size: 70%; white-space: nowrap; }
|
|
textarea { overflow-x: auto; }
|
|
.linenr { font-size: smaller }
|
|
.code-highlighted { background-color: #ffff00; }
|
|
.org-info-js_info-navigation { border-style: none; }
|
|
#org-info-js_console-label
|
|
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
|
|
.org-info-js_search-highlight
|
|
{ background-color: #ffff00; color: #000000; font-weight: bold; }
|
|
.org-svg { width: 90%; }
|
|
/*]]>*/-->
|
|
</style>
|
|
<link rel="stylesheet" title="Standard" href="trexio.css" type="text/css" />
|
|
|
|
<script type="text/javascript" src="org-info.js">
|
|
/**
|
|
*
|
|
* @source: org-info.js
|
|
*
|
|
* @licstart The following is the entire license notice for the
|
|
* JavaScript code in org-info.js.
|
|
*
|
|
* Copyright (C) 2012-2019 Free Software Foundation, Inc.
|
|
*
|
|
*
|
|
* The JavaScript code in this tag is free software: you can
|
|
* redistribute it and/or modify it under the terms of the GNU
|
|
* General Public License (GNU GPL) as published by the Free Software
|
|
* Foundation, either version 3 of the License, or (at your option)
|
|
* any later version. The code is distributed WITHOUT ANY WARRANTY;
|
|
* without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
* FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
|
|
*
|
|
* As additional permission under GNU GPL version 3 section 7, you
|
|
* may distribute non-source (e.g., minimized or compacted) forms of
|
|
* that code without the copy of the GNU GPL normally required by
|
|
* section 4, provided you include this license notice and a URL
|
|
* through which recipients can access the Corresponding Source.
|
|
*
|
|
* @licend The above is the entire license notice
|
|
* for the JavaScript code in org-info.js.
|
|
*
|
|
*/
|
|
</script>
|
|
|
|
<script type="text/javascript">
|
|
|
|
/*
|
|
@licstart The following is the entire license notice for the
|
|
JavaScript code in this tag.
|
|
|
|
Copyright (C) 2012-2019 Free Software Foundation, Inc.
|
|
|
|
The JavaScript code in this tag is free software: you can
|
|
redistribute it and/or modify it under the terms of the GNU
|
|
General Public License (GNU GPL) as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option)
|
|
any later version. The code is distributed WITHOUT ANY WARRANTY;
|
|
without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
|
|
|
|
As additional permission under GNU GPL version 3 section 7, you
|
|
may distribute non-source (e.g., minimized or compacted) forms of
|
|
that code without the copy of the GNU GPL normally required by
|
|
section 4, provided you include this license notice and a URL
|
|
through which recipients can access the Corresponding Source.
|
|
|
|
|
|
@licend The above is the entire license notice
|
|
for the JavaScript code in this tag.
|
|
*/
|
|
|
|
<!--/*--><![CDATA[/*><!--*/
|
|
org_html_manager.set("TOC_DEPTH", "4");
|
|
org_html_manager.set("LINK_HOME", "index.html");
|
|
org_html_manager.set("LINK_UP", "");
|
|
org_html_manager.set("LOCAL_TOC", "1");
|
|
org_html_manager.set("VIEW_BUTTONS", "0");
|
|
org_html_manager.set("MOUSE_HINT", "underline");
|
|
org_html_manager.set("FIXED_TOC", "0");
|
|
org_html_manager.set("TOC", "1");
|
|
org_html_manager.set("VIEW", "info");
|
|
org_html_manager.setup(); // activate after the parameters are set
|
|
/*]]>*///-->
|
|
</script>
|
|
<script type="text/javascript">
|
|
/*
|
|
@licstart The following is the entire license notice for the
|
|
JavaScript code in this tag.
|
|
|
|
Copyright (C) 2012-2019 Free Software Foundation, Inc.
|
|
|
|
The JavaScript code in this tag is free software: you can
|
|
redistribute it and/or modify it under the terms of the GNU
|
|
General Public License (GNU GPL) as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option)
|
|
any later version. The code is distributed WITHOUT ANY WARRANTY;
|
|
without even the implied warranty of MERCHANTABILITY or FITNESS
|
|
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
|
|
|
|
As additional permission under GNU GPL version 3 section 7, you
|
|
may distribute non-source (e.g., minimized or compacted) forms of
|
|
that code without the copy of the GNU GPL normally required by
|
|
section 4, provided you include this license notice and a URL
|
|
through which recipients can access the Corresponding Source.
|
|
|
|
|
|
@licend The above is the entire license notice
|
|
for the JavaScript code in this tag.
|
|
*/
|
|
<!--/*--><![CDATA[/*><!--*/
|
|
function CodeHighlightOn(elem, id)
|
|
{
|
|
var target = document.getElementById(id);
|
|
if(null != target) {
|
|
elem.cacheClassElem = elem.className;
|
|
elem.cacheClassTarget = target.className;
|
|
target.className = "code-highlighted";
|
|
elem.className = "code-highlighted";
|
|
}
|
|
}
|
|
function CodeHighlightOff(elem, id)
|
|
{
|
|
var target = document.getElementById(id);
|
|
if(elem.cacheClassElem)
|
|
elem.className = elem.cacheClassElem;
|
|
if(elem.cacheClassTarget)
|
|
target.className = elem.cacheClassTarget;
|
|
}
|
|
/*]]>*///-->
|
|
</script>
|
|
<script type="text/x-mathjax-config">
|
|
MathJax.Hub.Config({
|
|
displayAlign: "center",
|
|
displayIndent: "0em",
|
|
|
|
"HTML-CSS": { scale: 100,
|
|
linebreaks: { automatic: "false" },
|
|
webFont: "TeX"
|
|
},
|
|
SVG: {scale: 100,
|
|
linebreaks: { automatic: "false" },
|
|
font: "TeX"},
|
|
NativeMML: {scale: 100},
|
|
TeX: { equationNumbers: {autoNumber: "AMS"},
|
|
MultLineWidth: "85%",
|
|
TagSide: "right",
|
|
TagIndent: ".8em"
|
|
}
|
|
});
|
|
</script>
|
|
<script type="text/javascript"
|
|
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML"></script>
|
|
</head>
|
|
<body>
|
|
<div id="org-div-home-and-up">
|
|
<a accesskey="h" href=""> UP </a>
|
|
|
|
|
<a accesskey="H" href="index.html"> HOME </a>
|
|
</div><div id="content">
|
|
<h1 class="title">Front end API</h1>
|
|
<div id="table-of-contents">
|
|
<h2>Table of Contents</h2>
|
|
<div id="text-table-of-contents">
|
|
<ul>
|
|
<li><a href="#org9221b68">1. Coding conventions</a>
|
|
<ul>
|
|
<li><a href="#org1203fa6">1.1. Memory allocation</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#orge54fa96">2. Front end</a>
|
|
<ul>
|
|
<li><a href="#org18547c6">2.1. Error handling</a></li>
|
|
<li><a href="#orgb67d8fa">2.2. Back ends</a></li>
|
|
<li><a href="#org0d5127f">2.3. Read/write behavior</a></li>
|
|
<li><a href="#org9e964cd">2.4. TREXIO file type</a></li>
|
|
<li><a href="#org5fbaee5">2.5. Polymorphism of the file handle</a></li>
|
|
<li><a href="#org1dcea90">2.6. File opening</a></li>
|
|
<li><a href="#orga5a4e1f">2.7. File closing</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#org6c51f26">3. Templates for front end</a>
|
|
<ul>
|
|
<li><a href="#org52bc7b3">3.1. Description</a></li>
|
|
<li><a href="#org681a3c3">3.2. Templates for front end has/read/write a single dimensioning variable</a>
|
|
<ul>
|
|
<li><a href="#org5027f93">3.2.1. C templates for front end</a></li>
|
|
<li><a href="#orgf3dcbb2">3.2.2. Fortran templates for front end</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#orgbbfaaf5">3.3. Templates for front end has/read/write a dataset of numerical data</a>
|
|
<ul>
|
|
<li><a href="#orgbf9ee71">3.3.1. C templates for front end</a></li>
|
|
<li><a href="#org4df451d">3.3.2. Fortran templates for front end</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#org4514b6b">3.4. Sparse data structures</a></li>
|
|
<li><a href="#orgb3d5357">3.5. Templates for front end has/read/write a dataset of strings</a>
|
|
<ul>
|
|
<li><a href="#org33162ff">3.5.1. Introduction</a></li>
|
|
<li><a href="#orgbb52ee9">3.5.2. C templates for front end</a></li>
|
|
<li><a href="#orga35d58c">3.5.3. Fortran templates for front end</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#org769408d">3.6. Templates for front end has/read/write a single string attribute</a>
|
|
<ul>
|
|
<li><a href="#org4529784">3.6.1. Introduction</a></li>
|
|
<li><a href="#org25a72a6">3.6.2. C templates for front end</a></li>
|
|
<li><a href="#orgcf7769a">3.6.3. Fortran templates for front end</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#orgaf1b95c">4. Fortran helper/wrapper functions</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org9221b68" class="outline-2">
|
|
<h2 id="org9221b68"><span class="section-number-2">1</span> Coding conventions</h2>
|
|
<div class="outline-text-2" id="text-1">
|
|
<ul class="org-ul">
|
|
<li>integer types will be defined using types given in <code>stdint.h</code></li>
|
|
<li>pointers are always initialized to <code>NULL</code></li>
|
|
<li>when memory is freed, the pointer is set to <code>NULL</code></li>
|
|
<li><code>assert.h</code> should be used extensively</li>
|
|
<li>variable names are in lower case</li>
|
|
<li><code>#define</code> constants are in upper case</li>
|
|
<li>structs are suffixed by <code>_s</code></li>
|
|
<li>types are suffixed by <code>_t</code></li>
|
|
<li>API calls return <code>trexio_exit_code</code> (except for <code>trexio_open</code> function)</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div id="outline-container-org1203fa6" class="outline-3">
|
|
<h3 id="org1203fa6"><span class="section-number-3">1.1</span> Memory allocation</h3>
|
|
<div class="outline-text-3" id="text-1-1">
|
|
<p>
|
|
Memory allocation of structures can be facilitated by using the
|
|
following macro, which ensures that the size of the allocated
|
|
object is the same as the size of the data type pointed by the pointer.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #483d8b;">#define</span> <span style="color: #0000ff;">MALLOC</span>(<span style="color: #a0522d;">T</span>) (<span style="color: #228b22;">T</span>*) malloc (<span style="color: #a020f0;">sizeof</span>(T))
|
|
<span style="color: #483d8b;">#define</span> <span style="color: #0000ff;">CALLOC</span>(<span style="color: #a0522d;">N</span>,<span style="color: #a0522d;">T</span>) (<span style="color: #228b22;">T</span>*) calloc ( (N) , <span style="color: #a020f0;">sizeof</span>(T) )
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
When a pointer is freed, it should be set to <code>NULL</code>.
|
|
This can be facilitated by the use of the following macro:
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #483d8b;">#define</span> <span style="color: #0000ff;">FREE</span>(<span style="color: #a0522d;">X</span>) { free(X) ; (X)=<span style="color: #008b8b;">NULL</span>; }
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The maximum string size for the filenames is 4096 characters.
|
|
</p>
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #483d8b;">#define</span> <span style="color: #a0522d;">TREXIO_MAX_FILENAME_LENGTH</span> 4096
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orge54fa96" class="outline-2">
|
|
<h2 id="orge54fa96"><span class="section-number-2">2</span> Front end</h2>
|
|
<div class="outline-text-2" id="text-2">
|
|
<p>
|
|
All calls to TREXIO are thread-safe.
|
|
TREXIO front end is modular, which simplifies implementation of new back ends.
|
|
</p>
|
|
</div>
|
|
|
|
<div id="outline-container-org18547c6" class="outline-3">
|
|
<h3 id="org18547c6"><span class="section-number-3">2.1</span> Error handling</h3>
|
|
<div class="outline-text-3" id="text-2-1">
|
|
<table id="orga4d3089" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-right" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Macro</th>
|
|
<th scope="col" class="org-right">Code</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_FAILURE</code></td>
|
|
<td class="org-right">-1</td>
|
|
<td class="org-left">'Unknown failure'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_SUCCESS</code></td>
|
|
<td class="org-right">0</td>
|
|
<td class="org-left">'Success'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ARG_1</code></td>
|
|
<td class="org-right">1</td>
|
|
<td class="org-left">'Invalid argument 1'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ARG_2</code></td>
|
|
<td class="org-right">2</td>
|
|
<td class="org-left">'Invalid argument 2'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ARG_3</code></td>
|
|
<td class="org-right">3</td>
|
|
<td class="org-left">'Invalid argument 3'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ARG_4</code></td>
|
|
<td class="org-right">4</td>
|
|
<td class="org-left">'Invalid argument 4'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ARG_5</code></td>
|
|
<td class="org-right">5</td>
|
|
<td class="org-left">'Invalid argument 5'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_END</code></td>
|
|
<td class="org-right">6</td>
|
|
<td class="org-left">'End of file'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_READONLY</code></td>
|
|
<td class="org-right">7</td>
|
|
<td class="org-left">'Read-only file'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_ERRNO</code></td>
|
|
<td class="org-right">8</td>
|
|
<td class="org-left">strerror(errno)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_ID</code></td>
|
|
<td class="org-right">9</td>
|
|
<td class="org-left">'Invalid ID'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_ALLOCATION_FAILED</code></td>
|
|
<td class="org-right">10</td>
|
|
<td class="org-left">'Allocation failed'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_HAS_NOT</code></td>
|
|
<td class="org-right">11</td>
|
|
<td class="org-left">'Element absent'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_NUM</code></td>
|
|
<td class="org-right">12</td>
|
|
<td class="org-left">'Invalid dimensions'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_NUM_ALREADY_EXISTS</code></td>
|
|
<td class="org-right">13</td>
|
|
<td class="org-left">'Dimensioning variable already exists'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_DSET_ALREADY_EXISTS</code></td>
|
|
<td class="org-right">14</td>
|
|
<td class="org-left">'Dataset already exists'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_OPEN_ERROR</code></td>
|
|
<td class="org-right">15</td>
|
|
<td class="org-left">'Error opening file'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_LOCK_ERROR</code></td>
|
|
<td class="org-right">16</td>
|
|
<td class="org-left">'Error locking file'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_UNLOCK_ERROR</code></td>
|
|
<td class="org-right">17</td>
|
|
<td class="org-left">'Error unlocking file'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_FILE_ERROR</code></td>
|
|
<td class="org-right">18</td>
|
|
<td class="org-left">'Invalid file handle'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_GROUP_READ_ERROR</code></td>
|
|
<td class="org-right">19</td>
|
|
<td class="org-left">'Error reading group'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_GROUP_WRITE_ERROR</code></td>
|
|
<td class="org-right">20</td>
|
|
<td class="org-left">'Error writing group'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_ELEM_READ_ERROR</code></td>
|
|
<td class="org-right">21</td>
|
|
<td class="org-left">'Error reading element'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_ELEM_WRITE_ERROR</code></td>
|
|
<td class="org-right">22</td>
|
|
<td class="org-left">'Error writing element'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>TREXIO_INVALID_STR_LEN</code></td>
|
|
<td class="org-right">30</td>
|
|
<td class="org-left">'Invalid max<sub>str</sub><sub>len</sub>'</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>
|
|
The <code>trexio_string_of_error</code> converts an exit code into a string. The
|
|
string is assumed to be large enough to contain the error message
|
|
(typically 128 characters).
|
|
</p>
|
|
|
|
<p>
|
|
◉ Decoding errors
|
|
</p>
|
|
|
|
<p>
|
|
To decode the error messages, <code>trexio_string_of_error</code> converts an
|
|
error code into a string.
|
|
</p>
|
|
|
|
<pre class="example">
|
|
128
|
|
|
|
</pre>
|
|
|
|
<p>
|
|
The text strings are extracted from the previous table.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>*
|
|
<span style="color: #0000ff;">trexio_string_of_error</span> (<span style="color: #a020f0;">const</span> <span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">error</span>)
|
|
{
|
|
<span style="color: #a020f0;">switch</span> (error) {
|
|
<span style="color: #a020f0;">case</span> TREXIO_FAILURE:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Unknown failure"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_SUCCESS:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Success"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ARG_1:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid argument 1"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ARG_2:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid argument 2"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ARG_3:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid argument 3"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ARG_4:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid argument 4"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ARG_5:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid argument 5"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_END:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"End of file"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_READONLY:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Read-only file"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_ERRNO:
|
|
<span style="color: #a020f0;">return</span> strerror(errno);
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_ID:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid ID"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_ALLOCATION_FAILED:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Allocation failed"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_HAS_NOT:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Element absent"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_NUM:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid dimensions"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_NUM_ALREADY_EXISTS:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Dimensioning variable already exists"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_DSET_ALREADY_EXISTS:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Dataset already exists"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_OPEN_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error opening file"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_LOCK_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error locking file"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_UNLOCK_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error unlocking file"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_FILE_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid file handle"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_GROUP_READ_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error reading group"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_GROUP_WRITE_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error writing group"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_ELEM_READ_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error reading element"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_ELEM_WRITE_ERROR:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Error writing element"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
<span style="color: #a020f0;">case</span> TREXIO_INVALID_STR_LEN:
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Invalid max_str_len"</span>;
|
|
<span style="color: #a020f0;">break</span>;
|
|
}
|
|
<span style="color: #a020f0;">return</span> <span style="color: #8b2252;">"Unknown error"</span>;
|
|
}
|
|
|
|
<span style="color: #228b22;">void</span>
|
|
<span style="color: #0000ff;">trexio_string_of_error_f</span> (<span style="color: #a020f0;">const</span> <span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">error</span>, <span style="color: #228b22;">char</span> <span style="color: #a0522d;">result</span>[128])
|
|
{
|
|
strncpy(result, trexio_string_of_error(error), 128);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #a020f0;">subroutine</span> <span style="color: #0000ff;">trexio_string_of_error</span> (error, string) <span style="color: #a020f0;">bind</span>(C, name=<span style="color: #8b2252;">'trexio_string_of_error_f'</span>)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #a020f0;">import</span>
|
|
<span style="color: #228b22;">integer</span> (trexio_exit_code), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> error</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> string(128)</span>
|
|
<span style="color: #a020f0;">end subroutine</span> <span style="color: #0000ff;">trexio_string_of_error</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgb67d8fa" class="outline-3">
|
|
<h3 id="orgb67d8fa"><span class="section-number-3">2.2</span> Back ends</h3>
|
|
<div class="outline-text-3" id="text-2-2">
|
|
<p>
|
|
TREXIO has several back ends:
|
|
</p>
|
|
|
|
<ol class="org-ol">
|
|
<li><code>TREXIO_HDF5</code> relies on extensive use of the HDF5 library and the associated file format. The HDF5 file is binary and tailored to high-performance I/O. This back end is the default one. HDF5 can be compiled with MPI for parallel I/O. Note, that HDF5 has to be downloaded and installed independently of TREXIO, which may cause some obstacles, especially when the user is not allowed to install external software. The produced files usually have <code>.h5</code> extension.</li>
|
|
|
|
<li><code>TREXIO_TEXT</code> relies on basic file I/O in C, namely <code>fopen, fclose, fprintf, fscanf</code> etc. from <code>stdio.h</code> library. This back end is not optimized for performance. It is supposed to be used for debug purposes or, for example, when the user wants to modify some data manually within the file. This back end is supposed to work "out-of-the-box" since there are no external dependencies, which might be useful for users that do not have access to HDF5 library. The produced files usually have <code>.txt</code> extension.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Additional back ends can be implemented thanks to the modular nature of the front end.
|
|
This can be achieved by adding a new <code>case</code> (corresponding to the desired back end) in the front-end <code>switch</code>.
|
|
Then the corresponding back-end <code>has/read/write</code> functions has to be implemented. For example, see the commented
|
|
lines that correspond to the <code>TREXIO_JSON</code> back end (not implemented yet).
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #228b22;">int32_t</span> <span style="color: #228b22;">back_end_t</span>;
|
|
|
|
<span style="color: #483d8b;">#define</span> <span style="color: #a0522d;">TREXIO_HDF5</span> ( (<span style="color: #228b22;">back_end_t</span>) 0 )
|
|
<span style="color: #483d8b;">#define</span> <span style="color: #a0522d;">TREXIO_TEXT</span> ( (<span style="color: #228b22;">back_end_t</span>) 1 )
|
|
/*<span style="color: #b22222;">#define TREXIO_JSON ( (back_end_t) 2 )</span>*/
|
|
<span style="color: #483d8b;">#define</span> <span style="color: #a0522d;">TREXIO_INVALID_BACK_END</span> ( (<span style="color: #228b22;">back_end_t</span>) 2 )
|
|
|
|
<span style="color: #483d8b;">#define</span> <span style="color: #a0522d;">TREXIO_DELIM</span> <span style="color: #8b2252;">"\n"</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-org0d5127f" class="outline-3">
|
|
<h3 id="org0d5127f"><span class="section-number-3">2.3</span> Read/write behavior</h3>
|
|
<div class="outline-text-3" id="text-2-3">
|
|
<p>
|
|
Every time a reading function is called, the data is read from the
|
|
disk. If data needs to be cached, this is left to the user of the
|
|
library.
|
|
</p>
|
|
|
|
<p>
|
|
Writing to TREXIO files is done with transactions (all-or-nothing
|
|
effect) in a per-group fashion. File writes are attempted by
|
|
calling explicitly the write (<code>TREXIO_HDF5</code>) or flush (<code>TREXIO_TEXT</code>)
|
|
function, or when the TREXIO file is closed.
|
|
If writing is impossible because the data is not valid, no data is written.
|
|
</p>
|
|
|
|
<p>
|
|
The order in which the data is written is not necessarily consistent
|
|
with the order in which the function calls were made.
|
|
</p>
|
|
|
|
<p>
|
|
The TREXIO files are supposed to be opened by only one program at a
|
|
time: if the same TREXIO file is modified simultaneously by multiple
|
|
concurrent programs, the behavior is not specified.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-org9e964cd" class="outline-3">
|
|
<h3 id="org9e964cd"><span class="section-number-3">2.4</span> TREXIO file type</h3>
|
|
<div class="outline-text-3" id="text-2-4">
|
|
<p>
|
|
<code>trexio_s</code> is the the main type for TREXIO files, visible to the users
|
|
of the library. This type is kept opaque, and all modifications to
|
|
the files will be necessarily done through the use of functions,
|
|
taking such a type as argument.
|
|
</p>
|
|
|
|
<p>
|
|
File creation and opening functions will return <i>TREXIO file handles</i>,
|
|
namely pointers to <code>trexio_s</code> types. All functions accessing to the
|
|
TREXIO files will have as a first argument the TREXIO file handle.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #a020f0;">typedef</span> <span style="color: #a020f0;">struct</span> <span style="color: #228b22;">trexio_s</span> <span style="color: #228b22;">trexio_t</span>;
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #a020f0;">struct</span> <span style="color: #228b22;">trexio_s</span> {
|
|
<span style="color: #228b22;">char</span> <span style="color: #a0522d;">file_name</span>[TREXIO_MAX_FILENAME_LENGTH];
|
|
<span style="color: #228b22;">pthread_mutex_t</span> <span style="color: #a0522d;">thread_lock</span>;
|
|
<span style="color: #228b22;">back_end_t</span> <span style="color: #a0522d;">back_end</span>;
|
|
<span style="color: #228b22;">char</span> <span style="color: #a0522d;">mode</span>;
|
|
<span style="color: #228b22;">bool</span> <span style="color: #a0522d;">one_based</span>;
|
|
<span style="color: #228b22;">char</span> <span style="color: #a0522d;">padding</span>[6]; /* <span style="color: #b22222;">Ensures the proper alignment of back ends </span>*/
|
|
};
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="outline-container-org5fbaee5" class="outline-3">
|
|
<h3 id="org5fbaee5"><span class="section-number-3">2.5</span> Polymorphism of the file handle</h3>
|
|
<div class="outline-text-3" id="text-2-5">
|
|
<p>
|
|
Polymorphism of the <code>trexio_t</code> type is handled by ensuring that the
|
|
corresponding types for all back ends can be safely casted to
|
|
<code>trexio_t</code>. This is done by making the back-end structs start with
|
|
<code>struct trexio_s</code>:
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #a020f0;">struct</span> <span style="color: #228b22;">trexio_back_end_s</span> {
|
|
<span style="color: #228b22;">trexio_t</span> <span style="color: #a0522d;">parent</span> ;
|
|
/* <span style="color: #b22222;">add below specific back-end data </span>*/
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org1dcea90" class="outline-3">
|
|
<h3 id="org1dcea90"><span class="section-number-3">2.6</span> File opening</h3>
|
|
<div class="outline-text-3" id="text-2-6">
|
|
<p>
|
|
<code>trexio_open</code> creates a new TREXIO file or opens existing one.
|
|
</p>
|
|
|
|
<p>
|
|
input parameters:
|
|
</p>
|
|
<ol class="org-ol">
|
|
<li><code>file_name</code> - string containing file name</li>
|
|
<li><code>mode</code> - character containing open mode (see below)
|
|
<ul class="org-ul">
|
|
<li><code>'w'</code> - (write) creates a new file as READWRITE (overwrite existing file)</li>
|
|
<li><code>'r'</code> - (read) opens existing file as READONLY</li>
|
|
</ul></li>
|
|
<li><code>back_end</code> - integer number (or the corresponding global parameter) specifying the back end
|
|
<ul class="org-ul">
|
|
<li><code>TREXIO_HDF5</code> - for HDF5 back end (integer alternative: 0)</li>
|
|
<li><code>TREXIO_TEXT</code> - for TEXT back end (integer alternative: 1)</li>
|
|
</ul></li>
|
|
</ol>
|
|
|
|
<p>
|
|
output:
|
|
<code>trexio_t</code> file handle
|
|
</p>
|
|
|
|
<p>
|
|
Note: the <code>file_name</code> in TEXT back end actually corresponds to the
|
|
name of the directory where <code>.txt</code> data files are stored. The
|
|
actual name of each <code>.txt</code> file corresponds to the group name
|
|
provided in <code>trex.config</code> (e.g. <code>nucleus.txt</code> for nuclei-related
|
|
data). These names are populated by the generator.py (i.e. they
|
|
are hard-coded), which is why the user should tend to avoid
|
|
renaming the <code>.txt</code> data files.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_t</span>*
|
|
<span style="color: #0000ff;">trexio_open</span>(<span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>* <span style="color: #a0522d;">file_name</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span> <span style="color: #a0522d;">mode</span>,
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">back_end_t</span> <span style="color: #a0522d;">back_end</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file_name == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
<span style="color: #a020f0;">if</span> (file_name[0] == <span style="color: #8b2252;">'\0'</span>) <span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
/* <span style="color: #b22222;">Check overflow in file_name </span>*/
|
|
|
|
<span style="color: #a020f0;">if</span> (back_end < 0) <span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
<span style="color: #a020f0;">if</span> (back_end >= TREXIO_INVALID_BACK_END) <span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
|
|
<span style="color: #a020f0;">if</span> (mode != <span style="color: #8b2252;">'r'</span> && mode != <span style="color: #8b2252;">'w'</span>) <span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
|
|
<span style="color: #228b22;">trexio_t</span>* <span style="color: #a0522d;">result</span> = <span style="color: #008b8b;">NULL</span>;
|
|
<span style="color: #228b22;">void</span>* <span style="color: #a0522d;">result_tmp</span> = <span style="color: #008b8b;">NULL</span>;
|
|
|
|
/* <span style="color: #b22222;">Allocate data structures </span>*/
|
|
<span style="color: #a020f0;">switch</span> (back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
result_tmp = malloc(<span style="color: #a020f0;">sizeof</span>(trexio_text_t));
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
result_tmp = malloc(<span style="color: #a020f0;">sizeof</span>(trexio_hdf5_t));
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> result = (trexio_t*) malloc (sizeof(trexio_json_t));</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
result = (<span style="color: #228b22;">trexio_t</span>*) result_tmp;
|
|
|
|
assert (result != <span style="color: #008b8b;">NULL</span>); /* <span style="color: #b22222;">TODO: Error handling </span>*/
|
|
|
|
|
|
/* <span style="color: #b22222;">Data for the parent type </span>*/
|
|
|
|
strncpy(result->file_name, file_name, TREXIO_MAX_FILENAME_LENGTH);
|
|
<span style="color: #a020f0;">if</span> (result->file_name[TREXIO_MAX_FILENAME_LENGTH-1] != <span style="color: #8b2252;">'\0'</span>) {
|
|
free(result);
|
|
<span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
}
|
|
|
|
result->back_end = back_end;
|
|
result->mode = mode;
|
|
result->one_based = <span style="color: #008b8b;">false</span>; // <span style="color: #b22222;">Need to be flipped in Fortran interface</span>
|
|
<span style="color: #228b22;">int</span> <span style="color: #a0522d;">irc</span> = pthread_mutex_init ( &(result->thread_lock), <span style="color: #008b8b;">NULL</span>);
|
|
assert (irc == 0);
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
|
|
/* <span style="color: #b22222;">Back end initialization </span>*/
|
|
|
|
rc = TREXIO_OPEN_ERROR;
|
|
|
|
<span style="color: #a020f0;">switch</span> (back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_init(result);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_init(result);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_init(result);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
|
|
free(result);
|
|
<span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
}
|
|
|
|
/* <span style="color: #b22222;">File locking </span>*/
|
|
|
|
rc = TREXIO_LOCK_ERROR;
|
|
|
|
<span style="color: #a020f0;">switch</span> (back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_lock(result);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/* <span style="color: #b22222;">HDF5 v.>=1.10 has file locking activated by default </span>*/
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = TREXIO_SUCCESS;
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_lock(result);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
|
|
free(result);
|
|
<span style="color: #a020f0;">return</span> <span style="color: #008b8b;">NULL</span>;
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> result;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer</span>(8) <span style="color: #a020f0;">function</span> <span style="color: #0000ff;">trexio_open_c</span> (filename, mode, backend) <span style="color: #a020f0;">bind</span>(C, name=<span style="color: #8b2252;">"trexio_open"</span>)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #a020f0;">import</span>
|
|
<span style="color: #228b22;">character</span>(kind=<span style="color: #008b8b;">c_char</span>), <span style="color: #a020f0;">dimension</span>(*) ::<span style="color: #a0522d;"> filename</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> mode</span>
|
|
<span style="color: #228b22;">integer</span>(trexio_backend), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> backend</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_open_c</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
Because arrays are zero-based in Fortran, we need to set a flag to
|
|
know if we need to shift by 1 arrays of indices.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span> <span style="color: #0000ff;">trexio_set_one_based</span>(<span style="color: #228b22;">trexio_t</span>* <span style="color: #a0522d;">file</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>)
|
|
<span style="color: #a020f0;">return</span> TREXIO_FILE_ERROR;
|
|
|
|
file->one_based = <span style="color: #008b8b;">true</span>;
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_set_one_based</span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_set_one_based</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orga5a4e1f" class="outline-3">
|
|
<h3 id="orga5a4e1f"><span class="section-number-3">2.7</span> File closing</h3>
|
|
<div class="outline-text-3" id="text-2-7">
|
|
<p>
|
|
<code>trexio_close</code> closes an existing <code>trexio_t</code> file.
|
|
</p>
|
|
|
|
<p>
|
|
input parameters:
|
|
<code>file</code> – TREXIO file handle.
|
|
</p>
|
|
|
|
<p>
|
|
output:
|
|
<code>trexio_exit_code</code> exit code.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_close</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a0522d;">file</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_FILE_ERROR;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span> = TREXIO_FAILURE;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
/* <span style="color: #b22222;">Terminate the back end </span>*/
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_deinit(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_deinit(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_deinit(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
|
|
FREE(file);
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
}
|
|
|
|
/* <span style="color: #b22222;">File unlocking </span>*/
|
|
|
|
rc = TREXIO_UNLOCK_ERROR;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_unlock(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = TREXIO_SUCCESS;
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_unlock(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
/* <span style="color: #b22222;">Terminate front end </span>*/
|
|
|
|
<span style="color: #228b22;">int</span> <span style="color: #a0522d;">irc</span> = pthread_mutex_destroy( &(file->thread_lock) );
|
|
|
|
free(file);
|
|
|
|
<span style="color: #a020f0;">if</span> (irc != 0) <span style="color: #a020f0;">return</span> TREXIO_ERRNO;
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_close</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_close</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org6c51f26" class="outline-2">
|
|
<h2 id="org6c51f26"><span class="section-number-2">3</span> Templates for front end</h2>
|
|
<div class="outline-text-2" id="text-3">
|
|
</div>
|
|
<div id="outline-container-org52bc7b3" class="outline-3">
|
|
<h3 id="org52bc7b3"><span class="section-number-3">3.1</span> Description</h3>
|
|
<div class="outline-text-3" id="text-3-1">
|
|
<p>
|
|
Consider the following block of <code>trex.json</code>:
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-python">{
|
|
<span style="color: #8b2252;">"nucleus"</span>: {
|
|
<span style="color: #8b2252;">"num"</span> : [ <span style="color: #8b2252;">"int"</span> , [ ] ]
|
|
, <span style="color: #8b2252;">"charge"</span> : [ <span style="color: #8b2252;">"float"</span>, [ <span style="color: #8b2252;">"nucleus.num"</span> ] ]
|
|
, <span style="color: #8b2252;">"coord"</span> : [ <span style="color: #8b2252;">"float"</span>, [ <span style="color: #8b2252;">"nucleus.num"</span>, <span style="color: #8b2252;">"3"</span> ] ]
|
|
, <span style="color: #8b2252;">"label"</span> : [ <span style="color: #8b2252;">"str"</span> , [ <span style="color: #8b2252;">"nucleus.num"</span> ] ]
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
<code>TREXIO</code> is generated automatically by the <code>generator.py</code> Python
|
|
script based on the tree-like configuration provided in the
|
|
<code>trex.json</code> file. Because of that, generalized templates can be
|
|
implemented and re-used. This approach minimizes the number of bugs
|
|
as compared with manual copy-paste-modify scheme.
|
|
</p>
|
|
|
|
<p>
|
|
All templates presented below use the <code>$var$</code> notation to indicate
|
|
the variable, which will be replaced by the
|
|
<code>generator.py</code>. Sometimes the upper case is used, i.e. <code>$VAR$</code> (for
|
|
example, in <code>#define</code> statements). More detailed description of
|
|
each variable can be found below:
|
|
</p>
|
|
|
|
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Template variable</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
<th scope="col" class="org-left">Example</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>$group$</code></td>
|
|
<td class="org-left">Name of the group</td>
|
|
<td class="org-left"><code>nucleus</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_num$</code></td>
|
|
<td class="org-left">Name of the dimensioning variable (scalar)</td>
|
|
<td class="org-left"><code>nucleus_num</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset$</code></td>
|
|
<td class="org-left">Name of the dataset (vector/matrix/tensor)</td>
|
|
<td class="org-left"><code>nucleus_coord</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_rank$</code></td>
|
|
<td class="org-left">Rank of the dataset</td>
|
|
<td class="org-left"><code>2</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dim$</code></td>
|
|
<td class="org-left">Selected dimension of the dataset</td>
|
|
<td class="org-left"><code>nucleus_num</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dim_list$</code></td>
|
|
<td class="org-left">All dimensions of the dataset</td>
|
|
<td class="org-left"><code>{nucleus_num, 3}</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dtype$</code></td>
|
|
<td class="org-left">Basic type of the dataset (int/float/char)</td>
|
|
<td class="org-left"><code>float</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_h5_dtype$</code></td>
|
|
<td class="org-left">Type of the dataset in HDF5</td>
|
|
<td class="org-left"><code>double</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_std_dtype_in$</code></td>
|
|
<td class="org-left">Input type of the dataset in TEXT [fscanf]</td>
|
|
<td class="org-left"><code>%lf</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_std_dtype_out$</code></td>
|
|
<td class="org-left">Output type of the dataset in TEXT [fprintf]</td>
|
|
<td class="org-left"><code>%24.16e</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dtype_default$</code></td>
|
|
<td class="org-left">Default datatype of the dataset [C]</td>
|
|
<td class="org-left"><code>double/int32_t</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dtype_single$</code></td>
|
|
<td class="org-left">Single precision datatype of the dataset [C]</td>
|
|
<td class="org-left"><code>float/int32_t</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_dtype_double$</code></td>
|
|
<td class="org-left">Double precision datatype of the dataset [C]</td>
|
|
<td class="org-left"><code>double/int64_t</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$default_prec$</code></td>
|
|
<td class="org-left">Default precision for read/write without suffix [C]</td>
|
|
<td class="org-left"><code>64/32</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_f_dtype_default$</code></td>
|
|
<td class="org-left">Default datatype of the dataset [Fortran]</td>
|
|
<td class="org-left"><code>real(8)/integer(4)</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_f_dtype_single$</code></td>
|
|
<td class="org-left">Single precision datatype of the dataset [Fortran]</td>
|
|
<td class="org-left"><code>real(4)/integer(4)</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_f_dtype_double$</code></td>
|
|
<td class="org-left">Double precision datatype of the dataset [Fortran]</td>
|
|
<td class="org-left"><code>real(8)/integer(8)</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>$group_dset_f_dims$</code></td>
|
|
<td class="org-left">Dimensions in Fortran</td>
|
|
<td class="org-left"><code>(:,:)</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<p>
|
|
Note: parent group name is always added to the child objects upon
|
|
construction of TREXIO (e.g. <code>num</code> of <code>nucleus</code> group becomes
|
|
<code>nucleus_num</code> and should be accessed accordingly within TREXIO).
|
|
</p>
|
|
|
|
<p>
|
|
TREXIO generator parses the <code>trex.json</code> file. TREXIO operates with
|
|
names of variables based on the 1-st (parent group) and 2-nd (child
|
|
object) levels of <code>trex.json</code> . The parsed data is divided in 2
|
|
parts:
|
|
</p>
|
|
|
|
<ol class="org-ol">
|
|
<li>Dimensioning variables (contain <code>num</code> in their names). These are always scalar integers.</li>
|
|
<li>Datasets. These can be vectors, matrices or tensors. The types are indicated in <code>trex.json</code>.
|
|
Currently supported types: int, float and strings.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
For each of the aforementioned objects, TREXIO provides <b>has</b>,
|
|
<b>read</b> and <b>write</b> functionality. TREXIO supports I/O with single
|
|
or double precision for integer and floating point numbers.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org681a3c3" class="outline-3">
|
|
<h3 id="org681a3c3"><span class="section-number-3">3.2</span> Templates for front end has/read/write a single dimensioning variable</h3>
|
|
<div class="outline-text-3" id="text-3-2">
|
|
<p>
|
|
This section concerns API calls related to dimensioning variables.
|
|
</p>
|
|
|
|
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Function name</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
<th scope="col" class="org-left">Precision</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>trexio_has_$group_num$</code></td>
|
|
<td class="org-left">Check if a dimensioning variable exists in a file</td>
|
|
<td class="org-left">---</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_num$</code></td>
|
|
<td class="org-left">Read a dimensioning variable</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_num$</code></td>
|
|
<td class="org-left">Write a dimensioning variable</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_num$_32</code></td>
|
|
<td class="org-left">Read a dimensioning variable</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_num$_32</code></td>
|
|
<td class="org-left">Write a dimensioning variable</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_num$_64</code></td>
|
|
<td class="org-left">Read a dimensioning variable</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_num$_64</code></td>
|
|
<td class="org-left">Write a dimensioning variable</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div id="outline-container-org5027f93" class="outline-4">
|
|
<h4 id="org5027f93"><span class="section-number-4">3.2.1</span> C templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-2-1">
|
|
<p>
|
|
The <code>C</code> templates that correspond to each of the abovementioned
|
|
functions can be found below. First parameter is the <code>TREXIO</code> file
|
|
handle. Second parameter is the variable to be written/read
|
|
to/from the <code>TREXIO</code> file (except for <code>trexio_has_</code> functions).
|
|
Suffixes <code>_32</code> and <code>_64</code> correspond to API calls dealing with
|
|
single and double precision, respectively. The basic
|
|
(non-suffixed) API call on dimensioning variables deals with single
|
|
precision (see Table above).
|
|
</p>
|
|
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_num$_64</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">int64_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">u_num</span> = 0;
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span> = TREXIO_GROUP_READ_ERROR;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_read_$group_num$(file, &u_num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_read_$group_num$(file, &u_num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc =trexio_json_read_$group_num$(file, &u_num);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
*num = (<span style="color: #228b22;">int64_t</span>) u_num;
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_num$_64</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (num < 0 ) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_num$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_NUM_ALREADY_EXISTS;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_write_$group_num$(file, (<span style="color: #228b22;">int64_t</span>) num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_write_$group_num$(file, (<span style="color: #228b22;">int64_t</span>) num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_write_$group_num$(file, (int64_t) num);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_num$_32</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">int32_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">u_num</span> = 0;
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span> = TREXIO_GROUP_READ_ERROR;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_read_$group_num$(file, &u_num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_read_$group_num$(file, &u_num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc =trexio_json_read_$group_num$(file, &u_num);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
*num = (<span style="color: #228b22;">int32_t</span>) u_num;
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_num$_32</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">int32_t</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (num < 0 ) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_num$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_NUM_ALREADY_EXISTS;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_write_$group_num$(file, (<span style="color: #228b22;">int64_t</span>) num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_write_$group_num$(file, (<span style="color: #228b22;">int64_t</span>) num);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_write_$group_num$(file, (int64_t) num);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_num$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">int32_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
<span style="color: #a020f0;">return</span> trexio_read_$group_num$_32(file, num);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_num$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">int32_t</span> <span style="color: #a0522d;">num</span>)
|
|
{
|
|
<span style="color: #a020f0;">return</span> trexio_write_$group_num$_32(file, num);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_has_$group_num$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_has_$group_num$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_has_$group_num$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_has_$group_num$(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgf3dcbb2" class="outline-4">
|
|
<h4 id="orgf3dcbb2"><span class="section-number-4">3.2.2</span> Fortran templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-2-2">
|
|
<p>
|
|
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from Fortran.
|
|
These templates are based on the use of <code>iso_c_binding</code>. Pointers have to be passed by value.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_num$_64</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_num$_64</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_num$_64</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_num$_64</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_num$_32</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_num$_32</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_num$_32</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_num$_32</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_num$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_num$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_num$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, num) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> num</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_num$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_has_$group_num$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_has_$group_num$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgbbfaaf5" class="outline-3">
|
|
<h3 id="orgbbfaaf5"><span class="section-number-3">3.3</span> Templates for front end has/read/write a dataset of numerical data</h3>
|
|
<div class="outline-text-3" id="text-3-3">
|
|
<p>
|
|
This section concerns API calls related to datasets.
|
|
</p>
|
|
|
|
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Function name</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
<th scope="col" class="org-left">Precision</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>trexio_has_$group_dset$</code></td>
|
|
<td class="org-left">Check if a dataset exists in a file</td>
|
|
<td class="org-left">---</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_dset$</code></td>
|
|
<td class="org-left">Read a dataset</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_dset$</code></td>
|
|
<td class="org-left">Write a dataset</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_dset$_32</code></td>
|
|
<td class="org-left">Read a dataset</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_dset$_32</code></td>
|
|
<td class="org-left">Write a dataset</td>
|
|
<td class="org-left">Single</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_dset$_64</code></td>
|
|
<td class="org-left">Read a dataset</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_dset$_64</code></td>
|
|
<td class="org-left">Write a dataset</td>
|
|
<td class="org-left">Double</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div id="outline-container-orgbf9ee71" class="outline-4">
|
|
<h4 id="orgbf9ee71"><span class="section-number-4">3.3.1</span> C templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-3-1">
|
|
<p>
|
|
The C templates that correspond to each of the abovementioned functions can be found below.
|
|
First parameter is the <code>TREXIO</code> file handle. Second parameter is the variable to be written/read
|
|
to/from the <code>TREXIO</code> file (except for <code>trexio_has_</code> functions).
|
|
Suffixes <code>_32</code> and <code>_64</code> correspond to API calls dealing with single and double precision, respectively.
|
|
The basic (non-suffixed) API call on datasets deals with double precision (see Table above).
|
|
</p>
|
|
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_dset$_64</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, $group_dset_dtype_double$* <span style="color: #a020f0;">const</span> $group_dset$)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> ($group_dset$ == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
rc = TREXIO_FAILURE;
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_read_$group_dset$(file, $group_dset$, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_read_$group_dset$(file, $group_dset$, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_read_$group_dset$(file, $group_dset$, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
/* <span style="color: #b22222;">Handle index type </span>*/
|
|
<span style="color: #a020f0;">if</span> ($is_index$) {
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dim_size</span> = 1;
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">i</span>=0; i<rank; ++i){
|
|
dim_size *= dims[i];
|
|
}
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$[i] += ($group_dset_dtype_single$) 1;
|
|
}
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_dset$_64</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> $group_dset_dtype_double$* $group_dset$)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> ($group_dset$ == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_dset$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_DSET_ALREADY_EXISTS;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
$group_dset_dtype_double$* $group_dset$_p = ($group_dset_dtype_double$*) $group_dset$;
|
|
|
|
/* <span style="color: #b22222;">Handle index type </span>*/
|
|
<span style="color: #a020f0;">if</span> ($is_index$) {
|
|
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dim_size</span> = 1;
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">i</span>=0; i<rank; ++i){
|
|
dim_size *= dims[i];
|
|
}
|
|
|
|
$group_dset$_p = CALLOC(dim_size, $group_dset_dtype_double$);
|
|
<span style="color: #a020f0;">if</span> ($group_dset$_p == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$_p[i] = $group_dset$_p[i] - ($group_dset_dtype_single$) 1;
|
|
}
|
|
}
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
rc = TREXIO_FAILURE;
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_write_$group_dset$(file, $group_dset$_p, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_write_$group_dset$(file, $group_dset$_p, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_write_$group_dset$(file, $group_dset$_p, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
/* <span style="color: #b22222;">Handle index type </span>*/
|
|
<span style="color: #a020f0;">if</span> ($is_index$) {
|
|
FREE($group_dset$_p);
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_dset$_32</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, $group_dset_dtype_single$* <span style="color: #a020f0;">const</span> $group_dset$)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> ($group_dset$ == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dim_size</span> = 1;
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">i</span>=0; i<rank; ++i){
|
|
dim_size *= dims[i];
|
|
}
|
|
|
|
$group_dset_dtype_double$* $group_dset$_64 = CALLOC(dim_size, $group_dset_dtype_double$);
|
|
<span style="color: #a020f0;">if</span> ($group_dset$_64 == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
rc = TREXIO_FAILURE;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_read_$group_dset$(file, $group_dset$_64, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_read_$group_dset$(file, $group_dset$_64, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_read_$group_dset$(file, $group_dset$_64, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS){
|
|
FREE($group_dset$_64);
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
}
|
|
|
|
<span style="color: #a020f0;">if</span> ($is_index$) {
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$[i] = ($group_dset_dtype_single$) $group_dset$_64[i] + ($group_dset_dtype_single$) 1;
|
|
}
|
|
} <span style="color: #a020f0;">else</span> {
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$[i] = ($group_dset_dtype_single$) $group_dset$_64[i];
|
|
}
|
|
}
|
|
|
|
FREE($group_dset$_64);
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_dset$_32</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> $group_dset_dtype_single$* $group_dset$)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> ($group_dset$ == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_dset$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_DSET_ALREADY_EXISTS;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dim_size</span> = 1;
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">i</span>=0; i<rank; ++i){
|
|
dim_size *= dims[i];
|
|
}
|
|
|
|
$group_dset_dtype_double$* $group_dset$_64 = CALLOC(dim_size, $group_dset_dtype_double$);
|
|
<span style="color: #a020f0;">if</span> ($group_dset$_64 == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
/* <span style="color: #b22222;">A type conversion from single precision to double reqired since back end only accepts 64-bit data </span>*/
|
|
<span style="color: #a020f0;">if</span> ($is_index$) {
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$_64[i] = ($group_dset_dtype_double$) $group_dset$[i] - ($group_dset_dtype_double$) 1;
|
|
}
|
|
} <span style="color: #a020f0;">else</span> {
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dim_size; ++i){
|
|
$group_dset$_64[i] = ($group_dset_dtype_double$) $group_dset$[i];
|
|
}
|
|
}
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
rc = TREXIO_FAILURE;
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_write_$group_dset$(file, $group_dset$_64, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_write_$group_dset$(file, $group_dset$_64, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_write_$group_dset$(file, $group_dset$_64, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
FREE($group_dset$_64);
|
|
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, $group_dset_dtype_default$* <span style="color: #a020f0;">const</span> $group_dset$)
|
|
{
|
|
<span style="color: #a020f0;">return</span> trexio_read_$group_dset$_$default_prec$(file, $group_dset$);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> $group_dset_dtype_default$* $group_dset$)
|
|
{
|
|
<span style="color: #a020f0;">return</span> trexio_write_$group_dset$_$default_prec$(file, $group_dset$);
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_has_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_has_$group_dset$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_has_$group_dset$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_has_$group_dset$(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org4df451d" class="outline-4">
|
|
<h4 id="org4df451d"><span class="section-number-4">3.3.2</span> Fortran templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-3-2">
|
|
<p>
|
|
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from <code>Fortran</code>.
|
|
These templates are based on the use of <code>iso_c_binding</code>. Pointers have to be passed by value.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_dset$_64</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_double$, <span style="color: #a020f0;">intent</span>(in) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_dset$_64</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_dset$_64</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_double$, <span style="color: #a020f0;">intent</span>(out) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_dset$_64</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_dset$_32</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_single$, <span style="color: #a020f0;">intent</span>(in) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_dset$_32</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_dset$_32</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_single$, <span style="color: #a020f0;">intent</span>(out) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_dset$_32</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_default$, <span style="color: #a020f0;">intent</span>(in) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_dset$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
$group_dset_f_dtype_default$, <span style="color: #a020f0;">intent</span>(out) :: dset$group_dset_f_dims$
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_dset$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_has_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_has_$group_dset$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org4514b6b" class="outline-3">
|
|
<h3 id="org4514b6b"><span class="section-number-3">3.4</span> Sparse data structures</h3>
|
|
<div class="outline-text-3" id="text-3-4">
|
|
<p>
|
|
Sparse data structures are used typically for large tensors such as
|
|
two-electron integrals. For example, in the <code>trex.json</code> file sparse
|
|
arrays appear as for the <code>eri</code> :
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-python"><span style="color: #8b2252;">"ao_2e_int"</span> : {
|
|
<span style="color: #8b2252;">"eri_num"</span> : [ <span style="color: #8b2252;">"int"</span>, [ ] ]
|
|
<span style="color: #8b2252;">"eri"</span> : [ <span style="color: #8b2252;">"float sparse"</span>, [ <span style="color: #8b2252;">"ao.num"</span>, <span style="color: #8b2252;">"ao.num"</span>, <span style="color: #8b2252;">"ao.num"</span>, <span style="color: #8b2252;">"ao.num"</span> ] ]
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The electron repulsion integral \(\langle ij | kl \rangle\) is
|
|
represented as a quartet of integers \((i,j,k,l)\) and a floating
|
|
point value.
|
|
</p>
|
|
|
|
<p>
|
|
To store \(N\) integrals in the file, we store
|
|
</p>
|
|
|
|
<ul class="org-ul">
|
|
<li>An array of quartets of integers</li>
|
|
<li>An array of values (floats)</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Both arrays have the same size, \(N\), the number of non-zero integrals.
|
|
Knowing the maximum dimensions allows to check that the integers are
|
|
in a valid range, and also lets the library choose the smallest
|
|
integer representation to compress the storage.
|
|
</p>
|
|
|
|
<p>
|
|
Fortran uses 1-based array indexing, while C uses 0-based indexing.
|
|
Internally, we use a 0-based representation but the Fortran binding
|
|
does the appropriate conversion when reading or writing.
|
|
</p>
|
|
|
|
<p>
|
|
As the number of integrals to store can be prohibitively large, we
|
|
provide the possibility to read/write the integrals in chunks. So the
|
|
functions take two extra parameters:
|
|
</p>
|
|
<ul class="org-ul">
|
|
<li><code>offset</code> : the index of the 1st integral we want to read. An
|
|
offset of zero implies to read the first integral.</li>
|
|
<li><code>num</code> : the number of integrals to read.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
We provide a function to read a chunk of indices, and a function to
|
|
read a chunk of values, because some users might want to read only
|
|
the values of the integrals, or only the indices.
|
|
</p>
|
|
|
|
<p>
|
|
Here is an example for the indices:
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_chunk_ao_2e_int_eri_index_32</span>(<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>,
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">offset</span>,
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">num</span>,
|
|
<span style="color: #228b22;">int32_t</span>* <span style="color: #a0522d;">buffer</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (offset < 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (num < 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = 4; // <span style="color: #b22222;">To be set by generator : number of indices</span>
|
|
|
|
<span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">nmax</span>; // <span style="color: #b22222;">Max number of integrals</span>
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
|
|
rc = trexio_read_ao_2e_int_eri_num(<span style="color: #a020f0;">const</span> <span style="color: #228b22;">file</span>, &nmax);
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_read_chunk_ao_2e_int_eri_index(file, buffer, offset, num, rank, nmax);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_read_chunk_ao_2e_int_eri_index(file, buffer, offset, num, rank, nmax);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">default</span>:
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE; /* <span style="color: #b22222;">Impossible case </span>*/
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
For the values,
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_chunk_ao_2e_int_eri_value_64</span>(<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>,
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">offset</span>,
|
|
<span style="color: #a020f0;">const</span> <span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">num</span>,
|
|
<span style="color: #228b22;">double</span>* <span style="color: #a0522d;">buffer</span>)
|
|
{
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (offset < 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (num < 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
|
|
<span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">nmax</span>; // <span style="color: #b22222;">Max number of integrals</span>
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
|
|
rc = trexio_read_ao_2e_int_eri_num(<span style="color: #a020f0;">const</span> <span style="color: #228b22;">file</span>, &nmax);
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> rc;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_read_chunk_ao_2e_int_eri_value(file, buffer, offset, num, nmax);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_read_chunk_ao_2e_int_eri_index(file, buffer, offset, num, nmax);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">default</span>:
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE; /* <span style="color: #b22222;">Impossible case </span>*/
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgb3d5357" class="outline-3">
|
|
<h3 id="orgb3d5357"><span class="section-number-3">3.5</span> Templates for front end has/read/write a dataset of strings</h3>
|
|
<div class="outline-text-3" id="text-3-5">
|
|
</div>
|
|
<div id="outline-container-org33162ff" class="outline-4">
|
|
<h4 id="org33162ff"><span class="section-number-4">3.5.1</span> Introduction</h4>
|
|
<div class="outline-text-4" id="text-3-5-1">
|
|
<p>
|
|
This section concerns API calls related to datasets of strings.
|
|
</p>
|
|
|
|
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Function name</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>trexio_has_$group_dset$</code></td>
|
|
<td class="org-left">Check if a dataset exists in a file</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_dset$</code></td>
|
|
<td class="org-left">Read a dataset</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_dset$</code></td>
|
|
<td class="org-left">Write a dataset</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgbb52ee9" class="outline-4">
|
|
<h4 id="orgbb52ee9"><span class="section-number-4">3.5.2</span> C templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-5-2">
|
|
<p>
|
|
First parameter is the <code>TREXIO</code> file handle. Second parameter is the variable to be written/read
|
|
to/from the <code>TREXIO</code> file (except for <code>trexio_has_</code> functions).
|
|
</p>
|
|
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_dset$_low</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">char</span>* <span style="color: #a0522d;">dset</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (dset == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_read_$group_dset$(file, dset, rank, dims, max_str_len);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_read_$group_dset$(file, dset, rank, dims, max_str_len);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_read_$group_dset$(file, dset, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">char</span>** <span style="color: #a0522d;">dset</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (dset == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
<span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">dset_dim</span> = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &(dset_dim));
|
|
|
|
<span style="color: #a020f0;">if</span> (dset_dim == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">char</span>* <span style="color: #a0522d;">str_compiled</span> = CALLOC(dset_dim*(max_str_len+1) + 1, <span style="color: #228b22;">char</span>);
|
|
<span style="color: #a020f0;">if</span> (str_compiled == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
rc = trexio_read_$group_dset$_low(file, str_compiled, max_str_len);
|
|
<span style="color: #a020f0;">if</span> (rc != TREXIO_SUCCESS) {
|
|
FREE(str_compiled);
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
}
|
|
|
|
<span style="color: #228b22;">char</span> * <span style="color: #a0522d;">pch</span>;
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i < dset_dim; i++) {
|
|
|
|
pch = i == 0 ? strtok(str_compiled, TREXIO_DELIM) : strtok(<span style="color: #008b8b;">NULL</span>, TREXIO_DELIM) ;
|
|
<span style="color: #a020f0;">if</span> (pch == <span style="color: #008b8b;">NULL</span>) {
|
|
FREE(str_compiled);
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
|
|
strcpy(dset[i], <span style="color: #8b2252;">""</span>);
|
|
strcat(dset[i], pch);
|
|
|
|
}
|
|
|
|
FREE(str_compiled);
|
|
<span style="color: #a020f0;">return</span> TREXIO_SUCCESS;
|
|
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_dset$_low</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>* <span style="color: #a0522d;">dset</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (dset == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_dset$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_DSET_ALREADY_EXISTS;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
int64_t $group_dset_dim$ = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &($group_dset_dim$));
|
|
|
|
<span style="color: #a020f0;">if</span> ($group_dset_dim$ == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">rank</span> = $group_dset_rank$;
|
|
<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">dims</span>[$group_dset_rank$] = {$group_dset_dim_list$};
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #228b22;">char</span>* <span style="color: #a0522d;">tmp_str</span> = CALLOC(dims[0]*(max_str_len+1), <span style="color: #228b22;">char</span>);
|
|
<span style="color: #a020f0;">if</span> (tmp_str == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
<span style="color: #228b22;">char</span>** <span style="color: #a0522d;">dset_str</span> = CALLOC(dims[0], <span style="color: #228b22;">char</span>*);
|
|
<span style="color: #a020f0;">if</span> (dset_str == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
<span style="color: #228b22;">char</span>* <span style="color: #a0522d;">pch</span>;
|
|
<span style="color: #228b22;">size_t</span> <span style="color: #a0522d;">pch_len</span>;
|
|
/* <span style="color: #b22222;">parse the string using strtok </span>*/
|
|
<span style="color: #a020f0;">for</span>(<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i<dims[0]; i++) {
|
|
|
|
pch = i == 0 ? strtok( (<span style="color: #228b22;">char</span>*) dset, TREXIO_DELIM) : strtok(<span style="color: #008b8b;">NULL</span>, TREXIO_DELIM) ;
|
|
|
|
<span style="color: #a020f0;">if</span> (pch == <span style="color: #008b8b;">NULL</span>) {
|
|
FREE(dset_str[0]);
|
|
FREE(dset_str);
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
|
|
pch_len = strlen(pch);
|
|
|
|
<span style="color: #a020f0;">if</span> (pch_len > max_str_len) {
|
|
FREE(dset_str[0]);
|
|
FREE(dset_str);
|
|
<span style="color: #a020f0;">return</span> TREXIO_INVALID_STR_LEN;
|
|
}
|
|
|
|
dset_str[i] = tmp_str;
|
|
strncpy(tmp_str, pch, pch_len);
|
|
tmp_str += pch_len + 1;
|
|
}
|
|
|
|
rc = TREXIO_FAILURE;
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
rc = trexio_text_write_$group_dset$(file, (<span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>**) dset_str, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
rc = trexio_hdf5_write_$group_dset$(file, (<span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>**) dset_str, rank, dims);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> rc = trexio_json_write_$group_dset$(file, dset, rank, dims);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
FREE(dset_str[0]);
|
|
FREE(dset_str);
|
|
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
|
|
}
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>** <span style="color: #a0522d;">dset</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (dset == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_dset$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_DSET_ALREADY_EXISTS;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span>;
|
|
<span style="color: #228b22;">int64_t</span> <span style="color: #a0522d;">dset_dim</span> = 0;
|
|
|
|
/* <span style="color: #b22222;">Error handling for this call is added by the generator </span>*/
|
|
rc = trexio_read_$group_dset_dim$_64(file, &(dset_dim));
|
|
|
|
<span style="color: #a020f0;">if</span> (dset_dim == 0L) <span style="color: #a020f0;">return</span> TREXIO_INVALID_NUM;
|
|
|
|
<span style="color: #228b22;">char</span>* <span style="color: #a0522d;">str_compiled</span> = CALLOC(dset_dim*max_str_len + 1, <span style="color: #228b22;">char</span>);
|
|
<span style="color: #a020f0;">if</span> (str_compiled == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_ALLOCATION_FAILED;
|
|
|
|
strcpy(str_compiled, <span style="color: #8b2252;">""</span>);
|
|
<span style="color: #a020f0;">for</span> (<span style="color: #228b22;">uint64_t</span> <span style="color: #a0522d;">i</span>=0; i < dset_dim; i++) {
|
|
strcat(str_compiled, dset[i]);
|
|
strcat(str_compiled, TREXIO_DELIM);
|
|
}
|
|
|
|
rc = trexio_write_$group_dset$_low(file, str_compiled, max_str_len);
|
|
|
|
FREE(str_compiled);
|
|
|
|
<span style="color: #a020f0;">return</span> rc;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_has_$group_dset$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_has_$group_dset$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_has_$group_dset$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_has_$group_dset$(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orga35d58c" class="outline-4">
|
|
<h4 id="orga35d58c"><span class="section-number-4">3.5.3</span> Fortran templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-5-3">
|
|
<p>
|
|
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from <code>Fortran</code>.
|
|
These templates are based on the use of <code>iso_c_binding</code>. Pointers have to be passed by value.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_dset$_low</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset, max_str_len) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> dset(*)</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_dset$_low</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_dset$_low</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset, max_str_len) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> dset(*)</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_dset$_low</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_has_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_has_$group_dset$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset, max_str_len)</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(inout) ::<span style="color: #a0522d;"> dset(*)</span>
|
|
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">allocatable</span> ::<span style="color: #a0522d;"> str_compiled(:)</span>
|
|
<span style="color: #228b22;">integer</span>(8) ::<span style="color: #a0522d;"> $group_dset_dim$</span>
|
|
<span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> rc</span>
|
|
|
|
rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
|
|
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) trexio_read_$group_dset$ = rc
|
|
|
|
<span style="color: #a020f0;">allocate</span>(str_compiled($group_dset_dim$*(max_str_len+1)+1))
|
|
|
|
rc = trexio_read_$group_dset$_low(trex_file, str_compiled, max_str_len)
|
|
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
|
|
<span style="color: #a020f0;">deallocate</span>(str_compiled)
|
|
trexio_read_$group_dset$ = rc
|
|
<span style="color: #a020f0;">else</span>
|
|
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_str2strarray</span>(str_compiled, $group_dset_dim$, max_str_len, dset)
|
|
<span style="color: #a020f0;">deallocate</span>(str_compiled)
|
|
trexio_read_$group_dset$ = TREXIO_SUCCESS
|
|
<span style="color: #a020f0;">endif</span>
|
|
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_dset$</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_dset$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, dset, max_str_len)</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> dset(*)</span>
|
|
|
|
<span style="color: #228b22;">character</span>(len=:), <span style="color: #a020f0;">allocatable</span> ::<span style="color: #a0522d;"> str_compiled</span>
|
|
<span style="color: #228b22;">integer</span>(8) ::<span style="color: #a0522d;"> $group_dset_dim$</span>
|
|
<span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> rc</span>
|
|
|
|
rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
|
|
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
|
|
trexio_write_$group_dset$ = rc
|
|
<span style="color: #a020f0;">else</span>
|
|
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_strarray2str</span>(dset, $group_dset_dim$, max_str_len, str_compiled)
|
|
trexio_write_$group_dset$ = trexio_write_$group_dset$_low(trex_file, str_compiled, max_str_len)
|
|
<span style="color: #a020f0;">endif</span>
|
|
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_dset$</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org769408d" class="outline-3">
|
|
<h3 id="org769408d"><span class="section-number-3">3.6</span> Templates for front end has/read/write a single string attribute</h3>
|
|
<div class="outline-text-3" id="text-3-6">
|
|
</div>
|
|
<div id="outline-container-org4529784" class="outline-4">
|
|
<h4 id="org4529784"><span class="section-number-4">3.6.1</span> Introduction</h4>
|
|
<div class="outline-text-4" id="text-3-6-1">
|
|
<p>
|
|
This section concerns API calls related to string attributes.
|
|
</p>
|
|
|
|
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
|
|
|
|
|
|
<colgroup>
|
|
<col class="org-left" />
|
|
|
|
<col class="org-left" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th scope="col" class="org-left">Function name</th>
|
|
<th scope="col" class="org-left">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="org-left"><code>trexio_has_$group_str$</code></td>
|
|
<td class="org-left">Check if a string attribute exists in a file</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_read_$group_str$</code></td>
|
|
<td class="org-left">Read a string attribute</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="org-left"><code>trexio_write_$group_str$</code></td>
|
|
<td class="org-left">Write a string attribute</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-org25a72a6" class="outline-4">
|
|
<h4 id="org25a72a6"><span class="section-number-4">3.6.2</span> C templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-6-2">
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_read_$group_str$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #228b22;">char</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">str</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (str == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
|
|
<span style="color: #228b22;">trexio_exit_code</span> <span style="color: #a0522d;">rc</span> = TREXIO_FAILURE;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_read_$group_str$(file, str, max_str_len);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_read_$group_str$(file, str, max_str_len);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_read_$group_str$(file, str);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_write_$group_str$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">char</span>* <span style="color: #a0522d;">str</span>, <span style="color: #a020f0;">const</span> <span style="color: #228b22;">uint32_t</span> <span style="color: #a0522d;">max_str_len</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
<span style="color: #a020f0;">if</span> (str == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_2;
|
|
<span style="color: #a020f0;">if</span> (max_str_len <= 0) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_3;
|
|
<span style="color: #a020f0;">if</span> (trexio_has_$group_str$(file) == TREXIO_SUCCESS) <span style="color: #a020f0;">return</span> TREXIO_NUM_ALREADY_EXISTS;
|
|
|
|
<span style="color: #228b22;">size_t</span> <span style="color: #a0522d;">len_write</span> = strlen(str);
|
|
<span style="color: #a020f0;">if</span> (max_str_len < len_write) <span style="color: #a020f0;">return</span> TREXIO_INVALID_STR_LEN;
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_write_$group_str$(file, str);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_write_$group_str$(file, str);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_write_$group_str$(file, str);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-c"><span style="color: #228b22;">trexio_exit_code</span>
|
|
<span style="color: #0000ff;">trexio_has_$group_str$</span> (<span style="color: #228b22;">trexio_t</span>* <span style="color: #a020f0;">const</span> <span style="color: #a0522d;">file</span>)
|
|
{
|
|
|
|
<span style="color: #a020f0;">if</span> (file == <span style="color: #008b8b;">NULL</span>) <span style="color: #a020f0;">return</span> TREXIO_INVALID_ARG_1;
|
|
|
|
assert(file->back_end < TREXIO_INVALID_BACK_END);
|
|
|
|
<span style="color: #a020f0;">switch</span> (file->back_end) {
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_TEXT:
|
|
<span style="color: #a020f0;">return</span> trexio_text_has_$group_str$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
|
|
<span style="color: #a020f0;">case</span> TREXIO_HDF5:
|
|
<span style="color: #a020f0;">return</span> trexio_hdf5_has_$group_str$(file);
|
|
<span style="color: #a020f0;">break</span>;
|
|
/*
|
|
<span style="color: #b22222;"> case TREXIO_JSON:</span>
|
|
<span style="color: #b22222;"> return trexio_json_has_$group_str$(file);</span>
|
|
<span style="color: #b22222;"> break;</span>
|
|
*/
|
|
}
|
|
|
|
<span style="color: #a020f0;">return</span> TREXIO_FAILURE;
|
|
}
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgcf7769a" class="outline-4">
|
|
<h4 id="orgcf7769a"><span class="section-number-4">3.6.3</span> Fortran templates for front end</h4>
|
|
<div class="outline-text-4" id="text-3-6-3">
|
|
<p>
|
|
The <code>Fortran</code> templates that provide an access to the <code>C</code> API calls from Fortran.
|
|
These templates are based on the use of <code>iso_c_binding</code>. Pointers have to be passed by value.
|
|
</p>
|
|
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_str$_c</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, str, max_str_len)</span><span style="color: #a0522d;"> </span><span style="color: #a020f0;">&</span>
|
|
<span style="color: #a020f0;">bind</span>(C, name=<span style="color: #8b2252;">"trexio_write_$group_str$"</span>)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> str(*)</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_str$_c</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_str$_c</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, str, max_str_len)</span><span style="color: #a0522d;"> </span><span style="color: #a020f0;">&</span>
|
|
<span style="color: #a020f0;">bind</span>(C, name=<span style="color: #8b2252;">"trexio_read_$group_str$"</span>)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> str(*)</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_str$_c</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">interface</span>
|
|
<span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_has_$group_str$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file) bind(C)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_has_$group_str$</span>
|
|
<span style="color: #a020f0;">end interface</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_read_$group_str$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, str, max_str_len)</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> str(*)</span>
|
|
|
|
trexio_read_$group_str$ = trexio_read_$group_str$_c(trex_file, str, max_str_len)
|
|
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_read_$group_str$</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #228b22;">integer </span><span style="color: #a020f0;">function</span><span style="color: #a0522d;"> </span><span style="color: #0000ff;">trexio_write_$group_str$</span><span style="color: #a0522d;"> </span><span style="color: #000000; background-color: #ffffff;">(trex_file, str, max_str_len)</span>
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>, <span style="color: #a020f0;">only</span> : <span style="color: #008b8b;">c_null_char</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trex_file</span>
|
|
<span style="color: #228b22;">integer</span>(4), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_str_len</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> str</span>
|
|
|
|
<span style="color: #228b22;">character</span>(len=<span style="color: #a020f0;">len_trim</span>(str)+1) ::<span style="color: #a0522d;"> str_c</span>
|
|
|
|
str_c = <span style="color: #a020f0;">trim</span>(str) // <span style="color: #008b8b;">c_null_char</span>
|
|
|
|
trexio_write_$group_str$ = trexio_write_$group_str$_c(trex_file, str_c, max_str_len)
|
|
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_write_$group_str$</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="outline-container-orgaf1b95c" class="outline-2">
|
|
<h2 id="orgaf1b95c"><span class="section-number-2">4</span> Fortran helper/wrapper functions</h2>
|
|
<div class="outline-text-2" id="text-4">
|
|
<p>
|
|
The function below adapts the original C-based <code>trexio_open</code> for Fortran.
|
|
This is needed due to the fact that strings in C are terminated by <code>NULL</code> character <code>\0</code>
|
|
unlike strings in Fortran.
|
|
Note, that Fortran interface calls the main <code>TREXIO</code> API, which is written in C.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">contains</span>
|
|
<span style="color: #228b22;">integer</span>(8) <span style="color: #a020f0;">function</span> <span style="color: #0000ff;">trexio_open</span> (filename, mode, backend)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>, <span style="color: #a020f0;">only</span> : <span style="color: #008b8b;">c_null_char</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> filename</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> mode</span>
|
|
<span style="color: #228b22;">integer</span>(trexio_backend), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> backend</span>
|
|
<span style="color: #228b22;">character</span>(len=<span style="color: #a020f0;">len_trim</span>(filename)+1) ::<span style="color: #a0522d;"> filename_c</span>
|
|
<span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> rc</span>
|
|
|
|
filename_c = <span style="color: #a020f0;">trim</span>(filename) // <span style="color: #008b8b;">c_null_char</span>
|
|
trexio_open = trexio_open_c(filename_c, mode, backend)
|
|
<span style="color: #a020f0;">if</span> (trexio_open == 0_8) <span style="color: #a020f0;">then</span>
|
|
<span style="color: #a020f0;">return</span>
|
|
<span style="color: #a020f0;">endif</span>
|
|
rc = trexio_set_one_based(trexio_open)
|
|
<span style="color: #a020f0;">if</span> (rc /= TREXIO_SUCCESS) <span style="color: #a020f0;">then</span>
|
|
rc = trexio_close(trexio_open)
|
|
trexio_open = 0_8
|
|
<span style="color: #a020f0;">endif</span>
|
|
<span style="color: #a020f0;">end function</span> <span style="color: #0000ff;">trexio_open</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The subroutine below transforms an array of Fortran strings into one big string using <code>TREXIO_DELIM</code> symbol
|
|
as a delimeter and adds <code>NULL</code> character in the end in order to properly pass the desired string to
|
|
C API. This is needed due to the fact that strings in C are terminated by <code>NULL</code> character <code>\0</code>.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">subroutine</span> <span style="color: #0000ff;">trexio_strarray2str</span>(str_array, max_num_str, max_len_str, str_res)
|
|
<span style="color: #a020f0;">use</span>, <span style="color: #a020f0;">intrinsic</span> :: <span style="color: #0000ff;">iso_c_binding</span>, <span style="color: #a020f0;">only</span> : <span style="color: #008b8b;">c_null_char</span>
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_num_str </span>! <span style="color: #b22222;">number of elements in strign array</span>
|
|
<span style="color: #228b22;">integer</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_len_str </span>! <span style="color: #b22222;">maximum length of a string in an array</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> str_array(*)</span>
|
|
<span style="color: #228b22;">character</span>(len=:), <span style="color: #a020f0;">allocatable</span>, <span style="color: #a020f0;">intent</span>(out) ::<span style="color: #a0522d;"> str_res</span>
|
|
<span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> i</span>
|
|
|
|
str_res = <span style="color: #8b2252;">''</span>
|
|
<span style="color: #a020f0;">do</span> i = 1, max_num_str
|
|
str_res = str_res // <span style="color: #a020f0;">trim</span>(str_array(i)) // TREXIO_DELIM
|
|
<span style="color: #a020f0;">enddo</span>
|
|
str_res = str_res // <span style="color: #008b8b;">c_null_char</span>
|
|
|
|
<span style="color: #a020f0;">end subroutine</span> <span style="color: #0000ff;">trexio_strarray2str</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<p>
|
|
The subroutine below does the reverse tranformation from one big string with delimeters into an array of Fortran strings.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">subroutine</span> <span style="color: #0000ff;">trexio_str2strarray</span>(str_flat, max_num_str, max_len_str, str_array)
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
|
|
<span style="color: #228b22;">integer</span>(8), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_num_str </span>! <span style="color: #b22222;">number of elements in strign array</span>
|
|
<span style="color: #228b22;">integer</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> max_len_str </span>! <span style="color: #b22222;">maximum length of a string in an array</span>
|
|
<span style="color: #228b22;">character</span>, <span style="color: #a020f0;">intent</span>(in) ::<span style="color: #a0522d;"> str_flat(*)</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(inout) ::<span style="color: #a0522d;"> str_array(*)</span>
|
|
|
|
<span style="color: #228b22;">character</span>(len=max_len_str) ::<span style="color: #a0522d;"> tmp_str</span>
|
|
<span style="color: #228b22;">integer</span> ::<span style="color: #a0522d;"> i, j, k, ind, offset</span>
|
|
<span style="color: #228b22;">integer</span>(8) ::<span style="color: #a0522d;"> len_flat</span>
|
|
|
|
len_flat = (max_len_str+1)*max_num_str + 1
|
|
|
|
ind=1
|
|
offset=1
|
|
<span style="color: #a020f0;">do</span> i=1,max_num_str
|
|
k = 1
|
|
tmp_str=<span style="color: #8b2252;">''</span>
|
|
<span style="color: #a020f0;">do</span> j=ind,len_flat
|
|
<span style="color: #a020f0;">if</span> (str_flat(j) == TREXIO_DELIM) <span style="color: #a020f0;">then</span>
|
|
ind=j+1
|
|
<span style="color: #a020f0;">exit</span>
|
|
<span style="color: #a020f0;">endif</span>
|
|
tmp_str(k:k) = str_flat(j)
|
|
k = k + 1
|
|
<span style="color: #a020f0;">enddo</span>
|
|
str_array(i)=tmp_str
|
|
offset=ind
|
|
<span style="color: #a020f0;">enddo</span>
|
|
|
|
<span style="color: #a020f0;">end subroutine</span> <span style="color: #0000ff;">trexio_str2strarray</span>
|
|
</pre>
|
|
</div>
|
|
|
|
|
|
<p>
|
|
The subroutine is a Fortran analogue of <code>assert</code> in C. It check that the the return code of the
|
|
TREXIO API call is equal to a given return code. It can optionally print a success message if the
|
|
two code are identical, i.e. if the <code>assert</code> statement pass.
|
|
</p>
|
|
|
|
<div class="org-src-container">
|
|
<pre class="src src-f90"><span style="color: #a020f0;">subroutine</span> <span style="color: #0000ff;">trexio_assert</span>(trexio_rc, check_rc, success_message)
|
|
<span style="color: #a020f0;">implicit</span> <span style="color: #228b22;">none</span>
|
|
|
|
<span style="color: #228b22;">integer</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> trexio_rc</span>
|
|
<span style="color: #228b22;">integer</span>, <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">value</span> ::<span style="color: #a0522d;"> check_rc</span>
|
|
<span style="color: #228b22;">character</span>(len=*), <span style="color: #a020f0;">intent</span>(in), <span style="color: #a020f0;">optional</span> ::<span style="color: #a0522d;"> success_message</span>
|
|
|
|
<span style="color: #228b22;">character</span>*(128) ::<span style="color: #a0522d;"> str</span>
|
|
|
|
<span style="color: #a020f0;">if</span> (trexio_rc == check_rc) <span style="color: #a020f0;">then</span>
|
|
<span style="color: #a020f0;">if</span> (<span style="color: #a020f0;">present</span>(success_message)) <span style="color: #a020f0;">write</span>(*,*) success_message
|
|
<span style="color: #a020f0;">else</span>
|
|
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">trexio_string_of_error</span>(trexio_rc, str)
|
|
<span style="color: #a020f0;">print</span> *, <span style="color: #a020f0;">trim</span>(str)
|
|
<span style="color: #a020f0;">call</span> <span style="color: #0000ff;">exit</span>(1)
|
|
<span style="color: #a020f0;">endif</span>
|
|
|
|
<span style="color: #a020f0;">end subroutine</span> <span style="color: #0000ff;">trexio_assert</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="postamble" class="status">
|
|
<p class="author">Author: TREX-CoE</p>
|
|
<p class="date">Created: 2021-06-17 Thu 18:22</p>
|
|
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
|
|
</div>
|
|
</body>
|
|
</html>
|