.TH ph_get_fieldinfo 3 "Oct 2002" "University of Illinois" "C Library Calls"
.SH NAME
ph_get_fieldinfo, ph_retrieve_fieldinfo, ph_fieldinfo_iterate, ph_decode_field_attributes \- access field information from PH server
.SH SYNOPSIS
.B #include <phclient.h>
.P
.BI "int ph_get_fieldinfo(PH *" ph ", char *" fieldname ","
.BI "struct ph_fieldinfo **" fieldinfo ");"
.br
.BI "int ph_retrieve_fields(PH *" ph ");"
.br
.BI "void ph_decode_field_attributes(unsigned long " bitmask ","
.BI "char *" buf ", int " bufsize ");"
.br
.BI "int ph_fieldinfo_iterate(PH *" ph ", struct ph_fieldinfo **" fieldinfo ");"
.br
.BI "void ph_free_fieldinfo(PH *" ph ");"
.br
.BI "int ph_is_fieldinfo_cached(PH *" ph ");"
.SH VERSION
This man page documents version 1.2 of \fBlibphclient\fP.
.SH DESCRIPTION
These functions allow the caller to access the field list from the PH
server associated with the \fBPH\fP handle \fIph\fP.  The information
for a given field is encoded as a \fIstruct ph_fieldinfo\fP, which includes
the fields \fIname\fP (the field's name), \fIid\fP (the field's numeric ID),
\fImax_size\fP (the maximum size of the field), \fIdescription\fP (a text
string describing the field), and \fIattrib\fP (a bitmask of attributes
associated with the field).

The \fBph_retrieve_fieldinfo\fP() function retrieves the field list from
the server associated with \fIph\fP and caches it locally.  If the field
list is already cached before the call to \fBph_retrieve_fieldinfo\fP(),
it returns successfully without doing anything.

The \fBph_free_fieldinfo\fP() function frees the memory associated with
the locally-cached field list.  A subsequent call to
\fBph_retrieve_fieldinfo\fP() will reload the cache from the server.

The \fBph_is_fieldinfo_cached\fP() macro determines whether or not the
field list is cached locally.

The \fBph_get_fieldinfo\fP() function sets \fIfieldinfo\fP to point to
the \fIph_fieldinfo\fP structure describing \fIfieldname\fP.  If the 
field list has not been retrieved from the server,
\fBph_retrieve_fieldinfo\fP() is called.

The \fBph_fieldinfo_iterate\fP() function allows the calling application
to iterate through the entire field list by setting \fIfieldinfo\fP to
the next entry at each call.  To begin at the beginning of the list,
the caller must initialize \fIfieldinfo\fP to \fBNULL\fP.

The \fBph_decode_field_attributes\fP() function generates a text representation
of the attributes set in \fIbitmask\fP.  It writes the text string to the
buffer of size \fIbufsize\fP pointed to by \fIbuf\fP.
.SH RETURN VALUE
The \fBph_retrieve_fieldinfo\fP() function returns 0 on success, or -1 on error
and sets \fIerrno\fP.

The \fBph_is_fieldinfo_cached\fP() macro returns 1 if the field list is
cached locally, or 0 otherwise.

The \fBph_fieldinfo_iterate\fP() function returns 1 when field information
is returned, or 0 when there are no more fields.  On error, it returns
-1 and sets \fIerrno\fP.

The \fBph_get_fieldinfo\fP() function returns 0 on success, \fIPH_ERR_DATAERR\fP if
\fIfieldname\fP is not found.  On error, it returns -1 and sets errno.
.SH ERRORS
The \fBph_retrieve_fieldinfo\fP() and \fBph_get_fieldinfo\fP() functions
will fail with \fBEINVAL\fP if they receive an unexpected response code
from the server.

The \fBph_retrieve_fieldinfo\fP() function may fail with any error from the
functions \fIread\fP() or \fIwrite\fP().
.SH SEE ALSO
.BR read (2),
.BR write (2),
.BR ph_open (3)