#!/usr/local/bin/scripts/sh
#
# pen^:
# * "disk_mediaAccess__0x0891_GetPeerIp()" takes peer-name, not peer-index.
# * 'split' "disk_mediaAccess__0x0891_SyncBuffersAndSuspendIo()" into 'SYNC'...
# * "disk_mediaAccess__0x0891_WaitForSyncAndCopy()" additonally task peer-name.
# * before removing 'base-device' wait for vanishing of drbd-device --> 'holders'.

#
#.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/_A8A2BB38_78F0_11E6_B6F3_0000C00A45A9!0.!c
#
#/*******************************************************************************
#     io disk mediaAccess mediaHandlers.d/A8A2BB38_78F0_11E6_B6F3_0000C00A45A9
#     ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#
#     purpose             : media handler for drbd (distributed replicated block
#                           devices)
#
#     begin               : Mon May 15 14:33:04 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("A8A2BB38_78F0_11E6_B6F3_0000C00A45A9") = 0x0891
#
# * for every function:
#   * if returned result is not commented, the function returns 0 on no-error.


disk_mediaAccess_A8A2BB38_78F0_11E6_B6F3_0000C00A45A9() {
  # handles a 'drbd'-media (as a dm-linear media);
  # ^ not yet finished, has additional parameters.
  # $1: command, in {
  #       "2ChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #       "SIZE", "VERIFY", "WAIT", "_:", "__:"
  #     },
  #     * $1 in {
  #         "2ChildDev", "2ChildMedia", "DESTROY", "REALIZE", "RealizeForced",
  #         "SIZE", "VERIFY", "WAIT"
  #       }: see "../CommonCommandsSpecification.TXT",
  # detailed descitpion see: "disk_mediaAccess__A8A2BB2D_78F0_11E6_B6F3_0000C00A45A9()".

  # * quick and dirty, incorrect and absolutely not final:

  local  COMMAND FORCED INDEX MediaInfo ParentMedia ParentMediaPath ROLE
  local  TargetIndex WaitTime

  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: $FORCED                                          >>/dev/stderr

  case "$COMMAND" in
# ok.
      2ChildDev)
        disk_mediaAccess___2ChildDev                               \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
# ok.
      2ChildMedia)
        disk_mediaAccess__0x0891_2ChildMedia                       \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ok.
      BASE)                                        # get base media path.
        disk_mediaAccess__0x0891_BASE                              \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ok.
      CHECK|REPAIR)  return  0                                     ;;
# ok.
      DESTROY)
        disk_mediaAccess__0x0891_DESTROY                           \
          "$COMMAND"                                               \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
# ok.
      DrbdAdm)
        shift  5
        disk_mediaAccess__0x0891_DrbdAdm                           \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  \
          "$@"                                                     ;;
# ok.
      REALIZE|RealizeForced)
        disk_mediaAccess__0x0891_REALIZE                           \
          ''  ''     "$COMMAND"                                    \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
# ok.
      RealizeAlternateMedia)
        disk_mediaAccess__0x0891_REALIZE                           \
          'A' '.ALT' 'REALIZE'                                     \
          "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"  ;;
# ok.
      RESOURCE)                                    # get resource name.
        disk_mediaAccess__0x0891_RESOURCE                          \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ok.
      ResumeIo)
        disk_mediaAccess__0x0891_ResumeIo                          \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ok.
      ROLE)                                        # set role.
        ROLE="$6"
        disk_mediaAccess__0x0891_ROLE                              \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  \
          "$ROLE"                                                  ;;
# ok.
      SIZE)
        disk_mediaAccess__Size0 '0'      "$MediaInfo"              ;;
# ok.
      SuspendIo)
        disk_mediaAccess__0x0891_SuspendIo                         \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  ;;
# ok.
      SyncBuffersAndSuspendIo)
        WaitTime="$6"
        disk_mediaAccess__0x0891_SyncBuffersAndSuspendIo           \
          "$INDEX" "$MediaInfo"                "$ParentMediaPath"  \
          "$WaitTime"                                              ;;
      WaitForSyncAndCopy)
        TargetIndex="$6"
        disk_mediaAccess__0x0891_WaitForSyncAndCopy                \
          "$INDEX" "$MediaInfo" "$ParentMedia"  "$ParentMediaPath" \
          "$TargetIndex"                                           ;;
      *)
        disk_mediaAccess___NoContainer                             \
          "$COMMAND" "$INDEX" "$ParentMedia"                       \
          || return                                # return on error.

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


disk_mediaAccess__0x0891_2ChildMedia() {
  # converts the parent-media, denoted by the "<ParentMediaPath>", the
  # "index into the container" and the "<MediaInfo>" to its child-media and
  # writes it to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local  ChildMedia INDEX MediaInfo ParentMediaPath

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

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

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

  disk_mediaAccess__WriteQualifiedUuid  "$ChildMedia"
}


disk_mediaAccess__0x0891_2ChildMediaName() {
  # converts the parent-media, denoted by the "<ParentMediaPath>", the
  # "index into the container" and the "<MediaInfo>" to its child-media-name
  # and writes it to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local  ChildMediaName INDEX MediaInfo ParentMediaPath RESULT

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

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

  ChildMediaName="$(disk_mediaAccess___2ChildUuid  "$MediaInfo")"  \
    || return                                      # return on error.
  # echo  $ChildMediaName                                         >>/dev/stderr

  disk_mediaAccess__0x0891_isAlternateMedia                        \
    "$INDEX" "$MediaInfo" "$ParentMediaPath"
    RESULT="$?"
    # echo  $RESULT                                               >>/dev/stderr
    [ "1" == "$RESULT" ]  && return  "$RESULT"     # return on error.

  [ "0" == "$RESULT" ]  && ChildMediaName="${ChildMediaName}.ALT"
                                                   # 'alternate drbd-device'.
  echo  "$ChildMediaName"
}


disk_mediaAccess__0x0891_ApiVersion() {
  # writes the drbd-api-version to "stdout".

  # global:  DrbdAdm0x0EAA

  local      ApiVersion

  ApiVersion="$(
    "$DrbdAdm0x0EAA"  -V                                      \
      | grep                       'DRBDADM_API_VERSION'      \
        | string_SearchAndReplace  'DRBDADM_API_VERSION=' ''
  )"

  echo  "$ApiVersion"
}


disk_mediaAccess__0x0891_BASE() {
  # gets the drbd base media path from the media and writes it to "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local    ChildMediaName INDEX MediaInfo ParametersFile ParentMediaPath SUFFIX

  # parameters:
    local  LocalNodeId

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

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

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

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

  # echo  $LocalNodeId                                            >>/dev/stderr

  SUFFIX="$(
    disk_mediaAccess__0x0891_SUFFIX  '' "$LocalNodeId" "$ParametersFile"
  )"
 #  echo  $SUFFIX                                                 >>/dev/stderr

  disk_mediaAccess__WriteQualifiedUuid  "${ChildMediaName}$SUFFIX"
}


disk_mediaAccess__0x0891_BaseMediaByUuidPath() {
  # gets the drbd base media name from the media and writes it to "stdout";
  # $1: <ALTERNATE>.
  # $2: <NodeId>.
  # $3: path to parameters-file,

  # global:  DisksByUuidMountPath0x0EAA

  local      ALTERNATE BaseMediaName BaseMediaByUuidPath NodeId ParametersFile
  local      SUFFIX

  # parameters:
  local      UUID

  ALTERNATE="$1"
  NodeId="$2"
  ParametersFile="$3"

  # echo  $ALTERNATE                                              >>/dev/stderr
  # echo  $NodeId                                                 >>/dev/stderr
  # echo  $ParametersFile                                         >>/dev/stderr

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

  # echo  $UUID                                                   >>/dev/stderr

  SUFFIX="$(
    disk_mediaAccess__0x0891_SUFFIX                                   \
      "$ALTERNATE" "$NodeId" "$ParametersFile"
  )"

  BaseMediaName="${UUID}$SUFFIX"
  BaseMediaByUuidPath="${DisksByUuidMountPath0x0EAA}/$BaseMediaName"
  echo  "$BaseMediaByUuidPath"
}


disk_mediaAccess__0x0891_ConfigHasHandlerSection() {
  # returns true (0), if at least one 'handler for drbd' is specified;
  # $1: path to parameters-file.

  local  ParametersFile

  #^ parameters:

  ParametersFile="$1"

  # clear optional not ignored parameters.
    AfterResyncTarget=''
    BeforeResyncTarget=''
    FencePeer=''
    LocalIoError=''
    OutOfSync=''
    PriLostAfterSb=''
    PriOnInconDegr=''
    SplitBrain=''

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

  [                              \
       -n "$AfterResyncTarget"   \
    -o -n "$BeforeResyncTarget"  \
    -o -n "$FencePeer"           \
    -o -n "$LocalIoError"        \
    -o -n "$OutOfSync"           \
    -o -n "$PriLostAfterSb"      \
    -o -n "$PriOnInconDegr"      \
    -o -n "$SplitBrain"          \
  ]                                                # return result of previous
}                                                  # command.


disk_mediaAccess__0x0891_ConfigHasOnDiskSection() {
  # returns true (0), if at least one parameter for the "disk"-section is specified;
  # $1: path to parameters-file.

  local  ParametersFile

  # parameters:
  local  CMinRate CPlanAhead ResyncRate


  ParametersFile="$1"

  # clear optional not ignored parameters.
    CMinRate=''
    CPlanAhead=''
    ResyncRate=''

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

  [                                \
       -n "$CMinRate"              \
    -o -n "$CPlanAhead"            \
    -o -n "$ResyncRate"            \
  ]                                                # return result of previous
}                                                  # command.


disk_mediaAccess__0x0891_ConfigMaybeWriteHandlerSection() {
  # if at least one 'handler for drbd' is specified, writes the handler-section
  # to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.

  local  ParametersFile PREFIX0 PREFIX1

  #^ parameters:

  ParametersFile="$1"
  PREFIX0="$2"
  PREFIX1="${PREFIX0}  "

  disk_mediaAccess__0x0891_ConfigHasHandlerSection                            \
    "$ParametersFile"  || return 0                 # no handler-section.

  disk_mediaAccess__0x0891_ConfigWriteSectionHeader                           \
    'handlers'                                                    "$PREFIX0"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'after-resync-target'  'AfterResyncTarget'  "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'before-resync-target' 'BeforeResyncTarget' "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'fence-peer'           'FencePeer'          "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'local-io-error'       'LocalIoError'       "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'out-of-sync'          'OutOfSync'          "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'pri-lost-after-sb'    'PriLostAfterSb'     "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'pri-on-incon-degr'    'PriOnInconDegr'     "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                          \
    "$ParametersFile" 'split-brain'          'SplitBrain'         "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteSectionEnd                  "$PREFIX0"
}


disk_mediaAccess__0x0891_ConfigMaybeWriteOnDiskSection() {
  # if at least one parameter for the "disk"-section is specified, writes an
  # "on-disk-section" to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.

  local  ParametersFile PREFIX0 PREFIX1

  # parameters:
  local  CMinRate CPlanAhead ResyncRate

  ParametersFile="$1"
  PREFIX0="$2"
  PREFIX1="${PREFIX0}  "

  disk_mediaAccess__0x0891_ConfigHasOnDiskSection             \
    "$ParametersFile"  || return 0                 # no on-disk-sectionn.

  disk_mediaAccess__0x0891_ConfigWriteSectionHeader           \
    'disk'                                        "$PREFIX0"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter          \
    "$ParametersFile" 'c-min-rate'   'CMinRate'   "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter          \
    "$ParametersFile" 'c-plan-ahead' 'CPlanAhead' "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter          \
    "$ParametersFile" 'resync-rate'  'ResyncRate' "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteSectionEnd  "$PREFIX0"
}


disk_mediaAccess__0x0891_ConfigMaybeWriteParameter() {
  # if the mediaacess-parmeter, that corresponds to a drbd-parameter, is
  # specificied, writes the parameter-specification to "stdout";
  # $1: path to parameters-file.
  # $2: drbd-parameter-name,
  # $3: 'mediaAccess'-parameter-name,
  # $4: prefix; most often: indent.

  local  MediaAccess_NAME ParametersFile PREFIX

  #^ parameters:

  Drbd_NAME="$2"
  MediaAccess_NAME="$3"
  ParametersFile="$1"
  PREFIX="$4"

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

  [ -n "${!MediaAccess_NAME}" ]  || return 0       # parameter not set.

  disk_mediaAccess__0x0891_ConfigWriteParameter  \
    "$Drbd_NAME" "${!MediaAccess_NAME}" "$PREFIX"
}


disk_mediaAccess__0x0891_ConfigWrite() {
  # writes the configuration file corresponding to the parameters;
  # $1: <ALTERNATE>,
  # $2: <MediaInfo>,
  # $3: <RESOURCE>.

  # global:  DrbdConfigFolder0x0EAA

  local      ALTERNATE MediaInfo RESOURCE

  ALTERNATE="$1"
  MediaInfo="$2"
  RESOURCE="$3"

  disk_mediaAccess___0x0891_ConfigWrite  "$ALTERNATE" "$MediaInfo"  \                                       \
    >"$DrbdConfigFolder0x0EAA/${RESOURCE}.res"
}


disk_mediaAccess__0x0891_ConfigWriteHeader() {
  # writes the header of the configuration file, corresponding to the
  # parameters, to "stdout";
  # $1: path to parameters-file,
  # $2: <ALTERNATE>.

  local  ALTERNATE ParametersFile RESOURCE

  ALTERNATE="$2"
  ParametersFile="$1"

  RESOURCE="$(
    disk_mediaAccess___0x0891_RESOURCE  "$ALTERNATE" "$ParametersFile"
  )"

  echo  "resource  $RESOURCE {"
}


disk_mediaAccess__0x0891_ConfigWriteLocalOnSection() {
  # writes the local "on-section" of the configuration file, corresponding to
  # the parameters, to "stdout";
  # $1: path to parameters-file,
  # $2: <ALTERNATE>,
  # $3: prefix; most often: indent.

  local  ALTERNATE ParametersFile PREFIX

  ALTERNATE="$2"
  ParametersFile="$1"
  PREFIX="$3"

  disk_mediaAccess__0x0891_ConfigWriteOnSection   \
    "$ParametersFile" 'L' "$ALTERNATE" "$PREFIX"
}


disk_mediaAccess__0x0891_ConfigWriteMetadiskParameter() {
  # writes the metadisk-parameter-specification of the configuration file,
  # corresponding to the parameters, to "stdout";
  # $1: path to parameters-file.
  # $2: ^peer-index in { "L" } V [0, <infinity> )[N],
  #     * L: local metadata-disk.
  # $3: prefix; most often: indent.

  # global:  DisksByUuidMountPath0x0EAA

  local     _MetaDataIndex _MetaDataMedia _MetaDataMediaPath ParametersFile
  local     PeerIndex PREFIX

  #^ parameters:

  ParametersFile="$1"
  PeerIndex="$2"
  PREFIX="$3"

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

  # echo  $LocalMetaDataIndex                                     >>/dev/stderr
  # echo  $LocalMetaDataMedia                                     >>/dev/stderr
  # echo  ${PeerMetaDataIndex[*]}                                 >>/dev/stderr
  # echo  ${PeerMetaDataMedia[*]}                                 >>/dev/stderr

  if [ 'L' == "$PeerIndex" ]; then
      _MetaDataIndex="$LocalMetaDataIndex"
      _MetaDataMedia="$LocalMetaDataMedia"
    else
      _MetaDataIndex="${PeerMetaDataIndex[$PeerIndex]}"
      _MetaDataMedia="${PeerMetaDataMedia[$PeerIndex]}"
    fi

  # echo  $_MetaDataIndex                                         >>/dev/stderr
  # echo  $_MetaDataMedia                                         >>/dev/stderr
  # echo  $_NodeId                                                >>/dev/stderr

  if [ 'THIS' == "${_MetaDataMedia}" ]; then
      disk_mediaAccess__0x0891_ConfigWriteParameter                            \
        'meta-disk' 'internal' "$PREFIX"
    else
      _MetaDataMediaPath="${DisksByUuidMountPath0x0EAA}/${_MetaDataMedia}"

      if [ -z "${_MetaDataIndex}" ]; then
          # no index.
            disk_mediaAccess__0x0891_ConfigWriteParameter                      \
              'meta-disk' "${_MetaDataMediaPath}"                   "$PREFIX"
        else
            disk_mediaAccess__0x0891_ConfigWriteParameter                      \
              'meta-disk' "${_MetaDataMediaPath} ${_MetaDataIndex}" "$PREFIX"
       fi
    fi
}


disk_mediaAccess__0x0891_ConfigWriteNetSection() {
  # writes the "net-section" of the configuration file, corresponding to the
  # parameters, to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.

  local  ParametersFile PREFIX0 PREFIX1

  #^ parameters:

  ParametersFile="$1"
  PREFIX0="$2"
  PREFIX1="${PREFIX0}  "

  disk_mediaAccess__0x0891_ConfigWriteSectionHeader                  \
    'net'                                                "$PREFIX0"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'congestion-fill' 'CongestionFill' "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'connect-int'     'ConnectInt'     "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'csums-alg'       'CsumsAlg'       "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'on-congestion'   'OnCongestion'   "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'protocol'        'PROTOCOL'       "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'timeout'         'DrbdTimeout'    "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteTransportParameter             \
    "$ParametersFile"                                    "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter                 \
    "$ParametersFile" 'verify-alg'      'VerifyAlg'      "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteSectionEnd                     \
                                                         "$PREFIX0"
}


disk_mediaAccess__0x0891_ConfigWriteNodeIdParameter() {
  # writes the "node-id-parameter" of the "on-section" of the configuration
  # file to "stdout";
  # $1: <NodeId>,
  # $2: prefix; most often: indent.

  local  ApiVersion NodeId PREFIX

  NodeId="$1"
  PREFIX="$2"

  ApiVersion="$(disk_mediaAccess__0x0891_ApiVersion)"
  # echo  $ApiVersion                                             >>/dev/stderr


  disk_mediaAccess__0x0891_ConfigWriteNodeIdParameterApiV${ApiVersion}  \
    "$NodeId" "$PREFIX"
}


disk_mediaAccess__0x0891_ConfigWriteNodeIdParameterApiV1() {
  # writes the "node-id-parameter" of the "on-section" of the configuration
  # file according to api-version = 1 to "stdout";
  # $1: <NodeId>,
  # $2: prefix; most often: indent.
  :                                                # does actually nothing.
}


disk_mediaAccess__0x0891_ConfigWriteNodeIdParameterApiV2() {
  # writes the "node-id-parameter" of the "on-section" of the configuration
  # file according to api-version = 2 to "stdout";
  # $1: <NodeId>,
  # $2: prefix; most often: indent.

  local  NodeId PREFIX

  NodeId="$1"
  PREFIX="$2"

  disk_mediaAccess__0x0891_ConfigWriteParameterNoQuotes  \
    'node-id' "$NodeId" "$PREFIX"
}


disk_mediaAccess__0x0891_ConfigWriteOnSection() {
  # writes an "on-section" of the configuration file, corresponding to the
  # parameters, to "stdout";
  # $1: path to parameters-file,
  # $2: ^peer-index in { "L" } V [0, <infinity> )[N],
  #     * L: local metadata-disk.
  # $3: <ALTERNATE>,
  # $4: prefix; most often: indent.

  local  ALTERNATE _ADDR BaseMediaByUuidPath _MINOR _NAME _NodeId
  local  ParametersFile PeerIndex PREFIX0 PREFIX1 PREFIX2

  #^ parameters:

  ALTERNATE="$3"
  ParametersFile="$1"
  PeerIndex="$2"
  PREFIX0="$4"
  PREFIX1="${PREFIX0}  "
  PREFIX2="${PREFIX1}  "

  # echo  $PeerIndex                                              >>/dev/stderr

  [ 'A' == "$ALTERNATE"  -a 'L' != "$PeerIndex" ]  && return 0
                                                   # for an alternate resource
                                                   # write only the local on
                                                   # section.
  .  "$ParametersFile"  || return                  # return on error.

  if [ 'A' == "$ALTERNATE" ]; then
      if [ 'L' == "$PeerIndex" ]; then
          _ADDR="$(                                                     \
            echo  "$LocalAddr"                                          \
              | string__SearchAndReplace                                \
                  ':.[0-9]*\..[0-9]*\..[0-9]*\..[0-9]*:' ':127.0.0.1:'
          )"
          _MINOR="$AltLocalMinor"
          _NAME="$(hostname)"
          _NodeId="$LocalNodeId"
        fi
    else
      if [ 'L' == "$PeerIndex" ]; then
          _ADDR="$LocalAddr"
          _MINOR="$LocalMinor"
          _NAME="$(hostname)"
          _NodeId="$LocalNodeId"
        else
          _ADDR="${PeerAddr[$PeerIndex]}"
          _MINOR="${PeerMinor[$PeerIndex]}"
          _NAME="${PeerName[$PeerIndex]}"
          _NodeId="${PeerNodeId[$PeerIndex]}"
        fi
    fi

   # echo  ${_NodeId}                                             >>/dev/stderr

  _ADDR="$(
    echo  "${_ADDR}"                                           \
      | string_SearchAndReplace          'ipv4:'    'ipv4 '    \
        | string_SearchAndReplace        'ipv6:'    'ipv6 '    \
          | string_SearchAndReplace      'sci:'     'sci '     \
            | string_SearchAndReplace    'sdp:'     'sdp '     \
              | string_SearchAndReplace  'ssocks:'  'ssocks '
   )"

  BaseMediaByUuidPath="$(
    disk_mediaAccess__0x0891_BaseMediaByUuidPath               \
      "$ALTERNATE" "${_NodeId}" "$ParametersFile"
  )"
  # echo  $BaseMediaByUuidPath                                    >>/dev/stderr

  disk_mediaAccess__0x0891_ConfigWriteSectionHeader            \
    "on ${_NAME}"                      "$PREFIX0"
  disk_mediaAccess__0x0891_ConfigWriteParameterNoQuotes        \
    'address'  "${_ADDR}"              "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteNodeIdParameter          \
              "${_NodeId}"            "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteSectionHeader            \
    "volume $VOLUME"                   "$PREFIX1"
  disk_mediaAccess__0x0891_ConfigWriteParameter                \
    'device'   "/dev/drbd${_MINOR}"    "$PREFIX2"
  disk_mediaAccess__0x0891_ConfigWriteParameter                \
    'disk'     "$BaseMediaByUuidPath"  "$PREFIX2"
  disk_mediaAccess__0x0891_ConfigMaybeWriteOnDiskSection       \
    "$ParametersFile"                  "$PREFIX2"
  disk_mediaAccess__0x0891_ConfigWriteMetadiskParameter        \
    "$ParametersFile" "$PeerIndex"     "$PREFIX2"
  disk_mediaAccess__0x0891_ConfigWriteSectionEnd               \
                                       "$PREFIX1"   # volume.
  disk_mediaAccess__0x0891_ConfigWriteSectionEnd               \
                                       "$PREFIX0"   # on.
}


disk_mediaAccess__0x0891_ConfigWriteParameter(){
  # writes the parameter-specification to "stdout";
  # $1: parameter-name,
  # $2: parameter-value,
  # $2: prefix; most often: indent.

  local  NAME PREFIX VALUE

  NAME="$1"
  PREFIX="$3"
  VALUE="$2"

  echo  -e  "${PREFIX}${NAME}  \"$VALUE\";"
}


disk_mediaAccess__0x0891_ConfigWriteParameterNoQuotes(){
  # writes the parameter-specification without quoting ("...") to "stdout";
  # $1: parameter-name,
  # $2: parameter-value,
  # $2: prefix; most often: indent.

  local  NAME PREFIX VALUE

  NAME="$1"
  PREFIX="$3"
  VALUE="$2"

  echo  -e  "${PREFIX}${NAME}  $VALUE;"
}


disk_mediaAccess__0x0891_ConfigWriteSectionEnd() {
  # writes the end of a section to "stdout";
  # $1: prefix; most often: indent.

  local  PREFIX

  PREFIX="$1"

  echo  "${PREFIX}}"
}


disk_mediaAccess__0x0891_ConfigWriteSectionHeader() {
  # writes a section-header, corresponding to the parameter, to "stdout";
  # $1: section name,
  # $2: prefix; most often: indent.

  local  NAME PREFIX

  NAME="$1"
  PREFIX="$2"

  echo  "${PREFIX}${NAME} {"
}


disk_mediaAccess__0x0891_ConfigWriteTransportParameter() {
  # writes the "transport-parameter" of the "net-section" of the configuration
  # file to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.

  local  ApiVersion ParametersFile PREFIX

  ParametersFile="$1"
  PREFIX="$2"

  ApiVersion="$(disk_mediaAccess__0x0891_ApiVersion)"
  # echo  $ApiVersion                                             >>/dev/stderr

  disk_mediaAccess__0x0891_ConfigWriteTransportParameterApiV${ApiVersion}  \
    "$ParametersFile" "$PREFIX"
}


disk_mediaAccess__0x0891_ConfigWriteTransportParameterApiV1() {
  # writes the "transport-parameter" of the "net-section" of the configuration
  # file; according to api-version = 1 to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.
  :                                                # does actually nothing.
}


disk_mediaAccess__0x0891_ConfigWriteTransportParameterApiV2() {
  # writes the "transport-parameter" of the "net-section" of the configuration
  # file; according to api-version = 2 to "stdout";
  # $1: path to parameters-file,
  # $2: prefix; most often: indent.

  local    ParametersFile PREFIX

  # parameters:
    local  TRANSPORT

  ParametersFile="$1"
  PREFIX="$2"

  disk_mediaAccess__0x0891_ConfigMaybeWriteParameter     \
    "$ParametersFile" 'transport' 'TRANSPORT' "$PREFIX"
}


disk_mediaAccess__0x0891_DESTROY() {
  # destroy media or alternate media;
  # $1: <COMMAND>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMedia>,
  # $5: <ParentMediaPath>.

  # global:  DrbdAdm0x0EAA

  local      ALTERNATE ChildDev ChildDevPath ChildMediaName COMMAND INDEX
  local      MediaInfo ParametersFile ParentMedia ParentMediaPath RESULT
  local      RESOURCE SUFFIX

  # parameters:
    local    LocalNodeId

  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

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

  ChildMediaName="$(
    disk_mediaAccess__0x0891_2ChildMediaName                            \
      "$INDEX" "$MediaInfo" "$ParentMediaPath"
  )"  || return                                    # return on error.
  ChildMediaPath="$(disk_mediaAccess__DeviceName2Path  "$ChildDev")"
  # echo  $ChildDev                                               >>/dev/stderr
  # echo  $ChildMediaName                                         >>/dev/stderr
  # echo  $ChildMediaPath                                         >>/dev/stderr

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

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

  disk_mediaAccess__0x0891_isAlternateMedia                             \
    "$INDEX" "$MediaInfo" "$ParentMediaPath"
    RESULT="$?"
    # echo  $RESULT                                               >>/dev/stderr
    [ "1" == "$RESULT" ]  && return  "$RESULT"     # return on error.

  ALTERNATE=''
  [ "0" == "$RESULT" ]  && ALTERNATE='A'

  RESOURCE="$(
    disk_mediaAccess___0x0891_RESOURCE  "$ALTERNATE" "$ParametersFile"  \
  )"
  SUFFIX="$(
    disk_mediaAccess__0x0891_SUFFIX                                     \
      "$ALTERNATE" "$LocalNodeId" "$ParametersFile"
  )"

  # echo  $RESOURCE                                               >>/dev/stderr
  # echo  $SUFFIX                                                 >>/dev/stderr

  # must be done before stopping the drbd-device.
    disk_mediaAccess___UnMap      "$ChildMediaName"                     \

  "$DrbdAdm0x0EAA"      down                 "$RESOURCE"  || {
     # 'down' failed; try:
      "$DrbdAdm0x0EAA"  disconnect  --force  "$RESOURCE"  &&            \
      "$DrbdAdm0x0EAA"  down                 "$RESOURCE"
  }  || {                                          # 'down' still failed; undo:
    RESULT="$?"                                    # "disk_mediaAccess___UnMap()"
    disk_mediaAccess___WriteReverseMapEntry                             \
      "$ChildMediaPath" "$INDEX" "$ParentMediaPath"
    return  "$RESULT"                              # ... and return (on error!).
  }

  disk_mediaAccess__A8A2BB2D_78F0_11E6_B6F3_0000C00A45A9                \
    "$COMMAND"                                                          \
    "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"             \
    "$SUFFIX"  || return                           # return on error.

  disk_mediaAccess___UnLinkAndUnMap  "$ChildMediaName"
}


disk_mediaAccess__0x0891_DrbdAdm() {
  # executes "drbdadm" on the child-media of the parent-media, denoted by the
  # "parent-media-name" and the "index into container";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,
  # $@: parameters.

  # global:  DrbdAdm0x0EAA

  local      INDEX ParentMediaPath

  INDEX="$1"
  MediaInfo="$2"
  ParentMediaPath="$3"
  shift  3

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

  disk_mediaAccess__0x0891_DrbdCommand                              \
    "$DrbdAdm0x0EAA" "$INDEX" "$MediaInfo" "$ParentMediaPath" "$@"
}


disk_mediaAccess__0x0891_DrbdCommand() {
  # executes "command" on the child-media of the parent-media, denoted by the
  # "parent-media-name" and the "index into container";
  # $1: <COMMAND>,
  # $2: <INDEX>,
  # $3: <MediaInfo>,
  # $4: <ParentMediaPath>.
  # $@: parameters.

  local  ALTERNATE COMMAND INDEX MediaInfo ParentMediaPath RESOURCE RESULT

  COMMAND="$1"
  INDEX="$2"
  MediaInfo="$3"
  ParentMediaPath="$4"
  shift  4

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

  disk_mediaAccess__0x0891_isAlternateMedia     \
    "$INDEX" "$MediaInfo" "$ParentMediaPath"
    RESULT="$?"
    # echo  $RESULT                                               >>/dev/stderr
    [ "1" == "$RESULT" ]  && return  "$RESULT"     # return on error.

  ALTERNATE=''
  [ "0" == "$RESULT" ]  && ALTERNATE='A'

  RESOURCE="$(
    disk_mediaAccess__0x0891_RESOURCE           \
      "$INDEX" "$MediaInfo" "$ParentMediaPath"
  )"  || return                                    # return on error.

  disk_mediaAccess__0x0891_ConfigWrite          \
    "$ALTERNATE" "$MediaInfo" "$RESOURCE"

  "$COMMAND"  $@ "$RESOURCE"
}


disk_mediaAccess__0x0891_GetPeerIp() {
  # gets the ip# of a peer, identified by the <PeerIndex>.
  # $1: <MediaInfo>,
  # $2: <PeerIndex>.

  local  MediaInfo ParametersFile PeerIndex

  # parameters:
  local  PeerAddr

  MediaInfo="$1"
  PeerIndex="$2"

  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $PeerIndex                                              >>/dev/stderr

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

  # echo  ${PeerAddr[*]}                                          >>/dev/stderr

  disk_mediaAccess__0x0891_PeerAddr2Ip  "${PeerAddr["$PeerIndex"]}"
}


disk_mediaAccess__0x0891_isAlternateMedia() {
  # * returns
  #   * true (0), if the child-media of the parent-media, denoted by the
  #     "parent-media-name" and the "index into container" is the
  #     'alternate'-media;
  #   * "1" on error;
  #   * "2" if the child-media of the parent-media, denoted by the
  #     "parent-media-name" and the "index into container" is not the
  #     'alternate'-media;
  # * may only be called on a 'realized' media which its reverse-map-entries
  #   set correctly;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local  ChildMedia INDEX MediaInfo ParentMediaPath ReferenceIndexMediaPair
  local  TestIndexMediaPair

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

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

  ParentMedia="$(disk_mediaAccess__WriteQualifiedDevice  "$ParentMediaPath")"                                        >>/dev/stderr
  # echo  $ParentMedia                                            >>/dev/stderr

  ChildMedia="$(disk_mediaAccess___2ChildMedia0  "$MediaInfo")"
  # echo  $ChildMedia                                             >>/dev/stderr

  ReferenceIndexMediaPair="$(
    disk_mediaAccess__WriteIndexMediaPair  "$INDEX" "$ParentMedia"
  )"

  # 'normal drbd-device':
    TestIndexMediaPair="$(
      disk_mediaAccess___2ParentIndexMediaPair  "$ChildMedia"       2>/dev/null
    )"                                             # ignore errors silently.
    # echo  "r0 $ReferenceIndexMediaPair"                         >>/dev/stderr
    # echo  "t0 $TestIndexMediaPair"                              >>/dev/stderr

    [ "$ReferenceIndexMediaPair" == "$TestIndexMediaPair" ]  && return  2

  # 'altenate drbd-device':
    ChildMedia="${ChildMedia}.ALT"
    TestIndexMediaPair="$(
      disk_mediaAccess___2ParentIndexMediaPair  "$ChildMedia"     # 2>/dev/null
    )"                                             # ignore errors silently.
    # echo  "r1 $ReferenceIndexMediaPair"                         >>/dev/stderr
    # echo  "t1 $TestIndexMediaPair"                              >>/dev/stderr

    [ "$ReferenceIndexMediaPair" == "$TestIndexMediaPair" ]  && return  0

  return 1                                         # error
}


disk_mediaAccess__0x0891_isApiVersionGreaterOrEqual() {
  # returns true (0), if the <drbd-api-version> >= <VERSION>;
  # $1: <VERSION>.

  local  ApiVersion _VERSION

  _VERSION="$1"

  ApiVersion="$(disk_mediaAccess__0x0891_ApiVersion)"

  # echo  "$ApiVersion"                                           >>/dev/stderr

  [ "$ApiVersion" -ge "${_VERSION}" ]              # return result of this
}                                                  # command


disk_mediaAccess__0x0891_PeerAddr2Ip() {
  # ^
  # $1: <PeerAddr>.

  PeerAddr="$1"

  # echo  $PeerAddr                                               >>/dev/stderr

   echo  "$PeerAddr"                           \
     | string_SearchAndReplace     'ipv4:' ''  \
       | string__SearchAndReplace  ':.*$'  ''
}


disk_mediaAccess__0x0891_REALIZE() {
  # realize media, alternate media or realize media forced;
  # $1: <ALTERNATE>,
  # $2: <ChildMediaSuffix>,
  # $3: <COMMAND>,
  # $4: <INDEX>,
  # $5: <MediaInfo>,
  # $6: <ParentMedia>,
  # $7: <ParentMediaPath>.

  # global:  DrbdAdm0x0EAA

  local      ALTERNATE ChildMediaName ChildMediaSuffix COMMAND DrbdDevPath
  local      INDEX MediaInfo ParametersFile ParentMedia ParentMediaPath
  local      RESOURCE SUFFIX _LocalMinor

  # parameters:
    local    AltLocalMinor CongestionFill ConnectInt COPYRIGHT CopyrightDetails
    local    CsumsAlg DrbdTimeout LocalAddr LocalMetaDataIndex
    local    LocalMetaDataMedia LocalMinor LocalNodeId MetaDataVersion NOTES
    local    OnCongestion OnlyOnHosts PeerAddr PeerName PeerMetaDataIndex
    local    PeerMetaDataMedia PeerName PeerNodeId PROTOCOL RealizationOptions
    local    SIZE START TRANSPORT URL UUID VOLUME

  ALTERNATE="$1"
  ChildMediaSuffix="$2"
  COMMAND="$3"
  INDEX="$4"
  MediaInfo="$5"
  ParentMedia="$6" 
  ParentMediaPath="$7"

  # echo  $ALTERNATE                                              >>/dev/stderr
  # echo  $ChildMediaSuffix                                       >>/dev/stderr
  # echo  $COMMAND                                                >>/dev/stderr
  # echo  $INDEX                                                  >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr
  # echo  $ParentMedia                                            >>/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  $AltLocalMinor                                          >>/dev/stderr
  # echo  $CongestionFill                                         >>/dev/stderr
  # echo  $ConnectInt                                             >>/dev/stderr
  # echo  $COPYRIGHT                                              >>/dev/stderr
  # echo  $CopyrightDetails                                       >>/dev/stderr
  # echo  $CsumsAlg                                               >>/dev/stderr
  # echo  $DrbdTimeout                                            >>/dev/stderr
  # echo  $LocalAddr                                              >>/dev/stderr
  # echo  $LocalMetaDataIndex                                     >>/dev/stderr
  # echo  $LocalMetaDataMedia                                     >>/dev/stderr
  # echo  $LocalMinor                                             >>/dev/stderr
  # echo  $LocalNodeId                                            >>/dev/stderr
  # echo  $MetaDataVersion                                        >>/dev/stderr
  # echo  $NOTES                                                  >>/dev/stderr
  # echo  $OnCongestion                                           >>/dev/stderr
  # echo  $OnlyOnHosts                                            >>/dev/stderr
  # echo  ${PeerAddr[*]}                                          >>/dev/stderr
  # echo  ${PeerMetaDataIndex[*]}                                 >>/dev/stderr
  # echo  ${PeerMetaDataMedia[*]}                                 >>/dev/stderr
  # echo  ${PeerName[*]}                                          >>/dev/stderr
  # echo  ${PeerNodeId[*]}                                        >>/dev/stderr
  # echo  $PROTOCOL                                               >>/dev/stderr
  # echo  $RealizationOptions                                     >>/dev/stderr
  # echo  $SIZE                                                   >>/dev/stderr
  # echo  $START                                                  >>/dev/stderr
  # echo  $TRANSPORT                                              >>/dev/stderr
  # echo  $URL                                                    >>/dev/stderr
  # echo  $UUID                                                   >>/dev/stderr
  # echo  $VOLUME                                                 >>/dev/stderr

  # ^ ev. pen: realize | forced

  if [ 'A' = "$ALTERNATE" ]; then
      _LocalMinor="$AltLocalMinor"
    else
      _LocalMinor="$LocalMinor"
    fi
  # echo  $_LocalMinor                                            >>/dev/stderr

  RESOURCE="$(
    disk_mediaAccess___0x0891_RESOURCE  "$ALTERNATE" "$ParametersFile"
  )"
  SUFFIX="$(
    disk_mediaAccess__0x0891_SUFFIX                                     \
      "$ALTERNATE" "$LocalNodeId" "$ParametersFile"
  )"

  # echo  $RESOURCE                                               >>/dev/stderr
  # echo  $SUFFIX                                                 >>/dev/stderr

  # realize base media:
    disk_mediaAccess__A8A2BB2D_78F0_11E6_B6F3_0000C00A45A9              \
      "$COMMAND"                                                        \
      "$INDEX" "$MediaInfo" "$ParentMedia" "$ParentMediaPath"           \
      "$SUFFIX"  >/dev/null  || return             # return on error.

  DrbdDevPath="/dev/drbd${_LocalMinor}"

  ChildMediaName="${UUID}${ChildMediaSuffix}"
  # echo  $ChildMediaName                                         >>/dev/stderr

  disk_mediaAccess__0x0891_ConfigWrite                                  \
    "$ALTERNATE" "$MediaInfo" "$RESOURCE"

  if [ 'A' = "$ALTERNATE" ]; then
      "$DrbdAdm0x0EAA"  up "$RESOURCE"                              2>/dev/null
                                # no error messages; no return on errors.
    else
      "$DrbdAdm0x0EAA"  up "$RESOURCE"  || return  # return on error.
    fi

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


disk_mediaAccess__0x0891_RESOURCE() {
  # gets the drbd-resource-name from the realized media and writes it to
  # "stdout";
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,

  local  ChildMediaName INDEX MediaInfo ParentMediaPath

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

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

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

  echo  "${ChildMediaName}.RESOURCE"
}


disk_mediaAccess__0x0891_ResumeIo() {
  # resumes I/O on a replicated device;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMediaPath

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

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

  disk_mediaAccess__0x0891_DrbdAdm                        \
    "$INDEX" "$MediaInfo" "$ParentMediaPath" 'resume-io'
}


disk_mediaAccess__0x0891_ROLE() {
  # set role of drbd media or alternate drbd media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ROLE> in { "PRIMARY", "SECONDARY" }.

  local  INDEX ParentMediaPath ROLE

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

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

  case "$ROLE" in
      PRIMARY)    ROLE='primary'    ;;
      SECONDARY)  ROLE='secondary'  ;;
      *)          return 1
    esac

  disk_mediaAccess__0x0891_DrbdAdm                    \
    "$INDEX" "$MediaInfo" "$ParentMediaPath" "$ROLE"
}


disk_mediaAccess__0x0891_SUFFIX() {
  # writes the suffix for the drbd base media name to "stdout";
  # $1: <ALTERNATE>,
  # $2: <NodeId>,
  # $1: <ParametersFile>.

  # global:  ColRm0x0EAA

  local      ALTERNATE NodeId ParametersFile SUFFIX

  # parameters:
  local      VOLUME

  ALTERNATE="$1"
  NodeId="$2"
  ParametersFile="$3"

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

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

  # echo  $VOLUME                                                 >>/dev/stderr

  if [ 'A' = "$ALTERNATE" ]; then
      SUFFIX=".ALT.N${NodeId}.V${VOLUME}.BASE"
    else
      SUFFIX=".N${NodeId}.V${VOLUME}.BASE"
    fi

  echo  "$SUFFIX"
}


disk_mediaAccess__0x0891_SuspendIo() {
  # suspends I/O on a replicated device;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>.

  local  INDEX MediaInfo ParentMediaPath

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

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

  disk_mediaAccess__0x0891_DrbdAdm                         \
    "$INDEX" "$MediaInfo" "$ParentMediaPath" 'suspend-io'
}


disk_mediaAccess__0x0891_SyncBuffersAndSuspendIo() {
  # synchronizes any buffers to disk and suspends I/O on a replicated device;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMediaPath>,
  # $4: <WaitTime>.

  # global:  Sleep0x0EAA Sync0x0EAA

  local  INDEX MediaInfo ParentMediaPath WaitTime

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

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

  "$Sync0x0EAA"
  memory_FreeCache  All
  "$Sleep0x0EAA"  "$WaitTime"                      # "memory_FreeCache  All" is
                                                   # asynchronous, so wait long
                                                   # enough.
  disk_mediaAccess__0x0891_SuspendIo  "$INDEX" "$MediaInfo" "$ParentMediaPath"
}


disk_mediaAccess__0x0891_WaitForSync() {
  # wait until resync finished on all volumes for <TIME> seconds;
  # $1: <RESOURCE>,
  # $2: <TIME> to wait in seconds.

  local  ApiVersion I RESOURCE TIME

  RESOURCE="$1"
  TIME="$2"

  # echo  $RESOURCE                                               >>/dev/stderr
  # echo  $TIME                                                   >>/dev/stderr

  ApiVersion="$(disk_mediaAccess__0x0891_ApiVersion)"
  # echo  $ApiVersion                                             >>/dev/stderr

  for((I = 0; I < TIME; I++))
    do
        disk_mediaAccess___0x0891_WaitForSyncApiV${ApiVersion}  "$RESOURCE"
        sleep  1
      done
}


disk_mediaAccess__0x0891_WaitForSyncAndCopy() {
  # ^copy destroy media or alternate media;
  # $1: <INDEX>,
  # $2: <MediaInfo>,
  # $3: <ParentMedia>,
  # $4: <ParentMediaPath>,
  # $5: <TargetIndex>.

  local  ChildMedia GrandParentMedia GrandParentIndex INDEX ParametersFile
  local  ParentMedia ParentMediaPath PeerIp RemoteIndex
  local  RemoteIndexMediaPair RemoteMedia RESOURCE RESULT TargetIndex WaitTime0
  local  WaitTime1 WaitTime2

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

#  WaitTime0='30' # 10
#  WaitTime1='60' # 60
#  WaitTime2='30' # '30'
  WaitTime0='10'
  WaitTime1='15'
  WaitTime2='20'

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

  GrandParentIndex="$(
    disk_mediaAccess___2ParentIndex  "$ParentMedia"
  )"  || return                                    # return on error.

  GrandParentMedia="$(
    disk_mediaAccess___2ParentMedia  "$ParentMedia"
  )"  || return                                    # return on error.
  # echo  $GrandParentIndex                                       >>/dev/stderr
  # echo  $GrandParentMedia                                       >>/dev/stderr
  GrandParentMediaPath="$(
    disk_mediaAccess___Media2AbsolutePath  "$GrandParentMedia"
  )"  || return                                    # return on error.
  # echo  $GrandParentMediaPath                                   >>/dev/stderr

  # the grandparent media must be a media in a container:
    disk_mediaAccess__isContainer                                             \
      '0' "$GrandParentMedia" "$GrandParentMediaPath"  || return 0

  # the grandparent media must be a thin provisioned media:
    disk_mediaAccess___isThinProvisionedMedia                                 \
      "$GrandParentIndex" "$GrandParentMedia" "$GrandParentMediaPath"         \
      || return 0

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

  # echo  $UUID                                                   >>/dev/stderr

  ChildMedia="$(disk_mediaAccess__WriteQualifiedUuid  "$UUID")"
  RESOURCE="$(
    disk_mediaAccess__0x0891_RESOURCE  "$INDEX" "$MediaInfo" "$ParentMediaPath"
  )"  || {
      RESULT="$?"
      echo "  Device / Media: $ChildMedia"                        >>/dev/stderr
      return  "$RESULT"                            # return on error.
  }
  # echo  $RESOURCE                                               >>/dev/stderr

  echo  -e                                                                   \
    "\nwaiting for drbd synchronization for at least $WaitTime0 seconds."    \
                                                                  >>/dev/stderr
#  disk_mediaAccess__0x0891_WaitForSync  "$RESOURCE" "$WaitTime0"

  echo 'suspend i/o on remote.'                                   >>/dev/stderr
    PeerIp="$(disk_mediaAccess__0x0891_GetPeerIp  "$MediaInfo" '0')"         \
      || return                                  # return on error.
   # echo  $PeerIp                                                >>/dev/stderr
#^ works till here (06mar2019 tbrue)
return

  RemoteIndexMediaPair="$(
    ssh  "$PeerIp"                                                           \
      "/${SCRIPTS}/QuietMediaAccess_ __2ParentIndexMediaPair  $ChildMedia"
  )"  || return                                    # return on error.
  RemoteIndex="$(
    disk_mediaAccess___IndexMediaPair2Index  "$RemoteIndexMediaPair"
  )"
  RemoteMedia="$(
    disk_mediaAccess___IndexMediaPair2Media  "$RemoteIndexMediaPair"
  )"
  # echo  $RemoteIndexMediaPair                                   >>/dev/stderr
  # echo  $RemoteIndex                                            >>/dev/stderr
  # echo  $RemoteMedia                                            >>/dev/stderr

  echo                                                                       \
    "waiting for buffer synchronization on remote for $WaitTime1 seconds."   \
                                                                  >>/dev/stderr
    ssh  "$PeerIp"                                                           \
      "/${SCRIPTS}/QuietMediaAccess_" __MediaHandlerCommand                  \
        SyncBuffersAndSuspendIo  "$RemoteIndex" "$RemoteMedia" "$WaitTime1"  \
          || return                                # return on error.

  echo  "waiting for drbd synchronization for at least $WaitTime2 seconds."  \
                                                                  >>/dev/stderr
  disk_mediaAccess__0x0891_WaitForSync  "$RESOURCE" "$WaitTime2"             \
    || return                                     # return on error.

  echo  "waiting for local buffer synchronization for $WaitTime1 seconds."   \
                                                                  >>/dev/stderr
  disk_mediaAccess__0x0891_SyncBuffersAndSuspendIo                           \
    "$ParentMedia" "$INDEX" "$WaitTime1"                                     \
      || return                                   # return on error.

  echo  'copy media.'                                             >>/dev/stderr
    # echo  $GrandParentMedia                                     >>/dev/stderr
    # echo  $GrandParentIndex                                     >>/dev/stderr
    # echo  $TargetIndex                                          >>/dev/stderr
    # read

    # remove target media:
      "/${SCRIPTS}/QuietMediaAccess_"  __MediaHandlerCommand RM              \
        "$TargetIndex"      "$GrandParentMedia"                     2>/dev/null
                                                   # ignore errors silently.
    # copy it:
      "/${SCRIPTS}/QuietMediaAccess_"  __MediaHandlerCommand CP              \
        "$GrandParentIndex" "$GrandParentMedia" "$TargetIndex"

  disk_mediaAccess__0x0891_ResumeIo  "$ParentMedia" "$INDEX"                 \
    || return                                     # return on error.

  echo 'resume i/o on remote.'                                    >>/dev/stderr
    ssh  "$PeerIp"                                                           \
      "/${SCRIPTS}/QuietMediaAccess_" __MediaHandlerCommand                  \
        ResumeIo  "$RemoteIndex" "$RemoteMedia"
}


disk_mediaAccess___0x0891_ConfigWrite() {
  # writes the configuration file, corresponding to the parameters, to "stdout";
  # $1: <ALTERNATE>,
  # $2: <MediaInfo>.

  local  ALTERNATE MediaInfo ParametersFile PREFIX

  ALTERNATE="$1"
  MediaInfo="$2"
  PREFIX='  '

  # echo  $ALTERNATE                                              >>/dev/stderr
  # echo  "$MediaInfo"                                            >>/dev/stderr

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

  disk_mediaAccess__0x0891_ConfigWriteHeader                            \
      "$ParametersFile"     "$ALTERNATE"
  disk_mediaAccess__0x0891_ConfigMaybeWriteHandlerSection               \
      "$ParametersFile"                  "$PREFIX"

  echo  ''
    disk_mediaAccess__0x0891_ConfigWriteNetSection                      \
      "$ParametersFile"                  "$PREFIX"

  echo  ''
    disk_mediaAccess__0x0891_ConfigWriteOnSection                       \
      "$ParametersFile" '0' "$ALTERNATE" "$PREFIX"

  echo  ''
    disk_mediaAccess__0x0891_ConfigWriteLocalOnSection                  \
      "$ParametersFile"     "$ALTERNATE" "$PREFIX"

  disk_mediaAccess__0x0891_ConfigWriteSectionEnd                        \
                                         ''
}


disk_mediaAccess___0x0891_RESOURCE() {
  # gets the drbd-resource-name from the parameters-file and writes it to
  # "stdout";
  # $1: <ALTERNATE>,
  # $2: path to parameters-file.

  local  ALTERNATE ParametersFile RESOURCE

  # parameters:
  local  UUID

  ALTERNATE="$1"
  ParametersFile="$2"

  # echo  $ALTERNATE                                              >>/dev/stderr
  # echo  $ParametersFile                                         >>/dev/stderr

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

  # echo  $UUID                                                   >>/dev/stderr

  if [ 'A' = "$ALTERNATE" ]; then
      RESOURCE="${UUID}.ALT.RESOURCE"
    else
      RESOURCE="${UUID}.RESOURCE"
    fi

  echo  "$RESOURCE"
}


disk_mediaAccess___0x0891_WaitForSyncApiV1() {
  # wait until resync finished on all volumes;
  # $1: <RESOURCE>.

  # global:  DrbdAdm0x0EAA DrbdSetup0x0EAA

  local      MINOR RESOURCE

  RESOURCE="$1"
  # echo  $RESOURCE                                               >>/dev/stderr

  MINOR="$("$DrbdAdm0x0EAA"  sh-minor   "$RESOURCE")"
  # echo  $MINOR                                                  >>/dev/stderr

  "$DrbdSetup0x0EAA"         wait-sync  "$MINOR"
}


disk_mediaAccess___0x0891_WaitForSyncApiV2() {
  # wait until resync finished on all volumes;
  # $1: <RESOURCE>.

  # global:  DrbdSetup0x0EAA

  local      RESOURCE

  RESOURCE="$1"
  # echo  $RESOURCE                                               >>/dev/stderr

  "$DrbdSetup0x0EAA"  wait-sync-resource  "$RESOURCE"
}