The C interface for the HDS library is defined within file $STARLINK_DIR/include/star/hds.h. There is a one-to-one correspondance between each C function and each Fortran routine described in this document - the Fortran documentation should be consulted for information about the purpose of each function and the nature of its arguments.

Within C, each HDS locator is referred to by a pointer to an “ HDSLoc”, and all such variables must be initialised to NULL when they are declared. Functions that require a locator as input should be supplied with an “HDSLoc *”. Functions that return a locator as output should be supplied with an “HDSLoc **” (i.e. the address of an “HDSLoc *”):

  #include "star/hds.h"
  HDSLoc *loc = NULL;
  HDSLoc *cloc = NULL;
  int status;
  hdsOpen( "fred.sdf", "READ", &loc, &status );
  datFind( loc, "DATA", &cloc, &status );
  datAnnul( &cloc, status );
  datAnnul( &loc, status );

Each C function returns the integer status value as the function value in addition to returning it in the usual manner via the inherited status variable. In most cases, the returned function value will be ignored, as in the above example.

The C API includes the following three extra functions to manage the locking of HDS Locators by specific threads: