Resolving WinCC uaQueryArchiveByName Error 101 on Client Stations

Problem Overview

On a distributed WinCC V6.x / V7.x runtime system, a C-action that opens a User Archive (UA) by name on the server returns the expected archive handle, while the identical C-action executed on a WinCC client station fails immediately with:

Error calling uaQueryArchiveByName: 101

The error is raised by the WinCC UA C-API after a successful uaConnect() (no NULL pointer is reported for hConnect), which proves that the client did establish a session with the WinCC data manager, but the subsequent archive lookup cannot resolve the archive name "Incoming" against any archive that is locally known to the client runtime. Error code 101 in the WinCC UA API maps to UA_ERROR_INVALID_ARCHIVE_NAME / archive not found in client context, the typical signature of a client that has not been told which server package owns the requested archive.

This failure mode is exclusive to the WinCC client side and is the documented consequence of the WinCC multi-station architecture: components that are not delivered through a server prefix refer to the Standard Server that is configured for that component on the client. When no Standard Server is assigned or the assignment does not include the User Archive component, the client attempts to read its local data store. Because the client has no local User Archive database, the API returns 101 instead of opening a remote archive.

WinCC User Archive Architecture in Distributed Projects

WinCC User Archives are designed to run only on the server that owns the archive database. The WinCC client never holds a copy of the archive; it only receives a view of the data when a server data package is loaded onto the client and the component is bound to that server. The relevant WinCC UA reference, the WinCC User Archives manual, states that the User Archives editor is opened from the WinCC Control Center on the server project and that the resulting archive configuration is published to clients through the Server Data editor.

Three architectural rules must hold for a client C-action to read or write a User Archive:

1. The server project must publish a Server Data package that includes the User Archives component. The package name is the symbolic prefix that clients use to address server-owned data.
2. The client project must reference that package (load it during compile/download) so that the archive name Incoming exists in the client's name resolution table.
3. The client must bind the User Archive component to the server via Standard Server on the client. Components without an explicit Standard Server attempt to read from local data; without a local UA store, the call fails with error 101.

If the C-action uses the unqualified name "Incoming", WinCC looks for the archive in the client's own (non-existent) UA database. If the C-action uses the qualified form "<package>::Incoming", WinCC routes the call through the server prefix and the lookup succeeds.

Root Cause Analysis

The failure is caused by name resolution scope, not by an authentication or RPC issue:

The asymmetry is the diagnostic fingerprint: WinCC Controls bound to User Archives automatically use the Standard Server. The C-API does not perform that auto-binding unless the developer uses the qualified name. The discrepancy between control success and script failure is therefore not a runtime bug - it is a binding omission.

Error Code 101 in the WinCC UA C-API

The WinCC UA C-API (declared in apdefap.h / UAHArchive.h) returns negative or positive integers from uaGetLastError(). The value 101 falls in the archive-not-found cluster:

Code 101 is informational, not fatal: the connection handle remains valid, so the script can safely continue after correcting the lookup path and retrying.

Resolution Strategy: Two Configurable Levers

There are two independent fixes; both are required in most sites because they address complementary failures.

Lever 1 - Configure the Standard Server for the UA Component on the Client

Open the client project in the WinCC Explorer. In Server Data, locate the UA component. For each archive used by the client, set the Standard Server to the name of the WinCC server (must match the computer name registered in WinCC). Without this assignment, components that do not have a server prefix default to the client local data store, which has no UA database.

Lever 2 - Prefix the Archive Name with the Server Data Package

The WinCC UA C-API accepts a fully qualified name in the form:

<ServerDataPackageName>::<ArchiveName>

The server data package name is the symbolic name shown in the WinCC Explorer under Server Data. If the project was compiled with package name server_project and the archive is Incoming, the qualified call is:

uaQueryArchiveByName(hConnect, "server_project::Incoming", &hArchive)

The :: separator is a hard-coded WinCC UA syntax token. It is the same prefix used by WinCC Controls internally; explicit use in C-scripts restores the binding that the control layer provides automatically.

Corrected C-Action Script

The following script is the production-ready form of the original C-action. It demonstrates the connect / open / read / disconnect sequence and embeds the server prefix that resolves error 101:

#include "apdefap.h"

void OnClick(char* lpszPictureName,
             char* lpszObjectName,
             char* lpszPropertyName)
{
    UAHCONNECT hConnect = 0;
    UAHARCHIVE hArchive = 0;
    char szFilter[256] = {0};
    char szTemp[32]    = {0};
    BOOL  bOk          = FALSE;
    DWORD dwErr        = 0;
    long  lRowCount    = 0;
    SYSTEMTIME st;

    /* ---- 1. Connect to the local WinCC data manager ---- */
    if (uaConnect(&hConnect) == FALSE)
    {
        printf("Error calling uaConnect: %lu \n",
               (unsigned long)uaGetLastError());
        return;
    }
    if (hConnect == 0)
    {
        printf("Handle UACONNECT equals 0\n");
        return;
    }

    /* ---- 2. Open archive by qualified name ----
     *     Syntax:  "<ServerDataPackageName>::<ArchiveName>"
     *     Example: "server_project::Incoming"
     */
    if (uaQueryArchiveByName(hConnect,
                             "server_project::Incoming",
                             &hArchive) == FALSE)
    {
        dwErr = uaGetLastError();
        printf("Error calling uaQueryArchiveByName: %lu \n",
               (unsigned long)dwErr);
        uaDisconnect(hConnect);
        return;
    }

    /* ---- 3. Build a filter (date example) ---- */
    GetSystemTime(&st);
    sprintf(szTemp, "%04d-%02d-%02d",
            st.wYear, st.wMonth, st.wDay);
    sprintf(szFilter, "Date >= '%s'", szTemp);

    /* ---- 4. Query rows ---- */
    if (uaQueryArchive(hArchive, szFilter) == FALSE)
    {
        printf("Error uaQueryArchive: %lu \n",
               (unsigned long)uaGetLastError());
    }
    else
    {
        lRowCount = uaGetRowCount(hArchive);
        printf("Rows returned: %ld \n", lRowCount);
    }

    /* ---- 5. Clean up ---- */
    uaDisconnect(hConnect);
    return;
}

MultiClient Package Generation Procedure

The discussion above presupposes that the server data package exists on the client. If the client was never packaged, the prefix cannot resolve and error 101 will persist regardless of the script content. Generate and load the package with the following procedure.

1. On the WinCC server, open the WinCC Explorer and select Server Data. Right-click and choose Create / Update Server Data. Confirm the package name (the default is the server computer name, for example server_project).
2. Wait until the generator finishes; the package file (extension *.dcf for V6 or *.pck for V7) is written to the project path.
3. On the client, open the client project in the WinCC Explorer. In Server Data, right-click and choose Load. Point to the generated package.
4. Restart the WinCC client runtime. Without a runtime restart, the package is registered but not active.
5. Re-test the C-action. The uaQueryArchiveByName call should now succeed.

Verification Procedure

Confirm the fix using three independent checks before closing the incident.

Check 1 - Diagnostic Output

Run the C-action on the client and read the WinCC diagnostic output (APDIAG output window, WinCC Explorer -> Tools -> Diagnostic Output). The line Rows returned: N with N > 0 confirms successful binding. If the output shows Error calling uaQueryArchiveByName: 101, the prefix is still wrong or the package was not loaded.

Check 2 - WinCC Online Help Trace

Enable the UA trace from the WinCC Control Center: Computer -> Properties -> Graphics Runtime -> Diagnostics. Re-run the script. The trace records the qualified name that the runtime resolved; confirm that the package prefix matches what is in Server Data on the client.

Check 3 - Component Binding Audit

In WinCC Explorer on the client, expand Server Data, expand the loaded package, expand User Archives, and verify the Incoming archive is visible. If it is greyed out or missing, the server data package was not regenerated after the archive was added on the server. Repeat step 1 of the MultiClient procedure.

Installation-Specific Caveats

The original incident originated from a PCS7 installation. PCS7 installs WinCC as a sub-component and adds WinCC Options (including User Archives) through the PCS7 setup. If the WinCC Options were installed in a non-default order, the User Archive runtime may be registered but the UA C-API may be missing from the client. Verify on the client with:

1. Open Control Panel -> Add/Remove Programs on the client.
2. Confirm that WinCC User Archives appears as an installed component on the client. The license is required only on the server; the runtime DLLs (UAHApi.dll) must be present on both stations for the C-API to resolve.
3. If the UA option is missing, run the WinCC setup, choose Modify, and add User Archives. A reboot is required after installation.

Verify the DLL presence directly:

dir "%ProgramFiles%\Siemens\Automation\WinCC\bin\UAHApi.dll"

If the file is absent, the C-action cannot link against the API; the compiler succeeds because the headers are present, but the runtime returns 101 at the first call.

Related Errors and Edge Cases

WinCC V7 and TIA Portal Considerations

The qualified-name mechanism is preserved in WinCC V7 and in TIA Portal WinCC Professional, but the API surface is split between the legacy C-API (still supported for compatibility) and the modern RT Professional OLE DB Provider. The Query for User Archives (RT Professional) reference documents the SQL-based access path that supersedes the C-API for new development.

For new projects the recommended pattern is to query the UA through OLE DB using a connection string such as:

Provider=WinCCOLEDBProvider.1;Catalog=CC_<ProjectName>_<TimeStamp>;Data Source=<ServerName>\WinCC

Followed by a parameterized SELECT against the user archive table. The OLE DB path automatically uses the Standard Server binding and does not require the manual :: prefix. For legacy WinCC V6.0 / V6.2 sites, however, the C-API remains the only supported runtime API; the prefix-based fix documented in this article is the canonical resolution.

Frequently Asked Questions