# Business Logic — modUtil.FormatNumberForSql() [9 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `modUtil.FormatNumberForSql` |
| Layer | Utility |
| Module | `modUtil` (Package: `ar-reconciliation-vba-access/vba-source/modUtil.bas`) |

## 1. Role

### modUtil.FormatNumberForSql

`FormatNumberForSql` is a shared utility function that converts a VBA `Currency`-typed number into a SQL-safe string representation. Its business purpose is to prevent silent data corruption when numeric values are embedded directly into SQL statement text via string concatenation. On Windows systems with non-US locale settings (e.g., Vietnamese Windows, where the decimal separator is a comma "," instead of a period "."), naive string concatenation or `CStr()` would insert a comma into the SQL literal, silently breaking the statement's column-value count and causing runtime SQL errors. The function avoids this by delegating to VBA's `Str()` function — which always produces a period as the decimal separator regardless of locale — and then trimming the leading space that `Str()` adds for non-negative values. It plays the role of a localized-agnostic numeric formatter, called by the import pipeline (`modImport.RunImport`) when building `INSERT` statements for both `tblTransactions` and `tblBankStatement`, and by the reconciliation engine (`modReconcile.RunReconcile`) when performing fuzzy matching where the transaction amount must appear in a SQL `WHERE` clause.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["FormatNumberForSql(n As Currency)"])
    STEP1["Convert Currency to SQL-safe String via Str() + Trim()"]
    RETURN(["Return formatted String"])

    START --> STEP1
    STEP1 --> RETURN
```

**Processing Description:**

1. The method receives a single `Currency` parameter `n` (e.g., a monetary amount from an imported Excel row or a reconciled transaction).
2. It calls VBA's built-in `Str(n)` function, which produces a string representation guaranteed to use "." as the decimal separator regardless of the user's Windows locale. `Str()` also pads the string with a leading space for non-negative values.
3. It calls `Trim()` to remove the leading space, producing a compact numeric string (e.g., `"1234.56"` instead of `" 1234.56"`).
4. The resulting string is assigned to `FormatNumberForSql` (VBA's function return mechanism) and returned to the caller.

There are no conditional branches, no loops, and no external state reads. This is a pure transformation function.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `n` | `Currency` | A monetary amount — typically a transaction amount imported from an Excel file or a variance computed during bank reconciliation. Currency values in VBA are fixed-point numbers scaled by 10,000, providing up to 4 decimal places of precision, which is appropriate for financial data. |

**External state:** None. This method is pure — it reads no instance fields, static variables, or external state.

## 4. CRUD Operations / Called Services

This method makes no calls to other services, database operations, or business methods. It is a pure string transformation with no CRUD footprint.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| — | — | — | — | No database operations — pure string formatting utility |

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

No screen/batch entry points found within 8 hops. Direct callers found: 3 methods.
Terminal operations from this method: -

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Module: `modImport` | `RunImport` → `db.Execute("INSERT INTO tblBankStatement ... " + FormatNumberForSql(t.Amount))` | `[C] tblBankStatement` |
| 2 | Module: `modImport` | `RunImport` → `db.Execute("INSERT INTO tblTransactions ... " + FormatNumberForSql(t.Amount))` | `[C] tblTransactions` |
| 3 | Module: `modReconcile` | `RunReconcile` → `db.OpenRecordset("SELECT ... WHERE Amount = " + FormatNumberForSql(rsTrans!Amount))` | `[R] tblBankStatement` |
| 4 | Module: `modReconcile` | `InsertResult` → `db.Execute("INSERT INTO tblReconcileResult ... " + FormatNumberForSql(variance))` | `[C] tblReconcileResult` |

## 6. Per-Branch Detail Blocks

This method has no conditional branches, loops, or nested control flow. It is a single-statement function body.

**Block 1** — [FUNCTION BODY] (L34–L42)

> Assign the locale-safe string representation of a Currency value to the function's return variable. No conditional logic, no loops, no external calls.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `FormatNumberForSql = Trim(Str(n))` // Convert Currency to SQL-safe string. `Str()` guarantees "." as the decimal separator regardless of Windows locale. `Trim()` removes the leading space that `Str()` adds for non-negative numbers. |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Currency` | VBA Type | Fixed-point numeric type scaled by 10,000, providing up to 4 decimal places. Used in VBA for financial calculations to avoid floating-point rounding errors. |
| `Str()` | VBA Function | Built-in VBA function that converts a number to a String. Always uses "." as the decimal separator, regardless of the system's Windows locale settings. Prepends a space for non-negative values. |
| `Trim()` | VBA Function | Built-in VBA function that removes leading and trailing whitespace from a string. |
| SQL-safe string | Concept | A string representation of a value safe to embed directly into SQL text via concatenation — correct decimal separator, no special character escaping issues. |
| `tblTransactions` | Table | Stores imported transaction records (branch, date, amount, reference number, import batch ID). |
| `tblBankStatement` | Table | Stores bank statement line items (date, amount, bank reference number, import batch ID). |
| `tblReconcileResult` | Table | Stores the results of the reconciliation process (transaction ID, statement ID, match status, variance). |
| `tblBankStatement` | Table | Stores bank statement line items (date, amount, bank reference number, import batch ID). |
| Locale | Concept | The regional settings of the Windows operating system that determine number formatting conventions (decimal separator, thousands separator, date format). Commonly "en-US" uses "." while "vi-VN" (Vietnamese) uses ",". |