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

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

## 1. Role

### modUtil.FormatNumberForSql

`FormatNumberForSql` is a shared utility function that converts a `Currency` type numeric value into a SQL-safe string representation. Its primary purpose is to ensure that numeric values embedded directly into SQL statement text always use a period (`.`) as the decimal separator, regardless of the Windows locale settings on the host machine. On systems with non-US locales (e.g., Vietnamese Windows where the decimal separator is a comma `,`), direct string concatenation of `Currency` values using `&` or `CStr` silently inserts the locale-specific decimal character, which silently breaks the SQL statement's value count and causes runtime errors. This method uses VBA's `Str()` function — which is locale-independent and always uses `.` as the decimal separator — then `Trim()` to remove the leading space that `Str()` adds for non-negative numbers.

The method implements a **delegation pattern**: it delegates to two built-in VBA functions (`Str` and `Trim`) to achieve locale-safe formatting without requiring any external dependencies or complex logic. It serves as a reusable helper called by import and reconciliation procedures (`modImport.RunImport`, `modReconcile.InsertResult`, `modReconcile.RunReconcile`) whenever numeric values need to be interpolated into dynamically constructed SQL strings. Its role in the larger system is that of a **data transformer** — a shared utility ensuring data fidelity across diverse regional Windows configurations in a legacy Access/VBA application.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["Start: FormatNumberForSql"])
    PARAM["Parameter: n as Currency"]
    STR["Str n - Convert to string with dot decimal separator"]
    TRIM["Trim result - Remove leading space for positive values"]
    RETURN["Return SQL-safe numeric string"]
    END(["End"])

    START --> PARAM
    PARAM --> STR
    STR --> TRIM
    TRIM --> RETURN
    RETURN --> END
```

**Processing Description:**

1. **Accept parameter** — The function receives a single `Currency` typed parameter `n`, which holds the numeric value to be formatted.
2. **Convert to locale-safe string** — `Str(n)` is called. The VBA `Str` function converts the `Currency` value to its string representation using `.` as the decimal separator, which is locale-independent. For non-negative values, `Str` prepends a leading space (e.g., `Str(123.45)` yields `" 123.45"`). For negative values, no leading space is added (e.g., `Str(-123.45)` yields `"-123.45"`).
3. **Trim leading space** — `Trim()` removes the leading space that `Str()` adds for non-negative numbers, producing a clean numeric string suitable for SQL embedding.
4. **Return** — The resulting string is assigned to the function name `FormatNumberForSql`, which is how VBA functions return values.

There are no conditional branches, loops, or external method calls beyond `Str()` and `Trim()`. The processing is linear and deterministic.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `n` | `Currency` | A numeric monetary or measured value that needs to be embedded into a SQL statement. The `Currency` type in VBA provides fixed-point decimal arithmetic with 15 digits to the left of the decimal and 4 to the right, making it appropriate for financial and precise numeric data used in business operations such as import and reconciliation. |

**External state:** None. This method is purely functional — it reads only its parameter and returns a derived value without accessing any module-level variables, instance fields, or global state.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| — | `Str(n)` | — | — | VBA built-in function: converts Currency to locale-safe string representation (not a database operation). |
| — | `Trim(...)` | — | — | VBA built-in function: removes leading and trailing whitespace (not a database operation). |

**Note:** This method performs no database or service-level CRUD operations. It is a pure in-memory data transformation utility.

## 5. Dependency Trace

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

Terminal operations from this method: None (pure utility, no DB calls).

Direct callers found: 3 methods.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | `modImport.RunImport()` | `modImport.RunImport` -> `modUtil.FormatNumberForSql` | SQL interpolation of numeric values during data import |
| 2 | `modReconcile.InsertResult()` | `modReconcile.InsertResult` -> `modUtil.FormatNumberForSql` | SQL interpolation during reconciliation result insertion |
| 3 | `modReconcile.RunReconcile()` | `modReconcile.RunReconcile` -> `modUtil.FormatNumberForSql` | SQL interpolation during reconciliation execution |

**Context:** This utility is consumed by import and reconciliation workflows. When these callers construct SQL statements dynamically with numeric values, they route the values through `FormatNumberForSql` to ensure the resulting SQL text is always valid regardless of the user's Windows regional settings.

## 6. Per-Branch Detail Blocks

This method has no conditional branches, loops, or error-handling blocks. It is a single-pass linear transformation.

**Block 1** — [LINEAR PROCESS] (L37–42)

> Convert a Currency value to a SQL-safe string using locale-independent formatting.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `Str(n)` // Convert Currency to string with locale-independent decimal separator (period, ",") (VBA built-in, always uses "." regardless of Windows locale) |
| 2 | CALL | `Trim(Str(n))` // Remove leading space that Str() adds for non-negative values (e.g., " 123.45" -> "123.45") |
| 3 | RETURN | `FormatNumberForSql = Trim(Str(n))` // Assign result to function name (VBA return mechanism) |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Currency` | Data type | VBA fixed-point numeric type with 4 decimal places, used for financial and precise monetary calculations in the Access/VBA application |
| `Str()` | VBA function | Built-in VBA function that converts a numeric value to its string representation; always uses `.` as decimal separator regardless of system locale |
| `Trim()` | VBA function | Built-in VBA function that removes leading and trailing whitespace from a string |
| SQL-safe string | Concept | A numeric string formatted correctly for direct embedding into SQL statement text without causing syntax errors |
| Locale | Concept | Windows regional settings that determine formatting conventions such as decimal separators and thousands delimiters |
| `modImport` | Module | Import processing module that reads external data and inserts it into Access tables |
| `modReconcile` | Module | Reconciliation processing module that compares and validates data, inserting reconciliation results |