.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 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.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_get_sarray_slice.3.  The gd_get_sarray_slice man page.
.\"
.\" Copyright (C) 2010-2013, 2016 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_get_sarray_slice 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_get_sarray, gd_get_sarray_slice \(em retrieve STRING or SARRAY data from a
dirfile database

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_get_sarray_slice(DIRFILE *" dirfile ", const char *" field_code ,
.BI "unsigned int " start ", size_t " len ", const char **" data_out );
.HP
.BI "int gd_get_sarray(DIRFILE *" dirfile ", const char *" field_code ,
.BI "const char **" data_out );
.EC

.SH DESCRIPTION
The
.FN gd_get_sarray_slice
function queries a dirfile(5) database specified by
.ARG dirfile
for the
.B STRING
or
.B SARRAY
scalar
.ARG field_code .
Pointers to read-only string elements of the specified field are stored in the
user-supplied 
.ARG data_out
buffer, which must be large enough to hold
.ARG len
pointers.  The first element of the field stored is given by
.ARG start ,
and the number of elements stored is given by
.ARG len .

The
.FN gd_get_sarray
function behaves similarly, except it returns the entire field, as if
.FN gd_get_sarray_slice
were called with
.ARG start
equal to zero and
.ARG len
equal to the value returned by
.F3 gd_array_len .

The 
.ARG dirfile
argument must point to a valid DIRFILE object previously created by a call to
.F3 gd_open .
The number of elements returned by
.FN gd_get_sarray
may be obtained by calling
.F3 gd_array_len .
Unlike
.F3 gd_getdata ,
calling
.FN gd_get_sarray_slice
never results in a short read; attempting to read past the end of the
field will result in an error, and no data will be returned.

If
.ARG field_code
refers to a
.B STRING
field, it is treated as if it were a
.B SARRAY
field with only one element.  See the
.F3 gd_get_string
manual page for an example of how to replace
.F3 gd_get_string
calls with
.FN gd_get_sarray .

.SH RETURN VALUE
On success,
.FN gd_get_sarray
and
.FN gd_get_sarray_slice ,
return zero.  Storage for the strings returned by this function are managed
by GetData and should not be deallocated by the caller.  On error, these
functions return a negative-valued error code.  Possible error codes are:
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The field specified by
.ARG field_code
was not found in the database.
.DD GD_E_BAD_DIRFILE
An invalid
.ARG dirfile
was supplied.
.DD GD_E_BAD_FIELD_TYPE
The supplied
.ARG field_code
was not a
.BR STRING
nor
.BR SARRAY .
.DD GD_E_BOUNDS
A request for data beyond the end of the field was made.
.DD GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to perform the task.
This indicates a bug in the library.  Please report the incident to the
maintainer.
.PP
The error code is also stored in the
.B DIRFILE
object and may be retrieved after this function returns by calling
.F3 gd_error .
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH HISTORY
The
.FN gd_get_sarray
and
.FN gd_get_sarray_slice
functions appeared in GetData-0.10.0.

.SH SEE ALSO
.F3 gd_array_len ,
.F3 gd_get_string ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_open ,
.F3 gd_put_sarray_slice ,
.F3 gd_sarrays ,
dirfile(5)