.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Biblio::Isis 3pm" .TH Biblio::Isis 3pm "2021-12-26" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Biblio::Isis \- Read CDS/ISIS, WinISIS and IsisMarc database .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Biblio::Isis; \& \& my $isis = new Biblio::Isis( \& isisdb => \*(Aq./cds/cds\*(Aq, \& ); \& \& for(my $mfn = 1; $mfn <= $isis\->count; $mfn++) { \& print $isis\->to_ascii($mfn),"\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module will read \s-1ISIS\s0 databases created by \s-1DOS CDS/ISIS,\s0 WinIsis or IsisMarc. It can be used as perl-only alternative to OpenIsis module which seems to depriciate it's old \f(CW\*(C`XS\*(C'\fR bindings for perl. .PP It can create hash values from data in \s-1ISIS\s0 database (using \f(CW\*(C`to_hash\*(C'\fR), \&\s-1ASCII\s0 dump (using \f(CW\*(C`to_ascii\*(C'\fR) or just hash with field names and packed values (like \f(CW\*(C`^asomething^belse\*(C'\fR). .PP Unique feature of this module is ability to \f(CW\*(C`include_deleted\*(C'\fR records. It will also skip zero sized fields (OpenIsis has a bug in \s-1XS\s0 bindings, so fields which are zero sized will be filled with random junk from memory). .PP It also has support for identifiers (only if \s-1ISIS\s0 database is created by IsisMarc), see \f(CW\*(C`to_hash\*(C'\fR. .PP This module will always be slower than OpenIsis module which use C library. However, since it's written in perl, it's platform independent (so you don't need C compiler), and can be easily modified. I hope that it creates data structures which are easier to use than ones created by OpenIsis, so reduced time in other parts of the code should compensate for slower performance of this module (speed of reading \s-1ISIS\s0 database is rarely an issue). .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" Open \s-1ISIS\s0 database .PP .Vb 11 \& my $isis = new Biblio::Isis( \& isisdb => \*(Aq./cds/cds\*(Aq, \& read_fdt => 1, \& include_deleted => 1, \& hash_filter => sub { \& my ($v,$field_number) = @_; \& $v =~ s#foo#bar#g; \& }, \& debug => 1, \& join_subfields_with => \*(Aq ; \*(Aq, \& ); .Ve .PP Options are described below: .IP "isisdb" 5 .IX Item "isisdb" This is full or relative path to \s-1ISIS\s0 database files which include common prefix of \f(CW\*(C`.MST\*(C'\fR, and \f(CW\*(C`.XRF\*(C'\fR and optionally \f(CW\*(C`.FDT\*(C'\fR (if using \&\f(CW\*(C`read_fdt\*(C'\fR option) files. .Sp In this example it uses \f(CW\*(C`./cds/cds.MST\*(C'\fR and related files. .IP "read_fdt" 5 .IX Item "read_fdt" Boolean flag to specify if field definition table should be read. It's off by default. .IP "include_deleted" 5 .IX Item "include_deleted" Don't skip logically deleted records in \s-1ISIS.\s0 .IP "hash_filter" 5 .IX Item "hash_filter" Filter code ref which will be used before data is converted to hash. It will receive two arguments, whole line from current field (in \f(CW$_[0]\fR) and field number (in \f(CW$_[1]\fR). .IP "debug" 5 .IX Item "debug" Dump a \fBlot\fR of debugging output even at level 1. For even more increase level. .IP "join_subfields_with" 5 .IX Item "join_subfields_with" Define delimiter which will be used to join repeatable subfields. This option is included to support lagacy application written against version older than 0.21 of this module. By default, it disabled. See \*(L"to_hash\*(R". .IP "ignore_empty_subfields" 5 .IX Item "ignore_empty_subfields" Remove all empty subfields while reading from \s-1ISIS\s0 file. .SS "count" .IX Subsection "count" Return number of records in database .PP .Vb 1 \& print $isis\->count; .Ve .SS "fetch" .IX Subsection "fetch" Read record with selected \s-1MFN\s0 .PP .Vb 1 \& my $rec = $isis\->fetch(55); .Ve .PP Returns hash with keys which are field names and values are unpacked values for that field like this: .PP .Vb 4 \& $rec = { \& \*(Aq210\*(Aq => [ \*(Aq^aNew York^cNew York University press^dcop. 1988\*(Aq ], \& \*(Aq990\*(Aq => [ \*(Aq2140\*(Aq, \*(Aq88\*(Aq, \*(AqHAY\*(Aq ], \& }; .Ve .SS "mfn" .IX Subsection "mfn" Returns current \s-1MFN\s0 position .PP .Vb 1 \& my $mfn = $isis\->mfn; .Ve .SS "to_ascii" .IX Subsection "to_ascii" Returns \s-1ASCII\s0 output of record with specified \s-1MFN\s0 .PP .Vb 1 \& print $isis\->to_ascii(42); .Ve .PP This outputs something like this: .PP .Vb 4 \& 210 ^aNew York^cNew York University press^dcop. 1988 \& 990 2140 \& 990 88 \& 990 HAY .Ve .PP If \f(CW\*(C`read_fdt\*(C'\fR is specified when calling \f(CW\*(C`new\*(C'\fR it will display field names from \f(CW\*(C`.FDT\*(C'\fR file instead of numeric tags. .SS "to_hash" .IX Subsection "to_hash" Read record with specified \s-1MFN\s0 and convert it to hash .PP .Vb 1 \& my $hash = $isis\->to_hash($mfn); .Ve .PP It has ability to convert characters (using \f(CW\*(C`hash_filter\*(C'\fR) from \s-1ISIS\s0 database before creating structures enabling character re-mapping or quick fix-up of data. .PP This function returns hash which is like this: .PP .Vb 10 \& $hash = { \& \*(Aq210\*(Aq => [ \& { \& \*(Aqc\*(Aq => \*(AqNew York University press\*(Aq, \& \*(Aqa\*(Aq => \*(AqNew York\*(Aq, \& \*(Aqd\*(Aq => \*(Aqcop. 1988\*(Aq \& } \& ], \& \*(Aq990\*(Aq => [ \& \*(Aq2140\*(Aq, \& \*(Aq88\*(Aq, \& \*(AqHAY\*(Aq \& ], \& }; .Ve .PP You can later use that hash to produce any output from \s-1ISIS\s0 data. .PP If database is created using IsisMarc, it will also have to special fields which will be used for identifiers, \f(CW\*(C`i1\*(C'\fR and \f(CW\*(C`i2\*(C'\fR like this: .PP .Vb 9 \& \*(Aq200\*(Aq => [ \& { \& \*(Aqi1\*(Aq => \*(Aq1\*(Aq, \& \*(Aqi2\*(Aq => \*(Aq \*(Aq \& \*(Aqa\*(Aq => \*(AqGoa\*(Aq, \& \*(Aqf\*(Aq => \*(AqValdo D\e\*(AqArienzo\*(Aq, \& \*(Aqe\*(Aq => \*(Aqtipografie e tipografi nel XVI secolo\*(Aq, \& } \& ], .Ve .PP In case there are repeatable subfields in record, this will create following structure: .PP .Vb 3 \& \*(Aq900\*(Aq => [ { \& \*(Aqa\*(Aq => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ], \& }] .Ve .PP Or in more complex example of .PP .Vb 1 \& 902 ^aa1^aa2^aa3^bb1^aa4^bb2^cc1^aa5 .Ve .PP it will create .PP .Vb 3 \& 902 => [ \& { a => ["a1", "a2", "a3", "a4", "a5"], b => ["b1", "b2"], c => "c1" }, \& ], .Ve .PP This behaviour can be changed using \f(CW\*(C`join_subfields_with\*(C'\fR option to \*(L"new\*(R", in which case \f(CW\*(C`to_hash\*(C'\fR will always create single value for each subfield. This will change result to: .PP This method will also create additional field \f(CW000\fR with \s-1MFN.\s0 .PP There is also more elaborative way to call \f(CW\*(C`to_hash\*(C'\fR like this: .PP .Vb 4 \& my $hash = $isis\->to_hash({ \& mfn => 42, \& include_subfields => 1, \& }); .Ve .PP Each option controll creation of hash: .IP "mfn" 4 .IX Item "mfn" Specify \s-1MFN\s0 number of record .IP "include_subfields" 4 .IX Item "include_subfields" This option will create additional key in hash called \f(CW\*(C`subfields\*(C'\fR which will have original record subfield order and index to that subfield like this: .Sp .Vb 6 \& 902 => [ { \& a => ["a1", "a2", "a3", "a4", "a5"], \& b => ["b1", "b2"], \& c => "c1", \& subfields => ["a", 0, "a", 1, "a", 2, "b", 0, "a", 3, "b", 1, "c", 0, "a", 4], \& } ], .Ve .IP "join_subfields_with" 4 .IX Item "join_subfields_with" Define delimiter which will be used to join repeatable subfields. You can specify option here instead in \*(L"new\*(R" if you want to have per-record control. .IP "hash_filter" 4 .IX Item "hash_filter" You can override \f(CW\*(C`hash_filter\*(C'\fR defined in \*(L"new\*(R" using this option. .SS "tag_name" .IX Subsection "tag_name" Return name of selected tag .PP .Vb 1 \& print $isis\->tag_name(\*(Aq200\*(Aq); .Ve .SS "read_cnt" .IX Subsection "read_cnt" Read content of \f(CW\*(C`.CNT\*(C'\fR file and return hash containing it. .PP .Vb 1 \& print Dumper($isis\->read_cnt); .Ve .PP This function is not used by module (\f(CW\*(C`.CNT\*(C'\fR files are not required for this module to work), but it can be useful to examine your index (while debugging for example). .SS "unpack_cnt" .IX Subsection "unpack_cnt" Unpack one of two 26 bytes fixed length record in \f(CW\*(C`.CNT\*(C'\fR file. .PP Here is definition of record: .PP .Vb 12 \& off key description size \& 0: IDTYPE BTree type s \& 2: ORDN Nodes Order s \& 4: ORDF Leafs Order s \& 6: N Number of Memory buffers for nodes s \& 8: K Number of buffers for first level index s \& 10: LIV Current number of Index Levels s \& 12: POSRX Pointer to Root Record in N0x l \& 16: NMAXPOS Next Available position in N0x l \& 20: FMAXPOS Next available position in L0x l \& 24: ABNORMAL Formal BTree normality indicator s \& length: 26 bytes .Ve .PP This will fill \f(CW$self\fR object under \f(CW\*(C`cnt\*(C'\fR with hash. It's used by \f(CW\*(C`read_cnt\*(C'\fR. .SH "BUGS" .IX Header "BUGS" Some parts of \s-1CDS/ISIS\s0 documentation are not detailed enough to exmplain some variations in input databases which has been tested with this module. When I was in doubt, I assumed that OpenIsis's implementation was right (except for obvious bugs). .PP However, every effort has been made to test this module with as much databases (and programs that create them) as possible. .PP I would be very greatful for success or failure reports about usage of this module with databases from programs other than WinIsis and IsisMarc. I had tested this against ouput of one \f(CW\*(C`isis.dll\*(C'\fR\-based application, but I don't know any details about it's version. .SH "VERSIONS" .IX Header "VERSIONS" As this is young module, new features are added in subsequent version. It's a good idea to specify version when using this module like this: .PP .Vb 1 \& use Biblio::Isis 0.23 .Ve .PP Below is list of changes in specific version of module (so you can target older versions if you really have to): .IP "0.24" 8 .IX Item "0.24" Added \f(CW\*(C`ignore_empty_subfields\*(C'\fR .IP "0.23" 8 .IX Item "0.23" Added \f(CW\*(C`hash_filter\*(C'\fR to \*(L"to_hash\*(R" .Sp Fixed bug with documented \f(CW\*(C`join_subfields_with\*(C'\fR in \*(L"new\*(R" which wasn't implemented .IP "0.22" 8 .IX Item "0.22" Added field number when calling \f(CW\*(C`hash_filter\*(C'\fR .IP "0.21" 8 .IX Item "0.21" Added \f(CW\*(C`join_subfields_with\*(C'\fR to \*(L"new\*(R" and \*(L"to_hash\*(R". .Sp Added \f(CW\*(C`include_subfields\*(C'\fR to \*(L"to_hash\*(R". .IP "0.20" 8 .IX Item "0.20" Added \f(CW\*(C`$isis\->mfn\*(C'\fR, support for repeatable subfields and \&\f(CW\*(C`$isis\->to_hash({ mfn => 42, ... })\*(C'\fR calling convention .SH "AUTHOR" .IX Header "AUTHOR" .Vb 4 \& Dobrica Pavlinusic \& CPAN ID: DPAVLIN \& dpavlin@rot13.org \& http://www.rot13.org/~dpavlin/ .Ve .PP This module is based heavily on code from \f(CW\*(C`LIBISIS.PHP\*(C'\fR library to read \s-1ISIS\s0 files V0.1.1 written in php and (c) 2000 Franck Martin and released under \s-1LGPL.\s0 .SH "COPYRIGHT" .IX Header "COPYRIGHT" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module. .SH "SEE ALSO" .IX Header "SEE ALSO" Biblio::Isis::Manual for \s-1CDS/ISIS\s0 manual appendix F, G and H which describe file format .PP OpenIsis web site .PP perl4lib site