[Koha-cvs] CVS: koha-doc/en/sysadmin/maintenance command_line_scripts.xml,NONE,1.1

[skemotah]

Update of /cvsroot/koha/koha-doc/en/sysadmin/maintenance
In directory 
sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3238/en/sysadmin/maintenance

Added Files:
        command_line_scripts.xml 
Log Message:
Initial version of translation

--- NEW FILE ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
<article>
  <title>Command-line scripts</title>

  <articleinfo>
    <pubdate>2005-05-15</pubdate>

    <author>
      <firstname>Paul</firstname>

      <surname>POULAIN</surname>

      <email>paul AT koha-fr.org</email>
    </author>

    <authorblurb>
      <para>Consultant indépendant en logiciels libres, Koha "Release Manager"
      pour la version 2.0 puis 2.2, membre du comité de pilotage
      international</para>
    </authorblurb>

    <copyright>
      <year>2004</year>

      <year>2005</year>

      <holder>Paul Poulain</holder>
    </copyright>

    <legalnotice>
      <para>This document is related to Koha and is licensed to you under the
      GNU General Public License version 2 or later (<ulink
      
url="http://www.gnu.org/licenses/gpl.html";>http://www.gnu.org/licenses/gpl.html</ulink>).</para>

      <para>Koha-related documents may be reproduced and distributed in whole
      or in part, in any medium physical or electronic, as long as this
      copyright notice is retained on all copies.</para>

      <para>You may create a derivative work and distribute it provided that
      you:</para>

      <orderedlist>
        <listitem>
          <para>License the derivative work with this same license, or the
          Linux Documentation Project License (<ulink
          
url="http://www.tldp.org/COPYRIGHT.html";>http://www.tldp.org/COPYRIGHT.html</ulink>).
          Include a copyright notice and at least a pointer to the license
          used.</para>
        </listitem>

        <listitem>
          <para>Give due credit to previous authors and major
          contributors.</para>
        </listitem>
      </orderedlist>

      <para>Commercial redistribution is allowed and encouraged; however, the
      author would like to be notified of any such distributions.</para>

      <para>No liability for the contents of this document can be accepted.
      Use the concepts, examples and information at your own risk. There may
      be errors and inaccuracies, that could be damaging to your system.
      Proceed with caution, and although this is highly unlikely, the
      author(s) do not take any responsibility.</para>

      <para>All copyrights are held by their by their respective owners,
      unless specifically noted otherwise. Use of a term in this document
      should not be regarded as affecting the validity of any trademark or
      service mark. Naming of particular products or brands should not be seen
      as endorsements.</para>
    </legalnotice>

    <revhistory>
      <revision>
        <revnumber>2.2.2</revnumber>

        <date>2005-05-13</date>

        <authorinitials>jlj</authorinitials>

        <revdescription>
          <para>English translation by Jared Jennings</para>
        </revdescription>
      </revision>

      <revision>
        <revnumber>2.2.0</revnumber>

        <date>2005-02-25</date>

        <authorinitials>pp</authorinitials>

        <revdescription>
          <para>Version initiale</para>
        </revdescription>
      </revision>
    </revhistory>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <section>
      <title>General things</title>

      <para>This document presents the different scripts furnished with Koha.
      It does not talk about the scripts you can use to migrate your library
      records, but the ones a library can use for its daily function.</para>

      <para>For example, scripts to deal with late returns.</para>
    </section>

    <section>
      <title>Prerequisites</title>

      <para>Technical prerequisites:</para>

      <itemizedlist>
        <listitem>
          <para>Installation of Koha: we assume Koha to be installed. $KOHA is
          the directory where the library interface is found. If you type this
          command</para>

          <programlisting>ls -l $KOHA</programlisting>

          <para>You should see: <computeroutput>cgi-bin htdocs modules
          scripts</computeroutput></para>
        </listitem>

        <listitem>
          <para>The Koha configuration file is
          <filename>/etc/koha.conf</filename>. If not, you must specify where
          it is with this environment variable :</para>

          <programlisting>export 
KOHA_CONF=/etc/mykoha.configfile</programlisting>
        </listitem>

        <listitem>
          <para>All the commands we're about to use are used in a shell on the
          server.</para>
        </listitem>

        <listitem>
          <para>Open a shell (command line) and verify that Perl can find your
          modules:</para>

          <programlisting>export PERL5LIB=$KOHA/modules</programlisting>
        </listitem>

        <listitem>
          <para>The scripts are found in the directory
          <filename>scripts/misc</filename>. You should move them outside the
          Koha directory tree if you modify them, because each update of Koha
          will clobber them. (Actually, they will be backed up, but they won't
          be run by the <filename>crontab</filename> anymore.)</para>
        </listitem>

        <listitem>
          <para>All the scripts are suitable for placing in a table of
          periodic tasks (<filename>crontab</filename>). We will not deal with
          exactly how to do that here. For that, see the
          <filename>crontab</filename> documentation:</para>

          <programlisting>man crontab</programlisting>

          <para>and</para>

          <programlisting>man 5 crontab</programlisting>
        </listitem>

        <listitem>
          <para>All of these scripts worked, at one time. This does not mean
          they still work, nor that they will work in the version of Koha that
          you have downloaded. You are warned!</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section>
    <title>The scripts</title>

    <section>
      <title>overduenotice.pl</title>

      <para>This script looks for the patrons who have overdue items and sends
      notices.</para>

      <para>It isn't called with any command line parameters: all that is
      customizable is at the beginning of the script.</para>

      <para>It works this way :</para>

      <itemizedlist>
        <listitem>
          <para>Only the patrons who are in the "overduenoticerequired"
          category are dealt with. The others are ignored.</para>
        </listitem>

        <listitem>
          <para>The script sends an email to all the patrons who have given an
          email address.</para>
        </listitem>

        <listitem>
          <para>The script sends a list of all the overdue items to an
          internal email address, for going through manually.</para>
        </listitem>
      </itemizedlist>

      <para>Here are the parameters you can change :</para>

      <itemizedlist>
        <listitem>
          <para>the grace period before notification begins (7 days in the
          official version)</para>
        </listitem>

        <listitem>
          <para>how long to send notices before giving up (30 days in the
          official version). Usually, after this number of days the patron is
          suspended, but the suspension is <emphasis role="bold">not
          managed</emphasis> by this script.</para>
        </listitem>

        <listitem>
          <para>The "From" address that will appear in the emails to the
          patrons.</para>
        </listitem>

        <listitem>
          <para>The subject of the email.</para>
        </listitem>

        <listitem>
          <para>The body of the message. This is given in plain text, with 2
          exceptions :</para>

          <itemizedlist>
            <listitem>
              <para>special characters like <varname>\n</varname> (newline) or
              <varname>\t</varname> (tab).</para>
            </listitem>

            <listitem>
              <para>tags that will be replaced with their values by the
              script. These tags are surrounded by angle brackets:</para>

              <itemizedlist>
                <listitem>
                  <para>&lt;itemcount&gt; (the number of items which are
                  overdue)</para>
                </listitem>

                <listitem>
                  <para>&lt;firstname&gt; (the first name of the
                  patron)</para>
                </listitem>

                <listitem>
                  <para>&lt;lastname&gt; (the last name of the patron)</para>
                </listitem>

                <listitem>
                  <para>&lt;address1&gt;</para>
                </listitem>

                <listitem>
                  <para>&lt;address2&gt;</para>
                </listitem>

                <listitem>
                  <para>&lt;address3&gt;</para>
                </listitem>

                <listitem>
                  <para>&lt;city&gt; (the address)</para>
                </listitem>

                <listitem>
                  <para>&lt;postcode&gt; (the postal code)</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>fines2.pl</title>

      <para>This script calculates the overdue fines.</para>

      <para>It probably doesn't work anymore in version 2.2.</para>
    </section>

    <section>
      <title>notifys/fines.pl</title>

      <para>This script calculates the overdue fines.</para>

      <para>It probably doesn't work anymore in version 2.2.</para>
    </section>

    <section>
      <title>merge_authorities.pl</title>

      <para>This script merges two authorities passed as parameters.</para>

      <para>It recognizes the following options :</para>

      <itemizedlist>
        <listitem>
          <para>-h (or no option) : explain command-line parameters</para>
        </listitem>

        <listitem>
          <para>-f X (from), where X is an authority number. Combine X</para>
        </listitem>

        <listitem>
          <para>-t Y (to), where Y is an authority number. Combine with
          Y</para>
        </listitem>
      </itemizedlist>

      <para>All the bibliographical fields that pointed to the authority X
      point to the authority Y after the execution of the script.</para>

      <para>The script will:</para>

      <itemizedlist>
        <listitem>
          <para>Verify that the authorities are of the same kind.</para>
        </listitem>

        <listitem>
          <para>Display the authorities for validation</para>
        </listitem>

        <listitem>
          <para>Go ahead with the combination, if the user confirms it.</para>
        </listitem>
      </itemizedlist>

      <para>Upon confirmation, X becomes unused. It can be removed using
      Koha's graphical interface.</para>

      <para>There are two optional parameters:</para>

      <itemizedlist>
        <listitem>
          <para>-b (batch). In batch mode, the script looks for all the
          authorities that will be modified, and modifies all the
          bibliographical entries that use them. The authority numbers that
          will be changed are stored in a specific directory.</para>
        </listitem>

        <listitem>
          <para>-n (no confirmation), silent mode. If this switch is given,
          the script will not output anything and will do the merge without
          asking for confirmation.</para>
        </listitem>
      </itemizedlist>

      <para>Typically, the -b and -n switches are useful when the script is
      placed in the <filename>crontab</filename>, to update the
      bibliographical records that use an authority which has been
      modified.</para>

      <para>Here is an example, which I have in my
      <filename>crontab</filename>:</para>

      <programlisting>SHELL=/bin/bash

*/5 * * * * export PERL5LIB=/home/httpd/koha;export 
KOHA_CONF=/etc/koha.conf;/home/httpd/koha/scripts/misc/merge_authorities.pl -b 
-n</programlisting>
    </section>

    <section>
      <title>migration_tools/build_marc_word.pl</title>

      <para>A script which only concerns MARC21 installations. It reconstructs
      the marc_word table with only certain words, for better response
      times.</para>
    </section>

    <section>
      <title>migration_tools/bulkauthimport.pl</title>

      <para>A script that ought to migrate ISO2709 authority records, after
      the same model as bulkmarcimport.pl. It doesn't work in version
      2.2.2.</para>
    </section>

    <section>
      <title>migration_tools/cleanmarcdb.pl</title>

      <para>Doesn't work at this writing (Koha 2.2.2) but ought to be simple
      to correct.</para>
    </section>

    <section>
      <title>migration_tools/compare_iso_and_marc_parameters.pl</title>

      <para>Prints the list of MARC subfields which are used in an ISO2709
      file, but not declared in the cataloging table settings.</para>

      <para>This script helps in detecting errors in the settings.</para>

      <para>It accepts the following options:</para>

      <itemizedlist>
        <listitem>
          <para>-v or no option : print execution parameters.</para>
        </listitem>

        <listitem>
          <para>-file file.iso : the ISO file to compare to the catalog
          structure.</para>
        </listitem>

        <listitem>
          <para>-w : eliminates warnings if the ISO2709 file has format
          irregularities</para>
        </listitem>

        <listitem>
          <para>-c codetable : cataloging table from which to get the MARC
          parameters. If this option is omitted, the script will use the
          default cataloging table.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>migration_tools/dumpmarc.pl</title>

      <para>This script prints an ISO2709 file in a readable format.</para>

      <para>It takes the following options:</para>

      <itemizedlist>
        <listitem>
          <para>-v or no option : print execution parameters</para>
        </listitem>

        <listitem>
          <para>-file file.iso : the file to print out</para>
        </listitem>

        <listitem>
          <para>-n number : the record number to print (numbered by order in
          the file)</para>
        </listitem>

        <listitem>
          <para>-w : activate or deactivate warnings given if the file is not
          strictly ISO2709. If the script fails without -w, try again with -w,
          but know that your file is not ISO2709! If it works with the -w
          option, the defect is not that big. If there's a serious error, even
          using -w will end in failure.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>koha2marc.pl</title>

      <para>Only useful for libraries with an ancient version of Koha (1.2) or
      libraries which have set MARC=OFF, which isn't the case in any
      French-speaking library.</para>

      <para>This script reconstructs the MARC database from the non-MARC
      database.</para>

      <para>Caution: NEVER run this script if you have MARC set to ON, because
      you will erase a good portion of your records!!!</para>
    </section>

    <section>
      <title>rebuildnonmarc.pl</title>

      <para>This script does the opposite of the previous one. It is only
      useful for libraries having MARC=ON.</para>

      <para>It reconstructs Koha's non-MARC database from the MARC-Koha links
      settings and the MARC records.</para>

      <para>It must be run whenever something is modified in the MARC-Koha
      links settings. This shouldn't be too often.</para>

      <para>If you don't know whether you need to rerun this script, tell the
      Koha mailing list what you did, and we'll gladly tell you.</para>
    </section>

    <section>
      <title>rebuildthesaurus.pl</title>

      <para>A useless script, deprecated, it will be removed.</para>
    </section>

    <section>
      <title>update_marcsubjects.pl</title>

      <para>A script that updates the keywords in the MARC database. Only
      useful for libraries with MARC=OFF, which is not the case in any
      French-speaking library.</para>
    </section>

    <section>
      <title>migration_tools/buildLANG.pl</title>

      <para>A little script to reconstruct the list of language codes
      (authorized value list named LANG) from the contents of the
      database.</para>

      <para>It takes these parameters :</para>

      <itemizedlist>
        <listitem>
          <para>-h or no parameter : print the command-line options</para>
        </listitem>

        <listitem>
          <para>-s : the field/subfield containing the language codes (for
          example : "('101a','101b')" for UNIMARC)</para>
        </listitem>

        <listitem>
          <para>-d : delete the existing table before reconstructing it</para>
        </listitem>

        <listitem>
          <para>-l LANGUAGE : the language in which to generate the language
          codes. Only 'fr' and 'en' are available.</para>
        </listitem>
      </itemizedlist>

      <para>Note that in all cases the list of codes will be the ISO list,
      whether the language code is French or English.</para>

      <para>You can complete the list after it has been automatically
      constructed, but if you migrate a database, a missing value after the
      execution of this script is an unused value in your database; therefore
      it will be useless (unless you put in new data, of course).</para>
    </section>

    <section>
      <title>migration_tools/buildEDITORS.pl</title>

      <para>A script that automatically constructs the "EDITORS" authority
      list, used by the 210$c and 225$a plugins to figure out the author and
      the list of possible collections from the ISBN.</para>

      <para>For this script to work, the authority category must be defined,
      as indicated in the document "Set Parameters and Migrate your Data to
      Koha 2.2."</para>

      <para>It takes the following parameters :</para>

      <itemizedlist>
        <listitem>
          <para>-c (confirm). The script doesn't need any parameters. To keep
          it from running too fast, start it with -c, and it will stop before
          doing anything. You must use -c to make it reconstruct the EDITORS
          authority.</para>
        </listitem>

        <listitem>
          <para>-d : Erase the existing list before reconstructing it.
          Logically, you should use this option.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>migration_tools/build6xx.pl</title>

      <para>This script reconstructs the authorities lists from the records
      migrated into Koha. It doesn't work directly. You must modify the script
      to adapt it to the needs of your library, and the way you manage your
      authorities (authority structure: $a, $a and $b, $a and $x repeated,
      etc.)</para>

      <para>The present script is just a starting point and must be
      adapted.</para>
    </section>

    <section>
      <title>migration_tools/bulkmarcimport.pl</title>

      <para>This script imports an ISO2709 file into the active Koha database.
      It's the principal migration script. It works, but you would do better
      to clean your data as it's being imported; it's generally a good idea.
      If you want to do this, you must modify the script to adapt it to your
      cataloging standards. It works rather simply: it reads record by record,
      puts aside item records, imports the bibliographic record, and then puts
      in the item records.</para>

      <para>The details of this script's function are in the document "Set
      Parameters and Migrate Your Data to Koha 2.2."</para>
    </section>

    <section>
      <title>migration_tools/check_marc_definition.pl</title>

      <para>This script compares the records in the database and the
      cataloging structure. It prints a list of the fields which are in the
      database (probably imported by <filename>bulkmarcimport</filename>), but
      not used by the cataloging structure (Koha-MARC links), and a list of
      fields which are called for in the cataloging structure, but were never
      filled in.</para>

      <para>In the first case, it's certainly an error in your cataloging
      structure settings. If not, you ought to remove the field while
      importing (<filename>bulkmarcimport</filename>).</para>

      <para>In the second case, maybe it's an error, or maybe the field hasn't
      yet been used, and you want to start to use it.</para>
    </section>
  </section>
</article>