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