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