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