ZEBRA PRINTER MONITOR - TEST / PROD
=================================

Purpose
-------
Monitor all Zebra/ZDesigner printer queues on print server jkb-print.
The expected printer configuration is PRINT WIDTH = 832 dots.
This script does NOT change printer configuration. It only reads ^HH.

Start
-----
1. Copy this ENTIRE folder to a Windows PC. Windows PowerShell 5.1 and the
   PrintManagement module must be available. Use credentials that can read
   printer queues/ports on jkb-print, and network access to TCP/9100.
2. Run START_TEST.bat repeatedly. This never queries the print server
   or a printer; all printers and IPs are generated locally in VBScript.
3. Inspect data\test\ZebraMonitor_test.xlsx.
4. Run START_PROD.bat. Live data is written to
   data\prod\ZebraMonitor_prod.xlsx (separate from test history).

Workbook sheets
---------------
Uebersicht : last scan timestamp in B2, counts, explanations
Events     : ONE row per new or changed error state, not every failed hour
Status     : last state for every current queue, with last check and since
Runs       : ONE row per completed scan, even if no new incidents
Haeufigkeit: per-printer counts (wrong width AFTER known OK, initially/
            otherwise wrong, width changed while wrong, offline events)

Persisted source files: data\[test|prod]\events.tsv, state.tsv, runs.tsv.
They are UTF-16 tab-separated files, compatible with Excel Import-Csv.
The XLSX is regenerated from these files on every scan; do not edit it
as the authoritative data source, and keep it closed during scheduled runs.
No local Microsoft Excel installation or third-party PS module is needed.

State transition logic
----------------------
OK -> WRONG_WIDTH 600:  new event
WRONG_WIDTH 600 -> WRONG_WIDTH 600:  no duplicate
WRONG_WIDTH 600 -> OK:  recovery recorded in Status, NOT in Events
OK -> WRONG_WIDTH 600 (again):  NEW event
WRONG_WIDTH 600 -> WRONG_WIDTH 720:  NEW event (changed width)
OK -> OFFLINE:  new event
OFFLINE -> OFFLINE:  no duplicate
OFFLINE -> OK -> OFFLINE:  second event

Other monitored states: NO_RESPONSE means TCP connected but ^HH could
not be parsed; NO_IP means no TCP/IP host address found for that queue.
These are diagnostic events, not automatically considered OFFLINE.
When print-server enumeration fails, the scan stops and leaves state
and history unchanged. This does not attempt to recognize removed queues.

TEST mode cycles through 6 states and then repeats:
  1: B wrong width / C offline -> 2 events
  2: unchanged -> 0 events
  3: A wrong width; B/C recovered -> 1 event
  4: A unchanged, B wrong width, C offline -> 2 events
  5: A recovered, B/C unchanged -> 0 events
  6: A wrong width again; B/C recovered -> 1 event
For a clean test, delete the entire data\test folder.
Never delete data\prod unless you intend to erase monitoring history.

Hourly Windows Task Scheduler
-----------------------------
Program: cscript.exe
Arguments: //nologo "C:\Path\ZebraMonitor\ZebraMonitor.vbs" PROD
Start in: C:\Path\ZebraMonitor
Schedule: hourly. Set 'If the task is already running: Do not start
 a new instance'. Use a service/user account with access to the
print server and printers; run in a folder with write permissions.
Both BAT launchers include PAUSE for manual runs and are not suitable
for scheduled tasks.

Operational notes
-----------------
* Printer IP addresses are taken from Get-PrinterPort on jkb-print.
* Only printer queues whose DriverName matches Zebra or ZDesigner
  are scanned, and only ports with a PrinterHostAddress are probed.
* A different number of dots is not automatically wrong for every
  Zebra model. This monitor intentionally uses the requested 832.
* Port 9100 and the ^HH response must be reachable; no ping is used.
* If the workbook is open and cannot be replaced, history remains in
  the TSV files and the workbook is rebuilt on the next successful run.
* The small monitor.lock file prevents overlapping launches. If the
  script crashes, inspect whether a run is active before deleting it.
* Only a transition from measured OK (832) to WRONG_WIDTH is a confirmed
  observed new width loss; an initial WRONG_WIDTH is tracked separately.
* Number of incidents is based on HOURLY OBSERVED CHANGES, not on
  every unnoticed failure/recovery in between checks.
* Individual records are keyed by queue name; if renamed, the new
  queue is treated as a newly discovered printer.

Included example workbook
-------------------------
BEISPIEL_ZebraMonitor.xlsx is a STATIC example for previewing the sheets.
It is not used or modified by the monitoring script. Actual output is
created under data\test or data\prod when the corresponding BAT is run.
