基于Polyworks的宏脚本编程语言（MSCL）基础

• 一.语法基础
  • 变量
  • 保留变量
  • 表达式
    • 数学表达式
    • 逻辑表达式
  • 语句
    • 条件语句
    • 循环语句
  • 数组
  • 用户输入
    • 基本用户界面
    • 高级用户界面
  • 文件操作
    • 文件创建
    • 文件写入
    • 文件内容读取
    • 文件属性读取
• 二.对象操作（Inspector）
  • 选择对象
  • 获取对象类型
  • 对象尺寸控制
• 三.脚本与进程调用
• 四.杂项
  • 脚本执行效率的提升

  Polyworks作为通用测量软件平台，提供了内置的宏脚本编程语言，可以使用基于COM组件的技术调用软件底层指令与功能，实现测量计划自动化编制，和全流程的自动化测量，提供软件的使用效率。

宏脚本使用场景汇总

一.语法基础

变量

  变量是用于存储和查询信息的容器，在Polyworks中存在三种基本变量类型，包括整型，双精度型和字符串型等

• 整型：   整数（无小数点）
• 双精度型： 允许小数点的数字
• 字符串型： 字母和数字字符的序列

  在定义变量时不需要显式的指明变量类型，当为其赋值时，宏脚本内核会自动为其适配变量类型，定义变量使用DECLEAR指令，变量初始值可以在声明变量是指定，也可以使用SET指令指定：

DECLEAR varName
DECLEAR featureCount 5
SET featureCount 10

变量名可以由任意非保留变量构成，保留变量包含：_DOLLAR, _INSTALL_PATH, _PI, _NEWLINE等。在实际编程中，尽可能使用描述性的命名, 别心疼空间, 毕竟相比之下让代码易于新读者理解更重要. 不要用只有项目开发者能理解的缩写, 也不要通过砍掉几个字母来缩写单词。命名方法推荐使用骆驼式命名法：featureCount，和下划线法feature_count。

  获取变量值方法在变量名前添加$，如果变量存在于字符串中，则需要使用{ }将变量名包裹起来:

DECLARE variable1 "Message 1"
MACRO ECHO ( $variable1 )
MACRO ECHO ( "${variable1} followed by extra words" )

OUTPUT: Message 1
OUTPUT: Message 1 followed by extra words

变量修饰符   在某些情况下，比如字符串比较，需要将用户输入的字符串转换为小写字母或者大写字符，可以使用:l将修饰的字符串转化为小写，使用:u会将修饰的字符串转化大写：

DECLARE variable1 "Message 1"
MACRO ECHO ( "${variable1} Uppercase = ${variable1:u}" )

OUTPUT: Message 1 Uppercase = MESSAGE 1

保留变量

  保留变量用于存储与Polyworks环境相关的信息，可以用于查询相关的软件环境信息，主要环境变量如下：

表达式

数学表达式

• 数学表达式使用EXPR和EXPR_I来获得计算结果，两种不同的地方在于EXPR_I去除结果的小数部分；
• 基本数学操作符：+, -, *,/, % (取模)；
• 基本数学函数：ABS (取绝对值), SQRT (平方根), SIN, COS, TAN等等；

DECLARE a 1
DECLARE b 2
DECLARE c
DECLARE d
DECLARE e

SET c EXPR ( $a + $b )
SET d EXPR ( SQRT( $c ) )
SET e EXPR_I ( SQRT( $c ) )

MACRO PAUSE ( "Math", "$a + $b = $c", "Square Root of $c = $d", "Square Root of $c (no decimals) = $e" )

逻辑表达式

  在宏脚本语言中，需要使用逻辑表达式判断指令执行的结果和当前变量的状态。

比较操作符

• <   小于
• <=  小于等于
• >   大于
• >=  大于等于
• ==  等于
• !=  不等于

逻辑操作符

（需Polyworks 2020 IR1及以上版本）

• AND  逻辑与，两个表达式同时为真时，结果为真，否则为假；
• OR   逻辑或，两个表达式只需要一个为真，结果即为真，同时为假时，结果才为假；
• NOT  逻辑非，表达式为真时，返回结果为假，表达式为假时，返回结果为真；

IF $c == 0
    MACRO PAUSE ( "Zero", "$c equals zero." )
ELSEIF $c < 0
    MACRO PAUSE ( "Smaller than zero", "$c is negative (<0)." )
ELSE
    MACRO PAUSE ( "Bigger than zero", "$c is positive (>0)." )
ENDIF

IF $a > 0 AND $b > 0
    MACRO PAUSE ( "Bigger than zero", "$a AND $b are both bigger than zero." )
ENDIF

IF $a > 0 OR $b > 0
    MACRO PAUSE ( "Bigger than zero", "$a OR $b is bigger than zero." )
ENDIF

语句

条件语句

  条件语句用于控制程序的执行顺序，条件语句的指令如下：

• IF:    条件语句的开始，用于判断逻辑表达式
• ELSEIF:  增加分支判断
• ELSE:   当前面所有的判断语句均为假时，执行该分支
• ENDIF:   条件语句退出

语法结构如下：

IF <Condition_1>
    <Statement_1>
ELSEIF <Condition_2>
    <Statement_2>
ELSE
    <Statement_3>
ENDIF

循环语句

  循环语句用于重复的执行特定的语句，并在每一次循环迭代后，判断当前的循环条件。在宏脚本编程语言中只存在一种循环结构：WHILE循环，相关指令如下：

• WHILE: 循环结构开始
• ENDWHILE: 循环结构结束
• BREAK: 终止当前循环结构
• CONTINUE: 跳出本次循环
• ++: 当前变量（循环变量）累加1 (与SET i EXPR ( $i + 1 )相同 )
• --: 当前变量（循环变量）累减1 (与SET i EXPR ( $i - 1 )相同 )

语法结构如下：

WHILE <Condition>
    <ProcessCode>
ENDWHILE

数组

  数组是由一组元素组成的序列，其中的每个元素都分配一个数字（索引）–它的位置，其中第一次元素的索引为1，第二个元素的索引为2，以此类推。

MSCL中的仅支持一维数组，不支持二维或三维等高维数组；

数组中的元素的类型可以不同，比如{5.0, 2, "user"}就是一个合法的数组

MSCL中提供了完善的操作数组的指令 ：

（需Polyworks 2021 IR1及以上版本）

用户输入

  用户界面是用户与运行中的宏脚本进行信息交互的途径，用户可以通过键盘输入相应的参数，或者选择用户处理的文件或者文件夹。

基本用户界面

  在基本用户界面中用户通常可以一次输入一个参数，通常包括整型，双精度型，字符串型，以及密码类型参数，也支持文件路径和文件夹路径的选择，借助MACRO INPUT MULTIPLE_PARAMETERS指令也可以将其合并到一个用户界面中，一次性输入，常用的宏指令如下：

高级用户界面

（需Polyworks 2020 IR2及以上版本）

  使用MACRO INPUT DIALOG_BOX命令，可以在创建对话框时提供更多可能性，不仅可以实现常规的参数输入，还可以添加多选列表框，单选框和复选框等高级的用户界面组件，这在用户需要多个参数值时非常有用。

效果图如下：

常用的宏指令如下：

  要使用这些命令，首先使用MACRO INPUT DIALOG_BOX DEFINE命令定义对话框并为其分配一个标题。然后，使用相应的MACRO INPUT DIALOG_BOX命令将所需参数添加到对话框。请注意，它们的显示顺序与输入顺序相同。

文件操作

  常见的文件类型可以分为文本型文件和二进制型文件，二进制型文件无法使用记事本等文本编辑器直接编辑，需要使用专用的文件解析器解析其中的二进制对象，而文本型文件可以使用MSCL对其进行文件的创建，读取与信息写入等操作，也可以获得文件的行数和字段数等信息。

文件创建

  文本型文件在使用MSCL进行创建时可以指定文件编码类型，包含Unicode和Ascii两种类型，默认为Ascii，也可以指定文件覆盖模式，包括覆写原有文件和追加原有文件两种方式，文件创建指令如下：

DATA_FILE CREATE ( <File name>, <Unicode or ASCII file>, <Overwrite the file> )

文件写入

文件写入方法包括追究字符串和追加单行以及追加多行，具体包含如下指令：

文件内容读取

  文本型文件的读取包含多种形式，可以对一行，一行中的某个字段或者所有字段，以及每一列的信息进行读取。实际编程中，为了提高脚本执行效率，运行一条指令，应该读取尽可能多的信息。具体包含如下指令：

文件属性读取

  文本型文件的行数和每一行的字段数可以通过如下指令获得：

在MSCL中，提供了用于监听文件读写状态的的指令DATA_FILE WAIT_UNTIL_MODIFIED，该指令会暂停脚本的执行，直到指定的文件被修改，或者等待超时。如果文件不存在，脚本将会等待文件创建完成后，再执行后续指令。

二.对象操作（Inspector）

  在MSCL中的对象操作主要包括对象选择，对象类型判断，对象属性查询与设置，对象尺寸控制查询与设置等。主要的操作指令可以分为两类，即基于OBJECT的对象操作，和基于具体对象类型的对象操作，前者指令格式为TREEVIEW OBJECT <OPERATION COMMAND>，后者格式为TREEVIEW <OBJECT NAME> <OPERATION COMMAND>，为了提高脚本的通用性，首选基于OBJECT版的对象操作指令。

选择对象

获取对象类型

  使用TREEVIEW OBJECT PROPERTIES TYPES GET可以作为通用的对象类型查询指令，可以获得对象的类型（Reference，Feature，Comparison Point等），和主类型（Plane，Circle，Slot等）等信息。

对象尺寸控制

  获取和设置目录树中对象的尺寸和控制建议使用TREEVIEW OBJECT PROPERTIES DIMENSION系列的宏指令，不建议使用MEASURE CONTROL MEASURED和MEASURE CONTROL NOMINAL相关的宏指令，因为这两个宏指令只能设置和获取当前对象在几何控制里已经勾选过的尺寸控制。

三.脚本与进程调用

通常情况下，编写宏脚本时，会将不同的功能放在不同的脚本文件中，脚本之间通过互相调用来实现更加复杂的功能，同时也可以调用Polyworks外部的进程完成一些当前MSCL指令无法实现的数据计算或者通信等。涉及到的宏指令如下：

四.杂项

脚本执行效率的提升

通常情况下，每一条指令运行结束后，都会伴随着这个软件界面的刷新，包括目录树，3D场景，状态栏和信息栏等。因此，为了提高执行效率可以暂时的关闭这些软件区域的刷新，如下所示，使用Toggle参数，可以控制相关区域刷新的开关：

TREEVIEW REFRESH ( "Toggle" )
WINDOW REFRESH ( "Toggle","On","On")