.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "GRS1 3pm"
.TH GRS1 3pm "2011-12-23" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Z3950::Record::GRS1 \- Perl package used to encode GRS\-1 records.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::Z3950::GRS1;
\&
\&  my $a_grs1_record = new Net::Z3950::Record::GRS1;
\&  my $another_grs1_record = new Net::Z3950::Record::GRS1;
\&
\&  $a_grs1_record\->AddElement($type, $value, $content);
\&  $a_grs1_record\->Render();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Perl module helps you to create and manipulate \s-1GRS\-1\s0 records (generic record syntax).
So far, you have only access to three methods:
.SS "new"
.IX Subsection "new"
Creates a new \s-1GRS\-1\s0 object,
.PP
.Vb 1
\&  my $grs1 = new Net::Z3950::GRS1;
.Ve
.SS "AddElement"
.IX Subsection "AddElement"
Lets you add entries to a \s-1GRS\-1\s0 object. The method should be called this way,
.PP
.Vb 1
\&  $grs1\->AddElement($type, $value, $which, $content);
.Ve
.PP
where \f(CW$type\fR should be an integer, and \f(CW$value\fR is free text. The \f(CW$which\fR argument should
contain one of the constants listed in Appendix A. Finally, \f(CW$content\fR contains the \*(L"thing\*(R"
that should be stored in this entry. The structure of \f(CW$content\fR should match the chosen
element data type. For
.PP
.Vb 1
\&  $which == Net::Z3950::GRS1::ElementData::String;
.Ve
.PP
\&\f(CW$content\fR should be some kind of scalar. If on the other hand,
.PP
.Vb 1
\&  $which == Net::Z3950::GRS1::ElementData::Subtree;
.Ve
.PP
\&\f(CW$content\fR should be a \s-1GRS1\s0 object.
.SS "Render"
.IX Subsection "Render"
This method digs through the \s-1GRS\-1\s0 data structure and renders the record. You call it
this way,
.PP
.Vb 1
\&  $grs1\->Render();
.Ve
.PP
If you want to access the rendered record through a variable, you can do it like this,
.PP
.Vb 2
\&  my $record_as_string;
\&  $grs1\->Render(POOL => \e$record_as_string);
.Ve
.PP
If you want it stored in a file, Render should be called this way,
.PP
.Vb 1
\&  $grs1\->Render(FILE => \*(Aqrecord.grs1\*(Aq);
.Ve
.PP
When no file name is specified, you can choose to stream the rendered record, for instance,
.PP
.Vb 3
\&  $grs1\->Render(HANDLE => *STDOUT);             ## or
\&  $grs1\->Render(HANDLE => *STDERR);             ## or
\&  $grs1\->Render(HANDLE => *MY_HANDLE);
.Ve
.SS "Hash2grs"
.IX Subsection "Hash2grs"
This method converts a hash into a \s-1GRS\-1\s0 object. Scalar entries within the hash are converted
into \s-1GRS\-1\s0 string elements. A hash entry can itself be a reference to another hash. In this case,
the new referenced hash will be converted into a \s-1GRS\-1\s0 subtree. The method is called this way,
.PP
.Vb 1
\&  $grs1\->Hash2grs($href, $mapping);
.Ve
.PP
where \f(CW$href\fR is the hash to be converted and \f(CW$mapping\fR is referenced hash specifying the mapping
between keys in \f(CW$href\fR and (type, value) pairs in the \f(CW$grs1\fR object. The \f(CW$mapping\fR hash could
for instance look like this,
.PP
.Vb 5
\&  my $mapping = {
\&                        title   =>      [2, 1],
\&                        author  =>      [1, 1],
\&                        issn    =>      [3, 1]
\&                };
.Ve
.PP
If the \f(CW$grs1\fR object contains data prior to the invocation of Hash2grs, the new data represented
by the hash is simply added.
.SH "APPENDIX A"
.IX Header "APPENDIX A"
These element data types are specified in the Z39.50 protocol:
.PP
.Vb 10
\&  Net::Z3950::GRS1::ElementData::Octets
\&  Net::Z3950::GRS1::ElementData::Numeric
\&  Net::Z3950::GRS1::ElementData::Date
\&  Net::Z3950::GRS1::ElementData::Ext
\&  Net::Z3950::GRS1::ElementData::String                 <\-\-\-
\&  Net::Z3950::GRS1::ElementData::TrueOrFalse
\&  Net::Z3950::GRS1::ElementData::OID
\&  Net::Z3950::GRS1::ElementData::IntUnit
\&  Net::Z3950::GRS1::ElementData::ElementNotThere
\&  Net::Z3950::GRS1::ElementData::ElementEmpty
\&  Net::Z3950::GRS1::ElementData::NoDataRequested
\&  Net::Z3950::GRS1::ElementData::Diagnostic
\&  Net::Z3950::GRS1::ElementData::Subtree                <\-\-\-
.Ve
.PP
Only the '<\-\-\-' marked types are so far supported in this package.
.SH "AUTHOR"
.IX Header "AUTHOR"
Anders Sønderberg Mortensen <sondberg@indexdata.dk>
Index Data ApS, Copenhagen, Denmark.
2001/03/09
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Specification of the \s-1GRS\-1\s0 standard, for instance in the Z39.50 protocol specification.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 372:" 4
.IX Item "Around line 372:"
Non-ASCII character seen before =encoding in 'Sønderberg'. Assuming \s-1CP1252\s0