CAPL Reference Skill

Overview

CAPL (Communication Access Programming Language) is the event-driven scripting language

for Vector CANoe/CANalyzer. It follows C89/C90 syntax constraints — no C99 or

C++ features. This skill provides corrected, production-ready reference material for

automotive diagnostic security testing with CAPL + DLL two-layer architecture.

Quick Syntax Rules (C89 Compliance)

• All variable declarations MUST appear at the top of the block (no mixed declarations)
• No // comments in strict C89 (CAPL compiler accepts them, but avoid for portability)
• No snprintf — use sprintf (ensure buffer is large enough)
• No strncpy_s — use strncpy, manually null-terminate
• No _atoi64 — use atol() or parse hex manually
• Local array initialization with {} is NOT supported — assign element by element
• Test Module functions use PascalCase: TestWaitForTimeout, TestStep, etc.

File Structure Template

/*@!Encoding:936*/

includes
{
  #include "Common.can"
}

variables
{
  msTimer tCycle;
  message 0x123 msg_Test;
  long gCounter;
  byte gData[8];
}

on start
{
  gCounter = 0;
  setTimer(tCycle, 100);
}

on timer tCycle
{
  gCounter++;
  msg_Test.dlc = 8;
  msg_Test.byte(0) = gCounter;
  output(msg_Test);
  setTimer(tCycle, 100);
}

on message 0x456
{
  write("Rx 0x456 byte0=0x%02X", this.byte(0));
}

Key Event Handlers

Message Handling

variables
{
  message 0x100 msg_Tx;
  message EngineData msg_Engine;  /* DB-backed message */
}

on start
{
  msg_Tx.dlc = 8;
  msg_Tx.byte(0) = 0x11;
  output(msg_Tx);
}

/* Access DB signal */
on message EngineData
{
  write("Speed=%f", this.EngineSpeed);
}

/* Write signal and send */
on key 's'
{
  msg_Engine.EngineSpeed = 1000;
  output(msg_Engine);
}

Test Module Syntax (PascalCase — Correct!)

testcase TC_SecurityAccess()
{
  TestCaseTitle("TC_SA_01", "Security Access Level 1");

  TestStep("SendSeed", "Send 27 01 RequestSeed");
  /* send request... */

  if (TestWaitForMessage(0x708, 1000) == 1)
  {
    TestStepPass("CheckResp", "Response received");
  }
  else
  {
    TestStepFail("CheckResp", "Response timeout");
  }
}

Correct function names:

All take two parameters (name, description):

TestStep("StepName", "Description of what is being done");
TestStepPass("StepName", "Reason for pass");
TestStepFail("StepName", "Reason for failure");

DLL Integration — CAPL_DLL_INFO4 Table (NOT __declspec)

CRITICAL: CAPL DLL functions are NOT discovered via the Windows DLL export table.

They are registered in a special CAPL_DLL_INFO4 table[] array that CANoe

reads at load time. This is completely different from standard __declspec(dllexport).

Step 1: Use the Official Sample Project (DO NOT start from empty DLL project)

Path varies by version, search for CAPLdll under:

C:\Users\Public\Documents\Vector\CANoe <version>\Sample Configurations\Programming\CAPLdll

Open the .sln in Visual Studio. The sample project already has:

• Correct header dependencies
• CAPL_DLL_INFO4 table[] format for your CANoe version
• Calling convention macros (CAPL_DLL_CDECL, CAPL_FARCALL, etc.)
• onCaplInit() / onCaplExit() wiring

Step 2: Add Your C/C++ Function

In capldll.cpp, add your function following the same pattern as existing functions:

long MyAdd(long a, long b)
{
    return a + b;
}

Step 3: Register in CAPL_DLL_INFO4 table[]

Add an entry to the table (format varies by CANoe version — **always copy from the

existing entries in your sample project**):

CAPL_DLL_INFO4 table[] =
{
    /* existing entries — do NOT remove */

    {
        "MyAdd",
        (CAPL_FARCALL)MyAdd,
        "long",
        "long a, long b",
        CAPL_DLL_CDECL,
        0,
        CDLL_EXPORT
    },

    { 0, 0 }   /* END MARKER — must keep */
};

Field meanings:

1. "MyAdd" — function name visible to CAPL
2. (CAPL_FARCALL)MyAdd — function pointer
3. "long" — return type string (tells CAPL the return type)
4. "long a, long b" — parameter types string (tells CAPL the argument types)
5. CAPL_DLL_CDECL — calling convention (use the macro from the sample project)
6. 0 — reserved
7. CDLL_EXPORT — export flag

The { 0, 0 } entry MUST be the last entry — it is the table terminator.

Step 4: Compile with Correct Settings

Note: The reference document mentions /MT (static CRT) as an option to avoid

needing VC++ redistributable on target machines. This works BUT beware:

• Memory allocated in DLL cannot be freed by CANoe, and vice versa
• For simple DLLs this is fine; for DLLs that pass dynamic memory, use /MD

Step 5: Load DLL in CANoe

1. Open CANoe configuration
2. Menu: Configuration → Programming → CAPL DLL (or Options → CAPL → DLL)
3. Add → select your .dll file
4. Recompile the CAPL node
5. Check CAPL Browser / Functions list — your function should appear

Step 6: Call from CAPL

on key 't'
{
  long ret;
  ret = MyAdd(10, 20);
  write("MyAdd(10,20) = %d", ret);
}

Supported Parameter Types in CAPL_DLL_INFO4

For arrays/buffers, always pass the length as a separate long parameter:

long ProcessData(unsigned char* data, long len)
{
    if (data == 0 || len <= 0) return -1;
    /* process data[0] to data[len-1] */
    return 0;
}

Common Pitfalls

See references/capl_pitfalls.md for the full list with explanations.

Reference Files

• references/capl_pitfalls.md — Detailed pitfall explanations and corrections
• references/capl_test_templates.md — Reusable test case templates for UDS/security
• references/capl_dll_guide.md — DLL compilation and CAPL_DLL_INFO4 integration guide

When Receiving CAPL-Related Queries

1. Always verify syntax against C89 constraints before providing code examples
2. Use PascalCase for all Test Module function names
3. Place all variable declarations at the top of each block
4. Reference references/capl_pitfalls.md when user reports a CAPL error
5. For UDS diagnostic flows, use the templates in references/capl_test_templates.md
6. For DLL questions, emphasize: use the official sample project, register in CAPL_DLL_INFO4 table[], do NOT rely on __declspec(dllexport) alone