include/yaz/marcdisp.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) 1995-2012 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
  28 /**
  29  * \file marcdisp.h
  30  * \brief MARC conversion
  31  */
  32
  33 #ifndef MARCDISP_H
  34 #define MARCDISP_H
  35
  36 #include <yaz/yconfig.h>
  37 #include <stdio.h>
  38 #include <yaz/wrbuf.h>
  39
  40 #include <yaz/nmem.h>
  41 #include <yaz/xmltypes.h>
  42 #include <yaz/z-opac.h>
  43
  44 YAZ_BEGIN_CDECL
  45
  46 /** \brief a yaz_marc_t handle (private content) */
  47 typedef struct yaz_marc_t_ *yaz_marc_t;
  48
  49 /** \brief construct yaz_marc_t handle */
  50 YAZ_EXPORT yaz_marc_t yaz_marc_create(void);
  51
  52 /** \brief destroy yaz_marc_t handle */
  53 YAZ_EXPORT void yaz_marc_destroy(yaz_marc_t mt);
  54
  55 /** \brief set XML mode YAZ_MARC_LINE, YAZ_MARCXML, YAZ_MARC_ISO2709 ..
  56     \param mt MARC handle
  57     \param xmlmode mode.
  58
  59     This function ONLY affects yaz_marc_write_mode, yaz_marc_write_trailer.
  60 */
  61 YAZ_EXPORT void yaz_marc_xml(yaz_marc_t mt, int xmlmode);
  62
  63 /** \brief Output format: Line-format */
  64 #define YAZ_MARC_LINE      0
  65 /** \brief Output format: simplexml (no longer supported) */
  66 #define YAZ_MARC_SIMPLEXML 1
  67 /** \brief Output format: OAI-MARC (no longer supported) */
  68 #define YAZ_MARC_OAIMARC   2
  69 /** \brief Output format: MARCXML */
  70 #define YAZ_MARC_MARCXML   3
  71 /** \brief Output format: ISO2709 */
  72 #define YAZ_MARC_ISO2709   4
  73 /** \brief Output format: MarcXchange (ISO25577) */
  74 #define YAZ_MARC_XCHANGE   5
  75 /** \brief Output format: check only (no marc output) */
  76 #define YAZ_MARC_CHECK     6
  77 /** \brief Output format: Turbo MARC Index Data format (XML based) */
  78 #define YAZ_MARC_TURBOMARC 7
  79
  80 /** \brief set iconv handle for character set conversion */
  81 YAZ_EXPORT void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
  82
  83 /** \brief supply iconv handle for character set conversion */
  84 YAZ_EXPORT yaz_iconv_t yaz_marc_get_iconv(yaz_marc_t mt);
  85
  86 /** \brief set debug level
  87     \param mt handle
  88     \param level level, where 0=lowest, 1 more debug, 2 even more
  89 */
  90 YAZ_EXPORT void yaz_marc_debug(yaz_marc_t mt, int level);
  91
  92 /** \brief decodes ISO2709 buffer using straight buffers
  93     \param mt marc handle
  94     \param buf input buffer
  95     \param bsize size of buffer or (-1 if "any size")
  96     \param result result to be stored here
  97     \param rsize size of result (memory "owned" by yaz_marc_mt handle)
  98
  99     Decodes MARC in buf of size bsize.
 100     On success, result in *result with size *rsize.
 101     Returns -1 on error, or size of input record (>0) if OK
 102 */
 103 YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
 104                                    const char **result, size_t *rsize);
 105
 106 /** \brief decodes ISO2709/MARC buffer and stores result in WRBUF
 107     \param mt handle
 108     \param buf input buffer
 109     \param bsize size of buffer (-1 if "any size")
 110     \param wrbuf WRBUF for output
 111
 112     Decodes MARC in buf of size bsize.
 113     On success, result in wrbuf
 114     Returns -1 on error, or size of input record (>0) if OK
 115 */
 116 YAZ_EXPORT int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
 117                                      int bsize, WRBUF wrbuf);
 118
 119 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
 120 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
 121
 122 /** \brief modifies part of the MARC leader */
 123 YAZ_EXPORT void yaz_marc_modify_leader(yaz_marc_t mt, size_t off,
 124                                        const char *str);
 125
 126 /** \brief like atoi(3) except that it reads exactly len characters
 127     \param buf buffer to read
 128     \param len number of bytes to consider (being digits)
 129     \returns value
 130  */
 131 YAZ_EXPORT int atoi_n(const char *buf, int len);
 132
 133 /** \brief like atoi_n but checks for proper formatting
 134     \param buf buffer to read values from
 135     \param size size of buffer
 136     \param val value of decimal number (if successful)
 137     \retval 0 no value found (non-digits found)
 138     \retval 1 value found and *val holds value
 139 */
 140 YAZ_EXPORT
 141 int atoi_n_check(const char *buf, int size, int *val);
 142
 143 /** \brief MARC control char: record separator (29 Dec, 1D Hex) */
 144 #define ISO2709_RS 035
 145 /** \brief MARC control char: field separator (30 Dec, 1E Hex) */
 146 #define ISO2709_FS 036
 147 /** \brief MARC control char: identifier-field separator (31 Dec, 1F Hex) */
 148 #define ISO2709_IDFS 037
 149
 150 /** \brief read ISO2709/MARC record from buffer
 151     \param mt handle
 152     \param buf ISO2709 buffer of size bsize
 153     \param bsize size of buffer (-1 for unlimited size)
 154
 155     Parses ISO2709 record from supplied buffer
 156     \retval -1 ERROR
 157     \retval >0 OK (length)
 158 */
 159 YAZ_EXPORT int yaz_marc_read_iso2709(yaz_marc_t mt,
 160                                      const char *buf, int bsize);
 161
 162 /** \brief read MARC lineformat from stream
 163     \param mt handle
 164     \param getbyte get one byte handler
 165     \param ungetbyte unget one byte handler
 166     \param client_data opaque data for handers
 167     \retval -1 ERROR
 168     \retval >0 OK (length)
 169
 170     Parses MARC line record from stream
 171     Returns > 0 for OK (same as length), -1=ERROR
 172 */
 173 YAZ_EXPORT
 174 int yaz_marc_read_line(yaz_marc_t mt,
 175                        int (*getbyte)(void *client_data),
 176                        void (*ungetbyte)(int b, void *client_data),
 177                        void *client_data);
 178
 179 #if YAZ_HAVE_XML2
 180 /** \brief parses MARCXML/MarcXchange/TurboMARC record from xmlNode pointer
 181     \param mt handle
 182     \param ptr is a pointer to root xml node
 183     \retval 0 OK
 184     \retval -1 ERROR
 185 */
 186 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);
 187 #endif
 188
 189 /** \brief writes record in line format
 190     \param mt handle
 191     \param wrbuf WRBUF for output
 192     \retval 0 OK
 193     \retval -1 ERROR
 194 */
 195 YAZ_EXPORT int yaz_marc_write_line(yaz_marc_t mt, WRBUF wrbuf);
 196
 197 /** \brief writes record in MARCXML format
 198     \param mt handle
 199     \param wrbuf WRBUF for output
 200     \retval 0 OK
 201     \retval -1 ERROR
 202
 203     Sets leader[9]='a' .
 204 */
 205 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
 206
 207 /** \brief writes record in TurboMARC format
 208     \param mt handle
 209     \param wrbuf WRBUF for output
 210     \retval 0 OK
 211     \retval -1 ERROR
 212 */
 213 YAZ_EXPORT int yaz_marc_write_turbomarc(yaz_marc_t mt, WRBUF wrbuf);
 214
 215 /** \brief writes record in MarcXchange XML (ISO25577)
 216     \param mt handle
 217     \param wrbuf WRBUF for output
 218     \param format record format (e.g. "MARC21")
 219     \param type record type (e.g. Bibliographic)
 220     \retval 0 OK
 221     \retval -1 ERROR
 222 */
 223 YAZ_EXPORT int yaz_marc_write_marcxchange(yaz_marc_t mt, WRBUF wrbuf,
 224                                           const char *format,
 225                                           const char *type);
 226
 227 /** \brief writes record in ISO2709 format
 228     \param mt handle
 229     \param wrbuf WRBUF for output
 230     \retval 0 OK
 231     \retval -1 ERROR
 232 */
 233 YAZ_EXPORT int yaz_marc_write_iso2709(yaz_marc_t mt, WRBUF wrbuf);
 234
 235 /** \brief writes record in mode - given by yaz_marc_xml mode
 236     \param mt handle
 237     \param wrbuf WRBUF for output
 238     \retval 0 OK
 239     \retval -1 ERROR
 240
 241     This function calls yaz_marc_write_iso2709, yaz_marc_write_marcxml,
 242     etc.. depending on mode given by yaz_marc_xml.
 243 */
 244 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
 245
 246 #if YAZ_HAVE_XML2
 247 /** \brief writes MARC record as libxml2 tree
 248     \param mt handle
 249     \param root_ptr pointer to record node
 250     \param ns namespace of record (such as "http://www.loc.gov/MARC21/slim")
 251     \param format MarcXchange format (NULL for none)
 252     \param type MarcXchange format (NULL for none)
 253     \retval 0 Creation successful and *root_ptr is "record" node
 254     \retval -1 ERROR
 255 */
 256 YAZ_EXPORT
 257 int yaz_marc_write_xml(yaz_marc_t mt, xmlNode **root_ptr,
 258                        const char *ns,
 259                        const char *format,
 260                        const char *type);
 261 #endif
 262
 263 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
 264     \param mt handle
 265     \param leader_spec
 266     \retval 0 OK
 267     \retval -1 ERROR
 268
 269     Spec takes form pos=val,pos=val,...
 270     where value is either a number (decimal char value) or a
 271     string in 'a', e.g. 9='a'
 272
 273 */
 274 YAZ_EXPORT int yaz_marc_leader_spec(yaz_marc_t mt, const char *leader_spec);
 275
 276
 277 /** \brief sets leader, validates it, and returns important values
 278     \param mt handle
 279     \param leader of the 24 byte leader to be set
 280     \param indicator_length indicator length (returned value)
 281     \param identifier_length identifier length (returned value)
 282     \param base_address base address (returned value)
 283     \param length_data_entry length of data entry (returned value)
 284     \param length_starting length of starting
 285     \param length_implementation length of implementation defined data
 286 */
 287 YAZ_EXPORT
 288 void yaz_marc_set_leader(yaz_marc_t mt, const char *leader,
 289                          int *indicator_length,
 290                          int *identifier_length,
 291                          int *base_address,
 292                          int *length_data_entry,
 293                          int *length_starting,
 294                          int *length_implementation);
 295
 296
 297 /** \brief adds MARC comment string
 298     \param mt handle
 299     \param comment comment to be added)
 300 */
 301 YAZ_EXPORT
 302 void yaz_marc_add_comment(yaz_marc_t mt, char *comment);
 303
 304 /** \brief adds MARC annotation - printf interface
 305     \param mt handle
 306     \param fmt printf format string
 307 */
 308 YAZ_EXPORT
 309 void yaz_marc_cprintf(yaz_marc_t mt, const char *fmt, ...);
 310
 311 /** \brief adds subfield to MARC structure
 312     \param mt handle
 313     \param code_data code data buffer
 314     \param code_data_len length of code data
 315 */
 316 YAZ_EXPORT
 317 void yaz_marc_add_subfield(yaz_marc_t mt,
 318                            const char *code_data, size_t code_data_len);
 319
 320
 321 /** \brief adds controlfield to MARC structure
 322     \param mt handle
 323     \param tag (e.g. "001"
 324     \param data value for this tag
 325     \param data_len length of data
 326 */
 327 YAZ_EXPORT
 328 void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
 329                                const char *data, size_t data_len);
 330
 331
 332 #if YAZ_HAVE_XML2
 333 /** \brief adds controlfield to MARC structure using xml Nodes
 334     \param mt handle
 335     \param ptr_tag value of tag (TEXT xmlNode)
 336     \param ptr_data value of data (TEXT xmlNode)
 337 */
 338 YAZ_EXPORT
 339 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 340                                    const xmlNode *ptr_data);
 341
 342 /** \brief adds controlfield to MARC structure using xml Nodes for data
 343     \param mt handle
 344     \param tag string tag
 345     \param ptr_data value of data (TEXT xmlNode)
 346 */
 347 YAZ_EXPORT
 348 void yaz_marc_add_controlfield_xml2(yaz_marc_t mt, char *tag,
 349                                     const xmlNode *ptr_data);
 350 #endif
 351
 352 /** \brief adds datafield to MARC structure using strings
 353     \param mt handle
 354     \param tag value of tag as string
 355     \param indicator indicator string
 356     \param indicator_len length of indicator string
 357 */
 358 YAZ_EXPORT
 359 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
 360                             const char *indicator, size_t indicator_len);
 361
 362 #if YAZ_HAVE_XML2
 363 /** \brief adds datafield to MARC structure using xml Nodes
 364     \param mt handle
 365     \param ptr_tag value of tag (TEXT xmlNode)
 366     \param indicator indicator string
 367     \param indicator_len length of indicator string
 368 */
 369 YAZ_EXPORT
 370 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 371                                 const char *indicator, size_t indicator_len);
 372
 373 /** \brief adds datafield to MARC structure using xml Nodes
 374     \param mt handle
 375     \param tag_value string value (pointer copied verbatim, not strdupped)
 376     \param indicators indicator string ; pointer copied verbatim; not strdupped
 377 */
 378 YAZ_EXPORT
 379 void yaz_marc_add_datafield_xml2(yaz_marc_t mt, char *tag_value,
 380                                  char *indicators);
 381
 382 #endif
 383
 384 /** \brief returns memory for MARC handle
 385     \param mt handle
 386     \retval NMEM handle for MARC system
 387 */
 388 YAZ_EXPORT
 389 NMEM yaz_marc_get_nmem(yaz_marc_t mt);
 390
 391 /** \brief clears memory and MARC record
 392     \param mt handle
 393 */
 394 YAZ_EXPORT
 395 void yaz_marc_reset(yaz_marc_t mt);
 396
 397 /** \brief gets debug level for MARC system
 398     \param mt handle
 399 */
 400 YAZ_EXPORT
 401 int yaz_marc_get_debug(yaz_marc_t mt);
 402
 403 /** \brief Converts MARC format type to format type(YAZ_MARC_..)
 404     \param arg string
 405     \retval -1 unknown format (bad arg)
 406     \retval >= 0 OK (one of YAZ_MARC - values)
 407 */
 408 YAZ_EXPORT
 409 int yaz_marc_decode_formatstr(const char *arg);
 410
 411 /** \brief Enables or disables writing of MARC XML records using Libxml2
 412     \param mt handle
 413     \param enable 0=disable, 1=enable
 414 */
 415 YAZ_EXPORT
 416 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
 417
 418 /** \brief Performs "pretty" display of OPAC record to WRBUF using marc_t
 419     \param mt handle
 420     \param r OPAC record
 421     \param wrbuf WRBUF for resulting display string
 422
 423     This function uses iconv_handle of yaz_marc_t for character set
 424     conversion of both OPAC + ISO2709 part.
 425     \*/
 426 YAZ_EXPORT void yaz_opac_decode_wrbuf(yaz_marc_t mt, Z_OPACRecord *r,
 427                                       WRBUF wrbuf);
 428
 429 /** \brief Performs "pretty" display of OPAC record to WRBUF using marc_t
 430     \param mt handle
 431     \param r OPAC record
 432     \param wrbuf WRBUF for resulting display string
 433     \param cd iconv handle for OPAC content (not ISO2709 part)
 434
 435     This function uses iconv handle of yaz_marc_t for character set
 436     conversion of ISO2709 part and supplied handle (cd) for OPAC part.
 437     \*/
 438 YAZ_EXPORT void yaz_opac_decode_wrbuf2(yaz_marc_t mt, Z_OPACRecord *r,
 439                                        WRBUF wrbuf, yaz_iconv_t cd);
 440
 441 /** \brief flushes records
 442     \param mt handle
 443     \param wr WRBUF for output
 444     \retval 0 OK
 445     \retval -1 ERROR
 446 */
 447 YAZ_EXPORT int yaz_marc_write_trailer(yaz_marc_t mt, WRBUF wr);
 448
 449 /** \brief enables record collection output
 450     \param mt handle
 451 */
 452 YAZ_EXPORT void yaz_marc_enable_collection(yaz_marc_t mt);
 453
 454 YAZ_END_CDECL
 455
 456 #endif
 457 /*
 458  * Local variables:
 459  * c-basic-offset: 4
 460  * c-file-style: "Stroustrup"
 461  * indent-tabs-mode: nil
 462  * End:
 463  * vim: shiftwidth=4 tabstop=8 expandtab
 464  */
 465