pds4dispatch.h File Reference

Public types and prototypes for the PDS4 UDF dispatch layer. More...

#include "config.h"
#include "ncdispatch.h"
#include "nep.h"
#include <libxml/parser.h>
#include <libxml/tree.h>

Go to the source code of this file.

Data Structures
struct	NC_PDS4_VAR_INFO
struct	NC_PDS4_FILE_INFO

Macros
#define	NC_FORMATX_NC_PDS4   NC_FORMATX_UDF0
#define	PDS4_MAGIC_LEN   5
#define	PDS4_NAMESPACE   "http://pds.nasa.gov/pds4/pds/v1"

Typedefs
typedef struct NC_PDS4_VAR_INFO	NC_PDS4_VAR_INFO_T
typedef struct NC_PDS4_FILE_INFO	NC_PDS4_FILE_INFO_T

Functions
int	NC_PDS4_open (const char *path, int mode, int basepe, size_t *chunksizehintp, void *parameters, const NC_Dispatch *, int)
int	NC_PDS4_abort (int ncid)
int	NC_PDS4_close (int ncid, void *ignore)
int	NC_PDS4_inq_format (int ncid, int *formatp)
int	NC_PDS4_inq_format_extended (int ncid, int *formatp, int *modep)
int	NC_PDS4_get_vara (int ncid, int varid, const size_t *start, const size_t *count, void *value, nc_type)
NC_Dispatch *	NC_PDS4_initialize (void)
int	NC_PDS4_finalize (void)

Variables
const NC_Dispatch *	PDS4_dispatch_table

Detailed Description

Public types and prototypes for the PDS4 UDF dispatch layer.

Defines the per-variable layout struct (NC_PDS4_VAR_INFO_T), the per-file state struct (NC_PDS4_FILE_INFO_T), and the public API prototypes for the PDS4 User-Defined Format handler.

Author

Edward Hartnett

Date

2026-07-08

Copyright

Intelligent Data Design, Inc. All rights reserved.

Macro Definition Documentation

NC_FORMATX_NC_PDS4

#define NC_FORMATX_NC_PDS4   NC_FORMATX_UDF0

PDS4 format uses UDF5 slot for dispatch table model field (see nep.h for slot allocation)

PDS4_MAGIC_LEN

#define PDS4_MAGIC_LEN   5

PDS4 magic number length (5 bytes: "<?xml")

PDS4_NAMESPACE

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

PDS4 XML namespace URI

Typedef Documentation

NC_PDS4_FILE_INFO_T

typedef struct NC_PDS4_FILE_INFO NC_PDS4_FILE_INFO_T

Per-file PDS4 state

NC_PDS4_VAR_INFO_T

typedef struct NC_PDS4_VAR_INFO NC_PDS4_VAR_INFO_T

Per-variable PDS4 layout info (stored in var->format_var_info)

Function Documentation

NC_PDS4_abort()

int NC_PDS4_abort ( int  ncid )

extern

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  )

extern

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_finalize()

int NC_PDS4_finalize ( void  )

extern

Finalize the PDS4 dispatch layer.

No-op in the current implementation.

Returns

NC_NOERR No error.

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  )

extern

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_initialize()

NC_Dispatch * NC_PDS4_initialize ( void  )

extern

Initialize the PDS4 dispatch layer.

Registers the PDS4 handler via nc_def_user_format() for direct calls, and returns the dispatch table pointer for the self-registration (HAVE_NETCDF_UDF_SELF_REGISTRATION) path. Safe to call when the handler has already been registered via .ncrc autoload; in that case NC_EINVAL from nc_def_user_format() is silently ignored.

Returns

Pointer to PDS4 dispatch table, or NULL on failure.

Author

Edward Hartnett

Date

2026-07-08

NC_PDS4_inq_format()

int NC_PDS4_inq_format ( int  ncid, int *  formatp  )

extern

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  )

extern

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  )

extern

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

Variable Documentation

PDS4_dispatch_table

const NC_Dispatch* PDS4_dispatch_table

extern