# Business Logic — JKKOpsvkeiTelIktAddCC.callEKK0341B002SC() [58 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKOpsvkeiTelIktAddCC` |
| Layer | CC (Common Component) — shared business logic layer |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKOpsvkeiTelIktAddCC.callEKK0341B002SC()

This method serves as a **Service Interface (SIF) invocation bridge** for querying the **Equipment-Provided Service Contract List by Service Contract Number** (機器提供サービス契約一覧照会（サービス契約番号） — a read-only screen query used in the telecom operations management domain of the eO Customer Base System. It is called from the `mainProc()` entry method of `JKKOpsvkeiTelIktAddCC`, which handles the overall "Operation Service Contract <Telephone> Mass Registration" (オプソンサービス契約<電話>一括登録) workflow.

The method delegates to the CBS (Service Component) endpoint **EKK0341B002CBS** via a `ServiceComponentRequestInvoker`. Its responsibility is to prepare the inbound SIF request message (common envelope, mapping template, and basic header info), invoke the CBS, and then extract and map the result data back into the caller's `resultHash`. On success (status code `0`), the method populates `resultHash` with two keys: `TEMPLATE_ID_EKK0341B002` (the mapped result hash from the CBS response) and `ALLDATA_EKK0341B002` (the raw full record list from the CBS response, added per ANK-3754-00-00 for Tobira-font compatibility). If the CBS returns a non-zero status, the method simply returns the error code without modifying `resultHash`.

The method implements the **delegation pattern** — it does not contain business logic of its own but orchestrates message construction and CBS invocation, delegating to `editInMsgCmn()`, `mappingEKK0341B002InMsg()`, `editBasicCmn()`, and `mappingEKK0341B002SCOutMsg()` for individual preparation and extraction tasks. It is a **private helper** used exclusively by `mainProc()` within the same class.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["callEKK0341B002SC()"])
    STEP1["editInMsgCmn - Set SIF request common info"]
    STEP2["new CAANMsg(EKK0341B002CBSMsg) - Create template"]
    STEP3["mappingEKK0341B002InMsg - Map input parameters to template"]
    STEP4["editBasicCmn - Set basic common fields"]
    STEP5["sIFRequest.put(TEMPLATE_LIST_KEY) - Add template to request"]
    STEP6["new ServiceComponentRequestInvoker() - Create invoker"]
    STEP7["scCall.run(sIFRequest, handle) - Invoke EKK0341B002 CBS"]
    STEP8["Extract resultMsgs from SIFResult"]
    STEP9["template.getInt(STATUS_INT_KEY) - Get status code"]
    COND{"status == 0?"}
    THEN1["resultHash.put(TEMPLATE_ID, mappingEKK0341B002SCOutMsg)"]
    THEN2["resultHash.put(ALLDATA, EKK0341B002CBSMsg1List)"]
    ELSE1["status != 0 - skip result mapping"]
    RETURN(["return status"])

    START --> STEP1
    STEP1 --> STEP2
    STEP2 --> STEP3
    STEP3 --> STEP4
    STEP4 --> STEP5
    STEP5 --> STEP6
    STEP6 --> STEP7
    STEP7 --> STEP8
    STEP8 --> STEP9
    STEP9 --> COND
    COND -->|status == 0| THEN1
    THEN1 --> THEN2
    THEN2 --> RETURN
    COND -->|status != 0| ELSE1
    ELSE1 --> RETURN
```

**Processing flow description:**

1. **Build SIF common envelope** — `editInMsgCmn(param)` creates the SIF request wrapper (correlation ID, session context, etc.).
2. **Create CBS message template** — Instantiate `CAANMsg` with `EKK0341B002CBSMsg.class` as the message type.
3. **Map input parameters** — `mappingEKK0341B002InMsg(template, inHash)` sets the template fields: function code (`FUNC_CD_6 = "6"`), key service contract number (`svc_kei_no`), and nulls out the key equipment-provided service code, key equipment-provided service contract number, and key sort key.
4. **Set basic common fields** — `editBasicCmn(param, template)` adds basic header fields to the template.
5. **Add template to request** — Put the template array into the SIF request under `TEMPLATE_LIST_KEY`.
6. **Create CBS invoker** — Instantiate `ServiceComponentRequestInvoker`.
7. **Invoke CBS** — Call `scCall.run(sIFRequest, handle)` which routes to `EKK0341B002CBS`.
8. **Extract response messages** — Get the result message array from `SIFResult` using `TEMPLATE_LIST_KEY`.
9. **Get status code** — Read status from template using `STATUS_INT_KEY`.
10. **Branch on status**:
    - **status == 0** (success): Map the CBS response into `resultHash` under both `TEMPLATE_ID_EKK0341B002` and `ALLDATA_EKK0341B002`.
    - **status != 0** (error): Skip result mapping, proceed to return.
11. **Return** — Return the status code to the caller.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `param` | `IRequestParameterReadWrite` | The request parameter object carrying screen input data. Provides read-write access to form fields, file uploads, and HTTP-level request data from the calling screen. Used to extract basic common fields via `editBasicCmn()` and `editInMsgCmn()`. |
| 2 | `handle` | `SessionHandle` | The database session handle for the current transaction context. Passed directly to `ServiceComponentRequestInvoker.run()` so the CBS invocation shares the same database session (transaction scope) as the caller. |
| 3 | `inHash` | `HashMap<String, Object>` | A condition map containing the query parameters for the service contract list lookup. Specifically, it must contain the key `SVC_KEI_NO` (resolved to `"svc_kei_no"`) whose value is the **Service Contract Number** (サービス契約番号) to filter results. Also used in `mappingEKK0341B002InMsg()` to set the function code and null-out irrelevant key fields. |
| 4 | `resultHash` | `HashMap<String, Object>` | An output map populated with the CBS query results. On success, it receives two entries: `TEMPLATE_ID_EKK0341B002` ("EKK0341B002") containing the mapped result hash, and `ALLDATA_EKK0341B002` ("ALLDATA_EKK0341B002") containing the full raw `EKK0341B002CBSMsg1List` array. |

**External state / instance fields used:** None. This method is fully stateless — it uses only local variables and passed-in parameters. All constants are resolved from standalone constant files (`JKKHakkoSODConstCC`, `JPCModelConstant`, `JCMConstants`).

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `EKK0341B002CBS.run` | EKK0341B002CBS | KK_T_OPSVKEI (Equipment-Provided Service Contract) | Reads equipment-provided service contract records filtered by service contract number (`svc_kei_no`). CBS invoked via `ServiceComponentRequestInvoker.run()` with the SIF request envelope. |
| - | `JKKOpsvkeiTelIktAddCC.editInMsgCmn` | JKKOpsvkeiTelIktAddCC | - | Prepares the SIF common request envelope (correlation ID, timestamp, session info). |
| - | `JKKOpsvkeiTelIktAddCC.editBasicCmn` | JKKOpsvkeiTelIktAddCC | - | Sets basic header fields (function code, system ID, etc.) into the CBS message template. |
| - | `JKKOpsvkeiTelIktAddCC.mappingEKK0341B002InMsg` | JKKOpsvkeiTelIktAddCC | - | Maps query conditions from `inHash` into the CBS request template (clears all fields, sets function code to `FUNC_CD_6="6"`, sets `svc_kei_no`, nulls out unused key fields). |
| - | `JKKOpsvkeiTelIktAddCC.mappingEKK0341B002SCOutMsg` | JKKOpsvkeiTelIktAddCC | - | Extracts and maps the CBS response message into a `HashMap<String, Object>` result structure. |

**CRUD classification:**
- **R** (Read): `EKK0341B002CBS.run` — The CBS is a query/listing operation. It reads equipment-provided service contract data from the database filtered by the service contract number. No data is modified.

**How SC Code was determined:**
- The CBS class name `EKK0341B002CBSMsg` indicates the CBS endpoint code is `EKK0341B002CBS`.
- The template ID constant `TEMPLATE_ID_EKK0341B002 = "EKK0341B002"` confirms this.
- The table `KK_T_OPSVKEI` is the Equipment-Provided Service Contract table, consistent with the method's purpose (querying service contract list).

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 method.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS: `JKKOpsvkeiTelIktAddCC.mainProc()` | `mainProc(param, handle)` → `callEKK0341B002SC(param, handle, requestParam, wkResultHash)` (L434) | `EKK0341B002CBS [R] KK_T_OPSVKEI` |

**Caller analysis:**
- `mainProc()` at line 434 of `JKKOpsvkeiTelIktAddCC.java` directly invokes `callEKK0341B002SC()` during the "Operation Service Contract <Telephone> Mass Registration" workflow. It passes the request parameter, session handle, condition hash, and result hash.
- The caller `mainProc()` is itself a Common Component (CC) method, not a direct screen entry point. It is typically invoked by a CBS layer method that handles the screen-to-business-mapping.
- The method does not have screen-level entry points (`KKSV*`) within 8 hops of the call graph. It is a **private SIF invocation helper**, not a direct entry point for user-facing screens.

## 6. Per-Branch Detail Blocks

**Block 1** — [VARIABLE DECLARATION] (L1721)

Local variable declarations for the method execution context.

| # | Type | Code |
|---|------|------|
| 1 | SET | `sIFRequest = null` // SIF request map |
| 2 | SET | `resultMsgs = null` // SIF response message array |
| 3 | SET | `template = null` // CBS message template |
| 4 | SET | `scCall = null` // CBS invocation handler |
| 5 | SET | `sIFResult = null` // SIF response map |
| 6 | SET | `status = 0` // Return status code, default 0 |

**Block 2** — [CALL] `editInMsgCmn` — Build SIF common envelope (L1730)

Sets up the common SIF request information (correlation ID, timestamp, session context).

| # | Type | Code |
|---|------|------|
| 1 | CALL | `sIFRequest = editInMsgCmn(param)` |

**Block 3** — [CALL] `mappingEKK0341B002InMsg` — Prepare CBS template (L1732–1733)

Creates and configures the CBS message template with query parameters.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template = new CAANMsg(EKK0341B002CBSMsg.class.getName())` |
| 2 | CALL | `mappingEKK0341B002InMsg(template, inHash)` // Maps `svc_kei_no` from `inHash` |
| 3 | CALL | `editBasicCmn(param, template)` // Sets basic header fields |

**Block 4** — [SET] Add template to SIF request (L1736)

Adds the prepared template to the SIF request envelope.

| # | Type | Code |
|---|------|------|
| 1 | SET | `sIFRequest.put(JCMConstants.TEMPLATE_LIST_KEY, new CAANMsg[]{template})` // Template list key |

**Block 5** — [CALL] `ServiceComponentRequestInvoker.run` — Invoke CBS (L1739–1742)

Generates the CBS invocation object and calls the EKK0341B002 CBS endpoint.

| # | Type | Code |
|---|------|------|
| 1 | SET | `scCall = new ServiceComponentRequestInvoker()` |
| 2 | CALL | `sIFResult = scCall.run(sIFRequest, handle)` // Invokes EKK0341B002CBS |

**Block 6** — [SET] Extract response messages (L1744)

Extracts the result message array from the SIF response.

| # | Type | Code |
|---|------|------|
| 1 | SET | `resultMsgs = (CAANMsg[])sIFResult.get(JCMConstants.TEMPLATE_LIST_KEY)` |

**Block 7** — [SET] Extract status code (L1747)

Reads the status code from the template to determine success or failure.

| # | Type | Code |
|---|------|------|
| 1 | SET | `status = template.getInt(JCMConstants.STATUS_INT_KEY)` |

**Block 8** — [IF] Status == 0 Check — Success branch (L1750)

> If status is 0, the CBS query succeeded. Populate resultHash with the mapped results and the full raw data list (ANK-3754-00-00 change for Tobira-font compatibility).

| # | Type | Code |
|---|------|------|
| 1 | SET | `resultHash.put(TEMPLATE_ID_EKK0341B002, mappingEKK0341B002SCOutMsg(resultMsgs))` // TEMPLATE_ID_EKK0341B002 = "EKK0341B002" |
| 2 | SET | `resultHash.put(ALLDATA_EKK0341B002, resultMsgs[0].getMsgData().get(EKK0341B002CBSMsg.EKK0341B002CBSMSG1LIST))` // ALLDATA_EKK0341B002 = "ALLDATA_EKK0341B002" — full record list |

**Block 8.1** — [CALL] `mappingEKK0341B002SCOutMsg` — Extract CBS output (L1751–1753)

> Called as the value for `resultHash.put(...)`. Extracts the first message from `resultMsgs`, retrieves the `EKK0341B002CBSMsg1List`, and if it contains entries, returns the first entry's message data as a `HashMap<String, Object>`.

| # | Type | Code |
|---|------|------|
| 1 | SET | `msg = resultMsgs[0]` |
| 2 | SET | `msgList = (CAANMsg[])msg.getMsgData().get(EKK0341B002CBSMsg.EKK0341B002CBSMSG1LIST)` |
| 3 | IF | `0 < msgList.length` (L1758) — if result list is non-empty |
| 3.1 | SET | `retHash = msgList[0].getMsgData()` // Return first entry's data |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `svc_kei_no` | Field | Service Contract Number (サービス契約番号) — the unique identifier for a service contract line item, used as the primary lookup key for this query |
| TEMPLATE_ID_EKK0341B002 | Constant | SIF Template ID = "EKK0341B002" — the message template identifier for the Equipment-Provided Service Contract List query |
| FUNC_CD_6 | Constant | Function Code = "6" — identifies this operation as "Equipment-Provided Service Contract List Inquiry by Service Contract Number" (機器提供サービス契約一覧照会（サービス契約番号）) |
| ALLDATA_EKK0341B002 | Constant | Result key = "ALLDATA_EKK0341B002" — key in resultHash for storing the full raw record list (added for Tobira-font compatibility per ANK-3754-00-00) |
| SIF | Acronym | Service Interface — the messaging layer between the CC (Common Component) and the CBS (Service Component). Uses CAANMsg for serialization. |
| CBS | Acronym | Service Component (Component-Based Service) — the business logic layer that implements CRUD operations on database tables |
| CC | Acronym | Common Component — the shared business logic layer that orchestrates CBS calls and maps data between screens and services |
| CAANMsg | Class | Common Application ANswer Message — Fujitsu's message container class for SIF/CBS serialization |
| ServiceComponentRequestInvoker | Class | The SIF invocation handler that routes requests to CBS endpoints using the template-based message format |
| KK_T_OPSVKEI | Entity/DB | Equipment-Provided Service Contract table — stores records for equipment-provided (telecom) service contracts |
| EKK0341B002CBS | SC Code | Service Component for Equipment-Provided Service Contract List Inquiry — the CBS that performs the actual database read |
| EKK0341B002CBSMsg1List | Field | The message list field within the CBS response containing the list of service contract records |
| STATUS_INT_KEY | Constant | Template key for reading the integer status code from the CBS response |
| TEMPLATE_LIST_KEY | Constant | SIF key for storing and retrieving the template array in the request/response maps |
| TEMPLATE_ID_DETAIL_EKK0341B002 | Constant | Detailed template ID for "Equipment-Provided Service Contract List Inquiry by Service Contract Number" |
| IN_COLUMN_LIST_EKK0341B002 | Constant | Input column list for the EKK0341B002 IN template |
| K-Opticom | Business term | The telecommunications service brand (K-Opticom) operated by the customer base system |
| eO Customer Base System | Business term | The core telecom operations system (eo顧客基幹システム) that manages customer service contracts, orders, and provisioning |
| Tobira-font | Business term | A font/UI framework (Tobiraフォント) used in the customer-facing portal; required additional data (ALLDATA key) in the response for compatibility |
| ANK-3754-00-00 | Change ticket | Tobira-font compatibility change — added `ALLDATA_EKK0341B002` to resultHash to provide full record data to the Tobira UI layer |
| FUNC_CODE_1 / FUNC_CODE_6 | Constants | Function codes: `"1"` and `"6"` distinguish different modes of the EKK0341B002 query (e.g., different filter criteria or output formats) |

---