libError
========

Functions to support error passing

Overview
--------

Error passing is a technique where lower layer functions set values in
an error passing structure, and higher layer functions up along the call
tree add more context and detail to form strong diagnostics.

``epSet()`` is meant to be called at the lowest level of a call tree.
Generally the leaf most function does the ``epSet()``. Each parent
function up along the call chain tests for a returned fail condition,
testing either the child function return code or checking the **error
passing structure (EPS)** itself using ``epHasError()``. The parent then
contributes to the error passing structure by appending, prepending, and
setting additional fields to provide improved context and diagnostics to
its caller. At the level in the program where the error can be analyzed
for severity, corrective action is taken and the EPS is usually printed
or logged.

See `Error Passing Example <../shdoc/example-error-pass.bash>`__ which
is runnable. Output from a run:

|image1|

Contains the following:

**Lifecycle**

- epSet()

**Modifiers**

- epPrepend()
- epAppend()
- epSetErrorName()
- epSetErrorType()
- epSetDescription()
- epSetSeverity()
- epSetProbableCause()
- epSetProposedRepair()
- epSetFileName()
- epSetFuncName()
- epSetLineNum()
- epSetCodeNum()

**Observers**

- epErrorName()
- epErrorType()
- epSeverity()
- epFileName()
- epFuncName()
- epLineNum()
- epCodeNum()
- epFullDesc()
- epDescription()
- epProbableCause()
- epProposedRepair()
- epTimestamp()
- epHasError()

--------------

Index
-----

- `ksl::epSet <#kslepset>`__
- `ksl::epSetDescription <#kslepsetdescription>`__
- `ksl::epDescription <#kslepdescription>`__
- `ksl::epAppend <#kslepappend>`__
- `ksl::epPrepend <#kslepprepend>`__
- `ksl::epSetErrorName <#kslepseterrorname>`__
- `ksl::epErrorName <#ksleperrorname>`__
- `ksl::epSetErrorType <#kslepseterrortype>`__
- `ksl::epErrorType <#ksleperrortype>`__
- `ksl::epSetSeverity <#kslepsetseverity>`__
- `ksl::epSeverity <#kslepseverity>`__
- `ksl::epSetFuncName <#kslepsetfuncname>`__
- `ksl::epFuncName <#kslepfuncname>`__
- `ksl::epSetFileName <#kslepsetfilename>`__
- `ksl::epFileName <#kslepfilename>`__
- `ksl::epSetLineNum <#kslepsetlinenum>`__
- `ksl::epLineNum <#ksleplinenum>`__
- `ksl::epSetCodeNum <#kslepsetcodenum>`__
- `ksl::epCodeNum <#kslepcodenum>`__
- `ksl::epSetCause <#kslepsetcause>`__
- `ksl::epCause <#kslepcause>`__
- `ksl::epSetRepair <#kslepsetrepair>`__
- `ksl::epRepair <#ksleprepair>`__
- `ksl::epTimestamp <#ksleptimestamp>`__
- `ksl::epHasError <#kslephaserror>`__
- `ksl::epPrint <#kslepprint>`__

ksl::epSet
~~~~~~~~~~

Set values in an error passing structure.

epSet [options…]

OPTIONS

- -ca, –cause
- -cn, –codeNum
- -d, –description
- -en, –errorName
- -et, –errorType
- -fi, –fileName
- -fn, –funcName
- -li, –lineNum
- -rp, –repair
- -sv, –severity

With no args, epSet works on the default ``ep1`` error passing structure
(EPS). You can pass in ``ep1`` explicitly or supply your own EPS. If the
given EPS does not already exist in the environment, then it is created.

These two are equivalent: ``epSet;`` and ``epSet ep1;`` Or supply your
own: ``epSet myEp;``

Each call to ``epSet()`` initalizes all fields to empty/default values
with the timestamp set to current time, followed by setting any supplied
options. Most options are strings so they will need to be in double
quotes if they have embedded spaces.

Example
^^^^^^^

.. code:: bash

   echo ksl::epSet                # ep1 is initalized
   echo ksl::epSet ep2            # ep2 is initalized
   echo ksl::epSet --fi /home/abc # ep1 is initalized and file name is set

Arguments
^^^^^^^^^

- **$1** (array): is the Error Passing Structure (EPS). If not specified
  then EPS is ``ep1``

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image2|

ksl::epSetDescription
~~~~~~~~~~~~~~~~~~~~~

Sets the description field in the given EPS.

Overwrites any previous description. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the description. If one
arg is given, then $1 is the description and EPS ``ep1`` is used.

.. _example-1:

Example
^^^^^^^

.. code:: bash

   ksl::epSetDescription "Broken channel"      # ep1 is used
   ksl::epSetDescription ep2 "Broken channel"  # ep2 is used
   ksl::epSetDescription ""                    # sets ep1 description to empty
   ksl::epSetDescription                       # error

.. _arguments-1:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the description depending on
  number of args as described above.
- **$2** (string): is the description if two args are given.

Exit codes
^^^^^^^^^^

- **0**: Success - description was set.
- **1**: Failed - bad EPS or missing args.

Output on stderr
^^^^^^^^^^^^^^^^

- epSetDescription() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image3|

ksl::epDescription
~~~~~~~~~~~~~~~~~~

Retrieve the description.

.. _example-2:

Example
^^^^^^^

.. code:: bash

   echo $(ksl::epDescription)       # ep1 is used
   echo $(ksl::epDescription ep2)   # ep2 is used

.. _arguments-2:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-1:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

Output on stdout
^^^^^^^^^^^^^^^^

- the description

.. _output-on-stderr-1:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image4|

ksl::epAppend
~~~~~~~~~~~~~

Appends given string to the description in the given EPS.

EPS must already exist.

If two args are given, then $1 is EPS and $2 is the string to append. If
one arg is given, then $1 is the string to append and EPS ``ep1`` is
used.

.. _example-3:

Example
^^^^^^^

.. code:: bash

   ksl::epAppend "Broken channel"        # ep1 is used
   ksl::epAppend ep2 "Broken channel"    # ep2 is used
   ksl::epAppend ""                      # append empty string to ep1
   ksl::epAppend                         # error

.. _arguments-3:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the string to append depending on
  number of args as described above.
- **$2** (string): is the string to append if two args are given.

.. _exit-codes-2:

Exit codes
^^^^^^^^^^

- **0**: Success - string was appended.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-2:

Output on stderr
^^^^^^^^^^^^^^^^

- epAppend() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image5|

ksl::epPrepend
~~~~~~~~~~~~~~

Prepends given string to the description in the given EPS.

EPS must already exist.

If two args are given, then $1 is EPS and $2 is the string to prepend.
If one arg is given, then $1 is the string to prepend and EPS ``ep1`` is
used.

.. _example-4:

Example
^^^^^^^

.. code:: bash

   ksl::epPrepend "Broken channel"        # ep1 is used
   ksl::epPrepend ep2 "Broken channel"    # ep2 is used
   ksl::epPrepend ""                      # prepend empty string to ep1
   ksl::epPrepend                         # error

.. _arguments-4:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the string to prepend depending
  on number of args as described above.
- **$2** (string): is the string to prepend if two args are given.

.. _exit-codes-3:

Exit codes
^^^^^^^^^^

- **0**: Success - string was prepended.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-3:

Output on stderr
^^^^^^^^^^^^^^^^

- epPrepend() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image6|

ksl::epSetErrorName
~~~~~~~~~~~~~~~~~~~

Sets the error name in the given EPS.

Overwrites any previous error name. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the error name. If one
arg is given, then $1 is the error name and EPS ``ep1`` is used.

**Choices for ErrorName**

- CaughtException
- ConfigurationError
- DataFormatError
- AlreadyExistsError
- IllegalStateError
- InputOutputError
- InvalidAccessError
- InvalidArgumentError
- LengthError
- LogicError
- NetworkError
- NoPermissionError
- NotFoundError
- NotImplementedError
- NullPointerError
- NullValueError
- OperationNotPossibleError
- OverflowError
- RangeError
- SignalError
- SystemCallError
- TimeoutError
- UnderflowError

.. _arguments-5:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the error name depending on
  number of args as described above.
- **$2** (string): is the error name if two args are given.

.. _exit-codes-4:

Exit codes
^^^^^^^^^^

- **0**: Success - error name was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-4:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetErrorName() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image7|

ksl::epErrorName
~~~~~~~~~~~~~~~~

Returns the error name in the given EPS.

.. _example-5:

Example
^^^^^^^

.. code:: bash

   ksl::epErrorName               # ep1 is used
   echo $(ksl::epErrorName ep2)   # ep2 is used
   str=$(ksl::epErrorName ep2)    # ep2 is used

.. _arguments-6:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-5:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-1:

Output on stdout
^^^^^^^^^^^^^^^^

- the error name

.. _output-on-stderr-5:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

See also
^^^^^^^^

- `Choices for ErrorName <#ksl-epseterrorname>`__

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image8|

ksl::epSetErrorType
~~~~~~~~~~~~~~~~~~~

Sets the error type in the given EPS.

Overwrites any previous error type. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the error type. If one
arg is given, then $1 is the error type and EPS ``ep1`` is used.

**Choices for ErrorType**

- CommunicationsError
- ConfigurationError
- EnvironmentalError
- EquipmentError
- ProcessingError
- QualityOfServiceError

.. _example-6:

Example
^^^^^^^

.. code:: bash

   ksl::epSetErrorType "ProcessingError"      # ep1 is used
   ksl::epSetErrorType ep2 "ProcessingError"  # ep2 is used
   ksl::epSetErrorType  ""                    # sets ep1 error type to empty
   ksl::epSetErrorType                        # error

.. _arguments-7:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the error type depending on
  number of args as described above.
- **$2** (string): is the error type if two args are given.

.. _exit-codes-6:

Exit codes
^^^^^^^^^^

- **0**: Success - description was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-6:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetErrorType() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image9|

ksl::epErrorType
~~~~~~~~~~~~~~~~

Returns the error type in the given EPS.

.. _example-7:

Example
^^^^^^^

.. code:: bash

   ksl::epErrorType               # ep1 is used
   echo $(ksl::epErrorType ep2)   # ep2 is used
   str=$(ksl::epErrorType ep2)    # ep2 is used

.. _arguments-8:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-7:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-2:

Output on stdout
^^^^^^^^^^^^^^^^

- the error type

.. _output-on-stderr-7:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

.. _see-also-1:

See also
^^^^^^^^

- `Choices for ErrorType <#ksl-epseterrortype>`__

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image10|

ksl::epSetSeverity
~~~~~~~~~~~~~~~~~~

Sets the error severity in the given EPS.

Overwrites any previous severity. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the severity. If one arg
is given, then $1 is the severity and EPS ``ep1`` is used.

**Choices for Severity**

- Indeterminate
- Critical
- Major
- Minor
- Warning

.. _example-8:

Example
^^^^^^^

.. code:: bash

   ksl::epSetSeverity "Critical"        # ep1 is used
   ksl::epSetSeverity ep2 "Critical"    # ep2 is used
   ksl::epSetSeverity  ""               # sets ep1 severity to empty
   ksl::epSetSeverity                   # error

.. _arguments-9:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the severity depending on number
  of args as described above.
- **$2** (string): is the severity if two args are given.

.. _exit-codes-8:

Exit codes
^^^^^^^^^^

- **0**: Success - severity was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-8:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetSeverity() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image11|

ksl::epSeverity
~~~~~~~~~~~~~~~

Returns the severity in the given EPS.

.. _example-9:

Example
^^^^^^^

.. code:: bash

   ksl::epSeverity              # ep1 is used
   echo $(ksl::epSeverity ep2)  # ep2 is used
   str=$(ksl::epSeverity ep2)   # ep2 is used

.. _arguments-10:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-9:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-3:

Output on stdout
^^^^^^^^^^^^^^^^

- the severity

.. _output-on-stderr-9:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

.. _see-also-2:

See also
^^^^^^^^

- `Choices for Severity <#ksl-epsetseverity>`__

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image12|

ksl::epSetFuncName
~~~~~~~~~~~~~~~~~~

Sets the function name in the given EPS.

Overwrites any previous function name. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the function name. If
one arg is given, then $1 is the function name and EPS ``ep1`` is used.

.. _example-10:

Example
^^^^^^^

.. code:: bash

   ksl::epSetFuncName "crcCheck()"      # ep1 is used
   ksl::epSetFuncName ep2 "crcCheck()"  # ep2 is used
   ksl::epSetFuncName  ""               # sets ep1 function name to empty
   ksl::epSetFuncName                   # error

.. _arguments-11:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the function name depending on
  number of args as described above.
- **$2** (string): is the function name if two args are given.

.. _exit-codes-10:

Exit codes
^^^^^^^^^^

- **0**: Success - function name was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-10:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetFuncName() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image13|

ksl::epFuncName
~~~~~~~~~~~~~~~

Returns the function name in the given EPS.

.. _example-11:

Example
^^^^^^^

.. code:: bash

   ksl::epFuncName               # ep1 is used
   echo $(ksl::epFuncName ep2)   # ep2 is used
   str=$(ksl::epFuncName ep2)    # ep2 is used

.. _arguments-12:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-11:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-4:

Output on stdout
^^^^^^^^^^^^^^^^

- the function name

.. _output-on-stderr-11:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image14|

ksl::epSetFileName
~~~~~~~~~~~~~~~~~~

Sets the file name in the given EPS.

Overwrites any previous file name. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the file name. If one
arg is given, then $1 is the file name and EPS ``ep1`` is used.

.. _example-12:

Example
^^^^^^^

.. code:: bash

   ksl::epSetFileName "config.yml"     # ep1 is used
   ksl::epSetFileName ep2 "config.yml" # ep2 is used
   ksl::epSetFileName  ""              # sets ep1 file name to empty
   ksl::epSetFileName                  # error

.. _arguments-13:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the file name on number of args
  as described above.
- **$2** (string): is the file name if two args are given.

.. _exit-codes-12:

Exit codes
^^^^^^^^^^

- **0**: Success - file name was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-12:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetFileName() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image15|

ksl::epFileName
~~~~~~~~~~~~~~~

Returns the file name in the given EPS.

.. _example-13:

Example
^^^^^^^

.. code:: bash

   ksl::epFileName               # ep1 is used
   echo $(ksl::epFileName ep2)   # ep2 is used
   str=$(ksl::epFileName ep2)    # ep2 is used

.. _arguments-14:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-13:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-5:

Output on stdout
^^^^^^^^^^^^^^^^

- the file name

.. _output-on-stderr-13:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image16|

ksl::epSetLineNum
~~~~~~~~~~~~~~~~~

Sets the line number in the given EPS.

Overwrites any previous line number. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the line number. If one
arg is given, then $1 is the line number and EPS ``ep1`` is used.

.. _example-14:

Example
^^^^^^^

.. code:: bash

   ksl::epSetLineNum "55"        # ep1 is used
   ksl::epSetLineNum ep2 "55"    # ep2 is used
   ksl::epSetLineNum  ""         # sets ep1 line number to empty
   ksl::epSetLineNum             # error

.. _arguments-15:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the line number depending on
  number of args as described above.
- **$2** (string): is the line number if two args are given.

.. _exit-codes-14:

Exit codes
^^^^^^^^^^

- **0**: Success - line number was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-14:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetLineNum() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image17|

ksl::epLineNum
~~~~~~~~~~~~~~

Returns the line number in the given EPS.

.. _example-15:

Example
^^^^^^^

.. code:: bash

   ksl::epLineNum               # ep1 is used
   echo $(ksl::epLineNum ep2)   # ep2 is used
   str=$(ksl::epLineNum ep2)    # ep2 is used

.. _arguments-16:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-15:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-6:

Output on stdout
^^^^^^^^^^^^^^^^

- the line number

.. _output-on-stderr-15:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image18|

ksl::epSetCodeNum
~~~~~~~~~~~~~~~~~

Sets a code number in the given EPS.

Overwrites any previous code number. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the code number. If one
arg is given, then $1 is the code number and EPS ``ep1`` is used.

.. _example-16:

Example
^^^^^^^

.. code:: bash

   ksl::epSetCodeNum "999"        # ep1 is used
   ksl::epSetCodeNum ep2 "999"    # ep2 is used
   ksl::epSetCodeNum  ""          # sets ep1 code number to empty
   ksl::epSetCodeNum              # error

.. _arguments-17:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the code number depending on
  number of args as described above.
- **$2** (string): is the code number if two args are given.

.. _exit-codes-16:

Exit codes
^^^^^^^^^^

- **0**: Success - code number was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-16:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetCodeNum() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image19|

ksl::epCodeNum
~~~~~~~~~~~~~~

Returns the code number in the given EPS.

.. _example-17:

Example
^^^^^^^

.. code:: bash

   ksl::epCodeNum               # ep1 is used
   echo $(ksl::epCodeNum ep2)   # ep2 is used
   str=$(ksl::epCodeNum ep2)    # ep2 is used

.. _arguments-18:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-17:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-7:

Output on stdout
^^^^^^^^^^^^^^^^

- the code number

.. _output-on-stderr-17:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image20|

ksl::epSetCause
~~~~~~~~~~~~~~~

Sets a probable cause string in the given EPS.

Overwrites any previous cause. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the cause. If one arg is
given, then $1 is the cause and EPS ``ep1`` is used.

.. _example-18:

Example
^^^^^^^

.. code:: bash

   ksl::epSetCause "no power"      # ep1 is used
   ksl::epSetCause ep2 "no power"  # ep2 is used
   ksl::epSetCause  ""             # sets ep1 cause to empty
   ksl::epSetCause                 # error

.. _arguments-19:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the cause depending on number of
  args as described above.
- **$2** (string): is the cause if two args are given.

.. _exit-codes-18:

Exit codes
^^^^^^^^^^

- **0**: Success - cause was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-18:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetCause() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image21|

ksl::epCause
~~~~~~~~~~~~

Returns the probable cause in the given EPS.

.. _example-19:

Example
^^^^^^^

.. code:: bash

   ksl::epCause               # ep1 is used
   echo $(ksl::epCause ep2)   # ep2 is used
   str=$(ksl::epCause ep2)    # ep2 is used

.. _arguments-20:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-19:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-8:

Output on stdout
^^^^^^^^^^^^^^^^

- the cause

.. _output-on-stderr-19:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image22|

ksl::epSetRepair
~~~~~~~~~~~~~~~~

Sets a probable repair string in the given EPS.

Overwrites any previous repair. EPS must already exist.

If two args are given, then $1 is EPS and $2 is the repair. If one arg
is given, then $1 is the repair and EPS ``ep1`` is used.

.. _example-20:

Example
^^^^^^^

.. code:: bash

   ksl::epSetRepair "plug it in"      # ep1 is used
   ksl::epSetRepair ep2 "plug it in"  # ep2 is used
   ksl::epSetRepair  ""               # sets ep1 repair to empty
   ksl::epSetRepair                   # error

.. _arguments-21:

Arguments
^^^^^^^^^

- **$1** (array): is either the EPS or the repair depending on number of
  args as described above.
- **$2** (string): is the repair if two args are given.

.. _exit-codes-20:

Exit codes
^^^^^^^^^^

- **0**: Success - repair was set.
- **1**: Failed - bad EPS or missing args.

.. _output-on-stderr-20:

Output on stderr
^^^^^^^^^^^^^^^^

- epSetRepair() missing args
- arraySetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image23|

ksl::epRepair
~~~~~~~~~~~~~

Returns the probable repair in the given EPS.

.. _example-21:

Example
^^^^^^^

.. code:: bash

   ksl::epRepair                    # ep1 is used
   echo $(ksl::epRepair ep2)        # ep2 is used
   str=$(ksl::epRepair ep2)         # ep2 is used

.. _arguments-22:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-21:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-9:

Output on stdout
^^^^^^^^^^^^^^^^

- the repair

.. _output-on-stderr-21:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image24|

ksl::epTimestamp
~~~~~~~~~~~~~~~~

Returns the timestamp in the given EPS.

The value for timestamp was established on the most recent call to
epSet().

.. _example-22:

Example
^^^^^^^

.. code:: bash

   ksl::epTimestamp               # ep1 is used
   echo $(ksl::epTimestamp ep2)   # ep2 is used
   str=$(ksl::epTimestamp ep2)    # ep2 is used

.. _arguments-23:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-22:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-10:

Output on stdout
^^^^^^^^^^^^^^^^

- the timestamp

.. _output-on-stderr-22:

Output on stderr
^^^^^^^^^^^^^^^^

- arrayGetValue() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image25|

ksl::epHasError
~~~~~~~~~~~~~~~

Returns true if EPS is carrying an error.

The EPS is considered to be carrying an error if either the description
field or the code number field is non-empty.

.. _example-23:

Example
^^^^^^^

.. code:: bash

   if ksl::epHasError; then epPrint; fi   # ep1 is used
   [[ ksl::epHasError ep2 ]] && return 1  # ep2 is used

.. _arguments-24:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-23:

Exit codes
^^^^^^^^^^

- **0**: true - EPS is carrying an error.
- **1**: false - EPS is not carrying an error.

.. _output-on-stderr-23:

Output on stderr
^^^^^^^^^^^^^^^^

- epHasError() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image26|

ksl::epPrint
~~~~~~~~~~~~

Prints the given EPS in a formatted style to stdout.

$1 is the EPS and optional. If not supplied the default EPS of “ep1” is
used.

.. _example-24:

Example
^^^^^^^

.. code:: bash

   ksl::epPrint         # ep1 is used
   ksl::epPrint ep2     # ep2 is used

.. _arguments-25:

Arguments
^^^^^^^^^

- **$1** (array): is the EPS. If no args, then EPS ``ep1`` is used.

.. _exit-codes-24:

Exit codes
^^^^^^^^^^

- **0**: Success
- **1**: Failed - likely a bad EPS.

.. _output-on-stdout-11:

Output on stdout
^^^^^^^^^^^^^^^^

- See output from example script at top of this file.

.. _output-on-stderr-24:

Output on stderr
^^^^^^^^^^^^^^^^

- epPrint() no such array

  .. raw:: html

     <p>

  .. raw:: html

     <p>

  |image27|

.. |image1| image:: ../images/pub/errpass-example-output.png
.. |image2| image:: ../images/pub/divider-line.png
.. |image3| image:: ../images/pub/divider-line.png
.. |image4| image:: ../images/pub/divider-line.png
.. |image5| image:: ../images/pub/divider-line.png
.. |image6| image:: ../images/pub/divider-line.png
.. |image7| image:: ../images/pub/divider-line.png
.. |image8| image:: ../images/pub/divider-line.png
.. |image9| image:: ../images/pub/divider-line.png
.. |image10| image:: ../images/pub/divider-line.png
.. |image11| image:: ../images/pub/divider-line.png
.. |image12| image:: ../images/pub/divider-line.png
.. |image13| image:: ../images/pub/divider-line.png
.. |image14| image:: ../images/pub/divider-line.png
.. |image15| image:: ../images/pub/divider-line.png
.. |image16| image:: ../images/pub/divider-line.png
.. |image17| image:: ../images/pub/divider-line.png
.. |image18| image:: ../images/pub/divider-line.png
.. |image19| image:: ../images/pub/divider-line.png
.. |image20| image:: ../images/pub/divider-line.png
.. |image21| image:: ../images/pub/divider-line.png
.. |image22| image:: ../images/pub/divider-line.png
.. |image23| image:: ../images/pub/divider-line.png
.. |image24| image:: ../images/pub/divider-line.png
.. |image25| image:: ../images/pub/divider-line.png
.. |image26| image:: ../images/pub/divider-line.png
.. |image27| image:: ../images/pub/divider-line.png