Documentation
¶
Overview ¶
Package z3950 is a client for the Z39.50 information-retrieval protocol (ANSI/NISO Z39.50 / ISO 23950), the classic library search protocol that SRU succeeded. It speaks BER-encoded APDUs over TCP -- Initialize, Search (Type-1 RPN queries over the bib-1 attribute set), Present and Close -- implemented from the published standard using only the standard library.
Retrieved records decode through libcodex's readers by record syntax: MARC21 via iso2709, UNIMARC via unimarc, MARCXML via marcxml; SUTRS text is exposed raw. The Reader implements codex.RecordReader, so a Z39.50 search is a drop-in source for codex.Convert, mirroring the sru package:
c := z3950.NewClient("lx2.loc.gov:210/LCDB")
rd := c.NewReader(ctx, z3950.Term("title", "moby dick"))
codex.Convert(rd, marcjson.NewWriter(os.Stdout))
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
Address string // host:port of the Z39.50 server
Databases []string // databases to search
Syntax string // preferred record syntax: "marc21" (default), "unimarc", "xml", "sutrs"
PageSize int // records per Present; <=0 uses 10
// Authentication, sent as idAuthentication in the Initialize request. User,
// Password and Group select the structured idPass form; AuthOpen sends the
// single-string open form instead, for the rare server that only accepts it.
// All empty means anonymous (the field is omitted).
User string
Password string
Group string
AuthOpen string
}
Client holds the target address and session defaults. The zero value is not usable; construct one with NewClient.
func NewClient ¶
NewClient returns a Client for a target in host:port/database form (the conventional Z39.50 target notation, e.g. "lx2.loc.gov:210/LCDB").
func (*Client) Connect ¶
Connect dials the target and negotiates the session with an Initialize exchange. Close the Conn when done.
func (*Client) NewReader ¶
NewReader returns a Reader over the result set for the query. The connection is dialed lazily on the first Read and closed automatically at the end of the result set or on error; call Reader.Close to abandon a stream early. The context governs the dial and every request.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is one Z39.50 session: a TCP connection that has completed Initialize. It is not safe for concurrent use; the protocol is strictly request/response.
type Diagnostic ¶
type Diagnostic struct {
Set string // diagnostic set ("bib-1")
Condition int // bib-1 condition code
Message string // human-readable addinfo
}
Diagnostic is one bib-1 diagnostic from the server.
func (Diagnostic) String ¶
func (d Diagnostic) String() string
type DiagnosticsError ¶
type DiagnosticsError struct {
Diagnostics []Diagnostic
}
DiagnosticsError reports that a search or present failed with diagnostics.
func (*DiagnosticsError) Error ¶
func (e *DiagnosticsError) Error() string
type Query ¶
type Query struct {
// contains filtered or unexported fields
}
Query is a Z39.50 Type-1 (RPN) query over the bib-1 attribute set. Build one with Term and combine with And, Or and AndNot:
q := z3950.And(z3950.Term("author", "melville"), z3950.Term("title", "moby dick"))
A term carries a use attribute plus a structure attribute chosen automatically: phrase for multi-word terms, word otherwise (strict servers reject multi-word terms without one). Query.Phrase, Query.Word, Query.Truncated and Query.Exact refine a term, and a trailing "*" means right truncation ("mob*" finds moby; escape a literal asterisk as "\*"). Full bib-1 generality (proximity, other relations) is out of scope.
func Term ¶
Term is a single-term query against a named access point: one of "any", "title", "author", "subject", "isbn", "issn", "lccn" or "id".
func (Query) Exact ¶
Exact matches the complete field exactly: relation equal, first-in-field position, complete-field completeness. Suits control numbers and uniform identifiers more than free text.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader streams a search's records as *codex.Record, dialing on first use and fetching Present pages on demand. It implements codex.RecordReader, so a Z39.50 search is a source for codex.Convert, mirroring the sru package's Reader. Records whose syntax has no codex decoder (e.g. SUTRS) are skipped; use Conn.Present directly to inspect them.
func (*Reader) All ¶
All returns an iterator over the remaining records, for use as "for rec, err := range r.All()". It stops at the first error.
type Record ¶
type Record struct {
Syntax string // "marc21", "unimarc", "xml", "sutrs", "opac", or a dotted OID
Data []byte // raw record payload in its syntax
Diag *Diagnostic // set instead of Data for a surrogate diagnostic
}
Record is one retrieved record: its record syntax, the raw payload, or a surrogate diagnostic when the server could not deliver this record.
type Result ¶
type Result struct {
Count int // total hits in the result set
}
Result reports the outcome of a Search: the total hit count on the server's result set, retrievable with Conn.Present.
Source Files