# HDF 4.2 to 4.3 Migration Guide

For the past few decades, HDF4 has deployed almost all of the library's header
files, both public and private. This deployment scheme makes even trivial
refactoring and bug fixing difficult to accomplish without breaking binary
compatibility when "private" headers change.

HDF 4.3.0 will finally separate the public and private APIs in both the single-
and multi-file libraries, allowing us to begin the process of cleaning up
several decades of accumulated technical debt.

This document lists the changes to what we deploy and how that may impact
code that uses HDF4. There is also a list of removed symbols, organized by
header file in the appendices.

Note that this is not a complete guide to changes in 4.3.0. It's only intended
to help people navigate the public/private API split. Please see the release
notes for a comprehensive list of other changes, e.g., build system changes.

## Changes in HDF 4.3.0

* Private header files are no longer distributed. A complete list can be found below.
* The error-handling macros have been removed from `herr.h`.
* Most of `hbitio.h` has been moved to a private header file.
* Most of `hfile.h` has been moved to a private header file.
* `hdf.h` no longer pulls in the `hdfi.h` internal header file. See below for the implications of this.

## Migration Steps

Most users should not have to make any changes to their applications, as long
as they only use the public API as documented in the HDF4 Reference Manual.
The single- and multi-file API calls are all unchanged and we have preserved
the legacy HDF 3 API (found in `df.h`).

If you HAVE used any of the undocumented functionality packeded with the library
(e.g., `linklist.h`'s linked lists), you will either have to pull those
source files out of an older version of the library for incorporation into
your own code, or stick with HDF 4.2.16. Note that we don't plan to have
additional HDF 4.2.x maintenance releases.

An additional problem you may encounter stems from the removal of the `hdfi.h`
internal header file from `hdf.h`. That internal header brought in a lot of OS,
POSIX, and C headers which will now be missing from your application. If you
relied on the implicit inclusion of `hdfi.h` to bring in things like `sys/types`,
you will have to add these to your source code, as `hdf.h` only includes what
it needs.

## Appendix: List of Removed Header Files

The following headers are no longer installed:

* atom.h
* bitvect.h
* cdeflate.h
* cnbit.h
* cnone.h
* crle.h
* cskphuff.h
* cszip.h
* dfan.h
* dfgr.h
* dfrig.h
* dfsd.h
* dfufp2i.h
* dynarray.h
* hchunks.h
* hcompi.h
* hconv.h
* hdfi.h
* hkit.h
* linklist.h
* local\_nc.h
* mfani.h
* mfgri.h
* mstdio.h
* tbbt.h

We also no longer deploy the XDR header:
* xdr.h

## Appendix: List of Removed Functions and Function-Like Macros

### atom.h
```
HAIswap_cache
HAatom_object

HAinit_group
HAdestroy_group
HAregister_atom
HAPatom_object
HAatom_group
HAremove_atom
HAsearch_atom
HAshutdown
```

### bitvect.h
```
bv_new
bv_delete
bv_set
```

### cdeflate.h
```
HCPcdeflate_stread
HCPcdeflate_stwrite
HCPcdeflate_seek
HCPcdeflate_inquire
HCPcdeflate_read
HCPcdeflate_write
HCPcdeflate_endaccess
```

### cnbit.h
```
HCPcnbit_stread
HCPcnbit_stwrite
HCPcnbit_seek
HCPcnbit_inquire
HCPcnbit_read
HCPcnbit_write
HCPcnbit_endaccess
```

### cnone.h
```
HCPcnone_stread
HCPcnone_stwrite
HCPcnone_seek
HCPcnone_inquire
HCPcnone_read
HCPcnone_write
HCPcnone_endaccess
```

### crle.h
```
HCPcrle_stread
HCPcrle_stwrite
HCPcrle_seek
HCPcrle_inquire
HCPcrle_read
HCPcrle_write
HCPcrle_endaccess
```

### cskphuff.h
```
HCPcskphuff_stread
HCPcskphuff_stwrite
HCPcskphuff_seek
HCPcskphuff_inquire
HCPcskphuff_read
HCPcskphuff_write
HCPcskphuff_endaccess
```

### cszip.h
```
HCPcszip_stread
HCPcszip_stwrite
HCPcszip_seek
HCPcszip_inquire
HCPcszip_read
HCPcszip_write
HCPcszip_endaccess
```

### dfgr.h
```
DFGRIopen
```

### dfsd.h
```
DFSDIopen
DFSDIsdginfo
DFSDIclear
DFSDIclearNT
DFSDIgetdata
DFSDIputdata
DFSDIgetslice
DFSDIputslice
DFSDIendslice
DFSDIrefresh
DFSDIisndg
DFSDIgetrrank
DFSDIgetwrank
DFSDIsetdimstrs
DFSDIsetdatastrs
```

### dfufp2i.h
```
process
generate_scale
convert_interp
pixrep_scaled
compute_offsets
pixrep_simple
DFUfptoimage
```

### dynarray.h
```
DAcreate_array
DAdestroy_array
DAsize_array
DAget_elem
DAset_elem
DAdel_elem
```

### glist.h
```
HDGLinitialize_list
HDGLinitialize_sorted_list
HDGLdestroy_list
HDGLadd_to_beginning
HDGLadd_to_end
HDGLadd_to_list
HDGLremove_from_beginning
HDGLremove_from_end
HDGLremove_from_list
HDGLremove_current
HDGLremove_all
HDGLpeek_at_beginning
HDGLpeek_at_end
HDGLfirst_in_list
HDGLcurrent_in_list
HDGLlast_in_list
HDGLnext_in_list
HDGLprevious_in_list
HDGLreset_to_beginning
HDGLreset_to_end
HDGLnum_of_objects
HDGLis_empty
HDGLis_in_list
HDGLcopy_list
HDGLperform_on_list
HDGLfirst_that
HDGLnext_that
HDGLprevious_that
HDGLlast_that
HDGLall_such_that
HDGLremove_all_such_that
HDGSinitialize_stack
HDGSdestroy_stack
HDGSpush
HDGSpop
HDGSpop_all
HDGSpeek_at_top
HDGScopy_stack
HDGQinitialize_queue
HDGQdestroy_queue
HDGQenqueue
HDGQdequeue
HDGQdequeue_all
HDGQpeek_at_head
HDGQpeek_at_tail
HDGQcopy_queue
```

### hchunks.h
```
HMCcreate
HMCgetcompress
HMCgetcomptype
HMCgetdatainfo
HMCgetdatasize
HMCsetMaxcache
HMCwriteChunk
HMCreadChunk
HMCPcloseAID
HMCPgetnumrecs
```

### hdfi.h
```
INT16ENCODE
UINT16ENCODE
INT32ENCODE
UINT32ENCODE
NBYTEENCODE
INT16DECODE
UINT16DECODE
INT32DECODE
UINT32DECODE
NBYTEDECODE
MIN
MAX
```

### herr.h
```
HERROR
HRETURN_ERROR
HGOTO_ERROR
HGOTO_FAIL
HCLOSE_GOTO_ERROR
HGOTO_DONE
HE_REPORT
HE_REPORT_RETURN
HE_CLOSE_REPORT_RETURN
HE_REPORT_GOTO
HE_CLOSE_REPORT_GOTO
```

### hfile.h
```
BADFREC
BASETAG
SPECIALTAG
MKSPECIALTAG
HIget_access_rec
HIrelease_accrec_node
HIgetspinfo
HPcompare_filerec_path
HPcompare_accrec_tagref
HPgetdiskblock
HPfreediskblock
HPisfile_in_use
HDcheck_empty
HDget_special_info
HDset_special_info
HP_read
HPseek
HP_write
HPread_drec
tagcompare
tagdestroynode
HLPstread
HLPstwrite
HLPseek
HLPread
HLPwrite
HLPinquire
HLPendaccess
HLPcloseAID
HLPinfo
HXPstread
HXPstwrite
HXPseek
HXPread
HXPwrite
HXPinquire
HXPendaccess
HXPcloseAID
HXPinfo
HXPreset
HXPsetaccesstype
HXPshutdown
HCPstread
HCPstwrite
HCPseek
HCPinquire
HCPread
HCPwrite
HCPendaccess
HCPcloseAID
HCPinfo
get_comp_len
HBPstread
HBPstwrite
HBPseek
HBPinquire
HBPread
HBPwrite
HBPendaccess
HBPcloseAID
HBPinfo
HRPstread
HRPstwrite
HRPseek
HRPinquire
HRPread
HRPwrite
HRPendaccess
HRPcloseAID
HRPinfo
HTPstart
HTPinit
HTPsync
HTPend
HTPcreate
HTPselect
HTPendaccess
HTPdelete
HTPupdate
HTPinquire
HTPis_special
HTPdump_dds
```

### hqueue.h
```
H4_CIRCLEQ_HEAD
H4_CIRCLEQ_ENTRY
H4_CIRCLEQ_INIT
H4_CIRCLEQ_INSERT_AFTER
H4_CIRCLEQ_INSERT_BEFORE
H4_CIRCLEQ_INSERT_HEAD
H4_CIRCLEQ_INSERT_TAIL
H4_CIRCLEQ_REMOVE
```

### linklist.h
```
HULcreate_list
HULdestroy_list
HULadd_node
HULsearch_node
HULfirst_node
HULnext_node
HULremove_node
```

### mcache.h
```
HASHKEY
mcache_open
mcache_filter
mcache_new
mcache_get
mcache_put
mcache_sync
mcache_close
mcache_get_pagesize
mcache_get_maxcache
mcache_set_maxcache
mcache_get_npages
mcache_stat
```

### mfan.h
```
AN_CREATE_KEY
AN_KEY2REF
AN_KEY2TYPE
```

### mfgr.h
```
VALIDRIINDEX
GRIil_convert
GRIgrdestroynode
GRIattrdestroynode
GRIridestroynode
```

### mstdio.h
```
HCPmstdio_stread
HCPmstdio_stwrite
HCPmstdio_seek
HCPmstdio_inquire
HCPmstdio_read
HCPmstdio_write
HCPmstdio_endaccess
```

### tbbt.h
```
tbbtdfind
tbbtfind
tbbtdless
tbbtless
tbbtindx
tbbtdins
tbbtins
tbbtrem
tbbtfirst
tbbtlast
tbbtnext
tbbtprev
tbbtdfree
tbbtfree
tbbtprint
tbbtdump
tbbtcount
tbbt_shutdown
```

### vgint.h
```
VSIget_vdata_node
VSIrelease_vdata_node
VSIgetvdatas
VSIget_vsinstance_node
VSIrelease_vsinstance_node
VIget_vgroup_node
VIrelease_vgroup_node
VIget_vginstance_node
VIrelease_vginstance_node
VPparse_shutdown
Get_vfile
vsinst
vginst
vswritelist
vpackvg
vinsertpair
vpackvs
VPgetinfo
VSPgetinfo
map_from_old_types
trimendblanks
```

### error.h
```
nc_serror
NCadvise
```

### local\_nc.h (NOTE: May be prefixed with sd_)
```
IS_RECVAR
nc_serror
NCadvise
NC_computeshapes
NC_xtypelen
NC_xlen_array
NC_xlen_attr
NC_xlen_cdf
NC_xlen_dim
NC_xlen_iarray
NC_xlen_string
NC_xlen_var
NCmemset
NC_arrayfill
NC_copy_arrayvals
NC_free_array
NC_free_attr
NC_free_cdf
NC_free_dim
NC_free_iarray
NC_free_string
NC_free_var
NC_incr_array
NC_dimid
NCcktype
NC_indefine
xdr_cdf
xdr_numrecs
xdr_shorts
xdr_NC_array
xdr_NC_attr
xdr_NC_dim
xdr_NC_fill
xdr_NC_iarray
xdr_NC_string
xdr_NC_var
NC_typelen
NC_check_id
NC_dup_cdf
NC_new_cdf
NC_new_array
NC_re_array
NC_new_attr
NC_findattr
NC_new_dim
NC_new_iarray
NC_new_string
NC_re_string
NC_hlookupvar
NC_new_var
NCvario
NCcoordck
xdr_NCvshort
NC_dcpy
NCxdrfile_sync
NCxdrfile_create
hdf_fill_array
hdf_get_data
hdf_get_vp_aid
hdf_map_type
hdf_unmap_type
hdf_get_ref
hdf_create_dim_vdata
hdf_create_compat_dim_vdata
hdf_write_attr
hdf_write_dim
hdf_write_var
hdf_write_xdr_cdf
hdf_conv_scales
hdf_read_dims
hdf_read_attrs
hdf_read_vars
hdf_read_xdr_cdf
hdf_xdr_cdf
hdf_vg_clobber
hdf_cdf_clobber
hdf_close
hdf_read_sds_dims
hdf_read_sds_cdf
SDPfreebuf
NCgenio
NC_var_shape
NC_reset_maxopenfiles
NC_get_maxopenfiles
NC_get_systemlimit
NC_get_numopencdfs
cdf_unmap_type
nssdc_read_cdf
nssdc_write_cdf
nssdc_xdr_cdf
HDiscdf
HDisnetcdf
HDisnetcdf64
```

## Appendix: List of Removed Symbols, Types, etc.

### atom.h
```
group_t
atom_t
HAsearch_func_t
atom_id_cache
atom_obj_cache
```

### bitvect.h
```
bv_bool
BV_DEFAULT_BITS
BV_CHUNK_SIZE
bv_struct_tag
```

### cdeflate.h
```
comp_coder_deflate_info_t
cdeflate_funcs
```

### cnbit.h
```
NBIT_BUF_SIZE
NBIT_MASK_SIZE
nbit_mask_info_t
comp_coder_nbit_info_t
cnbit_funcs
```

### cnone.h
```
comp_coder_none_info_t
cnone_funcs
```

### crle.h
```
RLE_BUF_SIZE
RLE_NIL
RLE_MIN_RUN
RLE_MAX_RUN
RLE_MIN_MIX
comp_coder_rle_info_t
crle_funcs
```

### cskphuff.h
```
SKPHUFF_MAX_CHAR
SUCCMAX
TWICEMAX
ROOT
comp_coder_skphuff_info_t
cskphuff_funcs
```

### cszip.h
```
H4_SZ_ALLOW_K13_OPTION_MASK
H4_SZ_CHIP_OPTION_MASK
H4_SZ_EC_OPTION_MASK
H4_SZ_LSB_OPTION_MASK
H4_SZ_MSB_OPTION_MASK
H4_SZ_NN_OPTION_MASK
H4_SZ_RAW_OPTION_MASK
SZ_H4_REV_2
comp_coder_szip_info_t
cszip_funcs
```

### dfan.h
```
DFAN_LABEL
DFAN_DESC
DFAN_LAB_BLKSIZE
DFAN_DESC_BLKSIZE
DFAN_DEFENTRIES
DFANdirentry
DFANdirhead
```

### dfgr.h
```
DFGRdr
DFGRrig
```

### dfrig.h
```
DFRdr
DFRrig
R8dim
```

### dfsd.h
```
DFSsdg
DFnsdgle
DFnsdg_t_hdr
```

### dfufp2i.h
```
Input
Output
```

### dynarray.h
```
dynarr_p
```

### glist.h
```
Generic_list_element
Generic_list_info
Generic_list
Generic_stack
Generic_queue
```

### hbitio.h
```
bitrec_t
maskc
maskl
```

### hchunks.h
```
DIM_DEF
DIM_DEF_PTR
HCHUNK_DEF
HCHUNK_DEF_PTR
chunked_funcs
```

### hcompi.h
```
comp_coder_info_t
comp_stateinfo_t
comp_state_cache_t
compinfo_t
```

### hconv.h
```
UI8_IN
UI8_OUT
SI16_IN
SI16_OUT
UI16_IN
UI16_OUT
SI32_IN
SI32_OUT
UI32_IN
UI32_OUT
F32_IN
F32_OUT
F64_IN
F64_OUT
LUI8_IN
LUI8_OUT
LSI16_IN
LSI16_OUT
LUI16_IN
LUI16_OUT
LSI32_IN
LSI32_OUT
LUI32_IN
LUI32_OUT
LF32_IN
LF32_OUT
LF64_IN
LF64_OUT
NUI8_IN
NUI8_OUT
NSI16_IN
NSI16_OUT
NUI16_IN
NUI16_OUT
NSI32_IN
NSI32_OUT
NUI32_IN
NUI32_OUT
NF32_IN
NF32_OUT
NF64_IN
NF64_OUT
fpx
float_uint_uchar
```

### hdfi.h
```
DFMT_LE
DFMT_BE
DF_MT
UNIXUNBUFIO
UNIXBUFIO
FILELIB
H4_HAVE_LP64
FNAME_POST_UNDERSCORE
hdf_pint_t
JMEMSYS
FRETVAL
FCALLKEYW
FNAME
```

### hfile.h
```
MAGICLEN
HDFMAGIC
DD_SZ
NDDS_SZ
OFFSET_SZ
INVALID_OFFSET
INVALID_LENGTH
HI_OPEN
HI_CREATE
HI_READ
HI_WRITE
HI_CLOSE
HI_FLUSH
HI_SEEK
HI_SEEK_CUR
HI_SEEKEND
HI_TELL
OPENERR
hdf_file_t
dd_t
version_t
ddblock_t
tag_info
fileop_t
filerec_t
DDLIST_DIRTY
FILE_END_DIRTY
accrec_t
sp_info_block_t
funclist_t
functab_t
FIDTYPE
AIDTYPE
GROUPTYPE
SDSTYPE
DIMTYPE
CDFTYPE
VGIDTYPE
VSIDTYPE
BITTYPE
GRIDTYPE
RIIDTYPE
diskblock_header
diskblock_tail
```

### hkit.h
```
tag_descript_t
tag_descriptions
nt_descript_t
nt_descriptions
```

### linklist.h
```
HUL_UNSORTED_LIST
HUL_SORTED_LIST
HULsearch_func_t
HULfind_func_t
node_info_t
list_head_t
```

### mcache.h
```
HASHSIZE
RET_SUCCESS
RET_ERROR
DEF_PAGESIZE
DEF_MAXCACHE
BKT
MCACHE_DIRTY
MCACHE_PINNED
ELEM_READ
ELEM_WRITTEN
ELEM_SYNC
L_ELEM
MCACHE_EXTEND
MCACHE
```

### mfan.h
```
ANnode
ANentry
ANATOM_HASH_SIZE
```

### mfgr.h
```
GRATOM_HASH_SIZE
RI_TAG
ATTR_TAG
GR_ATTR_THRESHHOLD
gr_info_t
at_info_t
dim_info_t
ri_info_t
```

### mstdio.h
```
comp_model_stdio_info_t
mstdio_funcs
```

### tbbt.h
```
TBBT_FAST_UINT16_COMPARE
TBBT_FAST_INT32_COMPARE
tbbt_node_private
tbbt_tree_private
TBBT_NODE
TBBT_TREE
```

### vgint.h
```
VGROUP
VDATA
VSUBGROUP
SYMDEF
VWRITELIST
DYN_VWRITELIST
vs_attr_t
vg_attr_t
DYN_VREADLIST
vgroup_desc
vdata_desc
vginstance_t
vsinstance_t
vfile_t
```

### local\_nc.h
```
FILENAME_MAX
NC_BYTE_SIZE
NC_CHAR_SIZE
NC_SHORT_SIZE
NC_LONG_SIZE
NC_FLOAT_SIZE
NC_DOUBLE_SIZE
NC_UNSPECIFIED_SIZE
Void
ATTR_TAG
DIM_TAG
VAR_TAG
DATA_TAG
BOGUS_TAG
DIMVAL_VERSION00
DIMVAL_VERSION01
BLOCK_MULT
MAX_BLOCK_SIZE
BLOCK_COUNT
MAX_VXR_ENTRIES
vix_t
NC_array
NC_string
NC_iarray
NC_dim
NC_attr
NC
NC_var
netCDF_FILE
HDF_FILE
CDF_FILE
cdf_routine_name
MAGICOFFSET
CDFMAGIC
HDFXMAGIC
NCMAGIC
NCMAGIC64
NCLINKMAGIC
```