Rational Robot 头文件和库文件(翻译)

 

Robot头文件和库文件
头文件
SQABasic头文件包含一系列的声明，头文件可以应用到
一． 声明共有或则全局常量，变量和用户定义类型
二． 声明自定义sub,procedures和function
头文件中的声明可以应用到任何模块（脚本或者类库文件）。用’$include关键字，放在模块开始的地方-例如：
    ’$include “global.sbh”

SQABasic头文件类型
Sqabasic支持两种头文件类型：
一． 头文件保存在sqabasic路径。不用指定任何路径信息就可以在本工程或者其他工程中应用他们
二． 工程头文件可以保存在TMS_scrīpt文件夹中。不用指定任何路径信息就可以在同一个工程中处理。

这两种SQABasic头文件都有同样的扩展名- .sbh

库文件
库文件包含一个或者更多供procedure从其它文件调用的sub,procedure和function。
一． SQABasic库文件（扩展名为.sbl或则.rec）
注意，.rec文件可以作为脚本文件或者库文件，但是.sbl只能被用作库文件。
二．动态连接库文件（扩展名.dll）
下边的表格这几种类库文件不同的总结：

	.sbl	.rec	.dll
位置	SQABasic路径	当前工程文件中Datastore（文件夹TMS_scrīpt）	TMS_scrīpt/dll文家夹或则其他位置
范围	在SQABasic路径中，对所有工程文件都可用	对同一个工程所有脚本可用	依靠位置
验证点	不支持	支持标准的robot验证点	支持自定义验证点

任何.rec文件都能作为库文件。不管怎样，如果一个.rec文件作为脚本(可以从robot中直接运行或者用callscrīpt命令)，他必须有一个main过程。

在SQABasic库文件中声明过程
如果在SQABasic过程中有一个自定义的过程，你声明类文件的方法同样适用声明过程。
下边的例子是在sqabasic库文件中（mylib.sbl）声明一个自定义过程（mysub）:
    Declare Sub MySub Basiclib “MyLib”( arg1 as string,arg2 as integer)
一． 关键字basiclib，表示过程mysub在一个sqabasic库文件中
二．库文件的名字“mylib”，这里不需要写扩展名（.sbl或者.rec）
备注：basiclib关键字特指.sbx库文件的声明（和.dll库文件相对），这里不需要也不推荐带有.sbx扩展名的声明。

什么地方声明SQABasic库文件
可以在任何位置声明SQABasic库文件
一． 在脚本或者其他库文件，仅在模块中应用过程
二．头文件中，用道的模块
库文件包含不需要指定的例程或者’include头文件

在dll文件声明过程文件
如果在dll文件的自定义过程，声明过程同样可以声明dll文件。
下边是dll文件中（mydll.dll）声明自定义过程（mysub）的例子：
 declare sub mysub lib “mydll”(byval arg1 as string,Byval arg2 as integer)
一． 声明中加入Lib关键字，表示声明的过程在dll文件中（相对于.sbl或者.rec sqabasic库文件）
二．库文件名字（mydll），跟随库指定的名称
三．参数声明通常包括关键字byval（参数声明包括任何关键字）

如果编译位置在sqabas32路径或在系统路径的库文件（.dll），你不用特别声明路径。如果库文件不再sqabas32或者在系统路径，你需要制定路径，比如
 Declare Sub MySub Lib “E:\MyDll”  (byval arg1 as string,Byval arg2 as integer)

在什么地方声明dll文件
你可以声在任何为指声明dll文件：
1. 脚本或者sqabasic库文件，要用过程的模块
2. 头文件，任何模块指定的头文件

SQABasic路径
Sqabasic路径是robot保存和寻找sbl库文件和头文件的地方，用户在robot中也可以定义。
一旦你在robot中指定sqabasic路径，这个路径是固定的。不管怎样，robot自动设置sqabasic路径，当下列条件是真的时候：
i. 仍没有明确在robot中定义sqabasic
ii. 已经在rational Aministrator建立新的工程和数据仓库
iii. 打开最近创建的工程和数据仓库

当上边所有条件为真的时候，robot自动在新工程和数据仓库中设置sqabasic路径到下列位置：
[NewProject]\[NewDatastore]\DefaultTestscrīptDatastore\TMS_scrīpt\SQABas32

设置步骤：
1) 点Tools->General Options
2) 点Preferences页面
3) 在SQABasic路径中输入路径
Rational test早期版本没有提供菜单选项来设置sqabasic路径 – 参阅sqa common directory片断
指导使用头文件和库文件
推荐下边使用库文件方法：
a) 自定义函数或者过程应该使用有同样文件名字的头文件（.sbh）和库文件（.sbl），比如DataFunctions.sbh和DataFunctions.sbl。这个过程和函数在头文件中定义（指定声明头文件）和在库文件中定义。看下边的例子
b) 分离头文件（参阅常量头文件）用于包含常量，变量和用户定义类型用于脚本或者库文件调用。头文件用同样的文件名字后边附加_x或则_C（附加是早期命名规定）。注意包含常量和变量的头文件必须加入到声明头文件和库文件之前。（DataFunctions.sbh和DataFunctions.sbl），比如’include “DateFunctions_c.sbh”。这样做很容易维护。
c) 通过分类或者程序把相关的函数放在同一个库里，例如，把所有日期相关的函数放到DataFunctions.sbh/sbl，或者把所有的函数加入为特定程序开发的函数库中（比如AppName.SBH/SBL）
d) 函数是在库文件中子程序的的首选方式，处分过程的结果对于调用脚本是不相关的。函数应该返回一个值，或者适当的，数据可以通过变量或者数组返回。在后边的例子中，函数返回的结果表示成果或者失败。
e) 库文件中的所有得函数和子程序必须有“注释“，包含这个过程的目的和用途：:
•目的描述
•调用陈述 (类似函数声明)
•参数声明
•返回值
•例子
•可能产生的错误
•历史修改纪录
请看下边的例子。
f) 库文件的注释有合理的解释，通过读注释可以知道过程的逻辑
g) 如果开发和维护robot库文件是集中管理的方式，那么你可以加入到’$include 所有库文件到global.sbh头文件中，这样做对所有头文件都有用。这可以加入缺省的脚本模板。作为选择，测试人员在每个脚本中可以选择或者包含需要的库文件。
Rational Robot测试指导
Paul Downes (Paul_Downes@providian.com)
Carl Nagle (Carl.Nagle@sas.com)
7 December 20, 2001
头文件和库文件的例子
(NB. 这只是个例子.)
___________________ Declarations Header: Excel.sbh ___________________
'##############################################################################
'# Excel Function Library v4.0 Library Header File
'# ===========================
'#
'# DEscrīptION:
'# Contains functions that utilize Excel's COM Automation interface to use
'# spreadsheets. See Excel.sbl for library details.
'#
'# PACKAGE:
'# Excel.sbh Library Header File
'# Excel.sbl Source Code and Documentation
'# Excel_X.sbh Library Include File
'#
'# HISTORY:
'# Orig Author: Andy Tinkham <andy@tinkham.org>
'# Orig Date : 12-10-98
'#
'# Error Handling Code by Mark Butler (MKButler@russell.com) and Andy Tinkham
'#
'# CHANGES:
'# 00/00/00 Author Change details
'#
'# COPYRIGHT:
'# This code is copyright 1998-2002 by Andy Tinkham <andy@tinkham.org>.
'# except where otherwise indicated. Permission is given for use by the
'# Rational TeamTest community. Redistribution is allowed as long as no charge
'# is made for this code and all authorship credits remain intact.
'##############################################################################
'# CONSTANTS, VARIABLES, DATATYPES
'$Include "Excel_X.sbh"
'# EXPORTED FUNCTIONS
Declare Function ReadExcelDataSingle BasicLib "excel" (sFileName As String, _
sCell As String, Optional vSheet As Variant) As String
Declare Function ReadExcelData BasicLib "excel" (sFileName As String, _
sData() As String, Optional vSheet As Variant, Optional vRange As _
Variant, Optional vCell As Variant, Optional vColumnHeaders As Variant) As Integer
Declare Function WriteExcelDataSingle BasicLib "excel" (sFileName As String, _
sCell As String, vValue As Variant, Optional vSheet As Variant) As Integer
Declare Function WriteExcelData BasicLib "excel" (sFileName As String, _
sCell As String, vValues() As String, Optional vSheet As Variant) As Integer
Declare Function RetrieveNamedRanges BasicLib "excel" (sFileName As String, _
sResults() As String, Optional vSkipBuiltIns As Variant) As Integer
Declare Function VerifyNamedRanges BasicLib "excel" (larstrUsedNames() As String, _
lstrFileName As String) As Integer
Declare Sub SortCSVFileInExcel BasicLib "excel" (i_strCSVFile As String, _
i_strCellToSortBy As String, Optional i_varSecondCellToSortBy As Variant)
Declare Function GetWorksheets BasicLib "excel" (sFileName As String, _
sWorksheets() As String) As Integer
Testing Guidelines Rational Robot
Paul Downes (Paul_Downes@providian.com)
Carl Nagle (Carl.Nagle@sas.com)
8 December 20, 2001
___________________ Constants Header: Excel_c.sbh ___________________
'##############################################################################
'# Excel.sbl Function Library v4.0 Library Include File
'# ===============================
'#
'# DEscrīptION:
'# See Excel.sbl for library details.
'#
'# PACKAGE:
'# Excel.sbh Library Header File
'# Excel.sbl Source Code and Documentation
'# Excel_X.sbh Library Include File
'#
'# HISTORY:
'# Orig Author: Andy Tinkham <andy@tinkham.org>
'# Orig Date : 12-10-98
'#
'# COPYRIGHT:
'# This code is copyright 1998-2002 by Andy Tinkham <andy@tinkham.org>.
'# except where otherwise indicated. Permission is given for use by the
'# Rational TeamTest community. Redistribution is allowed as long as no charge
'# is made for this code and all authorship credits remain intact.
'##############################################################################
'# LIBRARY CONSTANTS
Const sqaFailure = -1
Const FileFormat_Xl7 = &H27
Const FileFormat_Xl9795 = &H2B
'# USER-DEFINED TYPES
'# GLOBAL VARIABLES
Global objExcel as Object
Global bPersistExcelObj as Integer
Testing Guidelines Rational Robot
Paul Downes (Paul_Downes@providian.com)
Carl Nagle (Carl.Nagle@sas.com)
9 December 20, 2001
_________________________ Library: Excel.sbl _________________________
'##############################################################################
'# Excel Function Library v4.0 Library Header File
'# ===========================
'#
'# DEscrīptION:
'# Contains functions that utilize Excel's COM Automation interface to use
'# spreadsheets. See Excel.sbl for library details.
'#
'# ReadExcelDataSingle Retrieves the value from a single cell
'# ReadExcelData Retrieves the values from a range of cells
'# WriteExcelDataSingle Writes a value to a cell on a specified sheet
'# WriteExcelData Writes array of values to range on specified sheet
'# RetrieveNamedRanges Return array of named ranges in specified workbook
'# VerifyNamedRanges Verify named ranges used by a scrīpt are available
'# SortCSVFileInExcel Open CSV file and sort data by one or two columns
'# GetWorksheets Retrieve list of worksheets in a specfied workbook
'#
'# PACKAGE:
'# Excel.sbh Library Header File
'# Excel.sbl Source Code and Documentation
'# Excel_X.sbh Library Include File
'#
'# HISTORY:
'# Orig Author: Andy Tinkham <andy@tinkham.org>
'# Orig Date : 12-10-98
'#
'# Error Handling Code by Mark Butler (MKButler@russell.com) and Andy Tinkham
'#
'# CHANGES:
'# 04/22/99 Andy Tinkham Added RetrieveNamedRanges
'# 04/26/99 Andy Tinkham Added VerifyNamedRanges
'# 10/15/99 Andy Tinkham Added SortCSVFileInExcel
'# 06/30/01 Paul Downes Added GetWorksheets function
'# 07/22/01 Paul Downes Added persistent Excel object code
'#
'# COPYRIGHT:
'# This code is copyright 1998-2002 by Andy Tinkham <andy@tinkham.org>.
'# except where otherwise indicated. Permission is given for use by the
'# Rational TeamTest community. Redistribution is allowed as long as no charge
'# is made for this code and all authorship credits remain intact.
'##############################################################################
'# Some portions of this code provided by and copyright of:
'#
'# Paul Downes, Providian Financial <paul_downes@providian.com>
'#
'# OPTIONS
Option Explicit
Option Compare Text
'# CONSTANTS
Const xlNormal = &HFFFFEFD1
Const xlLocalSessionChanges = 2
'# IMPORTED FUNCTIONS
'$Include "Excel_X.sbh"
'$Include "SQAutil.sbh"
'$Include "FileSysUtils.sbh"
'# EXTERNAL DEPENDENCIES
Declare Function GetPrivateProfileString Lib "kernel32" Alias "GetPrivateProfileStringA" _
(ByVal lpApplicationName As String, ByVal lpKeyName As String, ByVal lpDefault As _
String, ByVal lpReturnedString As String, ByVal nSize As Long, ByVal _
lpFileName As String) As Long
Declare Function GetWindowsDirectory Lib "kernel32" Alias "GetWindowsDirectoryA" _
(ByVal lpBuffer As String, ByVal nSize as Long) As Long
Testing Guidelines Rational Robot
Paul Downes (Paul_Downes@providian.com)
Carl Nagle (Carl.Nagle@sas.com)
10 December 20, 2001
'# FORWARD DECLARATONS
Declare Function GetWorksheets (sFileName As String, sWorksheets() As String) As Integer
'############################################################################
'# Function GetWorksheets
'# =============
'#
'# DEscrīptION:
'# Retrieve a list of the worksheets in a specfied workbook (Excel file).
'# Returns an array (base = 1) of the worksheet names, and the no. of sheets.
'#
'# *** TO-DO: validate file type
'#
'# EXAMPLES:
'# Dim sWorksheets() as String
'# Dim iWorksheetCount as Integer
'#
'# iWorksheetCount = GetWorksheets("C:\Test\MyWorkbook.xls", sWorksheets())
'#
'# PARAMETERS:
'# [In] sFileName Excel workbook file name
'# [Out] sWorksheets() Array of worksheet names
'#
'# RETURNS:
'# Number of worksheets in the workbook, if successful; else, -1
'#
'# ERRORS:
'# none
'#
'# HISTORY:
'# Orig Author: Paul Downes, Providian Financial (paul_downes@providian.com)
'# Orig Date : 06/30/01
'#
'# Change History:
'# Date Author Details
'# -------- ----------- ------------------------
'# 07/22/01 Paul Downes Added support for persistent Excel object
'#
'############################################################################
Function GetWorksheets (sFileName As String, sWorksheets() As String) As Integer
Dim Result as Integer
Etc.

可用的库文档
SQAPublisher
作者 ：Carl Nagle
Carl.Nagle@sas.com
http://groups.yahoo.com/group/RobotDDEUsers/files/Doc/sqabasic2000/SQAPublisher.htm

DocRipper
作者：Teresa Dowd
teresa_dowd@spectramarketing.com
http://groups.yahoo.com/group/RationalUsers/files/Misc/DocRipper.zip

SQA共通目录（7.x到2000）
Rational/SQA TeamTest v7.x版本, 在Administrator程序中设置公有SQA Robot库文件目录，这些可以被所有仓库和工程使用。V7.X版本，每一个仓库都有分开库目录。Administrator程序很容易设置公有目录。不管怎样，工作区是仓库和公有目录间中设置共享库注册适合的地方，Robot注册关键，设置SQABasic32目录地址，也就是存放公有目录的地方。很简单的方法是创建.REG文件来设置，调用该文件；例子如下：
___________________ SetCommonSQADir.reg ___________________
REGEDIT4
[HKEY_CURRENT_USER\Software\Rational Software\Rational Test\7\Robot\Robot]
"SQABasic32 Directory"="\\\\test_dev01\\data\\ratrepo\\sqabas32.common"
____________________________________________________________
同样, "UnSetCommonSQADir.reg"文件可以撤销设置. 推荐用网路路径，这样做要比驱动器映射要好得多。通过这种设置公有或者本地仓库库目录的选择方式是独占形式的。共有目录是适当的环境这样robot库的维护是集中的。个别用户在共享目录中都可以创建任何库文件。
混合公有和本地库文件的地方，共有目录将不能在注册表中设置。共有目录必须保存在网络共享目录中。建议测试脚本中指定’$Include包含网路路径的库文件。不过用common/sbh头文件对于每个本地库文件目录更加简单，这样做相当于”Global.sbh”头文件的声明方式（请看前面部分的第七点）
例如，设置如下:
UNC 库文件目录
Common\\test_svr\data\sqabas32.commonADO.sbh/sbx(1)
Excel.sbh/sbx
Etc.
Local\\test_svr\data\ratrepo\projname\sqabas32Common.sbh
Projname.sbh/sbl
Etc.
Rational Robot测试指导
Paul Downes (Paul_Downes@providian.com)
Carl Nagle (Carl.Nagle@sas.com)
13 December 20, 2001
The "Common.sbh" header would reference the shared library headers using the UNC path:
___________________ Common.sbh ___________________
'$Include "\\test_svr\data\sqabas32.common\ADO.sbh"
'$Include "\\test_svr\data\sqabas32.common\Excel.sbh
Etc.
___________________________________________________
共享投文件不许用unc路径指定, 比如:
_____________________ ADO.sbh _____________________
Declare Function ReadADOData BasicLib "\\test_svr\data\sqabas32.common\ADO" _
(i_strConnectStr As String, i_strSQL As String, o_strDBData() As String) _
As Integer
Etc.
___________________________________________________
备注:
(1) 远程库文件(i.e. 不再本地库目录中) 必须经过编译.
(2) 应用以上方法，当调试共有库例程的时候可能会产生“找不到文件”的错误信息.