include/yaz/marcdisp.h

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