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.27 2007-01-24 15:13:20 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                                    char **result, int *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 /** \brief depricated */
 110 YAZ_EXPORT int marc_display(const char *buf, FILE *outf);
 111 /** \brief depricated */
 112 YAZ_EXPORT int marc_display_ex(const char *buf, FILE *outf, int debug);
 113 /** \brief depricated */
 114 YAZ_EXPORT int marc_display_exl(const char *buf, FILE *outf, int debug,
 115                                 int length);
 116 /** \brief depricated */
 117 YAZ_EXPORT int marc_display_wrbuf(const char *buf, WRBUF wr, int debug,
 118                                   int bsize);
 119 /** \brief depricated */
 120 YAZ_EXPORT int yaz_marc_decode(const char *buf, WRBUF wr,
 121                                int debug, int bsize, int xml);
 122
 123 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
 124 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
 125
 126 /** \brief modifies part of the MARC leader */
 127 YAZ_EXPORT void yaz_marc_modify_leader(yaz_marc_t mt, size_t off,
 128                                        const char *str);
 129
 130 /** \brief like atoi(3) except that it reads exactly len characters */
 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     Returns > 0 for OK (same as length), -1=ERROR
 157 */
 158 YAZ_EXPORT int yaz_marc_read_iso2709(yaz_marc_t mt,
 159                                      const char *buf, int bsize);
 160
 161 /** \brief read MARC lineformat from stream
 162     \param mt handle
 163     \param getbyte get one byte handler
 164     \param ungetbyte unget one byte handler
 165     \param client_data opaque data for handers
 166
 167     Parses MARC line record from stream
 168     Returns > 0 for OK (same as length), -1=ERROR
 169 */
 170 YAZ_EXPORT
 171 int yaz_marc_read_line(yaz_marc_t mt,
 172                        int (*getbyte)(void *client_data),
 173                        void (*ungetbyte)(int b, void *client_data),
 174                        void *client_data);
 175
 176 /** \brief parses MARCXML/MarcXchange record from xmlNode pointer
 177     \param mt handle
 178     \param ptr is a pointer to root xml node
 179
 180     Returns 0=OK, -1=ERROR
 181 */
 182 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);
 183
 184 /** \brief writes record in line format
 185     \param mt handle
 186     \param wrbuf WRBUF for output
 187
 188     Returns 0=OK, -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
 196     Sets leader[9]='a' . Returns 0=OK, -1=ERROR .
 197 */
 198 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
 199
 200 /** \brief writes record in MarcXchange XML
 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
 206     Returns 0=OK, -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     Returns 0=OK, -1=ERROR
 216 */
 217 YAZ_EXPORT int yaz_marc_write_iso2709(yaz_marc_t mt, WRBUF wrbuf);
 218
 219 /** \brief writes record in mode - given by yaz_marc_xml mode
 220     \param mt handle
 221     \param wrbuf WRBUF for output
 222     This function calls yaz_marc_write_iso2709, yaz_marc_write_marcxml,
 223     etc.. depending on mode given by yaz_marc_xml.
 224     Returns 0=OK, -1=ERROR
 225 */
 226 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
 227
 228 /** \brief writes MARC record as libxml2 tree
 229     \param mt handle
 230     \param root_ptr pointer to record node
 231     \param ns namespace of record (such as "http://www.loc.gov/MARC21/slim")
 232     \param format MarcXchange format (NULL for none)
 233     \param type MarcXchange format (NULL for none)
 234     \retval 0 Creation successful and *root_ptr is "record" node
 235     \retval -1 ERROR
 236 */
 237 YAZ_EXPORT
 238 int yaz_marc_write_xml(yaz_marc_t mt, xmlNode **root_ptr,
 239                        const char *ns,
 240                        const char *format,
 241                        const char *type);
 242
 243 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
 244     \param mt handle
 245     \param leader_spec
 246     \retval 0 OK
 247     \retval -1 ERROR
 248
 249     Spec takes form pos=val,pos=val,...
 250     where value is either a number (decimal char value) or a
 251     string in 'a', e.g. 9='a'
 252
 253 */
 254 YAZ_EXPORT int yaz_marc_leader_spec(yaz_marc_t mt, const char *leader_spec);
 255
 256
 257 /** \brief sets leader, validates it, and returns important values
 258     \param mt handle
 259     \param leader of the 24 byte leader to be set
 260     \param indicator_length indicator length (returned value)
 261     \param identifier_length identifier length (returned value)
 262     \param base_address base address (returned value)
 263     \param length_data_entry length of data entry (returned value)
 264     \param length_starting length of starting
 265     \param length_implementation length of implementation defined data
 266 */
 267 YAZ_EXPORT
 268 void yaz_marc_set_leader(yaz_marc_t mt, const char *leader,
 269                          int *indicator_length,
 270                          int *identifier_length,
 271                          int *base_address,
 272                          int *length_data_entry,
 273                          int *length_starting,
 274                          int *length_implementation);
 275
 276
 277 /** \brief adds MARC comment string
 278     \param mt handle
 279     \param comment comment to be added)
 280 */
 281 YAZ_EXPORT
 282 void yaz_marc_add_comment(yaz_marc_t mt, char *comment);
 283
 284 /** \brief adds MARC annotation - printf interface
 285     \param mt handle
 286     \param fmt printf format string
 287 */
 288 YAZ_EXPORT
 289 void yaz_marc_cprintf(yaz_marc_t mt, const char *fmt, ...);
 290
 291 /** \brief adds subfield to MARC structure
 292     \param mt handle
 293     \param code_data code data buffer
 294     \param code_data_len length of code data
 295 */
 296 YAZ_EXPORT
 297 void yaz_marc_add_subfield(yaz_marc_t mt,
 298                            const char *code_data, size_t code_data_len);
 299
 300
 301 /** \brief adds controlfield to MARC structure
 302     \param mt handle
 303     \param tag (e.g. "001"
 304     \param data value for this tag
 305     \param data_len length of data
 306 */
 307 YAZ_EXPORT
 308 void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
 309                                const char *data, size_t data_len);
 310
 311
 312 /** \brief adds controlfield to MARC structure using xml Nodes
 313     \param mt handle
 314     \param ptr_tag value of tag (TEXT xmlNode)
 315     \param ptr_data value of data (TEXT xmlNode)
 316 */
 317 YAZ_EXPORT
 318 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 319                                    const xmlNode *ptr_data);
 320
 321
 322 /** \brief adds datafield to MARC structure using strings
 323     \param mt handle
 324     \param tag value of tag as string
 325     \param indicator indicator string
 326     \param indicator_len length of indicator string
 327 */
 328 YAZ_EXPORT
 329 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
 330                             const char *indicator, size_t indicator_len);
 331
 332 /** \brief adds datafield to MARC structure using xml Nodes
 333     \param mt handle
 334     \param ptr_tag value of tag (TEXT xmlNode)
 335     \param indicator indicator string
 336     \param indicator_len length of indicator string
 337 */
 338 YAZ_EXPORT
 339 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
 340                                 const char *indicator, size_t indicator_len);
 341
 342
 343 /** \brief returns memory for MARC handle
 344     \param mt handle
 345     \retval NMEM handle for MARC system
 346 */
 347 YAZ_EXPORT
 348 NMEM yaz_marc_get_nmem(yaz_marc_t mt);
 349
 350 /** \brief clears memory and MARC record
 351     \param mt handle
 352 */
 353 YAZ_EXPORT
 354 void yaz_marc_reset(yaz_marc_t mt);
 355
 356 /** \brief gets debug level for MARC system
 357     \param mt handle
 358 */
 359 YAZ_EXPORT
 360 int yaz_marc_get_debug(yaz_marc_t mt);
 361
 362 /** \brief convert MARC format type to format type(YAZ_MARC_..)
 363     \param arg string
 364     \returns -1 if arg is not a known format; YAZ_MARC_.. otherwise (OK)
 365 */
 366 YAZ_EXPORT
 367 int yaz_marc_decode_formatstr(const char *arg);
 368
 369 /** \brief enable writing of MARC XML records using Libxml2
 370     \param mt handle
 371     \param enable 0=disable, 1=enable
 372 */
 373 YAZ_EXPORT
 374 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
 375
 376 YAZ_END_CDECL
 377
 378 #endif
 379 /*
 380  * Local variables:
 381  * c-basic-offset: 4
 382  * indent-tabs-mode: nil
 383  * End:
 384  * vim: shiftwidth=4 tabstop=8 expandtab
 385  */
 386