simple_2D.c File Reference

Basic example demonstrating 2D array creation and reading in NetCDF. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <netcdf.h>

Macros
#define	FILE_NAME   "simple_2D.nc"
#define	NDIMS   2
#define	NX   6
#define	NY   12
#define	FILL_VALUE   -9999
#define	ERRCODE   2
#define	ERR(e)   {printf("Error: %s\n", nc_strerror(e)); exit(ERRCODE);}

Functions
int	main ()

Detailed Description

Basic example demonstrating 2D array creation and reading in NetCDF.

This example shows the fundamental workflow for working with NetCDF files:

• Creating a new NetCDF file
• Defining dimensions and variables
• Adding global and variable attributes
• Writing data to variables
• Closing and reopening the file
• Querying file structure with nc_inq(), nc_inq_dim(), and nc_inq_var()
• Reading and verifying attributes and data

The program creates a 2D integer array (6x12), partially writes sequential values (0, 1, 2, ..., 59) for the first NY-1 rows (leaving the last row unwritten), and sets a custom fill value (-9999) so unwritten elements are identifiable. It writes to a NetCDF file with a global attribute ("title") and a variable attribute ("units"), then reopens the file to verify metadata, attributes, fill value, and data correctness. This demonstrates the complete read-write cycle that forms the foundation of NetCDF programming.

Learning Objectives:

• Understand basic NetCDF file structure (dimensions, variables, attributes, data)
• Learn dimension and variable definition workflow
• Add global and variable attributes
• Master data writing and reading operations
• Query file metadata with nc_inq(), nc_inq_dim(), and nc_inq_var()
• Implement error handling patterns with nc_strerror()
• Verify metadata, attribute, and data integrity

Key Concepts:

• Dimensions: Named axes that define array shapes (x=6, y=12)
• Variables: Named data arrays with defined dimensions and types
• Attributes: Metadata attached to variables or the file (global)
• NetCDF-4 Format: HDF5-based format with enhanced features
• Define Mode: Metadata definition phase before data writing
• Data Mode: Phase where actual data is written/read
• Fill Value: Sentinel value returned for unwritten or missing data elements; set with nc_def_var_fill() during define mode, queried with nc_inq_var_fill(). Note: coord.c uses nc_put_att_float("_FillValue",...) which is the CF convention for documenting fill values as an attribute — a complementary but separate approach.

Prerequisites: None - this is a beginner example

Related Examples:

• coord_vars.c - Adds coordinate variables and CF metadata
• f_simple_2D.f90 - Fortran equivalent of this example
• simple_nc4.c - NetCDF-4 specific features (compression, chunking)

Compilation:

gcc -o simple_2D simple_2D.c -lnetcdf

Usage:

./simple_2D
ncdump simple_2D.nc

Expected Output: Creates simple_2D.nc containing:

• 2 dimensions: x(6), y(12)
• 1 variable: data(y, x) of type int with fill value -9999
• 1 global attribute: title = "Simple 2D Example"
• 1 variable attribute: units = "m/s"
• Data: sequential integers from 0 to 59 (first NY-1 rows); last row = -9999 (fill value)

Note

Companion code for "The NetCDF Developer's Handbook: The Authoritative Guide to Writing High-Performance Programs for Scientific Data Management, Second Edition" (https://www.amazon.com/dp/B0H7Q1Z75L)

Author

Edward Hartnett

Date

2026-01-15

Macro Definition Documentation

ERR

#define ERR

(

e

)

{printf("Error: %s\n", nc_strerror(e)); exit(ERRCODE);}

ERRCODE

#define ERRCODE   2

FILE_NAME

#define FILE_NAME   "simple_2D.nc"

FILL_VALUE

#define FILL_VALUE   -9999

NDIMS

#define NDIMS   2

NX

#define NX   6

NY

#define NY   12

Function Documentation

main()

int main

(

void

)