Configuring SAPI S7 ex1.exe for S7-300: VFD and C++ Guide

Overview

The SAPI S7 (S7 Application Programming Interface) is the C/C++ programming interface shipped with SIMATIC NET PC Software that allows custom Windows applications to communicate with Siemens S7 CPUs over MPI, PROFIBUS, or Industrial Ethernet. The bundled sample ex1.exe is a minimal read/write demonstration that links against s7onlinx.dll / W95_s7.dll and is the recommended starting point for any C++ developer building SCADA bridges, data loggers, or test harnesses against an S7-300, S7-400, or ET 200S station.

This reference covers:

• Locating the Device name and VFD name that ex1.exe prompts for at startup.
• Why PLCSIM (V5.4 + SPx and earlier) cannot be used as the target CPU.
• Hardware selection: USB PC Adapter (MPI/PROFIBUS) vs. CP 5512 (PCMCIA).
• SIMATIC NET configuration required before Visual Studio 2005/2008 can call the API.
• Building the sample with Visual C++ and verifying a successful cyclic read.
• An alternative path via the SIMATIC NET OPC server when the SAPI S7 route is not viable.

Prerequisites

The Device Name and VFD Name: What ex1.exe Asks For

When ex1.exe is launched it prints a console prompt similar to:

Enter device name (e.g. "S7ONLINE"):
Enter VFD name     (e.g. "M_PN_IO" / "M_DP_MASTER"):
Enter variable name:

Both identifiers come from the SIMATIC NET Configuration Console (Start → SIMATIC → SIMATIC NET → Configuration Console) and from the S7 connection editor inside STEP 7. They are not invented by the application; they are properties of the S7 connection you authored.

Device Name

The Device name in SIMATIC NET is the symbolic name of the PC interface module, not the PLC station. It is defined in the Configuration Console → Modules tree and appears as the access point of the application. By default the access point S7ONLINE is bound to the first active PC module. Common values:

• S7ONLINE – default for STEP 7 and most SAPI S7 examples.
• CP5512.PROFIBUS.1 – explicit PCMCIA CP 5512, MPI/PROFIBUS port 1.
• CP5611.PROFIBUS.1 – PCI CP 5611 PROFIBUS port 1.
• [email protected] – Industrial Ethernet via CP 1613.

VFD Name (Virtual Field Device)

The VFD is the PROFIBUS DP concept ported into the SAPI S7 layer: a logical namespace inside a station that owns a set of variables/slots. In Configuration Console → Stations → [Your S7-300] → S7 Connection the VFD column lists the type of model the S7 connection was configured for. Typical values:

To read the exact VFD string bound to a given connection, open SIMATIC Manager → NetPro → right-click S7 connection → Object Properties → General. The Interface field shows the bus type and the Station field shows the S7-300 station name configured in NetPro (e.g. S7300_PC_LINK). The VFD itself is taken from the PC side and matches the bus profile selected in SIMATIC NET Configuration Console → Access Points.

Why PLCSIM Cannot Be Used as a SAPI S7 Target

PLCSIM emulates the S7 CPU entirely in software on the engineering workstation, but it does not virtualise a PROFIBUS DP or MPI/Industrial Ethernet interface at the SAPI/CP layer. The SAPI S7 transport relies on a real s7onlinx routing path that terminates in a W95_s7.dll driver bound to a CP (CP 5512, CP 5611, CP 1613, etc.). PLCSIM only implements the internal S7 protocol used by STEP 7's online functions and has no exposed DP or PN interface for the SAPI layer.

Consequences for the developer:

• Symptoms when targeting PLCSIM: ex1.exe reports S7DLL_ERR_CONNECT (hex 0xFF10) after the connect timeout (default 10 s) or the S7 connection status in Configuration Console reads “No partner reachable”.
• The S7 online functions inside STEP 7 do work against PLCSIM because they use a different transport (S7DOS/SCANNER) that is built into the PLCSIM service.
• Software-only alternatives to PLCSIM that do work with SAPI S7: SIMATIC NET S7-PLCSIM Coupling (added in 2010 SP2) or third-party soft-PLCs such as S7-PLCSIM Coupler and ACCON-S7-Simulator. These present a virtual CP rather than a virtual CPU.

Hardware Selection: PC Adapter USB vs CP 5512

For the S7-300 313C-2DP on a single-segment MPI network, the PC Adapter USB at 187.5 kbps is the simplest path. The CP 5512 is preferred only when PROFIBUS DP at 1.5/12 Mbps is required, or when an ExpressCard/PCMCIA-equipped laptop is still in use.

SIMATIC NET Configuration

Before ex1.exe can connect, the PC side must declare the CP as the S7ONLINE access point and the S7-300 must be reachable on the bus. Walk through the steps below in order.

1. Install SIMATIC NET PC Software with the SIMATIC NET Configuration and S7 Communication components selected. Restart.
2. Open Configuration Console (Start → SIMATIC → SIMATIC NET). In the left tree expand Modules; your CP must appear with a green status icon.
3. Right-click Access Points → S7ONLINE → Properties. In the Assigned interface dropdown select the CP (e.g. CP5512(PROFIBUS) or PC Adapter(PROFIBUS)). Click Apply. This step is the single most common cause of ex1.exe returning 0xFF20.
4. Set the CP's own station address: Modules → CP5512 → Properties → PROFIBUS. For a PC acting as a DP master the typical address is 0; for MPI use 0 as well (PG address).
5. In STEP 7 / NetPro, configure the S7-300 station with MPI address 2 (or PROFIBUS address 2 if using PROFIBUS). Add an S7 connection from the PC station to the S7-300, set the connection type to S7 Connection, and assign the partner address to 2.
6. Compile and download the PC station and the S7-300 station. Verify the connection status with SIMATIC NET → Commissioning → Connections; status should read “established”.

Visual Studio C++ Integration

Once the bus is healthy, the C++ side must be told where the SAPI S7 headers and import libraries live.

1. Open SIMATIC NET Quick Start CD (Start → SIMATIC → SIMATIC NET → Documentation) and copy the SAPI_S7 sample directory to your working folder.
2. In Visual Studio 2005, open ex1.sln. Right-click the project → Properties → C/C++ → Additional Include Directories and add:

   C:\Program Files\Siemens\Automation\SIMATIC_NET\API\S7\INC

3. Under Linker → Additional Library Directories, add:

   C:\Program Files\Siemens\Automation\SIMATIC_NET\API\S7\LIB

4. Under Linker → Input → Additional Dependencies, add:

   W95_s7.lib s7onlinx.lib

5. Build the project in Release configuration, platform Win32. The output ex1.exe must be placed in a directory from which the SAPI DLLs are reachable. The simplest fix is to copy W95_s7.dll, s7onlinx.dll, and s7onasn.dll from ...\SIMATIC_NET\API\S7\BIN into the same folder as ex1.exe, or to add that BIN path to the system PATH.

Anatomy of the ex1 Source

The sample performs the canonical SAPI S7 sequence:

// Excerpt from ex1.c (SIMATIC NET 2008 sample, simplified)
S7_DEVICE  s7Device;
S7_DATETIME dt;
S7_RESULT  rc;

rc = S7SetDevice("S7ONLINE", &s7Device);
if (rc != S7DLL_OK) { printf("SetDevice failed 0x%04X\n", rc); return 1; }

rc = S7Connect(&s7Device, "S7ONLINE", "M_DP_MASTER", 2 /* MPI addr */);
if (rc != S7DLL_OK) { printf("Connect failed 0x%04X\n", rc); return 1; }

rc = S7ReadSZL(&s7Device, 0x0131, 0, &szlBuf, sizeof(szlBuf), &len);
// SZL 0x0131 = "Module identification" — useful first read to confirm the path

Replace "M_DP_MASTER" with the VFD you recorded from NetPro, and the second argument of S7Connect with the partner's MPI/PROFIBUS address (here 2).

Building, Running and Verifying

1. Launch SIMATIC NET Configuration Console and confirm S7ONLINE is bound to the active CP.
2. From a command prompt with the BIN path on the environment, run ex1.exe.
3. When prompted, enter:

   Device name : S7ONLINE
   VFD name    : M_DP_MASTER   (or MPI / M_PN_IO depending on connection)
   Variable    : DB1.DBD0      (any DB and byte offset that exists in the S7-300)
   

4. Expected output on success:

   Connection established to S7-300 station "S7300_PC_LINK".
   Value of DB1.DBD0 = 0x00000000 (0)
   Read elapsed: 12 ms
   

5. Set a non-zero value from STEP 7 (VAT table) and re-run; the read should reflect it within one cycle.

Diagnostic Checklist

Troubleshooting Matrix

Alternative Path: SIMATIC NET OPC Server

If the SAPI S7 route proves unstable — typically because PLCSIM is the only CPU available, or because the developer lacks a C++ toolchain — Siemens ships an OPC server that fronts the same bus and can be exercised from any language that supports COM automation (C#, Python via opcua after wrapping, LabVIEW, MATLAB, Excel).

1. In Configuration Console, enable OPC Server (SIMATIC NET ships the package as OPC.SimaticNET).
2. Start OPC Scout V10 (Start → SIMATIC → SIMATIC NET → OPC Scout). Add a new group, browse the server's namespace down to the S7-300 station, and add an item (e.g. S7:[S7300_PC_LINK]DB1,BYTE0).
3. Subscribe to the group; updates arrive at the configured update rate (default 100 ms).

This approach is documented in the Siemens FAQ How do you configure an S7 connection for the SIMATIC NET OPC server? and is the recommended teaching example in the SIMATIC NET Quick Start CD.

Field-Proven Caveats

• One access point, one CP. If your PC has two CPs, only the one bound to S7ONLINE is used by SAPI S7. To target a second bus, create a second access point (e.g. S7ONLINE_2) and pass it explicitly to S7SetDevice.
• 32-bit only. W95_s7.dll has no 64-bit build. On 64-bit Windows, run ex1.exe as a 32-bit process or rebuild against the IA64/AMD64-aware successor (SAPI S7 was extended in SIMATIC NET 2010 SP2 for x64). Newer projects should use the .NET wrapper S7.NET or the open-source Snap7 library which compiles natively for x64.
• Security context. The SAPI S7 service runs under the local system account by default. Custom applications calling it from a non-admin user need the ACLs configured in Configuration Console → Access Settings.
• Firmware levels. An S7-300 with firmware < V2.0 may reject the SZL 0x0131 read with 0xFF31. Update CPU firmware to the latest revision on the Siemens support site before chasing phantom driver bugs.
• Bus profile drift. After changing the CP's PROFIBUS profile (e.g. from 1.5 Mbps to 12 Mbps), the S7-300 must be power-cycled before the new profile is accepted. PLCs in RUN do not renegotiate the bus speed online.