[次] [性急過ぎる ] [トップ ] [内容 ] [インデックス ] [ netCDFホームページ ] [ユニ‐データホームページ]
Fortran版 NetCDFユーザーのガイド
この章は、netCDFファンクション ( netCDF データセット を扱うもの、または、netCDFライブラリ全体にかかわるもの) のインターフェースを提示する。
まだ開かれていない netCDF データセット (訳注: ファイルのこと) は、そのデータセット 名によってのみ参照され得る。いったん、netCDF データセットが開かれれば、それは、netCDF ID によって参照される。それはあなたがデータセットを作成する、もしくは開くとき、返された小さい非負の整数である。netCDF IDは、Cにおけるファイル記述子、または、FORTRANにおける論理的装置番号によく似ている。あらゆる1つのプログラムにおいて、別個に開かれた netCDF データセットのnetCDF IDは異なる。1つのnetCDF データセットは、同時に複数回開くことができる。その場合はnetCDF ID は異なる。しかしながら、ひとつの netCDF データセット を複数開いた実体のうち書き込みを可能にできるのは１つだけである。netCDF データセットが閉じられるとき、IDは、もはやnetCDF データセットと関連しなくなる。
netCDFライブラリにかかわる関数には以下のものが含まれる:
1つのオブジェクトとしてのnetCDF データセット に対して以下のような操作がサポートされる。
本章ではnetCDFインターフェースを規定する際に使用する規約を示した後で、これらの操作のためのインタフェースの詳細な記述を提示する。
本章以降でのnetCDF関数のためのインタフェース記述は、以下の要素からなる。
FORTRAN 関数引用仕様および引数の記述においては、大文字が入力用引数、小文字が出力用引数である。
プログラム例では、各netCDFファンクションコールから返されたエラー状態のチェックはエラーが検出された場合HANDLE_ERRサブルーチンを呼ぶようにしている。HANDLE_ERRサブルーチンの例としては、 Section 5.2
「エラー状態に対応するメッセージを得る:
NF_STRERROR」を参照せよ。
NF_STRERRORファンクションNF_STRERRORは、整数netCDFエラー状態、もしくは、他のnetCDFファンクションへの前のコールによっておそらく返されたシステムエラー番号に対応するエラーメッセージストリングへの静的な参照を返す。netCDFエラー状態コードのリストは各言語のためのインクルードファイルからも利用可能である。
CHARACTER*80 FUNCTION NF_STRERROR (INTEGER NCERR)
NCERR |
前のコールからあるnetCDFファンクションまで返されたであろうエラー状態。 |
あなたが無効の整数エラー状態 ( netCDFエラーメッセージと全く一致しない
) を提供するならば、〜もしくは、〜もしくは、あらゆるシステムエラーメッセージ
( システムstrerrorファンクションによって理解されたように
) に、nc_strerrorは、戻る、ストリング、示す、それ、ことができない、そのようなエラー状態。
ここにシンプルなエラー扱いの例がある使用するサブルーチンNF_STRERROR netCDFエラー状態と一致するエラーメッセージをプリントすることは、あらゆるnetCDFファンクションコール、そして、出口から戻った:
INCLUDE 'netcdf.inc'
...
SUBROUTINE HANDLE_ERR(STATUS)
INTEGER STATUS
IF (STATUS .NE. NF_NOERR) THEN
PRINT *, NF_STRERROR(STATUS)
STOP 'Stopped'
ENDIF
END
NF_INQ_LIBVERSファンクションNF_INQ_LIBVERSは、netCDFライブラリのバージョンを確認するストリングを返し、そして、それがいつあったかは、増大した。
CHARACTER*80ファンクションNF_INQ_LIBVERS
( )
エラー
このファンクションは、引数をとらず、従って、エラーは、その呼出しにおいて可能ではない。
ここで例使用であるNF_INQ_LIBVERSそのプログラムがどちらであるかに関するnetCDFライブラリのバージョンをプリントすることは、連結した:
'netcdf.inc'を含む
... .
プリント*、NF_INQ_LIBVERS ( )
NF_CREATEこのファンクションは、netCDF ID ( 他のnetCDFファンクションコールにおけるnetCDF データセットを参照するために続いて使われ得る ) を返す新しいnetCDF データセットを作成する。書込みアクセスへの開かれた新しいnetCDF データセット、そして、配置する、で、定義する、モード、準備が整った、というのは、〜からだ、あなた、加えるために、次元、変数、そして、帰する。
創造モードフラグは、同じ名前によって現存するデータセットにオーバーライトするかどうか指定する、そして、データセットへのアクセスが共有されるか否かに拘らず。
整数ファンクションNF_CREATE
( CHARACTER* ( * ) パス、整数CMODE、整数ncid )
エラー
NF_CREATE値を返すNF_NOERR、エラーが発生しなかったならば。エラーの可能な原因は、以下を含む。
NF_NOCLOBBERに。
我々が作成するこの例、foo.ncと指定されたnetCDF
データセット ;我々は、データセットがその名前を持つデータセットがまだ存在しなくさえすれば、現在のディレクトリにおいて作成されることを望む:
'netcdf.inc'を含む
... .
整数NCID、状態
... .
状態= NF_CREATE ( 'foo.nc'、NF_NOCLOBBER、NCID )
、かどうか ( STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS )
を呼ぶ、
NF_OPENするファンクションNF_OPENは、アクセスのために現存するnetCDF
データセットを開く。
整数ファンクションNF_OPEN (
CHARACTER* ( * ) パス、整数OMODE、整数ncid )
エラー
NF_OPENする値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_OPEN現存するnetCDF
データセットを開くことは、読取り‐オンリーな共有されなくアクセスのfoo.ncを指定した:
'netcdf.inc'を含む
... .
整数NCID、状態
... .
状態= NF_OPEN ( 'foo.nc'、0、NCID ) 、かどうか ( STATUS
.NE. NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
NF_REDEFファンクションNF_REDEFオープンnetCDF
データセットを置く、に、モードを定義する、従って、局面、変数、及び、属性は、加えられ得る、もしくは改名され得て、そして、属性は、削除され得る。
整数ファンクションNF_REDEF
( INTEGER NCID )
| NCID | 前のコールからNF_OPEN、または、NF_CREATEまでのNetCDF
ID。 |
エラー
NF_REDEF値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるfoo.ncと指定され、そして置かれた現存するnetCDF
データセットを開くためのNF_REDEF、それ、に、モードを定義する:
'netcdf.inc'を含む
... .
整数NCID、状態
... .
状態= NF_OPEN ( 'foo.nc'、NF_WRITE、NCID )
、データセットを開く、かどうか ( STATUS .NE.
NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
... .
状態= NF_REDEF ( NCID )
、入れられる、モードを定義する、かどうか (
状態.NE. NF_NOERR ) HANDLE_ERR ( STATUS ) を呼ぶ、
NF_ENDDEFファンクションNF_ENDDEFは、オープンnetCDFをデータセットであると考える、が無い、モードを定義する。それが中にあったとき、netCDF
データセットに出された変更は、モードを定義する、問題が発生しなかったならば、ディスクにチェックされて、犯される。非レコード変数は、「fill
value」もまで初期化されるかもしれない ( 「Writes
: NF_SET_FILLのためにFill Modeを示される」Section 5.12が39にページ付をすることを理解しなさい
) 。netCDF データセットは、データモードにそれから配置される。従って、変数データは、読まれ得る、もしくは書かれ得る。
このコールは、データをいくらかの情況の下にコピーすることを必要とするかもしれない。 第9 章を見る、「NetCDF File Structure、及び、Performance」、更に広い討論のための95 ページ。
整数ファンクションNF_ENDDEF
( INTEGER NCID )
NCID |
前のコールからNF_OPEN、または、NF_CREATEまでのNetCDF
ID。 |
エラー
NF_ENDDEF値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_ENDDEF新しいnetCDF
データセットの定義を終えることは、foo.ncを指定し、そして、それをデータモードに入れた:
'netcdf.inc'を含む
... .
整数NCID、状態
... .
状態= NF_CREATE ( 'foo.nc'、NF_NOCLOBBER、NCID )
、かどうか ( STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS )
を呼ぶ、
... .!次元、変数、属性を作成する
状態= NF_ENDDEF ( NCID ) 、かどうか ( 状態.NE. NF_NOERR
) HANDLE_ERR ( STATUS ) を呼ぶ、
NF_CLOSEファンクションNF_CLOSEは、オープンnetCDF
データセットを閉じる。データセットが中にあるならば、モードを定義する、NF_ENDDEF閉鎖の前に呼ばれるであろう。(
、この場合、かどうか、NF_ENDDEFは、エラーを返す、NF_ABORTは、データセットを一貫した状態に前に回復するために、自動的に呼ばれるであろう、定義する、モードは、最後に入力された、
) 、オープンnetCDF
データセットが閉じられた後で、そのnetCDF IDは、開かれる、もしくは作成される次のnetCDF
データセットに再び‐割り当てられるかもしれない。
整数ファンクションNF_CLOSE
( INTEGER NCID )
NCID |
前のコールからNF_OPEN、または、NF_CREATEまでのnetCDF
ID。 |
エラー
NF_CLOSE値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_CLOSE新しいnetCDF
データセットの定義を終えることは、foo.nc、及び、リリースをそのnetCDF
IDと命名した:
'netcdf.inc'を含む
... .
整数NCID、状態
... .
状態= NF_CREATE ( 'foo.nc'、NF_NOCLOBBER、NCID )
、かどうか ( STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS )
を呼ぶ、
... .!次元、変数、属性を作成する
状態= NF_CLOSE ( NCID ) 、かどうか ( 状態.NE. NF_NOERR )
HANDLE_ERR ( STATUS ) を呼ぶ、
NF_INQファミリーメンバー、の、NF_INQ、ファンクションのファミリーは、オープンnetCDF
データセットに関する情報を返す ( そのnetCDF IDを与えられて
) 。データセットは、ファンクションを尋ねる、どちらからでも呼ばれるかもしれない、モード、もしくは、データモードを定義する。最初のファンクション、もしあれば、NF_INQは、次元、変数、グローバルな属性の数の数の数、及び、無制限の長さによって定義された次元の次元IDのために値を返す。それぞれファミリーにおける他のファンクションは、ほんの情報のこれらのアイテムのうちの1つを返す。
FORTRANのために、これらのファンクション、含む、NF_INQNF_INQ_NDIMSNF_INQ_NVARSNF_INQ_NATTS、そして、NF_INQ_UNLIMDIM。
必要とされた情報が各オープンnetCDF データセットのためのメモリにおいて利用可能であるので、これらの関数が呼ばれるとき、I/Oは、遂行されない。
整数ファンクションNF_INQ (
整数NCID、整数ndims、整数nvars、整数ngatts、整数unlimdimid
) 整数ファンクションNF_INQ_NDIMS ( 整数NCID、整数ndims
) 整数ファンクションNF_INQ_NVARS ( 整数NCID、整数nvars
) 整数ファンクションNF_INQ_NATTS ( 整数NCID、整数ngatts
) 整数ファンクションNF_INQ_UNLIMDIM ( 整数NCID、整数unlimdimid
)
エラー
全てのメンバー、の、NF_INQファミリーは、値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_INQ netCDF
データセットについて知ることは、foo.ncを指定した:
'netcdf.inc'を含む
... .
整数状態、NCID、NDIMS、NVARS、NGATTS、UNLIMDIMID
... .
状態= NF_OPEN ( 'foo.nc'、NF_NOWRITE、NCID ) 、かどうか
( STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
... .
状態= NF_INQ ( NCID、NDIMS、NVARS、NGATTS、UNLIMDIMID )
、かどうか ( STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS )
を呼ぶ、
NF_SYNCファンクションNF_SYNCは、netCDF
データセットのディスクコピーを不メモリバッファと同期させる方法を提供する。あなたが同期することを望むであろう2つの理由がある、書く:
このファンクションは、netCDFライブラリの前のバージョンと後方へ‐互換性がある。その意図は、ライタ電話を受けることによる多重リーダ、及び、1つのライタの間のnetCDF
データセットのシェアリングを可能にすることであった記述、及び、リーダコール後のNF_SYNC各々の前のNF_SYNCは、読んだ。ライタのために、これは、バッファをディスクにフラッシュする。リーダのために、そのリーダが変更がデータセットを閉じて、再開しなければならないことなしの記述プロセス
( <例>、書かれたレコードの数 )
によって作られるのを見るように、それは、読まれた次が以前に隠されたバッファから来たよりむしろディスクから来たであろうことを確保する。あなたが少量のデータにただアクセスしているならば、あなたがバッファリングの利益を断念しているので、全ての書込み後のディスクへ常に同期することは、コンピュータ資源において高価であるかもしれない。
シェアリング ( そして、今推薦されるもの )
を完遂することがライタを持つことであり、そして、リーダが開く更に容易な方法、データセット、に関して、NF_SHAREは、だらりと垂れ、そして、呼ぶことは、必要ではないであろう全てのNF_SYNC。しかしながら、NF_SYNCファンクションは、更に優れた粒状をまだ提供する、より、2、3のnetCDFアクセスがプロセスの間に同期される必要があるさえあれば、NF_SHAREは、だらりと垂れる。
それは、付属のデータへの変更がによって属性の値のように自動的に増殖させられないノートにとって重要である、使用する、の、NF_SHAREは、だらりと垂れる。使用、の、NF_SYNCファンクションがまだこの目的のために必要とされる。
データスキーマを変えるためにライタ入力がモードを定義するとき、データセットsを共有することは、余分の注意を必要とする。前のリリースにおいて、そのライタが離れた後で、モードを定義する、それらのリーダは、データセットの古いコピーを見ている状態にしておかれた、‖
( それらの変更が新しいコピーに行われたので )
。リーダが変更を見るであろう唯一の方法は、データセットを閉じて、再開することによるものであった。今、それらの変更は、適当に行われる。しかし、リーダは、それらの内部のテーブルが今新しいデータセットスキーマと一致しないという知識を持っていない。netCDF
データセットsが再定義を横断して共有されるならば、netCDFライブラリに外部のあるメカニズムは、それを供給されなければならない、再定義、及び、原因の間のリーダによってアクセスを妨げる、呼ぶためのリーダ、あらゆる次のアクセスの前のNF_SYNC。
呼んでいるとき、NF_SYNC
netCDF
データセットは、データモードになければならない。netCDF
データセット、で、モードを定義する、ディスクへ同期される、時のみ、NF_ENDDEFは、呼ばれる。他のプロセスが呼ぶかもしれないと書いているnetCDF
データセットを研究しているプロセスNF_SYNC、変更と共にアップデートされることは、記述プロセス
( <例>、書かれたレコードの数 )
によってデータに進んだ (
データセットを閉じて、再開しなければならなくないで
) 。
netCDF データセットが閉じられるとき、もしくは、あなたが去るときはいつでも、データは、ディスクへ自動的に同期される、モードを定義する。
整数ファンクションNF_SYNC (
INTEGER NCID )
NCID |
前のコールからNF_OPEN、または、NF_CREATEまでのNetCDF
ID。 |
エラー
NF_SYNC値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_SYNCディスクに同期することは、foo.ncと指定されたnetCDF
データセットについて書く:
'netcdf.inc'を含む
... .
整数状態、NCID
... .
状態= NF_OPEN ( 'foo.nc'、NF_WRITE、NCID ) 、かどうか (
STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
... .
!データを書く、もしくは、属性を変える
... .
状態= NF_SYNC ( NCID ) 、かどうか ( 状態.NE. NF_NOERR )
HANDLE_ERR ( STATUS ) を呼ぶ、
NF_ABORTそれが自動的に呼ばれるので、あなたは、もはやこれをファンクションと呼ぶ必要がないデータセットが中にある場合のNF_CLOSEは、モードを定義し、そして、変更を犯すことによって、何かは、うまくいかない。ファンクションNF_ABORTnetCDF
データセットを単に閉じる (
それが中にないとしても、モードを定義する )
。データセットが作成されつつあり、そして、まだ在宅しているならば、モードを定義する、データセットは、削除される。かどうか、モードを定義する、コールから侵入された、に、NF_REDEF定義モードが入力され、そして、データセットが閉じられる前に、netCDF
データセットは、その状態に回復する。
整数ファンクションNF_ABORT
( INTEGER NCID )
NCID |
前のコールからNF_OPEN、または、NF_CREATEまでのNetCDF
ID。 |
エラー
NF_ABORT値を返すNF_NOERRエラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
ここで例使用であるNF_ABORT データセットの再定義を取り消すことは、foo.ncを指定した:
'netcdf.inc'を含む
... .
整数状態、NCID、LATID
... .
状態= NF_OPEN ( 'foo.nc'、NF_WRITE、NCID ) 、かどうか (
STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
... .
状態= NF_REDEF ( NCID ) 、かどうか ( 状態.NE. NF_NOERR )
HANDLE_ERR ( STATUS ) を呼ぶ、
... .
状態= NF_DEF_DIM ( NCID、` LAT '、18、LATID )
、かどうか ( STATUS .NE. NF_NOERR )
、その時、次元定義の故障したコールHANDLE_ERR (
STATUS ) 状態= NF_ABORT ( NCID )
、再定義を中断する、かどうか ( STATUS .NE. NF_NOERR
) 、HANDLE_ERR ( STATUS ) をENDIFと呼ぶ、
... .
NF_SET_FILLこのファンクションは、最適化するために、進んだ使用のためのものである、下で示されたいくらかの情況の下で書く。ファンクションNF_SET_FILLは、netCDF
データセットのためのフィルモードを記述、及び、リターンのために開いた状態にする、電流、リターンパラメータにおいてモードを満たす。フィル方法は、どちらとしてでも指定され得るNF_FILL〜もしくは、NF_NOFILL .デフォルト行動一致、に、NF_FILLは、そのデータである、前‐満たされる、に関して、値を満たす、それ、である、いっぱいになる、値は、いつあなたが非レコード変数を作成するかを手紙で知らせられる、もしくは、あなたがデータを越えて値を書くとき、それは、まだ書かれなかった。これは、それが書かれる前に、データを読む試みを検出するのを可能にする。使用に関する更に多くの情報のために
Section 7.16「フィルValues」、78
ページを見る、の、値を満たす。いかにあなた自身のフィル値を定義するかに関する情報のために
Section 8.1「属性のConventions」、81
ページを見なさい。
行動一致、に、NF_NOFILLフィル値によってデータを前‐満たすことのデフォルト行動をオーバライドする。これは、パフォーマンスを拡張するために使われ得る、
( それが複写を回避するので、書く、netCDFライブラリが書くとき、発生する、遅くデータと共に重ね書きされる値を満たす
) 。
netCDF データセットが既にどちらのモードにあったかを示す値は、返される。あなたは、オープンnetCDF データセットのフィル方法を一時的に切り替え、その後、それを前のモードに回復するためにこの値を使うことができる。
あなたがオンを変えた後で、オープンnetCDF
データセットのためのNF_NOFILLモード、あなたは、後で読まれるであろう全てのポジションで正当なデータを書くに違いなくなければならない。nofillモードが記述のために開いたnetCDF
データセットの一時的な特質のみであることに注目しなさい:あなたがデータセットを閉じて、再開するならば、それは、デフォルト行動に戻るであろう。あなたは、呼ぶことによってデフォルト行動に同じく戻ることができるNF_SET_FILL、再び、明白に定着するために、モードを満たす、に、NF_NOFILL .
nofillモードを示すために、それが有利である3つの状況がある:
NF_ENDDEF、及び、その時は、完全に全ての非レコード変数、及び、あなたが初期化することを望む全てのレコード変数の最初のレコードを書く。
NF_ENDDEFは、それから完全に全ての新しい変数を書く。
netCDF データセットが無制限の次元を持っており、そして、最後のレコードがnofillモードの間書かれたならば、それから、あなたがnetCDFインタフェースを経てのみデータにアクセスするならば、nofillモードがセットではなく、これであったかどうかが完全に透過であろうより、データセットは、更に短いかもしれない。
この特徴の使用は、将来のリリースにおいて利用可能ではないかもしれない ( 〜もしくは他の事はもちろん必要とされる ) 。プログラマは、この特徴に対する重い信頼がないようにと警告される。
整数ファンクションNF_SET_FILL
( INTEGER NCID、整数FILLMODE、整数old_mode )
NCID |
前のコールからNF_OPEN、または、NF_CREATEまでのNetCDF
ID。 |
|
FILLMODE |
データセット、どちらのNF_NOFILLのためにでもフィルモードを望んだ、〜もしくは、NF_FILL。 |
|
| old_mode | 電流を返されて、このコール、どちらのNF_NOFILLでも、または、NF_FILLの前にデータセットのモードを満たしなさい。 |
エラー
NF_SET_FILL値を返すNF_NOERR、エラーが発生しなかったならば。他の場合は、返された状態は、エラーを示す。エラーの可能な原因は、以下を含む。
NF_NOFILL、また、NF_FILL . ここで例使用であるnofillモードを設定するためのNF_SET_FILL、次の、foo.ncと指定されたnetCDF
データセットについて書く:
'netcdf.inc'を含む
... .
整数NCID、状態、OMODE
... .
状態= NF_OPEN ( 'foo.nc'、NF_WRITE、NCID ) 、かどうか (
STATUS .NE. NF_NOERR ) 、HANDLE_ERR ( STATUS ) を呼ぶ、
... .
!行動を前‐満たすデフォルトによってデータを書く
... .
OMODE = NF_SET_FILL ( NCID、NF_NOFILL )
... .
!前‐充填なしでデータを書く
... .
[次] [性急過ぎる ] [トップ ] [内容 ] [インデックス ] [ netCDFホームページ ] [ユニ‐データホームページ]