PDS4 User-Defined Format (UDF) dispatch layer. More...

#include "config.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include "nep_nc4.h"
#include "pds4dispatch.h"
#include <libxml/parser.h>
#include <libxml/tree.h>

Data Structures
struct	pds4_axis

Macros
#define	PDS4_NS "http://pds.nasa.gov/pds4/pds/v1"

Functions
static char *	pds4_trim (const char *s)

static char *	pds4_get_text (xmlNode *node)

static xmlNode *	pds4_find_child (xmlNode parent, const char name)

static int	pds4_att_exists (NCindex list, const char name)

static int	pds4_add_att (NCindex list, const char name, const char *value)

static int	pds4_type_to_nc_type (const char pds4_type, nc_type xtypep, size_t type_sizep, int endiannessp, char *type_name)

static int	pds4_set_var_type (nc_type xtype, int endianness, size_t type_size, const char type_name, NC_TYPE_INFO_T *typep)

static int	pds4_add_area_atts (NC_GRP_INFO_T grp, xmlNode area)

static int	pds4_add_leaf_atts (NC_GRP_INFO_T grp, xmlNode node)

static int	pds4_axis_cmp (const void a, const void b)

static int	pds4_read_array (NC_GRP_INFO_T grp, xmlNode array)

static int	pds4_read_table (NC_GRP_INFO_T grp, xmlNode table)

static int	pds4_read_file_area (NC_FILE_INFO_T h5, NC_GRP_INFO_T root_grp, xmlNode *file_area)

static int	pds4_read_label (NC_FILE_INFO_T h5, NC_PDS4_FILE_INFO_T pds4_file)

int	NC_PDS4_open (const char path, int mode, int basepe, size_t chunksizehintp, void parameters, const NC_Dispatch dispatch, int ncid)

static void	pds4_free_var_info (NC_GRP_INFO_T *grp)

int	NC_PDS4_close (int ncid, void *ignore)

int	NC_PDS4_abort (int ncid)

int	NC_PDS4_inq_format (int ncid, int *formatp)

int	NC_PDS4_inq_format_extended (int ncid, int formatp, int modep)

static int	pds4_resolve_data_path (const char label_path, const char data_filename, char *resolved)

static void	pds4_byte_swap (void *buf, size_t elem_size, size_t nelems)

static int	pds4_needs_swap (int endianness)

int	NC_PDS4_get_vara (int ncid, int varid, const size_t start, const size_t count, void *value, nc_type memtype)

Detailed Description

PDS4 User-Defined Format (UDF) dispatch layer.

Implements the NEP PDS4 reader. The PDS4 XML label is parsed with libxml2 and mapped into the netCDF-4 in-memory model (groups, dimensions, variables, attributes). Data reading via nc_get_vara() reads from the referenced binary or ASCII data files with automatic byte-order conversion.

Supported data objects:

Array / Array_2D_Image (contiguous, row-major)
Table_Binary (fixed-record, binary fields)
Table_Character (fixed-record, ASCII fields)
Table_Delimited (variable-record, ASCII fields)

netCDF Model Mapping

A PDS4 label file contains one or more File_Area_Observational elements, each referencing a separate binary or ASCII data file. The NEP PDS4 reader maps the label structure into the netCDF-4 in-memory model as follows:

The XML label root → root group. Elements of Identification_Area and Observation_Area become global string attributes on the root group.
Each File_Area_Observational → a child group of the root group, named from the File/file_name text content.
Array / Array_2D_Image inside a file area → netCDF dimensions created from the Axis_Array children (sorted ascending by sequence_number); each axis_name becomes the dimension name and elements its length; Last Index Fastest maps to C-order (fastest-varying index is rightmost). The array becomes a single netCDF variable in the child group, with type derived from Element_Array/data_type.
Table_Binary, Table_Character, Table_Delimited → a record dimension whose length comes from <records>; one netCDF variable per Field_Binary/Field_Character/Field_Delimited child, named from <name>, typed from <data_type>, with an optional units attribute from <unit>.

Byte-Order Handling

PDS4 specifies byte order per data object: MSB (Most Significant Byte first, big-endian) or LSB (Least Significant Byte first, little-endian). NEP records the byte order as NC_ENDIAN_BIG or NC_ENDIAN_LITTLE on each netCDF variable at open time. During data reading in NC_PDS4_get_vara(), elements are byte-swapped in-place when the file byte order differs from the host byte order. ASCII numeric fields (Table_Character, Table_Delimited) do not require byte-swapping; they are parsed directly via strtod() or strtoll().

Data File Resolution

Binary and text data files are referenced by filename only in the PDS4 label (the File/file_name element). NEP resolves each data filename relative to the directory that contains the XML label file, using pds4_resolve_data_path(). If the label has no directory component (i.e. it is in the current directory), the data file is also looked up in the current directory.

Author: Edward Hartnett

Date: 2026-07-08

Copyright: Intelligent Data Design, Inc. All rights reserved.

Macro Definition Documentation

◆ PDS4_NS

#define PDS4_NS "http://pds.nasa.gov/pds4/pds/v1"

PDS4 XML namespace URI

Function Documentation

◆ NC_PDS4_abort()

int NC_PDS4_abort ( int ncid )

Abort opening a PDS4 file.

Releases all resources allocated during a partial open, including the parsed XML document and per-file PDS4 state.

Parameters

ncid	NetCDF ID of the partially opened file.

Returns: NC_NOERR No error.; NC_EBADID Bad ncid.

Author: Edward Hartnett

Date: 2026-07-08

◆ NC_PDS4_close()

int NC_PDS4_close	(	int	ncid,
		void *	ignore
	)

Close a PDS4 file.

Frees per-variable layout info, the parsed XML document, and the per-file PDS4 state struct.

Parameters

ncid	NetCDF ID of the open PDS4 file.
ignore	Ignored (NULL).

Returns: NC_NOERR No error.; NC_EBADID Bad ncid.

Author: Edward Hartnett

Date: 2026-07-08

◆ NC_PDS4_get_vara()

int NC_PDS4_get_vara	(	int	ncid,
		int	varid,
		const size_t *	start,
		const size_t *	count,
		void *	value,
		nc_type	memtype
	)

Read a hyperslab of data from a PDS4 variable.

Reads contiguous array data or fixed-record table field data from the binary or ASCII data file referenced by the PDS4 label. Array reads honor the start/count hyperslab in C (row-major) order. Table field reads iterate over records start[0] through start[0]+count[0]-1. Byte-order conversion is applied automatically for binary types; ASCII fields are parsed via strtod()/strtoll().

Parameters

ncid	NetCDF ID of the group containing the variable.
varid	Variable ID within the group.
start	Array of start indices (0-based) for each dimension.
count	Number of elements to read along each dimension.
value	Output buffer large enough to hold the requested elements.
memtype	Requested memory type (type conversion not yet implemented; caller must request the native file type).

Returns: NC_NOERR No error.; NC_EBADID Bad ncid.; NC_ENOTVAR No variable with varid in this group.; NC_EINVAL Invalid parameters or seek error.; NC_ENOMEM Out of memory.; NC_ENOTFOUND Data file not found.

Author: Edward Hartnett

Date: 2026-07-08

◆ NC_PDS4_inq_format()

int NC_PDS4_inq_format	(	int	ncid,
		int *	formatp
	)

Inquire the format of a PDS4 file.

Parameters

ncid	NetCDF ID.
formatp	Pointer that receives the format code (NC_FORMAT_NETCDF4).

Returns: NC_NOERR No error.

Author: Edward Hartnett

Date: 2026-07-08

◆ NC_PDS4_inq_format_extended()

int NC_PDS4_inq_format_extended	(	int	ncid,
		int *	formatp,
		int *	modep
	)

Inquire the extended format of a PDS4 file.

Parameters

ncid	NetCDF ID.
formatp	Pointer that receives the extended format code (NC_FORMATX_NC_PDS4 = NC_FORMATX_UDF5).
modep	Pointer that receives the mode flags (NC_NOWRITE).

Returns: NC_NOERR No error.

Author: Edward Hartnett

Date: 2026-07-08

◆ NC_PDS4_open()

int NC_PDS4_open	(	const char *	path,
		int	mode,
		int	basepe,
		size_t *	chunksizehintp,
		void *	parameters,
		const NC_Dispatch *	dispatch,
		int	ncid
	)

Open a PDS4 XML label file.

Parses the PDS4 XML label with libxml2, validates the root element namespace, and maps the label content into the netCDF-4 in-memory model (root-group attributes, child groups, dimensions, variables). Only read-only access (NC_NOWRITE) is supported.

Parameters

path	Path to the PDS4 XML label file.
mode	Open mode flags; NC_WRITE causes NC_EPERM to be returned.
basepe	Ignored (present for dispatch interface compatibility).
chunksizehintp	Ignored.
parameters	Ignored.
dispatch	Dispatch table pointer assigned by NetCDF-C.
ncid	NetCDF ID assigned by the NetCDF-C dispatch layer.

Returns: NC_NOERR No error.; NC_EINVAL Null path, XML parse failure, or non-PDS4 namespace.; NC_EPERM Write mode requested.; NC_ENOTNC Root element namespace is not the PDS4 namespace.; NC_ENOMEM Out of memory.

Author: Edward Hartnett

Date: 2026-07-08

◆ pds4_add_area_atts()

static int pds4_add_area_atts	(	NC_GRP_INFO_T *	grp,
		xmlNode *	area
	)

static

◆ pds4_add_att()

static int pds4_add_att	(	NCindex *	list,
		const char *	name,
		const char *	value
	)

static

◆ pds4_add_leaf_atts()

static int pds4_add_leaf_atts	(	NC_GRP_INFO_T *	grp,
		xmlNode *	node
	)

static

◆ pds4_att_exists()

static int pds4_att_exists	(	NCindex *	list,
		const char *	name
	)

static

◆ pds4_axis_cmp()

static int pds4_axis_cmp	(	const void *	a,
		const void *	b
	)

static

◆ pds4_byte_swap()

static void pds4_byte_swap	(	void *	buf,
		size_t	elem_size,
		size_t	nelems
	)

static

◆ pds4_find_child()

static xmlNode * pds4_find_child	(	xmlNode *	parent,
		const char *	name
	)

static

◆ pds4_free_var_info()

static void pds4_free_var_info ( NC_GRP_INFO_T * grp )

static

◆ pds4_get_text()

static char * pds4_get_text ( xmlNode * node )

static

◆ pds4_needs_swap()

static int pds4_needs_swap ( int endianness )

static

◆ pds4_read_array()

static int pds4_read_array	(	NC_GRP_INFO_T *	grp,
		xmlNode *	array
	)

static

◆ pds4_read_file_area()

static int pds4_read_file_area	(	NC_FILE_INFO_T *	h5,
		NC_GRP_INFO_T *	root_grp,
		xmlNode *	file_area
	)

static

◆ pds4_read_label()

static int pds4_read_label	(	NC_FILE_INFO_T *	h5,
		NC_PDS4_FILE_INFO_T *	pds4_file
	)

static

◆ pds4_read_table()

static int pds4_read_table	(	NC_GRP_INFO_T *	grp,
		xmlNode *	table
	)

static

◆ pds4_resolve_data_path()

static int pds4_resolve_data_path	(	const char *	label_path,
		const char *	data_filename,
		char *	resolved
	)

static

◆ pds4_set_var_type()

static int pds4_set_var_type	(	nc_type	xtype,
		int	endianness,
		size_t	type_size,
		const char *	type_name,
		NC_TYPE_INFO_T **	typep
	)

static

◆ pds4_trim()

static char * pds4_trim ( const char * s )

static

◆ pds4_type_to_nc_type()

static int pds4_type_to_nc_type	(	const char *	pds4_type,
		nc_type *	xtypep,
		size_t *	type_sizep,
		int *	endiannessp,
		char *	type_name
	)

static

Data Structures

Macros

Functions

Detailed Description

netCDF Model Mapping

Byte-Order Handling

Data File Resolution

Macro Definition Documentation

◆ PDS4_NS

Function Documentation

◆ NC_PDS4_abort()

◆ NC_PDS4_close()

◆ NC_PDS4_get_vara()

◆ NC_PDS4_inq_format()

◆ NC_PDS4_inq_format_extended()

◆ NC_PDS4_open()

◆ pds4_add_area_atts()

◆ pds4_add_att()

◆ pds4_add_leaf_atts()

◆ pds4_att_exists()

◆ pds4_axis_cmp()

◆ pds4_byte_swap()

◆ pds4_find_child()

◆ pds4_free_var_info()

◆ pds4_get_text()

◆ pds4_needs_swap()

◆ pds4_read_array()

◆ pds4_read_file_area()

◆ pds4_read_label()

◆ pds4_read_table()

◆ pds4_resolve_data_path()

◆ pds4_set_var_type()

◆ pds4_trim()

◆ pds4_type_to_nc_type()