XScript 手册 · Chapter 50

SYS — 系统全局对象

SYS 是汇集了时间、文件、HTTP、模块执行等 系统级工具 的全局对象。它在整个项目中使用最为频繁,让脚本能够以统一的方式访问运行信息与操作系统资源。

时间 · 滴答

属性 / 方法	返回	说明
`SYS.TickCount`	`int`	系统启动后经过的 ms
`SYS.GetTickCount()`	`int`	同上(函数形式)
`SYS.GetElasped(int startTick)`	`int`	`TickCount - startTick`
`SYS.SecondCount`	`int`	秒级计数器
`SYS.Year` / `SYS.Month` / `SYS.Day` / `SYS.Hour`	`int`	当前日期 · 时刻
`SYS.DateString`	`string`	`YYYYMMDD`
`SYS.TimeString`	`string`	`HHMMSS`
`SYS.DateTimeString`	`string`	`YYYYMMDD_HHMMSS`
`SYS.DateTimeFilename`	`string`	文件名安全格式
`SYS.DateTimeMsecString`	`string`	含毫秒
`SYS.CurrentDateTimeInISO8601`	`string`	ISO 8601
`SYS.GetDateTimeStringFormat(string format)`	`string`	应用 C# 格式字符串

xscript

int start = SYS.TickCount;
DoSomething();
int elapsed = SYS.GetElasped(start);
Log($"Elapsed: {elapsed} ms");

文件 · 路径

方法	说明
`bool ExistsFile(string path)`	文件是否存在
`string ReadAllText(string path)`	读取全部
`bool WriteAllText(string path, string data)`	写入全部
`array ReadAllLines(string path)`	按行读为数组
`bool WriteAllLines(string path, array lines)`	按行数组写入
`bool AppendLine(string path, string data)`	追加行
`bool CreateDirectory(string path)`	创建目录
`bool DeleteFile(string path)`	删除
`bool CopyFile(string src, string dest, bool overwrite)`	复制
`string Combine(string path1, string path2)`	路径合并
`string GetFileName(string path)`	仅文件名
`string GetFileNameWithoutExtension(string path)`	不含扩展名
`string GetValidFileName(string name)`	替换文件名中不可用的字符
`string ProjectBaseDirectory`	项目根目录
`string DownloadsFolderPath`	下载文件夹

xscript

string file = SYS.Combine(SYS.ProjectBaseDirectory, "JSON\\cube_machine.json");
if (SYS.ExistsFile(file) == false)
{
    LogError($"Not found: {file}");
    return false;
}
string text = SYS.ReadAllText(file);

HTTP

方法	说明
`string SendHttpGet(string url)` / `SendHttpGet(string url, string token)`	GET
`string SendHttpPost(string url, string data)` / `SendHttpPost(string url, string data, string token)`	POST
`string SendHttpDelete(string url, string token)`	DELETE
`string SendHttpPatch(string url, string data, string token)`	PATCH
`SYS.HTTP_ERROR_STR`	返回错误时的比较值
`SYS.LastHttpError`	最近的错误信息

xscript

string url = SS.MachineApiServer + "/machine-status";
string result = SYS.SendHttpPost(url, data, SS.HttpToken);
if (result == SYS.HTTP_ERROR_STR)
{
    LogError($"ERROR: {SYS.LastHttpError}");
    return false;
}

参数 · 模块执行

方法	说明
`bool SaveSetupParam(void)`	保存 Setup 参数
`bool LoadJobFileParam(void)`	加载 Job 文件
`bool GetParamValue(string name, ref string value)`	查询参数
`bool SetModuleVar(string name, value)` / `bool GetModuleVar(string name, ref value)`	访问其他模块变量
`bool RunScriptFunction(string module, string func, args...)`	执行其他模块函数
`bool StartModule(string module)`	重启模块
`void StopMotorAll(void)`	全轴停止
`bool CheckMotorName(string name)`	确认轴是否存在

xscript

if (SYS.RunScriptFunction(moduleName, "ParseJsonToModuleData", data) == false)
{
    ShowError(EB_Ok, 107, moduleName);
    return false;
}

系统状态 · 错误

属性	类型	说明
`SYS.IsRunning`	`bool`	自动运行中
`SYS.ManualThreadExitSignal`	`bool`	手动线程终止信号
`SYS.LastErrorCode`	`int`	最近的错误代码
`SYS.LastErrorMsg`	`string`	最近的错误信息
`SYS.LastErrorModuleName`	`string`	发生错误的模块
`SYS.ProjectVersion` / `SYS.QMSVersion`	`string`	版本

xscript

if (SYS.IsRunning == false)
{
    return true;
}
 
SYS.LastErrorCode = 0;
SYS.LastErrorMsg = "";
SYS.ResetError();

实战示例 — HTTP + 超时 + 日志

xscript

FUNCTION GetServerOrderCount()
{
    string url = $"{SS.HttpOrderAddr}/order-queue/machines/{SS.MachineId}/status";
    int s = SYS.TickCount;
    string data = SYS.SendHttpGet(url, SS.HttpToken);
 
    if (data == SYS.HTTP_ERROR_STR)
    {
        if (SS.OrderMode == 1)
        {
            LogError($"GetServerOrderCount Error :[{SYS.TickCount-s}ms] {SYS.LastHttpError}");
        }
        return -1;
    }
 
    int count = Order::GetOrderCount(data);
    return count;
}

提示

长时间等待时,用 SYS.GetElasped(startTick) 管理经过时间 —— Sleep 期间也要检查 ManualThreadExitSignal。
文件 IO 务必先用 ExistsFile 确认。写入前用 CreateDirectory 确保父目录存在。
HTTP 调用通过比较 SYS.HTTP_ERROR_STR 来区分成功/失败(不是抛出异常)。
模块间变量 · 函数调用统一使用 SetModuleVar / GetModuleVar / RunScriptFunction。

SYS 全函数参考(XUtilSystem)

依据 C# 源码 —— XUtilSystem 本体 + _LinearConverter / _LoadCell / _ThreadSync partial 之并集。

时间 · 时刻(属性 / 函数)

项目	含义
`SYS.TickCount` / `SYS.SecondCount`	启动后经过 ms / 秒
`SYS.GetTickCount()` / `SYS.GetTime()`	当前 tick / 时刻
`SYS.GetElasped(startTick)`	经过 ms
`SYS.DateString` / `SYS.TimeString` / `SYS.DateTimeString` / `SYS.DateTimeMsecString` / `SYS.DateTimeFilename`	常用格式
`SYS.CurrentDateTimeInISO8601`	ISO-8601
`SYS.GetDateTimeStringFormat(format)`	自定义格式
`SYS.GetAdjustedDate(dateString, offset)`	日期偏移
`SYS.ConvertSecondsToTimeString(sec)`	秒 → `HH:mm:ss`
`SYS.Year` / `SYS.Month` / `SYS.Day` / `SYS.Hour`	分量值
`SYS.RunTimeString` / `SYS.StopTimeString` / `SYS.IdleTimeString` / `SYS.ErrorTimeString`	累计时间(系统统计)

系统 / 模块控制

函数	含义
`SYS.IsRunning`(属性)	系统是否运行
`SYS.Start()` / `SYS.StartStepRun()` / `SYS.Stop()` / `SYS.Exit()` / `SYS.ExitMonitorModule()`	全局控制
`SYS.SetError(module="")` / `SYS.ResetError()`	切换系统错误状态
`SYS.LastErrorCode` / `SYS.LastErrorMsg` / `SYS.LastErrorModuleName`(属性)	最近错误
`SYS.StartModule(module)` / `StopModule(module)` / `StartModuleStepRun(module)` / `ExitModule(module)`	单模块控制
`SYS.SetModuleError(module)` / `ResetModuleError(module)`	模块错误
`SYS.SetModuleBackground(module, value)`	后台运行切换
`SYS.SequenceModuleCountOnWaiting` / `SequenceModuleCountOnRunning`(属性)	时序计数
`SYS.StopManualThread()`	终止手动线程
`SYS.ManualThreadExitSignal`(属性)	手动线程终止信号
`SYS.GetThreadCount(threadName)` / `(moduleName, seqOrFuncName)`	线程数

系统信息 · 许可证 · 诊断

项目	含义
`SYS.QMSVersion` / `SYS.ProjectVersion`	版本信息
`SYS.GetExeFileVersion()` / `GetExeAssemblyVersion()`	可执行文件版本
`SYS.IsProjectOpen` / `ProjectBaseDirectory`	项目状态
`SYS.LicenseKeyCount` / `LicenseMotorCount` / `LicensePermitRemainDays` / `TrialLicenseEnabled` / `HaveProjectCodeLicense` / `HaveLicense`	许可证
`SYS.GetAvailableRamSize()` / `GetProcessMemorySize()` / `GetManagedMemorySize()` / `GetTotalMemorySize()`	内存
`SYS.AddThreadIdLog(prefix, log)` / `AddMemoryLog()` / `LogSystemInfo()` / `LogVersionInfo()`	诊断日志
`SYS.IsVisualStudioRunning(update=false)`	是否附加调试器

产能(UPH)

函数	含义
`SYS.ClearUphData()` / `AddUphData(uph)` / `GetAverageUph()`	UPH 统计
`SYS.SetBoost()` / `ResetBoost()`	加速模式

文件 / 目录

函数	含义
`SYS.MakeFullPath(pathname)` / `IsFullPath(path)`	路径转换
`SYS.GetCurrentDirectory()`	当前目录
`SYS.GetFileName(path)` / `GetFileNameWithoutExtension(path)` / `GetDirectoryName(path)`	分解
`SYS.ChangeFileExt(filepath, ext)`	替换扩展名
`SYS.GetUpdateFileName(filename)`	生成更新文件名
`SYS.GetValidFileName(fileName)`	安全文件名
`SYS.GetRelativePath(baseFolder, path)` / `GetAbsolutePath(baseFolder, path)`	绝对/相对转换
`SYS.Combine(p1, p2, p3="", p4="")`	路径合并
`SYS.ExistsFile(path)` / `ExistsDirectory(path)`	存在确认
`SYS.CreateFile(path)` / `DeleteFile(file)` / `CopyFile(src, dst, overwrite)` / `CopyFiles(srcDir, pattern, dstDir, overwrite)`	文件
`SYS.MoveFile(src, dst, overwrite=true)` / `RenameFile(src, dst, overwrite=true)`	移动/重命名
`SYS.SetFileHidden(path, setHidden=true)`	隐藏属性
`SYS.CreateDirectory(path)` / `DeleteDirectory(path, recursive)` / `ForceDeleteDirectory(path, recursive)` / `MoveDirectory(src, dst)`	目录
`SYS.CopyDirectory(src, dst, overwrite=true)`	目录复制
`SYS.GetFiles(path)` / `(path, pattern)` / `(path, pattern, subDirectory)`	文件列表
`SYS.GetDirectories(path)` / `(path, pattern)` / `(path, pattern, subDirectory)`	目录列表
`SYS.DeleteFiles(dir, remainCount)`	清理旧文件
`SYS.OpenExplorer(path)`	打开资源管理器
`SYS.Execute(file, param)`	外部执行

文本文件输入输出

函数	含义
`SYS.ReadAllLines(path)` / `ReadAllText(path)`	读取
`SYS.WriteAllLines(path, data)` / `WriteAllText(path, data)`	写入
`SYS.AppendAllLines(path, data)` / `AppendAllText(path, data)` / `AppendLine(path, data)`	追加
`SYS.IsJsonFile(filepath)`	是否 JSON 文件

参数(XParam)

函数	含义
`SYS.SaveParam(managerKey)` / `LoadParam(managerKey)`	任意键
`SYS.SaveJobFileParam()` / `LoadJobFileParam()`	JobFile 参数
`SYS.SaveSetupParam()` / `LoadSetupParam()`	Setup
`SYS.SaveMasterParam()` / `LoadMasterParam()`	Master
`SYS.SaveRunParam()` / `LoadRunParam()`	Run
`SYS.GetParamValueObjectRef(dataName, remainLog=true)`	XParamValue 对象
`SYS.SetParamValue(dataName)` / `(dataName, string/int/double/bool)`	设值
`SYS.GetParamValue(dataName, ref string/int/double/bool)`	读值
`SYS.SaveSysVisionInfo()` / `SaveJobVisionInfo()`	保存 Vision 信息
`SYS.SaveGlobalData()` / `LoadGlobalData()`	全局数据

模块间通信

函数	含义
`SYS.SetModuleVar(name, string/int/double/bool)`	写模块变量
`SYS.GetModuleVar(name, ref string/int/long/double/bool)`	读模块变量
`SYS.GetModuleVarXData(dataName)`	返回 XData
`SYS.RunScriptFunction(module, function)` / `(module, function, string/int/long/double/bool)`	调用其他模块函数

HTTP

函数	含义
`SYS.SendHttpGet(url, token="")`	GET
`SYS.SendHttpPost(url, data, token="", type="")`	POST
`SYS.SendHttpPatch(url, data, token="", type="application/json")`	PATCH
`SYS.SendHttpDelete(url, token="")`	DELETE
`SYS.HTTP_ERROR_STR`(属性)	错误 prefix(`"[HTTP-ERROR]"`)—— 用于比较返回值
`SYS.LastHttpError`(属性)	最近的错误信息

声音

函数	含义
`SYS.PlaySound(fileName)` / `PlaySoundLoop(fileName)` / `StopSound()`	wav 播放

电机 / IO 批量控制

函数	含义
`SYS.SetSpeedAll(speed)` / `(speed, percent)`	所有电机速度
`SYS.ServoOnAll(on)`(`SetServoOnAll`)	伺服批量 On/Off
`SYS.ResetMotorHomeDoneAll()`	复位 Home Done
`SYS.StopMotorAll()` / `StopMotorEmgAll()`	批量停止
`SYS.ClearAlarmAll()` / `GetAlarmCount()`	报警
`SYS.GetMotorNames()` / `GetIoNames()`	名称列表
`SYS.CheckIOName(name)` / `CheckMotorName(name)` / `CheckCylinderName(name)` / `CheckIntefaceName(name)` / `CheckDeviceContainerName(name)`	名称有效性

消息 / 错误

函数	含义
`SYS.ShowError(buttonType, code, module, format, args...)`	错误对话框(与全局 `ShowError` 一起使用)

其他(随机数 · 哈希 · CRC)

函数	含义
`SYS.GetRandom()` / `(min, max)` / `GetRandomDouble()`	随机数
`SYS.GetSha256Hash(input)`	SHA-256
`SYS.CalcCRC16(data, length)`	Modbus CRC-16
`SYS.UpdateCustomData(command, index)`	自定义数据更新

Linear Converter / LoadCell / Thread Sync

XUtilSystem_LinearConverter.cs / _LoadCell.cs / _ThreadSync.cs 中的函数同样在相同的 SYS.* 命名空间下调用 —— 由于仅在量产环境中使用,将在单独的章节(或 LCVT 与 MATH 的 LCVT_* 一起)中讲解。