NhlAddData

The Fortran name of this function is NhlFAddData.

This function is used to associate a DataItem object with a data resource in a DataComm object.

C synopsis

#include <ncarg/hlu/DataComm.h>

int NhlAddData(
		int		dcommid,
		NhlString	res_name,
		int		ditemid
		)

Fortran synopsis

      subroutine NhlFAddData(dcommid, res_name, ditemid, id)
      integer dcommid, ditemid, id
      character*(*) res_name

Arguments

dcommid (input): Identifies the DataComm object with the data resource.
res_name (input): Identifies the data resource to set in the DataComm object.
ditemid (input): Identifies the DataItem object id to associate with the res_name resource in the dcommid DataComm object.
id (output, Fortran only): The id of the DataSpec object that was created to describe the DataItem added.

Description

This function is used to associate the given ditemid DataItem object with the given res_name data resource in the given dcommid DataComm object.

If the given ditemid is a valid data type for the given res_name, then the ditemid will be "added" to that data resource. Different DataComm subclasses will use their data resources in different ways. For example, the XyPlot object has a data resource xyCoordData which is used as a list of DataItems. Each DataItem in the xyCoordData list may actually specify more than one curve in the plot.

Additionally, DataComm objects usually have a companion resource to the res_name resource that is used to retrieve DataSpec objects. The DataSpec objects are used to describe Data Specific plot attributes. For example, the XyPlot objects use the XyDataSpec object to describe actual line colors for each coordinate pair array described in the xyCoordData resource. The DataComm object creates a DataSpec object for each individual DataItem that is added. The DataSpec object is created as a child of the DataComm object, and given the same name as the DataItem object it is describing. The XyPlot object has the xyCoordDataSpec resource to allow you to retrieve the array of XyDataSpec objects that describe the DataItems in the xyCoordData resource. The elements of the companion resource correspond to the DataItem ids in the res_name resource. In the XyPlot case, this means that each DataItem in the xyCoordData resource array is described by the corresponding XyDataSpec object in the xyCoordDataSpec resource array.

Provided as a shortcut to doing an NhlGetValues of the companion resource, the NhlAddData function returns the id of the DataSpec object that was created to describe the DataItem added.

Return values

The NhlAddData C function returns a value of type int, and the NhlFAddData returns this value in id. The following table indicates what the return values mean:

Value	|			Meaning
--------+-------------------------------------------------
 > 0	|	The DataItem was added
	|	to the res_name data resource
	|	without any problems. The integer is
	|	the id of the DataSpec object being
	|	used to visualize that data.
--------+-------------------------------------------------
   0	|	The DataItem was added, but the
	|	function was unable to retrieve the value
	|	of the DataSpec object id.
--------+-------------------------------------------------
 < 0	|	Unable to add the given DataItem to the
NhlFATAL|	given res_name data resource. This probably
	|	indicates that type of DataItem is not
	|	understood by the given DataComm object.

Copyright

Copyright 1987-1999 University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.

NCAR Graphics is a registered trademark of the University Corporation for Atmospheric Research.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.17 $ $Date: 1998/06/15 21:26:01 $