---
title: Establish/refresh Oracle data connection
summary: Prepare or reuse the Oracle data-portal handle required for code-table lookups.
status: draft
owner: SAIF DocGen
last_reviewed: 2026-07-30
library: SAIF.Framework.CodeGen
reference_type: package
operation_id: OP-CODEGEN-001
trigger: Constructor call or later Connect invocation
---

# Establish/refresh Oracle data connection

This operation prepares the shared `IDataPortalInfo` handle that both code-generation operations use to run their query. It runs automatically the moment a caller constructs `CodeTableMap`, and it rebuilds the underlying Oracle data-layer objects only when the requested `dbUser` or `database` differs from the connection already cached on the instance — otherwise it leaves the existing connection untouched.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CODEGEN-001 |
| **Trigger** | Constructor call or later `Connect(dbUser, database)` invocation |
| **Inputs** | `dbUser`, `database` |
| **Outputs** | Populated or reused `m_dpi As IDataPortalInfo` |
| **Primary components** | `CodeTableMap.New`, `CodeTableMap.Connect` |
| **Entry point** | `SAIF.Framework.CodeGen\CodeTableMap.vb` |

## Steps

1. `CodeTableMap.New(dbUser, database)` calls `Connect(dbUser, database)` as the last step of object construction, so every new instance is connection-ready before the caller can invoke a generation method.
2. `Connect` first checks whether `m_dpi` already references an Oracle data portal ([BR-004](../business-rules.md#br-004-data-connection-is-only-re-established-when-parameters-change)).
   - If `m_dpi` exists and both `m_dpi.Database` and `m_dpi.dbUser` match the requested values, the method keeps the existing portal in place and returns without doing any further work ([BR-004](../business-rules.md#br-004-data-connection-is-only-re-established-when-parameters-change)).
   - If `m_dpi` is `Nothing`, or either value differs from what is cached, the method proceeds to build a new Oracle data-layer instance ([BR-004](../business-rules.md#br-004-data-connection-is-only-re-established-when-parameters-change)).
3. `Connect` instantiates `New clsMSOracleDataLayer(dbUser, database)` and reads its `DataPortalInfo` property.
   - The delegated constructor creates a new `clsDataAccess` owner together with a `clsDataAccess.clsEnvironment` object.
   - It copies the requested `dbUser` and `database` values into that environment, fixes `DBMSType` to Oracle, and turns on connection pooling.
   - It creates a `clsMSOracleDataPortal` from the prepared environment.
   - It registers that portal with `m_DataAccess.AddDataPortal(...)`, assigns `DataApiAccessLayer`, and hands the resulting `IDataPortalInfo` handle back to `CodeTableMap`.

   > **Origin**: Steps 3.1-3.4 are implemented in [Execute a data portal request](../../saif-framework-core/operations/execute-data-portal-request.md) (`SAIF.Framework.Core`) and execute on behalf of this operation.
4. `Connect` assigns the returned handle to `m_dpi`, so the instance is ready for the code-table query the generation operations issue immediately afterward.
5. No local exception handling wraps this sequence, so any failure raised while constructing or registering the Oracle data layer propagates unchanged to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller constructs CodeTableMap]) --> Check{Existing m_dpi?}
	Check -->|No| Build[Create new clsMSOracleDataLayer]
	Check -->|Yes| Compare{Same database<br>and dbUser?}
	Compare -->|Yes| Reuse[Keep current IDataPortalInfo]
	Compare -->|No| Build
	Build --> Assign[Assign DataPortalInfo to m_dpi]
	Reuse --> EndOk([Connection ready])
	Assign --> EndOk
```

## Failure and edge-case behavior

- Repeated calls with an unchanged `dbUser`/`database` pair intentionally reuse the current portal rather than paying the cost of rebuilding the Oracle data layer ([BR-004](../business-rules.md#br-004-data-connection-is-only-re-established-when-parameters-change)).
- Any exception raised while constructing `clsMSOracleDataLayer` or registering its portal propagates unchanged to the caller, because `Connect` neither catches nor wraps it.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

## Sources
- SAIF.Framework.CodeGen\CodeTableMap.vb
- SAIF.Framework.Core\V1\DataAccessLayer\MSOracle\MSOracleDataLayer.vb
- SAIF.Framework.Core\V1\Interfaces\iDataPortalInfo.vb