---
title: Provider location ancillary data retrieval
summary: Retrieves four provider-location-scoped reference lists — MCO enrollments, DCBS cost charges, offered services, and service contracts — through a shared plain-list pattern that bypasses the standard BOF criteria/data-portal lifecycle.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.View.Provider
reference_type: package
operation_id: OP-VP-09
trigger: Caller reads clsProviderLocation.MCOList, DCBSCostCharges, Services, or ServiceContracts, or constructs clsMCOProviderList / clsDCBSCostChargeList / clsProviderServiceList / clsProviderServiceContractList directly
---
# Provider location ancillary data retrieval
Four small reference lists share an identical architectural shape, distinct from the rest of this library: each is a plain `Generic.List(Of T)` (not a `clsBusinessCollection`), populated entirely inside its constructor by a `StringBuilder`-composed `SELECT` executed through `SqlHelper.ResultSetQuery`, filtered by a provider location ID. None goes through `IBusinessCriteria` or the standard data-portal `BeforeRetrieve`/`AfterRetrieve` lifecycle used by the rest of this library. They are merged into one operation here because they are near-duplicate retrieval flows governed by the same construction pattern and the same provider-location scoping, differing only in the table queried and, for service contracts, an additional expiration-window rule.
| Field | Value |
| --- | --- |
| **Operation ID** | OP-VP-09 |
| **Trigger** | `New clsMCOProviderList(dpi, providerLocationID)` — invoked directly or via `clsProviderLocation.MCOList`; `New clsDCBSCostChargeList(dpi, providerLocationID)` — via `clsProviderLocation.DCBSCostCharges`; `New clsProviderServiceList(dpi, providerLocationID)` — via `clsProviderLocation.Services`; `New clsProviderServiceContractList(dpi, providerLocationID, [offset])` — via `clsProviderLocation.ServiceContracts` |
| **Inputs** | Provider location ID (Decimal) for all four lists; an optional expiration offset in days (Decimal, default 721) for the service-contract list only |
| **Outputs** | `clsMCOProviderList` (MCO enrollment fee rates and plan reference), `clsDCBSCostChargeList` (cost/charge factor by effective window), `clsProviderServiceList` (service code, description, primary-service flag, DCBS specialty code), `clsProviderServiceContractList` (discount rates, max charge amount, plan reference, ordered by effective date descending) |
| **Primary components** | `clsMCOProviderList.New`, `clsDCBSCostChargeList.New`, `clsProviderServiceList.New`, `clsProviderServiceContractList.New` |
| **Entry point** | `Business\SAIF.Business.View.Provider\clsMCOProvider.vb` |
## Steps
1. **Construct the list for a location.** Each list type's constructor takes the data-portal info and a provider location ID (the service-contract list also accepts an optional offset); construction is the only entry point — there is no separate factory method or lazy retrieval step.
2. **Compose the query with a `StringBuilder`.** Each constructor builds its `SELECT` by appending literal fragments, always filtering `WHERE PROVIDER_LOCATION_SEQ_NUM = :ProviderLocationID`:
- `clsMCOProviderList` reads `MCO_PROVIDER` for enrollment flags and fee rates ([SQL-002](../sql/SQL-002-saif-business-view-provider.md), [MCO_PROVIDER](../database-tables.md#mco_provider)).
- `clsDCBSCostChargeList` reads `PROVIDER_DCBS_COST_CHARGE` for the cost/charge factor and effective window ([SQL-001](../sql/SQL-001-saif-business-view-provider.md), [PROVIDER_DCBS_COST_CHARGE](../database-tables.md#provider_dcbs_cost_charge)).
- `clsProviderServiceList` joins `PROVIDER_SERVICE_CODE` to `PROVIDER_SERVICE` for the service code, description, DCBS specialty code, and primary-service flag ([SQL-017](../sql/SQL-017-saif-business-view-provider.md), [PROVIDER_SERVICE_CODE](../database-tables.md#provider_service_code), [PROVIDER_SERVICE](../database-tables.md#provider_service)).
- `clsProviderServiceContractList` reads `PROVIDER_SERVICE_CONTRACT` for discount rates, max charge amount, and plan/service codes, ordered by effective date descending ([SQL-016](../sql/SQL-016-saif-business-view-provider.md), [PROVIDER_SERVICE_CONTRACT](../database-tables.md#provider_service_contract)).
3. **Apply the service-contract expiration window.** When the constructor's offset parameter is greater than zero (the default is 721 days), the service-contract query appends `AND (exp_date IS NULL OR exp_date > (sysdate - :Offset))`, excluding contracts expired further in the past than the offset window, and binds `:Offset` ([BR-002](../business-rules.md#br-002-provider-service-contract-expiration-window)).
- If the offset is zero or negative: no expiration predicate is appended and no `:Offset` parameter is bound, so all contracts regardless of expiration are returned.
4. **Execute and map each row.** Each constructor executes its query through `SqlHelper.ResultSetQuery`, then iterates the returned rows, constructing one DTO instance per row and adding it to the list (`Me.Add(...)`).
5. **Resolve the MCO plan reference for MCO enrollments and service contracts.** For each row in the MCO enrollment list, and for each service-contract row whose plan ID is non-blank, the DTO's `SetPlan` is called with the plan resolved by `GetMCOInfo(inDPI).Plan(planID)`, and throws an `ApplicationException` if the resolved plan's ID does not match the row's plan ID.
> **Origin**: `GetMCOInfo` and its `Plan(planID)` lookup are not defined in this library's own source; the MCO plan reference-data resolution is delegated to an external dependency that could not be identified from this library's code alone.**
6. **Return the populated list.** Once all rows are processed, the fully populated list is available as the return value of the `New` constructor (assigned by the caller) or as the cached lazy-load property on `clsProviderLocation`.
## Process flow
The following diagram visualizes this operation's control flow, common to all four list types.
```mermaid
flowchart TD
Start([List constructed for a provider location]) --> Which{Which list?}
Which -->|MCO enrollments| MCO[Query MCO_PROVIDER]
Which -->|DCBS cost charges| DCBS[Query PROVIDER_DCBS_COST_CHARGE]
Which -->|Provider services| Svc[Join PROVIDER_SERVICE_CODE
to PROVIDER_SERVICE]
Which -->|Service contracts| Contract[Query PROVIDER_SERVICE_CONTRACT]
Contract --> Offset{Offset greater than zero?}
Offset -->|Yes| AddExp[Append expiration window predicate]
Offset -->|No| NoExp[No expiration predicate]
MCO --> Exec[Execute query]
DCBS --> Exec
Svc --> Exec
AddExp --> Exec
NoExp --> Exec
Exec --> Loop[For each row: construct DTO,
add to list]
Loop --> PlanCheck{MCO enrollment or
service contract with a plan ID?}
PlanCheck -->|Yes| Resolve[Resolve MCO plan reference;
throw if plan ID mismatch]
PlanCheck -->|No| Skip[Skip plan resolution]
Resolve --> Done([Populated list returned])
Skip --> Done
```
## Failure and edge-case behavior
- None of these four lists are `clsBusinessCollection` types, so they have no `IsValid`, `IsDirty`, or `Save` semantics; they are pure read-only projections populated once at construction time.
- A location with no matching rows for a given list simply returns an empty list; no exception is raised.
- `SetPlan` throws an `ApplicationException` if the resolved MCO plan's ID (trimmed, case-insensitive) does not match the row's stored plan ID — a defensive consistency check against the external MCO reference-data source rather than a business rule enforced by this library's own data.
- The service-contract list guards the plan lookup with a non-blank check on the trimmed plan ID before calling `SetPlan`, but the MCO enrollment list calls `SetPlan` unconditionally for every row, so an MCO enrollment row with a blank plan ID would call `GetMCOInfo(inDPI).Plan("")`, a path not explicitly guarded in that constructor.*
- The default 721-day offset on service contracts is a caller-adjustable parameter; passing `0` or a negative number disables the expiration filter entirely and returns every contract ever recorded for the location, including long-expired ones ([BR-002](../business-rules.md#br-002-provider-service-contract-expiration-window)).
## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)
> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat as
> unknown until verified.
## Sources
- `Business\SAIF.Business.View.Provider\clsMCOProvider.vb`
- `Business\SAIF.Business.View.Provider\clsDCBSCostCharge.vb`
- `Business\SAIF.Business.View.Provider\clsProviderServices.vb`
- `Business\SAIF.Business.View.Provider\clsProviderServiceContract.vb`