<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-gui-C.dtd">
<!-- (Do not remove this comment block.)
Version: 1.0.0
Last modified: August 08th 2021

Maintainers:
  xxx
Author:
  TANIGUCHI Yasuaki <yasuakit@gmail.com>
  Christian Wehling <christian.wehling@web.de>
Translators:
  (translators put your name and email here)
-->
<chapter id="finance-quote"
         xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Setting Up the Quote Retrieval</title>

  <abstract>
    <para>If you have more than a couple of commodities, you will tire of having to update their quotes
      constantly. &app; has the ability to automatically download the most recent quote for your
      commodities using the Internet. This is accomplished through the &app-perl; module &app-fq;,
      which must be installed in order to activate this feature.
    </para>
  </abstract>

  <itemizedlist>
    <title>Prerequisites for an Online Quote update with &app-fq; are</title>

    <listitem>
      <para>the &app-perl; language interpreter and
      </para>
    </listitem>

    <listitem>
      <para>the &app-perl;-module &app-fq; with any dependencies.
      </para>
    </listitem>
  </itemizedlist>

  <note>
    <para>If you get stuck while performing the steps described here, you can reach many helpful users on the
      channels mentioned under <xref linkend="more_help" />.
    </para>
  </note>

  <para>You can also leave out this step and manually update your stock quotes.
  </para>

  <sect1 id="finance-quote-perl-install">
    <title>Installing &app-perl;</title>

    <abstract>
      <para>The installation of &app-perl; is essentially dependent on the operating system used. The effort for
        installation is low and is described in this section.
      </para>
    </abstract>

    <para>To check if &app-perl; is already installed on your system, call the command
      <userinput>perl -v</userinput> in the terminal.
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
    <informalexample><?dbfo pgwide="1"?>
<screen language="console">$ perl -v
This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-thread-multi
</screen>
    </informalexample>
      If you are shown the version number of the &app-perl; interpreter, skip the next details
      and continue instead with <xref linkend="finance-quote-install" />.
    </para>

    <procedure>
      <title>On &lin;</title>

      <step>
        <para>On most systems &app-perl; is probably already installed. If with the previous command does not show
          a version, then the easiest way is to use your system&rsquo;s package manager for installation.
        </para>
      </step>

      <step>
        <para>When using the &app; &flatpak; package, &app-perl; and &app-fq; are already functionally installed.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>On &mac;</title>

      <step>
        <para>&app-perl; is normally already set up under &mac;.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>On &win;</title>

      <step>
        <para>Under &win; run the program &mc.start.win-install-fq; to run. This will
          install <ulink url="&url-wp-en;Strawberry_Perl">Strawberry Perl</ulink>.
          <footnote>
            <para>&app; Version 2.2.6 and before require <ulink url="&url-wp-en;ActivePerl">ActivePerl</ulink>. in
              version 5.8.
            </para>
          </footnote>

          <footnote>
            <para>&app; Version 2.4 and before require <ulink url="&url-wp-en;ActivePerl">ActivePerl</ulink> Version
              5.16.3 and later.
            </para>
          </footnote>
        </para>
      </step>

      <step>
        <para>For execution you need <emphasis>Administrator privilegies</emphasis>, which are requested in the
          dialog. The installation can take more then 15 minutes.
        </para>
      </step>

      <step>
        <para>If during the installation the error message <computeroutput>No such file or directory
          </computeroutput> or <computeroutput>permission denied</computeroutput> are displayed,
          then it may help to disable the antivirus software temporarily.
        </para>
      </step>
    </procedure>

    <tip>
      <para>Afterwards it&rsquo;s a good idea to include the folder where &app; is installed,
        under &win; e.g. <userinput><replaceable>C:\Program Files (x86)\gnucash\bin</replaceable></userinput>,
        to your <envar>PATH</envar> environment variable.
        This way it&rsquo;s easier for you to use some <xref linkend="finance-quote-helper" /> when needed.
        Please refer to the documentation for your operating system for more information.
      </para>
    </tip>
  </sect1>

  <sect1 id="finance-quote-install">
    <title>Installing &app-fq;</title>

    <para>To determine if the &app-perl; module &app-fq; is already installed on your system, type
      <userinput>perldoc Finance::Quote</userinput> in a terminal window and check to see if there is
      any documentation
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
    <informalexample><?dbfo pgwide="1"?>
<screen language="console">
$ perldoc Finance::Quote
NAME
    Finance::Quote - Get stock and mutual fund quotes from various exchanges

SYNOPSIS
       [...]
</screen>
    </informalexample>
      available. If you are now shown documentation, then &app-fq; is already installed and you can
      configure periodical quotes update as described in <xref linkend="finance-quote-scheduler" />.
      If no documentation is displayed, you will have to continue with this chapter.
    </para>

    <para>The process of installing &app-fq; depends on the system. For the different supported systems, you
      can follow the instructions below:
    </para>

    <procedure>
      <title>On &lin;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Run the <userinput>gnc-fq-check</userinput> command to verify that the program is already in a directory
          that is entered in the <envar>PATH</envar> environment variable.
          <footnote>
            <simpara>If you&rsquo;ve installed &app; packages provided by your distribution,
              <filename>gnc-fq-check</filename> must be on your <envar>PATH</envar>. The currentness of your
              distribution can be checked under
              <ulink url="&url-repo;perl:finance-quote/versions"><citetitle>&app-fq;-
              versions</citetitle></ulink>.
            </simpara>
          </footnote>
        </simpara>
      </step>

      <step>
        <simpara>Next, update with <userinput>sudo gnc-fq-update</userinput>
          or <userinput>su -c gnc-fq-update</userinput> with root privileges
          &app-fq;. It depends on your distribution. For more information,
          see the next chapter at <xref linkend="gnc-fq-update" />.
        </simpara>
      </step>

      <step>
        <simpara>Run <userinput>gnc-fq-dump</userinput> to check &app-fq; works properly. This program returns the
          version number of &app-fq; module currently installed as well as a list of sources
          available via the &app-fq; module. It will also inform you if there is a problem with your
          installation or if it is missing, and may suggest a fix.
        </simpara>
      </step>
    </procedure>

    <procedure>
      <title>On &mac;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Install &app-xcode;
          <footnote>
            <para>You can install &app-xcode; from the App Store or install the
              much smaller Xcode command line tools by running <userinput>
              sudo xcode-select --install</userinput> from a Terminal.app prompt.
            </para>
          </footnote>
         if it is not installed. It contains devel tools, which are required
         by CPAN to build and test the needed &app-fq; modules.
        </simpara>
      </step>

      <step>
        <simpara>Run the <emphasis>Update Finance Quote</emphasis> app in the &app; dmg.
        </simpara>

        <para>You can run it from the dmg or copy it to the same folder to which you copied &app;. It will open a
          Terminal window and run a script for you which will ask lots of questions. Accept the
          default for each unless you know what you&rsquo;re doing.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>On &win;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Run &mc.start.win-install-fq;. This is a small utility that installs &app-fq; for you.
        </simpara>
      </step>
    </procedure>
  </sect1>

  <sect1 id="finance-quote-helper">
    <title>Helper Scripts for Update and Diagnostics</title>

    <abstract>
      <para>&app; provides several utilities that will help you select the
        correct symbols and verification for the desired online
        quote source. Another script performs the first-time
        installation or keeps &app-fq; up to date.
        And finally, tools for error analysis are also available.
      </para>
    </abstract>

    <procedure>
      <title>Running &app-perl; Scripts Under &win;</title>

      <step>
        <simpara>Open a <application>CMD</application> or <application>Powershell</application>
          window: Click <guimenu>Start</guimenu> and type either
          <userinput>cmd</userinput> or <userinput>powershell</userinput>
          then select the resulting menu item. You don't need to run as administrator.
        </simpara>
      </step>

      <step>
        <simpara>Since, as previously recommended, the GnuCash directory was entered in the <envar>PATH</envar>
          envinronment variable, prefix any gnc-fq-xxx &app-perl; script command with
          <quote>Perl</quote> and a space, e.g. <userinput>perl gnc-fq-check</userinput>.
          Otherwise you have to execute the command e.g. <userinput><replaceable>
          C:\strawberry-perl\bin\</replaceable>perl.exe <replaceable>C:\Program Files (x86)\gnucash\bin\
          </replaceable>gnc-fq-check</userinput>.
        </simpara>
      </step>
    </procedure>

    <sect2 id="gnc-fq-check">
      <title>gnc-fq-check</title>

      <abstract>
        <para>This program returns the version number of &app-fq; module currently installed as well
          as a list of sources available via &app-fq;. It will also inform you if there is a problem
          with your installation and may suggest a fix. 
        </para>
      </abstract>

<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
      <informalexample><?dbfo pgwide="1"?>
<screen language="console">
$ gnc-fq-check
Can't locate Mozilla/CA.pm in @INC (you may need to install the Mozilla::CA module)
(@INC contains: /usr/lib/perl5/site_perl/5.30.1/x86_64-linux-thread-multi /usr/
lib/perl5/site_perl/5.30.1 /usr/lib/perl5/vendor_perl/5.30.1/x86_64-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.30.1 /usr/lib/perl5/5.30.1/x86_64-linux-thread-multi
/usr/lib/perl5/5.30.1 /usr/lib/perl5/site_perl)
at /usr/lib/perl5/vendor_perl/5.30.1/Finance/Quote/Tiaacref.pm line 33.
Compilation failed in require at (eval 303) line 1.
BEGIN failed--compilation aborted at (eval 303) line 1.
 at /usr/local/bin/gnc-fq-check line 91.
("1.47" "adig" "aex" "aiahk" "alphavantage" "amfiindia" "asegr" "asia" "asx"
"australia" "bamosz" "bet" "bmonesbittburns" "bourso" "brasil" "bse" "bsero" "canada"
"canadamutual" "citywire" "cominvest" "cse" "deka" "dutch" "dwsfunds" "europe"
"fetch_live_currencies" "fidelity" "fidelity_direct" "fidelityfixed" "financecanada"
"finanzpartner" "finland" "fool" "france" "ftfunds" "ftportfolios" "ftportfolios_direct"
"fundlibrary" "goldmoney" "greece" "hex" "hu" "hufund" "hungary" "hustock" "indiamutual"
"known_currencies" "lerevenu" "maninv" "morningstar" "morningstarjp" "mstaruk" "nasdaq"
"nyse" "nz" "nzx" "platinum" "romania" "seb_funds" "sixfunds" "sixshares"
"stockhousecanada_fund" "tdefunds" "tdwaterhouse" "tiaacref" "tnetuk" "troweprice"
"troweprice_direct" "trustnet" "tsp" "tsx" "uk_unit_trusts" "ukfunds" "unionfunds"
"usa" "usfedbonds" "vanguard" "vwd" "yahoo" "yahoo_asia" "yahoo_australia"
"yahoo_brasil" "yahoo_europe" "yahoo_json" "yahoo_nz" "yahoo_yql" "za" "za_unittrusts")
</screen>
      </informalexample>

      <para>The first part is the error message about a missing &app-perl;-modul Mozilla/CA.pm. At the end in
        parentheses is the normal output of the currently installed &app-fq; version<footnote>
        <para>The most recent &app-fq; version is &app-fq-vers;.</para>
        </footnote>
        and a list of available sources.
      </para>

      <tip>
        <para>If an error is displayed, see the next section <xref linkend="gnc-fq-update" />.
          Otherwise, continue with <xref linkend="gnc-fq-dump" />.
        </para>
      </tip>
    </sect2>

    <sect2 id="gnc-fq-update">
      <title>gnc-fq-update</title>

      <abstract>
        <para>This program installs or updates the &app-fq; software module along with its dependencies.
          <note>
            <para>Windows users are generally better off using the update-tool &mc.start.win-install-fq;.
            </para>
          </note>
        </para>
      </abstract>

      <note>
        <para>This program needs superuser or administrative privileges to succeed in &lin; or &mac; but not in &win;.
        </para>
      </note>

      <para><userinput>gnc-fq-update</userinput> will launch a &app-perl;
        <acronym><ulink url="&url-cpan;">CPAN</ulink></acronym>
        <footnote>
          <simpara>See <ulink url="&url-cpan;misc/cpan-faq.html">CPAN Frequently Asked Questions</ulink> for details.
          </simpara>
        </footnote>
        module internally. When you launch the CPAN module for the first time, you must setup and
        configure it. However, on the most systems if you accept the default settings or answer
        the first question <computeroutput>Are you ready for manual configuration?
        [yes]</computeroutput> with <userinput>no</userinput>, you will be able to install
        &app-fq; successfully.
      </para>
    </sect2>

    <sect2 id="gnc-fq-dump">
      <title>gnc-fq-dump</title>
<!-- Todo: insert link to wiki and/or guide -->
      <abstract>
        <para>This program returns quote data for a source and a list of symbols in a
          format which is easy to read for humans. It is useful for checking that a
          given online quote source is up and functional. 
        </para>
      </abstract>

      <para>You can use this command to verify that the symbol <!-- <xref linkend="tool-ge-symbol" /> -->,
        which you want to use for your security for online quote retrieval, works for the
        desired qoute source. <!-- <xref linkend="tool-ge-TypeQuoteSource" /> -->.
      </para>
      
      <tip>
        <para>With <userinput>gnc-fq-dump</userinput> you can check symbols faster than from &app;
          if an error occurs during the retrieval with &app;. This might save you from running
          &app; with debug logging enabled while checking a nonworking symbol.
        </para>
      </tip>

      <itemizedlist>
        <listitem>
          <para>To get verbose information about a security, run a command from the
            command line of the form:
            <cmdsynopsis>
              <command>gnc-fq-dump</command>
              <arg choice="opt">-v</arg>
              <arg choice="plain"><replaceable>Source</replaceable></arg>
              <arg choice="plain" rep="repeat"><replaceable>Symbol</replaceable></arg>
            </cmdsynopsis>
            e.g. <command>gnc-fq-dump -v yahoo_json IBM</command>.
          </para>
        </listitem>
        
        <listitem>
          <para>To retrieve currency exchange rate run the following command:
            <command>gnc-fq-dump <optional>-v</optional> currency USD EUR</command>
            <footnote>
              <para>Since &app-fq; 1.41 the default source for currencies is
                hardcoded to be <quote>Alpha Vantage</quote>. Also read the
                notes on <xref linkend="gnc-tbl-fq-currency-source" />.
              </para>
            </footnote>
            <footnote>
              <para>The old yahoo currencies are still available as
                <command>gnc-fq-dump yahoo_json USDEUR=X</command>.
              </para>
            </footnote>
          </para>
        </listitem>
      </itemizedlist>

      <para>To test that &app-fq; is working for currencies within &app;,
        <orderedlist numeration="arabic">
          <listitem>
            <para>find a transaction between the desired commodity and the book currency and</para>
          </listitem>
          <listitem>
            <para>right-click on it, then</para>
          </listitem>
          <listitem>
            <para>select &gmi.ac.ed-ex; in the context menu.</para>
          </listitem>
        </orderedlist>
        The <xref linkend="trans-win-enter" /> will appear. Click the 
        <guilabel>Fetch Rate</guilabel> button and if everything is
        behaving itself the current rate will fill in the exchange rate box.
      </para>
    </sect2>

    <sect2 id="gnc-fq-helper">
      <title>gnc-fq-helper</title>

      <para>This is a script that &app; uses to retrieve quotes and not usually
        useful for the user to run. Should the retrieval of a symbol in &app;
        result in failures, this script can be used to perform diagnostics
        and help developers decide if the error is in &app; or &app-fq;.
      </para>
    </sect2>
  </sect1>

  <sect1 id="finance-quote-scheduler">
    <title>Configuring for Getting Quotes Periodically</title>

    <para>The command <command>gnucash-cli --quotes get &user-datafile;</command>
      <footnote>
        <simpara>The Online Quotes Retrieval command has been changed from &app; 4.0. The old command
          <command>gnucash --add-price-quotes &user-datafile;</command> is still available, but it
          is deprecated and will be removed in the future release. If you've upgraded from &app;
          3.11 or previous version, it is recommended to use the new command
          <command>gnucash-cli</command>.
        </simpara>
      </footnote>
      can be used to fetch the current quotes of your stocks and write them directly into your
      &app;-data file without starting the GUI. Thus an automatic, regular updating of the price
      database is possible.
      <warning>
        <para>Please note that the data file should not be open in another instance of &app; at the same time!
        </para>
      </warning>
    </para>

    <para>The file specified &user-datafile; will depend on the name and location of your data file. This can
      be determined by the name displayed in the top frame of the &app; window, before the
      <quote>-</quote>.
      <tip>
        <para>The file name can also be found under <guimenu>File</guimenu> in the recently opened file list. If
          you place the mouse over the menu item with the number 1 in the list of recently opened
          files, the complete file name is displayed in the <guilabel>status bar</guilabel>.
        </para>
      </tip>
    </para>

    <para>You have to register the <command>gnucash-cli</command> with a scheduler in order to get Online
      Quotes automatically and periodically. The method depends on your OS.
    </para>

    <example>
      <title>Automated quote retrieval every Friday at 4:00 p.m.</title>

      <procedure>
        <title>On &lin; and &mac;</title>

        <para>Register <command>gnucash-cli</command> with <application>cron</application>.
        </para>

        <step>
          <simpara>Run <command>crontab -e</command>.
          </simpara>
        </step>

        <step>
          <para>Add the following line to your crontab:
            <informalexample>
<screen>0 16 * * 5 gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1</screen>
            </informalexample>

            <warning>
              <para>If there is no graphic session that has already started the dbus, running on your computer at the
                time of the quote request, you must do the entry as follows instead:
                <informalexample>
<screen>0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1</screen>
                </informalexample>
                (Do not copy the line breaks into the crontab, they were inserted here only for the
                purpose of readability).
              </para>
            </warning>
          </para>
        </step>
      </procedure>

      <procedure>
        <title>On &win;</title>

        <para>Register <command>gnucash-cli</command> with Task Scheduler.
        </para>

        <step>
          <simpara>Select
            <menuchoice>
              <guimenu>Start</guimenu><guisubmenu>Windows Administrative
              Tools</guisubmenu><guimenuitem>Task Scheduler</guimenuitem>
            </menuchoice>
            .
          </simpara>
        </step>

        <step>
          <simpara>Select <guimenuitem>Create Task</guimenuitem>.
          </simpara>
        </step>

        <step>
          <simpara>Enter the appropirate items on <guilabel>Create Task</guilabel> Window.
          </simpara>
        </step>
      </procedure>

      <para>Adjust the time to the close of the stock exchange and consider <emphasis>fund quotes</emphasis>,
        that the net asset value (NAV) is determined well after the markets closed. The types have
        their description in <xref linkend="tool-price" />.
<!-- FIXME: adjust the link to a proper ID -->
      </para>
    </example>

    <para>Some users have made additions to the wiki and shared their experiences on the
      <ulink url="&url-wiki-OQ;#Updating_enabled_Quotes_from_outside_GnuCash">Online Quotes Page on
      GnuCash Wiki</ulink>.
    </para>
  </sect1>
</chapter>
