=============================================
Direct I/O コマンドラインツールユーザーガイド
=============================================

このドキュメントでは、Direct I/Oに関するコマンドラインツールの利用方法について紹介します。

ツールの配置と設定
==================

Direct I/Oに関するコマンドラインツールは :file:`$ASAKUSA_HOME/directio/bin` ディレクトリ内に格納されています。
また、いずれのツールもAsakusa FrameworkのDirect I/Oに関する設定情報を利用します。
これらの設定方法については :doc:`user-guide` を参照してください。

いずれのツールも :program:`hadoop` コマンドを経由して実行するため、環境にHadoopがインストールされている必要があります。
また、Hadoopのインストール先を通知するために、以下の環境変数のいずれかが必要です。

``HADOOP_CMD``
  :program:`hadoop` コマンドのパス
``HADOOP_HOME``
  :program:`Hadoop` のインストール先
``PATH``
  :program:`hadoop` コマンドが通っているパス 

ツール固有の環境変数の設定
--------------------------

ここで説明するコマンドラインツールは、実行前に :file:`$ASAKUSA_HOME/directio/conf/env.sh` を読み込んで必要な環境変数の設定などを行います。

以下は同ファイルの内容を改変し、環境変数 ``HADOOP_CMD`` を設定する例です。

..  code-block:: sh

    export HADOOP_CMD=/usr/bin/hadoop

ファイル操作
============

ファイル操作を行うコマンドは、Direct I/Oのベースパスやファイルパターンを利用して、実際のデータソース内のファイルに対して処理を行います。

ファイルのリストアップ
----------------------

:program:`$ASAKUSA_HOME/directio/bin/list-file.sh` コマンドを利用すると、Direct I/Oのパスを使ってデータソース上のファイルやディレクトリ一覧をリストアップできます。

以下の形式で指定します。

..  code-block:: sh

    list-file.sh <base-path> <resource-pattern> [<resource-pattern> [...]]

コマンドに指定可能な引数は以下のとおりです。

..  program:: list-file.sh

..  option:: -h, -help

    ヘルプメッセージを表示して終了します。

..  option:: base-path

    対象ファイルのベースパスを指定します。

    ベースパスは利用するデータソースを検出するためのパスで、多くの場合にはデータソースを配置したパスを指定します。
    ここに指定するパスは、DSLの入出力定義において ``getBasePath()`` メソッドで定義したものを指定できます。

..  option:: resource-pattern

    対象ファイルのベースパスからの相対パスを指定します。

    ここには ``*`` (ワイルドカード)などのメタ文字も指定できます。
    詳しくは `ファイル名のパターン`_ を参照してください。

..  hint::
    パスにディレクトリを指定した場合に、ディレクトリの内容の表示が行われるわけではありません。
    ディレクトリの内容を表示したい場合、 ``<resource-pattern>`` の末尾に ``/*`` と指定してください。

利用例
~~~~~~

1. ルートパス配下のすべてのディレクトリ/ファイルを出力する

   ..  code-block:: sh

       list-file.sh / "**/*"
   .. ***

2. ベースパス ``result`` 配下の拡張子 ``.csv`` を持つファイルをサブディレクトリ含めてすべて出力する

   ..  code-block:: sh

       list-file.sh result "**/*.csv"
   .. ***

ファイルの削除
--------------

:program:`$ASAKUSA_HOME/directio/bin/delete-file.sh` コマンドを利用すると、Direct I/Oのパスを使ってデータソース上のファイルを削除できます。

以下の形式で指定します。

..  code-block:: sh

    delete-file.sh [-r] <base-path> <resource-pattern> [<resource-pattern> [...]]

コマンドに指定可能な引数は以下のとおりです。

..  program:: delete-file.sh

..  option:: -h , -help

    ヘルプメッセージを表示して終了します。

..  option:: -r , -recursive

    ファイルだけでなくディレクトリとその内容も削除します。

    この指定がない場合、ディレクトリの削除は行いません。

..  option:: base-path

    対象ファイルのベースパスを指定します。

    ベースパスは利用するデータソースを検出するためのパスで、多くの場合にはデータソースを配置したパスを指定します。
    ここに指定するパスは、DSLの入出力定義において ``getBasePath()`` メソッドで定義したものを指定できます。

..  option:: resource-pattern

    対象ファイルのベースパスからの相対パスを指定します。

    ここには ``*`` (ワイルドカード)などのメタ文字も指定できます。
    詳しくは `ファイル名のパターン`_ を参照してください。

.. _directio-file-name-pattern:

ファイル名のパターン
--------------------

それぞれのコマンドの ``<resource-pattern>`` にはファイル名だけでなくワイルドカードなどのパターン用の文字列も利用できます。

ここに利用できるパターンは以下の通りです。

..  list-table:: 利用できるパターン
    :widths: 10 10 40
    :header-rows: 1

    * - 文字列
      - 名前
      - 概要
    * - 名前文字
      - リテラル
      - そのままファイル名として利用します。
        対象のデータソースが利用できるファイル名のうち、
        ``/`` , ``\`` , ``$`` , ``*`` , ``?`` , ``#`` , ``|`` , ``{`` , ``}`` , ``[`` , ``]`` 以外の文字を利用できます。
    * - ``/``
      - 名前区切り
      - パスに含まれる名前の区切り文字です。
    * - ``*``
      - ワイルドカード
      - 0個以上の任意の名前文字とマッチします。
    * - ``{..|..|..}``
      - 選択
      - ``|`` で区切られたいずれかの名前にマッチします。
        ``..`` の部分には名前文字と名前区切りの組み合わせのみを指定できます。

上記のほかに、特別なディレクトリやファイル名として ``**`` を利用できます。
これは、検索対象以下のすべてのサブディレクトリ(自身のディレクトリも含む)とそれに含まれるファイルにマッチします。

ただし、 ``**`` はディレクトリやファイル名の一部としては利用できません。
たとえば、 ``**.csv`` というパターンは利用できず、代わりに ``**/*.csv`` と書きます。

..  attention::
    利用しているシェルによっては、ファイル名のパターンに ``*`` 文字が含まれていた場合に自動的に展開されてしまいます。
    展開を回避するには、 ``"*"`` のようにダブルクウォート文字で囲むなどの指定を行なってください。

トランザクション操作
====================

トランザクション操作を行うコマンドは、Direct I/Oを利用した際のトランザクション処理を直接制御できます。

トランザクション制御については :doc:`user-guide` を参照してください。

トランザクションのリストアップ
------------------------------

:program:`$ASAKUSA_HOME/directio/bin/list-transaction.sh` コマンドを利用すると、Direct I/Oで実行中や実行に失敗したトランザクションの一覧を表示します。

以下の形式で指定します。

..  code-block:: sh

    list-transaction.sh

コマンドには引数を指定せずに実行します。

このコマンドを実行すると、以下の情報を表示します。

..  list-table:: 表示されるトランザクションの情報
    :widths: 4 6
    :header-rows: 1

    * - セクション
      - 内容
    * - ``Date``
      - トランザクションを開始した日時
    * - ``Execution ID``
      - 対象のジョブフローの実行ID
    * - ``Status``
      - トランザクションの状態
    * - ``Comments``
      - 補助的な情報

コミットの適用
--------------

:program:`$ASAKUSA_HOME/directio/bin/apply-transaction.sh` コマンドを利用すると、Direct I/Oでコミットに成功した未適用のトランザクションを、最後まで適用します。
この操作によって、in-doubt状態になっているトランザクションを適切に終了させられます。

以下の形式で指定します。

..  code-block:: sh

    apply-transaction.sh <execution-id>

コマンドに指定可能な引数は以下のとおりです。

..  program:: apply-transaction.sh

..  option:: execution-id

    対象のジョブフローの実行ID

上記の実行IDを確認するには、 `トランザクションのリストアップ`_ を実行し、 ``Execution ID`` の項目を参照してください。
また、同時に表示される ``Status`` の項目が ``Committed`` となっているもののみを、このコマンドで処理できます。
``Status`` の項目が ``Committed`` でない場合、このコマンドを実行しても処理は行われません。

コミットの破棄
--------------

:program:`$ASAKUSA_HOME/directio/bin/abort-transaction.sh` コマンドを利用すると、Direct I/Oで行われた任意のトランザクションを破棄できます。

以下の形式で指定します。

..  code-block:: sh

    abort-transaction.sh <execution-id>

コマンドに指定可能な引数は以下のとおりです。

..  program:: abort-transaction.sh

..  option:: execution-id

    対象のジョブフローの実行ID

上記の実行IDを確認するには、 `トランザクションのリストアップ`_ を実行し、 ``Execution ID`` の項目を参照してください。
``Status`` の項が ``Committed`` , ``NOT Committed`` のいずれの場合でも途中結果を強制的に破棄します。

..  warning::
    ``Status`` の項目が ``Committed`` になってるトランザクションに対してこのコマンドを実行すると、処理結果が中途半端にデータソース上に反映されたまま復元できなくなる場合があります。

    そのようなトランザクションには通常 `コミットの適用`_ を行うべきですが、コミットの内容が不要になった場合や、コミットの内容がエラーによりどうやっても適用できない場合などには、上記のコマンドも利用できます。

..  hint::
    ``Status`` の項目が ``NOT Committed`` である場合、コミットの破棄はほぼロールバック操作と同様になります。
    ただし、Direct I/Oの出力時に「ステージ領域の省略」を行っていた場合には、途中結果が出力先に一部反映されている可能性があります。