Update source headers for 2008. Omit CVS ID keyword subst.
[yaz-moved-to-github.git] / include / yaz / marcdisp.h
1 /* This file is part of the YAZ toolkit.
2  * Copyright (C) 1995-2008 Index Data.
3  * All rights reserved.
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of Index Data nor the names of its contributors
13  *       may be used to endorse or promote products derived from this
14  *       software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 /* $Id: marcdisp.h,v 1.32 2008-02-20 10:03:25 adam Exp $ */
28
29 /**
30  * \file marcdisp.h
31  * \brief MARC conversion
32  */
33
34 #ifndef MARCDISP_H
35 #define MARCDISP_H
36
37 #include <yaz/yconfig.h>
38 #include <stdio.h>
39 #include <yaz/wrbuf.h>
40
41 #include <yaz/nmem.h>
42 #include <yaz/xmltypes.h>
43 #include <yaz/z-opac.h>
44
45 YAZ_BEGIN_CDECL
46
47 /** \brief a yaz_marc_t handle (private content) */
48 typedef struct yaz_marc_t_ *yaz_marc_t;
49
50 /** \brief construct yaz_marc_t handle */
51 YAZ_EXPORT yaz_marc_t yaz_marc_create(void);
52
53 /** \brief destroy yaz_marc_t handle */
54 YAZ_EXPORT void yaz_marc_destroy(yaz_marc_t mt);
55
56 /** \brief set XML mode YAZ_MARC_LINE, YAZ_MARC_SIMPLEXML, ... */
57 YAZ_EXPORT void yaz_marc_xml(yaz_marc_t mt, int xmlmode);
58
59 /** \brief Output format: Line-format */
60 #define YAZ_MARC_LINE      0
61 /** \brief Output format: simplexml (no longer supported) */
62 #define YAZ_MARC_SIMPLEXML 1
63 /** \brief Output format: OAI-MARC (no longer supported) */
64 #define YAZ_MARC_OAIMARC   2
65 /** \brief Output format: MARCXML */
66 #define YAZ_MARC_MARCXML   3
67 /** \brief Output format: ISO2709 */
68 #define YAZ_MARC_ISO2709   4
69 /** \brief Output format: MarcXchange */
70 #define YAZ_MARC_XCHANGE   5
71 /** \brief Output format: check only (no marc output) */
72 #define YAZ_MARC_CHECK  6
73
74 /** \brief set iconv handle for character set conversion .. */
75 YAZ_EXPORT void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
76
77 /** \brief supply iconv handle for character set conversion .. */
78 YAZ_EXPORT yaz_iconv_t yaz_marc_get_iconv(yaz_marc_t mt);
79
80 /** \brief set debug level 
81     \param mt handle
82     \param level level, where 0=lowest, 1 more debug, 2 even more 
83 */
84 YAZ_EXPORT void yaz_marc_debug(yaz_marc_t mt, int level);
85
86 /** \brief decodes ISO2709 buffer using straight buffers
87     \param mt marc handle
88     \param buf input buffer
89     \param bsize size of buffer or (-1 if "any size")
90     \param result result to be stored here
91     \param rsize size of result (memory "owned" by yaz_marc_mt handle)
92
93     Decodes MARC in buf of size bsize.
94     On success, result in *result with size *rsize. 
95     Returns -1 on error, or size of input record (>0) if OK
96 */
97 YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
98                                    const char **result, size_t *rsize);
99
100 /** \brief decodes ISO2709/MARC buffer and stores result in WRBUF
101     \param mt handle
102     \param buf input buffer
103     \param bsize size of buffer (-1 if "any size")
104     \param wrbuf WRBUF for output
105
106     Decodes MARC in buf of size bsize.
107     On success, result in wrbuf
108     Returns -1 on error, or size of input record (>0) if OK
109 */
110 YAZ_EXPORT int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
111                                      int bsize, WRBUF wrbuf);
112
113 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
114 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
115
116 /** \brief modifies part of the MARC leader */
117 YAZ_EXPORT void yaz_marc_modify_leader(yaz_marc_t mt, size_t off,
118                                        const char *str);
119
120 /** \brief like atoi(3) except that it reads exactly len characters */
121 YAZ_EXPORT int atoi_n(const char *buf, int len);
122
123 /** \brief like atoi_n but checks for proper formatting
124     \param buf buffer to read values from
125     \param size size of buffer
126     \param val value of decimal number (if successful)
127     \retval 0 no value found (non-digits found)
128     \retval 1 value found and *val holds value
129 */
130 YAZ_EXPORT
131 int atoi_n_check(const char *buf, int size, int *val);
132
133 /** \brief MARC control char: record separator (29 Dec, 1D Hex) */
134 #define ISO2709_RS 035
135 /** \brief MARC control char: field separator (30 Dec, 1E Hex) */
136 #define ISO2709_FS 036
137 /** \brief MARC control char: identifier-field separator (31 Dec, 1F Hex) */
138 #define ISO2709_IDFS 037
139
140 /** \brief read ISO2709/MARC record from buffer
141     \param mt handle
142     \param buf ISO2709 buffer of size bsize
143     \param bsize size of buffer (-1 for unlimited size)
144
145     Parses ISO2709 record from supplied buffer
146     Returns > 0 for OK (same as length), -1=ERROR
147 */
148 YAZ_EXPORT int yaz_marc_read_iso2709(yaz_marc_t mt,
149                                      const char *buf, int bsize);
150
151 /** \brief read MARC lineformat from stream
152     \param mt handle
153     \param getbyte get one byte handler
154     \param ungetbyte unget one byte handler
155     \param client_data opaque data for handers
156
157     Parses MARC line record from stream
158     Returns > 0 for OK (same as length), -1=ERROR
159 */
160 YAZ_EXPORT 
161 int yaz_marc_read_line(yaz_marc_t mt,
162                        int (*getbyte)(void *client_data),
163                        void (*ungetbyte)(int b, void *client_data),
164                        void *client_data);
165
166 /** \brief parses MARCXML/MarcXchange record from xmlNode pointer 
167     \param mt handle
168     \param ptr is a pointer to root xml node 
169
170     Returns 0=OK, -1=ERROR
171 */
172 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);
173
174 /** \brief writes record in line format
175     \param mt handle
176     \param wrbuf WRBUF for output
177
178     Returns 0=OK, -1=ERROR
179 */
180 YAZ_EXPORT int yaz_marc_write_line(yaz_marc_t mt, WRBUF wrbuf);
181
182 /** \brief writes record in MARCXML format
183     \param mt handle
184     \param wrbuf WRBUF for output
185
186     Sets leader[9]='a' . Returns 0=OK, -1=ERROR . 
187 */
188 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
189
190 /** \brief writes record in MarcXchange XML
191     \param mt handle
192     \param wrbuf WRBUF for output
193     \param format record format (e.g. "MARC21")
194     \param type record type (e.g. Bibliographic)
195
196     Returns 0=OK, -1=ERROR
197 */
198 YAZ_EXPORT int yaz_marc_write_marcxchange(yaz_marc_t mt, WRBUF wrbuf,
199                                           const char *format,
200                                           const char *type);
201
202 /** \brief writes record in ISO2709 format
203     \param mt handle
204     \param wrbuf WRBUF for output
205     Returns 0=OK, -1=ERROR
206 */
207 YAZ_EXPORT int yaz_marc_write_iso2709(yaz_marc_t mt, WRBUF wrbuf);
208
209 /** \brief writes record in mode - given by yaz_marc_xml mode
210     \param mt handle
211     \param wrbuf WRBUF for output
212     This function calls yaz_marc_write_iso2709, yaz_marc_write_marcxml,
213     etc.. depending on mode given by yaz_marc_xml. 
214     Returns 0=OK, -1=ERROR 
215 */  
216 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
217
218 /** \brief writes MARC record as libxml2 tree
219     \param mt handle
220     \param root_ptr pointer to record node
221     \param ns namespace of record (such as "http://www.loc.gov/MARC21/slim")
222     \param format MarcXchange format (NULL for none)
223     \param type MarcXchange format (NULL for none)
224     \retval 0 Creation successful and *root_ptr is "record" node
225     \retval -1 ERROR
226 */  
227 YAZ_EXPORT
228 int yaz_marc_write_xml(yaz_marc_t mt, xmlNode **root_ptr,
229                        const char *ns, 
230                        const char *format,
231                        const char *type);
232
233 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
234     \param mt handle
235     \param leader_spec
236     \retval 0 OK
237     \retval -1 ERROR
238     
239     Spec takes form pos=val,pos=val,...
240     where value is either a number (decimal char value) or a
241     string in 'a', e.g. 9='a'
242     
243 */  
244 YAZ_EXPORT int yaz_marc_leader_spec(yaz_marc_t mt, const char *leader_spec);
245
246
247 /** \brief sets leader, validates it, and returns important values
248     \param mt handle
249     \param leader of the 24 byte leader to be set
250     \param indicator_length indicator length (returned value)
251     \param identifier_length identifier length (returned value)
252     \param base_address base address (returned value)
253     \param length_data_entry length of data entry (returned value)
254     \param length_starting length of starting 
255     \param length_implementation length of implementation defined data
256 */
257 YAZ_EXPORT
258 void yaz_marc_set_leader(yaz_marc_t mt, const char *leader,
259                          int *indicator_length,
260                          int *identifier_length,
261                          int *base_address,
262                          int *length_data_entry,
263                          int *length_starting,
264                          int *length_implementation);
265
266
267 /** \brief adds MARC comment string
268     \param mt handle
269     \param comment comment to be added)
270 */  
271 YAZ_EXPORT
272 void yaz_marc_add_comment(yaz_marc_t mt, char *comment);
273
274 /** \brief adds MARC annotation - printf interface
275     \param mt handle
276     \param fmt printf format string
277 */  
278 YAZ_EXPORT
279 void yaz_marc_cprintf(yaz_marc_t mt, const char *fmt, ...);
280
281 /** \brief adds subfield to MARC structure
282     \param mt handle
283     \param code_data code data buffer
284     \param code_data_len length of code data
285 */  
286 YAZ_EXPORT
287 void yaz_marc_add_subfield(yaz_marc_t mt,
288                            const char *code_data, size_t code_data_len);
289
290
291 /** \brief adds controlfield to MARC structure
292     \param mt handle
293     \param tag (e.g. "001"
294     \param data value for this tag
295     \param data_len length of data
296 */  
297 YAZ_EXPORT
298 void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
299                                const char *data, size_t data_len);
300
301
302 /** \brief adds controlfield to MARC structure using xml Nodes
303     \param mt handle
304     \param ptr_tag value of tag (TEXT xmlNode)
305     \param ptr_data value of data (TEXT xmlNode)
306 */  
307 YAZ_EXPORT
308 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
309                                    const xmlNode *ptr_data);
310
311
312 /** \brief adds datafield to MARC structure using strings
313     \param mt handle
314     \param tag value of tag as string
315     \param indicator indicator string
316     \param indicator_len length of indicator string
317 */  
318 YAZ_EXPORT
319 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
320                             const char *indicator, size_t indicator_len);
321
322 /** \brief adds datafield to MARC structure using xml Nodes
323     \param mt handle
324     \param ptr_tag value of tag (TEXT xmlNode)
325     \param indicator indicator string
326     \param indicator_len length of indicator string
327 */  
328 YAZ_EXPORT
329 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
330                                 const char *indicator, size_t indicator_len);
331
332
333 /** \brief returns memory for MARC handle
334     \param mt handle
335     \retval NMEM handle for MARC system
336 */  
337 YAZ_EXPORT
338 NMEM yaz_marc_get_nmem(yaz_marc_t mt);
339
340 /** \brief clears memory and MARC record
341     \param mt handle
342 */  
343 YAZ_EXPORT
344 void yaz_marc_reset(yaz_marc_t mt);
345
346 /** \brief gets debug level for MARC system
347     \param mt handle
348 */  
349 YAZ_EXPORT
350 int yaz_marc_get_debug(yaz_marc_t mt);
351
352 /** \brief convert MARC format type to format type(YAZ_MARC_..)
353     \param arg string
354     \returns -1 if arg is not a known format; YAZ_MARC_.. otherwise (OK)
355 */  
356 YAZ_EXPORT
357 int yaz_marc_decode_formatstr(const char *arg);
358
359 /** \brief enable writing of MARC XML records using Libxml2 
360     \param mt handle
361     \param enable 0=disable, 1=enable
362 */  
363 YAZ_EXPORT
364 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
365
366 /** \brief Performs "pretty" display of OPAC record to WRBUF */
367 YAZ_EXPORT void yaz_display_OPAC(WRBUF wrbuf, Z_OPACRecord *r, int flags);
368
369 /** \brief Performs "pretty" display of OPAC record to WRBUF using marc_t */
370 YAZ_EXPORT void yaz_opac_decode_wrbuf(yaz_marc_t mt, Z_OPACRecord *r, WRBUF wrbuf);
371
372
373 /** \brief flushes records
374     \param mt handle
375     \param wr WRBUF for output
376     \retval 0 OK
377     \retval -1 ERROR
378 */  
379 YAZ_EXPORT int yaz_marc_write_trailer(yaz_marc_t mt, WRBUF wr);
380
381 /** \brief enables record collection output
382     \param mt handle
383 */  
384 YAZ_EXPORT void yaz_marc_enable_collection(yaz_marc_t mt);
385
386 YAZ_END_CDECL
387
388 #endif
389 /*
390  * Local variables:
391  * c-basic-offset: 4
392  * indent-tabs-mode: nil
393  * End:
394  * vim: shiftwidth=4 tabstop=8 expandtab
395  */
396