[Top] [Prev] [Next]

10.4 Writing an Annotation: ANwriteann

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

  1. Create a file annotation or a data annotation.
  2. Write to the annotation.
  3. Terminate access to the annotation.

To write a file or data annotation, the calling program must contain the following routine calls:

C:		file_id = Hopen(filename, file_access_mode, num_dds_block);
		an_id = ANstart(file_id);
		ann_id = ANcreatef(an_id, annot_type);
	OR	ann_id = ANcreate(an_id, obj_tag, obj_ref, annot_type);
		status = ANwriteann(ann_id, ann_text, ann_length);
		status = ANendaccess(ann_id);
		status = ANend(an_id);
		status = Hclose(file_id);
FORTRAN:	file_id = hopen(filename, file_access_mode, num_dds_block)
		an_id = afstart(file_id)
		ann_id = affcreate(an_id, annot_type)
	OR	ann_id = afcreate(an_id, obj_tag, obj_ref, annot_type)
		status = afwriteann(ann_id, ann_text, ann_length)
		status = afendaccess(ann_id)
		status = afend(an_id)
		status = hclose(file_id)
ANwriteann writes the annotation text given in the parameter ann_text to the annotation specified by ann_id. The parameter ann_length specifies the number of characters in the annotation text, not including the NULL character. If the annotation has already been written with text, ANwriteann will overwrite the current text.

ANwriteann returns either SUCCEED (or 0) or FAIL (or -1). The parameters of ANwriteann are further defined in Table 10C.

TABLE 10C - ANwriteann Parameter List

Routine Name

[Return Type]

(FORTRAN-77)
Parameter
Parameter Type
Description
C
FORTRAN-77
ANwriteann

[int32]

(afwriteann)
ann_id
int32
integer
Annotation identifier

ann_text
char *
character*(*)
Text of the annotation

ann_length
int32
integer
Number of characters in the annotation

EXAMPLE 1. Creating File and Data Annotations

This example illustrates the use of ANcreatef/affcreate to create file annotations and ANcreate/afcreate to create data annotations.

In this example, the program creates an HDF file named "General_HDFobjects.hdf" then attaches to it two annotations, a file label and a file description. Within the HDF file, the program creates a vgroup named "AN Vgroup" and attaches to it two annotations, a data label and a data description. Refer to Chapter 5, Vgroups (V API), for a discussion of the V interface routines used in this example.

Note that the names AN_FILE_LABEL, AN_FILE_DESC, AN_DATA_LABEL, and AN_DATA_DESC are defined by the library to specify the type of the annotation to be accessed.

C version

FORTRAN-77 version





[Top] [Prev] [Next]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 07/21/98, NCSA HDF Development Group.