#!/usr/local/bin/scripts/sh
#
#^pen: wait
#
#.Y / 70 83 / / / / 105 / / / /  / /               ;A4_QUER.Y
#.YT 3 2 0 0 3 3 1 / / /
#.H!a!0:linux/<scripts>/io/disk/mediaAccess/mediaHandlers.d/A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for a 'pseudo raid' media with all
#                           its components on the same media
#
#     begin               : Thu Dec  8 00:45:26 CEST 2016
#
#     changes             :
#
#     copyright           : (C) 2016 by Thomas Bruecker
#
#     email               : public@thomas-r-bruecker.ch
#
#     version             : -0.0.0
#
#*******************************************************************************/

#/***************************************************************************
# *                                                                         *
# *   This program is free software; you can redistribute it and/or modify  *
# *   it under the terms of the GNU General Public License as published by  *
# *   the Free Software Foundation; either version 2 of the License, or     *
# *   (at your option) any later version.                                   *
# *                                                                         *
# *   This program is distributed in the hope that it will be useful, but   *
# *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU      *
# *   General Public License for more details.                              *
# *                                                                         *
# *   You should have received a copy of the GNU General Public License     *
# *   along with this program; if not, write to the Free Software           *
# *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,            *
# *   MA 02110-1301 USA.                                                    *
# *                                                                         *
# ***************************************************************************/

# MyHash("A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9") = 0x089B_2C
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.


disk_mediaAccess_A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9() {
  # handles a 'pseudo raid' media with all its components on the same media;
  # $1: command, in {
  #       "2ChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #       "SIZE", "VERIFY", "WAIT", "_:", "__:"
  #     },
  #     * $1 in {
  #         "2ChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #         "SIZE", "VERIFY", "WAIT"
  #       }: see "../CommonCommandsSpecification.TXT".

  local  COMMAND ComponentMediaIndex ComponentMediaPath FileName FORCED INDEX
  local  ManagementCommand MediaInfo ParentMedia ParentMediaPath
  local  SpareComponentMediaPath SyncActionCommand

  COMMAND="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  # quick, for verifying and 'wait':
    disk_mediaAccess__VerifyNoWait  "$COMMAND"  && return 0
                                                   # if ok, return 0; no
                                                   # waiting for component
                                                   # medias at all.

  disk_mediaAccess__RealizeForced2Forced  "$COMMAND"
  # echo  $FORCED                                                 >>/dev/stderr

  case "$COMMAND" in
      2ChildDev)
        disk_mediaAccess___2ChildDev                                         \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      2ChildMedia)
        disk_mediaAccess___2ChildMedia0                                      \
                             "$MediaInfo"                                    ;;
      ADD)
        SpareComponentMediaPath="$6"
        disk_mediaAccess__0x089B_2C_ADD                                      \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  \
          "$SpareComponentMediaPath"                                         ;;
      AddByIndex)
        ComponentMediaIndex="$6"
        disk_mediaAccess__0x089B_2C_AddByIndex                               \
          $ComponentMediaIndex                                               \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      CHECK|REPAIR)  return  0                                               ;;
      DESTROY)
        disk_mediaAccess__0x089B_2C_DESTROY                                  \
                             "$MediaInfo"                                    ;;
      FAIL)
        ComponentMediaPath="$6"
        disk_mediaAccess__0x089B_2C_FAIL                                     \
          "$ComponentMediaPath"                                              \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      FailByIndex)
        ComponentMediaIndex="$6"
        disk_mediaAccess__0x089B_2C_FailByIndex                              \
          $ComponentMediaIndex                                               \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      REALIZE|RealizeForced)
        disk_mediaAccess__0x089B_2C_REALIZE                                  \
          "$FORCED" "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
      RM)
        ComponentMediaPath="$6"
        disk_mediaAccess__0x089B_2C_RM                                       \
          "$ComponentMediaPath"                                              \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      RmByIndex)
        ComponentMediaIndex="$6"
        disk_mediaAccess__0x089B_2C_RmByIndex                                \
          $ComponentMediaIndex                                               \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      SIZE)
        disk_mediaAccess__0x089B_2C_SIZE                                     \
                             "$MediaInfo"                                    ;;
      STATUS)
        disk_mediaAccess__0x089B_2C_STATUS                                   \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _2RaidDevPath)
        disk_mediaAccess___0x089B_2C_2RaidDevPath                            \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _2StandardName)
        disk_mediaAccess___0x089B_2C_2StandardName                           \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _2SysPath)
        disk_mediaAccess___0x089B_2C_2SysPath                                \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _CHECK)
        disk_mediaAccess___0x089B_2C_CHECK                                   \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _ComponentMediaIndex2Path)
        ComponentMediaIndex="$6"
        disk_mediaAccess___0x089B_2C_ComponentMediaIndex2Path                \
          "$ComponentMediaIndex" "$MediaInfo"                                ;;
      _GetMdStuff)
        FileName="$6"
        disk_mediaAccess___0x089B_2C_GetMdStuff                              \
          "$FileName"                                                        \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _GetMismatchCount)
        disk_mediaAccess___0x089B_2C_GetMismatchCount                        \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _GetSyncAction)
        disk_mediaAccess___0x089B_2C_GetSyncAction                           \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _IDLE)
        disk_mediaAccess___0x089B_2C_IDLE                                    \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _ManagementCommand)
        ComponentMediaPath="$7"
        ManagementCommand="$6"
        disk_mediaAccess___0x089B_2C_ManagementCommand                       \
          $ComponentMediaPath                                                \
                    "$INDEX" "$ManagementCommand"                            \
                             "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _ManagementCommandByIndex)
        ComponentMediaIndex="$7"
        ManagementCommand="$6"
        disk_mediaAccess___0x089B_2C_ManagementCommandByIndex                \
          $ComponentMediaIndex                                               \
                    "$INDEX" "$ManagementCommand"                            \
                             "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _REPAIR)
        disk_mediaAccess___0x089B_2C_REPAIR                                  \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _RM)
        ComponentMediaPath="$6"
        disk_mediaAccess___0x089B_2C_RM                                      \
          "$ComponentMediaPath"                                              \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _RmByIndex)
        ComponentMediaIndex="$6"
        disk_mediaAccess___0x089B_2C_RmByIndex                               \
          $ComponentMediaIndex                                               \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _SyncActionCommand)
        SyncActionCommand="$6"
        disk_mediaAccess___0x089B_2C_SyncActionCommand                       \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  \
          "$SyncActionCommand"                                               ;;
      *)
        disk_mediaAccess___NoContainer                                       \
          "$COMMAND" "$INDEX" "$ParentMedia"                                 \
          || return                                # return on error.

        disk_mediaAccess__InvalidCommandError                                \
          "$COMMAND" "$INDEX"                                                \
          'A8A2BB2C_78F0_11E6_B6F3_0000C00A45A9'                             \
          "$ParentMedia"                                                     ;;
    esac                                           # return result of previous
}                                                  # command.


disk_mediaAccess__0x089B_2C_ADD() {
  # adds the spare-component-media, denoted by the <SpareComponentMediaPath>,
  # to the raid, 'mdadm --add';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>,
  # $5: <SpareComponentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath SpareComponentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"
  SpareComponentMediaPath="$5"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $SpareComponentMediaPath                                >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommand                   \
    "$SpareComponentMediaPath"                                     \
    "$INDEX" 'add' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_AddByIndex() {
  # adds the component-media, denoted by the <ComponentMediaIndex>, to the
  # raid, 'mdadm --add';
  # $1: <ComponentMediaIndex>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaIndex INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaIndex="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaIndex                                    >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommandByIndex            \
    "$ComponentMediaIndex"                                         \
    "$INDEX" 'add' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_DESTROY() {
  # destroy media;
  # $1: <MediaInfo>.

  # global:  DmSetup0x0EAA MdAdm0x0EAA

  local      ChildMediaName ChildMediaPath I ParametersFile RESULT

  # parameters:
    local    numComponents UUID

  MediaInfo="$1"

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"        \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  $numComponents                                          >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"
  ChildMediaPath="$(disk_mediaAccess___Uuid2ByUuidPath  "$ChildMediaName")"  \

  # must be done before stopping the raid.
    disk_mediaAccess___UnMap             "$ChildMediaName"

  "$MdAdm0x0EAA"  -S                     "$ChildMediaPath"
    RESULT="$?"

      disk_mediaAccess___UnLinkAndUnMap  "$ChildMediaName"

    [ '0' == "$RESULT" ]  || return                # return on error.

  for ((I=0; I < numComponents; I++))
    do
        "$DmSetup0x0EAA"  remove         "${ChildMediaName}.A${I}"           \
          || return                                # return on error.
       done
}


disk_mediaAccess__0x089B_2C_FAIL() {
  # marks the component-media, denoted by the <ComponentMediaPath>, in the raid
  # as faulty, 'mdadm --fail';
  # $1: <ComponentMediaPath>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaPath INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaPath="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaPath                                     >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommand                    \
    "$ComponentMediaPath"                                           \
    "$INDEX" 'fail' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_FailByIndex() {
  # marks the component-media, denoted by the <ComponentMediaIndex>, in the
  # raid as faulty, 'mdadm --fail';
  # $1: <ComponentMediaIndex>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaIndex INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaIndex="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaIndex                                    >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommandByIndex             \
    "$ComponentMediaIndex"                                          \
    "$INDEX" 'fail' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_REALIZE() {
  # realize media or realize media forced;
  # $1: <FORCED>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMediaPath>.

  local    ChildMediaName FORCED I INDEX MediaInfo ParametersFile
  local    ParentMediaPath RaidDevice RaidDevicePath StartSector

  # parameters:
    local  ALGORITHM ChunkSize ComponentSize COPYRIGHT CopyrightDetails KERNEL
    local  LEVEL numComponents OnlyOnHosts RealizationOptions START URL UUID

  FORCED="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMediaPath="$4"

  # echo  $FORCED                                                 >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  # clear global optional not ignored parameters.
    OnlyOnHosts=''
    RealizationOptions=''

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"       \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  $ALGORITHM                                              >>/dev/stderr
  # echo  $COPYRIGHT                                              >>/dev/stderr
  # echo  $CopyrightDetails                                       >>/dev/stderr
  # echo  $ChunkSize                                              >>/dev/stderr
  # echo  $ComponentSize                                          >>/dev/stderr
  # echo  $KERNEL                                                 >>/dev/stderr
  # echo  $LEVEL                                                  >>/dev/stderr
  # echo  $numComponents                                          >>/dev/stderr
  # echo  $OnlyOnHosts                                            >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  $START                                                  >>/dev/stderr
  # echo  $URL                                                    >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"
  # echo  $ChildMediaName                                         >>/dev/stderr

  disk_mediaAccess_isHandled                                                \
    "$FORCED" "$OnlyOnHosts" "$RealizationOptions"  || return 0

  StartSector="$START"
  for ((I=0; I < numComponents; I++))
    do
      disk_mediaAccess____LinearTable                                       \
        "${ChildMediaName}.A${I}" "$ParentMediaPath" "$RealizationOptions"  \
        "$ComponentSize" "$StartSector"                                     \
        || return                                  # return on error.

        let  "StartSector = StartSector + ComponentSize"
      done

  RaidDevice='255'
  RaidDevicePath="/dev/md${RaidDevice}"

  if [ "-1" != "$LEVEL" ]; then
      # raid is specified by "parameters".
        disk_mediaAccess____0x089B_2C_byParameters   || return
                                                   # return on error.
    else
      disk_mediaAccess____0x089B_2C_byUuid  "$UUID"  || return
                                                   # return on error.
    fi

  disk_mediaAccess___LinkAndMap                                             \
    "$ChildMediaName" "$INDEX" "$ParentMediaPath" "$RaidDevicePath"
}


disk_mediaAccess__0x089B_2C_RM() {
  # marks the component-media, denoted by the <ComponentMediaPath>, in the
  # the raid as faulty, 'mdadm --fail' and removes it from the raid,
  # 'mdadm --remove';
  # $1: <ComponentMediaPath>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaPath INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaPath="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaPath                                     >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess__0x089B_2C_FAIL                           \
    "$ComponentMediaPath"                                    \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  \
    || return                                      # return on error.

  disk_mediaAccess___0x089B_2C_RM                            \
    "$ComponentMediaPath"                                    \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_RmByIndex() {
  # marks the component-media, denoted by the <ComponentMediaIndex>, in the
  # the raid as faulty, 'mdadm --fail' and removes it from the raid,
  # 'mdadm --remove';
  # $1: <ComponentMediaIndex>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaIndex INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaIndex="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaIndex                                    >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess__0x089B_2C_FailByIndex                    \
    "$ComponentMediaIndex"                                   \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  \
    || return                                      # return on error.

  disk_mediaAccess___0x089B_2C_RmByIndex                     \
    "$ComponentMediaIndex"                                   \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x089B_2C_SIZE() {
  # writes the size of the media; the size of the media-info included to
  # "stdout";
  # $1: <MediaInfo>.

  local    INDEX MediaInfo TotalSize

  # parameters:
    local  ComponentSize numComponents START

  MediaInfo="$1"

  # echo  $ParentMedia                                            >>/dev/stderr

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"  \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  # echo  $ComponentSize                                          >>/dev/stderr
  # echo  $numComponents                                          >>/dev/stderr
  # echo  $START                                                  >>/dev/stderr

  let "TotalSize = $START + (ComponentSize * numComponents)"
  echo  "$TotalSize"
}


disk_mediaAccess__0x089B_2C_STATUS() {
  # reads the status of the child-media from "/proc/mdstat";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath StandardName

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  StandardName="$(
    disk_mediaAccess___0x089B_2C_2StandardName                 \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  grep  -A3  "$StandardName" '/proc/mdstat'
}


disk_mediaAccess___0x089B_2C_2RaidDevPath() {
  # writes the raid-device-path ("/dev/md<N>") of the child-media to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ChildDev INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  ChildDev="$(
    disk_mediaAccess___2ChildDev                               \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $ChildDev                                               >>/dev/stderr

  disk_mediaAccess___Media2AbsolutePath  "$ChildDev"
}


disk_mediaAccess___0x089B_2C_2StandardName() {
  # writes the standard-name ("md<N>") of the child-media to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath RaidDevPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  RaidDevPath="$(
    disk_mediaAccess___0x089B_2C_2RaidDevPath                     \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  echo "$RaidDevPath"  | string__SearchAndReplace  '^\/dev\/' ''
}


disk_mediaAccess___0x089B_2C_2SysPath() {
  # writes the '/sys/'-path of the child-media, denoted by its standard name,
  # to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath StandardName

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  StandardName="$(
    disk_mediaAccess___0x089B_2C_2StandardName                 \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

  echo "/sys/block/$StandardName"
}


disk_mediaAccess___0x089B_2C_CHECK() {
  # scrubs the child-media by 'md-check';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_SyncActionCommand                     \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" 'check'
}


disk_mediaAccess___0x089B_2C_ComponentMediaIndex2Path() {
  # writes the component-media-name corresponding to the parent-media to
  # "stdout";
  # $1: <ComponentMediaIndex>,
  # $2: <MediaInfo>.

  local    ChildMediaName ComponentMediaIndex MediaInfo ParametersFile

  # parameters:
    local  UUID

  ComponentMediaIndex="$1"
  MediaInfo="$2"

  ParametersFile="$(disk_mediaAccess__Parameters2File  "$MediaInfo")"  \
    || return                                      # return on error.
    .  "$ParametersFile"  || return                # return on error.

  ChildMediaName="$UUID"

  disk_mediaAccess___Uuid2AbsolutePath1                                \
    "${ChildMediaName}.A$ComponentMediaIndex"
}


disk_mediaAccess___0x089B_2C_GetMdStuff() {
  # reads the file denoted by <FileName> in the "<SysPath>/md/"-folder and
  # writes its contents to "stdout";
  # $1: <FileName> in "<SysPath>/md/",
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  # global:  Cat0x0EAA

  local      FileName INDEX MediaInfo ParentMedia ParentMediaPath SysPath

  FileName="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $FileName                                               >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  SysPath="$(
    disk_mediaAccess___0x089B_2C_2SysPath                      \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
    )"  || return                                  # return on error.

  "$Cat0x0EAA"  "${SysPath}/md/$FileName"
}


disk_mediaAccess___0x089B_2C_GetMismatchCount() {
  # reads the file "<SysPath>/md/mismatch_cnt";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_GetMdStuff                                   \
    'mismatch_cnt' "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___0x089B_2C_GetSyncAction() {
  # reads the file "<SysPath>/md/sync_action";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_GetMdStuff                                  \
    'sync_action' "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___0x089B_2C_IDLE() {
  # stops scrubbing the media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_SyncActionCommand                     \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" 'idle'
}


disk_mediaAccess___0x089B_2C_ManagementCommand() {
  # applies a managment-command, denoted by <ManagementOption>, to the raid-
  # device;
  # $1: <ComponentMediaPath>,
  # $2: <INDEX>,
  # $3: <ManagementOption> in {"add", "fail", "remove"},
  # $4: <MediaInfo>,
  # $5: <ParentMedia>,
  # $6: <ParentMediaPath>.

  # global:  MdAdm0x0EAA

  local      ComponentMediaPath INDEX ManagementOption MediaInfo ParentMedia
  local      ParentMediaPath RaidDevPath

  ComponentMediaPath="$1"
  INDEX="$2"
  ManagementOption="$3"
  MediaInfo="$4"
  ParentMedia="$5"
  ParentMediaPath="$6"

  # echo  $ComponentMediaPath                                     >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ManagementOption                                       >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  RaidDevPath="$(
    disk_mediaAccess___0x089B_2C_2RaidDevPath                                  \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $RaidDevPath                                            >>/dev/stderr

  "$MdAdm0x0EAA"  --${ManagementOption}  "$RaidDevPath" "$ComponentMediaPath"
}


disk_mediaAccess___0x089B_2C_ManagementCommandByIndex() {
  # applies a managment-command, denoted by <ManagementOption>, to the raid-
  # device;
  # $1: <ComponentMediaIndex>,
  # $2: <INDEX>,
  # $3: <ManagementOption> in {"add", "fail", "remove"},
  # $4: <MediaInfo>,
  # $5: <ParentMedia>,
  # $6: <ParentMediaPath>.

  local  ComponentMediaIndex ComponentMediaPath INDEX ManagementOption
  local  MediaInfo ParentMedia ParentMediaPath RaidDevPath

  ComponentMediaIndex="$1"
  INDEX="$2"
  ManagementOption="$3"
  MediaInfo="$4"
  ParentMedia="$5"
  ParentMediaPath="$6"

  # echo  $ComponentMediaIndex                                    >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  $ManagementOption                                       >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  ComponentMediaPath="$(
    disk_mediaAccess___0x089B_2C_ComponentMediaIndex2Path     \
      "$ComponentMediaIndex" "$MediaInfo"
  )"  || return                                    # return on error.
  # echo  $ComponentMediaPath                                     >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommand              \
    "$ComponentMediaPath"                                     \
    "$INDEX" "$ManagementOption" "$MediaInfo" "$ParentMedia"  \
    "$ParentMediaPath"
}


disk_mediaAccess___0x089B_2C_REPAIR() {
  # scrubs the child-media by 'md-repair';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_SyncActionCommand                      \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath" 'repair'
}


disk_mediaAccess___0x089B_2C_RM() {
  # removes the component-media, denoted by the <ComponentMediaPath>, from the
  # raid, 'mdadm --remove';
  # $1: <ComponentMediaPath>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaPath INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaPath="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaPath                                     >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommand                      \
    "$ComponentMediaPath"                                             \
    "$INDEX" 'remove' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___0x089B_2C_RmByIndex() {
  # removes the component-media, denoted by the <ComponentMediaIndex>, from the
  # raid, 'mdadm --remove';
  # $1: <ComponentMediaIndex>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  ComponentMediaIndex INDEX MediaInfo ParentMedia ParentMediaPath

  ComponentMediaIndex="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMedia="$4"
  ParentMediaPath="$5"

  # echo  $ComponentMediaIndex                                    >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  disk_mediaAccess___0x089B_2C_ManagementCommandByIndex               \
    "$ComponentMediaIndex"                                            \
    "$INDEX" 'remove' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___0x089B_2C_SyncActionCommand() {
  # writes a command to "<SysPath>/md/sync_action";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>,
  # $5: <SyncActionCommand>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath SyncActionCommand SysPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMedia="$3"
  ParentMediaPath="$4"
  SyncActionCommand="$5"

  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr
  # echo  $SyncActionCommand                                      >>/dev/stderr

  SysPath="$(
    disk_mediaAccess___0x089B_2C_2SysPath                      \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
    )"  || return                                  # return on error.

  echo  "$SyncActionCommand"  >"${SysPath}/md/sync_action"
}


disk_mediaAccess____0x089B_2C_byParameters() {
  # global:  AddDisk0x0EAA

  # global, imported from "disk_mediaAccess__0x089B_2C_REALIZE()":
  #         AddDisk0x0EAA ALGORITHM ChildMediaName ChunkSize LEVEL numComponents RaidDevice
  #         RealizationOptions


  local     ForthCommand I MAJOR MINOR

  echo  -e  "\nStart Raid manually in \"forth\"; hit <return> when done;"      \
                                                                  >>/dev/stderr
  echo      "  * Screens to load:"                                >>/dev/stderr
  echo      "    * \"2101 2105 THRU  2107 LOAD  2122 LOAD\""      >>/dev/stderr
  echo      "  * Parameters for Raid:"                            >>/dev/stderr
  echo      "    * Algorithm    = $ALGORITHM"                     >>/dev/stderr
  echo      "    * Chunk Size   = $ChunkSize"                     >>/dev/stderr
  echo      "    * Level        = $LEVEL"                         >>/dev/stderr
  echo      "    * # Components = $numComponents"                 >>/dev/stderr
  echo  -e  "\n  * Forth-Command: \"RAID_ CD{\"."                 >>/dev/stderr
  read

  for ((I=0; I < numComponents; I++))
    do
        MAJOR="$(disk_dm_2Major  "${ChildMediaName}.A${I}")"
        MINOR="$(disk_dm_2Minor  "${ChildMediaName}.A${I}")"
        "$AddDisk0x0EAA"  "$MAJOR" "$MINOR" "$RaidDevice" "$I"  >>/dev/stderr  \
          || return                                # return on error.
      done

  if  string_MatchQ  "$RealizationOptions" 'ro'; then
      ForthCommand='RAID_ }CDR'
    else
      ForthCommand='RAID_ }CDW'
    fi

  echo  -en  "\nFinish Start of Raid manually in \"forth\";"      >>/dev/stderr
  echo  -e                                        " hit <return> when done;"  \
                                                                  >>/dev/stderr
  echo  -e   "  * Forth-Command: \"$ForthCommand\"."              >>/dev/stderr
  read
}


disk_mediaAccess____0x089B_2C_byUuid() {
  # $1: UUID.

  # ^pen:
  #   * Test for components?
  #   * RealizationMode
  #   * RealizationOptions: takes also
  #     * "bitmap=<filename>"; --> path = "<UUID>.d/<filename>";
  #     * "bitmap-chunk=<M>"; M in 1024 bytes;
  #     * "write-behind=<N>;  N: 0 <= N <= 16383 "write-behind" (see "man mdadm").
  #     * "write-mostly=<I>"; I: "component index"; see above --> the media with this
  #     "component index" will be flagged as "write-mostly" (see "man mdadm").

  # global:  MdAdm0x0EAA Sleep0x0EAA

  # global, imported from "disk_mediaAccess__0x088F_REALIZE()"
  #         ('A8A2BB36_78F0_11E6_B6F3_0000C00A45A9)") or
  #         "disk_mediaAccess__0x089B_2C_REALIZE()":
  #         RaidDevicePath RealizationOptions

  local     UUID

  UUID="$1"
  UUID="$(disk_raid_Uuid2RaidUuid  "$UUID")"

  # echo  $UUID                                                   >>/dev/stderr

  # on some systems, a raid device is automaticall realized by "udev" when its
  # components are ready; so test, if it is already realized.
    if ! disk_mediaAccess__0x089B_2C__byUuid_isReady    "$UUID";  then
        # raid is not yet realized.
          "$MdAdm0x0EAA"  -A      "$RaidDevicePath"  -u "$UUID"  || return
      fi                                           # return on error.

  if  string_MatchQ  "$RealizationOptions" 'ro'; then
#^with isReady...
      "$Sleep0x0EAA"  10                           # wait 'for settling' raid.
      "$MdAdm0x0EAA"  --readonly  "$RaidDevicePath"  || return
    fi                                             # return on error.
}


disk_mediaAccess____0x089B_2C_byUuid_isReady() {
  # $1: RUuid (uuid as 'written by mdadm');
  # returns true (0), if the raid-device is ready.

  # global:  MdAdm0x0EAA

  # global, imported from "disk_mediaAccess__0x088F_REALIZE()"
  #         ('A8A2BB36_78F0_11E6_B6F3_0000C00A45A9)") or
  #         "disk_mediaAccess__0x089B_2C_REALIZE()":
  #         RaidDevicePath

  local  TestUuid Result RUuid TMP

  RUuid="$1"

  TMP=$("$MdAdm0x0EAA"  --brief  --detail  "$RaidDevicePath"  2>/dev/null)  \
    || return 1                                    # no such device.

  # we have a raid device at <RaidDevicePath>; but is it ours; check uuid:
    #                         | delete till "UUID=".
    TestUuid="$(echo  "$TMP"  | string__SearchAndReplace  '^.*UUID=' '')"
    [ "$RUuid" = "$TestUuid" ]                     # return result of this test.
}