[Top] [Prev] [Next] [Bottom]

10.11 Creating and Writing Annotations Using the AN Interface

The AN interface writes file labels, file descriptions, data object labels and data object descriptions according to the general AN programming models.

10.11.1 Creating Annotations

Creating an annotation without writing it involves the following steps:

1. Open the HDF file.
2. Initialize the AN interface.
3. Define the type of annotation to be created.
4. Create the annotation.
5. Terminate access to the annotation.
6. Terminate access to the AN interface.
7. Close the file.
To create a file annotation, the calling program must contain the following AN routine calls:

C:		file_id = Hopen(filename, access. block_size);
		an_id = ANstart(file_id);
		ann_id = ANcreatef(an_id, ann_type);
		status = ANendaccess(ann_id);
		status = ANend(an_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access, block_size)
		an_id = afstart(file_id)
		ann_id = affcreate(an_id, ann_type)
		status = afendaccess(ann_id)
		status = afend(an_id)
		status = hclose(file_id)

ANstart initializes the multifile annotation interface. ANcreate and ANcreatef creates the annotation. ANendaccess terminates access to the annotation, and ANend terminates access to the multifile annotation interface.

ANcreate has four parameters: an_id, tag, ref and ann_type. The an_id parameter is the interface identifier for the annotation to be written, the tag and ref parameters are the tag/reference number pair of the object the annotation will be assigned to and the ann_type parameter is the data annotation type. It is set to either AN_DATA_LABEL or AN_DATA_DESC. These annotation type definitions are defined in the "hdf.h" header file.

ANcreatef is used to create file annotations. The ann_type parameter in a call to ANcreatef can only be set to the type definitions AN_FILE_LABEL or AN_FILE_DESC, which are also defined in the "hdf.h" header file.

ANendaccess's one argument, ann_id, is an annotation returned by ANcreate and is disposed of by ANendaccess. Any subsequent attempts to access the annotation id will result in an error condition.

ANend also has only one parameter, an_id, which is the AN interface identifier returned by ANstart. This identifier is disposed of by ANend and access to the interface routines is terminated during this call. Any subsequent attempts to access the annotation interface id or routines will result in an error condition.

The parameters of these functions are defined in the following table.

TABLE 10K ANstart, ANcreate, ANcreatef, ANendaccess and ANend Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANstart

(afstart)

file_id

int32

integer

File identifier.

ANcreate

(afcreate)

an_id

int32

integer

AN interface identifier.

tag

uint16

integer

Tag of the item to be assigned the data annotation.

ref

uint16

integer

Reference number of the item to be assigned the data annotation.

type

int32

integer

Data annotation type: label or description.

ANcreatef

(affcreate)

an_id

int32

integer

AN interface identifier.

type

int32

integer

File annotation type: label or description.

ANendaccess

(afendaccess)

ann_id

int32

integer

Annotation identifier.

ANend

(afend)

an_id

int32

integer

AN interface identifier.

10.11.2 Writing an Annotation: ANwriteann

The AN programming model for writing an annotation is as follows:

1. Open the HDF file.
2. Initialize the AN interface.
3. Create the annotation identifier.
4. Write the annotation.
5. Terminate access to the annotation.
6. Terminate access to the AN interface.
7. Close the HDF file.
To write a file label, the calling program must contain the following AN routine calls:

C:		file_id = Hopen(filename, access. block_size);
		an_id = ANstart(file_id);
		ann_id = ANcreatef(an_id, ann_type);
		status = ANwriteann(ann_id, label, HDstrlen(label));
		status = ANendaccess(ann_id);
		status = ANend(an_id);
		status = Hclose(file_id);

FORTRAN:	file_id = hopen(filename, access, block_size)
		an_id = afstart(file_id)
		ann_id = affcreate(an_id, ann_type)
		status = afwriteann(ann_id, label, ann_length)
		status = anendaccess(ann_id)
		status = afend(an_id)
		status = hclose(file_id)

ANwriteann has three parameters: ann_id, label and ann_length. The ann_id parameter is the identifier for the annotation to be written, the label parameter contains the annotation string and the ann_length parameter contains the length of the annotation string. The label must be a null-terminated string. In the C interface, the HDstrlen function can be used to dynamically determine the length of the label string. In either C or Fortran-77, specifying a length value different from the actual length of the label will result in the label either being truncated or null-padded accordingly.

The parameters of ANwriteann are further defined in the following table.

TABLE 10L ANwriteann Parameter List
Routine Name

(Fortran-77)

Parameter

Data Type

Description

C

Fortran-77

ANwriteann

(afwriteann)

ann_id

int32

integer

Identifier for the annotation to be written.

label

char *

character* (*)

Label of the annotation.

ann_length

int32

integer

Length of the label in bytes.

EXAMPLE 8. Adding a File Label Using the AN Interface

The following examples add a file label and description to the HDF file named "Example6.hdf" using the AN interface routines.

C:

#include "hdf.h"
#include <string.h>

main( )
{

	int32 file_id, an_id, ann_id, vgroup_id, ann_type;
	uint16 obj_tag, obj_ref;
	intn status;
	static char file_label[] = "This is a file label.";

	/* Create the HDF file. */
	file_id = Hopen("Example6.hdf", DFACC_CREATE, 0);

	/* Initialize the AN interface and obtain an interface id. */
	an_id = ANstart(file_id);

	/* Set the file annotation type to be a file label. */
	ann_type = AN_FILE_LABEL;

	/* Create the file label and obtain an annotation id. */
	ann_id = ANcreatef(an_id, ann_type);

	/* Write the label to the file. */
	status = ANwriteann(ann_id, file_label, strlen(file_label));

	/* Create a vgroup. */
	status = Vstart(file_id);
	vgroup_id = Vattach(file_id, -1, "w");
	status = Vdetach(vgroup_id);
	status = Vend(file_id);

	obj_tag = DFTAG_VG;
	obj_ref = 0;

	/* Create the data description label. */
	ann_id = ANcreate(an_id, obj_tag, obj_ref, AN_DATA_DESC);

	/* Write the label to the file. */
	status = ANwriteann(ann_id, file_label, strlen(file_label));

	/* Terminate access to the annotation. */
	status = ANendaccess(ann_id);

	/* Terminate access to the AN interface. */
	status = ANend(an_id);

	/* Close the file. */
	status = Hclose(file_id);

}


 FORTRAN:	

PROGRAM CREATE A FILE LABEL integer hopen, afstart, affcreate, afendaccess, afend integer hclose, status, file_id, an_id, ann_id integer afwriteann integer*4 DFACC_CREATE, AN_FILE_LABEL parameter (DFACC_CREATE = 4, AN_FILE_LABEL = 2) character*21 file_label /"This is a file label."/ C Open the HDF file. file_id = hopen('Example6.hdf', DFACC_CREATE, 0) C Initialize the AN interface and obtain an interface id. an_id = afstart(file_id) C Use the file_id to write the label to the file. ann_id = affcreate(an_id, AN_FILE_LABEL) C Write the label to the file. status = afwriteann(ann_id, file_label, 21) C Terminate access to the annotation. status = afendaccess(ann_id) C Terminate access to the AN interface. status = afend(an_id) C Close the file. status = hclose(file_id) end



[Top] [Prev] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.