Next: Fill Values, Previous: NF_GET_VARM_ type, Up: Variables
Character strings are not a primitive netCDF external data type, in part because FORTRAN does not support the abstraction of variable-length character strings (the FORTRAN LEN function returns the static length of a character string, not its dynamic length). As a result, a character string cannot be written or read as a single object in the netCDF interface. Instead, a character string must be treated as an array of characters, and array access must be used to read and write character strings as variable data in netCDF datasets. Furthermore, variable-length strings are not supported by the netCDF interface except by convention; for example, you may treat a zero byte as terminating a character string, but you must explicitly specify the length of strings to be read from and written to netCDF variables.
Character strings as attribute values are easier to use, since the strings are treated as a single unit for access. However, the value of a character-string attribute is still an array of characters with an explicit length that must be specified when the attribute is defined.
When you define a variable that will have character-string values, use a character-position dimension as the most quickly varying dimension for the variable (the first dimension for the variable in FORTRAN). The length of the character-position dimension will be the maximum string length of any value to be stored in the character-string variable. Space for maximum-length strings will be allocated in the disk representation of character-string variables whether you use the space or not. If two or more variables have the same maximum length, the same character-position dimension may be used in defining the variable shapes.
To write a character-string value into a character-string variable, use either entire variable access or array access. The latter requires that you specify both a corner and a vector of edge lengths. The character-position dimension at the corner should be one for FORTRAN. If the length of the string to be written is n, then the vector of edge lengths will specify n in the character-position dimension, and one for all the other dimensions:(n, 1, 1, ..., 1).
In FORTRAN, fixed-length strings may be written to a netCDF dataset without a terminating character, to save space. Variable-length strings should follow the C convention of writing strings with a terminating zero byte so that the intended length of the string can be determined when it is later read by either C or FORTRAN programs.
The FORTRAN interface for reading and writing strings requires the use of different functions for accessing string values and numeric values, because standard FORTRAN does not permit the same formal parameter to be used for both character values and numeric values. An additional argument, specifying the declared length of the character string passed as a value, is required for NF_PUT_VARA_TEXT and NF_GET_VARA_TEXT. The actual length of the string is specified as the value of the edge-length vector corresponding to the character-position dimension.
Here is an example that defines a record variable, tx, for character strings and stores a character-string value into the third record using NF_PUT_VARA_TEXT. In this example, we assume the string variable and data are to be added to an existing netCDF dataset named foo.nc that already has an unlimited record dimension time.
INCLUDE 'netcdf.inc' ... INTEGER TDIMS, TXLEN PARAMETER (TDIMS=2) ! number of TX dimensions PARAMETER (TXLEN = 15) ! length of example string INTEGER NCID INTEGER CHID ! char position dimension id INTEGER TIMEID ! record dimension id INTEGER TXID ! variable ID INTEGER TXDIMS(TDIMS) ! variable shape INTEGER TSTART(TDIMS), TCOUNT(TDIMS) CHARACTER*40 TXVAL ! max length 40 DATA TXVAL /'example string'/ ... 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) ! enter define mode IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... ! define character-position dimension for strings of max length 40 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... ! define a character-string variable TXDIMS(1) = CHID ! character-position dimension first TXDIMS(2) = TIMEID STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... STATUS = NF_ENDDEF(NCID) ! leave define mode IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS) ... ! write txval into tx netCDF variable in record 3 TSTART(1) = 1 ! start at beginning of variable TSTART(2) = 3 ! record number to write TCOUNT(1) = TXLEN ! number of chars to write TCOUNT(2) = 1 ! only write one record STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL) IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)