.\" gd_native_type.3.  The gd_native_type man page.
.\"
.\" Copyright (C) 2009, 2010 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_native_type 3 "3 November 2010" "Version 0.7.0" "GETDATA"
.SH NAME
gd_native_type \(em returns the native data type of a field in a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "gd_type_t gd_native_type(DIRFILE *" dirfile ", const char *" field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_native_type ()
function queries a dirfile(5) database specified by
.I dirfile
and returns the native data type of the field
.IR field_code ,
which may contain a representation suffix.

The 
.I dirfile
argument must point to a valid DIRFILE object previously created by a call to
.BR gd_open (3).

The native data type of a field of a given entry type is calculated as:
.TP
.BR BIT \~or\~ INDEX \~Entry:
.BR GD_UINT64 ;
.TP
.BR CONST \~or\~ CARRAY \~Entry:
the data type of the field;
.TP
.BR LINCOM \~or\~ POLYNOM \~Entry:
if any of the scalar parameters is complex valued, or if the native data type of
any of the input fields is complex valued:
.BR GD_COMPLEX128 ,
otherwise:
.BR GD_FLOAT64 ;
.TP
.BR LINTERP \~Entry:
if the look-up table is complex valued:
.BR GD_COMPLEX128 ,
otherwise:
.BR GD_FLOAT64 ;
.TP
.BR MULTIPLY \~or\~ DIVIDE \~Entry:
if either input field is complex valued:
.BR GD_COMPLEX128 ,
otherwise:
.BR GD_FLOAT64 ;
.BR 
.TP
.BR PHASE \~Entry:
the native data type of the input field;
.TP
.BR RAW \~Entry:
the data type of the raw data on disk;
.TP
.BR RECIP \~Entry:
if the dividend or the native data type of the input field is complex valued:
.BR GD_COMPLEX128 ,
otherwise:
.BR GD_FLOAT64 ;
.TP
.BR SBIT \~Entry:
.BR GD_INT64 ;
.TP
.BR STRING \~Entry:
.BR GD_NULL .
.PP
Furthermore, if the supplied
.I field_code
contains a representation suffix, and the native data type of the field is
complex valued, the native type returned will be the corresponding real valued
type.

.SH RETURN VALUE
Upon successful completion,
.BR gd_native_type ()
returns the native data type of the field code specified.  This will be one of
the symbols:
.IP
.nh
.ad l
.BR GD_NULL ,\~ GD_UINT8 ,\~ GD_INT8 ,\~ GD_UINT16 ,\~ GD_INT16 ,\~ GD_UINT32 ,
.BR GD_INT32 ,\~ GD_FLOAT32 ,\~ GD_FLOAT64 ,\~ GD_COMPLEX64 ,\~ GD_COMPLEX128 .
.ad n
.hy
.PP
The meanings of these symbols are explained in the
.BR gd_getdata (3)
manual page.  On error, it returns
.B GD_UNKNOWN
and sets the dirfile error to a non-zero error value.  Possible error values
are:
.TP 8
.B GD_E_BAD_CODE
The field specified by
.I field_code
or one of the fields it uses as input was not found in the database.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_REPR
The representation suffix specified in
.IR field_code ,
or in one of its input fields, was not recognised.
.TP
.B GD_E_BAD_SCALAR
A non-literal scalar used in the definition of the field or one of its inputs
was not found, or was not a
.B CONST
or
.B CARRAY
field.
.TP
.B GD_E_DIMENSION
A scalar field was found where a vector field was expected.
.TP
.B GD_E_OPEN_LINFILE
An error occurred while trying to read a LINTERP table from disk.
.TP
.B GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.IR field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).
.SH SEE ALSO
.BR dirfile (5),
.BR gd_open (3),
.BR gd_getdata (3),
.BR gd_error (3),
.BR gd_error_string (3)