File: guidef-12.html

package info (click to toggle)
netcdf-doc 1%3A3a-2.1
links: PTS
area: main
in suites: etch, etch-m68k, sarge
size: 3,052 kB
ctags: 1,463
sloc: makefile: 58; sh: 17
file content (1131 lines) | stat: -rw-r--r-- 94,407 bytes
parent folder | download | duplicates (2)
<!-- Generated by Harlequin WebMaker 2.2.3 (24-Apr-1996)
LispWorks 3.2.2 -->
<HTML> <HEAD>
<TITLE>7	 Variables</TITLE>
</HEAD>
<BODY bgcolor="#ffffff">
<A NAME=HEADING12></A>
<A HREF="guidef-13.html">[Next] </A><A HREF="guidef-11.html">[Previous] </A><A HREF="guidef-1.html">[Top] </A><A HREF="guidef-3.html">[Contents] </A><A HREF="guidef-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
NetCDF User's Guide for Fortran<P>
<A NAME=HEADING12-0></A>
<H1>7  Variables</H1>
<HR>
 Variables <A NAME=MARKER-2-2429></A><A NAME=MARKER-2-2430></A><A NAME=MARKER-2-2431></A><A NAME=MARKER-2-2432></A><A NAME=MARKER-2-2433></A><A NAME=MARKER-2-2434></A><A NAME=MARKER-2-2435></A><A NAME=MARKER-2-2436></A><A NAME=MARKER-2-2437></A>for a netCDF dataset are defined when the dataset is created, while the netCDF dataset is in define mode. Other variables may be added later by reentering define mode. A netCDF variable has a name, a type, and a shape, which are specified when it is defined. A variable may also have values, which are established later in data mode. <P>
 Ordinarily, <A NAME=MARKER-2-2438></A><A NAME=MARKER-2-2439></A><A NAME=MARKER-2-2440></A><A NAME=MARKER-2-2441></A><A NAME=MARKER-2-2442></A><A NAME=MARKER-2-2443></A>the name, type, and shape are fixed when the variable is first defined. The name may be changed, but the type and shape of a variable cannot be changed. However, a variable defined in terms of the unlimited dimension can grow without bound in that dimension. <P>
 A <A NAME=MARKER-2-2444></A><A NAME=MARKER-2-2445></A>netCDF variable in an open netCDF dataset is referred to by a small integer called a <I>variable ID</I>.<P>
 Variable IDs reflect the order in which variables were defined within a netCDF dataset. Variable IDs are <A NAME=MARKER-10-2446></A>1, <A NAME=MARKER-10-2447></A>2, <A NAME=MARKER-10-2448></A>3,..., in the order in which the variables were defined. A function is available for getting the variable ID from the variable name and vice-versa. <P>
 Attributes (<A HREF=guidef-13.html#MARKER-9-2903>see Chapter 8 "Attributes,"  page 81</A>) may be associated with a variable to specify such properties as units.<P>
 Operations supported on variables are:<P>
<UL>
<LI>Create a variable, given its name, data type, and shape.<P>
<LI>Get a variable ID from its name.<P>
<LI>Get a variable's name, data type, shape, and number of attributes from its ID.<P>
<LI>Put a data value into a variable, given variable ID, indices, and value.<P>
<LI>Put an array of values into a variable, given variable ID, corner indices, edge lengths, and a block of values.<P>
<LI>Put a subsampled or mapped array-section of values into a variable, given variable ID, corner indices, edge lengths, stride vector, index mapping vector, and a block of values.<P>
<LI>Get a data value from a variable, given variable ID and indices.<P>
<LI>Get an array of values from a variable, given variable ID, corner indices, and edge lengths.<P>
<LI>Get a subsampled or mapped array-section of values from a variable, given variable ID, corner indices, edge lengths, stride vector, and index mapping vector.<P>
<LI>Rename a variable.<P>
</UL>
<A NAME=HEADING12-17></A>
<H2>7.1  Language Types Corresponding to netCDF external data types</H2>
<HR>
 The <A NAME=MARKER-2-2459></A><A NAME=MARKER-2-2460></A><A NAME=MARKER-2-2461></A><A NAME=MARKER-2-2462></A><A NAME=MARKER-2-2463></A><A NAME=MARKER-2-2464></A><A NAME=MARKER-2-2465></A><A NAME=MARKER-2-2466></A>following table gives the netCDF external data types and the corresponding type constants for defining variables in the <A NAME=MARKER-10-2467></A>FORTRAN interface:<P>
 
<TABLE BORDER="1"><TH><B>netCDF/CDL Data Type</B><TH><B>FORTRAN API Mnemonic</B><TH><B>Bits</B><TR>
<TD><CODE>byte</CODE><TD><CODE><A NAME=MARKER-10-129></A><A NAME=MARKER-2-130></A>NF_BYTE </CODE><TD>8<TR>
<TD><CODE>char</CODE><TD><CODE><A NAME=MARKER-10-131></A><A NAME=MARKER-2-132></A>NF_CHAR </CODE><TD>8<TR>
<TD><CODE>short</CODE><TD><CODE><A NAME=MARKER-10-133></A><A NAME=MARKER-2-134></A>NF_SHORT </CODE><TD>16<TR>
<TD><CODE>int</CODE><TD><CODE><A NAME=MARKER-10-135></A><A NAME=MARKER-2-136></A>NF_INT </CODE><TD>32<TR>
<TD><CODE>float</CODE><TD><CODE><A NAME=MARKER-10-137></A><A NAME=MARKER-2-138></A>NF_FLOAT </CODE><TD>32<TR>
<TD><CODE>double</CODE><TD><CODE><A NAME=MARKER-10-139></A><A NAME=MARKER-2-140></A>NF_DOUBLE </CODE><TD>64</TABLE>
<P>
 The first column gives the netCDF external data type, which is the same as the CDL data type. The next column gives the corresponding <A NAME=MARKER-10-2468></A>FORTRAN parameter for use in netCDF functions <A NAME=MARKER-10-2469></A>(the parameters are defined in the netCDF FORTRAN include-file <CODE>netcdf.inc</CODE>). The last column gives the number of bits used in the external representation of values of the corresponding type.<P>
 Note that there are no netCDF types corresponding to 64-bit integers or to characters wider than 8 bits in the current version of the netCDF library. <P>
<A NAME=HEADING12-22></A>
<H2>7.2  Create a Variable: <A NAME=MARKER-10-2470></A><CODE><A NAME=MARKER-2-2471></A>NF_DEF_VAR </CODE></H2>
<HR>
 The <A NAME=MARKER-2-2472></A><A NAME=MARKER-2-2473></A><A NAME=MARKER-2-2474></A>function <A NAME=MARKER-10-2475></A><CODE>NF_DEF_VAR</CODE> adds a new variable to an open netCDF dataset in define mode. It returns (as an argument) a variable ID, given the netCDF ID, the variable name, the variable type, the number of dimensions, and a list of the dimension IDs. <P>
<A NAME=HEADING12-24></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2476></A>INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
                            INTEGER XTYPE, INTEGER NVDIMS,
                            INTEGER VDIMS(*), INTEGER varid)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>NAME</CODE><TD>Name for this variable. Must begin with an alphabetic character, which is followed by zero or more alphanumeric characters including the underscore ('<CODE>_</CODE>'). Case is significant.<TR>
<TD><CODE>XTYPE</CODE><TD>The external type for this variable, one of the set of predefined netCDF external data types: <CODE>NF_BYTE</CODE>, <CODE>NF_CHAR</CODE>, <CODE>NF_SHORT</CODE>, <CODE>NF_INT</CODE>, <CODE>NF_FLOAT</CODE>, or <CODE>NF_DOUBLE</CODE>.<TR>
<TD><CODE>NVDIMS</CODE><TD>Number of dimensions for this variable. For example, <CODE>2</CODE> specifies a matrix, <CODE>1</CODE> specifies a vector, and <CODE>0</CODE> means the variable is a scalar with no dimensions. Must not be negative or greater than the predefined constant <CODE>NF_MAX_VAR_DIMS</CODE>.<TR>
<TD><CODE>VDIMS</CODE><TD>Vector of <CODE>NVDIMS</CODE> dimension IDs corresponding to this variable's dimensions. If the ID of the unlimited dimension is included, it must be last. This argument is ignored if <CODE>NVDIMS</CODE> is <CODE>0</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Returned variable ID</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2477></A>NF_DEF_VAR</CODE> returns the value <A NAME=MARKER-10-2478></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include: <P>
<UL>
<LI>The netCDF dataset is not in define mode.<P>
<LI>The specified variable name is the name of another existing variable.<P>
<LI>The specified type is not a valid netCDF type.<P>
<LI>The <A NAME=MARKER-2-2482></A><A NAME=MARKER-2-2483></A><A NAME=MARKER-2-2484></A><A NAME=MARKER-2-2485></A><A NAME=MARKER-2-2486></A><A NAME=MARKER-2-2487></A><A NAME=MARKER-2-2488></A>specified number of dimensions is negative or more than the constant <CODE><A NAME=MARKER-10-2489></A>NF_MAX_VAR_DIMS</CODE>, the maximum number of dimensions permitted for a netCDF variable. <P>
<LI>One <A NAME=MARKER-2-2490></A><A NAME=MARKER-2-2491></A>or more of the dimension IDs in the list of dimensions is not a valid dimension ID for the netCDF dataset.<P>
<LI>The <A NAME=MARKER-2-2492></A><A NAME=MARKER-2-2493></A>number of variables would exceed the constant <A NAME=MARKER-10-2494></A><CODE><A NAME=MARKER-2-2495></A>NF_MAX_VARS</CODE>, the maximum number of variables permitted in a netCDF dataset. <P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-37></A>
<H4>Example </H4>
 Here <A NAME=MARKER-10-2496></A>is an example using <A NAME=MARKER-10-2497></A><CODE>NF_DEF_VAR</CODE> to create a variable named <CODE>rh</CODE> of type <CODE>double</CODE> with three dimensions, <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE> in a new netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2498></A>INCLUDE 'netcdf.inc'
   ... 
INTEGER  STATUS, NCID
INTEGER  LATDIM, LONDIM, TIMDIM  ! dimension IDs
INTEGER  RHID                    ! variable ID
INTEGER  RHDIMS(3)               ! variable shape
   ... 
STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
   ... 
                                 ! define dimensions
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)
         ... 
                                 ! define variable
RHDIMS(1) = LONDIM
RHDIMS(2) = LATDIM
RHDIMS(3) = TIMDIM
STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-63></A>
<H2>7.3  <A NAME=MARKER-2-2499></A>Get a Variable ID from Its Name: <A NAME=MARKER-10-2500></A><CODE><A NAME=MARKER-2-2501></A>NF_INQ_VARID </CODE></H2>
<HR>
 The function <A NAME=MARKER-10-2502></A><CODE>NF_INQ_VARID</CODE> returns the ID of a netCDF variable, given its name.<P>
<A NAME=HEADING12-65></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2503></A>INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME, 
                              INTEGER varid)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>NAME</CODE><TD>Variable name for which ID is desired.<TR>
<TD><CODE>varid</CODE><TD>Returned variable ID.</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2504></A>NF_INQ_VARID</CODE> returns the value <A NAME=MARKER-10-2505></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The specified variable name is not a valid name for a variable in the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-72></A>
<H4>Example </H4>
 Here <A NAME=MARKER-10-2507></A>is an example using <A NAME=MARKER-10-2508></A><CODE>NF_INQ_VARID</CODE> to find out the ID of a variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2509></A>INCLUDE 'netcdf.inc'
   ... 
INTEGER  STATUS, NCID, RHID
   ... 
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)
</PRE>
<A NAME=HEADING12-83></A>
<H2>7.4  Get Information about a Variable from Its ID: <A NAME=MARKER-10-2510></A><CODE><A NAME=MARKER-2-2511></A>NF_INQ_VAR</CODE> family</H2>
<HR>
 A <A NAME=MARKER-2-2512></A><A NAME=MARKER-2-2513></A><A NAME=MARKER-2-2514></A><A NAME=MARKER-2-2515></A><A NAME=MARKER-2-2516></A><A NAME=MARKER-2-2517></A><A NAME=MARKER-2-2518></A><A NAME=MARKER-2-2519></A><A NAME=MARKER-2-2520></A><A NAME=MARKER-2-2521></A><A NAME=MARKER-2-2522></A><A NAME=MARKER-2-2523></A><A NAME=MARKER-2-2524></A><A NAME=MARKER-2-2525></A>family of functions that returns information about a netCDF variable, given its ID. Information about a variable includes its name, type, number of dimensions, a list of dimension IDs describing the shape of the variable, and the number of variable attributes that have been assigned to the variable. <P>
 The function <A NAME=MARKER-10-2526></A><CODE>NF_INQ_VAR</CODE> returns all the information about a netCDF variable, given its ID. The other functions each return just one item of information about a variable. <P>
 These other functions include <A NAME=MARKER-10-2527></A><CODE><A NAME=MARKER-2-2528></A>NF_INQ_VARNAME</CODE>,<A NAME=MARKER-10-2529></A> <CODE><A NAME=MARKER-10-2530></A>NF_INQ_VARTYPE</CODE>, <A NAME=MARKER-10-2531></A><CODE><A NAME=MARKER-2-2532></A>NF_INQ_VARNDIMS</CODE>, <CODE><A NAME=MARKER-10-2533></A><A NAME=MARKER-2-2534></A>NF_INQ_VARDIMID</CODE>, and<A NAME=MARKER-10-2535></A> <A NAME=MARKER-10-2536></A><CODE><A NAME=MARKER-2-2537></A>NF_INQ_VARNATTS</CODE>. <P>
<A NAME=HEADING12-87></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2538></A>INTEGER FUNCTION NF_INQ_VAR      (INTEGER NCID, INTEGER VARID,
                                  CHARACTER*(*) name, INTEGER xtype,
                                  INTEGER ndims, INTEGER dimids(*),
                                  INTEGER natts)
INTEGER FUNCTION NF_INQ_VARNAME  (INTEGER NCID, INTEGER VARID, 
                                  CHARACTER*(*) name)
INTEGER FUNCTION <A NAME=MARKER-2-2539></A>NF_INQ_VARTYPE  (INTEGER NCID, INTEGER VARID, 
                                  INTEGER xtype)
INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID, 
                                  INTEGER ndims)
INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID, 
                                  INTEGER dimids(*))
INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID, 
                                  INTEGER natts)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>name</CODE><TD>Returned <A NAME=MARKER-2-172></A><A NAME=MARKER-2-173></A><A NAME=MARKER-2-174></A>variable name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a variable name is given by the predefined constant <CODE>NF_MAX_NAME</CODE>.<TR>
<TD><CODE>xtype</CODE><TD>Returned external type for this variable, one of the set of predefined netCDF external data types. The valid netCDF external data types are <CODE>NF_BYTE</CODE>, <CODE>NF_CHAR</CODE>, <CODE>NF_SHORT</CODE>, <CODE>NF_INT</CODE>, <CODE>NF_FLOAT</CODE>, and <CODE>NF_DOUBLE</CODE>.<TR>
<TD><CODE>ndims</CODE><TD>Returned number of dimensions for this variable. For example, <CODE>2 </CODE>indicates a matrix, <CODE>1</CODE> indicates a vector, and <CODE>0</CODE> means the variable is a scalar with no dimensions.<TR>
<TD><CODE>dimids</CODE><TD>Returned <A NAME=MARKER-2-179></A>vector of <CODE>NDIMS</CODE> dimension IDs corresponding to the variable dimensions. The caller must allocate enough space for a vector of at least <CODE>NDIMS</CODE> integers to be returned. The maximum possible number of dimensions for a variable is given by the predefined constant <CODE><A NAME=MARKER-2-180></A>NF_MAX_VAR_DIMS</CODE>.<TR>
<TD><CODE>natts</CODE><TD>Returned number of variable attributes assigned to this variable.</TABLE>

</PRE>
Errors <P>
 These functions return the value <A NAME=MARKER-10-2540></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-106></A>
<H4>Example </H4>
 Here <A NAME=MARKER-10-2542></A>is an example using <A NAME=MARKER-10-2543></A><CODE>NF_INQ_VAR</CODE> to find out about a variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2544></A>INCLUDE 'netcdf.inc'
   ... 
INTEGER  STATUS, NCID
INTEGER  RHID               ! variable ID
CHARACTER*31 RHNAME         ! variable name
INTEGER  RHTYPE             ! variable type
INTEGER  RHN                ! number of dimensions
INTEGER  RHDIMS(NF_MAX_VAR_DIMS)   ! variable shape
INTEGER  RHNATT                    ! number of attributes
   ... 
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)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-125></A>
<H2>7.5  Write a Single Data Value: <A NAME=MARKER-10-2545></A><CODE><A NAME=MARKER-2-2546></A>NF_PUT_VAR1_<I>type </I></CODE></H2>
<HR>
 The <A NAME=MARKER-2-2547></A><A NAME=MARKER-2-2548></A><A NAME=MARKER-2-2549></A><A NAME=MARKER-2-2550></A>functions <A NAME=MARKER-10-2551></A><CODE>NF_PUT_VAR1_<B>type</B></CODE> put a single data value of the specified <B>type</B> into a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, an index that specifies which value to add or alter, and the data value. The value is converted to the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-127></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2552></A>INTEGER FUNCTION  NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), CHARACTER CHVAL)
INTEGER FUNCTION  NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER*1 I1VAL)
INTEGER FUNCTION  NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER*2 I2VAL)
INTEGER FUNCTION  NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER   IVAL)
INTEGER FUNCTION  NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), REAL      RVAL)
INTEGER FUNCTION  NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), DOUBLE    DVAL) 
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>INDEX</CODE><TD>The index of the data value to be written. The indices are relative to 1, so for example, the first data value of a two-dimensional variable would have index <CODE>(1,1)</CODE>. The elements of <CODE>index</CODE> must correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the record number.<TR>
<TD><CODE>CHVAL, I1VAL, I2VAL, IVAL, RVAL, </CODE>or<CODE> DVAL</CODE><TD>The data value to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 24, for details.</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2553></A>NF_PUT_VAR1_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2554></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified value is out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-147></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2556></A>Here <A NAME=MARKER-2-2557></A>is an example using <CODE>NF_PUT_VAR1_DOUBLE</CODE> to set the <CODE>(4,3,2)</CODE> element of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, so we want to set the value of <CODE>rh</CODE> that corresponds to the fourth <CODE>lon</CODE> value, the third <CODE>lat</CODE> value, and the second <CODE>time</CODE> value: <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
INTEGER  STATUS             ! error status
INTEGER  NCID
INTEGER  RHID               ! variable ID
INTEGER  RHINDX(3)          ! where to put value
DATA RHINDX /4, 3, 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)  ! get ID
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-164></A>
<H2>7.6  <A NAME=MARKER-2-2558></A><A NAME=MARKER-2-2559></A><A NAME=MARKER-2-2560></A><A NAME=MARKER-2-2561></A>Write an Entire Variable: <A NAME=MARKER-10-2562></A><CODE><A NAME=MARKER-2-2563></A>NF_PUT_VAR_<I>type </I></CODE></H2>
<HR>
 The <A NAME=MARKER-10-2564></A><CODE>NF_PUT_VAR_<B>type</B></CODE> family of functions write all the values of a variable into a netCDF variable of an open netCDF dataset. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once. The values to be written are associated with the netCDF variable by assuming that the <A NAME=MARKER-10-2565></A>first dimension of the netCDF variable varies fastest in the <A NAME=MARKER-10-2566></A>FORTRAN interface. The values are converted to the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-166></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2567></A>INTEGER FUNCTION NF_PUT_VAR_TEXT  (INTEGER NCID, INTEGER VARID,
                                   CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VAR_INT1  (INTEGER NCID, INTEGER VARID,
                                   INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VAR_INT2  (INTEGER NCID, INTEGER VARID,
                                   INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VAR_INT   (INTEGER NCID, INTEGER VARID,
                                   INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VAR_REAL  (INTEGER NCID, INTEGER VARID,
                                   REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
                                   DOUBLE DVALS(*))
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>TEXT, I1VALS, 
I2VALS, IVALS,RVALS, or DVALS</CODE><TD>The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details). The order in which the data will be written into the specified variable is with the first dimension varying fastest (like the ordinary FORTRAN convention).</TABLE>

</PRE>
Errors <P>
 Members of the <A NAME=MARKER-10-2568></A><CODE>NF_PUT_VAR_<B>type</B></CODE> family return the value <A NAME=MARKER-10-2569></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF dataset is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-186></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2571></A>Here is an example using <CODE>NF_PUT_VAR_DOUBLE</CODE> to add or change all the values of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, and that there are ten <CODE>lon</CODE> values, five <CODE>lat</CODE> values, and three <CODE>time</CODE> values. <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER  STATUS, NCID, TIMES
INTEGER  RHID                        ! variable ID
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)
DO 10 ILON = 1, LONS
   DO 10 ILAT = 1, LATS
      DO 10 ITIME = 1, TIMES
         RHVALS(ILON, ILAT, ITIME) = 0.5
10 CONTINUE
STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-207></A>
<H2>7.7  <A NAME=MARKER-2-2573></A><A NAME=MARKER-2-2574></A><A NAME=MARKER-2-2575></A><A NAME=MARKER-2-2576></A>Write an Array of Values: <A NAME=MARKER-10-2577></A><CODE><A NAME=MARKER-2-2578></A>NF_PUT_VARA<I>_type </I></CODE></H2>
<HR>
 The function <A NAME=MARKER-10-2579></A><CODE>NF_PUT_VARA_<B>type</B></CODE> writes values into a netCDF variable of an open netCDF dataset. The part of the netCDF variable to write is specified by giving a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The values to be written are associated with the netCDF variable by assuming that the <A NAME=MARKER-10-2580></A>first dimension of the netCDF variable varies fastest in the <A NAME=MARKER-10-2581></A>FORTRAN interface. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-209></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2582></A>INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  DOUBLE DVALS(*)) 
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The length of <CODE>START</CODE> must be the same as the number of dimensions of the specified variable. The elements of <CODE>START</CODE> must correspond to the variable's dimensions in order. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the edge lengths along each dimension of the block of data values to written. To write a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The length of <CODE>COUNT</CODE> is the number of dimensions of the specified variable. The elements of <CODE>COUNT </CODE>correspond to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>TEXT, I1VALS, 
I2VALS, IVALS,RVALS, or DVALS</CODE><TD>The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2583></A>NF_PUT_VARA_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2584></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified corner indices were out of range for the rank of the specified variable. For example, a negative index, or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error. <P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF dataset is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-236></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2586></A>Here <A NAME=MARKER-2-2587></A>is an example using <CODE>NF_PUT_VARA_DOUBLE</CODE> to add or change all the values of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, and that there are ten <CODE>lon</CODE> values, five <CODE>lat</CODE> values, and three <CODE>time</CODE> values. <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIMS=3)         ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER  STATUS, NCID, TIMES
INTEGER  RHID               ! variable ID
INTEGER  START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/        ! start at first value
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)
DO 10 ILON = 1, LONS
   DO 10 ILAT = 1, LATS
      DO 10 ITIME = 1, TIMES
         RHVALS(ILON, ILAT, ITIME) = 0.5
10 CONTINUE
STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-261></A>
<H2>7.8  <A NAME=MARKER-2-2588></A><A NAME=MARKER-2-2589></A><A NAME=MARKER-2-2590></A><A NAME=MARKER-2-2591></A>Write a Subsampled Array of Values: <A NAME=MARKER-10-2592></A><CODE><A NAME=MARKER-2-2593></A>NF_PUT_VARS_<B>type </B></CODE></H2>
<HR>
 Each member of the family of functions <A NAME=MARKER-10-2594></A><CODE>NF_PUT_VARS_<B>type</B></CODE> writes a subsampled (strided) array section of values into a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-263></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2597></A>INTEGER FUNCTION NF_PUT_VARS_TEXT  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),CHARACTER*(*) TEXT)
INTEGER FUNCTION NF_PUT_VARS_INT1  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF_PUT_VARS_INT2  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF_PUT_VARS_INT   (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IVALS(*))
INTEGER FUNCTION NF_PUT_VARS_REAL  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),  REAL RVALS(*))
INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),  DOUBLE DVALS(*))
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>START</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the number of indices selected along each dimension. To write a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>COUNT</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>STRIDE</CODE><TD>A vector of integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (STRIDE(1) gives the sampling interval along the most rapidly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.).<TR>
<TD><CODE>TEXT, I1VALS, 
I2VALS, IVALS,RVALS, or DVALS</CODE><TD>The block of data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2598></A>NF_PUT_VARS_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2599></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified start, count and stride generate an index which is out of range.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-289></A>
<H4>Example </H4>
 Here is an example of using <A NAME=MARKER-10-2601></A><CODE>NF_PUT_VARS_REAL</CODE> to write -- from an internal array -- every other point of a netCDF variable named <CODE>rh</CODE> which is described by the <A NAME=MARKER-10-2602></A>FORTRAN declaration <A NAME=MARKER-10-2603></A><CODE>REAL RH(6,4)</CODE> (note the size of the dimensions):<P>
<PRE>
<A NAME=MARKER-10-2604></A>INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIM=2)   ! rank of netCDF variable
INTEGER NCID         ! netCDF dataset ID
INTEGER STATUS       ! return code
INTEGER RHID         ! variable ID
INTEGER START(NDIM)  ! netCDF variable start point
INTEGER COUNT(NDIM)  ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
REAL RH(3,2)         ! note subsampled sizes for netCDF variable
                     ! dimensions
DATA START   /1, 1/  ! start at first netCDF variable value
DATA COUNT   /3, 2/  ! size of internal array: entire (subsampled)
                     ! netCDF variable
DATA STRIDE /2, 2/   ! access every other netCDF element
   ... 
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)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-315></A>
<H2>7.9  <A NAME=MARKER-9-2605></A>Write a Mapped Array of Values: <A NAME=MARKER-10-2606></A><CODE><A NAME=MARKER-2-2607></A>NF_PUT_VARM_type </CODE></H2>
<HR>
 The <A NAME=MARKER-10-2608></A><CODE>NF_PUT_VARM_<B>type</B></CODE> <A NAME=MARKER-2-2609></A><A NAME=MARKER-2-2610></A><A NAME=MARKER-2-2611></A><A NAME=MARKER-2-2612></A>family of functions writes a mapped array section of values into a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of counts, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-317></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2621></A>INTEGER FUNCTION NF _PUT_VARM_TEXT  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            CHARACTER*(*) TEXT)
INTEGER FUNCTION NF _PUT_VARM_INT1  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER*1 I1VALS(*))
INTEGER FUNCTION NF _PUT_VARM_INT2  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER*2 I2VALS(*))
INTEGER FUNCTION NF _PUT_VARM_INT   (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER IVALS(*))
INTEGER FUNCTION NF _PUT_VARM_REAL  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            REAL RVALS(*))
INTEGER FUNCTION NF _PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            DOUBLE DVALS(*))
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>START</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for writing the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the number of indices selected along each dimension. To write a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>COUNT</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>STRIDE</CODE><TD>A vector of integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (STRIDE(1) gives the sampling interval along the most rapidly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.).<TR>
<TD><CODE>IMAP</CODE><TD>A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable's dimensions (IMAP(1) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable). Distances between elements are specified in units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2). <TR>
<TD><CODE>TEXT, I1VALS, 
I2VALS, IVALS,RVALS, or DVALS</CODE><TD>The data values to be written. The data should be of the type appropriate for the function called. You cannot put CHARACTER data into a numeric variable or numeric data into a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2622></A>NF_PUT_VARM_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2623></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified <A NAME=MARKER-10-2625></A><CODE>START</CODE>, <A NAME=MARKER-10-2626></A><CODE>COUNT</CODE>, and <A NAME=MARKER-10-2627></A><CODE>STRIDE</CODE> generate an index which is out of range. Note that no error checking is possible on the <A NAME=MARKER-10-2628></A><CODE>IMAP</CODE> vector.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-349></A>
<H4>Example </H4>
 The following <A NAME=MARKER-10-2629></A><CODE>IMAP</CODE> vector maps in the trivial way a <A NAME=MARKER-10-2630></A>2x3x4 netCDF variable and an internal array of the same shape: <P>
<PRE>
<A NAME=MARKER-10-2631></A>REAL A(2,3,4)       ! same shape as netCDF variable
INTEGER IMAP(3)
DATA IMAP /1, 2, 6/ ! netCDF dimension       inter-element distance
                    ! ----------------       ----------------------
                    ! most rapidly varying       1
                    ! intermediate               2 (=IMAP(1)*2)
                    ! most slowly varying        6 (=IMAP(2)*3)
</PRE>
 Using the <A NAME=MARKER-10-2632></A><CODE>IMAP</CODE> vector above with <A NAME=MARKER-10-2633></A><CODE>NF_PUT_VARM_REAL</CODE> obtains the same result as simply using <A NAME=MARKER-10-2634></A><CODE>NF_PUT_VAR_REAL</CODE>.<P>
 Here is an example of using <A NAME=MARKER-10-2635></A><CODE>NF_PUT_VARM_REAL</CODE> to write -- from a transposed, internal array -- a netCDF variable named <CODE>rh</CODE> which is described by the <A NAME=MARKER-10-2636></A>FORTRAN declaration <A NAME=MARKER-10-2637></A><CODE>REAL RH(4,6)</CODE> (note the size and order of the dimensions):<P>
<PRE>
<A NAME=MARKER-10-2638></A>INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIM=2)   ! rank of netCDF variable
INTEGER NCID         ! netCDF ID
INTEGER STATUS       ! return code
INTEGER RHID         ! variable ID
INTEGER START(NDIM)  ! netCDF variable start point
INTEGER COUNT(NDIM)  ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM)   ! internal array inter-element distances
REAL RH(6,4)         ! note transposition of netCDF variable dimensions
DATA START   /1, 1/  ! start at first netCDF variable element
DATA COUNT   /4, 6/  ! entire netCDF variable; order corresponds
                     ! to netCDF variable -- not internal array
DATA STRIDE /1, 1/   ! sample every netCDF element
DATA IMAP   /6, 1/   ! would be /1, 4/ if not transposing

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)
</PRE>
 Here is another example of using <A NAME=MARKER-10-2639></A><CODE>NF_PUT_VARM_REAL</CODE> to write -- from a transposed, internal array -- a subsample of the same netCDF variable, by writing every other point of the netCDF variable:<P>
<PRE>
<A NAME=MARKER-10-2640></A>INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIM=2)   ! rank of netCDF variable
INTEGER NCID         ! netCDF dataset ID
INTEGER STATUS       ! return code
INTEGER RHID         ! variable ID
INTEGER START(NDIM)  ! netCDF variable start point
INTEGER COUNT(NDIM)  ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM)   ! internal array inter-element distances
REAL RH(3,2)         ! note transposition of (subsampled) dimensions
DATA START   /1, 1/  ! start at first netCDF variable value
DATA COUNT   /2, 3/  ! order of (subsampled) dimensions corresponds
                     ! to netCDF variable -- not internal array
DATA STRIDE /2, 2/   ! sample every other netCDF element
DATA IMAP   /3, 1/   ! would be `1, 2' if not transposing
   ... 
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)
</PRE>
<A NAME=HEADING12-411></A>
<H2>7.10  Read a Single Data Value: <A NAME=MARKER-10-2641></A><CODE><A NAME=MARKER-2-2642></A>NF_GET_VAR1_<I>type </I></CODE></H2>
<HR>
 The <A NAME=MARKER-2-2643></A><A NAME=MARKER-2-2644></A><A NAME=MARKER-2-2645></A><A NAME=MARKER-2-2646></A>functions <A NAME=MARKER-10-2647></A><CODE>NF_GET_VAR1_<B>type</B></CODE> get a single data value from a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to get, and the address of a location into which the data value will be read. The value is converted from the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-413></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2648></A>INTEGER FUNCTION  NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), CHARACTER chval)
INTEGER FUNCTION  NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER*1 i1val)
INTEGER FUNCTION  NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER*2 i2val)
INTEGER FUNCTION  NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), INTEGER   ival)
INTEGER FUNCTION  NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), REAL      rval)
INTEGER FUNCTION  NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
                                   INTEGER INDEX(*), DOUBLE    dval)

<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>INDEX</CODE><TD>The index of the data value to be read. The indices are relative to 1, so for example, the first data value of a two-dimensional variable has index <CODE>(1,1)</CODE>. The elements of <CODE>index</CODE> correspond to the variable's dimensions. Hence, if the variable is a record variable, the last index is the record number. <TR>
<TD><CODE>chval, i1val, i2val, ival, rval, </CODE>or<CODE> dval</CODE><P>&nbsp;<TD>The location into which the data value will be read. You cannot get CHARACTER data from a numeric variable or numeric data from a character variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur. See Section 3.3 "Type Conversion," page 24, for details.<P>&nbsp;</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2649></A>NF_GET_VAR1_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2650></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error.<P>
<LI>The value is out of the range of values representable by the desired data type. <P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-434></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2652></A>Here <A NAME=MARKER-2-2653></A>is an example using <CODE>NF_GET_VAR1_DOUBLE</CODE> to get the <CODE>(4,3,2)</CODE> element of the variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, so we want to get the value of <CODE>rh</CODE> that corresponds to the fourth <CODE>lon</CODE> value, the third <CODE>lat</CODE> value, and the second <CODE>time</CODE> value: <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
INTEGER STATUS, NCID
INTEGER RHID           ! variable ID
INTEGER RHINDX(3)      ! where to get value
DOUBLE PRECISION RHVAL ! put it here
DATA RHINDX /4, 3, 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_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-451></A>
<H2>7.11  Read an Entire Variable <A NAME=MARKER-10-2654></A><CODE><A NAME=MARKER-2-2655></A>NF_GET_VAR_<I>type </I></CODE></H2>
<HR>
 The <A NAME=MARKER-2-2656></A><A NAME=MARKER-2-2657></A><A NAME=MARKER-2-2658></A>members of the <A NAME=MARKER-10-2659></A><CODE>NF_GET_VAR_<B>type</B></CODE> family of functions read all the values from a netCDF variable of an open netCDF dataset. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once. The values are read into consecutive locations with the <A NAME=MARKER-10-2660></A>first dimension varying fastest. The netCDF dataset must be in data mode.<P>
<A NAME=HEADING12-453></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2661></A>INTEGER FUNCTION NF_GET_VAR_TEXT  (INTEGER NCID, INTEGER VARID,
                                   CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VAR_INT1  (INTEGER NCID, INTEGER VARID,
                                   INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VAR_INT2  (INTEGER NCID, INTEGER VARID,
                                   INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VAR_INT   (INTEGER NCID, INTEGER VARID,
                                   INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VAR_REAL  (INTEGER NCID, INTEGER VARID,
                                   REAL rvals(*))
INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
                                   DOUBLE dvals(*))
</PRE>
 There are six FORTRAN functions for reading an array of values from a netCDF variable. 
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>text, i1vals, <BR>i2vals, ivals,rvals, or dvals</CODE><TD>The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>
<P>
Errors <P>
 <CODE><A NAME=MARKER-10-2662></A>NF_GET_VAR_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2663></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-473></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2665></A>Here is an example using <CODE>NF_GET_VAR_DOUBLE</CODE> to read all the values of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, and that there are ten <CODE>lon</CODE> values, five <CODE>lat </CODE>values, and three <CODE>time</CODE> values. <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID                         ! variable ID
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)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
 <P>
<A NAME=HEADING12-490></A>
<H2>7.12  Read an Array of Values: <A NAME=MARKER-10-2667></A><CODE><A NAME=MARKER-2-2668></A>NF_GET_VARA_<I>type </I></CODE></H2>
<HR>
 The <A NAME=MARKER-2-2669></A><A NAME=MARKER-2-2670></A><A NAME=MARKER-2-2671></A><A NAME=MARKER-2-2672></A>members of the <A NAME=MARKER-10-2673></A><CODE>NF_GET_VARA_<B>type</B></CODE> family of functions read an array of values from a netCDF variable of an open netCDF dataset. The array is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the <A NAME=MARKER-10-2674></A>first dimension varying fastest. The netCDF dataset must be in data mode.<P>
<A NAME=HEADING12-492></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2675></A>INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  CHARACTER*(*) text)
INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER*1 i1vals(*))
INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER*2 i2vals(*))
INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  INTEGER ivals(*))
INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  REAL rvals(*))
INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
                                  INTEGER START(*), INTEGER COUNT(*),
                                  DOUBLE dvals(*))
</PRE>
 There are six FORTRAN functions for reading an array of values from a netCDF variable. 
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The length of <CODE>START</CODE> must be the same as the number of dimensions of the specified variable. The elements of <CODE>START</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the edge lengths along each dimension of the block of data values to be read. To read a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The length of <CODE>COUNT</CODE> is the number of dimensions of the specified variable. The elements of <CODE>COUNT </CODE>correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>text, i1vals, <BR>i2vals, ivals,rvals, or dvals</CODE><TD>The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>
<P>
Errors <P>
 <CODE><A NAME=MARKER-10-2676></A>NF_GET_VARA_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2677></A><CODE><A NAME=MARKER-2-2744></A>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified corner indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error. <P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-520></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2745></A>Here is an example using <A NAME=MARKER-2-2746></A><CODE>NF_GET_VARA_DOUBLE</CODE> to read all the values of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, and that there are ten <CODE>lon</CODE> values, five <CODE>lat </CODE>values, and three <CODE>time</CODE> values. <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIMS=3)                  ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID                         ! variable ID
INTEGER START(NDIMS), COUNT(NDIMS)
DOUBLE RHVALS(LONS, LATS, TIMES)
DATA START /1, 1, 1/                 ! start at first value
DATA COUNT /LONS, LATS, TIMES/       ! get all the values
   ... 
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)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-540></A>
<H2>7.13  Read a Subsampled Array of Values: <A NAME=MARKER-10-2747></A><CODE>NF_GET_VARS_<I>type </I></CODE></H2>
<HR>
 <A NAME=MARKER-2-2749></A><A NAME=MARKER-2-2750></A><A NAME=MARKER-2-2751></A><A NAME=MARKER-2-2752></A><A NAME=MARKER-2-2753></A>The <A NAME=MARKER-10-2754></A><CODE>NF_GET_VARS_<B>type</B></CODE> family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the <A NAME=MARKER-10-2757></A>first dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-542></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2758></A>INTEGER FUNCTION <A NAME=MARKER-2-2759></A>NF_GET_VARS_TEXT  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),CHARACTER*(*) text)
INTEGER FUNCTION <A NAME=MARKER-2-2760></A>NF_GET_VARS_INT1  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),INTEGER*1 i1vals(*))
INTEGER FUNCTION <A NAME=MARKER-2-2761></A>NF_GET_VARS_INT2  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*),INTEGER*2 i2vals(*))
INTEGER FUNCTION <A NAME=MARKER-2-2762></A>NF_GET_VARS_INT   (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER ivals(*))
INTEGER FUNCTION <A NAME=MARKER-2-2763></A>NF_GET_VARS_REAL  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), REAL rvals(*))
INTEGER FUNCTION <A NAME=MARKER-2-2764></A>NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), DOUBLE dvals(*))
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable from which the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>START</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the number of indices selected along each dimension. To read a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>COUNT</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>STRIDE</CODE><TD>A vector of integers specifying, for each dimension, the interval between selected indices or the value <CODE>0</CODE>. The elements of the vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A <CODE>0</CODE> argument is treated as <CODE>(1, 1, ..., 1)</CODE>. <TR>
<TD><CODE>text, i1vals, 
i2vals, ivals,rvals, or dvals</CODE><TD>The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2765></A>NF_GET_VARS_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2766></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified start, count and stride generate an index which is out of range.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-568></A>
<H4>Example </H4>
 <A NAME=MARKER-10-2768></A>Here is an example using <A NAME=MARKER-2-2769></A><CODE><A NAME=MARKER-10-2770></A>NF_GET_VARS_DOUBLE</CODE> to read every other value in each dimension of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. Values are assigned, using the same dimensional strides, to a 2-parameter array. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>lon</CODE>, <CODE>lat</CODE>, and <CODE>time</CODE>, and that there are ten <CODE>lon</CODE> values, five <CODE>lat </CODE>values, and three <CODE>time</CODE> values. <P>
<PRE>
INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIMS=3)                  ! number of dimensions
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
DOUBLE DATA(LONS, LATS, TIMES)
DATA START /1, 1, 1/                 ! start at first value
DATA COUNT /LONS, LATS, TIMES/
DATA STRIDE /2, 2, 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_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-589></A>
<H2>7.14  Read a Mapped Array of Values: <A NAME=MARKER-10-2771></A><CODE><A NAME=MARKER-2-2772></A>NF_GET_VARM<I>_type<B> </B></I></CODE></H2>
<HR>
 <A NAME=MARKER-2-2773></A><A NAME=MARKER-2-2774></A><A NAME=MARKER-2-2775></A><A NAME=MARKER-2-2776></A><A NAME=MARKER-2-2777></A>The <A NAME=MARKER-10-2778></A><CODE>NF_GET_VARM_<B>type</B></CODE> family of functions reads a mapped array section of values from a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of edge lengths, a <A NAME=MARKER-2-2779></A><A NAME=MARKER-2-2780></A>stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-591></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2787></A>INTEGER FUNCTION NF _GET_VARM_TEXT  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            CHARACTER*(*) text)
INTEGER FUNCTION NF _GET_VARM_INT1  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER*1 i1vals(*))
INTEGER FUNCTION NF _GET_VARM_INT2  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER*2 i2vals(*))
INTEGER FUNCTION NF _GET_VARM_INT   (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            INTEGER ivals(*))
INTEGER FUNCTION NF _GET_VARM_REAL  (INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            REAL rvals(*))
INTEGER FUNCTION NF _GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
                            INTEGER START(*), INTEGER COUNT(*),
                            INTEGER STRIDE(*), INTEGER IMAP(*),
                            DOUBLE dvals(*))
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>START</CODE><TD>A vector of integers specifying the index in the variable from which the first of the data values will be read. The indices are relative to 1, so for example, the first data value of a variable would have index <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>START</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last index would correspond to the starting record number for reading the data values. <TR>
<TD><CODE>COUNT</CODE><TD>A vector of integers specifying the number of indices selected along each dimension. To read a single value, for example, specify <CODE>COUNT</CODE> as <CODE>(1, 1, ..., 1)</CODE>. The elements of <CODE>COUNT</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the last element of <CODE>COUNT</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>STRIDE</CODE><TD>A vector of integers specifying, for each dimension, the interval between selected indices or the value <CODE>0</CODE>. The elements of the vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A <CODE>0</CODE> argument is treated as <CODE>(1, 1, ..., 1)</CODE>. <TR>
<TD><CODE>IMAP</CODE><TD>A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. IMAP(1) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. IMAP(N) (where N is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. Intervening IMAP elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2).<TR>
<TD><CODE>text, i1vals, 
i2vals, ivals,rvals, or dvals</CODE><TD>The block of data values to be read. The data should be of the type appropriate for the function called. You cannot read CHARACTER data from a numeric variable or numeric data from a text variable. For numeric data, if the type of data differs from the netCDF variable type, type conversion will occur (see Section 3.3 "Type Conversion," page 24, for details).</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2788></A>NF_GET_VARM_<B>type</B></CODE> returns the value <A NAME=MARKER-10-2789></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified <A NAME=MARKER-10-2791></A><CODE>START</CODE>, <A NAME=MARKER-10-2792></A><CODE>COUNT</CODE>, and <A NAME=MARKER-10-2793></A><CODE>STRIDE</CODE> generate an index which is out of range. Note that no error checking is possible on the <A NAME=MARKER-10-2794></A><CODE>IMAP</CODE> vector.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-623></A>
<H4>Example </H4>
 The following <A NAME=MARKER-10-2795></A><CODE>IMAP</CODE> vector maps in the trivial way a <A NAME=MARKER-10-2796></A>2x3x4 netCDF variable and an internal array of the same shape: <P>
<PRE>
<A NAME=MARKER-10-2797></A>REAL A(2,3,4)       ! same shape as netCDF variable
INTEGER IMAP(3)
DATA IMAP /1, 2, 6/ ! netCDF dimension       inter-element distance
                    ! ----------------       ----------------------
                    ! most rapidly varying       1
                    ! intermediate               2 (=IMAP(1)*2)
                    ! most slowly varying        6 (=IMAP(2)*3)
</PRE>
 Using the <A NAME=MARKER-10-2798></A><CODE>IMAP</CODE> vector above with <A NAME=MARKER-10-2799></A>NF_GET_VARM_REAL obtains the same result as simply using <A NAME=MARKER-10-2800></A>NF_GET_VAR_REAL.<P>
 Here is an example of using <A NAME=MARKER-10-2801></A><CODE>NF_GET_VARM_REAL</CODE> to transpose a netCDF variable named <CODE>rh</CODE> which is described by the <A NAME=MARKER-10-2802></A>FORTRAN declaration <A NAME=MARKER-10-2803></A><CODE>REAL RH(4,6) </CODE>(note the size and order of the dimensions):<P>
<PRE>
<A NAME=MARKER-10-2804></A>INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIM=2)   ! rank of netCDF variable
INTEGER NCID         ! netCDF dataset ID
INTEGER STATUS       ! return code
INTEGER RHID         ! variable ID
INTEGER START(NDIM)  ! netCDF variable start point
INTEGER COUNT(NDIM)  ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM)   ! internal array inter-element distances
REAL    RH(6,4)      ! note transposition of netCDF variable dimensions
DATA START   /1, 1/  ! start at first netCDF variable element
DATA COUNT   /4, 6/  ! entire netCDF variable; order corresponds
                     ! to netCDF variable -- not internal array
DATA STRIDE /1, 1/   ! sample every netCDF element
DATA IMAP   /6, 1/   ! would be /1, 4/ if not transposing
   ... 
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)
</PRE>
 Here is another example of using <A NAME=MARKER-10-2805></A><CODE>NF_GET_VARM_REAL</CODE> to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:<P>
<PRE>
<A NAME=MARKER-10-2806></A>INCLUDE 'netcdf.inc'
   ... 
PARAMETER (NDIM=2)   ! rank of netCDF variable
INTEGER NCID         ! netCDF dataset ID
INTEGER STATUS       ! return code
INTEGER RHID         ! variable ID
INTEGER START(NDIM)  ! netCDF variable start point
INTEGER COUNT(NDIM)  ! size of internal array
INTEGER STRIDE(NDIM) ! netCDF variable subsampling intervals
INTEGER IMAP(NDIM)   ! internal array inter-element distances
REAL    RH(3,2)      ! note transposition of (subsampled) dimensions
DATA START   /1, 1/  ! start at first netCDF variable value
DATA COUNT   /2, 3/  ! order of (subsampled) dimensions corresponds
                     ! to netCDF variable -- not internal array
DATA STRIDE /2, 2/   ! sample every other netCDF element
DATA IMAP   /3, 1/   ! would be `1, 2' if not transposing
   ... 
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)
</PRE>
<A NAME=HEADING12-685></A>
<H2>7.15  Reading and Writing Character String Values</H2>
<HR>
 <A NAME=MARKER-2-2807></A><A NAME=MARKER-2-2808></A><A NAME=MARKER-2-2810></A><A NAME=MARKER-2-2811></A>Character <A NAME=MARKER-2-2812></A><A NAME=MARKER-2-2813></A><A NAME=MARKER-2-2814></A><A NAME=MARKER-2-2815></A><A NAME=MARKER-2-2816></A>strings <A NAME=MARKER-2-2818></A><A NAME=MARKER-2-2822></A>are not a <A NAME=MARKER-2-2824></A><A NAME=MARKER-2-2825></A><A NAME=MARKER-2-2826></A><A NAME=MARKER-2-2827></A><A NAME=MARKER-2-2828></A><A NAME=MARKER-2-2829></A><A NAME=MARKER-2-2830></A><A NAME=MARKER-2-2831></A><A NAME=MARKER-2-2832></A><A NAME=MARKER-2-2833></A>primitive netCDF external data type, in part because FORTRAN does not support the abstraction of variable-length character strings (the FORTRAN <CODE>LEN</CODE> 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. <P>
 <A NAME=MARKER-2-2836></A><A NAME=MARKER-2-2837></A>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. <P>
 When you define a variable that will have character-string values, use a <I>character-position dimension</I> as the most quickly varying dimension for the variable (the <A NAME=MARKER-10-2843></A>first dimension for the variable in <A NAME=MARKER-10-2844></A>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. <P>
 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 <A NAME=MARKER-10-2845></A>one for <A NAME=MARKER-10-2846></A>FORTRAN. If the length of the string to be written is <CODE>n</CODE>, then the vector of edge lengths will specify <CODE>n</CODE> in the character-position dimension, and one for all the other dimensions:<A NAME=MARKER-10-2847></A><CODE>(n, 1, 1, ..., 1).</CODE> <P>
 <A NAME=MARKER-10-2848></A><A NAME=MARKER-2-2849></A><A NAME=MARKER-2-2854></A><A NAME=MARKER-2-2855></A>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. <P>
 <A NAME=MARKER-2-2856></A><A NAME=MARKER-2-2857></A><A NAME=MARKER-2-2858></A><A NAME=MARKER-2-2859></A><A NAME=MARKER-2-2860></A><A NAME=MARKER-2-2861></A><A NAME=MARKER-2-2862></A><A NAME=MARKER-2-2863></A><A NAME=MARKER-2-2864></A><A NAME=MARKER-2-2865></A>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 <CODE>NF_PUT_VARA_TEXT</CODE> and <CODE>NF_GET_VARA_TEXT</CODE>. The actual length of the string is specified as the value of the edge-length vector corresponding to the character-position dimension. <P>
 Here is an example that defines a record variable, <CODE>tx</CODE>, for character strings and stores a character-string value into the third record using <CODE>NF_PUT_VARA_TEXT</CODE>. In this example, we assume the string variable and data are to be added to an existing netCDF dataset named <CODE>foo.nc</CODE> that already has an unlimited record dimension <CODE>time</CODE>. <P>
<PRE>
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, &quot;chid&quot;, 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, &quot;tx&quot;, 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) = 0      ! 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 = <A NAME=MARKER-2-2866></A>NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL, 40)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING12-734></A>
<H2>7.16  <A NAME=MARKER-9-2867></A>Fill Values</H2>
<HR>
 <A NAME=MARKER-2-2870></A><A NAME=MARKER-2-2871></A>What happens when you try to read a value that was never written in an open netCDF dataset? You might expect that this should always be an error, and that you should get an error message or an error status returned. You <I>do</I> get an error if you try to read data from a netCDF dataset that is not open for reading, if the variable ID is invalid for the specified netCDF dataset, or if the specified indices are not properly within the range defined by the dimension lengths of the specified variable. Otherwise, reading a value that was not written returns a special <I>fill value</I> used to fill in any undefined values when a netCDF variable is first written. <P>
 You may ignore fill values and use the entire range of a netCDF external data type, but in this case you should make sure you write all data values before reading them. If you know you will be writing all the data before reading it, you can specify that no prefilling of variables with fill values will occur by calling <A NAME=MARKER-10-2872></A><CODE><A NAME=MARKER-2-2873></A>NF_SET_FILL </CODE>before writing. This may provide a significant performance gain for netCDF writes. <P>
 The variable attribute <CODE>_FillValue</CODE> may be used to specify the fill value for a variable. Their are <A NAME=MARKER-2-2874></A><A NAME=MARKER-2-2875></A><A NAME=MARKER-2-2876></A>default fill values for each type, defined in the include file <A NAME=MARKER-10-2877></A><CODE>netcdf.inc</CODE>:  <CODE><A NAME=MARKER-10-2878></A><A NAME=MARKER-2-2879></A>NF_FILL_CHAR</CODE>, <CODE><A NAME=MARKER-2-2880></A>NF_FILL_INT1</CODE> (same as <CODE><A NAME=MARKER-2-2881></A>NF_FILL_BYTE</CODE>), <CODE><A NAME=MARKER-2-2882></A>NF_FILL_INT2</CODE> (same as <CODE><A NAME=MARKER-2-2883></A>NF_FILL_SHORT</CODE>), <CODE><A NAME=MARKER-2-2884></A>NF_FILL_INT</CODE>, <CODE><A NAME=MARKER-2-2885></A>NF_FILL_REAL</CODE> (same as <CODE><A NAME=MARKER-2-2886></A>NF_FILL_FLOAT</CODE>), and <CODE><A NAME=MARKER-2-2887></A>NF_FILL_DOUBLE</CODE>.<P>
 <A NAME=MARKER-2-2888></A><A NAME=MARKER-2-2890></A>The netCDF byte and character types have different default fill values. The default fill value for characters is the zero byte, a useful value for detecting the end of variable-length C character strings. If you need a fill value for a byte variable, it is recommended that you explicitly define an appropriate <CODE>_FillValue</CODE> attribute, as generic utilities such as <CODE>ncdump</CODE> will not assume a default fill value for byte variables.<P>
 Type conversion for fill values is identical to type conversion for other values: attempting to convert a value from one type to another type that can't represent the value results in a range error. Such errors may occur on writing or reading values from a larger type (such as double) to a smaller type (such as float), if the fill value for the larger type cannot be represented in the smaller type.<P>
<A NAME=HEADING12-740></A>
<H2>7.17  Rename a Variable: <A NAME=MARKER-10-2891></A><CODE><A NAME=MARKER-2-2892></A>NF_RENAME_VAR </CODE></H2>
<HR>
 The function <A NAME=MARKER-10-2893></A><CODE>NF_RENAME_VAR</CODE> <A NAME=MARKER-2-2894></A><A NAME=MARKER-2-2895></A>changes the name of a netCDF variable in an open netCDF dataset. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a variable to have the name of any existing variable. <P>
<A NAME=HEADING12-742></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2896></A>INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
                                CHARACTER*(*) NEWNAM)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>VARID</CODE><TD>Variable ID.<TR>
<TD><CODE>NEWNAM</CODE><TD>New name for the specified variable.</TABLE>

</PRE>
Errors <P>
 <CODE><A NAME=MARKER-10-2897></A>NF_RENAME_VAR</CODE> returns the value <A NAME=MARKER-10-2898></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The new name is in use as the name of another variable.<P>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-750></A>
<H4>Example </H4>
 Here is an example using<A NAME=MARKER-10-2900></A><CODE><A NAME=MARKER-2-2901></A>NF_RENAME_VAR</CODE> to rename the variable <CODE>rh</CODE> to <CODE>rel_hum</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>: <P>
<PRE>
<A NAME=MARKER-10-2902></A>INCLUDE 'netcdf.inc'
   ... 
INTEGER  STATUS, NCID
INTEGER  RHID             ! variable ID
   ... 
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
   ... 
STATUS = NF_REDEF (NCID)  ! enter definition mode
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)
STATUS = NF_ENDDEF (NCID) ! leave definition mode
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<!-- TOC --><DL>
<DT><A HREF="guidef-12.html#HEADING12-17"><B>7.1 </B> - Language Types Corresponding to netCDF external data types</A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-22"><B>7.2 </B> - Create a Variable: NF_DEF_VAR </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-24"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-37"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-63"><B>7.3 </B> - Get a Variable ID from Its Name: NF_INQ_VARID </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-65"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-72"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-83"><B>7.4 </B> - Get Information about a Variable from Its ID: NF_INQ_VAR family</A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-87"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-106"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-125"><B>7.5 </B> - Write a Single Data Value: NF_PUT_VAR1_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-127"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-147"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-164"><B>7.6 </B> - Write an Entire Variable: NF_PUT_VAR_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-166"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-186"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-207"><B>7.7 </B> - Write an Array of Values: NF_PUT_VARA_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-209"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-236"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-261"><B>7.8 </B> - Write a Subsampled Array of Values: NF_PUT_VARS_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-263"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-289"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-315"><B>7.9 </B> - Write a Mapped Array of Values: NF_PUT_VARM_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-317"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-349"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-411"><B>7.10 </B> - Read a Single Data Value: NF_GET_VAR1_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-413"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-434"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-451"><B>7.11 </B> - Read an Entire Variable NF_GET_VAR_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-453"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-473"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-490"><B>7.12 </B> - Read an Array of Values: NF_GET_VARA_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-492"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-520"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-540"><B>7.13 </B> - Read a Subsampled Array of Values: NF_GET_VARS_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-542"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-568"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-589"><B>7.14 </B> - Read a Mapped Array of Values: NF_GET_VARM_type </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-591"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-623"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-685"><B>7.15 </B> - Reading and Writing Character String Values</A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-734"><B>7.16 </B> - Fill Values</A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-740"><B>7.17 </B> - Rename a Variable: NF_RENAME_VAR </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-742"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-12.html#HEADING12-750"><B>Example</B> - </A>
<DD>
</DL>

<HR>
<ADDRESS>NetCDF User's Guide for Fortran - 4 JUN 1997</ADDRESS>
<A HREF="guidef-13.html">[Next] </A><A HREF="guidef-11.html">[Previous] </A><A HREF="guidef-1.html">[Top] </A><A HREF="guidef-3.html">[Contents] </A><A HREF="guidef-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
</BODY>