Russ Rew, Glenn Davis, Steve Emmerson, and Harvey Davies
このマニュアルは変更を一切加えない状態で、作成・配布しても構いません。ただし、その場合には前記の著作権の一文と以下の説明文が全ての複製版に明記されていなければなりません。このソフトウェアと付属しているマニュアル等の文章は全て「原状のままで(無保証で)」提供されており、いかなる保証も付きません。UCARは保証に関する一切の責任を否認することを宣言します。それらの保証は明示・黙示に関わらず責任を否認し、又商品としての黙示的保証及び特定の目的の為の適応性に関する保証も致しません。
Unidata Program Center は University Corporation for Atmospheric Researchによって運営され、National Science Foundationによる補助を受けています。この作品中に示されている見解・発見・結論・推奨等は著者のものであり、必ずしもNational Science Foundationの見解・発見・結論・推奨等を反映しているとは限りません。
この文章中に会社・製品名が記載されていても Unidata Program Centerがそれらの会社・製品等を推奨しているわけではありません。Unidataはこの著作物から得られた情報を宣伝・広告等の目的に使用することを許可しておりません。
Unidata ( http://www.unidata.ucar.edu )はNational Science Foundationがスポンサーしている計画で、全米の大学にコンピューター及びネットワークの革新的な使用方法を提供することによって、大気及び大気関連のデータを最大限に利用し教育・研究に活かすための強力な武器を与えています。そのようなデータを解析・表示するにあたってUnidata Program CenterはUniversity of Wisconsin, Purdue University, NASA, and the National Weather Service等を含む他団体が開発したソフトウェアパッケージを大学側に提供しています。これらのソフトウェアに共通していることはデータをリアルタイムで取得し管理するUnidataが開発したシステムを使用していることです。このことによってUnidataの主張でもある、各地域に必要とされている各大学によるデータベースの独自取得・自己管理を実現できました。重要なのはUnidata 計画がデータセンターを有しないことです。データ管理は「分担」される任務であるべきなのです。
このマニュアル中で紹介されているNetwork Common Data Form (NetCDF) ソフトウェアは本来、数あるUnidataのアプリケーション用に共通のデータアクセス方法を提供する目的で開発されました。これらは定点観測・時系列・定間隔格子・衛星やレーダー観測等の様々なデータの種類を網羅しています。
NetCDFソフトウェアはI/Oライブラリとして機能し、 C・FORTRAN・C++・ Perl等の NetCDF が存在する全ての言語から呼び出し可能です。このライブラリは自己記述型マシン独立型のデータベースにデータを格納・引出します。個々のNetCDF ファイルは多次元の定義された変数(整数・実数・文字・バイト等の複数の種類を含む)を含むことが可能で、さらに各々の変数に従属的なデータ(単位・説明文など)を付随させることが出来ます。このインターフェースは既存のNetCDFファイルに既定された方法でデータを追加することが出来、機能的には(固定長の)記録方式と類似しているところもあります。しかしながら、 NetCDF ライブラリでは変数名・インデックスによってのみデータの直接アクセス格納や引出が可能であり、 ディスク(もしくはメモリ)保存型のファイルにのみ適応することが出来ます。
Unidataのソフトウェアの半分ほどは既にNetCDFアクセス可能になっており、以後、残りのUnidataのアプリケーションについても同様の共有制を持たせる予定です。それによって次のことが可能になります。
NetCDFは既にいくらか成功を収めています。現在ではNetCDFはCRAYからパーソナルコンピュータ、そしてほとんどのUNIXワークステーションを含むコンピュータのプラットフォームとして幅広く使用されています。NetCDFを使ってあるコンピュータ上で(例えばFORTRANで)複雑なファイルを作成し、その同じ自己記述型のファイルを他のコンピュータ上(例えばC)で 一切の変換なしで引き出すことが出来ます。ムNetCDF のファイルはネットワーク経由で転送したり、適切なネットワークファイルシステムを使用することによりリモート・アクセスすることも可能です。
Unidataソフトウェア以外のソフトウェアにおいてNetCDFアクセスを可能にすることはUnidataの支持層の利益に繋がると信じ、NetCDFライブラリをライセンスや重大な規制無く配布し、最新のバージョンをanonymous FTP経由で手に入れられるようにしてあります。このように自由に使用することを許可することによりUnidataの情報を解析・表示する手段のオプションが豊富になることと思われます。Unidataのソフトウェアは大気科学コミュニティー以外でも幅広く受け入れられているようで、現在では数多くのパブリックドメインや商業用データ解析システムがNetCDFファイルを読みこむことが出来ます。
いくつかの 組織ではNetCDFはデータ・アクセス法の標準として採用されており、NCSA(National Center for Supercomputer Applications; University of Illinois at Urbana-Champaignと提携している)ではHDFファイル形式(NCSAで使用されているツールがNetCDFプログラミング・インターフェースを支持する動きもあります。我々はこれらの動きを支持し、協力してきました。
NetCDFのソフトウェアがどれほどサポートされているのかという疑問が 時々寄せられます。 Unidataの正式な立場はNetCDFライブラリに添付されている著作権に関する事項にも述べられておりますが、ソフトウェアは全て‘as is(無保証)’の状態で提供されているというものです。実際には、ソフトウェアは随時アップデートされていくものなので、Unidataは当面、ソフトウェアを改良しつづける予定であります。 Unidataの目的は米国の地球科学者をサポートすることであるので、それらの学会・団体より寄せられた問題点が最優先されることをご了承下さい。
ユーザーの皆様がこのソフトウェアを重宝して下さり、活用法に関するフィードバックや改良点に関する提案を返してくだされば光栄に存じます。
Network Common Data Form (NetCDF)インターフェースのの 目的は 配列指向型のデータを自己記述型でかつポータブルなフォマーットで作成・アクセス・共有することにあります。 「自己記述型」とはそのファイルが自身に含まれるデータに関する情報を内包しているという意味です。「ポータブル」とはファイル内のデータが整数・文字・浮動小数点の格納方式が異なるコンピュータ間でやり取りできるということです。NetCDFインターフェースを使用して作った新しいファイルは、即、「ポータブル」になります。 データアクセス・管理・解析・表示するソフトウェアにNetCDFインターフェースを使用することにより、より有用なソフトウェアを作ることが出来ます。
NetCDFのソフトウェアにはNetCDFデータアクセス用にCとFORTRANのインターフェースを搭載しています。共通のプラットフォーム用にこのようなライブラリは用意されております。
NetCDFデータアクセス用のC++ と Perlのインターフェース もUnidataにより提供されています。NetCDFユーザのご助力によりそのほかのプラットフォームや他のプログラム言語用のソフトウェア・ポート もあります。配列指向型のデータやソフトウェアを共有し、より価値のあるファイルを作成することを目的に、NetCDFのソフトウェア・ライブラリのソースコードは無料で配布されています。
この ユーザー・ガイドはNetCDFデータモデルの紹介ですが、 FORTRAN のインターフェースのみで表示できます。他の言語のインターフェースリンクについてはNetCDF World Wide Web Site http://www.unidata.ucar.edu/packages/netcdf/ をご参照下さい。C, FORTRAN, C++ and Perl 用の表示文書がオンラインであります。同じサイトにUNIXシステム用の参照文書もCとFORTRANのインターフェース用にUNIX ユmanユページの形式であります。NetCDF World Wide Web Siteには他にもNetCDFに関する膨大な情報とNetCDFデータを使用できるソフトウェアへのポインタも掲載されています。
Network Common Data Form、すなわちNetCDF、は配列形式のデータを格納・引出すためのデータアクセス関数ライブラリへのインターフェースです。配列とはn次元(nは0,1,2...)の矩形構造を持ち、その要素が全て同じデータタイプ((例)8ビット文字、32ビット整数)のものを指します。スカラー(単純な一つの値)は0次元の配列です。
NetCDF はデータとは自己記述的でポータブルなオブジェクトの集合体であり、簡単なインターフェースを通じて引出し可能であるべきであるという見方を支持する抽象概念です。配列値 はデータの格納方式に関する事前の知識無しに直接アクセスできます。データに関する補助的な情報(例えば単位等)はデータと伴に格納できます。NetCDFのデータベースは一般的なユーティリティやアプリケーションプログラムを使用してアクセスでき、データの特定フィールドを変換・統合・解析・表示することが可能です。そのようなアプリケーションの開発はデータの有用性を向上させ、又、配列指向型のデータの管理・解析・表示を行うソフトウェアの再利用性の向上に繋がるでしょう。
NetCDFソフトウェアは抽象的データタイプを利用します。これはNetCDFファイル内のデータにアクセス・操作する命令は全てインターフェースによって提供されている関数のみを使わなければならないということです。データの表現はインターフェースを使うアプリケーションからは隠されており、データの格納方式は既存のプログラムに影響を及ぼすことなく変更できます。 NetCDFデータの物理的な表現方法はデータが作成されたコンピュータから独立しているように設計されています。
UnidataはC・FORTRAN・C++・PERL・色々なUNIX OSのためのNetCDFインターフェースを サポートしています。 このソフトウェアは各メジャーリリース前に、他数種類のOS用にこれらのOSのユーザーの皆様のご助力で移植テストをされています。 Unidataの NetCDF ソフトウェアは幅広い利用を促進するためにFTPを通じて無料で配布されております。
何故、配列指向型のデータ格納に関して既存のデータベース管理システムよりNetCDFの方が優れているのでしょうか?それはリレーショナルデータベースソフトウェアがNetCDFインターフェースがサポートするデータアクセス法に適していないからです。
まず、既存のリレーションモデルをサポートするデータベースシステムは データアクセスの基本単位として多次元のオブジェクト(配列)をサポートしていません。配列をリレーションとして表示することは便利なデータアクセス法を不便にし、又、多次元データや座標系の抽象化に対してはほとんど何のサポートもしていません。 配列指向型データを引出・修正・数学的に扱い・表示するためにはまったく異なるデータモデルが必要なのです。
これに関連し、汎用的なデータベースシステムに関する2番目に大きな問題があります。大きな配列に対するパフォーマンスの悪さです。衛星写真・科学的モデルの結果・長期的な全地球気象観測のデータなどを集積を効率的に引出せるように系統立て索引をつけることは既存のデータベースシステムの能力を超えています。
最後に、汎用的なデータベースシステムは資源面でもアクセスパフォーマンス面でも多大な犠牲の元に、配列指向型のデータを解析・管理・表示するためには不必要な機能を提供しています。例えば、精巧なアップデート機能・履歴検査・報告書のフォーマット・業務処理用の機能など科学的な操作には不必要なものばかりです。
ネットワーク透過性(マシン独立性)を達成するために、NetCDFはデータの表現・コード化のための標準プロトコルであるXDR(eXternal Data Representation; ftp://ds.internic.net/rfc/rfc1832.txt参照 ) に似た外部表現機能を利用します。この表現機能はデータをマシン独立型のビット列へとコード化します。 これは8ビットのバイトのみが一貫してコード化されるという前提のみにて、多種類のコンピューター上で既に実装されています。 IEEE 754 浮動小数点標準プロトコルが浮動小数点のデータを表現するのに使用されています。
NetCDFファイルののおおまかな構造の説明はSee NetCDFファイルの構造と性能にあります。
ファイル形式の詳細については See ファイルフォーマット仕様を参照してください。ただし、ファイル形式を指定した形でNetCDFファイルを読み取り・作成する独自の低レベルソフトウェアを開発することは好ましくありません。後に、フォーマットが更新された時に互換性に問題が生じる危険性があります。
NetCDFの 目的の一つは大きなファイルの部分集合へのアクセスを効率的に行うことであります。 この目的の為に、NetCDFは順次アクセスではなく直接アクセスを行います。 その方がデータが作成された順番と異なる順序で読み取られる場合や異なるアプリケーションによって読み取られる順番が異なる場合に有効です。
ポータブルな外部表現機能(XDR)に必要なオーバーヘッドの量は多くの要素に左右されます。例えばデータの種類・コンピュータの種類・データアクセスの粒度・コンピュータに実装されたXDRがのチューニング等の要素に依存します。通常の場合、オーバヘッドはアプリケーションが使用する全リソース量に比べると小さいため、 いずれの場合にも、XDRレイヤーにかかるオーバヘッドはデータのポータブルアクセスの利便性を考えると対した犠牲ではありません。
NetCDFを設計・実装するにあたってデータアクセスの効率は重大な要素でした。しかしながら、NetCDFインターフェースを非効率的に利用することは不可能ではありません。例えば、各記録から一つの値を要求するようなデータ摘出を行う場合などがそれにあたります。効率的にインターフェースを利用する方法に付いてはSee NetCDFファイルの構造と性能をご参照下さい。
NetCDF は配列を格納する為の汎用的なアーカイブフォーマットとして使用できます。NetCDFにおけるデータ圧縮は(低解像度の浮動小数点数を32ビットの配列で表す代わりに8ビットもしくは16ビットの整数配列を使用することにより)可能です。しかし、NetCDFの現行版はデータ圧縮率を最適にする設計にはなっていません。それ故、NetCDFは特定のデータベースのある特徴を生かした特殊目的用アーカイブフォーマットよりも多くのスペースを必要とするかもしれません。
NetCDFを使うことが、即、人間とマシンにとって意味のある「自己記述型」データを作成することと等価ではありません。変数や次元の名前は意味のあるものを用い、存在する慣例に従った形を取るべきです。次元に関しては(意味があると思われる場合には)対応する座標変数も与えるべきです。
属性は従属的な情報を供給する上で大変重要です。関連する慣習に従い、対応する標準属性を使用することが大切です。See 属性の慣習に一般的なアプリケーションソフトウェアのためのNetCDFライブラリ専用の属性やその慣習が記述されています。
いくつかの団体はNetCDFデータ用に独自の付加的慣例やスタイルを定義しています。これらの慣習やそれらの利用法に付いてはNetCDF Conventions site, http://www.unidata.ucar.edu/packages/netcdf/conventions.html を参照してください。
上記の慣例は都合の良い場合には使用すべきです。ローカルな使用のためにはしばしば付加的な慣例が必要とされます。このような慣例を敷く場合には、関連分野のユーザの為にも上記の NetCDF conventions siteに掲載しておくことが望ましいです。
NetCDFの 開発はUnidataの必要に迫られたしごく控えめな目標に向かって始められました。その目標とはUnidataのアプリケーションとリアルタイムの気象データとの間に共通のインターフェースを 提供することです。元々Unidataのソフトウェアは複数のハードウェアプラットフォーム上で実行され、CとFORTRANの両方からアクセスされることが前提にあったので、 Unidataの目標を達成することはより広く応用できるパッケージを提供する可能性をも秘めていました。 これらのパッケージを広く提供し、かつ同じような需要のある団体と協力することによって、我々は 科学的なデータを取得するために作られたあるソフトウェアが他の分野ばかりではなく同じ分野の中でさえも利用されない現状を打破しようと試みました。 (Fulker, 1988).
NetCDfソフトウェアの重要な コンセプトはNASA Goddard National Space Science Data Center (NSSDC)で開発されたデータアクセスソフトウェアの解説である論文、Treinish and Gough (1987) に記述されています。このソフトウェアによって提供されているインターフェースはCommon Data Format (CDF)と呼ばれ、 NASA CDF は元は配列を格納するための抽象化をサポートするプラットフォーム特定型のFORTRANライブラリとして開発されました。
NASA CDFパッケージは様々な種類のデータと幅広いアプリケーションに応用されてきました。NASA CDFは単純さ(サブルーチンは13個のみ)・格納フォーマットからの独立性・汎用性・データの論理的な見方をサポートする能力・一般的なアプリケーションに対するサポートという利点を備えていました。
1987年の8月にUnidataはコロラド州ボルダーで ワークショップが開催されました。 NASAと協力し、NASAの既存のインターフェースと互換性を持たせながらCDF FORTRANインターフェースを拡張・Cインターフェースを定義・一つのセルによるデータ集合体のアクセス許可をする可能性が追求されました。
それとは独自にNew Mexico Institute of Mining and Technologyの Dave RaymondはUNIX用にあるCソフトウェアのパッケージを開発していました。それは自己記述的データへの順次アクセスを可能にし、データの解析・分析・表示に対して「パイプとフィルター(又はデータフロー)」的なアプローチをサポートするものでした。 このパッケージもまた,「Common Data Format」 という名を冠しており、後に C-Based Analysis and Display System (CANDIS)へと改められました。Unidataは Raymondの成果を知り(Raymond, 1988)、名前付き次元、及び同一データオブジェクト内に形の異なる変数を使用するなどといった、彼の着眼点のいくつかをUnidata NetCDF インターフェースに起用しました。
1988年の初頭に Unidata のGlenn DavisがCで書かれXDRの上に被さった NetCDFパッケージの試作品を完成させました。この試作品は次の2点を証明しました。ひとつは単一ファイルのXDR上に実装されたCDFインターフェースの開発費用が許容内であること。そして2点目はそのようなプログラムがUNIXとVMSとの両方に実装可能であることでした。同時にそれは、小さく、ポータブルでNASA CDFと互換性のあるFORTRANインターフェースが望まれている汎用性を持ち得ないことも証明しました。 NASA CDF と Unidataユs NetCDFとはその後独自の発展を遂げましたが、NASA CDFの最新版は NetCDFと似たような特徴を持っています。
1988年の初頭に、1987年の Unidata CDFワークショップにも参加したSeaSpace, Inc.(カリフォルニア州サンディエゴにある商用ソフトウェア開発会) のJoe Fahleが独自にNASA CDFインターフェースをいくつか重要な点で拡張したCDFパッケージをCで開発しました (Fahle, 1989)。Raymondのパッケージと同様に、SeaSpace CDFソフトウェアは関連の無い形の変数を同一データオブジェクト内に含むことを許容し、多次元の配列に対する一般的なアクセス方法を可能にしました。 Fahleの成果はSeaSpace社では、画像処理システムに おける中間的な段階での格納形態として使われていました。このインターフェースとフォーマットは後に Terascanデータフォーマットへと発展していきます。
FahleのインターフェースはNASAのインターフェースを我々の目的に応じる形に拡張しようとした際に直面した問題の大部分を解決していました。1988年8月にUnidata NetCDF用インターフェースの形式を決定し、残された問題を解決するために小規模のワークショップが開催されました。 参加者は SeaSpace社のJoe Fahle 、Apple社の Michael Gough(NASA CDFソフトウェアの開発者の一人)、 Miami大学のAngel Li (VMSにNetCDFソフトウェアの試作品を実装し、ユーザー候補である人)、それにUnidataのシステム開発部のスタッフ達でした。いくつか簡略できる点が指摘された後にワークショップとしての合意が得られました。Glenn DavisとRuss Rewがソフトウェアの最初のバージョンを完成させる前に、ワークショップの成果を含んだUnidata NetCDFインターフェースの仕様に関する文書が意見交換を促すために広く配布されました。他のデータアクセスインターフェースとの比較やNetCDFを使用した感想に付いてはRew and Davis (1990a)、Rew and Davis (1990b)、 Jenter and Signell (1992)、 and Brown, Folk, Goucher, and Rew (1993)で議論されています。
1991年10月にNetCDF ソフトウェア2.0版の配布開始を発表しました。Cインターフェースに小さな修正を加えた(次元の長さを int ではなく long と宣言した)ことによって MS-DOSコンピューター等の安価なプラットフォーム上でのNetCDFの利便性を向上させました。さらに他のプラットフォーム上での再コンパイル作業を必要としないという利点もありました。このインターフェースへの変更は関連するファイルフォーマットの変更が必要となることもありませんでした。
1993年6月に NetCDF 2.3版がリリースされました。このバージョンではファイルフォーマットに変更はなされませんでしたが、記録への単一呼び出しアクセス・不連続なデータに関する断面へのアクセスの最適化・ユstrideユを使用した指定断面への部分サンプリング・ヤmapped array sections(マップされた配列断面)ユを使用した不連続データへのアクセス・ ncdumpとncgenユーティリティの改良・試験的な C++ インターフェース等が追加されました。
1996年2月にリリースされた2.4版では新たなプラットフォームやC++インターフェースへのサポートが加えられ、又、スーパーコンピューターのアーキテクチャに関しては重要な最適化がなされました。
1996年5月にNetCDFデータに高レベルなインターフェースを提供するソフトウェアのFAN (File Array Notation)の配布が開始された。FANのユーティリティーにはNetCDFのファイルから配列指向データを抽出し操作する・NetCDF配列から特定のデータを印刷する・ASCIIデータをNetCDFデータにコピーする・NetCDFアレイ上で様々な統計操作(sum, mean, max, min, product,ノ) を行う等が含まれました。 FAN に関する詳細は FAN Utilities document, http://www.unidata.ucar.edu/packages/netcdf/fan_utils.html にあります。
このガイドは 1997年 1月にリリースされたnetCDF 3の説明文です。NetCDF 3版は過去のバージョンと同じファイルフォーマットを使用しますが、 2.4版に比べていくつかの大きな変更がなされています。
NetCDF データモデルは名前付き属性を持つ名前付き配列変数の集合として系統だてられるデータに関しては広く応用が利きます。しかしながらこのモデルとソフトウェアの実装にはいくつかの重要な制限があります。 この制限の一部はNetCDFが包含する要求の中で相反するものに対するトレードオフに内在するものであります。他の制限に関しては次のバージョンにて対応していく予定です。
現在 NetCDF で使用できる外部数値データ種は 8-、 16-、 32-ビットの整数、 32-もしくは 64-ビットの浮動小数点数 に限られています。これらの限られたサイズはビットフィールドにデータを格納することに比べるとファイルスペースを無駄に使用する可能性があります。例えば、 9-ビットの数値の配列は16-ビットの短い整数として格納しなければなりません。1-、2-ビット長の数値を8-ビット長の値として格納するのは更に無駄が多くなります。
現行の NetCDF ファイルフォーマットでは一つのNetCDFファイルに格納できるデータは 2ギガバイトです。この制約はファイル内の配置格納の為に32ビットオフセットを使用しているために生じています。
現行のモデルの 制約の一つに各NetCDFファイルに対して無制限の(可変の)次元が一つしか使用できないことです。 無制限の次元においては複数の変数を共有することが可能ですが、それらの変数は同時に発展しなければなりません。これによってNetCDFモデルでは同一ファイル内において複数の無制限次元を持つ変数を扱ったり異なる変数に複数の無制限次元を持たせることができません。つまり、NetCDFモデルは矩型でない変数(例えば不調和な配列)の表現には不向きということになります。
データの完全な自己表現性にも限界があります。 実際にデータを共有したり格納したりする際には必ずと言って良いほど既存の決まり事が存在します。 NetCDFでは変数・次元・属性に意味のある名前、計算する際に使用可能な形態の単位、ファイル全体に関する属性値のテキストストリング、簡単な座標系に関する情報を格納出来ます。 しかし、より複雑なメタデータ(例えば一般的ではないグリッド上に正確に地球座標系 のデータを投影したり衛星からの映像を正確に表現するために必要な情報等)に対応するためには慣習を敷く必要がでてきます。
NetCDFデータモデルに適切な修正を加えることによりこれらの慣習が不必要になったり、メタデータの幾つかの種類を統一的かつコンパクトな方法で表現できるようになるかもしれません。例えば、NetCDFデータモデルに明確な 地球座標系を与えることによって複雑な地球座標系の慣習を簡易化することは可能ですが、データモデルが複雑になるという弊害があります。ここで問題となるのはモデルの豊かさと汎用性(多種多様なデータを扱える能力)との間に適切なトレードオフ地点を見つけることです。ある特定の分野の研究者同士が共有する概念を表すためだけに作られたデータモデルは複数の分野でデータを共有したり統合したりすることには不向きかもしれません。
NetCDFデータモデルはツリー・ネスト配列・ 循環的なデータ等のネスト型配列構造をサポートしていません。その最たる理由は現行のFORTRANインターフェースによって任意のNetCDFファイルを書き込み読み取れなければならないからです。複雑な表現方法や慣習によって、幾つかのネスト型構造を表現することは可能ですが、その結果、NetCDFの目標である自己記述型データではなくなってしまう可能性があります。
最後に、 現行の実装ではNetCDFファイルへの同時アクセスは制限されています。一つのファイルは同時に複数の人が読み取ることが出来ますが、書き込める人は一人に限られており、複数人による同時書き込みはサポートされていません。
現時点における計画では 等価的なデータパッキングの追加、同時アクセスのサポートの向上、2ギガバイト以上のファイルへのアクセス機能です。他にも実現可能であれば加えられる可能性のある拡張機能としてキーもしくは座標値によるデータアクセス、効率的な構造変更(例えば、新しい変数や属性の追加・変更等)、別のファイルのデータ断面へのポインタ機能、ネスト型配列(不調和配列・ツリー配列・循環型配列の表現の実現)への対応、複数の無制限次元の導入などです。
NetCDF ファイルは dimensions (次元)、 variables (変数)、 attributes (属性)等の情報を含み、全てに固有の名とID番号が割り振られています。データの意味や配列指向のデータフィールド間の関係をを把握するためにこれらの構成成分を同時に使用することが出来ます。 NetCDF ライブラリではファイル通常のファイル名のみでなくID番号によっても指定される複数のNetCDF ファイルに同時にアクセス可能です。
NetCDFファイルには記号テーブルが存在し、変数の名・データタイプ・ランク(次元数)・次元・開始ディスクアドレス等の情報が記載されています。 個々の要素はそのIDを表す配列索引(subscript、添字)の一次関数であるディスクアドレスに記憶されています。つまり、これらの索引を別々に保存する必要が無く(この点で関係データベースと異なる)、素早くコンパクトな記憶法である。
次元、変数、属性の名はローマ字もしくはアンダースコアで始まる任意のローマ字と数字で構成されている文字列(アンダースコア'_’、ハイフン'-'を含む)で表されます。(ただし、アンダ-スコアで始まる名はシステム用にのみ使用します。)
ここで簡単なNetCDFの例を使い、 NetCDFデータモデルの原理を説明します。このデータには次元も変数も属性も含まれています。 この簡単な NetCDF オブジェクトの表記は CDL (network Common Data form Language)と呼ばれ、NetCDFファイルを表記するのに大変適しています。 NetCDFシステムにはバイナリのNetCDFファイルから人間指向のCDLテキストファイルを作成する、及び逆の操作を行うためのユーティリティが含まれています。
dimensions: // dimension names and lengths are declared first
lat = 5, lon = 10, level = 4, time = unlimited;
variables: // variable types, names, shapes, attributes
float temp(time,level,lat,lon);
temp:long_name = "temperature";
rh:long_name = "relative humidity";
rh:valid_range = 0.0, 1.0; // min and max
int lat(lat), lon(lon), level(level);
time:units = "hours since 1996-1-1";
:source = "Fictional Model Output";
data: // optional data assignments
lon = -160,-140,-118,-96,-84,-52,-45,-35,-25,-15;
rh =.5,.2,.4,.2,.3,.2,.4,.5,.6,.7,
.1,.3,.1,.1,.1,.1,.5,.7,.8,.8,
.1,.2,.2,.2,.2,.5,.7,.8,.9,.9,
.1,.2,.3,.3,.3,.3,.7,.8,.9,.9,
NetCDFファイル用の CDL表記は後述(See ncdumpを参照)のユーティリティプログラム ncdump を使って簡単に自動作成できます。別の NetCDF ユーティリティである ncgen はNetCDF ファイル(もしくは随意にNetCDFファイルを作成するために必要な呼び出しを含むC及びFORTRANのソースコード)をCDLインプットから作成します。(See ncgen)
CDL 表記法は単純で大部分が自明です。 NetCDFファイルの構成要素を説明してゆくに従いCDL 表記法のより詳細な部分を明らかにしていいkます。この時点では、 CDL文がセミコロンで終わることに注意してください。スペース・タブ・改行は自由に使って文を読みやすくしてください。 CDL のコメントはどの行においても ヤ // ユ に続きます。NetCDFファイルはCDL では下のように記述されます。
ここで name (名)は ncgen ユーティリティー を使ってファイル名を作成する際に単にデフォルトとして使用されます。 CDL記述には3つのオプションがあり、 dimensions ・ variables ・ data のキーワードによって開始されます。NetCDF 次元の宣言は dimensions の後に記述されます。NetCDF 変数及び属性は variables の後に定義され、変数データの割り当ては data の後に続きます。
次元は実際の物理的な次元(例えば、時刻・緯度・経度・高度等)を表すために使用します。また、次元は他の数量の指標(例えば、ステーションやモデル現行番号)としても使用できます。
NetCDF 次元は名前 name と 長さ lengthを持っています。次元長とは任意の正の整数ですが、 NetCDFファイル中の一つの次元は UNLIMITED の長さを持つことが出来ます。
そのような次元は無制限次元 unlimited dimension もしくは記録次元 record dimension と呼ばれます。無制限次元を持つ変数はその次元に沿って無制限に延びることが出来ます。無制限次元指標は従来の記録指向型ファイルにおける記録番号のようなものです。 一つの NetCDF ファイルは最大で一つの無制限次元しか持てませんが、無制限次元を持たなくても構いません。 もし、変数が無制限次元を持つとしたら、その次元は最も重要な(最も遅く変化する)ものでなくてはなりません。 従って、無制限次元は必ずCDL形式の最初の次元でなければならず、 FORTRAN配列宣言においては最後 の次元でなくてはなりません。
CDL 次元宣言はCDLキーワードの次元 dimensions に続く行(複数行でも可)に書かれます。同一行における複数の次元宣言は コンマで区切ります。宣言は各々名前=長さ name = length で表されます。
上記の例では4つの次元 lat 、 lon 、 level 、そして time があります。最初の3つの次元は固定長です。 Time は無制限長 UNLIMITED を与えられており、これは time が無制限次元 unlimited であることを意味します。
NetCDF ファイル中で名前のあるデータの基本単位は変数 variableです。変数はその形 shape が次元のリストとして定義されます。それらの次元は既に存在していなければなりません。次元の個数はランク rank (またはディメンショナリティ dimensionality )と呼ばれます。スカラー変数はランク0となり、ベクトルはランク1、マトリクスはランク2ということになります。
変数の形を定義するのに同じ次元を複数回使用しても構いません。(以前のバージョンのNetCDFではこれは不可能でした。)例えば、 correlation(instrument, instrument) と定義して、異なる機器で測定された値の相関を示すマトリクスを表すことが出来ます。しかし、物理的な空間/時間に相当する次元を持つデータは、たとえその次元の幾つかが同じ値を取る場合においても、異なる次元で構成される形を取るべきです。
変数 は大部分のデータをNetCDFのファイルとして格納するのに使用されます。変数とは同一タイプの値の配列を指します。 スカラー値は0次元の配列として扱われます。変数は名前・データタイプ・変数が定義されたときに与えられた次元のリストによる形を持ちます。 また、変数は関連する属性を持つことも出来ます。この属性は後に加え・削除し・変更することが出来ます。
変数外部データタイプとはNetCDFのタイプ typesの小さな集合の一つであり、次のような名前を持ちます。 FORTRAN インターフェースで NF_BYTE (同義語 NF_INT1 ), NF_CHAR , NF_SHORT (同義語 NF_INT2 ), NF_INT,NF_FLOAT (同義語 NF_REAL ), 及び NF_DOUBLE 。
CDL 表記ではではこれらはより単純な byte ・ char ・ short ・ int ・ float ・及び double 等の名前を与えられています。 real はCDL表記において float の同義語として使用できます。 long はint に対する deprecated 同義語です。 各変数の厳密な意味については「NetCDF外部データタイプ」 See NetCDF 外部データ型をご参照下さい。
CDL 変数宣言はCDKL単位中のキーワード variable に続きます。それらの形式は次元付きの変数については
t前述の CDL の例では変数が6つあります。次に述べるように、その内4つは座標変数です。残りの2つの変数 temp と rh は主変数 primary variables とも呼ばれ、一般的にデータと見なされるもので構成されています。各々の変数は time という無制限の次元を第一次元として含み、よって記録変数 record variables と呼ばれます。記録変数ではない変数は固定長(データ値の個数)を持ち、次元長の積に相当します。記録変数の長さはもその次元長の積ですが、この場合には無制限次元の長さが一定ではないためにその積は変数であり、当然変化します。無制限次元の長さは記録数に該当します。
NetCDFにおいては変数が次元と同一の名前を持つことが許されています。それらの変数はNetCDFライブラリにとっては特別な意味を持ちません。しかしながら、そのライブラリを使用するソフトウェアに特別な意味を持つ変数として扱われるという慣習があります。
次元と同じ名前を持つ 変数は座標変数 coordinate variable と称されます。通常はその次元に対応する物理的な座標を定義するために使われます。前出のCDLの例には次のように定義される座標変数 lat 、 lon 、 level 及び time が含まれています。
lon = -160,-140,-118,-96,-84,-52,-45,-35,-25,-15;
これらはこの次元に沿った地点における緯度・経度・気圧・時刻を定義しています。つまり、ここでは高度1000、850、700、及び500 mbarに相当する高度と北緯20、30、40、50、60度におけるデータが存在するということです。各座標変数はベクトルであり同一の名前を持つ次元のみで構成されている形を持つことに注意してください。
次元に沿った位置は指標 index を使用することによって指定できます。指標は整数であり、最小値は FORTRANでは1になります。前出の例では700 mbarレベルにおける指標は 3 となります。
次元に対応する座標変数が存在する場合には、その次元に沿った位置を指定するための代替的的で通常は寄り便利な方法があります。原稿の座標変数を使用するアプリケーションパッケージでは、それらの値が数値ベクトルであり、狭義の意味で単調である(全ての値は異なり、一方的に増加もしくは減少する)という仮定をしています。
NetCDFの 属性 attributes はデータに関するデータ(補助的データ ancillary data ・メタデータ metadata )を格納するために使用されます。その手法は従来のデータベースシステムのデータ辞書や図表を格納するのに使用されている手法と多くの類似点があります。大半の属性は特定の変数に関する情報を含んでいます。その変数の名前(もしくはID)と属性の名前と併せて識別されます。
幾つかの 属性はファイル全体の情報を与えており、グローバル属性( global attributes) と呼ばれます。これらは属性の名前とCDLの場合には空白の変数名、C及びFORTRANの場合には特別なnullグローバル変数IDによって識別されます。
属性には関連する変数(グローバル属性の場合にはnullグローバル変数)、名前、データタイプ、データ長、そして値があります。現行版においては全ての属性をベクトルとして扱っています。スカラー値は単一要素ベクトルとして扱われます。
可能な場合には従来の 属性名を使用する方が好ましいでしょう。新しく名前をつける場合には出来る限り意味のあるものを付けましょう。
属性の 外部タイプは定義される際に指定されます。属性に使用できるタイプは変数の場合のNetCDFの外部データタイプと同じです。異なる変数に同一の名前の属性がある場合には異なるタイプの場合があります。例えば、変数タイプ int の有効データ値の最大値を特定する属性 valid_max は int タイプであるべきです。それに対して変数タイプ double に対する属性 valid_max は double タイプであるべきです。
属性は変数や次元よりも ダイナミックです。属性は削除可能で、作成後にもタイプ・長さ・値を変更することが可能です。それに対して、NetCDFインターフェースでは変数を削除したり、変数のタイプや形を変更することは出来ません。
となります。 CDLにおいては各属性の タイプや長さは明確には宣言されません。 それらは属性に割り振られた値によって決定されます。単一の属性に所属する値は全て同一タイプでなければなりません。 色々なNetCDFタイプの定数に使用される表記法については後述する。(See データ 定数のCDL表記)
NetCDF の例(See Network Common Data Form Language (CDL))では units は変数 lat に対する属性で13文字列` degrees_north 'の配列値を持ちます。そして valid_range とは長さ2、値ヤ 0.0 ユ と ヤ 1.0 ユを持つ変数 rh の属性です。
NetCDFファイルの例では一つの グローバル属性--- source ---が定義されています。実際の NetCDFファイルではファイル全体の起源・歴史・慣習・特徴などを記述するためにより多くのグローバル属性を持つかもしれません。
NetCDFファイルを処理する 一般的なアプリケーションの多くは 標準的な属性の慣習に従っており、特に理由が内場合には慣習に従うことをお薦めします。 Units , long_name 、 valid_min 、 valid_max 、 valid_range 、 scale_factor 、 add_offset 、 _FillValue 、及び他の慣習的な属性についてはSee 属性の慣習を参照してください。
任意のNetCDFファイルが最初に作成されてから時がたっていても属性を定義することは可能です。ですから、ファイルの作成当初に使用される可能性のある属性を全て網羅するようと悩む必要はありません。しかし、既存のファイルに新しい属性を加えることはファイルをコピーするのと同じ作業量が必要となる場合があります。より詳しい議論はSee NetCDFファイルの構造と性能にあります。
データの塊を処理するために使われる変数に 対し、属性は補助的なデータやデータに関する情報のために使用されます。 NetCDFのオブジェクトに関連し、属性に格納された補助的なデータの総量は通常、メモリ上に十分保存できます。それに対し、変数は全体をメモリ上に保管するにはしばしば大きすぎ、 処理するために分割する必要が出てきます。
属性と変数の異なる点はまだあります。それは変数は多次元であることができることです。属性は全てスカラー(単一数値)もしくはベクトル(一方向に既定された次元)です。
変数はデータ値を割り当てられる前に名前・タイプ・形を定義されます。ですから値の無い変数が存在することもあります。属性の値は作成時に指定する必要があるので、値の無い属性は存在しません。
変数は属性を持ち得ますが、属性は属性を持つことが出来ません。変数に割り当てられた属性は変数と同じ単位を持つことが出来ます(例えば valid_range )。単位の無い属性というのも可能です(例えば scale_factor )。 関連する変数と異なる単位を使用するデータを格納したい場合には属性よりも変数を使うことをお薦めします。 より一般的には、データが説明のための補助的データを必要としたり、多次元であったり、データの値の指標として定義されたNetCDF次元を必要としたり、格納量が多大である場合には場合には 、データは属性よりも変数として表現されるべきでしょう。
この章では6つの基本的なNetCDFの外部データ型、及びNetCDFインターフェースによってサポートされているデータアクセスの種類を紹介し、さらに配列型以外のデータ構造がNetCDFファイルによって実装可能であるかを紹介します。
NetCDFインターフェースによってサポートされている外部データ型は以下の通りです。
これらはデータの精度と個々の値に必要なビット数の駆け引きの幅を広げるために設定されました。これらの外部データ型は任意のマシンや言語の組み合わせによってサポートされている内部データ型から完全に独立しています。
これらのデータ型が「外部」と呼ばれるのはNetCDFデータのポータブル外部表記に対応するからです。あるプログラムがデータを内部変数として読み込む際に、必要であれば指定された内部変数型に変換されます。同様に、内部データ型がNetCDF変数の外部データ型と異なる場合には、内部データをNetCDF変数として書き込む際に、異なる外部データ型に変換されてしまう可能性があります。
外部型と内部型を分離し、自動的に外部-内部タイプ変換をすることにはいくつかの利点があります。数値変数の外部データ型を知らなくても自動的にどのような数値型にも変換できるからです。 この特性を利用して、十分に幅広い範囲の内部データ型を使用することによって外部データ型から独立した 形にコードを単純化したりすることも可能です。即ち、数種類の異なる外部データ型を持つ数値NetCDFデータに関しては2倍精度になります。ある変数の外部データ型が変更されてもプログラムを書き換える必要は無いのです。
外部数値型から、もしくは外部数値型へ変換をする場合にはライブラリに任せます。このように外部データ表記と内部データ型間の変換を自動化し、両者を切り離すことはNetCDFの将来のバージョンにとってはより一層重要な意味を持ちます。圧縮データに新たな外部データ型が加えられ、それに自然に対応する内部データが存在しないケースも出てくるかもしれません。(例えば11ビット値の圧縮配列等)
ある数値型から別の型に変換する場合に、変換された値を表現しきれない型に変換するとエラーが生じます。例えば、内部の短い整数型では外部で整数として格納されているデータを表しきれないでしょう。数値配列にアクセスする際に、表現可能な領域から一つ以上の値がはみ出してしまった場合にはレンジエラーが返されてきます。領域内に収まる他の数値については正常な変換が行われます。
ここで注意して頂きたいのはデータ型の変換に伴う単なる精度の悪化ではエラーが返されないということです。つまり、2倍精度の数値を1倍精度の不動小数点数に変換した場合には、2倍精度の値が変換先のプラットフォームで表現可能な1倍精度の不動小数点数の範囲から逸脱しない限り、エラーは返されません。 同様に、不動小数点数の仮数の有効桁数では表しきれない程の大きな整数値を読み込んだ場合にも、この操作によって失われた精度に対するエラーは返されません。 このような精度のロスを避けるにはアクセスする前に外部データの変数型をチェックし、十分な精度を持つ内部データ型に変換するようにしてください。
基本外部データ型の名前( byte , char , short , int , float 又は real , 及び double)はCDLにおいては予約語です。ですから、変数・次元・属性の名前はこれらを使用してはいけません。
IB yte データは符号付整数値(-128〜127)としても符号無し整数値(0〜255)としても扱うことができます。しかし、 バイトデータ型を他の数値表現型に変換する場合には符号付数値として認識されます。
NetCDF外部データ型と任意の言語のデータタイプとの互換性についてはSee 変数を参照してください。
NetCDFデータにアクセスする(読み込む・書き込む)場合には ,オープンされたNetCDFファイル、NetCDF変数、及び変数の要素を特定する情報(例:番号)を指定します。アクセス機能の名前は内部データ型の名前に対応します。内部データ型と外部変数型の表現が異なる場合にはデータが読み書きされる際に内部型と外部型との間の変換が行われます。
データへは direct(直接)アクセスします。これによって大きなファイルから小さな部分集合を効率的にアクセスすることができます。その部分集合の前にあるデータを先にアクセスしないからです。 データを、ファイル中の位置ではなく、変数を指定することによって読み書きすることは 、データアクセスをそのファイルの中に他に幾つ変数が存在するかとは無関係になります。これによってデータに新たな変数が加わるデータフォーマットの変更に対してプログラムの書き換えは不必要になります。
CとFORTRANインターフェースでは、データアクセスをする度にファイルを名前で特定せずに、ファイルが初めて作成・オープンされた時に割り当てられるファイルIDと呼ばれる小さな整数によって識別されます。
同様に、 任意の変数はデータアクセスの度に名前で識別されません。その代わり、変数IDと呼ばれる、NetCDF中の各変数を識別するのに使用される小さな整数 によって識別されます。
NetCDFインターフェースにはオープンなNetCDFファイル中のデータ値に直接アクセスする方法が幾つか用意されています。これらのアクセス形式を汎用性の小さいほうら順に説明します:
4種類のベクトル ( index vector ・ count vector ・ stride vector ・ index mapping vector )は変数の各次元に対応する要素を一つずつ持っています。ですから、n次元の 変数(rank = n)についてはn個のベクトルが必要となります。変数がスカラー量(無次元)の場合には、 これらのベクトルは無視されます。
Array section (配列断面)とは2つのベクトルによって指定される連続的な直方体、もしくは「板切れ」のようなものです。 Index vectorが原点に最も近い角の要素の座標を表します。 Count vector は各変数の次元に沿った板切れの縁の長さを順番に表します。アクセスされた値の個数はこれらの縁の長さの積です。
Subsampled array section (部分サンプルされた配列断面)は array section に似ていますが、さらにに stride vector というベクトルを使用してサンプリングを識別するために使用されます。このベクトルは各次元ごとに要素があり、その次元に沿って取るべきストライドの長さを表しています。例えば、ストライドが4であるなら、その次元に沿って4つ置きの値をとるという意味になります。この場合にも、アクセスされた値の総数は count vector(カウントベクトル)の各要素の積になります。 .
Mapped array section (マップドアレイセクション)は subsampled array section に似ていますが、さらに index mapping vector (インデックスマッピング)が加わり、NetCDF変数に関連するデータのメモリー中の配置を指定することができます。 各値の参照値からのオフセットは 各インデックスと対応する index mapping vectorの要素を掛け合わせたものの和になります。(マッピングがされていない場合には仮想的な内部配列のインデックスが使用されます。)アクセスされた値の個数は subsampled array section の場合と同じになります。
マップされた配列断面の応用については後により詳細に述べます。その前に、より一般的な配列断面へのアクセスの例を見ましょう。
先に扱ったNetCDFファイルの例(See Network Common Data Form Language (CDL))において、あるレベル(例えば2段目)の temp 変数の全データの断面を読み取りたいとし、そしてそのNetCDFファイルには記録が3つ ( time 値)あるとます。次元は
FORTRANの場合にはCDL表記法とは次元が逆転しており、第一次元が最も早く変化し、記録変数の最後尾が記録次元となっています。それ故、一つのレベルのみのデータを保持している変数のFORTRAN における宣言は次のようになります。
PARAMETER (LATS=5, LONS=10, LEVELS=1, TIMES=3)
REAL TEMP(LONS, LATS, LEVELS, TIMES)
第2レベルにのみある全時刻・全緯度・全経度のデータブロックを識別するためには、始点インデックスと縁の長さを与えなければなりません。始点インデックスは FORTRANでは(1, 1, 2, 1) であるので、 time ・ lon ・ lat 次元については最初から開始したいのですが、 level 次元については2番目の値から開始したいわけです。 Time 値については3個全て、 level 値については1個のみ、 lat 値については5個全て、そして lon v値については10個全てを取得しいので、縁の長さは FORTRANでは(10, 5, 1, 3) になります。この操作によって合計150個(3*1*5*1)の不動小数点数が返されるので、これだけの数を収容するのに十分な配列スペースを 確保しなければなりません。このデータが返される順番は最も早く変化する 最初の次元 LON , になります:
Mapped array sections を使用することによって変数要素のディスクアドレスとメモリ上で格納されているアドレスの間に自明ではない関係を確立することができます。 例えば、メモリ上のマトリクスはディスク上のマトリクスを移項したもので、要素が全く異なる順番で格納されるかもしれません。通常の array sectionにおいてはディスク上とメモリアドレス の関係は自明です:メモリ内値の構造(次元サイズと順番)は array sectionのものと一致しています。しかしながら、mapped array sectionにおいてはNetCDFの変数要素の指数とそれらのメモリ上のアドレスとのマッピングを定義するのに index mapping vector が使用されます。
マップ アレイアクセスによって,メモリに常駐する配列の原点とある任意の点間とのオフセット量(配列の要素の数)は index mapping vectorとその点の coordinate offset vector の inner product 1 (内積)で表される。 ある任意の 点の coordinate offset vector は各次元の内包される配列の原点からその点までのオフセット量を与えます。 FORTRANではある点の, coordinate offset vectorの値は元のcoordinate vectorの値より1小さくなります。つまり、配列要素 A(3,5)のcoordinate offset vectorは[2, 4]になります。
通常の配列部分の index mapping vector はム最も早く変化する次元から最も遅く変化する次元の順番にム常に定数1を持つはずです。なぜならば、その値と最も早く変化する次元の一辺の長さの積を取り、その値と次に早く変化する次元の一辺の長さとの積を取る、という操作を繰る返すからです。 しかし、mapped arrayにおいては, NetCDF変数のディスク上での位置とメモリ上での位置との相関は異なることもあります。
マップドアレイアクセスに関する詳しい例はマップドアレイアクセスに関するインターフェースの説明文にあります。 See マップされた配列の値を書き込む: NF_PUT_VARM_ type.
NetCDF抽象化によって部分サンプルされた配列断面やマップドアレイセクションによるアクセスを可能ですが、 これらを使用する必要はありません。 これらのより汎用的なアクセス法が不必要な場合には、これらの機能を無視して単一値によるアクセスや通常の配列断面アクセス方法を使用してください。
NetCDF変数には各々、最初に定義された時に指定される外部タイプを所有しています。この外部タイプによってデータがテキストや数値として扱われるか判別されます。数値として扱われる場合には、その範囲と精度も指定されます。
NetCDFの変数の外部タイプが char の場合、テキスト配列である文字データのみが変数として書き込み、読み取ることが可能です。 テキストデータを異なるタイプのデータに自動変換する機能はサポートされていません。
ただし、数値データである場合には変数を異なるデータタイプとしてアクセスし、メモリに格納されている数値データとNetCDF変数との間で自動的にタイプ変換する機能をNetCDFライブラリは保有しています。例えば、全ての数値データを倍精度の浮動小数点数として 扱うプログラムを作成した場合には、NetCDF変数の外部タイプがどんなタイプであるかを気にせずに、NetCDFデータを倍精度配列に読み取ることができます。 NetCDFデータを読み取る際には、様様な大きさの整数 や単精度の浮動小数点数は、倍精度の数値用のデータアクセスインターフェースを使ってアクセスすれば、自動的に全て倍精度数値になります。もちろん、このように自動的に数値が変換されることを望まない場合には、その数値タイプが存在すれば、各々のNet CDF 変数の外部データタイプに対応したインターフェースを使用すれば避けられます。
NetCDFが行なう数値変換は大変わかりやすいものばかりです。それは、数値変換が任意のタイプのデータを別のデータタイプの変数を取るよう指定する操作であるからです。例えば、浮動小数点NetCDFデータを整数として読む場合には、結果は零に打ち切られます。浮動小数点数を整数の変数に割り付ける場合と同様です。このような打ち切りは数値変換に伴う精度悪化の例といえます。
ある数値タイプから他の異なる数値タイプに変換する場合にも、変換先のタイプが変換された数値を表すことのできないタイプの場合にもエラーが生じます。例えば、整数では外部タイプとしてIEEE浮動小数点数として格納されているデータを表せません。数値の配列をアクセスする際には、一つ以上の数値が表せる範囲外である場合にはレンジエラーが返ってきます。その他の範囲内にある数値については正しく変換されます。
注意すべき点は、タイプ変換による精度のロスのみではエラーを引き起こさないということです。例えば、倍精度の数値を整数として読む場合には、倍精度の数値の大きさが読込先のプラットフォームで表し切れる整数の範囲外でなければエラーと判定されません。 同様に、大きな整数を浮動小数点数に変換する際に、浮動小数点数の仮数部にその整数の全てのビットを表し切れなくて精度にロスが生じたとしてもエラーにはなりません。このような精度のロスを避けたい場合にはアクセスする変数の外部タイプをチェックして、使用する内部タイプと整合性があることを確認してください。
表し切れる範囲の境界に近い大きな浮動小数点数を書き込む場合にレンジエラーが生じるかどうかはプラットフォーム次第です。NetCDF浮動小数点変数に書き込める最大の浮動小数点数は、使用しているシステムで表せる 最大の浮動小数点数であり、2の128乗よりは小さい値です。倍精度変数に書き込める最大の倍精度数値は、使用しているシステムで表せる最大の倍精度数値であり、2の104乗より小さくなります。
この自動変換と外部データ表示とと内部とでデータタイプを切り離すことは、NetCDFの将来のバージョンにおいてより重要性を増してくるでしょう。それは、将来、対応する内部タイプが存在しない詰めありデータ用(例えば11ビット数値の配列等)に新たな外部データタイプが導入されることが考えられるからです。
NetCDF抽象化が直接的にサポートする唯一の データ構造は ベクトル属性つきの名前のついている配列の集合のみです。NetCDFはリンクされたリストや、ツリー、粗い配列、不均一な配列等、ポインタを必要とする種類のデータ構造を表現するのには適していません。
ある配列のデータを他の配列のデータへのポインタとして使用することに関する様様な慣例を採用することにより、配列の集合により他のデータ構造を構築することは可能です。そのようなデータ構造を構築する際に、NetCDFライブラリは役にも立ちませんが阻害もしません。その代わり、そのような慣例を設計する手段を提供します。
次の例は属性 row_index を使用して 不均質な配列 ragged_mat を格納し、 それによって各列の始点となるインデックスを指定することにより関連するインデックス変数の名前を与えています。 この例では、最初の列は12個(12-0)の要素からなり、2列目は7個(19 -12)、という具合に続きます。
ragged_mat:row_index = "row_start";
もう一つの例として、NetCDF変数は任意のNetCDFGファイルの中でグループ化することが挙げられます。各グループの変数の名前を伝統的な区切り文字であるスペースやコンマによってリストにしている属性を定義することによってこれは可能になります。このようなグループ化の為に属性名の慣習付けをすることによって幾つもの名前のある変数グループを作ることを可能にします。 ある特定の慣習に従った属性を各々の変数に与えることによって変数がどのグループに属しているかのリストが作れます。他の属性や変数を指定する属性や変数の導入により、 NetCDFファイルにおける幾種の複雑な構造を表すための柔軟な手段が与えられます。
NetCDF ライブラリ 使用する為にNetCDFインターフェースの事を全て知っている必要はありません。 NetCDFファイル作るのであれば片手で足りるほどのルーチンさえ知っていれば必要な次元・変数・属性を定義し、NEtCDFファイルにデータを書き込むことができます。( ncgen ユーティリティを使用して予めファイルを作成しておいてから、NetCDFライブラリのデータ書き込みコールを活用したプログラムを走らせたならば、使用するルーチンの数はより少なくなります。同様に、あるNetCDFオブジェクトに格納されたデータにアクセスするソフトウェアを作成する際には、NetCDFファイルを開き、データにアクセスする為にはNetCDFライブラリの本の一部のNetCDFライブラリしか使用しません。 もちろん、任意のNetCDFファイルにアクセスする包括的なアプリケーションを作る場合には、NetCDFライブラリにより精通している必要があります。
この章では通常の使用に必要な一般的なNetCDFのコールのシークエンスのテンプレートを幾つか紹介します。 明確さのため、ここではルーチンの名前のみを挙げています。宣言やエラーチェックについては触れていません。また、タイプに限定される変数や属性のルーチン名のサフィクスについても省略してあります。複数回使用される宣言文は字下げをしてあります。また、...を使用して他の宣言文の任意のシークエンスを表しています。 全パラメーターのリストは後の章で説明します。
これは新しいNetCDFファイルを生成するために使用する 一般的なNetCDFコールの配列です:
NF_DEF_VAR ! 変数の定義: 名前、タイプ、次元から
NF_CLOSE ! 閉じる: 新しいNetCDFファイルを保存する
コール一つでNetCDFファイルを作成できます。その時点では、二つあるNetCDFモードの最初のモードに入っています。開かれたNetCDFファイルにアクセスする際でしたら、定義モードもしくはデータモード に 入るはずです。定義モードでは次元・変数・新しい属性などを作れますが、変数データを読んだり書き込んだりすることは出来ません。データモードではデータにアクセスし、既存の属性を変更することは出来ますが、次元・変数・属性を 新たに作ることは出来ません。
新たに作られた時限には各々 NF_DEF_DIM へのコールが一つ必要となります。同様に全ての変数には NF_DEF_VAR へのコールが一つ必要です。さらに、定義され、値を割り振られた属性には NF_PUT_ATT ファミリーのメンバーへのコールが必要となります。 定義モードから出て、データモードに入るには NF_ENDDEF とコールしてください。
一度データモードに入ると、変数に新たなデータを加えたり、古い値を変更したり、既存の属性値を変更することが出来ます(ただし、属性については格納スペースが増加しないことが条件です。)NetCDF変数に単一の値を書き込むためには、書き込むデータ種によっては NF_PUT_VAR1 ファミリーのメンバーが必要となります。 NF_PUT_VAR ファミリーのメンバーを使用して変数の取るべき値を全て一度に書き込むにことも出来ます。変数の配列や配列断面は NF_PUT_VARA ファミリーを使って書き込めます。部分サンプルされた配列断面も NF_PUT_VARS ファミリーのメンバーを使うことによって書き込めます。マップドアレイセクションも NF_PUT_VARM ファミリーのメンバーを使うことによって書き込めます。 (部分サンプルやマップドアクセスは通常のデータアクセス法の一種であり、後に説明いたします。
最後に、 書き込むために開いたNetCDFファイルは NF_CLOSE を使って必ず閉じてください。ファイルシステムへのアクセスはデフォルトでNetCDFライブラリによってバッファーされています。 データを書き込める開かれた異常な状態でプログラムが終了された場合には、その回に加えた変更が全て無効になる可能性があります。このデフォルトでバッファーしてしまう機能は、ファイルを開く際に、 NF_SHARE フラグを立てることによって避けられます。 フラグが立っていても、定義モードで行なわれた属性値の変更や定義モードで変更された事項は NF_SYNC 又は NF_CLOSE がコールされない限り、実行されません。
ここでは NetCDFファイルの名前ばかりでなく、それに含まれている次元・変数・属性の名前も既知である場合を取り上げます。(そうでない場合には"inquireモコールをする必要があります。NetCDFファイルの中の変数のデータを読むための極一般的なCでのコールの順序は:
まず、ファイルの名前を与えることにより、 最初のコールがNetCDFファイルを開きます。そして、その後、開かれたファイルを参照するために必要なNetCDF IDを返します。
次に、 NF_INQ_DIMID へのコールでアクセスする次元ごとに 次元名に由来した次元IDが割り振られます。同様にして、必要な変数IDも変数名に由来する名前が NF_INQ_VARID へのコールで決定されます。 一旦、変数IDを手に入れれば、 NetCDF ID、変数ID、そして必要な属性名を使うことにより、 NF_GET_ATT ファミリーのメンバーとして入力することにより、変数の属性値も読み取れます。(通常、各々の属性に対して NF_GET_ATT_TEXT もしくは、 NF_GET_ATT_DOUBLE ) 。変数データの値はNetCDFファイルから、直接アクセスすることが出来ます。単一の値の場合には、 NF_GET_VAR1 ファミリーのメンバーへのコールのよって、 そして変数全体の場合には NF_GET_VAR ファミリーへ、又は配列・部分サンプル・マップドアクセスの場合には NF_GET_VARA , NF_GET_VARS , もしくは NF_GET_VARM ファミリーへのコールを使います。
最後に、 NetCDF ファイルは NF_CLOSE によって閉じられます。読み取るだけのためにファイルを開いた場合には閉じる必要はありません。
変数の名前を前もって知らなくてもその全ての変数を処理するようなプログラム(例えば総括的なソフトウェア)を作成することは可能です。同様に、次元や属性名も明らかではない場合もあります。
NetCDFのオブジェクトに関するほかの情報も”inquire”機能を使用してNetCDFファイルから得られます。この機能は全NetCDFファイル・次元・変数・属性等の情報を返します。 下記のテンプレートはそれらの使用法を示しています:
上記の例のようにコール一つで既存のNetCDFファイルが開き、NetCDF IDを返します。このNetCDF IDは NF_INQ ルーチンに送られ、その操作によって次元数・変数の数・グローバル属性の数・そして存在すれば無制限次元のIDが返されます
このinquire 機能は手頃で、I/Oを必要としません。それは、最初にNetCDFファイルを開いた時に、提供する情報がメモリ内に格納されるからです。
次元 IDは 1で始まる連続な整数を取り、一旦割り当てられると消去することは出来ません。また、次元も定義されたら消去することは出来ません。 ですから、NetCDFファイル中の次元IDの数を知るということは全ての時限IDを知ることと道義になります。それらは 1, 2, 3, ノ 等の整数で次元の数だけ存在します。各次元IDに大しては、inquire機能への NF_INQ_DIM で次元名と次元長が返されます。
変数 IDもまた連続した整数 1, 2, 3, ノ で表され、変数の数だけ存在します。変数IDは NF_INQ_VAR コールを使用して各変数に割り当てられた名前、タイプ、形状、と属性数を知ることが出来ます。
一旦、ある変数の 属性値が 既知になると、 NF_INQ_ATTNAME コールによって任意の変数に割り当てられたNetCDF ID・変数ID・属性数を知ることが出来ます。属性名が分かると, NF_INQ_ATT コールで属性タイプと属性長が分かります。タイプと長さから、属性値を格納するために十分なスペースを確保しておくことが出来ます。 次に、 NF_GET_ATT ファミリーの一員へコールすることにより変数値が返されます。
一度NetCDF変数のIDと形状が既知になると、データの値は単一の値の場合は NF_GET_VAR1 ファミリーへの一員へのコール、そして複数の場合には、 NF_GET_VAR, NF_GET_VARA, NF_GET_VARS, 又は様様な種類の配列アクセス法に関しては NF_GET_VARM へのコールすることになります。
既存の NetCDFファイルはかなりの変更を加えることが出来ます。すでに存在している次元・変数・属性などに新たに加えたり、名前を変更することも可能ですし、既存の属性は抹消することが出来ます。 次のコードのテンプレートは既存のファイルに新しい要素を加えるための極一般的な例です。
NF_DEF_DIM ! (あれば)新しい次元を定義し、加える。
NF_DEF_VAR ! (あれば)新しい変数を定義し、加える。
NF_PUT_ATT ! (あれば)新しい属性を定義し、加える。
NF_ENDDEF ! 定義をチェックし、定義モードから出る。
NetCDF ファイルは、まず、 NF_OPEN コールによって開きます。このコールによって、開かれたファイルはデータモードに入ります。このモードではきぞんんおデータ値にアクセスしたり変更を加えたりすることが出来ます。また、属性値も(大きくならない限りにおいては)変更できます。ただし、このモードでは何もたすことは出来ません。新しいNetCDF次元・変数・属性を加えるには NF_REDEF コールによってテイギモードに入らなければなりません。定義モードでは、新しい次元を定義するためには NF_DEF_DIM コールを、新しい変数を加えるには NF_DEF_VAR コールを、そして古い変数や増大してしまった古い属性に新しい属性を与えるには NF_PUT_ATT ファミリーへコールします。
定義モードから出て、再びデータモードに入ることも出来ます。そこで、新しい定義に矛盾が無いか等をチェックし、ディスクに保存するには NF_ENDDEF コールをしてください。データモードに戻りたくなければ、単に NF_CLOSE コールをしてください。これは、最初に NF_ENDDEF コールをしたことと同義になります。
NF_ENDDEF コールがなされる前であれば、 NF_ABORT コールによって、定義モードで行なった全ての再定義を無効にしてNetCDFライブラリを元の状態に戻せます。 また、この NF_ABORT コールを使って、 NF_ENDDEF コールが失敗した場合にNetCDFファイルを矛盾の無い状態まで復帰させることが出来ます。定義モードから NF_CLOSE コールをしたら自動的に追従する NF_ENDDEF へのコールが失敗した際には、 NF_ABORT コールが自動的に呼び出され、NetCDFライブラリは閉じられ、元の矛盾の無い状態(定義モードに入る前の状態)に戻ります。
一つのプロセスは書き込み用に一時に最大一個のNetCDFファイルを開いていなければなりません。ライブラリは、統制の取れた NF_SYNC 機能の利用と NF_SHARE 旗を立てることによって同時に複数の読者に扱われることに大してのすポートに制限を設けています。もし、書き込むほうが定義モードに変更を加えれば(例:新しい変数、次元、属性)、 そのライブラリに対して読者が同時にアクセスすることを防ぐ制約を外部から加える必要があり、また、読者に対して次回のアクセスの前にNF_SYNC を呼び出すように注意を促す必要が出てきます。
NetCDF ライブラリはエラー処理を柔軟に行なうのに必要な機能を揃えています。 個々のNetCDF 機能は整数のステータス値を返送します。もし、返送されたステータス値によっエラーが発見されると、その処理方法をどのようにするかは自由です。関連するエラーメッセージを表示することから、エラー表示を無視して続行することも(後者は推奨しかねますが)可能です。簡単な例として、このガイド中の例はエラーステータスを調べ、エラーを処理するために別個の機能を呼び出すようになっています。
返送されたせ異数のエラーステータスをエラーメッセージストリングに変換するために NF_STRERROR 関数が準備されています。
たまに、 low levell I/O エラーがNetCDFライブラリより下層で起こる可能性があります。 例えば、ある書き込みオペレーションにより割り当てられたディスク容量を越えてしまったら、既に存在しないデバイスに書き込もうとした場合に、NetCDFライブラリより下層からエラーメッセージを表示されることがあります。しかしながら、結果として書き込みエラーは返送されたステータス値に反映されます。
NetDCFのCやFORTRANインターフェースを使用するプログラムのコンパイルとNetCDFライブラリとリンクさせる方法 は各々の条件により異なります。オペレーティングシステム、使用するコンパイラー、NetCDFライブラリやインクルードファイルの格納先などの要因です。それでもここでは敢えて、UNIXプラットフォーム上でNetCDFライブラリを使用する プログラムをコンパイルしリンクする例を挙げます。各自、使用する状況に応じてこれらの例を応用してください。
NetCDF機能や定数を参照する FORTRAN ファイルには 適切な INCLUDE 文を 最初に参照する前に含んでいなければなりません:
FORTRANコンパイラが必ず参照する基本時辞書に netcdf.inc ファイルがインストールされていない限り、コンパイラを呼び出す際には -I オプションを使用し、 netcdf.inc がインストールされているディレクトリを指定する必要があります。例えば:
この章では、単独のNetCDFファイルもしくはNetCDFライブラリ全体を扱うNetCDF機能のインターフェースに付いて解説します。
開かれていない NetCDFファイルを参照する場合にはそのファイル名でのみ参照することが可能です。一度NetCDFファイルが開かれた後には、N etCDF ID によって参照されます。NetCDF IDとはファイルを生成又は開いた時に返される小さな非負の整数である。 NetCDF ID はCにおけるファイル記述子もしくはFにおける論理装置番号によく似ています。単一のプログラムにおいては、 開かれたNetCDFファイルのNetCDF IDはファイルごとに個別の値をとります。 あるNetCDFファイルが複数回開かれた場合には複数の異なるNetCDF IDを持つことになります。しかし、書き込み可能なNetCDFファイルは開かれたファイルのある一つのIDのファイルに限定されます。開かれていたNetCDFファイルが閉じられると、割り当てられていたNetCDF ID とそのファイル間の関連付けは断たれます。
NetCDFライブラリを操作する関数には以下のものがあります:
この章では、NetCDFのインターフェースを表現するために使用される慣習のまとめの後に、これらの操作のためのインターフェースについて詳細に記述します。
この章、及びこれに続く章の中で、 各々のインターフェースでのNetCDF関数についての解説には以下の項目が含まれます:
FORTRANの 関数プロトタイプと正式なパラメーターの定義では、出力パラメータ(返された値が格納される場所)は小文字で書かれ、大文字でかかれている入力パラメータと区別されています。
この例はエラーハンドリングに関する単純な慣習に沿って、各NetCDF関数に対する呼び出しで返されたステータスをもらさずチェックし、エラーが発見されると HANDLE_ERR subroutine を呼び出します。 そのような subroutineの例は See エラー状態に対応したエラーメッセージを得る: NF_STRERRORにあります。
関数 NF_STRERROR は、他のNetCDF関数を呼び出したときに返されであろう、整数NetCDFエラー状態又はシステムエラー番号に対応するエラーメッセージストリングに対し、静的な参照個所を返します。NetCDFのエラー状態のリストは各言語バインディング中の対応する内部ファイルにあります。
この関数によって新規のNetCDFファイルが生成されます。これによって返されたNetCDF IDは他のNetCDF関数呼び出しにおいてこのファイルファイルを参照するために使用できます。書き込みアクセス用に開かれ、定義モードになっているNetCDFファイルファイルに、新しい次元・変数・属性などを加えることが出来ます。
生成モードのフラグによって、既存の同一名のファイルを上書きするか、及びファイルへのアクセスが共有されるかなどを指定できます。
関数 NF_OPEN は既存のNetCDFファイルとアクセスするために開きます。
関数 NF_REDEF は開かれたNetCDFファイルを定義モードにし、次元・変数・属性などを付加又はそれらの名前を変更し、さらに属性を削除できるようにする。
関数 NF_ENDDEF は開かれたNetCDFファイルを定義モードから抜きます。定義モード中にNetCDFファイルに加えられた変更はチェックされ、問題なければディスクに書き込まれます。この時、非記録変数を"フィル値”に初期化することも可能です。(See 書き込みのフィルモードを設定する: NF_SET_FILLを参照。)NetCDFファイルはデータモードになり、 変数データを読み取り・書き込みが可能になる。
この呼び出しは、場合によってはデータをコピーする作業が含まれる。これに関しての詳細は See NetCDFファイルの構造と性能にあります。
関数 NF_CLOSE は開いているNetCDFファイルを閉じます。ファイルが定義モードにある場合には、閉じる前に NF_ENDDEF が呼び出されます。(この場合には、もし NF_ENDDEF がエラーを返せば、 NF_ABORT が自動的に呼び出され、最後に定義モードに入った時の矛盾の無い状態に復旧します。)開かれたNetCDFファイルが閉じられた後は、そのNetCDF ID は次に開かれる又は生成されるNetCDFファイルに割り当てることが出来ます。
関数 NF_INQ の一族は NetCDF IDを与えられた開かれたNetCDFファイルに関する情報を返します。ファイル問い合わせ関数は定義モードとデータモードのどちらからでも呼び出すことが出来ます。最初の関数 NF_INQ は次元数・変数の数・グローバル属性の数・無制限長で定義された次元があればその次元IDを返します。この一族の他の関数はこれらのうちどれか一つの情報を返します。
FORTRANでは、これに属する関数には NF_INQ 、 NF_INQ_NDIMS 、 NF_INQ_NVARS 、 NF_INQ_NATTS 、 NF_INQ_UNLIMDIM があります。
これらの関数が呼び出されても、必要な情報は開かれた個々のNetCDFファイルについてメモリ上にあるので、 I/O は行なわれません。
関数 NF_SYNC はメモリ内バッファとNetCDFファイルのディスク上コピーとを同期させる方法を提供します。 書き込み後に、同期させたい理由としては2つ挙げられます。
この関数はNetCDFライブラリ以前のバージョンと後方互換性があります。その目的は、一つのNetCDFファイルを複数の読者と一人の作成者の間で共有可能にすることにあります。作成者は書き込み後に NF_SYNC を呼び出し、読者は読み取る前に毎回 NF_SYNC を呼び出します。作成者側では、この操作によってバッファされているものが全てディスク上に移動します。読者側では、この操作によって次に読み取られる記録が以前にキャッシュされたバッファからではなく、ディスクからの読み取りであることが保証されます。これによって、読者はファイルを閉じて新たに開くことなく、書込み操作によって加えられた変更を見ることが出来ます(例えば書き込まれた記録数)。わずかなデータ量をアクセスする場合には、書き込み後に一々ディスクと同期させることは、バッファすることの有用性を手放すことになり、コンピュータ資源のコストを上げてしまいます。
共有を簡単にするために(そして推奨される方法は)、作成者、読者共にファイルを NF_SHARE フラグを立てて開くことです。そうすれば NF_SYNC を呼び出す必要は 全くなくなります。しかし、 異なる処理間において少数のNetCDFアクセスのみを同期させる場合には、 NF_SYNC 関数はNF_SHAREフラグよりも より細かい粒度を持ちます。
従属的なデータ(属性値など)に加えられた変更にも注意する必要があります。これらは NF_SHAREフラグによっては自動的に伝達されません。このためには NF_SYNC 関数を使わなければなりません。
作成者がデータの設計を変えるために定義モードに入った時にファイルを共有する場合は特に注意しなくてはなりません。以前のバージョンでは、作成者が定義モードを抜けると、変更は新ファイルに加えられたために、読者は旧ファイルを参照したままでした。読者が変更を見る為にはファイルを一度閉じて開きなおさなければなりませんでした。 それによって、変更されたファイルが手元にあっても、読者側の内部テーブルが新しいファイルの設計と一致していないことには読者には伝わりません。再定義後にもNetCDFファイルが共有されるためには、再定義中に読者がデータにアクセスするのを防ぎ、次にアクセスする前に読者に NF_SYNC を呼び出させる 、何らかのNetCDFライブラリ外のメカニズムが必要になります。
NF_SYNC を呼び出すとき、NetCDFファイルは データモードになくてはなりません。定義モードのNetCDFファイルは NF_ENDDEF が呼び出されたときにのみディスクと同期します。他の処理によって書き込まれているNetCDFファイルを読み取る処理は NF_SYNC を呼び出すことによって 、ファイルを閉じてサイド開くことなく、書き込み処理によって変えられた最新の変更(例えば、書かれた記録数)に関する情報を得られます。
この関数はもう、呼び出す必要がありません。 ファイルが定義モード中に、不具合が生じ変更を決定できない場合には、 NF_CLOSE によって自動的に呼び出されます。 関数 NF_ABORT は 定義モードに無い場合には、単にNetCDFファイルを閉じます。 もし、ファイルが生成されている最中で、まだ定義モードにある場合には、ファイルは削除されます。 NF_REDEF への呼び出しによって定義モードに入った場合には、NetCDFファイルは定義モードに入る以前の状態に復旧され、ファイルは閉じられます。
この例では NF_ABORT を使って、 foo.nc というファイルの再定義から撤退する。
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'LAT', 18, LATID)
IF (STATUS .NE. NF_NOERR) THEN ! 次元定義失敗
STATUS = NF_ABORT(NCID) ! 再定義中止
この関数は以下に述べる状況下での書き込みを最適化するための高度な使用を目的としています。関数 NF_SET_FILL は書き込み用に開かれたNetCDFファイルの フィルモード を設定し、返しの引数として現行のモードを返します。フィルモードは NF_FILL 又は NF_NOFILL のどちらででも設定でき、NF_FILLに対応したデフォルト状態はデータがフィル値によって既に埋められているというものです。即ち、非記録型変数を生成する際、もしくは未だに書き込まれていないデータを超えた値を記入する際に、フィル値が記入されます。これによって書き込まれる前にデータを読み取ってしまうことを感知できます。フィル値の使用法の 詳細については、 See フィル値。独自のフィル値の定義の仕方については See 属性の慣習。
NF_NOFILL に対応する動作は、データをフィル値で満たそうとするデフォルト動作を無効にします。これによって、NetCDFライブラリがフィル値を書き込み、さらにそれらの値が後にデータによって上書きされるという二重の操作を避けることができ、パフォーマンスが向上します。
返り値によってNetCDFファイルがどのモードにあったかということが分かります。この値を利用して、開かれたNetCDFファイルのフィルモードを一時的に変更し、後で元のモードに復旧させることが出来ます。
開かれたNetCDFファイルを NF_NOFILL モードにした後は、後で読み取られる全ての位置に有効なデータが書き込まれていることを確認してください。nofillモードは書き込み用に開かれたNetCDFファイルの一時的な性質でしかない点に注意してください。ファイルを一旦閉じて再度開いたときには、デフォルト動作に戻ります。又、フィルモードを陽に NF_NOFILL に設定するために、再び NF_SET_FILL を呼び出すことによってデフォルト動作に戻ることが出来ます。
nofillモードを設定することが有益な場合が3つあります。
もし、NetCDFファイルが無制限次元を持ち、最後の記録がnofillモードにおいて書き込まれた場合には、nofillモードが設定されていない場合に比べてファイルが短い可能性がある。 しかし、これはNetCDFインターフェースを通してのみデータアクセスすれば完全に透過性は保たれる。
将来のリリースでは、この機能はなくなっている(又は不必要)であるかもしれない。プログラマーの方はこの機能に必要以上に頼らないことが望ましい。
NetCDF ファイルの次元はファイルが作成されると同時に定義され、NetCDFファイルが定義モード中に行なわれる。 後に次元数を増やしたい場合などには定義モードに再び入れば良い。 NetCDF次元には次元名と次元庁が存在する。一つのNetCDFファイルは最大で一つの unlimited (無制限)次元を持つことが出来る。 この次元を使用する変数はこの次元沿いには無制限に成長できる。
一つのNetCDFファイルには定義できる次元数に上限(100)が提唱されている。この上限値は 事前に定義されたマクロ NF_MAX_DIM である。上限値を規定する目的は一般的なアプリケーションをより簡潔に作成できる点にある。それらのアプリケーションでは NF_MAX_DIMS 配列を用意することのよって任意のNetCDFファイルを扱うことができる。NetCDF ライブラリの実装においてはこの勧告された上限値 は強制項目ではない。それ故、必要に応じてそれ以上の次元数を使用することも可能である。しかし、勧告された上限値を守っているNetCDFユーティリティは、その結果生じるNetCDFファイルを扱えなくなる可能性もある
通常、次元名と次元長は次元がはじめて定義されるときに固定される。後に次元名を変更することは可能ではあるが、次元長(無制限次元を除いて)は既存のファイルの内容を新たに次元長を固定した新しいNetCDFファイルに コピーする以外に次元長を増やす手段はない。
開かれたNetCDFファイル中の NetCDF 次元は dimension IDと呼ばれる小さい整数によって参照されている。 FORTRAN インターフェースでは、次元IDは定義された順に 1, 2, 3, ノ,となる。
関数 NF_DEF_DIM 等は定義モード中であれば、新しい次元を開かれたNetCDFファイルに加えることが出来る。 NetCDFのIDを与えたあれば、この操作によって、(引数として)次元ID、次元名、次元長を返す。最大で一つの無制限次元(記録次元)がNetCDFファイルごとに定義できる
次元名。アルファベットの文字で始まり、次に零もしくはアンダースコア(ヤ _ ユ)を含む英数字が続く。大文字小文字は区別される。 |
|
次元長。この次元をインデックスとして使用する変数に対して、この次元が持ちうる値の数量。正の整数( size_tタイプ)もしくは事前に定義された定数 NF_UNLIMITED である。 |
|
これは NF_DEF_DIM 機能を使用して次元名 lat 次元長18、そして次元名 rec 次元長無制限の二つの次元を持つ新しい foo.nc というNetCDFファイルを生成する例です:
INTEGER STATUS, NCID, LATID, RECID
STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
関数 NF_INQ_DIMID は次元名を与えると、(引数として)NetCDFの次元IDをを返します。仮に ndims ある NetCDF ファイルに定義された次元数だとすると、各々の次元のIDは 1 と ndims. の間の値を取ります。
この関数のファミリーはNetCDF次元についての情報を返します。次元に関するの情報には次元名と次元長があります。無制限長の次元の長さは、存在していれば、その段階までに書かれた記録の数です。
このファミリーに属する関数は NF_INQ_DIM , NF_INQ_DIMNAME , そして NF_INQ_DIMLEN があります。関数 NF_INQ_DIM はその次元についての全ての情報を返します。他の機能はその次元についてある一つの情報を返します。
この 例では NF_INQ_DIM を使用して既存のNetCDFファイル foo.nc の lat と名づけられた次元の長さと無限長次元の現在の長さをを求めます:
INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
関数 NF_RENAME_DIM は開かれた書きこみ状態にあるNetCDFファイル中の次元の名前を変更します。新しい名前が古い名前よりも長い場合にはNetCDFファイルは定義モードになければなりません。他に同名の次元がある場合にはその名前に変更することはできません。
この 例では NF_RENAME_DIM を使用して既存のNetCDFファイル foo.nc 中の次元 lat を latitude に変更します:
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
NetCDFファイルにおける 変数はNetCDFファイルが生成され、定義モードに あるときに定義されます。再度、定義モードに入ることによって変数を足すことができます。NetCDF 変数には名前、型、及び形があり、変数が定義されるときに指定されます。変数は値を持つこともでき、後にデータモードにある時に確立されます。
通常、変数が最初に定義された段階で 名前、型、及び形は固定されますが、名前は後から変更できます。 しかし、変数の型と形は変更できません。無限長次元を使用して定義された変数はその次元に沿っては無限に成長できます。
開かれたNetCDFファイル中の NetCDF変数 は variable ID変数ID という小さな整数によって参照されます。
変数IDはNetCDFファイル中に定義された順番になっています。よって、変数IDは 1, 2, 3,ノ, という値を取ります。変数IDから変数名を取得 、またその逆をもできる機能が備わっています。
単位などの性質を指定するために変数に属性 (See 属性) を関連付けることもできます。
下の表には変数をFORTRAN インターフェースで定義するために必要なNetCDF外部データ型とそれに対応する型の定数を示してあります。
1段目にはNetCDF外部データ型がリストされていますが、これはCDLデータ型と同じです。2段目は NetCDF機能で使用する対応する FORTRAN パラメーター (パラメーターはNetCDF FORTRANインクルードファイル netcdf.inc で定義されています。) です。最後の段は対応する型の値を外部表記するために使用されるビット数です。
関数 NF_DEF_VAR は定義モードにある開かれたNetCDFファイルに新たに変数を追加します。NetCDFID・変数名・変数方・次元数・次元IDのリストを与えると、(引数として)変数IDを返します。
この例では NF_DEF_VAR を使用して、新しい foo.nc という名前のNetCDFファイル中に、 time , lat , and lon の3つの次元を持つ、変数名 rh のダブル型の変数を生成します:
INTEGER LATDIM, LONDIM, TIMDIM ! 次元 IDs
STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
この 関数のファミリーは変数のIDを与えるとそのNetCDF変数に関する情報を返します。 変数にに関する情報にはその名前・型・次元の数・変数の形を表す変数IDのリスト・変数に割り当てられている変数属性の数等です。
関数 NF_INQ_VAR はある変数のIDを与えるとNetCDF関数に関する情報をすべて返します。その他の関数はある変数に関する一つの情報を返します。
このほかの関数とは NF_INQ_VARNAME , NF_INQ_VARTYPE , NF_INQ_VARNDIMS , NF_INQ_VARDIMID , NF_INQ_VARNATTS 等です。
CHARACTER*(*) name, INTEGER xtype,
これは NF_INQ_VAR を使用してNetCDFファイル foo.nc の中の rh という変数に関しての情報を探す例です。
INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! 変数の形
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
関数 NF_PUT_VAR1_ type は指定された型 ( type )の単一のデータ値を開かれた状態でデータモードにあるNetCDFファイルの変数に書きこみます。入力はNetCDF ID・変数ID・書き加え又は変更するインデックス・データ値です。必要な場合には、その値は変数の外部データタイプに変換されます。
書きこまれるデータ値のインデックス。インデックスは1に相対的なものであり、例えば2次元の変数の最初のデータ値のインデックスは(1,1)になります。 インデックスの要素は変数の次元に対応しなければなりません。よって、変数が記録変数であれば、最後のインデックスは記録数に対応します。 |
|
書きこまれるデータ値。データ値は呼び出し関数に対応した型でなければなりません。文字(CHARACTER)データ値を数値変数に書き込んだり、数値データを文字変数書きこむことは出来ません。数値データがNetCDF変数型と異なる場合には型(type)変換が行われます。 詳細についてはSee タイプ変換を参照してください。 |
この 例では NF_PUT_VAR1_DOUBLE を使用して既存のNetCDFファイル foo.nc の変数 rh の (4,3,2) 要素を0.5にします。簡潔にするためにこの例では変数 rh の次元が lon , lat , an time であることを既知とします。よって、書きこむ変数 rh の値は4番目の lon 値・3番目の lat 値・2番目の time 値に対応します。
関数 NF_PUT_VAR_ type のファミリーは開かれたNetCDFファイルのNetCDF変数にすべての値を書きこみます。これはスカラー変数に値を書き込んだり多次元変数の値が一度にすべて書き込める場合に使用できるもっとも単純なインターフェースです。書きこまれる値は、 FORTRAN インターフェースにおいて最も早く変化するNetCDF変数が最初 の次元であるという仮定の元にNetCDF変数と関連付けられます。必要に応じて、値は外部デー型に変換されます。
書きこまれるデータ値の塊。データは呼び出した関数に対応する型でなくてはならない。文字(CHARACTER) データを数値変数に、又は数値データを文字変数に入れることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。(詳細についてはSee タイプ変換を参照。)最初の次元が最も早く変化する順番で(通常のFORTRAN変換と同様に)、データは指定された変数に書き込まれます。 |
関数 NF_PUT_VAR_ type ファミリーに属する関数は、エラーが発生していない場合には NF_NOERR の値を返します。その他の場合には、返されたステータスがエラーが発生したことを示します。エラーの原因としては:
この 例では NF_PUT_VAR_DOUBLE を使用して既存のNetCDFファイル foo.nc の変数 rh の値全てに20.5を加えるか0.5に変更するかします。簡潔にするためにこの例では変数 rh の次元は lon , lat , と time であり、 lon 値は10個, lat 値は5個, そして time 値が3個である事は既知とします。
PARAMETER (TIMES=3, LATS=5, LONS=10) ! 次元長
DOUBLE RHVALS(LONS, LATS, TIMES)
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
RHVALS(ILON, ILAT, ITIME) = 0.5
関数 NF_PUT_VARA_ type は開かれたNetCDFファイルのNetCDF変数のに値を書き込みます。書き込むNetCDF変数の部分は変数の部分配列の隅と縁の長さを与えることによって指定されます。 書き込まれる値はNetCDF変数の 最初 の次元がFORTRAN インターフェースにおいて最も早く変化するという仮定の元にNetCDF変数に関連付けられます。NetCDFファイルはデータモードになっていなければなりません。
最初にデータ値が書きこまれる変数内のインデックスを指定する整数のベクトル。インデックスは1に相対的なので、変数の最初のデータ値のインデックスは (1, 1, ..., 1) となります。 START の長さは指定された変数の次元数と同じでなければなりません。 START の要素は変数の次元と順番に対応していなければなりません。従って、 記録変数の場合には、最後のインデックスがデータ値を書き込む開始記録番号となります。 |
|
書き込まれるデータ値の塊の各次元の縁の長さを指定する整数のベクトル。単一のデータ値を書き込む場合には、 COUNT を (1, 1, ..., 1) と指定します。 COUNT の長さは指定された変数ベクトルの次元数と同じです。 COUNT の要素は変数の次元に対応します。 従って、記録変数の場合には、 COUNT の最後の要素が書き込む記録数の総計に対応します。 |
|
書き込まれるデータ値の塊。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数に、又は数値データを文字変数に入れることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細はSee タイプ変換にあります。 ). |
関数 NF_PUT_VARA_ type はエラーが発生していない場合には NF_NOERR 値を返します。それ以外の場合には、返されたステータスがエラーの発生を示します。エラーの原因としては::
この 例では NF_PUT_VARA_DOUBLE を使用して既存のNetCDFファイル foo.nc 中の変数 rh の値に30.5を加えるか0.5に変更するかします。簡潔にするために、この例では、変数 rh の次元が lon , lat , と time であり、 lon 値は10個、 lat 値は5個、そして time 値は3個あることが既知とします。
PARAMETER (TIMES=3, LATS=5, LONS=10) ! 次元長
INTEGER START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! 最初の値から始める
DATA COUNT /LONS, LATS, TIMES/
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
RHVALS(ILON, ILAT, ITIME) = 0.5
STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
関数 NF_PUT_VARS_ type のファミリーに属するものは各々部分サンプルされた(ストライドされた)配列断面を開かれたNetCDFファイルの変数に書き込みます。部分サンプルされた配列断面は隅、カウントのベクトル、そして ストライドベクトルを与えることによって指定します。NetCDFファイルはデータモードになっていなければなりません。
最初にデータ値が書きこまれる変数内のインデックスを指定する整数のベクトル。インデックスは1に相対的なので、変数の最初のデータ値のインデックスは (1, 1, ..., 1) となります。 START の要素は変数の次元と順番に対応していなければなりません。従って、 記録変数の場合には、最後のインデックスがデータ値を書き込む開始記録番号となります。 |
|
各次元に沿って選ばれたインデックスの数を指定する指定する整数のベクトル。単一のデータ値を書き込む場合には、 COUNT を (1, 1, ..., 1) と指定します。 COUNT の要素は変数の次元に順番に対応します。 従って、記録変数の場合には、 COUNT の最後の要素が書き込む記録数の総計に対応します。 |
|
NetCDF変数の各次元に対してのサンプリング間隔を指定する整数のベクトル。 ストライドベクトルの要素はNetCDF変数の次元に順番に対応します。(STRIDE(1) はNetCDF変数の次元の中で最も早く変化する時限のサンプリング間隔を与えます。)サンプリング間隔は型独立の要素の単位 で示されています。(値が1の場合には対応する次元に沿って隣接するNetCDF変数をアクセスし、値が2の場合には対応する次元の1つおきの値にアクセスします。 |
|
書き込まれるデータ値の塊。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数に、又は数値データを文字変数に入れることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細についてはSee タイプ変換を参照してください。 |
この例は NF_PUT_VARS_REAL を使用して、内部アレイから、 rh と言う名のNetCDF変数を一つおきに書き込んでいく例です。変数 rh はFORTRAN宣言文 REAL RH(6,4) において定義されています。(次元の大きさに注目してください。)
PARAMETER (NDIM=2) ! NetCDF変数のランク
INTEGER START(NDIM) ! NetCDF 変数のスタート地点
INTEGER COUNT(NDIM) ! 内部配列のサイズ
INTEGER STRIDE(NDIM) ! NetCDF変数の部分サンプル間隔
REAL RH(3,2) ! NetCDF変数の部分サンプルのサイズを記録
DATA START /1, 1/ ! 最初の NetCDF変数から開始
DATA COUNT /3, 2/ ! 内部配列のサイズ: 全体(部分サンプル)
DATA STRIDE /2, 2/ ! NetCDF要素に一つおきにアクセス
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
関数 NF_PUT_VARM_ type の一族はマップされた配列断面の値を開かれたNetCDFファイルの変数に書き込んでいきます。マップされた配列断面は隅の位置・カウントのベクトル・ ストライドベクトル・ インデックスマッピングベクトルを与えることによって指定されます。 インデックスマッピングベクトルとは整数のベクトルで、NetCDF変数の次元と内部データ配列のメモリ内構造間のマッピングを指定するベクトルです。データ配列に関する次元の順番や長さに関する仮定は一切なされません。 NetCDFファイルはデータモードになっていなければなりません。
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
最初にデータ値が書きこまれる変数内のインデックスを指定する整数のベクトル。インデックスは1に相対的なので、変数の最初のデータ値のインデックスは (1, 1, ..., 1) となります。 START の要素は変数の次元と順番に対応していなければなりません。従って、 記録変数の場合には、最後のインデックスがデータ値を書き込む開始記録番号となります。 |
|
各次元に沿って選ばれたインデックスの数を指定する指定する整数のベクトル。単一のデータ値を書き込む場合には、 COUNT を (1, 1, ..., 1) と指定します。 COUNT の要素は変数の次元に順番に対応します。 従って、記録変数の場合には、 COUNT の最後の要素が書き込む記録数の総計に対応します。 |
|
NetCDF変数の各次元に対してのサンプリング間隔を指定する整数のベクトル。 ストライドベクトルの要素はNetCDF変数の次元に順番に対応します。(STRIDE(1) はNetCDF変数の次元の中で最も早く変化する時限のサンプリング間隔を与えます。)サンプリング間隔は型独立の要素の単位 で示されています。(値が1の場合には対応する次元に沿って隣接するNetCDF変数をアクセスし、値が2の場合には対応する次元の1つおきの値にアクセスします。 |
|
NetCDF変数と内部データ配列のメモリ内構造間のマッピングを指定する整数ベクトル。インデックスマッピングベクトルの要素はNetCDF変数の次元と順番に対応します。(IMAP(1)はNetCDF変数の次元の内、最も遅く変化する次元に対応する内部配列の要素間の距離を与えます。)要素間の距離は要素の単位で示されます。(メモリ内で隣接している位置にある内部要素間の距離は1であり、NetCDF 2の場合のように要素のバイト長ではありません。) |
|
書き込まれるデータ値。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数に、又は数値データを文字変数に入れることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細についてはSee タイプ変換を参照してください。) |
エラーが発生していない場合には関数 NF_PUT_VARM_ type は NF_NOERR の値を返します。それ以外の場合には、返されたステータスがエラーが発生したことを示します。エラーの原因としては:
以下の IMAP ベクトルは2x3x4 NetCDF変数と同じ形の内部配列を簡潔な方法でマップします。
DATA IMAP /1, 2, 6/ ! NetCDF次元 要素間距離
! ---------------- ----------------------
上記の例で IMAP ベクトルと併せて NF_PUT_VARM_REAL 使用すると、単に NF_PUT_VAR_REAL を使用した場合と同じ結果が得られます。
この例では NF_PUT_VARM_REAL を使用して、転置された内部配列から、NetCDF変数 rh を書きます。 変数 rh は FORTRAN êÈåæï? REAL RH(4,6) で定義されています。(次元の大きさに注意してください。)
PARAMETER (NDIM=2) ! NetCDF変数のランク
INTEGER START(NDIM) ! NetCDF変数のスタート地点
INTEGER COUNT(NDIM) ! 内部配列のサイズ
INTEGER STRIDE(NDIM) ! NetCDF変数の部分サンプル間隔
INTEGER IMAP(NDIM) ! 内部配列の要素間距離
REAL RH(6,4) ! NetCDF変数次元の置き換えに注意
DATA START /1, 1/ ! 最初のNetCDF変数の要素から開始
DATA COUNT /4, 6/ ! NetCDF変数全体; 順番は
! NetCDF変数に対応している -- 内部配列のではない
DATA STRIDE /1, 1/ ! NetCDF要素を全てサンプルする
DATA IMAP /6, 1/ ! 置換しなければ /1, 4/
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
この例では NF_PUT_VARM_REAL を使用して転置された内部配列から同じNetCDF変数からなる部分サンプル配列を、NetCDF変数を一つおきのポイントに書き込むことによって作成します。
PARAMETER (NDIM=2) ! NetCDF変数のランク
INTEGER NCID ! NetCDFデータセットのID
INTEGER START(NDIM) ! NetCDF変数のスタート地点
INTEGER COUNT(NDIM) ! 内部配列のサイズ
INTEGER STRIDE(NDIM) ! NetCDF変数の部分サンプル間隔
INTEGER IMAP(NDIM) ! 内部配列の要素間距離i
REAL RH(3,2) ! (部分サンプルされた)次元の置換に注意
DATA START /1, 1/ ! 最初のNetCDF変数の値から開始
DATA COUNT /2, 3/ ! (部分サンプルされた)次元の順番はNetCDF変数に対応
DATA STRIDE /2, 2/ ! NetCDF要素を一つおきにサンプル
DATA IMAP /3, 1/ ! 置換しなければ`1, 2'
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
関数 NF_GET_VAR1_ type は開かれたデータモードにあるNetCDFファイルの変数から単一のデータ値を取得します。入力は NetCDF ID・変数ID・取得する値を指定する多次元のインデックス・データ値が読み込まれる位置のアドレスです。 この値は必要に応じて変数の外部データタイプから変換されます。
読み込まれるデータ値のインデックス。インデックスは1に相対的であるので、2次元変数の最初のデータ値のインデックスは (1,1) になります。 index の要素は変数の次元に対応していなければなりません。よって、記録変数の場合には、最後のインデックスが記録番号になります。 |
|
データ値が読み込まれる位置。数値変数から文字CHARACTERデータを取得したり、文字変数から数値データを取得することは出来ません。数値データの場合には、データ型がNetCDF変数型と異なれば、タイプ変換が行なわれます。詳細については See タイプ変換を参照のこと。 |
エラーが発生していない場合には関数 NF_GET_VAR1_ type は NF_NOERR の値を返します。それ以外の場合には、返されたステータスがエラーが発生したことを示します。エラーの原因としては:
この例では NF_GET_VAR1_DOUBLE を使用して、既存のNetCDFファイル foo.nc から変数 rh の (4,3,2) 要素を取得します。 簡潔にするために、この例では rh の次元が lon , lat , 及び time であることを既知とし、よって、取得したいのは rh の4番目の lon 値、 3番目の lat 値、そして 2番目の time 値ということになります。
関数 NF_GET_VAR_ type の一族は開かれたNetCDFファイルの変数の値を全て読みます。これは、スカラー変数や多次元変数の値を全て一度で読むためには最も簡単なインターフェースです。 変数は隣接する位置に 最初の 次元が最も早く変化するように 次々と書き込まれていきます。NetCDFファイルはデータモードになければなりません。
読み込まれるデータ値の塊。。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数から、又は数値データを文字変数カラ読み取ることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細についてはSee タイプ変換を参照のこと。 |
この例では NF_GET_VAR_DOUBLE を使用して既存のNetCDF ファイル foo.nc の変数 rh の値を全て読み取ります。簡潔のためにこの例では、変数 rh の次元は lon , lat , 及び time であり、 lon 値が10個、, lat 値が5個、そして, time 値が3個あることを既知とします。.
PARAMETER (TIMES=3, LATS=5, LONS=10) ! 次元長
DOUBLE RHVALS(LONS, LATS, TIMES)
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
関数 NF_GET_VARA_ type の一族は開かれたNetCDFファイルの変数から値の配列を読み取ります。 配列は隅の位置と各辺の長さを表わすベクトルを与えて指定します。値は 最初の 次元が最も早く変化するように、次々と読み込まれます。
INTEGER START(*), INTEGER COUNT(*),
There are six FORTRAN functions for reading an array of values from a NetCDF variable.
最初にデータ値が読み取られる変数内のインデックスを指定する整数のベクトル。インデックスは1に相対的なので、変数の最初のデータ値のインデックスは (1, 1, ..., 1) となります。 START の長さは指定された変数の次元と一致していなければなりません。 START の要素は変数の次元と順番に対応していなければなりません。従って、 記録変数の場合には、最後のインデックスがデータ値を読み込む開始記録番号となります 。 |
|
読み込まれるデータの塊の各次元に沿った辺の長さを指定する整数のベクトル。単一のデータ値を読み込む場合には、 COUNT を (1, 1, ..., 1) と指定します。 COUNT の長さは指定された変数の次元の数と一致します。 COUNT の要素は変数の次元に順番に対応します。 従って、記録変数の場合には、 COUNT の最後の要素が書き込む記録数の総計に対応します。 |
|
読み込まれるデータ値の塊。。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数から、又は数値データを文字変数から読み取ることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細についてはSee タイプ変換を参照のこと。 |
エラーが発生していなければ、関数 NF_GET_VARA_ type は NF_NOERR の値を返します。それ以外の場合は、返されたステータスがエラーが発生したことを示します。エラーの原因としては:
この例では NF_GET_VARA_DOUBLE を使用して、既存の NetCDF ファイル foo.nc の変数 rh の値を全て読み取ります。簡潔のためにこの例では、変数 rh の次元が lon , lat , と time であり、 lon 値は10個、 lat 値は5個、そして time 値が3個あることを既知とします。
PARAMETER (TIMES=3, LATS=5, LONS=10) ! 次元長
INTEGER START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! 最初の値から開始
DATA COUNT /LONS, LATS, TIMES/ ! 全ての値を取得
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
関数 NF_GET_VARS_ type の一族は開かれたNetCDFファイルから部分サンプルされた (ストライドした) NetCDF変数の配列断面 の値を読みます。部分サンプルされた配列断面は隅・縁の長さを示すベクトル・ ストライドベクトルを与えることによって指定されます。値はNetCDF変数の中で最後の次元が最も早く変化する用に読まれます。NetCDFファイルはデータモードに無くてはなりません。
最初にデータ値が読み取られる変数内のインデックスを指定する整数のベクトル。インデックスは1に相対的なので、変数の最初のデータ値のインデックスは (1, 1, ..., 1) となります。 START の要素は変数の次元と順番に対応していなければなりません。従って、 記録変数の場合には、最後のインデックスがデータ値を読み込む開始記録番号となります 。 |
|
各次元に沿って幾つのインデックスが選定されるかを指定するサイズ_t の整数ベクトル。 例えば単一の値を読み取る場合には、 count を (1, 1, ... , 1) と指定すればよい。 count の要素は変数の次元に順番に対応する。よって、記録変数の場合には count の最初の要素が読み取る記録数の総計に対応する。 |
|
各次元で選定されたインデックスの間隔を示す整数ベクトル、もしくはゼロの値。ベクトルの要素は変数の次元に順番に対応する。値が1の場合には対応するNetCDF 変数の隣接した値にアクセスする。 値が2の場合には対応するNetCDF変数の値を一つおきにアクセスする。 引数 0 は (1, 1, ..., 1) として扱われる。 |
|
読み込まれるデータ値の塊。。データの型は呼び出された関数に適当な型でなければなりません。 文字(CHARACTER) データを数値変数から、又は数値データを文字変数から読み取ることは出来ません。数値データについては、データ型がNetCDF変数型と異なる場合にはタイプ変換が行われます。 (詳細についてはSee タイプ変換を参照のこと。) |
この例では関数 NF_GET_VARS_DOUBLE を使用してNetCDFファイル foo.nc の変数 rh の各次元から一つおきに値を読み取ります。値はパラメータが2つ存在する配列と同じ次元ストライドを割り当てられています。 簡潔のためこの例では、 rh の次元が lon , lat , と time であり、 lon 値は10個、 f lat 値は5個、そして time 値は3個存在することが既知のこととします。
PARAMETER (TIMES=3, LATS=5, LONS=10) ! 次元長
INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
DOUBLE DATA(LONS, LATS, TIMES)
DATA START /1, 1, 1/ ! 最初の値から開始
DATA COUNT /LONS, LATS, TIMES/
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
関数 NF_GET_VARM_ type の一族は開かれたNetCDFファイルのNetCDF変数からマップされた配列断面を読みます。 マップされた配列断面は隅・縁の長さ・ ストライドベクトル・インデックスマッピングベクトル を与えることによって指定されます。 インデックスマッピングベクトルとはNetCDF変数と内部データ配列のメモリ内構造との間のマッピングを指定する整数ベクトルです。データ配列に関しては順番や長さなどについていかなる仮定もされません。
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
INTEGER START(*), INTEGER COUNT(*),
次の IMAP ベクトルは 2x3x4のNetCDF変数と同じ形の内部配列を自明な形でマップします。
DATA IMAP /1, 2, 6/ ! NetCDF次元 要素間距離
! ---------------- ----------------------
上記の IMAP ベクトルと NF_GET_VARM_REAL とを使用た場合と、単に NF_GET_VAR_REALを使用した場合とでは同じ結果が得られます。
この例では NF_GET_VARM_REAL を使用してFORTRAN 宣言文 REAL RH(4,6) (次元のサイズと順番に注目)で表わされたNetCDF変数 rh を移項します。
PARAMETER (NDIM=2) ! NetCDF変数のランク
INTEGER START(NDIM) ! NetCDF 変数スタート地点
INTEGER COUNT(NDIM) ! 内部配列のサイズ
INTEGER STRIDE(NDIM) ! NetCDF変数の部分サンプル間隔
INTEGER IMAP(NDIM) ! 内部配列の要素間距離
REAL RH(6,4) ! NetCDF変数の次元が置換されている点に注意
DATA START /1, 1/ ! 最初のNetCDF変数要素から開始
DATA COUNT /4, 6/ ! NetCDF変数全体; 順番はNetCDF変数に対応
DATA STRIDE /1, 1/ ! NetCDF要素を全てサンプル
DATA IMAP /6, 1/ ! 置換していなければ /1, 4/
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
関数 NF_GET_VARM_REAL を使用したこの別の例では、NetCDF変数の点を一つ置きにアクセスして同じNetCDF変数を移項すると同時に部分サンプルします。
PARAMETER (NDIM=2) ! NetCDF変数のランク
INTEGER START(NDIM) ! NetCDF変数のスタート地点
INTEGER COUNT(NDIM) ! 内部配列のサイズ
INTEGER STRIDE(NDIM) ! NetCDF変数の部分サンプル間隔
INTEGER IMAP(NDIM) ! 内部配列の要素間距離
REAL RH(3,2) ! (部分サンプルされた)次元の置換に注意
DATA START /1, 1/ ! 最初のNetCDF変数の値から開始
DATA COUNT /2, 3/ ! (部分サンプルされた)次元の順番はNetCDF変数に
DATA STRIDE /2, 2/ ! NetCDF要素を一つおきにサンプル
DATA IMAP /3, 1/ ! 置換していなければ `1, 2'
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
文字 列 は 基本的なNetCDF外部データ型ではありません。なぜならば、FORTRANでは可変長の文字列の抽象化をサポートしていないからです。( FORTRANの LEN 関数は文字列の動的な長さではなく、静的な長さを返します。) その結果、NetCDFインターフェースでは文字列は単一のオブジェクトとして読み書きすることが出来ません。文字列は文字の配列として扱わなければならないのです。それ故、NetCDFファイルの変数データとして文字列を読み書きするためには配列アクセスをしなければなりません。さらに、NetCDFインターフェースでは可変長の文字列は慣習による場合を除いてはサポートされていません。例えば、零バイトを文字列を終了するものとして扱うことは可能ですが、NetCDF変数に読み書きされる文字列の長さを明示しなければなりません。
文字列を属性値として扱えば使用しやすくなる。それは文字列がアクセスする際に一つの単位として扱われるからである。しかしながら、文字列の属性値の値はやはり固有の長さを持つ文字の配列であり、その長さは属性が定義されるときに指定される必要がある。
文字列値を持つ変数をを定義する際には, 文字列位置次元 character-position dimension を最も早く変化する次元として使用しなければならない。 ( FORTRAN の変数において最初の次元 f)文字列次元の長さは文字列変数に格納されるあらゆる文字列の最大長である。 最大長の列を格納するスペースは、使用するか否かにかかわらず、文字列変数のディスク表現の中に割り当てられる。 仮に、2個以上の変数の最大長が同じである場合には、変数の形を定義するにあたって同じ文字位置次元を使用しても良い。
文字列変数に文字列の値を書き込むには、全変数アクセスもしくは配列アクセスを使用します。後者を使用する場合には隅と縁の長さのベクトルの両方を指定する必要があります。文字位置次元の隅はFORTRAN においてone です。 もし書き込む列の長さが n と仮定すると、縁の長さのベクトルは文字位置次元に n を指定し、他の次元には全て1を指定します: (n, 1, 1, ..., 1) 。
FORTRANにおいてはスペースを節約するために、固定長の文字列はNetCDFファイルにsひゅ雨量文字無しで書き込むことが出来ます。可変長の文字列は Cの終了文字零バイトを加える 慣習に従い、後にC 又は FORTRANのプログラムで目的となる文字列の長さが識別できるようにしておかなければなりません。
文字列を読み書きするためのFORTRAN インターフェースは 文字列値と数値をアクセスとをするのには異なる関数を必要とします。 それは、標準のFORTRANでは文字列値と数値の両方に同じ正式なパラメータを使用することが禁じられているからです。さらに、 NF_PUT_VARA_TEXT と NF_GET_VARA_TEXTにおいては、 指定された、値として扱われた文字列の長さを指定する別の引数が必要です。文字列の実際の長さは、対応する文字位置次元の縁の長さベクトルの値として指定されます。
この例では、文字列を扱う記録変数 tx を定義し、 NF_PUT_VARA_TEXT を使用して文字列値を3番目の記録に書き込みます。ここでは、文字列変数とデータは既に見せ威厳記録次元 time を持つ既存のNetCDFファイル foo.nc に書き加えられると仮定します。
PARAMETER (TXLEN = 15) ! 文字列の例の長さ
INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF(NCID) ! 定義モードに入る
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
TXDIMS(1) = CHID ! 最初の文字の位置の次元
STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_ENDDEF(NCID) ! 定義モードを抜ける
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! write txval into tx NetCDF variable in record 3
STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL, 40)
開かれたNetCDFファイルに書き込まれたことのない値を読み取ろうとしたならば何が起こるでしょう?必ずエラーが発生し、エラーメッセージもしくはエラーステータスが返されると思われがちです。確かに、開かれていないNetCDFファイルからデータを読もうとした場合、指定されたNetCDFファイルにおいてその変数IDが有効でない場合、または指定されたインデックスが指定された変数の次元長で定義された領域外にある場合にはエラーが発生します。しかし、それ以外の場合には、書き込まれていない値を読もうとすると、初めにNetCDF変数が書かれたときに未定義の全ての値を埋めるための使用される特別なフィル値 fill value が返されます。
このフィル値を無視してNetCDF外部データ型の全領域を使うことも出来ますが、その場合には読む前に全てのデータ値を書き込んだことを確認しなければなりません。もし、読む前に全てのデータ値を書き込むことが確かであれば、書き込む前に NF_SET_FILL を呼び出すことによってフィル値を持っている変数が前もって埋められてしまわないと確信できます。 これによってNetCDFの書き込み効率が著しく向上することもあります。
変数属性 _FillValue はある変数のフィル値を指定するためにも使えます。各型ごとに デフォルトのフィル値があり、インクルードファイル netcdf.inc の中で定義されています。 netcdf.inc : NF_FILL_CHAR , NF_FILL_INT1 (same as NF_FILL_BYTE ), NF_FILL_INT2 (same as NF_FILL_SHORT ), NF_FILL_INT , NF_FILL_REAL (same as NF_FILL_FLOAT ), and NF_FILL_DOUBLE .
NetCDFバイトと文字型は異なるデフォルトのフィル値を持ちます。文字用のデフォルトのフィル値は 零バイトであり、可変長のC 文字列の終わりを判別するのに役立ちます。バイト変数にフィル値が必要なときには、適した _FillValue 属性を定義することをお勧めします。それは、 ncdump 等の一般的なユーティリティではバイト変数に関してはデフォルトのフィル値を仮定しないからです。
フィル値のタイプ変換は他の値のタイプ変換と全く同様です。ある値をその値を表現できない別の型に変換しようとするとレンジエラーが生じます。 そのようなエラーは、大きな型(例えばダブル型)から小さな型(例えばフロート型)へと読み書きする際に、大きい方の方のフィル値が小さい方の型では表現できない時に生じることがあります。
関数 NF_RENAME_VAR は開かれたNetCDFファイルのNetCDF変数の名前を変更します。もし新しい名前が以前の名前よりも長い場合にはNetCDFファイルは定義モードになっていなければなりません。既に存在している変数名にすることは出来ません。
この例では NF_RENAME_VAR を使用して、既存のNetCDFファイル foo.nc 内の変数 rh の名前を rel_hum に変更します。
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF (NCID) ! 定義モードに入る
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NetCDF変数の性質である単位・特別な値・有効な値の最大値と最小値・スケーリングファクター・オフセット等を指定するために、各変数には属性が伴う。 NetCDFファイルの属性はファイル生成時に、NetCDFファイルが定義モードにある時に定義される。NetCDFファイルを再度定義モードにすることによって、属性を追加することが可能です。NetCDF属性はその属性が割り当てられているNetCDF変数・名前・ 型・長さ・一つ又は複数の値のシーケンスを持っています。属性はその変数IDと名前で示されます。 属性名が不明の場合には、その変数IDと数を使い、関数 NF_INQ_ATTNAME で名前を知ることができます。
変数に伴う属性は、通常、変数が生成された直後に、NetCDFファイルがまだ定義モードにあるうちに定義されます。データ型・長さ・属性値はファイルがデータモードにあっても変更できます。ただしこれは、元々属性が定義された際に使用した以上のスペースが必要とされない場合に限ります。
どの変数とも関連していない属性を定義することも可能です。これらは グローバル属性 と呼ばれ、関数 NF_GLOBAL を変数の擬似IDとして使います。グローバル属性は通常NetCDFファイル全体に関係し、NetCDFファイルのタイトルや作業記録を付ける為に使われます。
アンダースコア(ヤ _ ユ) で始まる名前はNetCDFライブラリ専用です。 NetCDFファイルを処理する一般的なアプリケーションは標準的な 属性の慣習を仮定しており、 よほどの理由が無い限り、これらの慣習に従いましょう。以下に、有用であることが証明済みの、推奨される標準的な属性の名前や意味が表記されています。 これらの中には数値データを仮定しているものもあり(例えば、 units , valid_range , scale_factor )、文字データ用には使うべきではない属性が幾つかあることに注意されたい。
変数データの単位を指定留守文字列。Unidata は自由に取得できるルーチンライブラリを開発・提供しています。これを使えば文字列と単位指定のバイナリ形式との間の変換やバイナリ形式で様々な有用な操作を行なうことができる。 このライブラリは幾つかのNetCDFアプリケーションで使われている。推奨される単位構文を使用すれば、整合単位で表現されたデータを、算術演算用に一般的な単位に自動的に変換することが可能です。 詳しくは、See 単位。 |
|
長い記述的な名前。プロットのラベルなどに使える。変数に long_name 属性が割り当てられていなければ、変数名をデフォルトとして使用しましょう。 |
|
この変数の有効値の最小値と最大値を示す2つの数値のベクトル。 valid_min と valid_max 属性の値を指定することと 等価である。これらの変数はどれも 有効範囲 を定義している。 valid_min 又は valid_max のどちらか一方でも定義されていたら、 valid_range 属性を定義してはいけません。 一般的なアプリケーションは 有効範囲 外の値は 欠損として扱うのが望ましい。 各 valid_range 、 valid_min そして valid_max 属性の型はその変数の型と一致してしてなければなりません。(ただし、 byte データ型は除く:これらは意図する範囲を符号付整数型によって指定できる。) valid_min 、 valid_max 、 valid_range のいずれも定義されていない場合には、一般的なアプリケーションは有効範囲を次の方法で定義するのが良い。 データがバイト型で _FillValue が明示されていない場合、有効範囲は全ての可能な値を含む。 それ以外の場合には、有効範囲から(明示された、もしくはデフォルト指定の) _FillValue を下記の要領で除外する。 _FillValue が正の値の場合には、それが有効な最大値とし、正で無い場合には有効な最小値として定義する。整数型については、 _FillValue とこの有効な最大値又は最小値の差を1とする。浮動小数点型については、丸め誤差を念頭に置き、この差を表現可能な最小値(最も下位のビットで1)の2倍に設定する。 |
|
ある変数についてこの属性が与えられていれば、データにアクセスするアプリケーションによってデータが読み込まれた後に、データはこの約数と掛け合わせる。 |
|
ある変数についてこの属性が与えられている場合、データはそれにアクセスするアプリケーションによって読み込まれた後にこの数が加えられる。もし、 scale_factor と add_offset の両方の属性が与えられている場合には、データはまずスケールされ、その後でオフセットが加えられる。 scale_factor と add_offset を同時に使うことによって、簡単なデータ圧縮を行なうことができ、これによって、 NetCDFファイル内に低解像度の浮動小数点データを小さい整数として格納することが出来ます。スケールされたデータが書き込まれた場合、アプリケーションはます、オフセットを差し引き、その後にスケールファクターで割ればよい。 scale_factor と add_offset が 圧縮に使われる際には、関連する変数(圧縮データを格納している) の型は通常、byte型かshort型である。一方で、解凍されたデータは float 型や double型となるようにされている。 scale_factor と add_offset 属性は両方とも解凍されたデータの持つ型(float 型や double型)でなければなりません。 |
|
_FillValue 属性は、変数に割り当てられているディスクスペースを予め埋めるために使用される フィル値 を指定します。このように予めスペースを埋める動作は、 NF_SET_FILL .を使って ノーフィル モード が設定されていない限り行なわれます。詳細については、 See 書き込みのフィルモードを設定する: NF_SET_FILL 書き込まれた事のない値を読み取った時に フィル値 が返されます。 _FillValue が定義されていれば、それはスカラーで、変数と同じ型を取ります。デフォルトの フィル値 が変数の型に合致していれば、変数について _FillValue 属性をいちいち定義する必要はありません。しかし、byte型データにデフォルトのフィル値を使用することはお勧めできません。この変数の属性の値を変更する際には、その値がそれ以降の書き込みに対してのみ有効である点に注意してください。それ以前にフィル値が書き込まれたデータは変更されません。 一般のアプリケーションはしばしば、未定義の値又は 欠損値を表現するために値を書き込む必要があります。 フィル値 はこれに対して適切な値を提供します。それは、フィル値が通常、有効範囲がいの値を取るために、一般のアプリケーションでは欠損値として扱われるからです。 フィル値 を有効範囲内に設定することは出来ますが、薦められません。 より詳しい説明については、See フィル値を参照のこと。 |
|
この属性はライブラリや慣習に従った一般のアプリケーションによって特別扱いされるわけではありませんが、しばしば有用な文書であるので特定のアプリケーションで使われることがあります。 missing_value 属性はスカラーでもベクトルでも良く、欠損データを示す値を含んでいます。 一般のアプリケーションが、これらの値を欠損値として取り扱えるように、これらの値は 有効範囲 外にあるべきです。 |
|
使用価値の無くなった属性です。元はbyte値が 符号付か符号無しのどちらで扱われるべきか指定するために作られました。現在ではこの目的の為に、 valid_min と valid_max の属性を使用できます。例えば、byte変数に非負の値のみ格納したい場合には、 valid_min = 0 と valid_max = 255 とを使えます。NetCDFライブラリはこの属性を無視します。 |
|
この変数の値をプリントするFORTRANアプリケーションが使用するべきフォーマットを与える文字配列です。例えば、ある変数が有効数字3桁の精度しかないことが明らかであれば、 FORTRAN_format 属性を "(G10.3)" と定義するのが適当でしょう。 |
|
検査履歴のためにグローバル属性。これは文字配列で、ファイルを修正したプログラムの各呼び出しに対して一行割り振られています。 性質の良い 一般の NetCDF アプリケーションは、アクセスする際に日付・時刻・ユーザー名・プログラム名・コマンドの引数を含む一行を追加します。 |
|
存在する場合には、ヤ Conventions ユ はグローバル属性であり、データセットが従う慣習の名前を示す文字配列です。ある分野に固有な慣習の集合体を記述した文書の貯蔵場所のディレクトリの相対的なディレクトリ名として解釈される文字列の形式を取ります。これによって、慣習の階層構造が可能になり、慣習の記述や例を、それを定義した機関やグループが保持する場所を与えている。慣習のディレクトリ名は現在ではホストマシン ftp.unidata.ucar.edu .上の pub/netcdf/Conventions/ ディレクトリから相対的に解釈される。代わりに、慣習を記述した文書が維持されている WWW サイトを指定するために、完全なURL指定子を使用しても良い。 |
|
例えば、NUWGというグループが、ある 分野に固有のデータ構造の次元名・変数名・必要な属性・NetCDF表現に対する慣習について合意したとする。NUWGは合意された慣習を記述した文書をConventionsディレクトリのサブディレクトリ NUWG/ に 保管しておくことができる。これらの慣習に従ったデータセットは "NUWG" という値を持ったグローバル Conventions ëÆê´Ç?ä<Ç?DZÇ?Ç?Ç»ÇÈÅB |
|
後にこのグループが、NUWGデータの特定の部分集合(例えば時系列等)について新たに慣習を追加することに決めた場合、その追加される慣習の記述は NUWG/Time_series/ サブディレクトリに保管されます。これらの追加された慣習に従ったデータセットは "NUWG/Time_series" の値を持つグローバル Conventions 属性を使い、NUWG慣習と追加されたNUWG時系列慣習にも従ったことを示します。 |
関数 NF_PUT_ATT_ type は、開かれたNetCDFファイルの変数属性又はグローバル属性を追加・変更する。新規の属性、又は属性を格納するために必要なスペースが前より大きくなる場合には、NetCDFファイルは 定義モードでなくてはなりません。
どんな型の属性も生成可能ですが、ほとんどの用途にはテキストやダブル属性で十分です。
属性名。アルファベット文字で始り、アンダースコア (ヤ _ ユ)を含む零又は英数字が続きます。大文字小文字は区別されます。属性名の慣習は幾つかのNetCDFの一般的なアプリケーション で仮定されています。例えば、 units はNetCDF変数に単位を与える文字列属性の名前です。慣習的な属性名の一覧が前出のNetCDFインターフェースについての章にあります。 |
|
前もって定義されたNetCDF外部データ型の集合の一つ。有効なNetCDF外部データ型は NF_BYTE 、 NF_CHAR 、 NF_SHORT 、 NF_INT 、 NF_FLOAT 、 NF_DOUBLE 等です。どんな型の属性も生成できますが、ほとんどの用途には NF_CHAR と NF_DOUBLE の属性で十分です。 |
|
LEN 属性値の配列。データは呼び出し関数に妥当な型でなければなりません。数値属性にCHARACTERデータを書き込んだり、テキスト属性に数値データを書き込むことは出来ません。 数値データの場合、データの型が属性の型と異なればタイプ変換が行なわれます。(詳細についてはSee タイプ変換を参照してください。) |
エラーが発生していなければ、 NF_PUT_ATT_ type は NF_NOERR の値を返します。 それ以外の場合には、返された状態がエラーを示します。エラーの原因として次のようなものが考えられます。
この例では、 NF_PUT_ATT_DOUBLE を使って、既存の foo.nc という名前のNetCDFファイルにおいて、 rh という名前のNetCDF変数に対して valid_range という属性、及び、 title という名前のグローバル属性を追加している。
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF (NCID) ! 定義モードに入る
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
この関数の一族はNetCDF属性に関する 情報を返します。これらの関数は一つを除いて全て変数IDと属性名を必要とします。例外は NF_INQ_ATTNAME 関数です。属性に関する情報には型・長さ・名前・番号などが含まれます。属性値を取得する方法については NF_GET_ATT の節を参照してください。
関数 NF_INQ_ATTNAME は変数IDと番号を与えると、属性の名前を返します。この関数は、他の全ての属性関数において属性は番号ではなく名前によってアクセスされるために、変数に関連した属性の名前を全て必要とする 一般的なアプリケーションにおいて役に立ちます。属性の番号は名前よりも 揮発性があり、同じ変数の属性が 削除された時に変わることがあります。このため、 属性の番号は 属性 IDとは呼ばれません。
関数 NF_INQ_ATT は属性の型と長さを返します。他の関数は各々、属性の情報を一つだけ返します。
この例では、 NF_INQ_ATTLEN を使って、既存の foo.nc という名前のNetCDFファイルにおいて、 rh という名前の変数の属性 valid_range の長さと、 title という名前のグローバル属性について問い合わせる。
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
NF_GET_ATT_ type の一族の関数は、変数IDと名前を与えるとNetCDF属性の値を 返す。
返された 属性値。属性値のベクトルの要素は全て返されるので、十分なスペースを確保する必要があります。 どれだけのスペースを確保しておかなければならないか分からない時には、 まず NF_INQ_ATTLEN を呼び出して属性の 長さを調べましょう。数値変数から文字データを読み取ったり、テキスト変数から数値データを読み取ることは出来ません。 数値データの場合には、データの型がNetCDF変数の型と異なればタイプ変換は行なわれます。(詳細については、See タイプ変換を参照してください。) |
エラーが発生していなければ、 NF_GET_ATT_ type は NF_NOERR の値を返します。 それ以外の場合には、返された状態がエラーを示します。エラーの原因として次のようなものが考えられます。
この例は NF_GET_ATT_DOUBLE を使って、既存の foo.nc .という名前のNetCDFファイルの rh というNetCDF変数の属性 valid_range の値と、 title という名前のグローバル属性とについて調べる。この例では、幾つの値が返されるか不明であると仮定する。そこで、格納するスペースが十分であることを確認するために、 まず始めに属性の長さについて問い合わせる。
PARAMETER (MVRLEN=3) ! "有効範囲"の値の最大数
PARAMETER (MTLEN=80) ! "title" 属性に最大長
DOUBLE PRECISION VRVAL(MVRLEN) ! vr 属性値
CHARACTER*80 TITLE ! title 属性値
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
WRITE (*,*) 'valid_range attribute too big!'
STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
WRITE (*,*) 'title attribute too big!'
STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
関数 NF_COPY_ATT は開かれたNetCDFファイルから他のファイルへ属性をコピーします。また同じNetCDF内で、ある変数の属性を別の変数にコピーするときにも使えます。
この例では、 NF_COPY_ATT を使って 、既存の foo.nc というNetCDFファイルにおける変数 rh から変数属性 units をコピーして、他の既存の bar.nc というNetCDFファイルの変数 avgrh に貼り付ける。変数 avgrh は既に存在するが、属性 units はまだ持っていないと仮定する。
INTEGER NCID1, NCID2 ! NetCDF ID
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF (NCID2) ! 定義モードに入る
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! 変数属性を "rh" からコピーして "avgrh"に貼り付ける
STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
関数 NF_RENAME_ATT は属性の名前を変更します。新しい名前が元の名前より長い場合には、NetCDFファイルは定義モードになっている必要があります。同じ変数の他の属性名と同じ名前になってしまうような属性名の変更はできない。
この例では、 NF_RENAME_ATT を使って、既存のというNetCDFファイルにおける変数 rh の変数属性の名前を units から Units Ç...ï?çXÇ?ÇÈÅB
関数 NF_DEL_ATT は開かれたNetCDFファイルから NetCDF 属性を削除します。NetCDF ファイルは定義モードになっている必要があります。
この例では、 NF_DEL_ATT を使って、既存の foo.nc というNetCDFファイルから変数 rh の変数属性Units を削除します。
この例では、 NF_DEL_ATT を使って、既存の foo.nc というNetCDFファイルから変数 rh の変数属性Unitsを削除します。
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_REDEF (NCID) ! 定義モードに入る
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
この章では、NetCDFの性能について理解するのに必要なNetCDFのファイル 構造 を の詳細を説明します。
NetCDFは配列指向のデータアクセスの為のデータ抽象化であり、その抽象化をサポートするインターフェースの具体的な実装を与えるソフトウェアライブラリです。この実装によって配列を表現するための機種独立型のフォーマットを提供されます。 NetCDFファイルフォーマットはインターフェースの表面からは見えないが、現行の実装と関連するファイル構造を幾らか理解していれば、どのNetCDF操作が他よりコストがかかるか明らかになるでしょう。
NetCFフォーマットの詳細に関しては、 See ファイルフォーマット仕様を参照してください。フォーマットの知識が無くても、NetCDFデータの読み書きや 効率に関する問題点のほとんどを理解することは可能です。文書化されたインターフェースのみを使い、フォーマットに関しては何の仮定もしていないプログラムは、将来NetCDF フォーマットが変更されても機能しつづけます。それは、 フォーマットの変更は全て文書化されたインターフェースの下層で行なわれ、かつ、以前のバージョンのNetCDFファイルフォーマットはサポートされるからです。
NetCDFファイルは2つの部分からなる一つのファイルとして格納されています。
ヘッダー部分とデータ部分は両方とも機種独立型で表現されています。この形式は、配列や非バイトデータの効率的な格納をサポートするために拡張されたXDR(eXternal Data Representation)と非常に似ています。
ファイルの先頭にあるヘッダー部分はファイルに含まれる次元・変数・属性についての名前・型・その他の性質に関する情報を含みます。各変数の情報には固定際すデータについては変数データの先頭の オフセットや、記録中の他の変数の相対オフセット 等がある。ヘッダーは、又、次元長や各変数の複数次元のインデックスを適切なオフセットにマップするのに必要な情報を含みます。
このヘッダーの使用可能なスペースに余分はありません。NetCDFファイル中の次元・変数・属性(属性値を全て含む)に必要な最低限の大きさしかありません。 これによって、NetCDFファイルは コンパクトであり、データを自己記述的にするための従属的なデータを格納するのにほとんど オーバーヘッドを必要としないという利点があります。この構造の欠点は、NetCDFファイルのヘッダーを増大(又は可能性としては低いが縮小)させるようなどの操作も、データをコピーすることによって移動させるということです。例えば、新しい次元や変数を追加したりする場合がそうです。 このコストは NF_REDEF への呼び出しの後に NF_ENDDEF が呼び出されたときに掛かります。データを書き込む前に必要な時限・変数・属性を生成して、ファイルのヘッダー部分により多くのスペースを必要とする生成後のNetCDF要素の追加や名前の変更を避けることによって、その後のヘッダー部分の変更に伴うコストを回避することが出来ます。
ヘッダーのサイズが変更されると、ファイル中のデータは移動され、ファイル内におけるデータ値の位置が変更されます。再定義中に他のプログラムがこのファイルを読み取っている場合には、そのファイルを間違っている可能性のある旧インデックスを使用して参照することとなります。NetCDFファイルが再定義を超えて共有されるためには、再定義中の読み取りアクセスを防ぎ、次回のアクセスの前に読み取る側に NF_SYNC を呼び出させるような、NetCDFライブラリ外の機構が必要となります。
ヘッダーに続く固定サイズデータ部分は無制限次元を有さない変数の変数データを全て含みます。各変数のデータはこのファイル部分に連続的に格納されています。無制限次元が無い場合には、これがNetCDFファイルの末尾の部分となります。
固定サイズデータ部分に続く記録データ部分は、各々記録データの情報を全て含む固定サイズ記録の変数番号からなります。各変数の記録データは各記録中に連続的に格納されています。
各データ部分における変数データの順番は変数が定義された順番と同じで、NetCDF変数IDの昇順になります。 これを知っていると、現行ではデータを連続的に読み書きすることが最適なデータアクセス法なので、場合によってはデータアクセス性能を向上させることが出来ます。
XDRはデータ記述とコード化の為の標準であり、外部データ表現の為のライブラリでもあります。これによって、プログラマーは機種独立な手法によってデータ構造をコード化することができます。NetCDFはヘッダー部分とデータ部分で情報を表現するために拡張されたXDR形式を採用しています。この拡張 XDR はライブラリが実装されているどのマシン上でも読み取れるポータブルなデータを書くのに使用されています。
データ表現の為に規範的な外部データ表現を使用するコストはデータの型によって異なり、又、その外部データ型がマシンの本来の形式であるかにもよります。
ある機種のデータ型では、外部データ形式からデータを変換したり、外部形式へと変換するのに膨大な時間を費やすかもしれません。最悪の場合は、IEEE浮動小数点が本来の表現法では無いマシン上で 浮動小数点データの大きな配列を読み書きすることでしょう。
I/O 階層の実装は、NetCDFファイルのポータブルデータを読み書きするのための C standard I/O (stdio)ライブラリの実装とよく似ています。よって、標準的なI/Oライブラリを理解すれば、 同時にデータをアクセスする複数の処理や、I/Oバッファの使われ方、NetCDFファイルの開け閉めのコストに関する様々な疑問が解決されます。特に、NetCDFファイルに対して一つの書き込み処理が行なわれている間に 、別の複数の読み取り処理が進行することも可能です。データの読み書きには、stdio fread() や fwrite() への呼び出しより下位のものは使用していない。 NF_SYNC 呼び出しは全て C standard I/O ライブラリの fflush 呼び出しと類似しており、他の処理が読み取れるように未記入の バッファデータを書き込んでいきます。 NF_SYNC は又、ヘッダーの変更(例えば、属性値への変更)を最新のものにします。 NF_SHARE は the _IONBF フラグを setvbuf 状態にした、バッファされていないstdio streamを設定することと同義です。
stdio ライブラリの場合と同様に、ファイルの異なる部分への"探索"が生じると、 flushが実行される。従って、書き込み操作の順番はI/O性能に著しい影響を与えます。 各記録中にデータが書き込まれたのと同じ順番でデータを読み取ることによってバッファflushを最小限に留めることができます。
NetCDFデータアクセスは、同一のファイルに同時に複数の書き込み処理が行なえるようにはなっていません。
I/O階層を別のプラットフォーム固有のI/O階層に置き換えることにより、NetCDFの実装をあるプラットフォームに合わせて調整できます。これによってNetCDFと標準的なI/Oとの相似点、つまりデータ共有の性質・バッファ動作・I/O操作のコストなどが換わる可能性があります。
配布されたNetCDF実装は ポータブルであることを目標にしています。場合によっては、よりよいI/O性能のために実装を最適化するような プラットフォーム固有のポート の方が実用的でしょう。
前出のように、I/O効率を向上させるためにI/O階層を置き換えることは可能です。 Cray Y-MPと類似した、Cray コンピューターのOSであるUNICOSに関しては、これは既になされています。
更に、 NETCDF_FFIOSPEC 環境変数を正しく設定することにより、ユーザーは一層、I/O効率を上げることが出来ます。この変数は、UNICOS OS下で実行中に、NetCF I/Oの Flexible File I/OTバッファを指定します。(この変数は他のOSでは無視されます。)適切な設定を選択すればNetCDF I/Oの効率を飛躍的に向上させることが出来ます―デフォルトのFORTRAN bianry I/Oを超えることもも可能です。下記のような指定が可能です。
CRIの FFIO ライブラリによってサポートされているオプション/構成はこの機構を通じて利用できます。FFIOの機能を最大限利用するためにCRIのI/O最適化ガイドを参照することをお勧めします。 この機構は、又、CRIのEIE I/Oライブラリとも互換性があります。
Tuning the NETCDF_FFIOSPEC 変数をプログラムのI/Oパターンに調整すれば、性能が飛躍的に向上します。何百倍というスピードが得られた例もあります。
配列を圧かうっぷりけー書んがNetCDFインターフェースを使用する主な理由の一つに、好意レベルのNetCDFユーティリティとNetCDFデータの一般的なアプリケーションを利用することがある。現在では、NetCDFソフトウェア配布版の一部として2つのNetCDFユーティリティが用意されている。
より汎用の NetCDFユーティリティが2つ FAN (File Array Notation)パッケージのに含まれている。
FANに関しての詳細は see http://www.unidata.ucar.edu/packages/netcdf/fan_utils.html .
他のNetCDFユーティリティにはユーザーからの寄与があり、NetCDFデータをアクセスする様々な視覚化や解析パッケージが存在する。 無償・有償両方ののNetCDFデータをアクセスし扱えるソフトウェアの最新情報については、NetCDF Softwareリスト が次のサイトにあります。 http://www.unidata.ucar.edu/packages/netcdf/software.html .
この章には ncgen と ncdump ユーティリティの説明があります。これら2つのツールはバイナリのNetCDFファイルとNetCDFファイルのテキスト表記間の変換を行ないます。 ncdump の出力と ncgen の入力はCDL(network Common data form Description Language)として知られるささやかな言語によってテキスト表記されたものです。
以下の CDLの例では、幾つかの名前付き次元( lat , lon , time )、変数( z , t , p , rh , lat , lon , time )、変数属性( units , _FillValue , valid_range )とデータからなるNetCDFファイルを記述しています。
lat = 10, lon = 5, time = unlimited;
int lat(lat), lon(lon), time(time);
float z(time,lat,lon), t(time,lat,lon);
lat = 0, 10, 20, 30, 40, 50, 60, 70, 80, 90;
lon = -140, -118, -96, -84, -52;
全ての CDL 宣言文はセミコロンで終わります。スペース・タブ・改行は可読性の為に自由に使えます。コメントは ダブルスラッシュ //に続き、どの行にも配置可能です。
CDL 記述は次元・変数・属性の3つのオプション部分から構成されます。変数部は変数宣言文や属性割り当てを含むことが出来ます。
次元はCDL記述で記述される多次元変数の形を定義するために使われます。次元には名前と長さがあります。CDL記述の次元の内、一つの次元まで無制限長を持つことが出来、それはこの次元を使う変数が任意の長さになり得る(ファイル中の記録番号のように)ことを意味します。
変数は同じ型の値の多次元配列を表現します。変数は名前・データ型・そして次元のリストによって記述された形を持ちます。各変数はデータ値のほかに関連する属性(下記参照)も持ちえます。 名前・データ型・変数の形はCDL記述中の変数部分における宣言文によって指定されます。変数は次元と同じ名前を持つことが出来ます。慣習として、そのような変数は 次元の座標値を名前に含んでいます。
属性は変数やNetCDFファイル全体についての情報を含んでいます。属性は単位・特別な値・有効な値の最大値と最小値・圧縮パラメーターのような特性を指定するのに使われます。 属性情報は単一の値や値の配列によって表現されます。例えば、 units は celsius 等の文字列によって表現される属性です。属性には関連する変数・名前・データ型・長さがあります。 データ用の変数とは対照的に、属性は従属的なデータ(データに関するデータ)のためにあります。
CDLでは、属性は変数と属性名とをコロン( `:' ) で区切ったもので指定される。変数名を省略し、属性名をコロン( `:' ) ではじめることによって、NetCDFファイル全体に グローバル属性を割り当てることもできます。 CDLの属性のデータ型はそれに割り当てられている値の型で決まります。属性の長さはデータ値の数又はそれに割り当てられた文字列中の文字の数になります。文字でない属性に複数の値を割り当てる場合には、値をコンマ( `,' )で区切れば可能です。属性に割り当てられた値は全て同じ型でなくてはいけません。
変数・属性・次元に対するCDL 名には、英数字とヤ _ ユ 及びヤ - ユの任意の組み合わせが許可されているが、 ` _ 'で始まる名前はライブラリ専用です。CDL名では大文字小文字は区別されます。NetCDFライブラリはNetCDF名に制約を加えていないので、有効なCDL名ではない名前を使って変数を定義することも可能ですが薦められません。 基本的なデータ型の名前はCDLでは予約語であるので、変数・次元・属性の名前は型の名前は取れません。
CDL記述のオプションのデータ部分では、 NetCDF 変数が 初期化されます。 初期化のお構文は単純です。
variable = value_1, value_2, ノ ;
コンマで区切られた定数のリストは、空白・タブ・改行によって分けることができます。多次元配列では、最後の次元が最も早く変わります。 よって、行列には行順ではなく列順が使われます。 変数を満たすのに不十分な値が与えられた場合には、フィル値によって埋められます。定数の型は変数に宣言された型と一致していなくても良く、例えば、整数を浮動小数点数に強制的に変換するといった操作が行なわれます。意味のあるタイプ変換は全てサポートされています。
byte データ型が追加されていることと、 unsigned 修飾子が無いことを除けば、 CDL はCと同様の基本的データ型をサポートしています。宣言文では、型名の指定は大文字でも小文字でも 構いません。
byte 型は8ビットデータ用である点が char 型と異なります。そして、零バイトは文字データにおけるような特別な意味を持ちません。 ncgen ユーティリティは byte 宣言文を、出力C コードにおいては char 宣言文に、そして出力FORTRANコードにおいては BYTE , INTEGER*1 もしくは同類のプラットフォーム固有の宣言文に変換します。
short 型は -32768 と 32767の間の値を保持します。 ncgen ユーティリティは short 宣言文を、出力Cコードにおいては short 宣言文に、そして出力FORTRANコードにおいては INTEGER*2 宣言文に変換します。
int 型は -2147483648 と2147483647の間の値を保持します。 ncgen ユーティリティは int 宣言文を、出力Cコードにおいては int 宣言文に 、そして出力FORTRANコードにおいては int 宣言文に変換します。 CDL 宣言文では integer と long は int の同義語として認識されています。
float 型は -3.4+38 と 3.4+38との間の値を保持でき、外部表現には32ビットのIEEE規格化された単精度浮動小数点数が使われます。 ncgen ユーティリティは float 宣言文を、出力Cコードにおいてはfloat 宣言文に、そして出力FORTRANコードにおいては REAL 宣言文に変換します。 CDL 宣言文では realは floatの同義語として認識Ç≥ÇÍÇfÇ¢Ç<Ç?ÅB
double 型は-1.7+308 と1.7+308の間の値を保持し、外部表現には64ビットのIEEE規格化された倍精度浮動小数点数が使われます。 ncgen ユーティリティは double 宣言文を、出力Cコードにおいては double 宣言文に、そして出力 FORTRANコードにおいては DOUBLE PRECISION 宣言文に変換します。
属性はCDL記述の variables 節において、 属性の型と 長さを決める定数のリストを与えることによって、 初期化されます。(NetCDFライブラリへのC と FORTRAN の手続きインターフェースにおいては、属性の型と名前は定義されるときに明記されなければならない。) CDLは、異なるNetCDF型で区別がつくように、定数値の構文を記述している。 CDL定数の構文はC構文と似ているが、 ints と doubles から区別するために、 型の接尾子が shorts と floatsに添えてある。
バイト定数は単一の文字、又は、シングルクオートで囲んだ複数文字のエスケープ列で表現されます。例えば、
'\33' // ASCII エスケープ文字(8進数で33)
'\376' // 8進数で377 = 10進数で-127 (又は 254)
文字定数はダブルクオートで囲まれています。 文字配列はダブルクオートで囲んだ文字列として表現できます。複数の文字列は単一の文字配列にと連結されます。 これによって、長い文字配列を複数の行に 書くことが出来ます。複数の可変長の文字列値をサポートするためには、ヤ , ユのような慣習的な区切り文字を使用することができるが、このような文字列区切りのための慣習はNetCDFライブラリ層の上のソフトウェアに実装されていなければなりません。通常のC文字列のエスケープ慣習はそのまま使用できます。 例えば、
"Two\nlines\n" // 2つの改行文字を埋め込んだ 10文字の文字列
"a bell:\007" // ASCIIベルを含む文字列
short 定数の形式は `s' 又は `S' を付加した整定数である。 short 定数が `0' で始まれば、8進数であると解釈されます。 `0x' で始まれば、16進数の整数として解釈されます。例えば、
int 定数の形式は普通の整定数です。 int 定数が `0' で始まれば、それは8進数であると解釈されます。 `0x' で始まれば、16進数として解釈されます。有効な int 定数の例を幾つか挙げます。
1234567890L // 現在では使用されない。古いlong接尾子を使用している。
float 型は有効数字7桁の精度を持つデータを表現するのに適しています。 float 定数の形式は C 浮動小数点定数に `f' 又は `F' を付加したものと同じです。 CDL float では整数と区別するために小数点が必要です。次に挙げる例は全て、妥当な float 定数です。
ncgen ツールは NetCDFファイル、又は、NetCDFファイルを生成する C 又は FORTRAN のプログラムを生成します。 ncgen ,を呼び出す際にオプションを指定しなければ、 そのプログラムは単に CDL 入力の構文をチェックし、CDL構文に合致しないものがあればエラーメッセージを出すだけです。
ncdump ツールは標準の出力にNetCDFファイルのCDLテキスト表現を出力する。 オプションによって、入力されたデータの変数データの一部又は全てを除外することも出来ます。 ncdump からの出力は ncgen への入力として使用できるようになっています。よって、 ncdump と ncgen はバイナリ表現とテキスト表現との間でデータ表現を変換するための正逆変換として使用できます。
ncdump は又、NetCDFファイル用の簡単なブラウザとしても使えます。これによって、NetCDFファイル内の、次元名と次元長・変数名と型と形・属性名と値・オプションとして全てまたは選択された変数の値などを見ることが出来ます。
ncdump はNetCDFの変数データの各型について使用されているデフォルトのフォーマットを定義しています。しかし、これはNetCDF変数に C_format 属性が定義されていればこちらのほうが優先されます。この場合には、 ncdump は C_format 属性を使ってその変数の値をフォーマットします。 例えば、浮動小数点数であるNetCDF変数 Z の有効数字が3桁しかないことが分かっている場合などに、この変数属性を使うと良いでしょう。
ncdump は `_' を使って _FillValue 属性(これはまだ書かれていないデータを表現するためにあります)と等しい値を持つデータ値を表現します。もし、変数が If a variable _FillValue 属性を有していなければ、変数がバイト方で無い限り変数型のデフォルトフィル値が使用されます。
この省では、NetCDFに関して最も良くある質問に対して答えます。より包括的で最新のFAQ文書は http://www.unidata.ucar.edu/packages/netcdf/faq.htmlにあります。
NetCDF (network Common Data Form) は配列指向のデータアクセスのためにインターフェースで、そのインターフェースの実装を与えるC・FORTRAN・C++・Perl用のソフトウェアライブラリを集めたものです。NetCDFソフトウェアはColorado州のBoulderにあるUnidata Program Centerの Glenn Davis、 Russ Rew、 と Steve Emmerson によって開発され、他のNetCDFユーザからの貢献にによって増強されました。NetCDFライブラリは配列を表現するための機種独立のフォーマットを定義しています。インターフェース・ライブラリ・フォーマットが合わさって配列指向データの生成、アクセス、そして共有をサポートしています。
ソースの 配布は下記のディレクトリからanonymous FTP経由で手に入れることができる。
はい、できます。このFAQ文書の最新版、NetCDF Userユs Guideのハイパーテキスト版、及びその他の情報は以下にあります。
3版は同じフォーマットを保持していますが、CとFortran用に、自動タイプ変換に加えタイプ変換の安全性を向上させた新しいインターフェースを導入しています。詳細については 下記を参照してください。
http://www.unidata.ucar.edu/packages/netcdf/release-notes.html .
はい、あります。メーリングリストに関する情報や参加/脱会方法についての質問は majordomo@unidata.ucar.edu まで、subject無しで本文に次のように記入したメールを送ってください。
NetCDFメーリングリストは15カ国に渡り500程の登録者がいます。(このうちの幾つかはより多くのアドレスへのエイリアスです。)幾つかのグループはNetCDFを配列指向データを表現する標準的な方法として採用しています。それらには、大気科学、水理学、海洋学、環境モデリング、地球物理学、クロマトグラフィ、質量分析学、ニューロイメージング等が含まれます。
異なるデータ構成の性能の含みを明らかにするのに十分なレベルのNetCDFデータの物理的構造の説明に関しては、See NetCDFファイルの構造と性能を参照してください。又、ファイルフォーマットについての詳しい仕様については、 See ファイルフォーマット仕様を参照してください。
NetCDFデータをアクセスするプログラムは、全てのアクセスを文書化されたインターフェースを通じて行なうべきであり、NetCDFデータの物理的フォーマットに依存するべきではない。そのようにしておけば、将来フォーマットが変更されてもプログラムを変更する必要が生じない。なぜならば、そのような変更は旧バージョン・新バージョン両方のフォーマットをサポートするようにライブラリも変更されるからである。
現行のUnidataからのNetCDF配布版に含まれるユーティリティは、NetCDFファイルを可読なASCII 形式に変換する ncdump 、可読なASCII形式のファイルからバイナリのNetCDFファイルに変換し直す又はそのNetCDFファイルを生成するC もしくはFORTRANのプログラムに戻す ncgen である。
幾つかの商用又は無償の解析及びデータ視覚化 パッケージがNetCDFデータアクセスに適応している。これらのパッケージやNetCDFデータを処理し表示するために使える他のソフトウェアについては下記を参照のこと。
Scientific Data Format Information FAQ, が http://fits.cv.nrao.edu/traffic/scidataformats/faq.html にあり、 CDFやHDFを含む配列指向データ用の他のアクセスインターフェースやフォーマットを分かりやすく紹介しています。
バグを発見したら、その情報をを support@unidata.ucar.edu に送ってください。これは netcdfgroup メーリングリスト全体で扱うには適さない質問や議論をするためのアドレスでもあります。
C++はCインターフェースによって提供される機能を全て持っている。(ただし、 nc_put_varm_ type と nc_get_varm_ type のマップされた配列アクセスを除く。)C++インターフェースを使用すると( http://www.unidata.ucar.edu/packages/netcdf/cxxdoc_toc.html )NetCDF 要素のIDは不必要になり、属性を生成際に型の指定が不要になる。さらに、次元を扱う際に、より直接的に扱うことができる。しかし、C++インターフェースはCに比べて未成熟で、C程広く使われていない。さらに、C++インターフェースの文章はあまり広範ではなく、NetCDFデータモデルとCインターフェースに慣れていることを前提としている。
Unidata Program Centerが開発した単位ライブラリによって フォーマットされたバイナリ形式の単位間の変換を行い、また、バイナリ形式で単位型代数演算を行なうことが可能です。単位ライブラリそのものは自己完結型であり、NetCDFライブラリとの間には依存性はありません。それでもこのライブラリは一般的なNetCDFプログラムを書く際には非常に有用ですので、手に入れることをお勧めします。この ライブラリと関連文書は http://www.unidata.ucar.edu/packages/udunits/ から取得できます。
以下に Unidata 単位ライブラリの関数 utScan() によって解釈できる単位文字列の例を挙げてあります。
milliseconds since 1992-12-31 12:34:0.1 -7:00
単位とは単位の任意の整数冪に任意の定数を掛けたものとして指定されます。割り算はスラッシュ `/' 、掛け算は空白・ピリオド `.' ・ハイフン `-' ,のいずれか、冪算は 整数の添え字又は冪乗演算子 `^' ・ `**' で表わされます。括弧を用いて表記をグループ化したり明瞭化することもできます。 最後の例のタイムススタンプは特殊なケースとして扱われます。
任意のガリレオ変換( すなわち、 y = ax + b )も許されています。特に、温度の変換は正しく扱われています。次の指定:
原点シフトの演算が掛け算より優先されることに注意してください。演算の優先順位は(下位から上位に向かって)除算、乗算、原点移動、冪算になります。
関数utScan() は全てのSI接頭語(つまり、 "mega" 、 "milli" )やそれらの短縮形(つまり、 "M" 、 "m" )に対応できます。
関数 utPrint() は常にtsんに指定を一意にコード化します。誤った解釈を防ぐために、このコード化のスタイルをデフォルトとして使用することをお勧めします。一般的には、単位は基本単位・因数・ 冪指数によってコード化されます。基本単位は空白によって区切られ、冪指数は対応する単位に直接付加されます。上記の例は次のようにコード化されます:
98636.5 kilogram meter-1 second-2
0.001 seconds since 1992-12-31 19:34:0.1000 UTC
(華氏単位が原点255.372 kelvinからの分数の偏差としてkelvin単位の分数としてコード化されていることに注意してください。さらに、最後の例では時刻がUTCに変換されていることにも注意してください。)
単位ライブラリのデータベースはフォーマットされたファイルで単位定義を含み、このパッケージを初期化するのに使われます。有効な単位名や記号等はまずここで探して下さい。
この単位ファイルのフォーマットに関しては内部に文書があり、ユーザーは必要に応じてファイルを 修正することが出来ます。特に、単位や定数(さらに既存の単位や定数の異なった綴り)は簡単に付け足していくことが出来ます。
関数utScan() は大文字小文字を区別します。これによって不都合が生じるようでしたら、単位ファイルに適切な項目を追加してください。
このappendixでは NetCDF ファイルフォーマット1版の仕様を述べます。このフォーマットは少なくともNetCDFライブラリ3.0版までは使用される予定です。
このフォーマットはまず最初に BNF 文法表記によって正式に表現されます。この文法では、オプションの要素は括弧( `[' と `]' )によって囲まれます。注釈は `//' の後に続きます。端末語でないものは小文字で、端末語は大文字で表記されます。0又はそれ以上の項目を並べる場合には `[entity ...]' と表記されます。
header := magic numrecs dim_array gatt_array var_array
magic := 'C' 'D' 'F' VERSION_BYTE
VERSION_BYTE := '\001' // ファイルフォーマットのバージョン番号
dim_array := ABSENT | NC_DIMENSION nelems [dim ...]
gatt_array := att_array // グローバル属性
att_array := ABSENT | NC_ATTRIBUTE nelems [attr ...]
var_array := ABSENT | NC_VARIABLE nelems [var ...]
ABSENT := ZERO ZERO // 配列が無いことを意味する( nelems == 0に同じ)
nelems := NON_NEG // 以下のシークエンスの要素数
dim_length := NON_NEG // 0であればこれは記録次元。
attr := name nc_type nelems [values]
nc_type := NC_BYTE | NC_CHAR | NC_SHORT | NC_INT | NC_FLOAT | NC_DOUBLE
var := name nelems [dimid ...] vatt_array nc_type vsize begin
// スカラーなら0 、ベクトルなら 1、マトリクスなら 2、等
vatt_array := att_array // 変数に特定の属性
dimid := NON_NEG // 変数形状のための次元 ID(dim_arrayへのインデックス)
vsize := NON_NEG // 変数サイズ。記録変数で無い場合には、
begin := NON_NEG // 変数のスタート位置。この変数のデータの
non_recs := [values ...] // 記録変数ではない最初の変数、2番目、...のデータ。
recs := [rec ...] // 最初の記録、2番目の記録、...
rec := [values ...] // 記録nに対する最初の記録変数、
values := [bytes] | [chars] | [shorts] | [ints] | [floats] | [doubles]
padding := <次の4バイト境界までの0, 1, 2, または 3 バイト>
CHAR := <8ビット ACSII/ISO でコード化されたcharacter>
SHORT := <16ビット符号付整数・ビッグエンディアン・ 2の補数表現>
INT := <32ビット符号付整数・ビッグエンディアン・ 2の補数表現>
FLOAT := <32ビット IEEE 単精度浮動小数点・ビッグエンディアン>
DOUBLE := <64ビット IEEE ニ倍精度浮動小数点・ビッグエンディアン>
NC_BYTE := 1 // データは8ビット符号付整数の配列
NC_CHAR := 2 // データは文字配列(テキスト等)
NC_SHORT := 3 // データは16ビット符号付整数の配列
NC_INT := 4 // データは32ビット符号付整数の配列
NC_FLOAT := 5 // データはIEEE 単精度浮動小数点の配列
指定されたデータ値の オフセット(ファイル内の位置)を計算するには、指定された変数型 nc_type に適切なデータ値の一つの外部サイズ(バイト単位)を external_sizeof とする。
NF_OPEN (or NF_ENDDEF)呼び出しは前もって var_arrayと示された 変数配列内をスキャンし、 recsize を計算するために"記録”変数の vsize の和を計算する。
変数の次元サイズの積を右から左にとっていき、記録変数の最も左の(記録)次元は飛ばし、各変数についての結果を product 配列に格納する。例えば:
この時点では、最も左にある積を次の4の倍数に丸めたものが変数サイズ、すなわち、上の文法においては vsize になる。例えば、上記の非記録変数では、 vsize フィールド値は 212 (210を次の4の倍数に丸めた値)となる。記録変数に対しては、 vsize の値はちょうど 72である。なぜならば、72は既に4の倍数であるからである。
求めるデータ値の座標の配列を coord とし、求める結果を offset とする。この時、 offset は単に、求める変数の最初のデータ値のファイルオフセット(その begin フィールド)に coord と productベクトル の内積を変数の各データのサイズ(バイト単位)を掛けたものを加えた値となる。最後に、もしその変数が記録変数であれば、 記録数 `coord[0]' と記録サイズ recsize との積が加算され、最終的な offset 値が導かれる。
上の文法によれば、 最も小さな有効なNetCDF fileで次元、変数、属性を持たない、従ってデータを持たないものを導くことができます。空の NetCDFファイルのCDL表現は次のようになります:
この 空のNetCDFファイルは32バイトの大きさで、 CDL表現から `ncgen -b empty.cdl' を使って空NetCDFファイルを生成して確認することが出来ます。この空ファイルはそれがNetCDF 1版のファイルであることを示す4バイトの”マジックナンバー”である `C' , `D' , `F' , `\001' で始まります。続いて、記録数・次元の空配列・グローバル属性の空配列・変数の空配列を表わす7つの32ビット0が後にきます。
ファイルの16バイトの各部分は4行で表示されています。最初の行はバイトを16進数表示し、 2行目はを文字表示しています。3行目は2バイトごとにグループ化して、それを符号付16ビット整数として表示しています。 4行目は(手作業で追加されたものであるが)バイトをNetCDF要素及び値として解釈したものを表示している。
C D F 001 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0
17220 17921 00000 00000 00000 00000 00000 00000
[magic number ] [ 0 records ] [ 0 dimensions (ABSENT) ]
0000 0000 0000 0000 0000 0000 0000 0000
\0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0 \0
00000 00000 00000 00000 00000 00000 00000 00000
C D F 001 \0 \0 \0 \0 \0 \0 \0 \n \0 \0 \0 001
17220 17921 00000 00000 00000 00010 00000 00001
[magic number ] [ 0 records ] [NC_DIMENSION ] [ 1 dimension ]
0000 0003 6469 6d00 0000 0005 0000 0000
\0 \0 \0 003 d i m \0 \0 \0 \0 005 \0 \0 \0 \0
00000 00003 25705 27904 00000 00005 00000 00000
[ 3 char name = "dim" ] [ size = 5 ] [ 0 global atts
0000 0000 0000 000b 0000 0001 0000 0002
\0 \0 \0 \0 \0 \0 \0 013 \0 \0 \0 001 \0 \0 \0 002
00000 00000 00000 00011 00000 00001 00000 00002
(ABSENT) ] [NC_VARIABLE ] [ 1 variable ] [ 2 char name =
7678 0000 0000 0001 0000 0000 0000 0000
v x \0 \0 \0 \0 \0 001 \0 \0 \0 \0 \0 \0 \0 \0
30328 00000 00000 00001 00000 00000 00000 00000
"vx" ] [1 dimension ] [ with ID 0 ] [ 0 attributes
0000 0000 0000 0003 0000 000c 0000 0050
\0 \0 \0 \0 \0 \0 \0 003 \0 \0 \0 \f \0 \0 \0 P
00000 00000 00000 00003 00000 00012 00000 00080
(ABSENT) ] [type NC_SHORT] [size 12 bytes] [offset: 80]
\0 003 \0 001 \0 004 \0 001 \0 005 200 001
00003 00001 00004 00001 00005 -32767
[ 3] [ 1] [ 4] [ 1] [ 5] [fill ]
入力引数は大文字で、出力引数は小文字で表記してあります。全ての引数のFORTRAN タイプは引数の名前によりアルファベット順にしてあり、関数の宣言の下にリストされています。
CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
INTEGER FUNCTION NF_REDEF (NCID)
INTEGER FUNCTION NF_ENDDEF (NCID)
INTEGER FUNCTION NF_SYNC (NCID)
INTEGER FUNCTION NF_ABORT (NCID)
INTEGER FUNCTION NF_CLOSE (NCID)
INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE 旗表現
CHARACTER(*) CURNAME ! 現行の名前(変更前)
DOUBLEPRECISION DVAL ! 単一のデータ値
DOUBLEPRECISION dval ! 出力単一のデータ値
DOUBLEPRECISION DVALS !データ値の配列
DOUBLEPRECISION dvals ! 出力データ値の配列
INTEGER FILLMODE ! フィルモード設定のためのNF_NOFILL 又は NF_FILL
INTEGER IMAP ! インデックスマッピングベクトル
INTEGER INDEX ! 変数配列の インデックスベクトル
INTEGER MODE ! 開かれたモードNF_WRITE 又は NF_NOWRITEの一つ
CHARACTER(*) NAME ! 次元、変数、又は属性名
CHARACTER(*) name ! 出力次元、変数、又は属性名
INTEGER NCERR ! NF_xxx 関数呼び出しによる出力エラー
INTEGER NCID ! 開かれたNetCDFファイルのNetCDF ID
INTEGER NCID_IN ! 開かれたソースのNetCDFファイルのNetCDF ID
INTEGER NCID_OUT ! 開かれたデスティネーションのNetCDFファイルのNetCDF ID
CHARACTER(*) NEWNAME ! 次元・変数・属性の新規名
INTEGER old_mode ! 以前のフィルモード、 NF_NOFILL 又は NF_FILL
CHARACTER(*) PATH ! NetCDFファイルの名前
INTEGER START ! 最初の値の変数配列インデックス
INTEGER unlimdimid ! 無制限次元の返されたID
NetCDF3版 ではNetCDFライブラリが完全に書き直されています。このバージョンは以前のより2倍は早くなっています。NetCDFファイルのフォーマットはそのままなので、3版で書かれたファイルは2版で読むことが出来、又、逆も可能です。
ライブラリの芯部は現在、 ANSI Cで書かれています。 このバージョンをコンパイルするには ANSI C コンパイラが必要です。 FORTRAN インターフェースは、NetCDF-2で使用されたのとは異なる技術を利用して C インターフェースの上の層にのせてあります。
ライブラリを書き直すことによって、進歩したCやFORTRANのインターフェースを利用する機会が得られ、かなりの恩恵がありました。
2版の FORTRAN インターフェースを使用しているプログラムを書き直す必要はありません。なぜならば、NetCDF-3ライブラリには急関数・グローバル・動作を全てサポートする 後方互換性インターフェースが含まれているからです。 この新しいインターフェースの恩恵がNetCDFのアプリケーション中でそれらを使用するきっかけになることを願います。NetCDF-2の呼び出しを一つ一つ対応するNetCDF-3の呼び出しに置き換えていくことで、旧アプリケーションを新しいインターフェースに徐々に変換していくことは可能です。
NetCDFの実行の変更は、ほとんど全てのプラットフォーム上での携帯性、保全性、及びパフォーマンスの向上に繋がりました。 I/Oとタイプ層を完全に切り離すことによりプラットフォーム固有の最適化が簡単になりました。 新しいライブラリは販売元が提供している XDR ライブラリを使用していないので、NetCDFを使用するプログラム同士をリンクすることが 簡易になり、ほとんどの場合においてデータアクセスのスピードが速くなっています。
まず最初にNetCDF-2インターフェースを使った FORTRAN コードの例です。
CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
PRINT *, 'Cannot get data, error code =', STATUS
NetCDF-3のライブラリは新しい命名の慣習に従っており、NetCDfプログラムをより読み易くしようと試みています。例えば、変数名を変更する関数の名前は以前の NCVREN ではなく NF_RENAME_VAR となります。
全てのNetCDF-3 FORTRAN 関数名は NF_ 接頭辞で始まります。関数名の2番目の部分は動詞のようなもので、 GET 、 PUT 、 INQ (問い合わせるのinquire)又は OPEN 等があります。名前の3番目の部分は一般的に動詞の目的語にあたります。例えば、次元、変数、属性を扱う関数では DIM 、 VAR 、及び ATT となります。様々な変数のI/O操作を 識別するためには、一文字の修飾子が VAR に付加されます。
新しいインターフェースにおいては、どのような数値タイプへ、又はからの自動変換も提供されているので、ユーザーは数値変数の外部データ型を知っている必要はありません。この特徴を使って、コードを外部データ型に依存しないようにして簡単にすることができます。 type punning の排除することによって、 以前のインターフェースでは起こりえた幾つかの種類のタイプエラーを防げるようになりました。変数の外部データ型を扱うに際にプログラムを変更する必要が無いために、新しいインターフェースはプログラムをより強固にすることが出来ます。
外部数値型からの変換が必要な場合はライブラリによって扱われます。この自動変換機能と外部データ表記の内部データ型からの分離はNetCDF4版においてより重要になります。4版では、自然に対応する内部データ型が存在しない圧縮データ(例えば11ビット値の配列) 用の新しい外部データ型が用意される予定です。
ある数値型から他の型に変換する操作は、ターゲットの型が変換された値を表現できない場合にエラーがを引き起こします。(NetCDF-2においては、そのようなオーバーフローはXDR階層でのみ起こり得ました。)例えば、 REAL は外部では NF_DOUBLE (IEEE浮動小数点数)として格納されているデータをもつことが出来ないかもしれません。値の配列をアクセスする際には、表現し得る範囲を超えた値が一つ又はそれ以上ある場合には、 NF_ERANGE エラーが返されますが、他の値は正しく変換されます。
タイプ変換において、単に精度のロスが生じただけではエラーが返されないことに注意してください。そのため、例えばINTEGERに 二倍精度の値を読み込んだ場合には、その二倍精度の値の大きさがプラットフォーム上の INTEGERsで表現できる範囲を超えない限りエラーは生じません。 同様に、仮数部分に整数のビットを全て収めることの出来ない REAL に大きな整数を読み込み、精度が失われてもエラーは生じません。このような精度のロスを防ぐためには、アクセスする変数の外部データ型を確認し、それと互換性のある内部データ型を使用しましょう。
新しいインターフェースはテキスト列を表現する文字配列と小さい整数を表わす8ビットバイトの配列とを区別します。このインターフェースはテキスト列のための CHARACTER and INT1、そして 1バイト整数の内部データ型をサポートします。
新しいインターフェースのエラーの取り扱い方はNetCDF-2の方法とは異なる。 NetCDF-2のインターフェースでは、エラーが検知された時のデフォルト動作はエラーメッセージを出力してexitすることであった。エラーの取り扱いをコントロールするには、 関数 NCPOPT を呼び出さなければならず、エラーの原因を究明する為に、 返されたエラー引数の 値をテストしなければならなかった。
新しいインターフェースにおいては、 関数が返す整数状態は成功/失敗のみではなく、エラーの原因をもしめす。 ライブラリは何かを出力したり、 exit を呼び出そうとすることはありません。(ただし、NetCDF-2互換の関数を使用している場合はこの限りではありません。)関数の返された状態を確認し、手動で行なわなければなりません。平行した(マルチプロセッサ)実行をきれいサポートするために、又、NetCDFが使用される環境についての仮定条件を減らすために、これらのグローバルは削除されました。 新しい動作は、独自のGUIインターフェースを持つアプリケーション中で、NetCDFを隠された階層として使用するのにより適したサポートを提供しているはずです。
NetCDF-2 インターフェースが NCLONG を使って32ビット整数に対応した外部データ型を同定していたのに対し、新しいインターフェースは NF_INT を使います。 NCLONG は後方互換性の為に、 NF_INT と同じ値を取るように定義されているが、 新しいコードでは使用されるべきでない。新しい64ビットプラットフォームが64ビット整数にlongを使用しているので、この名前の衝突によって引き起こされる混乱を少なくしたいのです。 未だに64ビット整数に対応するNetCDF外部データ型が存在しないことに注意してください。
2版のインターフェースの関数 NCTLEN に対応する関数は無い。内部データ型と外部データ型を分離することと、新しいタイプ変換インターフェースによって、 NCTLEN は不要になる。ユーザーは ネイティブの型でもって読み書きするので、 ネイティブ型に必要なスペースの知識 さえあれば、完璧にある値に割り当てるスペースを決定することができる。
以前のライブラリでは、 NetCDFオブジェクトの名前に使用された記号がCDLの制約に沿っているか判断する方法が無かった。 CDLを使用しているncdump と ncgen のユーティリティは、名前に関しては英数字とメ _ モ and メ - モ のみの使用をを許可している。 この制約は新しい次元・属性・変数を生成する際に、ライブラリによっても強制されることになった。制約の弱い名前を冠する既存の要素はまだ問題なく使える。
NetCDF-2に対応する関数が存在しない、新しい関数がNetCDF-3には2つある。 NF_INQ_LIBVERS と NF_STRERROR である。現行のNetCDFライブラリは NF_INQ_LIBVERS の文字列として返される。NetCDF関数の呼び出しによって返された状態に対応するエラーメッセージは関数NF_STRERRORによって記号列として返される。
新しい NF_SHARE フラグはアクセスのデフォルトバッファを防ぐために、 NF_OPEN 又は NF_CREATE 呼び出しで使用できる。 NF_SHARE を使用することによってNetCDFファイルに同時にアクセスすれば、ディスクのアップデートが同期であることを確認するために、アクセスが終了するたび毎に NF_SYNC を呼び出す必要が無い。従属的なデータ(例えば属性値)への変更にも注意しなければならない。 なぜならば、これらは NF_SHARE フラグを使用しても自動的に伝達されないからである。 このためには、まだ NF_SYNC 関数が必要である。
2版のインターフェースの問い合わせ関数は一つしかなく、 NCVINQ によって名前、型、変数の形を得ていた。同様に、 次元・属性・NetCDFファイルに関する情報を得る関数も一つしか無かった。 この情報の部分集合が得る場合には、不必要な情報を押さえる為にdummy 引数を与えなければならなかった。新しいインターフェースでは、新たな問い合わせ関数ができ、これらの項目を個別に返す。それによって引数の数え損ねによるエラーが起こりにくくなった。
以前の実装では NCVPT と NCVGT 呼び出し中で 0値のカウント要素が 指定されているとエラーが返された。 この制約がはずされたことによって、 NF_PUT_VAR と NF_GET_VAR の一族の関数が0 値のカウント要素を使って呼び出せることになった。これはデータがアクセスされないことを意味し、一見、無意味のように思われるが、0値のカウントを特殊なケースとして扱わなくて良いので、プログラムによっては単純になります。
以前の実装ではncvardef中の変数の形を指定するのに同じ次元を2回以上使用するとエラーが返されました。 自己相関マトリクスなど同じ次元を2度使用することに意味のある良い例があるので、この制約はNetCF-3実装では緩められた。
新しいインターフェースでは、 NF_PUT_VARM と NF_GET_VARM 族の関数に対する IMAP 引数の単位は 、望まれる内部データ型のデータ要素の数によって表わされ、NetCDF2版のマップされたアクセスインターフェースのようにバイトでは表わされない。
下記はNetCD-2の関数名と対応するNetCDF-3関数の対応表です。 NetCDF-2関数の引数のリストはNetCDF-2 Userユs Guideに載っています。
other software for scientific data 117
add_offset attribute 88
differences between C and C++ 117
differences between C and FORTRAN 117
applications, generic 18, 19, 29, 48, 86, 89, 92
add_offset 88
Conventions 89
_FillValue 88
FORTRAN_format 89
history 89
long_name 87
missing_value 89
scale_factor 87
signedness 89
title 89
units 19, 87, 119
valid_max 87
valid_min 87
valid_range 87
C code via ncgen , generating 110
byte data type 17, 107
char data type 17
long data type 17
real data type 17
char data type 21, 107
character-position dimension 82, 83
closing a dataset 29, 30, 40, 43, 44
generating via ncgen 110
commercial netCDF software 116
common netCDF call sequence 28
compatibility interface, backward 132
compiling netCDF-using code 33
computing file offsets of data 123
concurrent dataset access 42, 103, 114
byte 108
double 109
float 109
int 109
short 109
PARAMETER name 134
units syntax 119
Conventions attribute 89
floating-point values, cost of 102
between data types and data 54
access, other software for 117
correspondence between data types and 54
section, netCDF file fixed-size 101
and data, correspondence between 54
byte 21
CDL byte 17, 107
CDL char 17
CDL double 17, 109
CDL float 17, 109
CDL int 17
CDL long (deprecated) 17
CDL real 17
CDL short 17
char 21, 107
double 21, 108
float 21, 108
int 21, 108
NCLONG (deprecated) 135
NF_BYTE 16
NF_CHAR 16
NF_DOUBLE 16
NF_FLOAT 16
NF_INT 16
NF_INT1 16
NF_INT2 16
NF_REAL 16
NF_SHORT 16
short 21, 108
signed byte 22
unsigned byte 22
generating via ncgen 110
define mode 32, 43, 44, 48, 56
CDL long data type 17
NCLONG data type 135
dimension 15, 16, 18, 30, 31, 48
discipline-specific conventions 90
File I/O library, CRAY Flexible 104
_FillValue attribute 88
fixed-length character-strings 82
fixed-size data section, netCDF file 101
Flexible File I/O library, CRAY 104
and C interfaces, differences between 117
code via ncgen , generating 110
FORTRAN_format attribute 89
freely available netCDF software 116
frequently asked questions 114
dimension 30, 31, 48, 49, 50, 56
INCLUDE statement 33
compatability of interfaces 25
layering, FORTRAN interface 132
UDUNITS 119
linking with netCDF library 33
long CDL data type (deprecated) 17
long_name attribute 87
mapping vector, index 23, 25, 54, 67, 69, 78, 130
missing_value attribute 89
PARAMETER 134
correspondence, netCDF-2 function 136
dimension 16, 48, 49, 50, 51, 52
ncdump 111
ncgen 110
generating FORTRAN code via 110
NCLONG data type (deprecated) 135
NCTLEN elimination 135
function name correspondence 136
netCDF-3 interface vs. netCDF-2 132
NETCDF_FFIOSPEC 103
NETCDF_FFIOSPEC environment variable 103
netCDF-using code, compiling 33
NF_ABORT 44
NF_BYTE 55
NF_BYTE data type 16
NF_CHAR 55
NF_CHAR data type 16
NF_CLOBBER 37
NF_CLOSE 40
NF_COPY_ATT 96
NF_CREATE 36
NF_DEF_DIM 48
NF_DEF_VAR 55
NF_DEL_ATT 99
NF_DOUBLE 55
NF_DOUBLE data type 16
NF_ENDDEF 39
NF_FILL 45
NF_FILL_FLOAT 134
NF_FLOAT 55
NF_FLOAT data type 16
NF_GET_ATT_DOUBLE 94
NF_GET_ATT_INT 94
NF_GET_ATT_INT1 94
NF_GET_ATT_INT2 94
NF_GET_ATT_REAL 94
NF_GET_ATT_TEXT 94
NF_GET_VAR1_DOUBLE 71
NF_GET_VAR1_DOUBLE example 72
NF_GET_VAR1_INT 71
NF_GET_VAR1_INT1 71
NF_GET_VAR1_INT2 71
NF_GET_VAR1_REAL 71
NF_GET_VAR1_TEXT 71
NF_GET_VARA_DOUBLE 74
NF_GET_VARA_INT 74
NF_GET_VARA_INT1 74
NF_GET_VARA_INT2 74
NF_GET_VARA_REAL 74
NF_GET_VARA_TEXT 74
NF_GET_VAR_DOUBLE 73
NF_GET_VAR_INT 73
NF_GET_VAR_INT1 73
NF_GET_VAR_INT2 73
NF_GET_VARM_DOUBLE 76, 78
NF_GET_VARM_INT 76, 78
NF_GET_VARM_INT1 76, 78
NF_GET_VARM_INT2 76, 78
NF_GET_VARM_REAL 76, 78
NF_GET_VARM_TEXT 76, 78
NF_GET_VAR_REAL 73
NF_GET_VARS_DOUBLE 77
NF_GET_VARS_INT 77
NF_GET_VARS_INT1 76
NF_GET_VARS_INT2 77
NF_GET_VARS_REAL 77
NF_GET_VARS_TEXT 76
NF_GET_VAR_TEXT 73
NF_GLOBAL 86, 93
NF_INQ 41
NF_INQ_ATT 92
NF_INQ_ATTID 93
NF_INQ_ATTLEN 93, 95
NF_INQ_ATTNAME 31, 86, 93
NF_INQ_ATTTYPE 93
NF_INQ_DIM 50
NF_INQ_DIMID 30
NF_INQ_DIMLEN 50
NF_INQ_DIMNAME 50
NF_INQ_LIBVERS 36
NF_INQ_NATTS 41
NF_INQ_NDIMS 41
NF_INQ_NVARS 41
NF_INQ_UNLIMDIM 41
NF_INQ_VAR 58
NF_INQ_VARDIMID 58
NF_INQ_VARID 57
NF_INQ_VARNAME 58
NF_INQ_VARNATTS 58, 93
NF_INQ_VARNDIMS 58
NF_INQ_VARTYPE 58
NF_INT 55
NF_INT1 data type 16
NF_INT2 data type 16
NF_MAX_DIMS 48
NF_MAX_NAME 51, 58, 134
NF_MAX_VAR_DIMS 59
NF_NOCLOBBER 37
NF_NOERR 37, 38, 39, 40, 42, 44, 46, 49, 50, 51, 52, 56, 57, 59, 60, 62, 64, 66, 69, 72, 73, 75, 78, 80, 85, 91, 93, 97, 98, 99
NF_NOFILL 45, 46
NF_NOWRITE 38
NF_OPEN 37
NF_PUT_ATT_DOUBLE 90
NF_PUT_ATT_INT 90
NF_PUT_ATT_INT1 90
NF_PUT_ATT_INT2 90
NF_PUT_ATT_REAL 90
NF_PUT_ATT_TEXT 90
NF_PUT_VAR1_DOUBLE 59
NF_PUT_VAR1_DOUBLE example 61
NF_PUT_VAR1_INT 59
NF_PUT_VAR1_INT1 59
NF_PUT_VAR1_INT2 59
NF_PUT_VAR1_REAL 59
NF_PUT_VAR1_TEXT 59
NF_PUT_VARA_DOUBLE 63
NF_PUT_VARA_DOUBLE example 62, 64
NF_PUT_VARA_INT 63
NF_PUT_VARA_INT1 63
NF_PUT_VARA_INT2 63
NF_PUT_VARA_REAL 63
NF_PUT_VARA_TEXT 63, 84
NF_PUT_VAR_DOUBLE 61
NF_PUT_VAR_INT 61
NF_PUT_VAR_INT1 61
NF_PUT_VAR_INT2 61
NF_PUT_VARM_DOUBLE 67
NF_PUT_VARM_INT 67
NF_PUT_VARM_INT1 67
NF_PUT_VARM_INT2 67
NF_PUT_VARM_REAL 67
NF_PUT_VARM_TEXT 67
NF_PUT_VAR_REAL 61
NF_PUT_VARS_DOUBLE 65
NF_PUT_VARS_INT1 65
NF_PUT_VARS_INT2 65
NF_PUT_VARS_REAL 65
NF_PUT_VARS_TEXT 65
NF_PUT_VAR_TEXT 61
NF_REAL data type 16
NF_REDEF 38
NF_RENAME_ATT 98
NF_RENAME_DIM 52
NF_RENAME_VAR 84
NF_SET_FILL 45, 84
NF_SHARE 29, 32, 37, 38, 43, 103, 136
NF_SHORT 55
NF_SHORT data type 16
NF_STRERROR 35
NF_SYNC 42
NF_UNLIMITED 49
NF_WRITE 38
PARAMETER name conventions 134
platform-specific optimization 103
problem reports, searching past 117
scale_factor attribute 87
scientific data access, other software for 117
searching past problem reports 117
shared dataset access 42, 103, 114
signed 89
signed byte data type 22
signedness attribute 89
software for scientific data access 117
space required for attribute 86
specification, file format 121
INCLUDE 33
stride vector 23, 54, 65, 66, 67, 69, 76, 78
conventions, units 119
valid_max attribute 87
valid_min attribute 87
valid_range attribute 87
floating-point, converting 102
dimensions, maximum number of 56, 59
variable dimensions, maximum 56
index mapping 23, 25, 54, 67, 69, 78, 130