Add sources for episode 3

README.md

@@ -10,10 +10,12 @@ This repository hosts the source code and supporting assets featured in the DBL
 ## Repository Layout
 - `episode1/` - materials for Episode 1, including the `Ep1Demo.sln` solution and shared build settings in `Common.props`.
 - `episode2/` - materials for Episode 2, provided as individual source files that demonstrate `Select`, `Where`, `OrderBy`, `GroupBy`, joins, updates, and deletes against ISAM data.
+- `episode3/` - materials for Episode 3, provided as individual source files that demonstrate I/O Hooks, logging hooks, performance considerations, and a bonus buffer-handling example.
 
 ## Episode Guide
 - **Episode 1: Basic I/O in Synergy DBL** - demonstrates basics of CRUD operations in Synergy DBL, setting the stage for future deep dives into file handling, error management, and coding patterns.
 - **Episode 2: Querying ISAM Data with the Select Class** - explores how the `Select` class brings SQL-like querying capabilities to ISAM data, building on the I/O fundamentals from Episode 1 with practical examples for filtering, sorting, grouping, updating, deleting, and joining records across files.
+- **Episode 3: I/O Hooks in Synergy DBL** - dives into intercepting and extending standard I/O operations such as `READS` and `WRITEs` without changing core application logic. The episode walks through creating a custom `LoggingIOHooks` class, attaching hooks to file channels, using global hooks with `SYN_GLOBALHOOKS_OPEN`, applying hooks selectively by filename or open mode, and evaluating performance considerations for synchronous hook execution.
 
 ## Using the Samples
 1. Ensure you have a Synergy DBL development environment (Synergy/DE, the Visual Studio integration, or your preferred compiler toolchain).

episode3/Program.dbl

@@ -0,0 +1,16 @@
+main
+    record
+        channel, int
+    record rec
+        somedata, a100
+proc
+    open(channel=0, i:i, "employee.ism")
+    new Example.BufferedLoggingIOHooks(channel)
+
+    ; Perform read operations as usual
+    ; The hooks will automatically log messages before and after the read
+    reads(channel, rec)
+
+    close channel
+    channel = 0
+end

episode3/buffer.dbl

@@ -0,0 +1,44 @@
+import System.Collections
+import Synergex.SynergyDE.IOExtensions
+
+namespace Example
+    class BufferedLoggingIOHooks inherits IOHooks
+        private const BUFFER_THRESHOLD, int, 100
+        protected logBuffer, @ArrayList
+        ; Other hook methods
+
+        public method BufferedLoggingIOHooks
+            ch, int
+            parent(ch)
+        proc
+
+        endmethod
+
+        protected method write_post_operation_hook, void
+            inout buffer, a
+            in flags, IOFlags
+            inout error, int
+        proc
+            ; Append log to buffer
+            logBuffer.Add(BuildLogEntry(buffer))
+            ; Periodically flush the buffer
+            if logBuffer.Count >= BUFFER_THRESHOLD then
+                FlushLogBuffer()
+            else
+                return
+        endmethod
+
+        private method BuildLogEntry, @a
+            buffer, a
+        proc
+            ;;format the log entry here and return it
+            mreturn (@a)buffer
+        endmethod
+
+        private method FlushLogBuffer, void
+        proc
+            ;;write out all of the entries from logBuffer and clear it
+        endmethod
+
+    endclass
+endnamespace

episode3/logging.dbl

@@ -0,0 +1,27 @@
+import Synergex.SynergyDE.IOExtensions
+
+namespace Example
+    class LoggingIOHooks inherits IOHooks
+        public method LoggingIOHooks
+            ch, int
+            parent(ch)
+        proc
+        endmethod
+
+        protected method read_pre_operation_hook, void
+            in flags, IOFlags
+        proc
+            ; Custom logic before a read operation
+            Console.WriteLine("Pre-read hook: Starting read operation.")
+        endmethod
+
+        protected method read_post_operation_hook, void
+            inout buffer, a
+            in flags, IOFlags
+            inout error, int
+        proc
+            ; Custom logic after a read operation
+            Console.WriteLine("Post-read hook: Read operation completed.")
+        endmethod
+    endclass
+endnamespace

episode3/performance.dbl

@@ -0,0 +1,22 @@
+import Synergex.SynergyDE.IOExtensions
+
+namespace Example
+    class HeavyProcessingIOHooks inherits IOHooks
+        public method HeavyProcessingIOHooks
+            ch, int
+            parent(ch)
+        proc
+
+        endmethod
+
+        protected method read_post_operation_hook, void
+            inout buffer, a
+            in flags, IOFlags
+            inout error, int
+        proc
+            ; Complex data processing
+            ; or time-consuming external API call
+            ;PerformComplexDataProcessing(buffer)
+        endmethod
+    endclass
+endnamespace