# Business Logic — JFUTicketUseShinIraiCC.callSC() [56 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JFUTicketUseShinIraiCC` |
| Layer | CC/Common Component |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JFUTicketUseShinIraiCC.callSC()

This method serves as the centralized API invocation dispatcher for the **Ticket Usage Request** business process (チケット利用依頼, or "ticket usage request") within the K-Opticom customer base system (eo顧客基盤システム). It wraps a single remote Service Component (SC) call — specifically the **EKKA0050002** service — which is responsible for registering and managing ticket-based usage requests for subscribed services (e.g., content add-ons, policy changes). The method implements a **delegation pattern**, building a parameter map from the incoming request parameters, invoking the SC via `ServiceComponentRequestInvoker`, and then processing the response.

Upon receiving the SC response, the method extracts the `CAANMsg` template and return status, invokes `editErrorInfoCom` to normalize error information into the standard error info format, and then sets the processed error list into the control map via `TemplateErrorUtil.getErrorInfo`. If the SC returns a non-zero return code or a non-zero status, the method constructs a detailed error message — capturing the SYSID, service contract number, policy code, and content registration mechanism details — and logs it as a system error (`EKF1930-KW`) before returning the result message to the caller. In the normal (zero-error) path, the method simply returns the `CAANMsg` for downstream screen or batch processing.

Design-wise, `callSC` is a **shared utility component** embedded within `JFUTicketUseShinIraiCC`, a common component class that coordinates ticket usage request operations. It is called by `JFUTicketUseShinIraiCC.execute()`, which acts as the entry point from the screen or batch layer. This method encapsulates the entire lifecycle of a single-ticket-usage-SC-invocation: parameter preparation, invocation, error normalization, error logging, and result return.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["callSC start"])
    BUILD_MAP["getInvokeCBS: Build paramMap from param and mappingData"]
    DEBUG_BEFORE["printDebugLog: API call start with paramMap"]
    SC_CALL["scCall.run(paramMap, handle)"]
    DEBUG_AFTER["printDebugLog: API call complete with result"]
    EXTRACT_TPL["Extract CAANMsg[] templates from result"]
    EXTRACT_MSG["Get msg = templates[0]"]
    EXTRACT_RET["Extract return_code and status from result"]
    EDIT_ERR["editErrorInfoCom: Edit error info"]
    GET_ERR_LIST["Get ERROR_INFO from control map"]
    NULL_CHECK{errList null?}
    INIT_LIST["errList = new ArrayList"]
    SET_ERR["setControlMapData: Set error info via TemplateErrorUtil"]
    STATUS_CHECK{return_code == 0 AND status == 0?}
    GET_API_CD["Get API result code from msg"]
    DEF_API_CD["apiRetCd = 9000 (HTTP status:500)"]
    BUILD_MSG["Build error message with ticket usage details"]
    LOG_ERR["printSyslog4Err: Output syslog error KKIFE334"]
    RETURN_MSG["Return msg"]
    NORMAL_RETURN["Return msg (normal)"]

    START --> BUILD_MAP
    BUILD_MAP --> DEBUG_BEFORE
    DEBUG_BEFORE --> SC_CALL
    SC_CALL --> DEBUG_AFTER
    DEBUG_AFTER --> EXTRACT_TPL
    EXTRACT_TPL --> EXTRACT_MSG
    EXTRACT_MSG --> EXTRACT_RET
    EXTRACT_RET --> EDIT_ERR
    EDIT_ERR --> GET_ERR_LIST
    GET_ERR_LIST --> NULL_CHECK
    NULL_CHECK -->|Yes| INIT_LIST
    NULL_CHECK -->|No| SET_ERR
    INIT_LIST --> SET_ERR
    SET_ERR --> STATUS_CHECK
    STATUS_CHECK -->|Yes| NORMAL_RETURN
    STATUS_CHECK -->|No| GET_API_CD
    GET_API_CD --> API_CD_NULL{apiRetCd null?}
    API_CD_NULL -->|Yes| DEF_API_CD
    API_CD_NULL -->|No| BUILD_MSG
    DEF_API_CD --> BUILD_MSG
    BUILD_MSG --> LOG_ERR
    LOG_ERR --> RETURN_MSG
    RETURN_MSG --> END_NODE(["callSC end"])
    NORMAL_RETURN --> END_NODE
```

**Processing Flow Summary:**

1. **Parameter Map Build** — `getInvokeCBS` maps `CAANMsg` data from the input parameter objects into a `HashMap<String, Object>` for the SC call.
2. **Pre-Call Debug Log** — Logs the start of the API call with the built parameter map.
3. **Service Component Invocation** — Delegates to `scCall.run()` to execute the EKKA0050002CBS API, passing the parameter map and session handle.
4. **Post-Call Debug Log** — Logs the completion with the raw SC result.
5. **Result Extraction** — Extracts the template array (`CAANMsg[]`) and the primary message object from the result.
6. **Status Extraction** — Pulls out the return code (as `Integer`) and the status field (as `int`).
7. **Error Info Normalization** — Calls `editErrorInfoCom` to enrich the error info with the return code and data map context.
8. **Error List Management** — Retrieves any existing error list from the control map; initializes an empty list if none exists, then sets the merged error info back via `TemplateErrorUtil.getErrorInfo`.
9. **Error Status Check** — If the return code is not `"0"` or status is non-zero, enters the error handling branch: extracts the API result code (defaulting to `9000` for HTTP status 500), builds a detailed error message, and logs it via `printSyslog4Err`. Otherwise, returns normally.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `handle` | `SessionHandle` | The database session handle that maintains the transactional context (connection, transaction isolation, and session state) for the SC call. It is passed through to `scCall.run()` to ensure the ticket usage request executes within the same database transaction. |
| 2 | `scCall` | `ServiceComponentRequestInvoker` | The service component invoker proxy that routes the parameter map to the remote or local SC implementation (EKKA0050002CBS). It acts as the delegation bridge between this common component and the actual business service. |
| 3 | `param` | `IRequestParameterReadWrite` | The request parameter object carrying the input data for the ticket usage request. It holds the mapped `CAANMsg` fields, the control map (which contains the error info list), and serves as both input carrier and error info output container. |
| 4 | `dataMapKey` | `String` | A string key used to identify the data map within `param`. It is passed to `editErrorInfoCom` so that error info is associated with the correct data map context (e.g., distinguishing between different sub-requests in a multi-operation batch). |
| 5 | `mappingData` | `Object[][]` | A 2D array of mapping rules used by `getInvokeCBS` to determine how fields from the input parameters should be mapped into the `CAANMsg` paramMap for the SC call. Each row typically contains `{sourceKey, targetKey}` or similar mapping pairs. |

**External State Read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `KKIFE334` | `static final String = "KKIFE334"` | External Interface ID constant used as the syslog message category/key for error logging. Identifies this method's error messages to the K-Opticom external interface logging system. |
| `API_MSG_ID` | `static final String = "EKF1930-KW"` | API Message ID constant used as the syslog message identifier for the error log entry (KEY: `EKF1930-KW`). Used to correlate error messages with the ticket usage request operation in system logs. |

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| - | `JFUTicketUseShinIraiCC.getInvokeCBS` | JFUTicketUseShinIraiCC | - | Maps request parameters into a `HashMap<String, Object>` for the SC call (R) |
| - | `JFUTicketUseShinIraiCC.printDebugLog` | JFUTicketUseShinIraiCC | - | Logs the start of the API call with paramMap |
| C | `ServiceComponentRequestInvoker.run` | EKKA0050002CBS | - | Invokes the EKKA0050002 Service Component to register/process the ticket usage request |
| - | `JFUTicketUseShinIraiCC.printDebugLog` | JFUTicketUseShinIraiCC | - | Logs the API call completion with the result |
| U | `JFUTicketUseShinIraiCC.editErrorInfoCom` | JFUTicketUseShinIraiCC | - | Normalizes error information based on return code and data map key |
| R | `IRequestParameterReadWrite.getControlMapData` | - | - | Reads existing error info list from the control map |
| U | `IRequestParameterReadWrite.setControlMapData` | - | - | Sets the processed error info back into the control map |
| R | `TemplateErrorUtil.getErrorInfo` | TemplateErrorUtil | - | Extracts and formats error information from the SC result |
| R | `CAANMsg.getString` | - | - | Reads API result code, SYSID, service contract number, policy code, and content add-on keys from the response message |
| - | `JFUTicketUseShinIraiCC.printSyslog4Err` | JFUTicketUseShinIraiCC | - | Outputs a system error log when the SC call returns a non-zero return code or status |

**CRUD Classification Notes:**

- **C (Create)**: The `scCall.run()` invocation targets the EKKA0050002CBS service component, which handles the creation/registration of ticket usage requests. This is the primary write operation of the method.
- **R (Read)**: `getInvokeCBS`, `getControlMapData`, `getErrorInfo`, and multiple `getString` calls on the response message all read data.
- **U (Update)**: `editErrorInfoCom` and `setControlMapData` modify the error information state within the param object.
- No D (Delete) operations are performed in this method.

## 5. Dependency Trace

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

No screen/batch entry points found within 8 hops. Direct callers found: 1 methods.
Terminal operations from this method: `printSyslog4Err` [-], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R], `getString` [R]

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CC: JFUTicketUseShinIraiCC | `execute()` → `callSC()` | `scCall.run [C] EKKA0050002CBS`, `getString [R] msg fields`, `printSyslog4Err [-] KKIFE334` |

**Trace Notes:**

- `callSC` is a **private helper method** of `JFUTicketUseShinIraiCC` and is only invoked from within the same class by `execute()`.
- `execute()` serves as the entry point that the screen or batch layer calls to perform the ticket usage request operation.
- The terminal operations from `callSC` are primarily reads from the `CAANMsg` response (SYSID, service contract number, policy code, content add-on mechanism keys) and error logging via `printSyslog4Err`. The actual create operation (`scCall.run`) targets the EKKA0050002CBS service component, which is responsible for persisting the ticket usage request data.

## 6. Per-Branch Detail Blocks

**Block 1** — SET `(paramMap initialization)` (L148)

Builds the parameter map for the SC call by delegating to `getInvokeCBS`.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `paramMap = getInvokeCBS(param, mappingData)` |

**Block 2** — EXEC `(pre-call debug logging)` (L150)

Logs the start of the API invocation with the built parameter map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `printDebugLog("[][][]Ticket usage request API call start" + paramMap)` // Logs API call start with paramMap |

**Block 3** — CALL `(SC invocation)` (L151)

Invokes the EKKA0050002CBS service component via the service component invoker.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `result = scCall.run(paramMap, handle)` |

**Block 4** — EXEC `(post-call debug logging)` (L153)

Logs the completion of the API invocation with the raw result.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `printDebugLog("[][][]Ticket usage request API call complete" + result)` |

**Block 5** — SET `(result extraction)` (L155–L159)

Extracts the template array, message object, return code, and status from the SC result.

| # | Type | Code |
|---|------|------|
| 1 | SET | `templates = (CAANMsg[])result.get(JCMConstants.TEMPLATE_LIST_KEY)` // Extracts template array from result map |
| 2 | SET | `msg = templates[0]` // Primary response message |
| 3 | SET | `return_code = result.get(JCMConstants.RET_CD_INT_KEY)` // Return code (Integer) — "0" indicates success [-> JCMConstants.TEMPLATE_LIST_KEY], [-> JCMConstants.RET_CD_INT_KEY] |
| 4 | SET | `status = msg.getInt(JCMConstants.STATUS_INT_KEY)` // Status field from message [-> JCMConstants.STATUS_INT_KEY] |

**Block 6** — CALL `(error info normalization)` (L161)

Normalizes error info by calling the internal `editErrorInfoCom` method with the return code and data map context.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `editErrorInfoCom(param, templates, return_code, dataMapKey, mappingData)` |

**Block 7** — SET `(error list retrieval)` (L164–L169)

Retrieves the existing error info list from the control map; initializes an empty list if absent.

| # | Type | Code |
|---|------|------|
| 1 | SET | `errList = (ArrayList<Object>)param.getControlMapData(SCControlMapKeys.ERROR_INFO)` |

**Block 8** — IF `(errList null check)` `(L170)`

Checks whether an existing error list is present in the control map.

| # | Type | Code |
|---|------|------|
| 1 | SET | `errList = new ArrayList<Object>()` // Initializes empty error list if null |

**Block 9** — SET `(error info merge and set)` (L173)

Merges error information from the SC result into the error list and sets it back into the control map.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `param.setControlMapData(SCControlMapKeys.ERROR_INFO, TemplateErrorUtil.getErrorInfo(result, errList))` // Merges and stores error info |

**Block 10** — IF `(error status check)` `(L176)`

Conditional branch: if the return code is non-zero or the status field is non-zero, the method enters error handling mode.

> Business description: Checks whether the SC call succeeded. A return code of `"0"` and a status of `0` indicate a successful ticket usage request. Any deviation triggers the error logging path.
>
> `[-> "0".equals(return_code.toString()) AND 0 == status]`

**Block 10.1** — ELSE (error path) `(L177–L196)`

When the SC call fails, this block constructs a detailed error message and logs it.

| # | Type | Code |
|---|------|------|
| 1 | SET | `apiRetCd = msg.getString(EKKA0050002CBSMsg.API_RSLT_CD)` // API result code from response |

**Block 11** — IF `(apiRetCd null check)` `(L179)`

If the SC response did not include an API result code, defaults to `9000` indicating a generic HTTP status 500 error.

> `[-> apiRetCd == null]`

| # | Type | Code |
|---|------|------|
| 1 | SET | `apiRetCd = "9000 (HTTP status:500)"` // Default error code when API result code is missing |

**Block 12** — SET `(error message construction)` `(L183–L194)`

Builds a comprehensive error message containing all relevant ticket usage details.

> Original comment: メッセージログ（システムログ）にメッセージID「EKF1930-KW」に該当するメッセージを出力する — Output a message corresponding to message ID "EKF1930-KW" to the message log (system log).

| # | Type | Code |
|---|------|------|
| 1 | SET | `message = "Error occurred in ticket usage request, ticket usage information could not be registered normally."` // Error message prefix |
| 2 | SET | `+ "(KEY: identification code=TASV000301SC : SYSID=" + msg.getString(EKKA0050002CBSMsg.SYSID)` // Includes SYSID from response |
| 3 | SET | `: service contract number=" + msg.getString(EKKA0050002CBSMsg.SVC_KEI_NO)` // Service contract number |
| 4 | SET | `: policy code=" + msg.getString(EKKA0050002CBSMsg.SISAK_CD)` // Policy code |
| 5 | SET | `: content registration mechanism code=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_CD)` // Content add-on mechanism code |
| 6 | SET | `: content registration mechanism target key1=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_KEY_1)` |
| 7 | SET | `: key2=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_KEY_2)` |
| 8 | SET | `: key3=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_KEY_3)` |
| 9 | SET | `: key4=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_KEY_4)` |
| 10 | SET | `: key5=" + msg.getString(EKKA0050002CBSMsg.CP_ADD_KEIKI_KEY_5)` |
| 11 | SET | `: API processing result code=" + apiRetCd + ")"` |

**Block 13** — CALL `(error logging)` `(L195)`

Outputs the error to the system log using the KKIFE334 interface ID and EKF1930-KW message ID.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `printSyslog4Err(KKIFE334, API_MSG_ID, message)` // Logs system error [KKIFE334="KKIFE334"], [API_MSG_ID="EKF1930-KW"] |

**Block 14** — RETURN `(method exit)` `(L197)`

Returns the response message to the caller regardless of success or error path.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return msg` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `callSC` | Method | Calls the Service Component (SC) — central invocation method for the ticket usage request API |
| `getInvokeCBS` | Method | Maps `CAANMsg` request data into a parameter map (`HashMap<String, Object>`) for CBS/SC invocation |
| `editErrorInfoCom` | Method | Internal method that edits and normalizes error information based on the SC return code |
| `printDebugLog` | Method | Outputs debug-level log messages with the API call context |
| `printSyslog4Err` | Method | Outputs a system error-level log (syslog) with a specific message ID and category |
| `TemplateErrorUtil.getErrorInfo` | Method | Utility that extracts and formats error information from SC results into a standardized error list |
| `SCControlMapKeys.ERROR_INFO` | Constant Key | Control map key for the error information list — stores error details per request |
| `JCMConstants.TEMPLATE_LIST_KEY` | Constant Key | Key to extract the `CAANMsg[]` template array from the SC result map |
| `JCMConstants.RET_CD_INT_KEY` | Constant Key | Key to extract the return code (Integer) from the SC result map |
| `JCMConstants.STATUS_INT_KEY` | Constant Key | Key to extract the status field (int) from the response `CAANMsg` |
| `scCall` | Parameter | ServiceComponentRequestInvoker — the proxy that delegates to the remote/local SC implementation |
| `handle` | Parameter | SessionHandle — database session and transaction context carrier |
| `param` | Parameter | IRequestParameterReadWrite — input/output carrier for the ticket usage request, holding both request data and error info |
| `mappingData` | Parameter | Object[][] — 2D mapping rules for field mapping into the SC parameter map |
| `dataMapKey` | Parameter | String — identifies the data map context for error info association |
| `paramMap` | Variable | HashMap<String, Object> — parameter map built from request data, passed to the SC call |
| `result` | Variable | Map<?, ?> — raw result returned by scCall.run(), containing templates, return code, and status |
| `msg` | Variable | CAANMsg — the primary response message from the SC, used to extract status, API result code, and error details |
| `return_code` | Variable | Integer — the return code from the SC result; `"0"` means success |
| `status` | Variable | int — the status field from the response message; `0` means success |
| `errList` | Variable | ArrayList<Object> — list of error entries managed in the control map |
| `apiRetCd` | Variable | String — API processing result code extracted from the response message |
| `message` | Variable | String — the formatted error message constructed for system log output |
| `KKIFE334` | Constant | External Interface ID = "KKIFE334" — identifies the KKIFE334 external interface for error logging |
| `API_MSG_ID` | Constant | API Message ID = "EKF1930-KW" — the syslog message identifier for ticket usage request errors |
| TEMPLATE_ID_EKKA0050002 | Constant | Template ID = "EKKA0050002" — the template identifier for the ticket usage request SC |
| SYSID | Constant | Field key = "sysid" — system identifier for the service request |
| SVC_KEI_NO | Constant | Field key = "svc_kei_no" — service contract number |
| SISAK_CD | Constant | Field key = "sisak_cd" — policy code |
| CMP_ADD_OPTNTY_CD | Constant | Field key = "cmp_add_optnty_cd" — content registration mechanism code |
| CMP_ADD_OPTNTY_TG_KEY_1 through 5 | Constants | Field keys for content registration mechanism target keys (1 through 5) |
| FMT_YMDHMSS | Constant | Date format string = "yyyyMMddHHmmss" — used for timestamp formatting |
| STATUS_FORMAT | Constant | Status format string = "%1$04d" — zero-padded 4-digit status format |
| PREFIX_KEY_ITEM | Constant | Error item prefix = "key_" — prefix for error item keys |
| PREFIX_ERR_ITEM | Constant | Error item suffix = "_err" — suffix for error item keys |
| KEY_RETURN_MESSAGE | Constant | CC error message prefix = "RETURN_MESSAGE_" — prefix for CC-level error messages |
| WAR | Constant | Message separator = "WAR" — used as a separator in message formatting |
| CAANMsg | Type | Fujitsu's standard message object for request/response data exchange — holds typed fields (getString, getInt, etc.) |
| IRequestParameterReadWrite | Type | Interface for bidirectional request parameter access — holds both input data and control map for error propagation |
| ServiceComponentRequestInvoker | Type | Invoker proxy that routes calls to Service Component implementations |
| SessionHandle | Type | Database session handle — manages DB connections, transactions, and session state |
| EKKA0050002CBS | SC | EKKA0050002 Service Component — the backend service for ticket usage request processing (registering/processing ticket-based usage requests for subscribed services) |
| Ticket Usage Request (チケット利用依頼) | Business term | A request to register or modify ticket-based usage rights for a customer's subscribed services (e.g., content add-ons, policy changes). Tickets represent authorized usage entitlements. |
| TASV000301SC | SC Code | Ticket management SC code — referenced in error message as the identification code for the ticket system |
| EKKA0050002CBSMsg | Class | Message class for the EKKA0050002 service — defines field constants (API_RSLT_CD, SYSID, SVC_KEI_NO, SISAK_CD, CP_ADD_KEIKI_*) for the ticket usage request response |
| API_RSLT_CD | Field | API result code — the SC's business-level result code indicating success or specific failure reason |
| SVC_KEI_NO | Field | Service contract number — the unique identifier for the customer's service contract |
| SISAK_CD | Field | Policy code — identifies the promotional or business policy applied to the service |
| CP_ADD_KEIKI_CD | Field | Content add-on registration mechanism code — identifies the mechanism type for content add-on registration |
| CP_ADD_KEIKI_KEY_1 through 5 | Fields | Content add-on registration mechanism target keys (1–5) — identifies specific content or entity keys associated with the add-on |
| EKF1930-KW | Message ID | Syslog message ID for ticket usage request error logging — used with KKIFE334 interface to log errors |
| eo顧客基盤システム | Japanese term | eo Customer Base System — the core customer information and service management platform for K-Opticom's eo brand telecommunications services |