/sap-background-jobs

name: sap-background-jobs
description: "Investigate SAP background jobs, including failed or aborted jobs, job status, job steps, job logs, runtime dumps, TBTCO, TBTCP, and TBTCJOBLOG0-9."

SAP Background Job Investigation

Overview

This is an investigation procedure, not a callable background-job connector. Use the read-only SQL and dump tools with TBTCO, TBTCP, TBTCJOBLOG0-9, and T100 as described below. The procedure covers finding job instances, reading logs, and diagnosing failures including runtime dumps.

Rules

• ALWAYS identify the exact job instance with both `JOBNAME` and `JOBCOUNT` before investigating it
• Treat every SQL error as a likely agent query defect. Stop the investigation, diagnose the reported table, field, type, grouping, or ABAP SQL syntax problem, correct the query, and rerun the same query before continuing. Do not treat a failed query as an empty result or switch to unrelated tables/tools without explaining why the corrected query cannot run.
• ALWAYS follow the partition lookup and fallback sequence in Step 4, then count the matching entries before retrieving a log
• NEVER attempt to build the full job log for large logs (>100 entries) — use targeted queries instead (filter by msgtype, or read only last N entries)
• ALWAYS check TBTCP for every job step, including its program, variant, status, and `AUTHCKNAM` execution user
• NEVER use the job scheduler to identify the runtime context of a failed step. `TBTCO-SDLUNAME` is the user who scheduled the job, while `TBTCP-AUTHCKNAM` is the execution user for that specific step. A multi-step job can use a different execution user for each step
• ALWAYS resolve every message through T100 as described in Step 8 before interpreting its text or `MSGV1`-`MSGV4` values; treat any business meaning inferred beforehand as unproven
• For aborted jobs (status = 'A'), ALWAYS check the **last few log entries first** — they contain the failure reason
• When message 00/671 appears, follow the dump investigation in Step 9
• Custom messages (message class starting with Z* or Y*) indicate custom code is writing to the job log — these are often the most informative for business logic failures
• For periodic jobs, check `TBTCO.periodic = 'X'` and the period fields (`prdmins`, `prdhours`, `prddays`, `prdweeks`, `prdmonths`) to understand scheduling

Procedure

1. Establish the SAP connection

Identify the SAP system the user intends to investigate and obtain its `connectionId`. In a multi-system workspace, do not infer the target system from the job name alone. Use `abapfs_get_sap_system_info` to obtain the SAP system timezone and UTC offset; use that timezone when interpreting job dates and times.

2. Find the job instance

**Query TBTCO** to find job instances by name, status, date range, or user:

SELECT jobname, jobcount, status, strtdate, strttime, enddate, endtime, 
       sdluname, reluname, authcknam, periodic, joblog
FROM tbtco
WHERE jobname = '{JOB_NAME}'
  AND status = '{STATUS}'
ORDER BY strtdate DESCENDING, strttime DESCENDING

Omit the `status` predicate when the user did not request a status filter.

Key fields:

• `jobname` + `jobcount` = unique job instance identifier (always need both)
• `status` = current state (see Status Codes below)
• `strtdate`/`strttime` = actual start
• `enddate`/`endtime` = actual end
• `sdluname` = user who scheduled the job
• `reluname` = user who released the job
• `authcknam` = job-header authorization-check user; do not use it as the failed step's runtime user
• `periodic` = 'X' if recurring
• `joblog` = **partition pointer** (critical for log retrieval)

3. Get the job steps

**Query TBTCP** to see what programs run in the job:

SELECT jobname, jobcount, stepcount, progname, variant, authcknam, status
FROM tbtcp
WHERE jobname = '{JOB_NAME}' AND jobcount = '{JOBCOUNT}'
ORDER BY stepcount

`TBTCP-AUTHCKNAM` is the execution user for that individual step. Record it for every step because different steps in the same job can run as different users. Identify the step active immediately before the failure from the step order, step status, and job-log lifecycle messages such as 00/550. Use that step's execution user when investigating authorization failures and matching runtime dumps.

4. Determine the log partition

**Primary method — Read the `joblog` field** from TBTCO. Extract the digit after "DB":

• `DB0 ...` → query `TBTCJOBLOG0`
• `DB1 ...` → query `TBTCJOBLOG1`
• ...
• `DB9 ...` → query `TBTCJOBLOG9`

**Fallback — if the determined table returns no results:** 1. The `joblog` pointer may be stale (e.g., after log reorganization or table redistribution) 2. Run COUNT queries for all 10 tables in parallel: TBTCJOBLOG0, TBTCJOBLOG1, ..., TBTCJOBLOG9 3. Identify which table contains entries for this jobname + jobcount

**If `joblog` is empty:**

• The job may not have produced a log (e.g., it was never started, or it's still in Planned/Released state)
• Try scanning all 10 tables, but expect no results

5. Check the log size

SELECT COUNT(*) as cnt 
FROM tbtcjoblog{n}
WHERE jobname = '{JOB_NAME}' AND jobcount = '{JOBCOUNT}'

**Decision tree based on size:**

• **≤ 100 entries**: Retrieve the full log and investigate its lifecycle, warnings, errors, custom messages, and failing-step context
• **> 100 entries**: Retrieve error/abort entries and the final 20 entries (see Step 7)

6. Retrieve the job log

SELECT jobname, jobcount, linenumber, enterdate, entertime, 
       msgid, msgno, msgtype, msgv1, msgv2, msgv3, msgv4
FROM tbtcjoblog{n}
WHERE jobname = '{JOB_NAME}' AND jobcount = '{JOBCOUNT}'
ORDER BY linenumber

7. Targeted queries for large or failed job logs

**For failures — get last N entries (most valuable):**

SELECT jobname, jobcount, linenumber, enterdate, entertime,
       msgid, msgno, msgtype, msgv1, msgv2, msgv3, msgv4
FROM tbtcjoblog{n}
WHERE jobname = '{JOB_NAME}' AND jobcount = '{JOB