1 User-Defined Formats for NetCDF {#user_defined_formats}
2 ===============================
6 User-Defined Formats {#udf_user_defined_formats}
7 =====================================
9 ## Introduction {#udf_Introduction}
11 User-defined formats allow users to write their own adaptors for the
12 netCDF C library, so that it can read and (optionally) write a
13 proprietary format through the netCDF API.
15 This capability is currently experimental. It involves the exposing of internal
16 netcdf interfaces and data structures that were previously invisible to users.
17 This means that it is unstable and the exposed interfaces are subject to change.
20 User-defined format code is packaged into a separate library, the
21 user-defined format dispatch library. This library, when linked with
22 the netCDF library, will allow user programs to read their proprietary
23 format through the netCDF API. The proprietary format is treated as if
24 it were one of the netCDF C library native binary formats.
26 Coding the user-defined format dispatch library requires knowledge of
27 the netCDF library internals. User-defined format dispatch libraries
32 Some file formats use the first few bytes of the file as an identifier
33 for format. For example, HDF5 files have "HDF5" as the fist 4 bytes,
34 and netCDF classic files have "CDF1" as the first four bytes. This is
35 called the "magic number" of the file.
37 User-defined formats can optionally support magic numbers. If the
38 user-defined format uses a magic number, and that magic number is
39 associated with the user-defined format, then netCDF will be able to
40 correctly identify those files from nc_open(). It will not be
41 necessary for the user to know or specify the underlying format.
43 ## Using User-Defined Formats from C Programms {#udf_With_C}
45 A user-defined format can be added dynamically in the case of C programs.
48 /* Add our test user defined format. */
49 if (nc_def_user_format(NC_UDF0, &tst_dispatcher, NULL)) ERR;
52 The file can now be opened by netCDF:
55 if (nc_open(FILE_NAME, NC_UDF0, &ncid)) ERR;
58 If a magic number is used in the file, that may be passed to
59 nc_def_user_format(). In that case, specifying the NC_UDF0 mode flag
60 to nc_open() is optional. The nc_open() will check the file and find
61 the magic number, and automatically associate the file with
62 NC_UDF0. The user will not need to know the format in order to open
63 the file with nc_open().
65 ## Building NetCDF C Library with a User-Defined Format Library {#udf_Build_NetCDF_With_UDF}
67 Once a user-defined format library is created, it may built into a
68 netCDF install. This allows the netCDF Fortran APIs, and the netCDF
69 utilities (ncdump, ncgen, nccopy) to natively use the user-defined
72 First the user-defined dispatch library must be built and installed.
74 Then the netcdf-c package must be (re-)built. When building netcdf-c,
75 add the location of the user-defined format dispatch library include
76 file to the CPPFLAGS, and the location of the user-defined format
77 dispatch library in LDFLAGS.
79 Configure netcdf-c with the option ````--with-udf0=<udf_lib_name>````.
81 If a magic number is associated with the user-defined format, it can
82 be specified with the --with-udf0-magic-number= argument.
84 ## Creating a User-Defined Format {#udf_Create_UDF}
86 Creators of user-defined format libraries will have to become familar
87 with the internals of the netCDF-4 code.
89 ### Read-Only User-Defined Formats
91 Many users will find that a read-only user-defined formats meets most
92 of their needs. With a read-only user-defined format, netCDF will be
93 able to read files of the user-defined format. Tools like ncdump and
94 nccopy can work on the files.
96 A read-only user-defined format can be implemented with only 6
97 functions. The code in libhdf4 is an excellent example of a read-only
100 ## Examples {#udf_Examples}
102 The most simple-case example of a user-defined format is provided in
103 test nc_test4/tst_udf.c.
105 A slightly more complex example, including the required
106 autoconf/automake files to build a user-defined format library, can be
107 found at the [sample user-defined format
108 library](https://github.com/NOAA-GSD/sample-netcdf-dispatch). In this
109 example, the HDF4 SD reader is re-implemented as an external
110 user-defined format. (This is unnecessary if you just want to read
111 HDF4 SD files, since the netCDF C library already includes an HDF4 SD
112 file reader. This user-defined format library uses the same code. It
113 is repackaged as a user-defined library to provide a working sample.)