CALL

What it does

CALL(register_id, [argument1], ...)

CALL is not a function in the sense the rest of this Handbook uses the word. It is a hole in the function surface: an escape from Excel's evaluator into arbitrary native code in a DLL. It has no mathematical definition, no domain, and no result kind of its own. What it returns is whatever the code at the far end returns, marshalled back through a caller-declared type string.

Nothing, in its own right. CALL marshals its arguments into a native call, invokes the procedure, and marshals the return value back into a worksheet value. The "semantics" of a CALL cell are the semantics of the DLL entry point.

The seam has two forms, and knowing which one you are looking at is the first step in reading any CALL formula:

CALL(register_id, [argument1], …)                      -- pre-registered
CALL(module_text, procedure, type_text, [argument1], …) -- self-describing

Arguments

• register_id — a value returned by a previously executed REGISTER or REGISTER.ID. Not a name, not a handle you can construct: an opaque token produced by this session.
• module_text — quoted text naming the DLL containing the procedure. Microsoft's page qualifies this as the Windows form; the function is documented as having a different shape on other environments.
• procedure — the function's name within the DLL, or its ordinal value. Microsoft's wording is that the ordinal is used "not [in] text form" — so this argument position accepts two different kinds of value with different meanings, which is the position most often gotten wrong.
• type_text — text specifying the return data type and the data types of all arguments, with the first letter specifying the return value. This is the load-bearing argument and the dangerous one. Microsoft's page as fetched does not include the full type-code table; the codes are documented in the Excel C API / XLL developer documentation rather than in the worksheet-function reference.
• argument1, … — optional; the values passed through to the procedure.

Try it

This Excel interface needs a host library. OneCalc cannot load a native library in this preview.

Quirks

The danger, stated once and plainly

Microsoft's own page leads with a caution, and this page will too. CALL transfers control to native code with no type checking beyond a string the caller wrote. If type_text does not match the callee's actual signature, arguments are marshalled wrongly and the process may read or write memory it does not own. Microsoft's wording: the function "is provided for advanced users only", and using it incorrectly "may cause errors that will require you to restart your computer".

Three specific properties make this worse than an ordinary foreign-function interface:

1. The contract is a string in a cell. type_text is data, not a compiled declaration. Nothing validates it against the DLL. A one-character error is a memory-safety bug.
2. The DLL is named by a string too. module_text is resolved by the operating system's library search, so which file actually loads depends on the machine, not the workbook.
3. It is reachable from a document. A spreadsheet is a document users open casually. CALL is the mechanism by which a document can execute native code, which is precisely why Excel confines it (see below) and why it is disabled or blocked in modern configurations.

The Handbook states this as documented risk and design consequence, not as an observation of a particular Excel build's current defenses, which it has not measured.

Result and edge cases

Whatever the callee returns, converted according to the first letter of type_text. The value-universe chapter's raw function return boundary is exactly the boundary this function sits on: an add-in procedure may hand back things — including the C API's empty/"nil" token — that a published formula result cannot hold, and a normalization step stands between the two. See the value universe, where that raw-versus-published gap is recorded as empirically pinned by add-in probes.

The most important structural constraint is a confinement one. Microsoft states that CALL "is only callable from Excel macro sheets" — it is not a general worksheet function, despite appearing in the function catalog. It is also documented as not available in Excel for the web, while being listed for Windows, Mac, iPad and Android.

Errors

Microsoft's page documents no error-value table for CALL. There is a reason for that which is worth stating rather than glossing: the failure modes of CALL are not, mostly, worksheet errors. A mismatched type_text does not produce #VALUE! — it produces undefined behaviour in the process. The error surface of this function is the operating system's, not Excel's.

What the shared model does say: an error value arriving as an argument propagates through coercion unless a function declares otherwise (see coercion and lifting), and CALL's recorded error_collapse_profile is None, meaning no special folding. That is an engine-level statement about the wrapper, not a claim about what a DLL does with what it receives.

How to implement

Notes for implementers

• type_text is a miniature type language, and its exact code set is part of the C API rather than the worksheet function surface. Any faithful implementation must reproduce that language, not invent an equivalent.

Rust code

This entry has no Rust implementation yet.

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• REGISTER.ID — the other half of the seam, and the only other member of call_register_id_family. REGISTER.ID produces the token; CALL consumes it. The two pages should be read together.
• REGISTER — the macro-sheet function that performs registration with full naming (and which, unlike REGISTER.ID, cannot be used on a worksheet). It does not appear in this Handbook's catalog of worksheet functions; it is named here because CALL's first syntax form refers to it.
• UNREGISTER — the teardown counterpart, likewise a macro-sheet function.
• EUROCONVERT — a category-mate ("User defined functions that are installed with add-ins") but nothing like it in kind: EUROCONVERT is arithmetic that happens to ship in an add-in, whereas CALL is the mechanism by which foreign code becomes callable at all.
• XLL add-in functions generally — every custom function registered by an XLL arrives through this same C API registration machinery. CALL is that machinery exposed as a formula.

Readers confuse CALL with VBA's Application.Run and with Declare statements. Those are VBA-level constructs with VBA's own marshalling; CALL is the worksheet/macro-sheet route into the C API, and its type system is the C API's.

Named variants

No named variants are recorded yet.