简介面向使用 C 处理测试测量数据的开发者这份文档围绕 C 对 TDMS含 TDM文件的读写展开帮助读者在数据采集、自动化测试等场景中绕开格式转换的繁琐直接调用 NI 官方 DDC 库完成文件级操作。文中以 writeDDCFile 与 ReadDDCFile 两个完整函数为主干串起 DDC_CreateFile、DDC_AddChannel、DDC_SetDataValues、DDC_SaveFile 的写入链路以及 DDC_OpenFile、DDC_GetNumChannels、DDC_GetDataValuesDouble 的读取链路并提示新增通道时名称参数必须唯一、否则会相互覆盖这类易踩的细节。作者还记录了 TDM 与 TDMS 的实测差异同等通道数与数据长度下文件体积接近TDMS 写入耗时却接近 TDM 的两倍通道数升至万级时写入时间明显增加写盘前需为第三方库的中间文件预留数倍空间。压缩包内为 1 个 doc 文件约 20KB体量轻便已有 996 人学习下载适合想快速上手 TDMS 读写接口的初中级开发者查阅。1. 从一份采集程序说起C 读写 TDMS 到底难在哪做振动采集上位机的同行多半遇到过一个场景128 个通道、每通道 102400 个采样点存成 CSV 要一百多兆Excel 打不开文本解析一遍要十几秒还丢精度。换成 TDMS 之后同一批数据落到磁盘上还是一百兆出头但带上索引之后第二次读明显变快。这就是为什么做科学计算和数据采集的 C 程序绕不开 TDMS 这个格式。这里整理的是用 C 加一套 C 风格接口库读写 TDM/TDMS 的完整实例从创建文件、加通道组、灌数据到打开、遍历、取值两条链路都有可编译的骨架。适合谁读正在给测试台架写数据落盘模块的 C 开发、要从上位机导出数据给分析端的人、以及被 CSV 拖慢过的人。看完至少能跑通也大概知道哪几行最容易出事。2. 接口全景DDC 库把 TDM/TDMS 拆成了哪几层对象这套库是纯 C 接口头文件一进来就是一堆DDC_前缀函数第一眼会觉得函数多得让人头疼。实际上它的对象模型只有三层半理清楚之后读写两条链路都只有七八步。2.1 文件—通道组—通道的三层句柄模型TDMS 的逻辑结构是严格的树形一个文件下面挂若干通道组group每个组下面挂若干通道channel每条通道下面才是真正的采样点数组外加一串属性键值对property。在 C 接口里这三层各对应一个不透明句柄类型层级句柄类型主要 API文件DDCFileHandleDDC_CreateFile/DDC_OpenFile/DDC_SaveFile/DDC_CloseFile通道组DDCChannelGroupHandleDDC_AddChannelGroup/DDC_GetChannelGroups/DDC_GetNumChannels通道DDCChannelHandleDDC_AddChannel/DDC_SetDataValues/DDC_GetDataValuesDouble属性无独立句柄DDC_SetChannelProperty/DDC_GetChannelGroupProperty所谓句柄本质上就是个void*里面包着库自己维护的结构体调用方不要去看也不要自己释放只能通过DDC_CloseFile或者库提供的销毁函数交回去。所有 API 的返回值都是int状态码0 表示成功非 0 要立刻查错误信息把错误吞掉的后果后面会讲。另一个必须先记住的是数据类型枚举。写入时DDC_AddChannel的第二个参数决定了这条通道的数据类型后续取值函数必须与之匹配枚举对应 C 类型取值函数DDC_DoubledoubleDDC_GetDataValuesDoubleDDC_SinglefloatDDC_GetDataValuesFloatDDC_I32int32_tDDC_GetDataValuesInt32DDC_I16int16_tDDC_GetDataValuesInt16DDC_String字符缓冲DDC_GetDataValuesString常见做法是采集端一律写DDC_Double分析端读之前先调DDC_GetChannelType判断真实类型再分发到对应函数别想当然地拿DDC_GetDataValuesDouble去读一条DDC_I16的通道——有的版本会返回错误码有的版本会给你一堆零这种玄学问题排查起来能耗掉半天。2.2 写入链路的七步调用顺序写入的最小闭环踩在七个点上顺序不能乱创建文件、加组、加通道、设数据、可选写属性、保存、关闭。骨架长这样// 最小写入骨架文件 - 组 - 通道 - 数据 - 保存 - 关闭 int WriteMinimal(const char* path, const double* data, size_t len) { DDCFileHandle file nullptr; // 1. 创建文件第二个参数决定是 TDM 还是 TDMS int rc DDC_CreateFile(path, TDMS, 采集数据, test, 标题, 说明, file); if (rc ! 0) return rc; DDCChannelGroupHandle group nullptr; // 2. 加通道组第三个参数是描述可以留空 rc DDC_AddChannelGroup(file, group01, 振动信号, group); if (rc ! 0) { DDC_CloseFile(file); return rc; } DDCChannelHandle ch nullptr; // 3. 加通道类型、名字、描述、单位名字在同组内必须唯一 rc DDC_AddChannel(group, DDC_Double, ch0, , m/s2, ch); if (rc ! 0) { DDC_CloseFile(file); return rc; } // 4. 一次把整段数据塞进去第三参数是点数 rc DDC_SetDataValues(ch, data, static_castunsigned __int64(len)); if (rc ! 0) { DDC_CloseFile(file); return rc; } // 5. 保存才会真正把内存里的数据落到磁盘 rc DDC_SaveFile(file); // 6. 关闭句柄无论保存成功与否 DDC_CloseFile(file); return rc; }参数里最容易被忽略的是DDC_CreateFile的第三个到第六个参数。它们分别是文件描述、文件名、标题、标题描述写进文件头里用来存实验条件、采样率、设备编号这类元信息。很多人图省事全传空串结果半年后拿到一个data.tdms完全不知道它是什么工况下采的只能从文件名去猜。我现在的习惯是把采样率、量程、传感器编号都塞进属性里// 属性是 meta 信息的正解别往文件名里塞 DDC_SetChannelProperty(ch, SampleRate, DDC_Double, sampleRate, 1); DDC_SetChannelProperty(ch, SensorSN, DDC_String, SN-0001, 1);DDC_SetChannelProperty第三参数指定属性类型第四参数传地址第五参数是值的个数数组属性才用得上不是逗号分隔的值。属性会随文件一起存读的时候用DDC_GetChannelProperty取回来这是把数据交给别人时唯一靠谱的自解释手段。2.3 读取链路与类型取值读取链路看起来对称但比写入多两步——必须先拿到组句柄数组和通道句柄数组才能往下遍历。完整的调用次序是// 读取骨架打开 - 拿组 - 拿通道 - 拿长度 - 取值 DDCFileHandle file nullptr; DDC_OpenFile(path, TDMS, file); // 1. 打开格式要对上 unsigned int groupCount 0; DDC_GetNumChannelGroups(file, groupCount); // 2. 先问数量 std::vectorDDCChannelGroupHandle groups(groupCount); DDC_GetChannelGroups(file, groups.data(), groupCount); // 3. 再取句柄数组 for (unsigned int i 0; i groupCount; i) { unsigned int chCount 0; DDC_GetNumChannels(groups[i], chCount); std::vectorDDCChannelHandle chans(chCount); DDC_GetChannels(groups[i], chans.data(), chCount); // 组内同理 for (unsigned int j 0; j chCount; j) { unsigned __int64 len 0; DDC_GetNumDataValues(chans[j], len); // 4. 单通道点数 std::vectordouble buf(len); DDC_GetDataValuesDouble(chans[j], 0, len, buf.data()); // 5. 起止索引 } } DDC_CloseFile(file);第 3 步的DDC_GetChannelGroups是整条链路的关键它负责把上一步问到的数量填成真正的句柄。原始示例代码里正好漏了这一步直接拿未初始化的数组往下走后面会专门讲这个坑。DDC_GetDataValuesDouble的第二个参数是起始索引第三个是点数这样就能只取一段数据。做大文件浏览时不要一次读全量按窗口取几百兆的文件翻页不会卡。至于“多次访问后读取变快”这个现象原因是库内部维护了索引缓存第一次打开要扫一遍块索引后面命中缓存。这也带来一个副作用如果多个线程同时读同一个句柄缓存状态可能互相干扰正确做法是每个线程DDC_OpenFile一份自己的句柄。3. 写入实现拆解WriteDDCFile 里每一步在干什么原始的写入函数长这样去掉注释之后不到二十行但每一行都有说法int CTDMSTestDlg::WriteDDCFile(const char* filePath, int channelNum, int dataLen, const char* fileType /* TDM */) { DWORD begin ::GetTickCount(); DDCFileHandle testFile; DDC_CreateFile(filePath, fileType, , , , , testFile); // 创建指定格式的文件 DDCChannelGroupHandle group01; DDC_AddChannelGroup(testFile, group01, , group01); // 增加一个通道组 DDCChannelHandle* channels new DDCChannelHandle[channelNum]; double* channelData CreateRandomData(dataLen); for (int i 0; i channelNum; i) { char channelIdx[20]; itoa(i, channelIdx, 10); // 通道名 序号 DDC_AddChannel(group01, DDC_Double, channelIdx, , , channels[i]); // 注意每次增加通道时第三个参数值要不一样否则会覆盖 DDC_SetDataValues(channels[i], channelData, dataLen); // 为通道设置数据 } DDC_SaveFile(testFile); DWORD end ::GetTickCount(); DDC_CloseFile(testFile); delete[] channels; delete[] channelData; return end - begin; }3.1 创建文件与通道组参数到底落在哪DDC_CreateFile的七个参数依次是文件路径、格式字符串、文件描述、文件名、标题描述、标题、输出句柄。格式字符串只有TDM和TDMS两个合法值写错了会直接返回错误码路径用相对路径时是相对当前工作目录不是相对 exe 所在目录这一点在服务里跑的时候经常翻车——打包部署后工作目录变成了C:\Windows\System32文件就“消失”了。稳妥做法是先把相对路径转成绝对路径再传进去。DDC_AddChannelGroup只有三个有效参数文件的句柄、组名、描述。组名在同一文件内唯一重复添加同名组时库的行为是返回错误还是追加不同版本不一致别赌自己在业务层加个唯一性检查。描述建议写清楚这组数据代表什么工况比如工位3-空载-3000rpm对后期检索的价值远大于省下的那几十字节。3.2 通道名重复会覆盖这是最容易翻车的一行示例里用itoa把序号转成字符串当通道名还专门留了一行注释「每次增加通道时第三个参数的值要不一样否则会覆盖」。这句话是整段代码里最值钱的一行血泪经验。DDC_AddChannel的第三个参数是通道名当你在同一个组里第二次用同名调用它时库并不会给你新建一条通道而是把已有那条的句柄还给你接着DDC_SetDataValues就把原数据盖掉了。表现出来就是明明写了 128 个通道读回来只有 1 个且数据是全零或者某一条的重复。围绕这一行还有三个衍生问题。第一char channelIdx[20]配itoa只够撑到二十位十进制通道数上千之后名字会变长得换成snprintf(channelIdx, sizeof(channelIdx), ch_%05d, i)定长命名还方便后期按名字排序。第二itoa不是标准 C 函数跨编译器比如换到某个 Linux 工具链直接编不过用std::to_string或snprintf更省事。第三通道名里不要放空格和点号某些解析工具会把它们当成层级分隔符处理。如果要做“追加写入”注意DDC_AddChannel对已存在通道的处理和新建不同拿到句柄后调DDC_AppendDataValues才是追加语义DDC_SetDataValues永远是覆盖。这两个函数名长得像用错方向就是一次数据丢失。3.3 计时的坑GetTickCount 包不住保存示例统计耗时的方式是GetTickCount()取开始和结束然后end - begin。三个问题其一GetTickCount返回 32 位毫秒连续运行四十多天会回绕归零做长时间稳定性测试时算出来的耗时会变成负数其二示例里end取在DDC_SaveFile之后、DDC_CloseFile之前关闭文件本身也有磁盘抖动开销尤其在网络盘上其三毫秒精度测小文件根本不够看128 通道 10 万点的写入耗时可能几百毫秒误差能到 10%。我一般换成std::chrono::steady_clock并且把DDC_CloseFile也纳入统计区间auto t0 std::chrono::steady_clock::now(); // ... 创建、加通道、设数据、保存 ... DDC_CloseFile(file); auto ms std::chrono::duration_caststd::chrono::milliseconds( std::chrono::steady_clock::now() - t0).count();3.4 TDM 和 TDMS 选哪个实测比文档靠谱两种格式的表层差异是TDM 由 XML 头和二进制数据组成索引和描述都是可读文本TDMS 从头到尾都是二进制没有 XML 段。官方材料里一般更推崇 TDMS理由是性能好、适合流式写。但拿同一份数据实测下来结论并不完全一致对比项TDMTDMS相同通道数、相同点数下的文件大小基本一致基本一致写入耗时较快约为 TDM 的两倍首次读取耗时接近接近多次读取耗时有索引缓存变快也变快但始终略慢于 TDM通道数固定、每通道点数固定时两者文件体积几乎没差别所以“TDMS 更省空间”这个说法在中小规模数据上并不成立。写入耗时上 TDMS 反而更慢这和它边写边维护块索引、要做更多的元数据落盘有关数据量越大差距越明显。读取侧两者都有索引第二次读都比第一次快差距在毫秒级。真正决定选型的是使用场景而不是绝对快慢如果程序是“一次性写完整段数据、事后交给分析端读”TDM 更划算XML 头还能让人拿文本编辑器直接看一眼通道结构如果是长时间连续采、边采边写、对断电后的可恢复性有要求TDMS 的分块追加语义更合适因为它的元数据也是二进制且按块组织中途异常时前面的块通常还能读出来。还有个规模问题要记住通道数增加到一万这个量级时写入耗时会有一次明显跳变不是线性的而单通道长度的增加和耗时基本是线性的。所以设计采集方案时宁可少通道、长缓冲也不要搞几千个短通道。4. 读取实现拆解ReadDDCFile 的骨架和它藏着的三个坑原始的读取函数是这段int CTDMSTestDlg::ReadDDCFile(const char* filePath, const char* fileType /* TDM */) { DWORD begin ::GetTickCount(); DDCFileHandle ddcFile; DDC_OpenFile(filePath, fileType, ddcFile); // 打开文件 unsigned int groupNum 0; DDC_GetNumChannelGroups(ddcFile, groupNum); // 获取通道组的数目 DDCChannelGroupHandle* groups new DDCChannelGroupHandle[groupNum]; for (int i 0; i groupNum; i) { unsigned int channelNum 0; DDC_GetNumChannels(groups[i], channelNum); // 获取通道的数目 DDCChannelHandle* channels new DDCChannelHandle[channelNum]; for (int j 0; j channelNum; j) { unsigned __int64 dataLen 0; DDC_GetNumDataValues(channels[j], dataLen); // 获取数据长度 double* data new double[dataLen]; DDC_GetDataValuesDouble(channels[j], 0, dataLen, data); for (int k 0; k dataLen; k) { data[k]; // 这里本该是业务处理 } } delete[] groups; // 在内层循环里释放外层数组 groups NULL; } DWORD end ::GetTickCount(); DDC_CloseFile(ddcFile); delete[] groups; return end - begin; }这段代码的骨架方向是对的但它不能直接跑。4.1 正确版本补齐句柄数组那一步问题出在groups[i]从来没被赋过值。DDC_GetNumChannelGroups只回答“有几个组”不负责给你组句柄拿到数量之后必须再调一次DDC_GetChannelGroups把句柄填进去组内的DDC_GetChannels同理。补全之后的版本int ReadAll(const char* path, const char* fileType) { DDCFileHandle file nullptr; int rc DDC_OpenFile(path, fileType, file); if (rc ! 0) { return rc; } // 打开失败就没有句柄可用 unsigned int groupNum 0; if (DDC_GetNumChannelGroups(file, groupNum) ! 0 || groupNum 0) { DDC_CloseFile(file); return -1; } std::vectorDDCChannelGroupHandle groups(groupNum); DDC_GetChannelGroups(file, groups.data(), groupNum); // 关键补齐 for (unsigned int i 0; i groupNum; i) { unsigned int channelNum 0; if (DDC_GetNumChannels(groups[i], channelNum) ! 0) continue; std::vectorDDCChannelHandle chans(channelNum); DDC_GetChannels(groups[i], chans.data(), channelNum); for (unsigned int j 0; j channelNum; j) { unsigned __int64 dataLen 0; if (DDC_GetNumDataValues(chans[j], dataLen) ! 0 || dataLen 0) continue; std::vectordouble buf(static_castsize_t(dataLen)); rc DDC_GetDataValuesDouble(chans[j], 0, dataLen, buf.data()); if (rc ! 0) continue; // 类型不匹配等错误在这里暴露 // ... 业务处理 buf ... } } DDC_CloseFile(file); return 0; }改法本身不复杂但要点在于每一层都先校验返回码再用句柄。这套 C 接口没有异常出错只能靠状态码rc ! 0那一行看着啰嗦省掉一次线上就是一次段错误。4.2 三处硬伤未取句柄、循环里删除、数据不释放把原始版本的错误挨个对一遍。第一处是groups[i]未初始化就被当参数传进DDC_GetNumChannels这个数组是用new申请但没初值的裸内存里面是随机垃圾传进去轻则返回错误码、重则库内部解引用野指针直接崩也就是那种“打开文件就闪退、日志一条没有”的黑匣子现场。第二处是delete[] groups被写在了for (i)循环体内的末尾紧接着又groups NULL然后下一轮迭代再delete[] groups此时是空指针还好但循环结束后函数末尾还有一次delete[] groups——同一个指针被释放两次堆直接损坏。正确位置只有一个循环全部结束、DDC_CloseFile之后。用std::vector就没这问题。第三处是new double[dataLen]之后从头到尾没有delete[]channels数组同样泄漏。读一个 128 通道 10 万点的文件泄漏就是 128 × 100000 × 8 字节约 100MB 一次。批量跑一百个文件进程内存就上去了。同样用std::vectordouble管理一出作用域自动回收。4.3 大文件的内存与分块策略dataLen的类型是unsigned __int64说明这套接口本身支持超过 4G 点数的通道。真按这个长度一次性new double[dataLen]12G 的数据文件就需要 12G 连续内存32 位进程完全没戏64 位进程也会因为内存碎片和物理内存上限直接失败。分块读取是必选项// 按 64K 点一块读内存占用恒定 const unsigned __int64 kChunk 65536; std::vectordouble buf(kChunk); for (unsigned __int64 offset 0; offset dataLen; offset kChunk) { unsigned __int64 n std::min(kChunk, dataLen - offset); DDC_GetDataValuesDouble(ch, offset, n, buf.data()); // 起止索引就是干这个的 // ... 处理 buf[0..n) ... }DDC_GetDataValuesDouble的第二个参数起始索引和第三个参数点数就是为分块设计的。块大小选 64K 点512KB是个折中太小的话函数调用和锁开销占比上升太大的话单次拷贝耗时长、UI 会卡。做进度条的话每块处理完更新一次128 通道 10 万点的文件基本感觉不到顿挫。5. 避坑清单磁盘留三倍、通道破万、句柄与时间统计这一章全是踩出来的。每条按现象、原因、解决三段走能对上号的直接抄。5.1 现象写到一半报磁盘空间不足一看目录里多了个巨大临时文件原因这套库保存时并不是直接在目标文件上原地写而是先落中间文件最后再合并成最终文件。中间文件的体积远大于成品实测 12G 左右的最终数据文件需要至少 32G 的可用空间才能顺利写完。空间不足时DDC_SaveFile返回非零但很多人没检查返回值以为写成功了实际只留下半截文件。解决落盘前先查一次可用空间按「预计数据量 × 3」做门槛判断不够就提前报错给上层别等写到 90% 才失败。中小数据量不用太焦虑128 通道、每通道 102400 点、成品约 100M 的场景中间文件也在可接受范围内。另外把中间目录配置到和成品同一个物理盘上跨盘合并会额外拉长保存时间。5.2 现象通道数从几百加到一万写入时间不是翻倍而是跳了好几倍原因通道数到一万量级时元数据条目本身的规模上来了库在保存时对通道索引的整理和后处理开销显著上升不再是线性关系。而单通道点数增加时耗时基本线性——数据段是顺序落盘的。这决定了“宽表”比“长表”更吃亏。解决重新设计通道划分。同一个传感器的三轴数据不要拆成三条通道可以合并成一条通道加属性说明或者按采集单元分组、每组控制在几百通道以内。真的是上万测点的场景考虑按时间段切成多个文件每个文件内部再分组把单个文件的通道数压下去。5.3 现象打开文件后第一行就崩或者读回来的通道数是天文数字原因就是上一章说的句柄未取、野指针解引用。也可能是DDC_OpenFile的格式参数和实际文件不符——文件是 TDMS参数传了TDM有的版本返回错误码有的版本返回 0 但句柄无效。解决所有DDC_调用后紧跟返回码判断打开文件后立刻用DDC_GetNumChannelGroups验证句柄可用格式参数不要写死默认值从文件扩展名推导或者干脆先用TDMS试、失败再用TDM重试一次。5.4 现象跑了几天以后耗时统计是负数或者内存一直涨原因时间统计用GetTickCount32 位毫秒在连续运行 49.7 天后回绕内存一直涨则是句柄和缓冲没有释放循环里的new配不上delete或者DDC_OpenFile成功后中途 return 忘了DDC_CloseFile。解决时间统一换std::chrono::steady_clock句柄用 RAII 包一层析构里调DDC_CloseFile缓冲一律std::vector。再加一条每个DDC_OpenFile对应且只对应一个DDC_CloseFile不要指望进程退出时系统帮你收库内部可能还有落盘动作没完成。5.5 一张排查表现象优先怀疑排查动作写入返回成功但读回空文件保存失败未判返回码 / 通道名重复被覆盖打印每步返回码检查组内通道名唯一性读回数据全零类型不匹配用 Double 读 Int16先DDC_GetChannelType再分发取值函数第二次读明显变快第三次又慢索引缓存失效 / 多线程共用句柄每线程独立DDC_OpenFile大批量读时进程被杀一次性分配整通道缓冲改分块读取块大小 64K 点部署后找不到输出文件相对路径基于工作目录统一转绝对路径6. 二次开发把 demo 改成能进采集流水线的模块这份示例代码最好的用法不是直接塞进工程而是当成协议参考。真要落地我一般做三件事包一层 RAII、抽出通道描述结构、写一个自校验的读写往返测试。RAII 那层很薄就是把句柄的关闭动作绑到析构上避免任何一条 return 路径漏掉// 极简 RAII句柄生命周期跟着对象走 class TdmsFile { public: explicit TdmsFile(const std::string path, const char* type TDMS) { rc_ DDC_OpenFile(path.c_str(), type, h_); } ~TdmsFile() { if (rc_ 0 h_) DDC_CloseFile(h_); } TdmsFile(const TdmsFile) delete; // 句柄不可拷贝 TdmsFile operator(const TdmsFile) delete; bool ok() const { return rc_ 0; } DDCFileHandle raw() const { return h_; } private: DDCFileHandle h_ nullptr; int rc_ -1; };通道描述建议抽成结构体把名字、单位、数据类型、属性打包采集层只负责填结构体落盘层统一遍历。这样以后从 TDM 换成 TDMS、或者把落盘换成别的格式只改一层。属性写入也一并收进去元信息就不会漏。改造完必须验一遍不然改出来的东西看着像对的。我的做法是写一个往返测试造一段已知数据比如sin加线性斜坡避免全零掩盖问题写盘、重新打开、逐点比对误差超过1e-12就判定失败同时比对通道数、组名、属性值。再补一轮边界样本零长度通道、单点通道、超长通道百万点以上、通道名含下划线和中划线、属性值为空串。这几组跑过基本能挡住九成的回归问题。还有一个技巧值得单独说调试读写代码时别急着看自己的业务结果先写一个“结构打印”函数把文件的组名、通道名、类型、长度、属性全打出来。TDMS 是二进制格式出了问题没有后悔药看不见结构就只能靠猜。这个函数我每个项目都会留一份后期对接分析端时直接拿它当协议文档用。从那以后我每次接采集落盘的活第一件事都是先写这个结构打印和往返校验再写业务逻辑——顺序反过来后面排查的成本要高出好几倍。希望帮到你。本文还有配套的精品资源点击获取
