NCL Home > Documentation > HLUs > API

NhlRLGetMDArray

NhlRLGetMDArray, NhlRLGetMDIntegerArray, NhlRLGetMDFloatArray, NhlRLGetMDDoubleArray

The Fortran names of these functions are NhlFRLGetMDIntegerArray, NhlFRLGetMDFloatArray, NhlFRLGetMDDoubleArray. There is no Fortran binding for NhlRLGetMDArray.

Used to add the given name and val_addr to the ResList.


C synopsis

#include <ncarg/hlu/hlu.h>

NhlErrorTypes NhlRLGetMDArray(
		int		list_id,
		NhlString	resname,
		NhlPointer	*data_addr,
		NhlString	*type_element,
		unsigned int	*size_element,
		int		*num_dimensions,
		int		**len_dimensions
		)

NhlErrorTypes NhlRLGetMDIntegerArray(
		int		list_id,
		NhlString	resname,
		int		**data_addr,
		int		*num_dimensions,
		int		**len_dimensions
		)

NhlErrorTypes NhlRLGetMDFloatArray(
		int		list_id,
		NhlString	resname,
		float		**data_addr,
		int		*num_dimensions,
		int		**len_dimensions
		)

NhlErrorTypes NhlRLGetMDDoubleArray(
		int		list_id,
		NhlString	resname,
		double		**data_addr,
		int		*num_dimensions,
		int		**len_dimensions
		)

Fortran synopsis

      subroutine NhlFRLGetMDIntegerArray(list_id, resname, iarray, 
     +                   num_dim, len_dim, ierr)
      integer list_id, iarray(*), num_dim, len_dim, ierr
      character*(*) resname

      subroutine NhlFRLGetMDFloatArray(list_id, resname, rarray,
     +                   num_dim, len_dim, ierr)
      integer list_id, num_dim, len_dim, ierr
      real rarray(*)
      character*(*) resname

      subroutine NhlFRLGetMDDoubleArray(list_id, resname, darray,
     +                   num_dim, len_dim, ierr)
      integer list_id, num_dim, len_dim, ierr
      double precision darray(*)
      character*(*) resname

Arguments

list_id (input)
Id of the ResList to retrieve the name/val_addr pair from.
resname (input)
Specifies the resource name to retrieve the value of.
data_addr (output, C only)
Specifies the address of the pointer to the array retrieved from the resname resource when the ResList is applied to an HLU object using the NhlGetValues function. The programmers are responsible for freeing this array when they finish with it.
type_element (output, C only)
Returns the name of the type of each element in the data array. This parameter must be a valid pointer to an NhlString. The NhlString will be assigned during the call to NhlGetValues, and the programmer is responsible for freeing the NhlString returned.
size_element (output, C only)
Returns the size, in bytes, of each element in the data array. This parameter must be a valid pointer to an unsigned integer.
num_dimensions (output, C only)
Returns the number of dimensions in the data array. This parameter must be a valid pointer to an integer.
len_dimensions (output, C only)
Returns an array of length num_dimensions. Specifies the length of each dimension in the data array. The array will be allocated during the call to NhlGetValues, and the programmer is responsible for freeing the array returned.
num_dim (input, Fortran only)
This parameter must contain the number of dimensions in the data array as it is declared in the program (iarray or rarray). It is also the number of elements in the len_dim array. If the resource that is being returned has fewer dimensions than the data array, this value will be changed to indicate the number of dimensions that were returned.
len_dim (input, Fortran only)
This array must contain the length of each dimension in the data array as it is declared in the program (iarray or rarray). If the resource that is being returned has fewer dimensions than the data array, the num_dim variable will indicate how many dimensions were returned, and therefore the number of elements in this array that have been changed to indicate the length of each dimension that was returned. The array will be modified during the call to NhlFGetValues.
iarray (output, Fortran only)
The multi-dimensioned integer array retrieved from the resname resource when the list is applied to an HLU object using the NhlFGetValues function.
rarray (output, Fortran only)
The multi-dimensioned real array retrieved from the resname resource when the list is applied to an HLU object using the NhlFGetValues function.
darray (output, Fortran only)
The multi-dimensioned double precision array retrieved from the resname resource when the list is applied to an HLU object using the NhlFGetValues function.
ierr (output, Fortran only)
Error code.

Types

Type name:		NhlTErrorTypes
Definition:
typedef enum _NhlErrType{
	NhlFATAL	= -4,	/* "FATAL"	*/
	NhlWARNING	= -3,	/* "WARNING"	*/
	NhlINFO		= -2,	/* "INFO"	*/
	NhlNOERROR	= -1	/* "NOERROR"	*/
} NhlErrorTypes;

Description

These functions can only be used on a NhlGETRL ResList. They are used to retrieve name/data_addr pairs from the ResList that will be passed to the NhlGetValues function. These functions need to be used to retrieve an Array resource from an HLU object. The programmer is responsible for freeing the memory returned to the data_addr, type_element, and len_dimensions parameters after the call to NhlGetValues.

Return values

The C functions return a value of type NhlErrorTypes, and the Fortran subroutines return the error value in ierr. If they are unable to retrieve the name/value pair to the list, they will return NhlFATAL; otherwise they will return NhlNOERROR.

See also