---
title: Reserve service reference lookups
summary: Loads and caches the vocational service type, vocational cost type, and medical service type reference lists together with their service descriptions.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim
reference_type: package
operation_id: OP-BC-15
trigger: A caller requests a reserve service reference list through the reserve services module accessors
---

# Reserve service reference lookups

Reserving for a claim requires naming the kind of service being reserved for: a vocational service type, a vocational cost type, or a medical service type, each of which carries a set of more specific service descriptions. This operation loads those three lists, caches each in a module-level static so the round trip happens once per process, and groups the descriptions under their parent service type so callers can drive dependent pick lists from a single retrieval.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-BC-15 |
| **Trigger** | `ReserveServices.GetVocationalServiceTypes(dataPortalInfo, refresh)`, `ReserveServices.GetVocationalCostTypes(dataPortalInfo, refresh)`, `ReserveServices.GetMedicalServiceTypes(dataPortalInfo, refresh)` |
| **Inputs** | A data portal info; an optional refresh flag |
| **Outputs** | A vocational service type code table keyed by code; a service type collection for vocational cost types and for medical service types, each service type carrying its service description collection |
| **Primary components** | `mdlReserveServices.GetVocationalServiceTypes`, `mdlReserveServices.GetVocationalCostTypes`, `mdlReserveServices.GetMedicalServiceTypes`, `clsVocationalServiceTypes`, `clsServiceTypeCollection`, `clsServiceType`, `clsServiceDescriptionCollection`, `clsServiceDescription` |
| **Entry point** | `Business\SAIF.Business.Claim\mdlReserveServices.vb` |

## Steps

1. **Serve the cached list when possible.** Each module accessor holds its loaded list in a static local, builds it on first use, and rebuilds it only when the caller passes the refresh flag.
2. **Load the vocational service types.** `clsVocationalServiceTypes` selects every column of the vocational service type code table and stores each row's code and description in a code table keyed by code ([SQL-012](../sql/SQL-012-saif-business-claim.md), [CL_RESERVE_VOC_SERV_TYPE_CODE](../database-tables.md#cl_reserve_voc_serv_type_code)).
3. **Build the service type query.** For vocational cost types and for medical service types, `clsServiceTypeCollection` assembles a select that joins the service type code table to its matching service description code table with a left outer join, so a service type with no descriptions still appears, and orders the result by service type description and then service description.
   - The medical variant joins the medical service type and medical service description code tables.
   - The vocational variant joins the vocational service cost and vocational service description code tables.
   - These reference tables and the statement that joins them are not represented in this library's database table or SQL catalogs.*
4. **Execute as a result set.** The collection issues the assembled statement as a result-set request rather than a reader-based retrieve, so the whole reference list is materialized in one pass.
5. **Group descriptions under their service type.** `AfterRetrieve` walks the result rows in the ordered sequence, starting a new service type whenever the service type code changes, and attaching a service description collection to each service type.
   - Rows whose service description code is blank — the outer-join placeholders for a service type with no descriptions — are filtered out of the description collection rather than added as empty entries.
6. **Return read-only lists.** The service type collection and its description collections are read-only framework collections, so callers can enumerate and bind them but cannot persist changes through them.

## Process flow

The following diagram visualizes the load-and-group flow.

```mermaid
flowchart TD
	Start([Caller requests a reserve<br>service reference list]) --> Cache{Cached and refresh<br>not requested?}
	Cache -->|Yes| Serve([Return the cached list])
	Cache -->|No| Which{Which list?}
	Which -->|Vocational service types| Voc[Select the vocational service<br>type code table]
	Which -->|Vocational cost types| Cost[Join cost code table to<br>vocational description codes]
	Which -->|Medical service types| Med[Join medical service type to<br>medical description codes]
	Voc --> Table[Store code and description<br>in a code table]
	Cost --> Rows[Read the ordered result set]
	Med --> Rows
	Rows --> Group{Service type code<br>changed?}
	Group -->|Yes| NewType[Start a new service type<br>with an empty description list]
	Group -->|No| Desc{Description code blank?}
	NewType --> Desc
	Desc -->|Yes| Skip[Skip the outer-join placeholder]
	Desc -->|No| Add[Add the service description]
	Skip --> Next{More rows?}
	Add --> Next
	Next -->|Yes| Group
	Next -->|No| Store([Cache and return the list])
	Table --> Store
```

## Failure and edge-case behavior

- The caches are module-level statics with no expiry, so a reference list changed in the database is not seen until a caller explicitly requests a refresh or the process restarts.
- The grouping logic depends on the result set arriving sorted by service type; removing or changing the order-by clause would silently produce duplicate service type entries.*
- Because blank description codes are filtered after grouping, a service type with no descriptions is returned with an empty description collection rather than being omitted, which callers binding dependent pick lists must handle.
- The joined reference tables are not catalogued in this library's database table documentation, so schema changes to them are not tracked here.*
- The lists are read-only; maintaining reserve service reference data happens outside this library.

## 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.

## Sources

- `Business\SAIF.Business.Claim\mdlReserveServices.vb`
- `Business\SAIF.Business.Claim\clsVocationalServicesTypes.vb`
- `Business\SAIF.Business.Claim\clsServiceType.vb`
- `Business\SAIF.Business.Claim\clsServiceTypeCollection.vb`
- `Business\SAIF.Business.Claim\clsServiceDescription.vb`
- `Business\SAIF.Business.Claim\clsServiceDescriptionCollection.vb`