include/yaz/marcdisp.h

   1 /*
   2  * Copyright (c) 1995-2007, 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.30 2007-12-17 20:59:30 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 supply iconv handle for character set conversion .. */
  75 YAZ_EXPORT void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
  76
  77 /** \brief set debug level
  78     \param mt handle
  79     \param level level, where 0=lowest, 1 more debug, 2 even more
  80 */
  81 YAZ_EXPORT void yaz_marc_debug(yaz_marc_t mt, int level);
  82
  83 /** \brief decodes ISO2709 buffer using straight buffers
  84     \param mt marc handle
  85     \param buf input buffer
  86     \param bsize size of buffer or (-1 if "any size")
  87     \param result result to be stored here
  88     \param rsize size of result (memory "owned" by yaz_marc_mt handle)
  89
  90     Decodes MARC in buf of size bsize.
  91     On success, result in *result with size *rsize.
  92     Returns -1 on error, or size of input record (>0) if OK
  93 */
  94 YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
  95                                    const char **result, size_t *rsize);
  96
  97 /** \brief decodes ISO2709/MARC buffer and stores result in WRBUF
  98     \param mt handle
  99     \param buf input buffer
 100     \param bsize size of buffer (-1 if "any size")
 101     \param wrbuf WRBUF for output
 102
 103     Decodes MARC in buf of size bsize.
 104     On success, result in wrbuf
 105     Returns -1 on error, or size of input record (>0) if OK
 106 */
 107 YAZ_EXPORT int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
 108                                      int bsize, WRBUF wrbuf);
 109
 110 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
 111 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
 112
 113 /** \brief modifies part of the MARC leader */
 114 YAZ_EXPORT void yaz_marc_modify_leader(yaz_marc_t mt, size_t off,
 115                                        const char *str);
 116
 117 /** \brief like atoi(3) except that it reads exactly len characters */
 118 YAZ_EXPORT int atoi_n(const char *buf, int len);
 119
 120 /** \brief like atoi_n but checks for proper formatting
 121     \param buf buffer to read values from
 122     \param size size of buffer
 123     \param val value of decimal number (if successful)
 124     \retval 0 no value found (non-digits found)
 125     \retval 1 value found and *val holds value
 126 */
 127 YAZ_EXPORT
 128 int atoi_n_check(const char *buf, int size, int *val);
 129
 130 /** \brief MARC control char: record separator (29 Dec, 1D Hex) */
 131 #define ISO2709_RS 035
 132 /** \brief MARC control char: field separator (30 Dec, 1E Hex) */
 133 #define ISO2709_FS 036
 134 /** \brief MARC control char: identifier-field separator (31 Dec, 1F Hex) */
 135 #define ISO2709_IDFS 037
 136
 137 /** \brief read ISO2709/MARC record from buffer
 138     \param mt handle
 139     \param buf ISO2709 buffer of size bsize
 140     \param bsize size of buffer (-1 for unlimited size)
 141
 142     Parses ISO2709 record from supplied buffer
 143     Returns > 0 for OK (same as length), -1=ERROR
 144 */
 145 YAZ_EXPORT int yaz_marc_read_iso2709(yaz_marc_t mt,
 146                                      const char *buf, int bsize);
 147
 148 /** \brief read MARC lineformat from stream
 149     \param mt handle
 150     \param getbyte get one byte handler
 151     \param ungetbyte unget one byte handler
 152     \param client_data opaque data for handers
 153
 154     Parses MARC line record from stream
 155     Returns > 0 for OK (same as length), -1=ERROR
 156 */
 157 YAZ_EXPORT
 158 int yaz_marc_read_line(yaz_marc_t mt,
 159                        int (*getbyte)(void *client_data),
 160                        void (*ungetbyte)(int b, void *client_data),
 161                        void *client_data);
 162
 163 /** \brief parses MARCXML/MarcXchange record from xmlNode pointer
 164     \param mt handle
 165     \param ptr is a pointer to root xml node
 166
 167     Returns 0=OK, -1=ERROR
 168 */
 169 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);
 170
 171 /** \brief writes record in line format
 172     \param mt handle
 173     \param wrbuf WRBUF for output
 174
 175     Returns 0=OK, -1=ERROR
 176 */
 177 YAZ_EXPORT int yaz_marc_write_line(yaz_marc_t mt, WRBUF wrbuf);
 178
 179 /** \brief writes record in MARCXML format
 180     \param mt handle
 181     \param wrbuf WRBUF for output
 182
 183     Sets leader[9]='a' . Returns 0=OK, -1=ERROR .
 184 */
 185 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
 186
 187 /** \brief writes record in MarcXchange XML
 188     \param mt handle
 189     \param wrbuf WRBUF for output
 190     \param format record format (e.g. "MARC21")
 191     \param type record type (e.g. Bibliographic)
 192
 193     Returns 0=OK, -1=ERROR
 194 */
 195 YAZ_EXPORT int yaz_marc_write_marcxchange(yaz_marc_t mt, WRBUF wrbuf,
 196                                           const char *format,
 197                                           const char *type);
 198
 199 /** \brief writes record in ISO2709 format
 200     \param mt handle
 201     \param wrbuf WRBUF for output
 202     Returns 0=OK, -1=ERROR
 203 */
 204 YAZ_EXPORT int yaz_marc_write_iso2709(yaz_marc_t mt, WRBUF wrbuf);
 205
 206 /** \brief writes record in mode - given by yaz_marc_xml mode
 207     \param mt handle
 208     \param wrbuf WRBUF for output
 209     This function calls yaz_marc_write_iso2709, yaz_marc_write_marcxml,
 210     etc.. depending on mode given by yaz_marc_xml.
 211     Returns 0=OK, -1=ERROR
 212 */
 213 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
 214
 215 /** \brief writes MARC record as libxml2 tree
 216     \param mt handle
 217     \param root_ptr pointer to record node
 218     \param ns namespace of record (such as "http://www.loc.gov/MARC21/slim")
 219     \param format MarcXchange format (NULL for none)
 220     \param type MarcXchange format (NULL for none)
 221     \retval 0 Creation successful and *root_ptr is "record" node
 222     \retval -1 ERROR
 223 */
 224 YAZ_EXPORT
 225 int yaz_marc_write_xml(yaz_marc_t mt, xmlNode **root_ptr,
 226                        const char *ns,
 227                        const char *format,
 228                        const char *type);
 229
 230 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
 231     \param mt handle
 232     \param leader_spec
 233     \retval 0 OK
 234     \retval -1 ERROR
 235
 236     Spec takes form pos=val,pos=val,...
 237     where value is either a number (decimal char value) or a
 238     string in 'a', e.g. 9='a'
 239
 240 */
 241 YAZ_EXPORT int yaz_marc_leader_spec(yaz_marc_t mt, const char *leader_spec);
 242
 243
 244 /** \brief sets leader, validates it, and returns important values
 245     \param mt handle
 246     \param leader of the 24 byte leader to be set
 247     \param indicator_length indicator length (returned value)
 248     \param identifier_length identifier length (returned value)
 249     \param base_address base address (returned value)
 250     \param length_data_entry length of data entry (returned value)
 251     \param length_starting length of starting
 252     \param length_implementation length of implementation defined data
 253 */
 254 YAZ_EXPORT
 255 void yaz_marc_set_leader(yaz_marc_t mt, const char *leader,
 256                          int *indicator_length,
 257                          int *identifier_length,
 258                          int *base_address,
 259                          int *length_data_entry,
 260                          int *length_starting,
 261                          int *length_implementation);
 262
 263
 264 /** \brief adds MARC comment string
 265     \param mt handle
 266     \param comment comment to be added)
 267 */
 268 YAZ_EXPORT
 269 void yaz_marc_add_comment(yaz_marc_t mt, char *comment);
 270
 271 /** \brief adds MARC annotation - printf interface
 272     \param mt handle
 273     \param fmt printf format string
 274 */
 275 YAZ_EXPORT
 276 void yaz_marc_cprintf(yaz_marc_t mt, const char *fmt, ...);
 277
 278 /** \brief adds subfield to MARC structure
 279     \param mt handle
 280     \param code_data code data buffer
 281     \param code_data_len length of code data
 282 */
 283 YAZ_EXPORT
 284 void yaz_marc_add_subfield(yaz_marc_t mt,
 285                            const char *code_data, size_t code_data_len);
 286
 287
 288 /** \brief adds controlfield to MARC structure
 289     \param mt handle
 290     \param tag (e.g. "001"
 291     \param data value for this tag
 292     \param data_len length of data
 293 */
 294 YAZ_EXPORT
 295 void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
 296                                const char *data, size_t data_len);
 297
 298
 299 /** \brief adds controlfield to MARC structure using xml Nodes
 300     \param mt handle
 301     \param ptr_tag value of tag (TEXT xmlNode)
 302     \param ptr_data value of data (TEXT xmlNode)
 303 */
 304 YAZ_EXPORT
 305 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 306                                    const xmlNode *ptr_data);
 307
 308
 309 /** \brief adds datafield to MARC structure using strings
 310     \param mt handle
 311     \param tag value of tag as string
 312     \param indicator indicator string
 313     \param indicator_len length of indicator string
 314 */
 315 YAZ_EXPORT
 316 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
 317                             const char *indicator, size_t indicator_len);
 318
 319 /** \brief adds datafield to MARC structure using xml Nodes
 320     \param mt handle
 321     \param ptr_tag value of tag (TEXT xmlNode)
 322     \param indicator indicator string
 323     \param indicator_len length of indicator string
 324 */
 325 YAZ_EXPORT
 326 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 327                                 const char *indicator, size_t indicator_len);
 328
 329
 330 /** \brief returns memory for MARC handle
 331     \param mt handle
 332     \retval NMEM handle for MARC system
 333 */
 334 YAZ_EXPORT
 335 NMEM yaz_marc_get_nmem(yaz_marc_t mt);
 336
 337 /** \brief clears memory and MARC record
 338     \param mt handle
 339 */
 340 YAZ_EXPORT
 341 void yaz_marc_reset(yaz_marc_t mt);
 342
 343 /** \brief gets debug level for MARC system
 344     \param mt handle
 345 */
 346 YAZ_EXPORT
 347 int yaz_marc_get_debug(yaz_marc_t mt);
 348
 349 /** \brief convert MARC format type to format type(YAZ_MARC_..)
 350     \param arg string
 351     \returns -1 if arg is not a known format; YAZ_MARC_.. otherwise (OK)
 352 */
 353 YAZ_EXPORT
 354 int yaz_marc_decode_formatstr(const char *arg);
 355
 356 /** \brief enable writing of MARC XML records using Libxml2
 357     \param mt handle
 358     \param enable 0=disable, 1=enable
 359 */
 360 YAZ_EXPORT
 361 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
 362
 363 /** \brief Performs "pretty" display of OPAC record to WRBUF */
 364 YAZ_EXPORT void yaz_display_OPAC(WRBUF wrbuf, Z_OPACRecord *r, int flags);
 365
 366 /** \brief Performs "pretty" display of OPAC record to WRBUF using marc_t */
 367 YAZ_EXPORT void yaz_opac_decode_wrbuf(yaz_marc_t mt, Z_OPACRecord *r, WRBUF wrbuf);
 368
 369
 370 /** \brief flushes records
 371     \param mt handle
 372     \param wrbuf WRBUF for output
 373     \retval 0 OK
 374     \retval -1 ERROR
 375 */
 376 YAZ_EXPORT int yaz_marc_write_trailer(yaz_marc_t mt, WRBUF wr);
 377
 378 /** \brief enables record collection output
 379     \param mt handle
 380 */
 381 YAZ_EXPORT void yaz_marc_enable_collection(yaz_marc_t mt);
 382
 383 YAZ_END_CDECL
 384
 385 #endif
 386 /*
 387  * Local variables:
 388  * c-basic-offset: 4
 389  * indent-tabs-mode: nil
 390  * End:
 391  * vim: shiftwidth=4 tabstop=8 expandtab
 392  */
 393