# Business Logic — JKKKikiDslAddCC.callSC() [75 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKKikiDslAddCC` |
| Layer | CC / Common Component — a shared utility component within the BPM custom layer |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKKikiDslAddCC.callSC()

`callSC` is the **central service-component invocation bridge** in the KKK (DSL order handling) module. It wraps the invocation of any Service Component (SC) that follows the Fujitsu EJB-based communication framework, handling the full lifecycle of request preparation, service dispatch, response extraction, status normalization, error aggregation, and result validation.

The method implements the **Adapter + Template** pattern: it reads the incoming telegram metadata (transaction ID, use-case ID, operation ID, call type), extracts user-context data (client hostname, IP, screen ID, operator), and maps DSL-specific parameters from the `mappingData` array into a `CAANMsg` template whose class name is constructed dynamically from the service interface identifier (`svcIf`). It then dispatches this template to the generic `ServiceComponentRequestInvoker.run()` API, which is the entry point for all downstream SC executions.

Upon receiving the SC response, `callSC` normalizes status codes — overriding the template status to `9000` if the SC itself reports a non-zero return code, and resetting the status to `0` if the code does not correspond to any registered return message. It also enforces a **minimum status threshold** by comparing the template status against the business-partner-set return code, elevating the status in the control map if the template's status is more severe.

Error information is extracted from both the template message (`setErrorInf`) and the SC result map (`TemplateErrorUtil.getErrorInfo`), merged into a single error list, and stored back in the control map. Finally, the method performs a **terminal validation**: if the SC did not return exactly `"0"` with a status of `0`, it throws an `SCCallException`, propagating the actual return code and status to the caller.

`callSC` is used internally by three methods within `JKKKikiDslAddCC` — `addKikiDsl`, `addSOD`, and `judgeSodHakko` — to execute DSL order creation, service order data registration, and service order issuance judgment, respectively. This makes it the **primary dispatch mechanism** for all DSL service component calls in the KKK module.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["callSC(params)"])
    EDIT["editInMsg(param, mappingData)<br/>Build paramMap from telegram + user data"]
    SRCALL["scCall.run(paramMap, handle)<br/>Invoke Service Component"]
    TEMPLATES["templates = result.get(TEMPLATE_LIST_KEY)"]
    MSG["msg = templates[0]"]
    RETCODE["returnCode = result.get(RET_CD_INT_KEY)"]
    TSTATUS["templateStatus = msg.getInt(STATUS_INT_KEY)"]
    CHECKRC["returnCode != 0?"]
    SET9000["templateStatus = 9000<br/>SC reported error"]
    MSGLOOKUP["JCMAPLConstMgr.getString(<br/>RETURN_MESSAGE_xxxx)?"]
    RESETSTATUS["templateStatus = 0<br/>Unknown status reset"]
    BPSTATUS["bpStatus = parse(getControlMapData(RETURN_CODE))<br/>-1 if null"]
    CMPSTATUS["templateStatus > bpStatus?"]
    SETCM{"Yes"}
    SETCM2{"No"}
    SETERRORINF["setErrorInf(msg, map)<br/>Extract error fields from template"]
    ERRMAP["errList = getControlMapData(ERROR_INFO)"]
    ERRNULL{"errList == null?"}
    CREATEERR["errList = new ArrayList<Object>()"]
    UPDATEERR["TemplateErrorUtil.getErrorInfo(result, errList)<br/>setControlMapData(ERROR_INFO, mergedErrList)"]
    VALIDATE["rtnCode != '0' OR status != 0?"]
    THROWEX["throw SCCallException(<br/>'戻値不正', rtnCode, status)"]
    RETURN["return msg<br/>Success: response message"]

    START --> EDIT --> SRCALL --> TEMPLATES --> MSG --> RETCODE --> TSTATUS
    TSTATUS --> CHECKRC
    CHECKRC -->|Yes| SET9000
    CHECKRC -->|No| MSGLOOKUP
    SET9000 --> MSGLOOKUP
    MSGLOOKUP -->|null (unknown)| RESETSTATUS
    MSGLOOKUP -->|not null| CMPSTATUS
    RESETSTATUS --> CMPSTATUS
    CMPSTATUS --> SETCM
    CMPSTATUS --> SETCM2
    SETCM --> SETCM2
    SETCM2 --> SETERRORINF
    SETERRORINF --> ERRMAP
    ERRMAP -->|null| CREATEERR
    ERRMAP -->|not null| UPDATEERR
    CREATEERR --> UPDATEERR
    UPDATEERR --> VALIDATE
    VALIDATE -->|Yes| THROWEX
    VALIDATE -->|No| RETURN
```

**Processing flow summary:**

1. **Request Preparation** (`editInMsg`): Reads the incoming telegram metadata and user-context control map data, maps DSL parameters from `mappingData`, and assembles a `paramMap` with a dynamically named `CAANMsg` template.

2. **Service Invocation** (`scCall.run`): Dispatches the prepared request to the generic SC invocation bridge with the session handle.

3. **Response Extraction**: Retrieves the template list and status code from the result map.

4. **Status Normalization**: If the SC reports a non-zero return code, overrides the template status to `9000`. Then checks if the status maps to a known return message; if not, resets it to `0`.

5. **Status Elevation**: Compares the normalized template status against the business-partner-set return code stored in the control map. If the template status is higher (more severe), replaces the control map's return code and message with the template's.

6. **Error Information Collection**: Extracts error fields from the response template via `setErrorInf`, then merges SC-level error details via `TemplateErrorUtil.getErrorInfo`.

7. **Terminal Validation**: Verifies the SC returned exactly return code `"0"` and status `0`. If not, throws `SCCallException`. Otherwise, returns the response message.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `handle` | `SessionHandle` | The EJB session context for the SC invocation, carrying session-level information such as transaction boundaries, security credentials, and connection pooling metadata. |
| 2 | `scCall` | `ServiceComponentRequestInvoker` | The generic service-component dispatcher object used to invoke arbitrary SCs. It provides the `run(paramMap, handle)` method that executes the downstream service component with the prepared parameter map and session handle. |
| 3 | `param` | `IRequestParameterReadWrite` | The request parameter holder that carries the incoming telegram metadata (transaction ID, use-case ID, operation ID, call type), user context (hostname, IP, screen ID, operator, date/time), and control map data (return code, error info, etc.). |
| 4 | `dataMapKey` | `String` | A key used to access a business data map (`HashMap<String, Object>`) stored within `param` via `param.getData(dataMapKey)`. This map receives error field values extracted from the response template during the `setErrorInf` call. |
| 5 | `mappingData` | `Object[][]` | A 2D mapping array where each row represents a field-to-value binding for the SC request template. Row `[0][1]` contains the service interface name (`svcIf`) used to construct the template class name. Subsequent rows map column names (`mappingData[i][0]`) to values (`mappingData[i][1]`); empty value strings are treated as nulls. |

**External state / instance fields read:**

| Source | Description |
|--------|-------------|
| `editInMsg` (called method) | Reads `param.getTelegramID()`, `param.getUsecaseID()`, `param.getOperationID()`, `param.getCallType()`, and control map entries for hostname, IP, screen ID, operator, and operation date/time. |
| `setErrorInf` (called method) | Reads `msg.getSchema().getSchemaKeySet()` to iterate over all template schema keys, extracting fields ending with `_err`. |
| `JCMConstants` (constant class) | Provides keys: `TEMPLATE_LIST_KEY`, `RET_CD_INT_KEY`, `STATUS_INT_KEY`, `TRANZACTION_ID_KEY`, `USECASE_ID_KEY`, `OPERATION_ID_KEY`, `CALL_TYPE_KEY`, `CLIENT_HOST_NAME_KEY`, `CLIENT_IP_ADDRESS_KEY`, `INVOKE_GAMEN_ID_KEY`, `OPERATOR_ID_KEY`, `OPERATE_DATE_KEY`, `OPERATE_DATETIME_KEY`. |
| `SCControlMapKeys` (constant class) | Provides keys: `RETURN_CODE`, `RETURN_MESSAGE`, `ERROR_INFO`, `REQ_HOSTNAME`, `REQ_HOSTIP`, `REQ_VIEWID`. |
| `JCMAPLConstMgr` (utility class) | Provides `getString(key)` to look up return message text by the pattern `RETURN_MESSAGE_xxxx`. |

## 4. CRUD Operations / Called Services

The method itself does not directly query or modify database tables. Instead, it dispatches to Service Components (SCs) and calls internal utility methods. The operations are classified below.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `scCall.run(paramMap, handle)` | (varies — SC code resolved at runtime from `mappingData[0][1]`) | (depends on which SC is invoked) | Generic service-component invocation. The actual SC called depends on the `svcIf` value in `mappingData[0][1]`, which determines the template class name `eo.ejb.cbs.cbsmsg.{svcIf}CBSMsg`. |
| C/R | `editInMsg(param, mappingData)` | N/A (internal utility) | N/A | Reads telegram and control map data to build the SC request parameter map and constructs the `CAANMsg` template. |
| U | `setErrorInf(msg, map)` | N/A (internal utility) | N/A | Updates the business data map with error fields extracted from the response template schema. |
| R | `TemplateErrorUtil.getErrorInfo(result, errList)` | N/A (utility class) | N/A | Reads error information from the SC result map and merges it into the existing error list. |

Because `callSC` is a **generic dispatcher**, the actual SC code and database tables accessed depend on which caller invokes it and what `svcIf` value is provided in `mappingData`. The three callers (`addKikiDsl`, `addSOD`, `judgeSodHakko`) each pass different service interfaces, resulting in different downstream SCs, SC codes, and database operations.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Class: `JKKKikiDslAddCC.addKikiDsl` | `JKKKikiDslAddCC.addKikiDsl` → `callSC(handle, scCall, param, dataMapKey, mappingData)` | SC dispatch — varies by caller context (DSL order registration) |
| 2 | Class: `JKKKikiDslAddCC.addSOD` | `JKKKikiDslAddCC.addSOD` → `callSC(handle, scCall, param, dataMapKey, mappingData)` | SC dispatch — service order data creation |
| 3 | Class: `JKKKikiDslAddCC.judgeSodHakko` | `JKKKikiDslAddCC.judgeSodHakko` → `callSC(handle, scCall, param, dataMapKey, mappingData)` | SC dispatch — service order issuance judgment |

**Terminal operations reachable from this method:**

| Terminal Method | Type | Source |
|----------------|------|--------|
| `scCall.run` | Dispatch | Generic SC invocation (varies by caller) |
| `editInMsg` | Read (internal) | Telegram + control map data extraction |
| `setErrorInf` | Update (internal) | Error field extraction from template |
| `TemplateErrorUtil.getErrorInfo` | Read | SC result error info retrieval |
| `JCMAPLConstMgr.getString` | Read | Return message lookup by status code |

## 6. Per-Branch Detail Blocks

**Block 1** — [SET] `(paramMap initialization)` (L2339)

Request preparation via `editInMsg`. This is a nested method call that internally:
- Creates a `HashMap<String, Object> paramMap`
- Populates telegram metadata keys (`TRANZACTION_ID_KEY`, `USECASE_ID_KEY`, `OPERATION_ID_KEY`, `CALL_TYPE_KEY`) from `param`
- Populates user-context control map keys (`CLIENT_HOST_NAME_KEY`, `CLIENT_IP_ADDRESS_KEY`, `INVOKE_GAMEN_ID_KEY`, `OPERATOR_ID_KEY`)
- Extracts `svcIf` from `mappingData[0][1]` and creates a `CAANMsg` with class name `eo.ejb.cbs.cbsmsg.{svcIf}CBSMsg`
- Sets operator ID, operate date, operate date/time on the template
- Iterates over `mappingData` to set field values (or nulls for empty strings)
- Wraps the template in a `CAANMsg[]` array and stores it under `TEMPLATE_LIST_KEY`

| # | Type | Code |
|---|------|------|
| 1 | CALL | `paramMap = editInMsg(param, mappingData)` // Prepares request parameter map with template |

---

**Block 2** — [SET] `(SC invocation)` (L2341)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `result = scCall.run(paramMap, handle)` // Invokes the Service Component |

---

**Block 3** — [SET] `(response extraction)` (L2343–2344)

| # | Type | Code |
|---|------|------|
| 1 | SET | `templates = (CAANMsg[])result.get(JCMConstants.TEMPLATE_LIST_KEY)` // Extract response template array |
| 2 | SET | `msg = templates[0]` // Take first (and only) template as response message |

---

**Block 4** — [SET] `(return code acquisition)` (L2347)

Comment: リターンコード取得 (Obtain return code)

| # | Type | Code |
|---|------|------|
| 1 | SET | `returnCode = (Integer)result.get(JCMConstants.RET_CD_INT_KEY)` // Extract return code from SC result |

---

**Block 5** — [SET] `(template status acquisition)` (L2349)

| # | Type | Code |
|---|------|------|
| 1 | SET | `templateStatus = msg.getInt(JCMConstants.STATUS_INT_KEY)` // Extract status from response template |

---

**Block 6** — [IF] `(SC reported error — override status to 9000)` (L2351)

Condition: `0 != returnCode` — If the SC returned a non-zero return code, the template status is overridden to `9000` to indicate an SC-level error.

| # | Type | Code |
|---|------|------|
| 1 | SET | `templateStatus = 9000` // Override status to 9000 when SC reports error |

---

**Block 7** — [IF] `(unknown status — reset to 0)` (L2354)

Condition: `null == JCMAPLConstMgr.getString("RETURN_MESSAGE_" + format(templateStatus))` — If the formatted status code does not correspond to a registered return message (i.e., it's an unknown status), reset the status to `0`.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `JCMAPLConstMgr.getString("RETURN_MESSAGE_" + String.format("%1$04d", templateStatus))` // Lookup return message |
| 2 | SET | `templateStatus = 0` // Reset to 0 if status is unknown |

---

**Block 8** — [IF/ELSE] `(business partner status acquisition)` (L2357–2364)

Retrieve the business-partner-set return code from the control map. If absent, use `-1` as the baseline (meaning any template status will be higher).

| # | Type | Code |
|---|------|------|
| 1 | SET | `bpStatus = 0` // Default initial value |
| 2 | SET | `obj = param.getControlMapData(SCControlMapKeys.RETURN_CODE)` // Get BP-set return code |
| 3 | IF | `null == obj` // BP has not set a return code |
| 3.1 | SET | `bpStatus = -1` // Use -1 as default (any template status will override) |
| 3.2 | ELSE | |
| 3.2.1 | SET | `bpStatus = Integer.parseInt((String)param.getControlMapData(SCControlMapKeys.RETURN_CODE))` // Parse the BP-set status |

---

**Block 9** — [IF] `(status elevation — use template status if more severe)` (L2366)

Condition: `templateStatus > bpStatus` — If the normalized template status is higher (more severe) than what the business partner set, propagate the template's status and its corresponding message to the control map.

| # | Type | Code |
|---|------|------|
| 1 | SET | `formatStatus = String.format("%1$04d", templateStatus)` // Format status as 4-digit string |
| 2 | SET | `message = JCMAPLConstMgr.getString("RETURN_MESSAGE_" + formatStatus)` // Look up message text |
| 3 | SET | `param.setControlMapData(SCControlMapKeys.RETURN_CODE, formatStatus)` // Override return code |
| 4 | SET | `param.setControlMapData(SCControlMapKeys.RETURN_MESSAGE, message)` // Override return message |

> This block implements a **minimum severity policy**: the SC's own status takes precedence if it is more severe than any status the business layer has already set, ensuring that critical SC errors are never masked by business-layer processing.

---

**Block 10** — [CALL] `(error information extraction from template)` (L2382)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `setErrorInf(msg, (HashMap<String, Object>)param.getData(dataMapKey))` // Extract _err fields from template schema |

**Nested detail of `setErrorInf`:**
- Iterates over all keys in the message schema (`msg.getSchema().getSchemaKeySet()`)
- For each key ending with `_err`, if the template field is not null and the business data map does not already contain that key, stores the error field value in the map.

---

**Block 11** — [IF/ELSE] `(error list initialization)` (L2385–2388)

Retrieve the existing error list from the control map; create a new one if it does not exist.

| # | Type | Code |
|---|------|------|
| 1 | SET | `errList = (ArrayList<Object>)param.getControlMapData(SCControlMapKeys.ERROR_INFO)` // Get existing error list |
| 2 | IF | `null == errList` // No existing error list |
| 2.1 | SET | `errList = new ArrayList<Object>()` // Create new error list |
| 2.2 | ELSE | // Error list already exists |

---

**Block 12** — [SET] `(merge SC error info)` (L2391)

| # | Type | Code |
|---|------|------|
| 1 | SET | `param.setControlMapData(SCControlMapKeys.ERROR_INFO, TemplateErrorUtil.getErrorInfo(result, errList))` // Merge and store error list |

---

**Block 13** — [SET] `(validation data extraction)` (L2396–2397)

Comment: 取得したリターンコード、ステータスの内容を見て異常かどうかの判断をする (Check if abnormal by examining the obtained return code and status)

| # | Type | Code |
|---|------|------|
| 1 | SET | `rtnCode = result.get(JCMConstants.RET_CD_INT_KEY).toString()` // Convert return code to String |
| 2 | SET | `status = msg.getInt(JCMConstants.STATUS_INT_KEY)` // Get status as Integer |

---

**Block 14** — [IF] `(terminal validation — throw on non-zero)` (L2400)

Condition: `!("0".equals(rtnCode) && 0 == status.intValue())` — If the return code is not `"0"` or the status is not `0`, the method throws an `SCCallException` with the message "戻値不正" (Invalid return value).

Comment: 異常の場合、SCCallExceptionを生成してスローする (In case of abnormality, generate SCCallException and throw)

| # | Type | Code |
|---|------|------|
| 1 | SET | `scCallEx = new SCCallException("戻値不正", rtnCode, status)` // Create exception with message, code, and status |
| 2 | RETURN | `throw scCallEx` // Propagate the exception to the caller |

---

**Block 15** — [RETURN] `(success path)` (L2402)

When all validation passes (return code `"0"` and status `0`), return the response message to the caller.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return msg` // Return the SC response message |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `callSC` | Method | Central service-component invocation bridge — wraps any SC call with request preparation, response handling, and validation |
| `SC` | Acronym | Service Component — a modular business logic unit in the Fujitsu EJB framework, invoked via the `ServiceComponentRequestInvoker` |
| `SCCode` | Acronym | Service Component Code — an identifier like `EKK0361A010SC` that uniquely identifies a service component |
| `CAANMsg` | Class | Common Application Abstract Network Message — the message object used to carry request and response data between SCs and the BPM layer |
| `SessionHandle` | Class | EJB session handle carrying session context (transaction, security, connection) for SC invocation |
| `ServiceComponentRequestInvoker` | Interface | The generic dispatcher that executes Service Components via its `run(paramMap, handle)` method |
| `IRequestParameterReadWrite` | Interface | Request parameter holder that provides telegram metadata and control map data read/write access |
| `paramMap` | Variable | A `HashMap<String, Object>` containing the assembled SC request parameters, including the template and metadata |
| `paramMap` | Variable | A `HashMap<String, Object>` containing the assembled SC request parameters, including the template and metadata |
| `svcIf` | Variable | Service interface name extracted from `mappingData[0][1]`; used to construct the SC message template class name (`eo.ejb.cbs.cbsmsg.{svcIf}CBSMsg`) |
| `mappingData` | Parameter | A 2D array mapping SC request field names to their values; row 0, column 1 holds the service interface name |
| `dataMapKey` | Parameter | A key used to access the business data map within `param`, where error fields are stored by `setErrorInf` |
| `templateStatus` | Variable | The status code from the response template, normalized to account for SC return code and unknown-status checks |
| `bpStatus` | Variable | Business-partner-set return code stored in the control map, used as a minimum severity threshold |
| `R` | — | Read (see CRUD classification) |
| `RETURN_MESSAGE_xxxx` | Constant | Return message lookup key pattern where `xxxx` is a 4-digit status code |
| `templateStatus = 9000` | Constant | Error override status — when the SC reports a non-zero return code, status is set to 9000 |
| `ERR_xxx` | Field | Error fields in the response template whose names end with `_err`, containing localized error descriptions |
| `ERROR_INFO` | Constant | Control map key for the error information list (`ArrayList<Object>`) |
| `RETURN_CODE` | Constant | Control map key for the business-partner return code |
| `RETURN_MESSAGE` | Constant | Control map key for the business-partner return message text |
| `REQ_HOSTNAME` | Constant | Control map key for the requesting client hostname |
| `REQ_HOSTIP` | Constant | Control map key for the requesting client IP address |
| `REQ_VIEWID` | Constant | Control map key for the requesting screen/view ID |
| `SCControlMapKeys` | Class | Constant class defining control map key names for SC communication (part of the Fujitsu JCM framework) |
| `JCMConstants` | Class | Constant class defining communication framework keys (transaction ID, use-case ID, operation ID, status, etc.) |
| `JCMAPLConstMgr` | Class | Fujitsu JCM framework utility for retrieving constant message strings by key |
| `TemplateErrorUtil.getErrorInfo` | Method | Utility that extracts error information from the SC result map and merges it with an existing error list |
| `editInMsg` | Method | Internal utility that builds the SC request parameter map by reading telegram data, control map data, and mapping data |
| `setErrorInf` | Method | Internal utility that extracts error fields from the response template schema and stores them in the business data map |
| `SCCallException` | Class | Custom exception thrown when the SC returns a non-zero return code or non-zero status, carrying the actual return code and status |
| `戻値不正` | Japanese | "Invalid return value" — the error message embedded in `SCCallException` |
| `リターンコード取得` | Japanese | "Obtain return code" — comment describing the extraction of the SC return code from the result map |
| `異常の場合` | Japanese | "In case of abnormality" — comment introducing the terminal validation check |
| `取得したリターンコード` | Japanese | "Obtained return code" — comment about validating the SC response |