#!/usr/local/bin/scripts/sh
# ^pen:
# * "^"
# * 'TIMEOUT' --> 'wait'
# * code straffen; ausklammern

#
#.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/A8A2BB36_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB36_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for a raid media
#
#     begin               : Tue May 16 13:05:33 CEST 2017
#
#     changes             :
#
#     copyright           : (C) 2017 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("A8A2BB36_78F0_11E6_B6F3_0000C00A45A9" = 0x088F_36
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.


disk_mediaAccess_A8A2BB36_78F0_11E6_B6F3_0000C00A45A9() {
  # * handles a raid 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",
  #     ^* "_:":  ^verify command,
  #              ^$2: path to the media (device, file, rootFolder of a filsystem),
  #              ^$3: index into container,
  #     ^* "__:": ^verify command,
  #              $2: media-handler-uuid,
  #              $3: size,
  #              $4: uuid,
  #              $5: prefix, most often: indent;
  #              ^* writes the size-parameter to "stdout".

  local  COMMAND DEVICE FORCED FileName INDEX ManagementCommand MediaInfo
  local  ParentMedia ParentMediaPath 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)
        disk_mediaAccess__0x088F_36_ADD                                      \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      AddDevice)
        DEVICE="$6"
        disk_mediaAccess__0x088F_36_AddDevice                                \
          "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      AddDeviceWriteMostly)
        DEVICE="$6"
        disk_mediaAccess__0x088F_36_AddDeviceWriteMostly                     \
          "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      AddWriteMostly)
        disk_mediaAccess__0x088F_36_AddWriteMostly                           \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      CHECK|REPAIR)  return  0                                               ;;
      ClearMaxBacklogUsed)
        disk_mediaAccess__0x088F_36_ClearMaxBacklogUsed                      \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      DESTROY)
        disk_mediaAccess__0x088F_36_DESTROY                                  \
                              "$MediaInfo"                                   ;;
      FAIL)
        disk_mediaAccess__0x088F_36_FAIL                                     \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      FailDevice)
        DEVICE="$6"
        disk_mediaAccess__0x088F_36_FailDevice                               \
          "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      MaxBacklogUsedPercentage)
        disk_mediaAccess__0x088F_36_MaxBacklogUsedPercentage                 \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      REALIZE|RealizeForced)
        disk_mediaAccess__0x088F_36_REALIZE                                  \
          "$FORCED" "$INDEX" "$MediaInfo" "$ParentMediaPath"                 ;;
      RM)
        disk_mediaAccess__0x088F_36_RM                                       \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      RmDevice)
        DEVICE="$6"
        disk_mediaAccess__0x088F_36_RmDevice                                 \
          "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      SIZE)
        disk_mediaAccess__Size1                                              ;;
      STATUS)
        disk_mediaAccess__0x089B_2C_STATUS                                   \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _2BitmapPath)
        disk_mediaAccess___0x088F_36_2BitmapPath                             \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _2ComponentMediaPath)
        disk_mediaAccess___0x088F_36_2ComponentMediaPath                     \
                             "$MediaInfo" "$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"  ;;
#      _:)
#        shift 1
#        disk_mediaAccess_0x088F_36_col__   "$@"
#                                                             ;;  # ^
#      __:)
#        shift 1
#        disk_mediaAccess_0x088F_36_col___  "$@"
#                                                             ;;  # ^
      _CHECK)
        disk_mediaAccess___0x089B_2C_CHECK                                   \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _GetBitmapStuff)
        FileName="$6"
        disk_mediaAccess___0x088F_36_GetBitmapStuff                          \
          "$FileName"                                                        \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _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)
        ManagementCommand="$6"
        disk_mediaAccess___0x088F_36_ManagementCommand                       \
                    "$INDEX" "$ManagementCommand"                            \
                             "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _REPAIR)
        disk_mediaAccess___0x089B_2C_REPAIR                                  \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _RM)
        disk_mediaAccess___0x088F_36_RM                                      \
                    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
      _RmDevice)
        DEVICE="$6"
        disk_mediaAccess___0x088F_36_RmDevice                                \
          "$DEVICE" "$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"                                                \
          'A8A2BB36_78F0_11E6_B6F3_0000C00A45A9'                             \
          "$ParentMedia"                                                     ;;
    esac                                           # return result of previous
}                                                  # command.


disk_mediaAccess__0x088F_36_ADD() {
  # adds the parent-media to the raid, 'mdadm --add';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ComponentMediaPath 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

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

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


disk_mediaAccess__0x088F_36_AddDevice() {
  # adds the device to the raid, 'mdadm --add';
  # $1: <DEVICE>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  DEVICE INDEX MediaInfo ParentMedia ParentMediaPath

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

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

  disk_mediaAccess____0x088F_36_ManagementCommand                            \
    "$DEVICE" "$INDEX" 'add' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x088F_36_AddDeviceWriteMostly() {
  # adds the device as 'write-mostly-device' to the raid,
  # 'mdadm --add'  <...>  --write-mostly <...>';
  # $1: <DEVICE>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  # global:  MdAdm0x0EAA

  local      DEVICE INDEX MediaInfo ParentMedia ParentMediaPath RaidDevPath

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

  # echo  $DEVICE                                                 >>/dev/stderr
  # 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                                             >>/dev/stderr

  "$MdAdm0x0EAA"  --add  "$RaidDevPath"  --write-mostly "$DEVICE"
}


disk_mediaAccess__0x088F_36_AddWriteMostly() {
  # adds the parent-media as 'write-mostly-media' to the raid,
  # 'mdadm --add  <...>  --write-mostly <...>';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ComponentMediaPath INDEX MediaInfo ParentMedia ParentMediaPath
  local  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

  ComponentMediaPath="$(
    disk_mediaAccess____0x088F_36_CreateBaseMedia               \
      "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.

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


disk_mediaAccess__0x088F_36_ClearMaxBacklogUsed() {
  # clears "<bitmap-folder>/max_backlog_used";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  BitmapPath 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

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

  echo 'x'  > "${BitmapPath}/max_backlog_used"
}


disk_mediaAccess__0x088F_36_DESTROY() {
  # destroys the child-media;
  # $1: <MediaInfo>.

  # global:    DmSetup0x0EAA MdAdm0x0EAA Rm0x0EAA

  local        ChildMediaFolderPath ChildMediaName I IW MediaInfo
  local        numActiveNormalComponents numActiveWriteMostlyComponents
  local        numSpareNormalComponents numSpareWriteMostlyComponents
  local        ParametersFile RaidDevPath RESULT TmpMediaName TmpMediaPath

  # parameters:
    local  -a  ActiveMedias ActiveWriteMostlyMedias
    local      RealizationMode
    local  -a  SpareMedias SpareWriteMostlyMedias
    local      UUID

  MediaInfo="$1"
  # echo  "$MediaInfo"                                            >>/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  ${ActiveMedias[@]}                                      >>/dev/stderr
  # echo  ${ActiveWriteMostlyMedias[@]}                           >>/dev/stderr
  # echo  $RealizationMode                                        >>/dev/stderr
  # echo  ${SpareMedias[@]}                                       >>/dev/stderr
  # echo  ${SpareWriteMostlyMedias[@]}                            >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  [ "dm" == "$RealizationMode" ]  &&  {
    echo  -e  "\"RealizationMode = 'dm'\" is not supported yet.";  \
                                                                  >>/dev/stderr
    return 2;
  }

  [ "md" != "$RealizationMode" ]  &&  {
    echo  -e  "\"RealizationMode = '$RealizationMode'\" is not supported.";
                                                                  >>/dev/stderr
    return 2;
  }

  ChildMediaName="$UUID"
  ChildMediaFolderPath="$(
    disk_mediaAccess___2ChildMediaFolderPath  "$ChildMediaName"
  )"
  # echo  $ChildMediaFolderPath                                   >>/dev/stderr
  # echo  $ChildMediaName                                         >>/dev/stderr

  numActiveNormalComponents="${#ActiveMedias[@]}"
  numActiveWriteMostlyComponents="${#ActiveWriteMostlyMedias[@]}"
  numSpareNormalComponents="${#SpareMedias[@]}"
  numSpareWriteMostlyComponents="${#SpareWriteMostlyMedias[@]}"
  RaidDevPath="/dev/md/$ChildMediaName"

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

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

  for ((I=0; I < numActiveNormalComponents; I++))
    do
        TmpMediaName="${ChildMediaName}.A${I}"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        if  disk_dm__isDevice         "$TmpMediaPath"; then
            "$DmSetup0x0EAA"  remove  "$TmpMediaName"
            "$Rm0x0EAA"       -f      "$TmpMediaPath"
          fi
      done

  for ((I = 0; I < numActiveWriteMostlyComponents; I++))
    do
        let "IW = I + numActiveNormalComponents"
        TmpMediaName="${ChildMediaName}.A${IW}"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        if  disk_dm__isDevice         "$TmpMediaPath"; then
            "$DmSetup0x0EAA"  remove  "$TmpMediaName"
            "$Rm0x0EAA"       -f      "$TmpMediaPath"
          fi
      done

  for ((I=0; I < numSpareNormalComponents; I++))
    do
        TmpMediaName="${ChildMediaName}.S${I}"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        if  disk_dm__isDevice         "$TmpMediaPath"; then
            "$DmSetup0x0EAA"  remove  "$TmpMediaName"
            "$Rm0x0EAA"       -f      "$TmpMediaPath"
          fi
      done

  for ((I = 0; I < numSpareWriteMostlyComponents; I++))
    do
        let "IW = I + numSpareNormalComponents"
        TmpMediaName="${ChildMediaName}.S${IW}"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        if  disk_dm__isDevice         "$TmpMediaPath"; then
            "$DmSetup0x0EAA"  remove  "$TmpMediaName"
            "$Rm0x0EAA"       -f      "$TmpMediaPath"
          fi
      done

  disk_mediaAccess___UnLink  "$ChildMediaName"

  return "$RESULT"
}


disk_mediaAccess__0x088F_36_FAIL() {
  # marks the parent-media in the raid as faulty, 'mdadm --fail';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  ComponentMediaPath 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

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

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


disk_mediaAccess__0x088F_36_FailDevice() {
  # marks the parent-media in the raid as faulty, 'mdadm --fail';
  # $1: <DEVICE>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  DEVICE INDEX MediaInfo ParentMedia ParentMediaPath

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

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

  disk_mediaAccess____0x088F_36_ManagementCommand                             \
    "$DEVICE" "$INDEX" 'fail' "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess__0x088F_36_MaxBacklogUsedPercentage() {
  # writes the "max_backlog_used" value in percent of the "backlog"-value to
  # "stdout"
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  BACKLOG INDEX MaxBacklogUsed MediaInfo ParentMedia ParentMediaPath
  local  RESULT

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

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

  BACKLOG="$(
    disk_mediaAccess___0x088F_36_GetBitmapStuff                \
      'backlog'                                                \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  MaxBacklogUsed="$(
    disk_mediaAccess___0x088F_36_GetBitmapStuff                \
      'max_backlog_used'                                       \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo "$BACKLOG"                                               >>/dev/stderr
  # echo "$MaxBacklogUsed"                                        >>/dev/stderr

  let "RESULT = 100 * (MaxBacklogUsed + (BACKLOG / 100)) / BACKLOG"
    # not 100% correct !
  echo "$RESULT"
}


disk_mediaAccess__0x088F_36_REALIZE() {
  # realizes the child-media or realizes the child-media forced;
  # $1: <FORCED>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMediaPath>.

  # global:    ReadLink0x0EAA

  local        ChildMediaName FinalRaidDevPath FORCED INDEX MediaInfo
  local        ParametersFile ParentMediaPath RaidDevPath

  # parameters:
    local  -a  ActiveMedias ActiveWriteMostlyMedias
    local      ALGORITHM ChunkSize ComponentSize COPYRIGHT CopyrightDetails
    local      KERNEL LEVEL NOTES OnlyOnHosts RealizationMode
    local      RealizationOptions
    local  -a  SpareMedias SpareWriteMostlyMedias
    local      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  ${ActiveMedias[@]}                                      >>/dev/stderr
  # echo  ${ActiveWriteMostlyMedias[@]}                           >>/dev/stderr
  # echo  $ALGORITHM                                              >>/dev/stderr
  # echo  $ChunkSize                                              >>/dev/stderr
  # echo  $ComponentSize                                          >>/dev/stderr
  # echo  $COPYRIGHT                                              >>/dev/stderr
  # echo  $CopyrightDetails                                       >>/dev/stderr
  # echo  $KERNEL                                                 >>/dev/stderr
  # echo  $LEVEL                                                  >>/dev/stderr
  # echo  $NOTES                                                  >>/dev/stderr
  # echo  $OnlyOnHosts                                            >>/dev/stderr
  # echo  $RealizationMode                                        >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  ${SpareMedias[@]}                                       >>/dev/stderr
  # echo  ${SpareWriteMostlyMedias[@]}                            >>/dev/stderr

  # echo  $START                                                  >>/dev/stderr
  # ^ most probably not used?

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

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

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

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

  FinalRaidDevPath="$("$ReadLink0x0EAA"  -e  "$RaidDevPath")"
  # echo  $FinalRaidDevPath                                       >>/dev/stderr

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


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

  # global:  DmSetup0x0EAA Rm0x0EAA

  local      ComponentMediaPath 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

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

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

  "$DmSetup0x0EAA"  remove  "$ComponentMediaPath"               \
    || return                                      # return on error.

  "$Rm0x0EAA"  -f           "$ComponentMediaPath"
}


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

  local  DEVICE INDEX MediaInfo ParentMedia ParentMediaPath

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

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

  disk_mediaAccess__0x088F_36_FailDevice                               \
    "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  \
    || return                                      # return on error.

  disk_mediaAccess___0x088F_36_RmDevice                                \
    "$DEVICE" "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"
}


disk_mediaAccess___0x088F_36_2BitmapPath() {
  # writes the "<SysPath>/md/bitmap"-path of the child-media to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMedia ParentMediaPath SysPath

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

  # 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.

  echo "${SysPath}/md/bitmap"
}


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

  # global:    ColRm0x0EAA

  local        ChildMediaName ComponentMediaPath I IW numActiveNormalComponents
  local        numActiveWriteMostlyComponents numSpareNormalComponents
  local        numSpareWriteMostlyComponents ParametersFile ParentMedia
  local        ParentMediaPath TmpTargetPath

  # parameters:
    local  -a  ActiveMedias ActiveWriteMostlyMedias
    local      RealizationMode
    local  -a  SpareMedias SpareWriteMostlyMedias
    local      UUID

  ParametersFile="$1"
  ParentMediaPath="$2"

  # echo  $ParametersFile  | "$ColRm0x0EAA"  79                   >>/dev/stderr
  # echo  $ParentMediaPath                                        >>/dev/stderr

  .  "$ParametersFile"  || return                  # return on error.

  # echo  ${ActiveMedias[@]}                                      >>/dev/stderr
  # echo  ${ActiveWriteMostlyMedias[@]}                           >>/dev/stderr
  # echo  ${SpareMedias[@]}                                       >>/dev/stderr
  # echo  ${SpareWriteMostlyMedias[@]}                            >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"

  numActiveNormalComponents="${#ActiveMedias[@]}"
  numActiveWriteMostlyComponents="${#ActiveWriteMostlyMedias[@]}"
  numSpareNormalComponents="${#SpareMedias[@]}"
  numSpareWriteMostlyComponents="${#SpareWriteMostlyMedias[@]}"


  for ((I=0; I < numActiveNormalComponents; I++))
    do
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath  "${ActiveMedias[$I]}"
        )"  || return                              # return on error.
        # echo $TmpTargetPath                                     >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          echo  "${ChildMediaName}.A${I}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I = 0; I < numActiveWriteMostlyComponents; I++))
    do
        let "IW = I + numActiveNormalComponents"
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath                             \
            "${ActiveWriteMostlyMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          echo  "${ChildMediaName}.A${IW}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I=0; I < numSpareNormalComponents; I++))
    do
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath  "${SpareMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          echo  "${ChildMediaName}.S${I}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I = 0; I < numSpareWriteMostlyComponents; I++))
    do
        let "IW = I + numSpareNormalComponents"
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath                             \
            "${SpareWriteMostlyMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          echo  "${ChildMediaName}.S${IW}"
          return                                   # return result of previous
        }                                          # command.
      done
}                                                  # return result of previous
                                                   # command.

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

  local  ChildMediaFolderPath ChildMediaName ComponentMediaPath I IW MediaInfo
  local  numActiveNormalComponents numActiveWriteMostlyComponents
  local  numSpareNormalComponents numSpareWriteMostlyComponents ParametersFile
  local  ParentMedia ParentMediaPath TmpTargetPath

  # parameters:
    local  -a  ActiveMedias ActiveWriteMostlyMedias
    local      RealizationMode
    local  -a  SpareMedias SpareWriteMostlyMedias
    local      UUID

  MediaInfo="$1"
  ParentMediaPath="$2"

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

  # echo  ${ActiveMedias[@]}                                      >>/dev/stderr
  # echo  ${ActiveWriteMostlyMedias[@]}                           >>/dev/stderr
  # echo  ${SpareMedias[@]}                                       >>/dev/stderr
  # echo  ${SpareWriteMostlyMedias[@]}                            >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"

  ComponentMediaName="$(
    disk_mediaAccess___0x088F_36_2ComponentMediaName                  \
      "$ParametersFile" "$ParentMediaPath"
  )"  || return                                    # return on error.
   echo  $ComponentMediaName                                     >>/dev/stderr

  disk_mediaAccess____0x088F_36_2ComponentMediaPath                   \
      "$ChildMediaName" "$ComponentMediaName"
return

  ChildMediaName="$UUID"
  ChildMediaFolderPath="$(
    disk_mediaAccess___2ChildMediaFolderPath  "$ChildMediaName"
  )"
  # echo  $ChildMediaFolderPath                                   >>/dev/stderr
  # echo  $ChildMediaName                                         >>/dev/stderr

  numActiveNormalComponents="${#ActiveMedias[@]}"
  numActiveWriteMostlyComponents="${#ActiveWriteMostlyMedias[@]}"
  numSpareNormalComponents="${#SpareMedias[@]}"
  numSpareWriteMostlyComponents="${#SpareWriteMostlyMedias[@]}"


  for ((I=0; I < numActiveNormalComponents; I++))
    do
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath  "${ActiveMedias[$I]}"
        )"  || return                              # return on error.
        # echo $TmpTargetPath                                     >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          f_ToAbsolutePath  "${ChildMediaFolderPath}/${ChildMediaName}.A${I}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I = 0; I < numActiveWriteMostlyComponents; I++))
    do
        let "IW = I + numActiveNormalComponents"
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath                               \
            "${ActiveWriteMostlyMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          f_ToAbsolutePath  "${ChildMediaFolderPath}/${ChildMediaName}.A${IW}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I=0; I < numSpareNormalComponents; I++))
    do
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath  "${SpareMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          f_ToAbsolutePath  "${ChildMediaFolderPath}/${ChildMediaName}.S${I}"
          return                                   # return result of previous
        }                                          # command.
      done

  for ((I = 0; I < numSpareWriteMostlyComponents; I++))
    do
        let "IW = I + numSpareNormalComponents"
        TmpTargetPath="$(
          disk_mediaAccess___Media2AbsolutePath                               \
            "${SpareWriteMostlyMedias[$I]}"
        )"  || return                              # return on error.
        # echo  $TmpTargetPath                                    >>/dev/stderr

        [ "$ParentMediaPath" = "$TmpTargetPath" ]  && {
          f_ToAbsolutePath  "${ChildMediaFolderPath}/${ChildMediaName}.S${IW}"
          return                                   # return result of previous
        }                                          # command.
      done
}                                                  # return result of previous
                                                   # command.

Xdisk_mediaAccess_0x088F_36_col__() {
  # $1: size;
  # $2: uuid;
  # $3: prefix; most often: indent;
  # * writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  PREFIX="$3"
  PREFIX1="  $PREFIX0"
  SIZE="$1"
  UUID="$2"

  MediaHandlerUuid="$(
    echo  "${FUNCNAME[1]}"                                     \
      | string__SearchAndReplace    '^disk_mediaAccess_*' ''   \
        | string_SearchAndReplace   '_'                   '-'  \
  )"

  disk_mediaAccess_0x088F_36_col___                            \
    "$MediaHandlerUuid" "$SIZE" "$UUID" "$PREFIX"
}


Xdisk_mediaAccess_0x088F_36_col___() {
  # $1: media-handler-uuid;
  # $2: size;
  # $3: uuid;
  # $4: prefix; most often: indent;
  # ^* writes the size-parameter to "stdout".

  local  MediaHandlerUuid PREFIX SIZE UUID

  MediaHandlerUuid="$1"
  PREFIX0="$4"
  PREFIX1="  $PREFIX0"
  SIZE="$2"
  UUID="$3"

  START='8' # ^
  # ^ sort parameters.

  disk_mediaAccess_col__METHOD              "$MediaHandlerUuid" "$PREFIX0"
    disk_mediaAccess_col__CommonParameters  "$MediaHandlerUuid" "$PREFIX1"
    disk_mediaAccess_col__SIZE              "$SIZE"             "$PREFIX1"
    disk_mediaAccess_col__START             "$START"            "$PREFIX1"
    disk_mediaAccess_col__UUID              "$UUID"             "$PREFIX1"
  disk_mediaAccess_col__MethodEnd                               "$PREFIX0"
}


Xdisk_mediaAccess_col__LINEAR() {                  # ': _LINEAR'
  # $1: size;
  # $2: uuid;
  # $3: prefix; most often: indent;
  # * writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB36_78F0_11E6_B6F3_0000C00A45A9  "_:"  "$@"
}


Xdisk_mediaAccess_col___LINEAR() {                  # ': __LINEAR'
  # $1: media-handler-uuid;
  # $2: size;
  # $3: uuid;
  # $4: prefix; most often: indent;
  # ^* writes the size-parameter to "stdout".

  disk_mediaAccess__A8A2BB36_78F0_11E6_B6F3_0000C00A45A9  "__:" "$@"
}


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

  # global:  Cat0x0EAA

  local      BitmapPath FileName INDEX MediaInfo ParentMedia ParentMediaPath

  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

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

  "$Cat0x0EAA"  "${BitmapPath}/$FileName"
}


disk_mediaAccess___0x088F_36_RM() {
  # removes the parent-media from the raid, 'mdadm --remove';
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>.

  # global:  DmSetup0x0EAA Rm0x0EAA

  local      ComponentMediaPath 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

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

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

  "$DmSetup0x0EAA"  remove  "ComponentMediaPath"                \
    || return                                      # return on error.

  "$Rm0x0EAA"  -f           "$ComponentMediaPath"
}

disk_mediaAccess___0x088F_36_RmDevice() {
  # removes the device from the raid, 'mdadm --remove';
  # $1: <DEVICE>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  local  DEVICE INDEX MediaInfo ParentMedia ParentMediaPath

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

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

  disk_mediaAccess____0x088F_36_ManagementCommand            \
    "$DEVICE" "$INDEX" 'remove' "$MediaInfo" "$ParentMedia"  \
    "$ParentMediaPath"
}


disk_mediaAccess____0x088F_36_2ComponentMediaPath() {
  # writes the component-media-name corresponding to the component-media-path to
  # "stdout";
  # $1: <ChildMediaName>,
  # $2: <ComponentMediaName>.

  local    ChildMediaFolderPath ChildMediaName ComponentMediaName

  ChildMediaName="$1"
  ComponentMediaName="$2"

  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $ComponentMediaName                                     >>/dev/stderr

  ChildMediaFolderPath="$(
    disk_mediaAccess___2ChildMediaFolderPath  "$ChildMediaName"
  )"
  # echo  $ChildMediaFolderPath                                   >>/dev/stderr

  echo  "${ChildMediaFolderPath}/$ComponentMediaName"
}


disk_mediaAccess____0x088F_36_byParameters() {
  # global:  AddDisk0x0EAA DeviceMapperBasePath0x0EAA MdAdm0x0EAA MkDir0x0EAA
  #          MediaInfoSize0x0EAA

  # global, imported from
  #                  "disk_mediaAccess_A8A2BB36_78F0_11E6_B6F3_0000C00A45A9()":
  #          ActiveMedias ActiveWriteMostlyMedias ALGORITHM ChildMediaName
  #          ChunkSize ComponentSize LEVEL RaidDevPath RealizationMode
  #          RealizationOptions SpareMedias SpareWriteMostlyMedias UUID

  local      ActiveMediaList BitMapChunk BitMapFile BitMapPath
  local      ChildMediaFolderPath FORCED ForthCommand I IW MAJOR MINOR
  local      numActiveComponents numActiveNormalComponents
  local      numActiveWriteMostlyComponents numSpareNormalComponents
  local      numSpareWriteMostlyComponents RaidDevice RaidParameters
  local      SpareMediaList TmpDeviceMapperMediaPath TmpMediaName TmpMediaPath
  local      WriteBehind

  [ "dm" == "$RealizationMode" ]  &&  {
    echo  -e  "\"RealizationMode = 'dm'\" is not supported yet.";  \
                                                                  >>/dev/stderr
    return 2;
  }

  [ "md" != "$RealizationMode" ]  &&  {
    echo  -e  "\"RealizationMode = '$RealizationMode'\" is not supported.";
                                                                  >>/dev/stderr
    return 2;
  }

  ActiveMediaList=''

  ChildMediaFolderPath="$(
    disk_mediaAccess___2ChildMediaFolderPath  "$ChildMediaName"
  )"
  # echo  $ChildMediaFolderPath                                   >>/dev/stderr
    "$MkDir0x0EAA"  -p  "$ChildMediaFolderPath"

  numActiveNormalComponents="${#ActiveMedias[@]}"
  numActiveWriteMostlyComponents="${#ActiveWriteMostlyMedias[@]}"
  let "numActiveComponents                                                   \
       = numActiveNormalComponents + numActiveWriteMostlyComponents"

  numSpareNormalComponents="${#SpareMedias[@]}"
  numSpareWriteMostlyComponents="${#SpareWriteMostlyMedias[@]}"

  # echo  $numActiveComponents                                    >>/dev/stderr
  # echo  $numActiveWriteMostlyComponents                         >>/dev/stderr
  # echo  $numSpareNormalComponents                               >>/dev/stderr
  # echo  $numSpareWriteMostlyComponents                          >>/dev/stderr

  for ((I=0; I < numActiveNormalComponents; I++))
    do
        TmpMediaName="${ChildMediaName}.A${I}"
        TmpDeviceMapperMediaPath="${DeviceMapperBasePath0x0EAA}/$TmpMediaName"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpDeviceMapperMediaPath                         >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        disk_mediaAccess___LinearTable                                   \
          "$TmpMediaName" "${ActiveMedias[$I]}"                          \
          "$RealizationOptions" "$ComponentSize" "$MediaInfoSize0x0EAA"  \
          || return                                # return on error.

        ln  -s  "$TmpDeviceMapperMediaPath" "$TmpMediaPath"
        ActiveMediaList+="$TmpMediaPath "
      done
  # echo  A: $ActiveMediaList                                     >>/dev/stderr

  for ((I = 0; I < numActiveWriteMostlyComponents; I++))
    do
        let "IW = I + numActiveNormalComponents"
        TmpMediaName="${ChildMediaName}.A${IW}"
        TmpDeviceMapperMediaPath="${DeviceMapperBasePath0x0EAA}/$TmpMediaName"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpDeviceMapperMediaPath                         >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        disk_mediaAccess___LinearTable                                   \
          "$TmpMediaName" "${ActiveWriteMostlyMedias[$I]}"               \
          "$RealizationOptions" "$ComponentSize" "$MediaInfoSize0x0EAA"  \
          || return                                # return on error.

        ln  -s  "$TmpDeviceMapperMediaPath" "$TmpMediaPath"
        ActiveMediaList+="--write-mostly $TmpMediaPath "
      done
  # echo  A: $ActiveMediaList                                     >>/dev/stderr

  for ((I=0; I < numSpareNormalComponents; I++))
    do
        TmpMediaName="${ChildMediaName}.S${I}"
        TmpDeviceMapperMediaPath="${DeviceMapperBasePath0x0EAA}/$TmpMediaName"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpDeviceMapperMediaPath                         >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        disk_mediaAccess___LinearTable                                   \
          "$TmpMediaName" "${SpareMedias[$I]}"                           \
          "$RealizationOptions" "$ComponentSize" "$MediaInfoSize0x0EAA"  \
          || return                                # return on error.

        ln  -s  "$TmpDeviceMapperMediaPath" "$TmpMediaPath"
        SpareMediaList+="$TmpMediaPath "
      done
  # echo  S: $SpareMediaList                                      >>/dev/stderr

  for ((I = 0; I < numSpareWriteMostlyComponents; I++))
    do
        let "IW = I + numSpareNormalComponents"
        TmpMediaName="${ChildMediaName}.S${IW}"
        TmpDeviceMapperMediaPath="${DeviceMapperBasePath0x0EAA}/$TmpMediaName"
        TmpMediaPath="${ChildMediaFolderPath}/$TmpMediaName"

        # echo  $TmpMediaName                                     >>/dev/stderr
        # echo  $TmpDeviceMapperMediaPath                         >>/dev/stderr
        # echo  $TmpMediaPath                                     >>/dev/stderr

        disk_mediaAccess___LinearTable                                   \
          "$TmpMediaName" "${SpareWriteMostlyMedias[$I]}"                \
          "$RealizationOptions" "$ComponentSize" "$MediaInfoSize0x0EAA"  \
          || return                                # return on error.

        ln  -s  "$TmpDeviceMapperMediaPath" "$TmpMediaPath"
        SpareMediaList+="--write-mostly $TmpMediaPath "
      done

  if [ "0" != "$numActiveComponents" ]; then
      ActiveMediaList="--raid-devices=$numActiveComponents  $ActiveMediaList"
    else
      ActiveMediaList=''
    fi
# echo  A: $ActiveMediaList                                       >>/dev/stderr
# echo  S: $SpareMediaList                                        >>/dev/stderr

  BitMapFile="$(
    disk_mediaAccess__GetRealizationOption  "$RealizationOptions" 'bitmap-file'
  )"
  BitMapPath="${ChildMediaFolder}/$BitMapFile"

  BitMapChunk="$(
    disk_mediaAccess__GetRealizationOption  "$RealizationOptions" 'bitmap-chunk'
  )"
  WriteBehind="$(
    disk_mediaAccess__GetRealizationOption  "$RealizationOptions" 'write-behind'
  )"

# echo  "BitMapFile: $BitMapFile"                                 >>/dev/stderr

  if [ "0" == "$LEVEL"  -o "1" == "$LEVEL" ]; then
      # supported by "mdadm --build".
        RaidParameters='--assume-clean '
#^ 1*) not for raid0:
        [ -n "$BitMapFile" ]   && RaidParameters+="--bitmap=$BitMapPath "

#^ 1*) not for raid0; but works!
        [ -n "$BitMapChunk" ]  && RaidParameters+="--bitmap-chunk=$BitMapChunk "

#^ 1*) omit if == 0;
#^ 1*), 3*) not for raid1:       RaidParameters+="--chunk=$ChunkSize "
        RaidParameters+="--level=$LEVEL "
#^ 1*) not for raid1:  RaidParameters+="--layout=$ALGORITHM "
#        RaidParameters+="--raid-devices=$numActiveComponents "
#^ 1*), 2*) not for raid0:
        [ -n "$WriteBehind" ]  && RaidParameters+="--write-behind=$WriteBehind"
        #^  [ -n "$WriteMostly" ]  && RaidParameters#^pen  [ -n "$WriteMostly" ]
        # echo  $RaidParameters                                   >>/dev/stderr
        "$MdAdm0x0EAA"  --build  $RaidDevPath $RaidParameters $ActiveMediaList  \
          || return                                # return on error.
#^ mdadm: :option --spare-devices not valid in build mode
        # * error: "mdadm: :option --spare-devices not valid in build mode";
        #   so:
          "$MdAdm0x0EAA"  --add  $RaidDevPath  $SpareMediaList
           # ^this works; the writemostly active disk is replaced with a
           # writemostly spare disk.

#^ 1*), 2*) not for raid0?: "-W" but works!
#^ 2*) according to "man mdadm", only valid for RAID1 !
#^ 3*) according to "man mdadm", not for RAID1 !

# * "--bitmap="$(pwd)/BitMap.BIN": must be a path!
# * "--write-behind=16383":  max. 16383
      return
    fi

  echo  -en  "\nStart Raid manually in \"forth\";"                >>/dev/stderr
  echo                                " hit <return> when done;"  >>/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"  || return
      done                                         # return on error.

  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                                " hit <return> when done;"  >>/dev/stderr
  echo  -e   "  * Forth-Command: \"$ForthCommand\"."              >>/dev/stderr
  read
}


disk_mediaAccess____0x088F_36_CreateBaseMedia() {
  # creates the base-media (for the raid-leg) and writes the component-media-
  # name corresponding to the parent-media to "stdout";
  # $1: <MediaInfo>,
  # $2: <ParentMedia>,
  # $3: <ParentMediaPath>,
  # $4: <RealizationOptions>.

  # global:  DeviceMapperBasePath0x0EAA MediaInfoSize0x0EAA

  local      ChildMediaName ComponentMediaName ComponentMediaPath
  local      DeviceMapperComponentMediaPath MediaInfo ParentMedia ParentMediaPath ParametersFile

  # parameters:
    local    ComponentSize RealizationOptions UUID

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

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

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

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

  # echo  $ComponentSize                                          >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr

  ChildMediaName="$UUID"

  ComponentMediaName="$(
    disk_mediaAccess___0x088F_36_2ComponentMediaName                  \
      "$ParametersFile" "$ParentMediaPath"
  )"  || return                                    # return on error.
  # echo  $ComponentMediaName                                     >>/dev/stderr

  ComponentMediaPath="$(
    disk_mediaAccess____0x088F_36_2ComponentMediaPath                 \
      "$ChildMediaName" "$ComponentMediaName"                         \
        || return                                  # return on error.
  )"
  # echo  $ComponentMediaPath                                     >>/dev/stderr

  DeviceMapperComponentMediaPath="$DeviceMapperBasePath0x0EAA"
  DeviceMapperComponentMediaPath+="/$ComponentMediaName"

  # echo  $DeviceMapperComponentMediaPath                         >>/dev/stderr

  disk_mediaAccess___LinearTable                                   \
    "$ComponentMediaName" "$ParentMedia"                           \
    "$RealizationOptions" "$ComponentSize" "$MediaInfoSize0x0EAA"  \
      || return                                    # return on error.

  ln  -s  "$DeviceMapperComponentMediaPath" "$ComponentMediaPath"

  echo  $ComponentMediaPath
}


disk_mediaAccess____0x088F_36_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"

  ComponentMediaPath="$(f_ToAbsolutePath  "$ComponentMediaPath")"

  # 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"
}