InstallShield内部库函数全集十七－批处理函数

19  批处理函数
19.1  高级批处理文件函数
    高级批处理文件函数和Ez批处理文件函数不同，它们提供更大的灵活性和对批处理文件的更多控制。当需要对一个批处理文件做更多扩充和更复杂的修改，则使用这些函数。
    为用这些高级函数来编辑一个批处理文件，你必须首先通过调用BatchFileLoad把该文件装入到内存。当完成了对该批处理文件的修改，然后必须调用BatchFileSave保存该文件。
    安装初始化时，它选择目标系统的启动批处理文件（Autoexec.bat)作为缺省批处理文件（除非通过调用BatchSetFileName来修改），如果没有指定其它文件名，该文件就是由BatchFileLoad读入内存的文件。为确定缺省批处理文件的全限定名，调用BatchGetFileName。
    不要把Ez配置文件函数和高级配置文件函数混合起来。调用BatchFileLoad之后，直到你调用了BatchFileSave保存你的修改后，你才能使用Ez配置文件函数。
BatchAdd
添加一个环境变量到一个批处理文件。
BatchDeleteEx
删除批处理文件中的一行。
BatchFileLoad
把一个批处理文件装入内存来用高级批处理函数编辑它。
BatchFileSave
保存一个由BatchFileLoad装入的批处理文件。
BatchFind
在一个批处理文件中查找项目。
BatchGetFileName
检索缺省批处理文件的全限定名。
BatchMoveEx
移动一个批处理文件中的一个项目。
BatchSetFileName
指定作为缺省批处理文件的一个批处理文件。
相关函数：
SdShowFileMods
19.1.1  BatchAdd
语法：BatchAdd (szKey, szValue, szRefKey, nOptions);
说明：BatchAdd函数插入一个ＳET命令或其它ＤOS命令到一个已经由BatchFileLoad装入内存的批处理文件中。参数nOptions使你可以将新命令添加到文件的第一个或最后一个语句，用新命令取代一个现存语句，或指定将新命令添加到一个现存语句的前面或后面。
    除非你将常量COMMAND和你传递给nOptions的值用或操作符连接，否则BatchAdd自动在你要插入的语句的开始添加DOS关键字SET。如果你没有在nOptions显式指定REPLACE，那么即使在批处理文件中存在重复行，指定的语句也会被添加。
调用BatchAdd前，你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后，调用BatchFileSave来把它保存到磁盘。
参数：
szKey
指定要添加到批处理文件中的关键字。PATH、 TEMP和 MYENV是该参数有效值的例子。
szValue
指定要添加到该批处理文件中的关键字的值。该字符串必须不长于512个字节；传递一个长于512字节的字符串将会引起一个安装错误。为添加一个更长的字符串，使用FileGrep 和 FileInsertLine函数。
批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行，则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径，然后再能把它插入到要添加至批处理文件的字符串中。
szRefKey
指定在批处理文件中与你添加的szKey相关的参考项。
nOptions
指定该行被插入到文件何处。在该参数位置传递下列预定义常量之一：
BEFORE：该语句被添加到包含szRefKey的第一行的前面。如果szRefKey是一个空字符串(“”)，该语句被添加到文件首行。
AFTER：该语句被添加到包含szRefKey的最后一行的后面。如果szRefKey是一个空字符串(“”)，该语句被添加到文件末行。
REPLACE：该语句将置换文件中已存在的一行。如果存在多行有相同的字，仅最后一行被置换。如果szKey不存在于文件中，新行添加到szRefKey之后。如果szRefKey是一个空字符串(“”)，该语句被添加到文件末行。
    当被添加的语句不是一个SET命令，给szKey传递一个空字符串，给szValue传递完整命令，并将常量COMMAND和其它选项之一用或操作符(|)连接，如下所示：
   BatchAdd("", "PAUSE", "", COMMAND | AFTER);
返回值：
0：BatchAdd成功添加一个SET语句或其它命令到批处理文件。
< 0：BatchAdd未能添加一个SET语句或其它命令到批处理文件。
注解：
·一个InstallShield参考项可以是一个环境变量，DOS命令或一个程序文件名。环境变量是关键字，如PATH, COMSPEC, LIB或其它预定义或用户定义的标识符。一个环境变量的值使用DOS SET命令来设置。显示在一个批处理文件中的语句必须是DOS命令，程序名（有或没有命令行参数）或注解。有关命令和环境变量的详细定义请参阅操作系统手册。
19.1.2  BatchDeleteEx
语法：BatchDeleteEx (szKey, nOptions);
说明：BatchDeleteEx函数删除一个批处理文件中包含szKey指定的值的行。调用BatchDeleteEx前，你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后，调用BatchFileSave来把它保存到磁盘。
参数：
szKey
指定标识要被删除的行的参考关键字。
nOptions
表明szKey是指定一个SET语句中的一个环境变量还是一个命令。在该参数位置传递下列预定义常量之一：
0：指定szKey是一个SET语句中的一个环境变量。一个环境变量是一个预定义的标识符（如PATH, COMSPEC和 LIB)，或一个用户定义的标识符。例如，如果szKey的值是"LIBPATH"并且nOptions设置为0，则下面语句将被删除：
SET LIBPATH=C:\Lang\Lib
COMMAND：指定szKey是一个DOS命令或一个程序文件名。
返回值：
0：BatchDeleteEx成功删除包含指定值的行。
< 0：BatchDeleteEx未能删除包含指定值的行。
19.1.3  BatchFileLoad
语法：BatchFileLoad (szBatchFile);
说明：BatchFileLoad函数将指定批处理文件的一份拷贝装入内存以便其它高级批处理文件函数可以被调用来操作该文件。在szBatchFile指定你要编辑的批处理文件名或给szBatchFile传递一个空字符串来编辑缺省批处理文件，它由InstallShield初始化设置为由系统使用的Autoexec.bat。
    注意你可以调用BatchFileLoad来创建一个新批处理文件。为了这么做，你可以给szBatchFile传递一个不存在的文件名。然后调用其它批处理函数来编辑新文件。最后，调用BatchFileSave将新文件保存到磁盘。
使用任何高级批处理文件函数之前，你必须首先调用BatchFileLoad将要修改的文件装入到内存。在你修改文件后，调用BatchFileSave将它保存到磁盘。为得到将安装脚本中使用的缺省批处理文件的全限定名，调用BatchGetFileName。为指定另一个在安装脚本中使用的缺省批处理文件，调用BatchSetFileName。
参数：
szBatchFile
指定装入内存的批处理文件的全限定名。为装入缺省批处理文件，给该参数传递一个空字符串(“”)。如果你在该参数指定一个文件，该文件成为缺省批处理文件。调用该函数后，你可以使用所有高级批处理文件函数来操作该文件。
返回值：
0：BatchFileLoad成功将指定批处理文件装入内存。
< 0：BatchFileLoad未能将指定批处理文件装入内存。
19.1.4  BatchFileSave
语法：BatchFileSave (szBackupFile);
说明：BatchFileSave函数将由BatchFileLoad函数装入内存的批处理文件保存到磁盘。文件保存为它的原始名。如果在szBackupFile指定一个文件名，在被编辑的文件被写到磁盘前原始文件用该文件名更名。如果szBackupFile包含一个空字符串(“”)，原始文件被该修改的文件置换。如果你结束用高级批处理文件函数修改一个批处理文件时没有调用BatchFileSave，所有修改将被丢失。
参数：
szBackupFile
指定在编辑被保存前是否要有一个原始文件拷贝的备份。
如果无需创建备份文件，给该参数指定一个空字符串。
如果原始文件必须用一个特定名备份，给该参数传递该文件名。该文件名必须是非限定的（也就是，不限定一个驱动器和/或路径）。注意如果具有指定名称的文件已经存在， BatchFileSave将生成一个唯一的文件扩展名，如接下去布告牌项目中描述。
如果原始文件备份时必须带有一个安装生成文件的扩展名，指定通配符””作为文件扩展名（例如，”Batch.”）。然后安装将赋一个数值型值，从001开始，作为扩展名。如果一个有该扩展名的文件已经存在，扩展名值将增加1直到产生一个唯一的文件名。
一旦创建了备份，InstallShield保存备份文件名到系统变量INFOFILENAME。
注意下列重要事实：1）如果上一次对BatchFileLoad的调用指定的批处理文件不存在，备份文件将和由调用BatchFileSave创建的批处理文件相同。2）如果szBakupFile指定原始批处理文件名，那么将不会创建一个备份文件。
返回值：
0：BatchFileSave成功保存内存中的批处理文件到磁盘。
< 0：BatchFileSave未能保存内存中的批处理文件到磁盘。
19.1.5  BatchFind
语法：BatchFind (szRefKey, svResult, nOptions);
说明：BatchFind函数在一个批处理文件中查找出现szRefKey指定的参考关键字的一处或多处。如果你在nOptions指定常量RESTART，返回参考关键字第一次出现之处。为找到出现szRefKey的下一处，将参数nOptions设置为CONTINUE重复调用该函数。
    调用BatchFind前，你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后，调用BatchFileSave来把它保存到磁盘。
参数：
szRefKey
指定要查找的参考关键字。参考关键字可以是一个环境变量，一个DOS命令或一个程序名。如果参考关键字是一个文件名并且你没有指定一个文件扩展名，函数将返回所有有该基名的关键字。例如，如果你指定Win.com，查找仅对该参考关键字。如果你指定WIN，Win.exe文件，Win.dll文件,Win.sys文件等等如故存在于批处理文件中，则都将被返回。
svResult
指定在批处理文件中找到的关键字的值。
nOptions
指定从哪儿开始查找；在该参数位置传递下列预定义常量之一：
CONTINUE：从批处理文件当前位置开始查找。
RESTART：从批处理文件开始来开始查找。
当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量)时,将常量COMMAND和CONTINUE或RESTART用或操作符(|)连接,如下所示:
BatchFind ("SCAN.EXE", svResult, COMMAND | RESTART);
返回值：
0：BatchFind成功找到szRefKey的值并在szResult返回它。
< 0：BatchFind未能找到szRefKey的值并在szResult返回它。
19.1.6  BatchGetFileName
语法：BatchGetFileName (svFileName);
说明：BatchGetFileName函数检索缺省批处理文件（由InstallShield初始设置为系统启动时使用的自举Autoexe.bat文件）的全限定名。为指定一个不同的批处理文件为安装脚本中使用的缺省批处理文件，调用BatchSetFileName。
参数：
svFileName
在szFileName返回缺省批处理文件的全限定名。
返回值：
0：BatchGetFileName成功检索缺省批处理文件的全限定名。
< 0：BatchGetFileName未能检索缺省批处理文件的全限定名。
19.1.7  BatchMoveEx
语法：BatchMoveEx (szMove, szRefKey, nOptions, nMoveOption);
说明：BatchMoveEx函数将一个批处理文件中由szMove指定的行从一个位置移动至另一个位置。参数nOptions指定是把该行放置在批处理文件的开始或结尾，还是在szRefKey指定的行的前面或后面。调用BatchMoveEx前，你必须调用BatchFileLoad来把要修改的文件装入内存。在你修改该文件后，调用BatchFileSave来把它保存到磁盘。
参数：
szMove
指定标识要被移动行的参考关键字。
szRefKey
指定关键字，它标识用来定位移动行的参考行。如果szRefKey是一个空字符串，由szMove 指定的行移动到文件的开始或结尾，根据nOptions的值而定。
nOptions
指定将行移动到何处；给该参数传递下列预定义常量之一：
BEFORE：由szMove指定的行被移动到包含szRefKey参考关键字的行的前面。如果szRefKey是一个空字符串，则由szMove指定的行被移动到文件的开始。
AFTER：由szMove指定的行被移动到包含szRefKey参考关键字的行的后面。如果szRefKey是一个空字符串，则由szMove指定的行被移动到文件的结尾。
    当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量)时,将常量COMMAND和BEFORE 或AFTER用或操作符(|)连接，如下所示:
BatchMoveEx ("PATH", "SCAN.EXE", BEFORE | COMMAND, 0);
nMoveOption
指定szMove是一个命令还是一个环境变量。给该参数传递下列预定义常量之一：
0：指定szMove是一个环境变量。
COMMAND：指定szMove是一个命令。
返回值：
0：BatchMoveEx成功移动批处理文件中的指定行。
< 0：BatchMoveEx未能移动批处理文件中的指定行。
19.1.8  BatchSetFileName
语法：BatchSetFileName (szBatchFile);
说明：BatchSetFileName函数指定由Ez批处理文件函数及以一个空字符串为其参数调用BatchFileLoad时所使用的批处理文件名。在安装脚本中，该文件被作为缺省批处理文件。安装初始化过程中，缺省批处理文件被设置为系统使用的Autoexec.bat文件。
应重视下列有关BatchSetFileName的事实：
它不确认指定文件的存在性。
它不把文件装入内存。
参数：
szBatchFile
指定在安装脚本中作为缺省批处理文件使用的文件的全限定名。
返回值：
0：BatchSetFileName成功设置指定文件为缺省批处理文件。
< 0：BatchSetFileName未能设置指定文件为缺省批处理文件。
注解：
BatchSetFileName只简单地指定缺省批处理文件的名称。即使文件名是无效的或指定文件不存在时该函数也会成功。一个无效的文件名将导致随后的Ez批处理文件和高级批处理文件函数失败。
19.2  Ez批处理文件函数
Ez批处理文件函数修改缺省批处理文件。除非通过调用BatchSetFileName来修改，缺省批处理文件是Autoexec.bat。应注意的是每个Ez批处理文件函数打开缺省批处理文件然后在作修改后自动保存它。你使用Ez批处理文件函数时你不用调用函数来打开和保存。
    不要把Ez批处理文件函数和高级批处理文件函数混合起来。调用BatchFileLoad之后，直到你调用了BatchFileSave保存文件后，你才能使用Ez批处理文件函数。
EzBatchAddPath
修改缺省批处理文件，通过添加一个路径名到一个PATH命令的查找路径或到一个赋给环境变量的值。
EzBatchAddString
添加一行文本到缺省批处理文件。
EzBatchReplace
置换缺省批处理文件中的一个语句。
19.2.1  EzBatchAddPath
语法：EzBatchAddPath (szKey, szPath, szRefDir, nPosition);
说明：EzBatchAddPath函数修改缺省批处理文件，通过添加一个路径名到一个PATH命令的查找路径或到一个赋给环境变量的值。除非通过调用BatchSetFileName来修改，缺省批处理文件是Autoexec.bat。
    调用BatchGetFileName来确定缺省批处理文件的全限定名。为改变EzBatchAddPath使用的批处理文件的文件名，调用BatchSetFileName。该函数不支持长文件名。在把它传递到调用EzBatchAddPath 之前调用LongPathToShortPath来转换长路径到它等价短路径。
参数：
szKey
指定要修改的环境变量名。如，为修改PATH语句，在这儿指定”path”。 如果指定的环境变量没有在缺省批处理文件中找到，则为环境变量创建一个完整SET语句并插入到文件中。
szPath
指定添加到环境变量当前值的路径名。在查找路径中插入一个分界分号来把它和其它路径名分隔开。
szRefDir
指定与你添加的szPath新路径名相关的参考关键字（一个路径名）。如果这是一个空字符串，该路径名添加到查找路径的开始或结尾，根据nPosition的值而定。如果由szRegKey指定的路径名没有在查找路径中找到，szKey的值被添加到结尾。
nPosition
指定在查找路径的何处添加新路径名，具体包括以下选项：
BEFORE：新路径名被插入到szRefDir指定的路径名的前面。如果szRefDir 包含一个空字符串，该路径名被添加到查找路径的前面。
AFTER：新路径名被插入到szRefKey指定的路径名之后。如果szRefDir 包含一个空字符串，该路径名被添加到查找路径的结尾。
返回值：
0：EzBatchAddPath成功添加路径名到批处理文件。
< 0：EzBatchAddPath未能添加路径名到批处理文件。
注解：
·缺省批处理文件是隐藏或只读时EzBatchAddPath 可能失败。
·EzBatchAddPath对它修改的文件不做拷贝备分。
19.2.2  EzBatchAddString
语法：EzBatchAddString (szLine, szRefKey, nOptions);
说明：EzBatchAddString函数添加一文本行到缺省批处理文件；除非通过调用BatchSetFileName来修改，缺省批处理文件是Autoexec.bat。为确定缺省批处理文件的全限定名，调用BatchGetFileName。为修改由EzBatchAddPath使用的批处理文件的名称，调用BatchSetFileName。
参数：
szLine
指定添加到文件中的文本行。除非你在nOptions 指定NOSET，该函数假定szLine是一个环境变量；在szLine被写入到缺省批处理文件中前文本”SET”被插入到字符串的前面。
    批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行，则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径，然后再能把它插入到要添加至批处理文件的字符串中。
szRefKey
指定和你想要在缺省批处理文件中添加的szLine相关的参考关键字。EzBatchAddString在缺省批处理文件中查找参考关键字和在该行前面或后面放置szLine的内容，根据nOptions 的值。
nOptions
指定使用的选项；在该参数位置传递下列预定义常量之一：
BEFORE：SzLine被添加到包含szRefKey的行之前。如果szRefKey是一个空字符串，szLine被添加到文件的第一行。
AFTER：SzLine被添加到包含szRefKey的行之后。如果szRefKey是一个空字符串，szLine被添加到文件的最后一行。
REPLACE：SzLine置换文件中的一现存行。如果有多行有相同关键字存在，EzBatchAddString仅置换包含该关键字的最后一行。
NOSET：指定文本”SET”不被插入到szLine中的字符串的前面。该常量可以和BEFORE、 AFTER、 和REPLACE用或操作符(|)组合。
当你查找的参考关键字是一个DOS命令或程序名(而不是一个环境变量)时,将常量COMMAND和其它选项常量用或组合,如下所示:
    EzBatchAddString (szLine, szRefKey, AFTER | COMMAND);
返回值：
0：EzBatchAddString成功添加文本字符串到一个指定批处理文件。
< 0：EzBatchAddString未能添加文本字符串。
注解：
·EzBatchAddString 在参数szRefKey中查找合适的参考关键字。如，一个环境变量的关键字是该环境变量本身的名称。
·如果缺省批处理文件是隐藏或只读时，EzBatchAddString可能失败。
·EzBatchAddString对它修改的文件不做拷贝备分。
19.2.3  EzBatchReplace
语法：EzBatchReplace (szNewString);
说明：EzBatchReplace函数置换缺省批处理文件中的一个现存行；除非通过调用BatchSetFileName来修改，缺省批处理文件是Autoexec.bat。为确定缺省批处理文件的全限定名，调用BatchGetFileName。为修改由EzBatchAddPath使用的批处理文件的名称，调用BatchSetFileName。
参数：
szNewString
指定置换文件中一现存行的新字符串。
    批处理文件完全不支持长路径名。如果你使用该函数来添加包含长路径名的一行，则必需先调用LongPathToShortPath把长路径名转换成它等价的短路径，然后再能把它插入到要添加至批处理文件的字符串中。
返回值：
0：EzBatchReplace成功置换文本行。
< 0：EzBatchReplace未能置换文本行。
注解：
·EzBatchReplace分析szNewString并确定该字符串的关键字。然后它在缺省批处理文件中查找包含相同关键字的一行。该函数置换找到的有相同关键字的最后一行。
·一个批处理文件中的一些常用关键字是PATH、 COMSPEC、TEMP、Smartdrv.exe、Win.com、和Share.exe。
·如果缺省批处理文件是隐藏或只读时，EzBatchReplace函数可能失败。
·EzBatchReplace对它修改的文件不做拷贝备分。