FortranのためのNetCDFユーザーのガイド

4 NetCDFライブラリの使用

我々がnetCDFコールの一般のシーケンスのテンプレートが一般の使用のために必要としたことを規定するこの章。明瞭のために、我々は、ルーチンの名前のみ提示する;宣言、及び、エラーチェックを省略しなさい;変数、及び、属性のための一定の名前のタイプ‐特定の接尾部を省略しなさい;典型的に呼び出された多重時代であるステートメントをインデントしなさい;そして、...を使いなさい。他のステートメントの随意のシーケンスを表すために。十分なパラメータリストは、後の章で述べられる。

4.1 NetCDF Datasetを作成すること

NF_CREATE、netCDF datasetを作成する:入る、モードを定義する、
... .
NF_DEF_DIM、次元を定義する:名前、及び、長さから
... .
NF_DEF_VAR、変数を定義する:名前からタイプは、薄暗くなる
... .
NF_PUT_ATT、属性の値を割り当てる、
... .
NF_ENDDEF、定義を終える:離れる、モードを定義する、
... .
NF_PUT_VAR、変数に値を提供する、
... .
NF_CLOSE、閉じる:新しいnetCDF datasetをセーブする
わずか1つのコールは、2 netCDFモードの第1日であなたがどちらのポイントであろうかのnetCDF datasetを作成するのに必要とされる。オープンnetCDF datasetにアクセスして、それが中にあるとき、モード、もしくは、データモードを定義する。で、モードを定義する、あなたは、次元、変数、及び、新しい属性を作成し得る。しかし、あなたは、変数データを読むことができない、及び書くことができない。データモードにおいて、あなたは、データにアクセスし、そして、現存する属性を変え得る。しかし、あなたは、新しい次元、変数、または、属性を作成することを可能にされない。

1つのコール、に、NF_DEF_DIMは、作成された各次元のために必要とされる。同様に、1つのコール、に、NF_DEF_VAR各変数創造、及び、メンバーへの1つのコールのために必要とされる、の、NF_PUT_ATTファミリーは、定義された各属性のために必要とされ、そして、値を割り当てられる。離れるために、モードを定義し、そして、データモード、コールを入力するNF_ENDDEF .

データモードに1度、あなたは、新しいデータを変数に加え、古い値を変え、そして、現存する属性の値を変え得る ( 属性の変更が更に多くの記憶スペースを必要としない限り ) 。1つの値は、書かれるかもしれない、メンバーのうちの1つに関するnetCDF変数に、の、NF_PUT_VAR1ファミリー、に応じて、どんなタイプの、データ、あなたは、書かなければならない。変数の全ての値は、書かれるかもしれない、ただちに、メンバーのうちの1つと共に、の、NF_PUT_VARファミリー。変数のアレイ、または、アレイ断面は、メンバーを用いて書かれるかもしれない、の、NF_PUT_VARAファミリー。アレイセクションのサブ‐見本をとった、メンバーを用いて書かれるかもしれない、の、NF_PUT_VARSファミリー。アレイセクションをマップした、メンバーを用いて書かれるかもしれない、の、NF_PUT_VARMファミリー。( アクセスのサブ‐見本をとって、マップした、後で一般的な形の説明されるデータアクセスである。 )

最終的に、あなたは、呼出しによって書くために開かれたnetCDF datasets全てを明白に閉じるべきであるNF_CLOSE .デフォルトによって、ファイルシステムへのアクセスは、netCDFライブラリによってバッファされる。プログラムが記述のために開いたnetCDF datasetsと共に異常に終了するならば、あなたの最も最近の修正は、失われるかもしれない。データのこのデフォルトバッファリングは、無効にされる、設定によって、datasetを開いているとき、NF_SHAREは、だらりと垂れる。このフラグがセットされるとしてもではあるが、作られた属性の値、または、変更に変わる、で、モードを定義する、書かれない、まで、NF_SYNC、〜もしくは、NF_CLOSEは、呼ばれる。

4.2 NetCDFのために既知の名前を持つDatasetを読むこと

NF_OPEN、現存するnetCDF datasetを開く、
... .
NF_INQ_DIMID、次元IDを得る、
... .
NF_INQ_VARID、変数IDを得る、
... .
NF_GET_ATT、属性の値を得る、
... .
NF_GET_VAR、値を得る、の、変数、
... .
NF_CLOSE、netCDF datasetを閉じる、
最初に、1つのコールは、netCDF datasetを開き ( dataset名前を与えられて ) そして、netCDF ID ( 全ての次のコールにおけるオープンnetCDF datasetを参照するために使われる ) を返す。

次、コール、に、関心の各次元のためのNF_INQ_DIMIDは、次元名から次元IDを得る。同様に、各々は、IDがコールによってその名前から決定される変数を必要としたNF_INQ_VARID .いったん、変数IDが知られていれば、変数属性の値は、netCDF ID、変数ID、及び、入力としての所望の属性の名を用いて検索され得る、メンバーに、の、NF_GET_ATTファミリー ( 、典型的に、NF_GET_ATT_TEXT、〜もしくは、NF_GET_ATT_DOUBLE各々のための ) は、属性を望んだ。変数データ値は、コールによるnetCDF datasetから直接アクセスされ得る、メンバーに、の、1つの値のためのNF_GET_VAR1ファミリー、全体の変数のためのNF_GET_VARファミリー、または、様々な他のメンバー、の、NF_GET_VARANF_GET_VARS〜もしくは、アレイ、サブ‐見本をとられた、もしくは、マップされたアクセスのためのNF_GET_VARMファミリー。

最終的に、netCDF datasetは、接近されるNF_CLOSE .読取りのためにのみ開いたdatasetを閉じるために、必要性がない。

4.3 netCDFのために未知の名前を持つDatasetを読むこと

netCDFオブジェクトに関する名前、そして、他の情報は、呼ぶことによってnetCDF datasetsから獲得されるかもしれない、ファンクションを尋ねる。これらは、全てのnetCDF dataset、次元、変数、または、属性に関する情報を返す。次のテンプレートは、いかにそれらが使われるかを例証する:

NF_OPEN、現存するnetCDF datasetを開く、
... .
NF_INQ、何がそれにあるかを見い出す、
... .
NF_INQ_DIM、次元名前、長さを得る、
... .
NF_INQ_VAR、変数名前、タイプ、形を得る、
... .
NF_INQ_ATTNAME、属性の名前を得る、
... .
NF_INQ_ATT、属性の値を得る、
... .
NF_GET_ATT、属性の値を得る、
... .
NF_GET_VAR、値を得る、の、変数、
... .
NF_CLOSE、netCDF datasetを閉じる、
前の例と同様に、netCDF IDを返して、1つのコールは、現存するnetCDF datasetを開く。IDが与えられるこのnetCDF、NF_INQルーチン ( 1つがあるならば、次元、変数の数、グローバルな属性の数の数、及び、無制限の次元のIDを返す ) 。

全て、尋ねる、ファンクションは、I/Oを使わず、必要としないために、安い、‖ ( netCDF datasetが最初に開かれるとき、それらが提供する情報がメモリに格納されるので ) 。

始まって、次元IDが連続した整数を使う、際、1 .いったん、作成されれば、同じく次元は、削除されることができない。従って、netCDF datasetにおいて次元IDの数を知ることは、全ての次元IDを知ることを意味する:それらは、それらの整数である1、2、3、...、アップして、次元の数に達するまで。各次元IDのために、コール、に、ファンクションを尋ねる、NF_INQ_DIMは、次元名前、及び、長さを返す。

変数IDは、連続した整数から同じく割り当てられる1、2、3、...、アップして、変数の数に達するまで。これらは、使われ得るNF_INQ_VARは、名前、タイプ、形、及び、各変数に割り当てられた属性の数を発見するために、呼ぶ。

いったん、変数のための属性の数が知られていれば、連続するコール、に、NF_INQ_ATTNAMEは、netCDF IDを与えられた各属性、変数ID、及び、属性の番号のために名前を返す。属性の名によって武装した、コール、に、NF_INQ_ATTは、そのタイプ、及び、長さを返す。タイプ、及び、長さを与えられて、あなたは、属性の価値を保つために、十分なスペースを割当て得る。その時、メンバーへのコール、の、NF_GET_ATTファミリーは、属性の値を返す。

いったん、netCDF変数のID、及び、形が知られていれば、データ値は、呼出しによってアクセスされ得る、メンバー、の、1つの値のためのNF_GET_VAR1ファミリー、または、メンバー、の、NF_GET_VAR ,NF_GET_VARA ,NF_GET_VARS ,〜もしくは、NF_GET_VARM、のために、様々な種類のアレイアクセス。

4.4新しい局面、変数、属性を加えること

NF_OPEN、現存するnetCDF datasetを開く、
... .
NF_REDEF、それを置いた、に、モードを定義する、
... .
NF_DEF_DIM、追加の次元 ( もしあれば ) を定義する、
... .
NF_DEF_VAR、追加の変数 ( もしあれば ) を定義する、
... .
NF_PUT_ATT、他の属性 ( もしあれば ) を定義する、
... .
NF_ENDDEF、定義をチェックする、離れる、モードを定義する、
... .
NF_PUT_VAR、新しい変数値を提供する、
... .
NF_CLOSE、netCDF datasetを閉じる、
netCDF datasetがによって最初に開かれるA、NF_OPENは、呼ぶ。このコールは、データモード ( 現存するデータ値がアクセスされ得ることを意味し、そして、変わった ) にオープンdatasetを入れる。現存する属性は、変えられ得る ( それらが成長しない限り ) 。しかし、何も、加えられることができない。呼出しによって新しいnetCDF次元、変数、または、あなたが入力しなければならない属性を加えるためにモードを定義するNF_REDEF .で、モード、コールを定義する、新しい次元を定義するためのNF_DEF_DIM、新しい変数を定義するためのNF_DEF_VAR、及び、メンバー、の、新しい属性を変数に割り当てる、もしくは、古い属性を拡大するためのNF_PUT_ATTファミリー。

あなたは、去ることができる、モードを定義する、そして、呼出しによって一貫性のために全ての新しい定義をチェックする、そして、変更をディスクに約束するデータモードに再び入る、NF_ENDDEF .あなたがデータモード、単にコールに再び入ることを望まないならば、NF_CLOSE ( 最初の呼出しの効果を持つであろう ) NF_ENDDEF。

まで、NF_ENDDEFコール、あなたは、作られた全ての再定義を取り消すかもしれない、で、モードを定義する、そして、前の状態を回復する、呼出しによるnetCDF datasetのうちで、NF_ABORT .あなたは、同じく使用するかもしれない、NF_ABORTは、netCDF datasetを一貫した状態に回復するために、呼ぶ、かどうか、コール、に、NF_ENDDEFは、フェイルする。あなたが呼んだならば、定義モード、及び、意味されたコールからのNF_CLOSE、に、NF_ENDDEFは、フェイルする、NF_ABORTは、netCDF datasetを閉じ、そして、それをその前の一貫した国家に残すために、自動的に呼ばれるであろう ( あなたが入る前に、モードを定義する ) 。

せいぜい、1つのプロセスは、一度に書けるためにnetCDF datasetを開いた状態にするべきである。訓練された使用によって、そのライブラリは、1つのライタを多重の同時に起こるリーダへの限られたサポートに提供するように設計されている、の、NF_SYNCファンクション、そして、NF_SHAREは、だらりと垂れる。ライタが変更を行うならば、で、モードを定義する、新しい変数の追加、次元、または、属性のように、約、ライブラリに外部の方法は、リーダを妨げるために必要である、から、同時に起こるアクセスを行う、そして、リーダに通知するために、に、呼ぶ、次のアクセスの前のNF_SYNC。

4.5エラーの扱い

NF_STRERRORファンクションは、返された整数エラー状態をエラーメッセージストリングに変換するために、利用可能である。

時おり、低い‐レベルI/Oエラーは、netCDF図書館より下の層において発生するかもしれない。例えば、かどうか、オペレーションがあなたをもたらす、と書く、もはや利用可能ではないデバイスに、あなたは、ディスク割当を越える、もしくは、書こうと試みるために、netCDF図書館より下の層からエラーを得るかもしれない、しかし、生じること、書く、エラーは、返された状態値においてまだ反映されるであろう。

4.6 NetCDFライブラリを持つコンパイル、及び、連結

〜毎、netCDFファンクション、または、定数に参照を付けるFORTRANファイルは、最初のそのような参照の前に適切なINCLUDEステートメントを含まなければならない:

'netcdf.inc'を含む
例えば、netcdf.incがインストールされるディレクトリを指定するために、netcdf.incファイルがFORTRANコンパイラが常に見る標準のディレクトリにインストールされない限り、コンパイラを呼び出しているとき、あなたは、-Iオプションを使わなければならない:

f77 -c -I/usr/local/netcdf/include myprogram.f
代りに、あなたは、netCDFが異なるロケーションにインストールされる他のプラットホームであなたのプログラムが編集しないであろうその時以外のINCLUDEステートメントにおいて絶対的パス名前を指定するであろう。

netCDFライブラリが連結するものが常に見る標準のディレクトリにインストールされない限り、あなたは、netCDFライブラリを使うオブジェクトファイルを連結するために-L、そして、-lオプションを使わなければならない。例えば:

f77 -o myprogram myprogram.o -L/usr/local/netcdf/lib -lnetcdf
代りに、あなたは、ライブラリのために絶対的パス名前を指定するであろう:

f77 -o myprogram myprogram.o -l/usr/local/netcdf/lib/libnetcdf

4.1 - NetCDF Datasetを作成している

4.2 - NetCDFのために既知の名前を持つDatasetを読んでいる

4.3 - netCDFのために未知の名前を持つDatasetを読んでいる

4.4 -新しい局面、変数、属性を加えている

4.5 -エラーの扱い

4.6 - NetCDFライブラリを持つコンパイル、及び、連結