十四、系统与环境函数

十四、系统与环境函数

1、Clipboard()

功  能：提取或替换Windows系统剪贴板的文本内容。

语  法：Clipboard ( { string } )

参  数：string：string类型，可选项，指定要复制到系统剪贴板上的文本。如果剪贴板上已有内容的话，该文本将取代剪贴板的当前内容。

返回值：String。函数执行成功时，如果剪贴板上包含文本数据，那么函数返回剪贴板的当前内容；如果剪贴板上包含非文本数据（比如位图）或不包含任何数据，那么函数返回空字符串（""）。如果string参数的值为NULL，Clipboard()函数返回NULL。

用  法：无论是否指定string参数，Clipboard()都将返回剪贴板的当前内容。当指定string参数时，剪贴板的原有内容被string参数的值取代；省略string参数时，仅仅得到剪贴板的内容。

示  例：1、下面的代码将剪贴板内容放置到变量ls_CoName中。

        String ls_CoName

        ls_CoName = Clipboard()

2、下面的代码字符串”春眠不觉晓”取代剪贴板原有的内容，并把它保存到变量Heading中。

String Heading

        Heading = Clipboard(”春眠不觉晓”)

 

2、CommandParm()

功  能：得到应用程序运行时指定的命令参数。

语  法：CommandParm ( )

返回值：String。函数执行成功时返回应用程序运行时的命令行参数，函数执行错误或没有命令行参数时函数返回空字符串（""）。

用  法：命令行参数是应用程序启动时跟在应用程序名称后面的任何参数，比如，在运行窗口中输入了下述命令：

MyAppl C:\EMPLOYEE\EMPLIST.TXT

那么MyAppl应用程序中使用CommandParm()函数得到的命令行参数为：

C:\EMPLOYEE\EMPLIST.TXT

当应用程序的命令行中包含几个参数时，CommandParm()函数作为一个字符串返回所有参数。利用字符串操作函数可以分离各参数。

在应用对象的Open事件中没有必要执行CommandParm()函数。此时，Open事件的argument参数中包含了命令行参数。

    示  例：string ls_cmd, ls_arg[]

integer i, li_argcnt

// Get the arguments and strip blanks

// from start and end of string

ls_cmd = Trim(CommandParm())

li_argcnt = 1

DO WHILE Len(ls_cmd) > 0

// Find the first blank

    i = Pos( ls_cmd, " ")

    // If no blanks (only one argument),

    // set i to point to the hypothetical character

    // after the end of the string

    if i = 0 then i = Len(ls_cmd) + 1

    // Assign the arg to the argument array.

    // Number of chars copied is one less than the

    // position of the space found with Pos

  ls_arg[li_argcnt] = Left(ls_cmd, i - 1)

    // Increment the argument count for the next loop

    li_argcnt = li_argcnt + 1

    // Remove the argument from the string

    // so the next argument becomes first

    ls_cmd = Replace(ls_cmd, 1, i, "")

LOOP

 

3、DoScript()

功  能：执行AppleScript程序段，该函数只在Macintosh平台上有效。

语  法：DoScript ( script, result )

参  数：script：string类型，指定要运行的程序段（script）result：string类型，由AppleScript程序段返回的结果信息或出错信息。

返回值：Integer。返回由AppleScript返回的结果代码。如果任何参数的值为NULL，DoScript()函数返回NULL。

 

4、GetApplication()

功  能：得到当前应用对象的句柄，这样你可以查询或设置应用对象的属性（通常用于编写通用代码）。

语  法：GetApplication ( )

返回值：Application。返回当前应用对象的句柄。

示  例：下面的代码得到应用对象的句柄，然后关闭工具条的跟随提示。

        Application app

        App = GetApplication()

        App.ToolbarTips = FALSE

        这段代码可以写成如下的简练形式。

        GetApplication().ToolbarTips = FALSE

 

5、GetEnvironment()

功  能：得到操作系统、处理器、屏幕显示等与系统相关的信息。

语  法：GetEnvironment ( environmentinfo )

参  数：environmentinfo：Environment对象名，用于保存系统环境信息。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果参数environmentinfo的值为NULL，GetEnvironment()函数返回NULL。

用  法：当开发交叉平台项目时，利用GetEnvironment()函数，应用程序能够得到当前运行的操作系统、使用的CPU类型、操作系统的版本、屏幕的大小以及颜色数等信息，这些信息的具体表示请参阅本书环境对象（Environment Object）的介绍。

示  例：下面的代码要启动另一个应用程序，由于在不同的操作系统中文件位置及表示方法不同、因此使用GetEnvironment()函数得到当前运行的操作类型系统，然后对不同操作系统使用不同的文件名表示方法。

string path

environment env

integer rtn

rtn = GetEnvironment(env)

IF rtn <> 1 THEN RETURN

CHOOSE CASE env.OSType

CASE aix!

    path = "/export/home/pb_apps/analyze.exe"

CASE Windows!, WindowsNT!

    path = "C:\PB_apps\analyze.exe"

CASE ELSE

RETURN

END CHOOSE

Run(path)

 

6、GetFocus()

功  能：确定当前焦点位于哪个控件上。

语  法：GetFocus ( )

返回值：GraphicObject。函数执行成功时返回当前得到焦点控件的引用，发生错误时返回无效引用。

用  法：应用程序利用IsValid()函数可以检测GetFocus()是否返回有效的控件引用。同时，使用TypeOf()函数可以确定控件的类型。

示  例：下面的代码将当前得到焦点控件的引用赋值给变量which_cont，然后把该控件的Text属性的值赋给一个变量（注意代码中使用了两个对象变量sle_which和和cb_which，目的在于引用相应对象的属性）。

GraphicObject which_control

SingleLineEdit sle_which

CommandButton cb_which

string text_value

which_control = GetFocus()

CHOOSE CASE TypeOf(which_control)

CASE CommandButton!

    cb_which = which_control

    text_value = cb_which.Text

CASE SingleLineEdit!

    sle_which = which_control

    text_value = sle_which.Text

CASE ELSE

    text_value = ""

END CHOOSE

 

7、Handle()

功  能：得到PB窗口型对象的句柄。使用该函数可以得到应用对象、窗口或控件的句柄，但不能得到绘图对象的句柄。

语  法：Handle ( objectname {,previous})

参  数：objectname：要得到句柄的PB对象的名称，该参数可以是除绘图对象外的任何PB对象的名称；

previous：Boolean类型，可选参数。它指明是否想要得到前一个应用对象实例的句柄。其有效值为：False – 返回当前实例的句柄；True --返回前一个应用对象实例的句柄。

返回值：Long。返回指定对象的句柄。如果objectname是一个应用对象，并且previous参数的值为True，那么如果不存在应用对象的前一个实例，该函数返回0。

用  法：如果你的应用程序需要在调用Windows SDK函数或需要在PB Send()函数的参数中使用对象句柄时，那么可以使用Handle()函数得到所需对象的句柄。

示  例：下面的代码得到窗口w_child的句柄，并赋给变量ll_whandle。

        Long ll_whandle

        ll_whandle = Handle(w_child)

 

8、Post()

功  能：将指定消息加入到某个窗口的消息队列中，这个窗口既可以是PowerBuilder应用的窗口，也可以是其它应用的窗口。

语  法：Post( handle, messageno, word, long )

参  数：handle：long类型，指定窗口的系统句柄，将向该窗口邮寄消息；

messageno：UnsignedInteger类型，指定要邮寄的消息号 ；

word：long类型，指定与消息一起邮寄的word类参数值。如果messageno参数指定的消息不使用该参数，那么将这个参数的值设置为0；

long：long类型或string，指定与消息一起邮寄的long型参数值或字符串。

返回值：Boolean。如果任何参数的值为NULL，Post()函数返回NULL。

用  法：Post()函数用于向窗口发送非PowerBuilder预定义事件的消息，这个窗口可以是PowerBuilder应用的窗口，也可以是其它应用的窗口。Post()函数把发送的消息放置在指定窗口消息队列的尾部，然后返回到应用程序中，它并不等待相应事件事件处理程序的执行。这一点与Send()函数不同，Send()函数直接触发指定窗口相应的事件，执行事件处理程序后返回到调用应用中。因此，我们说Post()函数采用的是异步方式，Send()函数采用的是同步方式。

Post()函数的参数handle指定接收消息的窗口句柄，对PowerBuilder窗口来说，使用Handle()函数可以得到该句柄。对其它应用程序的窗口来说，可以调用系统API函数查找窗口并得到相应窗口的句柄。

如果应用程序要邮寄PowerBuilder定义事件（包括预定义事件和用户定义事件），那么使用PostEvent()函数既简单有方便。当应用程序在long参数位置指定一个字符串时，Post()函数复制一个该字符串的副本，然后将副本的地址传送给指定窗口。

示  例：下面的代码向窗口w_date邮寄一个向下滚动一页的消息（消息号为277）。

        Post(Handle(w_date) , 277 , 3 , 0)

 

9、ProfileInt()

功  能：从初始化文件（.ini）中读取整型设置值。

语  法：ProfileInt ( filename, section, key, default )

参  数：filename：string类型，指定初始化文件的名称，可以包括路径，省略路径时，该函数按操作系统的标准路径搜索指定文件；

section：string类型，指定要得到的值所在的节（Section）；

key：string类型，指定要得到的值的名称，不用区分大小写；

default：integer类型，当指定的文件、节名、项目名不存在或不能转换为整数时，函数返回该参数指定的值。

返回值：Integer。函数执行成功时，在指定的文件、节名、项目名不存在任何错误的情况下，函数返回相应项的值；如果指定的文件、节名、项目名不存在或不能转换为整数时，函数返回default参数指定的缺省值。如果发生错误，函数返回-1。如果任何参数的值为NULL，ProfileInt()函数返回NULL。

用  法：使用ProfileInt()函数可以得到初始化文件中指定项整数设置的值。初始化文件的格式采用PB.INI文件的格式，由节和项组成，下面是PB.INI文件的一部分。

        [PB]

        CompilerWarnings = 1

        DasherInIdentifiers = 1

        DatabaseWarnings = 1

        [HELP]

        HelpOnStartup = 0

        OnLineRegistrationPath = d:\pb9\pb9\olreg

        HelpPath2 = d:\pb9\pb9

        [DataBase]

        DBMS = ODBC

        DataBase = Dgqb

        UserID = dba

        在初始化文件中，节名使用方括号括起来，项目采用下述格式：

          项目名 = 值

        在ProfileInt()函数中，指定节名和项目名时，不要带芳括号。

        如果应用程序想设置指定项目的值，那么请使用SetProfileString()函数，另外，利用ProfileInt()函数还可以得到Windows操作系统注册表指定项的值。

   示  例：假定应用程序使用C:\PB.INI初始化文件，其内容如上，那么得到PB节DatabaseWarnings项的值的语句可以写为（默认值为1）：

        rc = ProfileInt(“C:\PB.INI”,”PB”,”DatabaseWarnings”,1)

 

9、ProfileString()

功  能：从初始化文件（.ini）中读取字符串型设置值。

语  法：ProfileString ( filename, section, key, default )

参  数：filename：string类型，指定初始化文件的名称，可以包括路径，省略路径时，该函数按操作系统的标准路径搜索指定文件；

section：string类型，指定要得到的值所在的节（Section）；

key：string类型，指定要得到的值的名称，不用区分大小写；

default：string类型，当指定的文件、节名、项目名不存在时，函数返回该参数指定的值。

返回值：String。函数执行成功时，在指定的文件、节名、项目名不存在任何错误的情况下，函数返回相应项的值；如果指定的文件、节名、项目名不存在，函数返回default参数指定的缺省值。如果发生错误，函数返回空字符串。如果任何参数的值为NULL，ProfileString()函数返回NULL。

用  法：ProfileString()函数的用法与ProfileInt()函数相似，请参看ProfileInt()函数的介绍。需要注意的是，ProfileInt()函数返回的字符串的最大长度为4096字节。

示  例：1、These examples use a file called PROFILE.INI, which contains the following lines. Quotes around string values in the INI file are optional:

[Employee]

Name=Smith

[Dept]

Name=Marketing

2、This statement returns the string contained in keyword Name in section Employee in file C:\PROFILE.INI and returns None if there is an error. In the example, the return value is Smith:

ProfileString("C:\PROFILE.INI", "Employee", "Name", "None")

3、The following statements open w_marketing if the string in the keyword Name in section Department of file C:\PROFILE.INI is Marketing:

IF ProfileString("C:\PROFILE.INI", "Department", &

   "Name", "None") = "Marketing" THEN

   Open(w_marketing)

END IF

 

10、Restart()

功  能：停止所有程序段的执行、关闭所有窗口、提交事务、断开与数据库的连接，然后重新启动应用程序。

语  法：Restart()

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。

 

11、Run()

功  能：运行指定的应用程序。

语  法：Run ( string {, windowstate } )

参  数：string：string类型，指定要运行的应用程序的名称，其中可以包括路径以及相应的参数，就像在命令行中键入的那样；

windowstate：WindowState枚举类型，可选项，指定程序运行时的窗口状态。有效取值为：Maximized! - 最大化窗口；Minimized! - 最小化窗口；Normal! - 缺省值，正常窗口。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果任何参数的值为NULL，Run()函数返回NULL。

用  法：使用Run()函数，应用程序能够启动操作系统中的任何程序。当在Run()参数中指定了要启动应用程序的参数时，参数的意义、格式、个数等由具体的应用程序确定。如果在Run()函数的string参数中指定了文件名但没有给出扩展名时，PowerBuilder认为该文件的扩展名为.EXE。要运行扩展名不是.EXE的应用程序（比如.BAT, .COM, 或.PIF），必须在Run()函数的参数中指定文件的扩展名。

示  例：运行记事本程序。Run(“Notepad”)

 

12、Send()

功  能：向窗口发送指定的消息并立即执行相应的事件处理程序。

语  法：Send( handle, messageno, word, long )

参  数：handle：long类型，指定窗口的系统句柄，将向该窗口发送消息；

messageno：UnsignedInteger类型，指定要发送的消息号；

word：long类型，指定与消息一起发送的word类参数值。如果messageno参数指定的消息不使用该参数，那么将这个参数的值设置为0；

long：long类型或string，指定与消息一起发送的long型参数值或字符串。

返回值：Long。函数执行成功时返回Windows系统调用SendMessage()的返回值，发生错误时返回-1。如果任何参数的值为NULL，Send()函数返回NULL。

用  法：Send()函数用于向窗口发送非PowerBuilder预定义事件的消息，这个窗口可以是PowerBuilder应用的窗口，也可以是其它应用的窗口。Send()函数直接触发指定窗口相应的事件，执行事件处理程序后返回到调用应用中，这一点与Post()函数不同，Post()函数把发送的消息放置在指定窗口消息队列的尾部，然后返回到应用程序中，它并不等待相应事件事件处理程序的执行。因此，我们说Post()函数采用的是异步方式，Send()函数采用的是同步方式。

Send()函数的参数handle指定接收消息的窗口句柄，对PowerBuilder窗口来说，使用Handle()函数可以得到该句柄。对其它应用程序的窗口来说，可以调用系统API函数查找窗口并得到相应窗口的句柄。实际上，Send()函数把它的各个参数直接传送给Windows的系统调用SendMessage()。在各种C++开发工具的WINDOWS.H文件中可以查到各消息编号。

如果应用程序要发送PowerBuilder定义事件（包括预定义事件和用户定义事件），那么使用TriggerEvent()函数既简单有方便。

当应用程序在long参数位置指定一个字符串时，Send()函数复制一个该字符串的副本，然后将副本的地址传送给指定窗口。

示  例：1、下面的代码向窗口w_date发送一个向下滚动一页的消息（消息号为277）。

        Send(Handle(w_date) , 277 , 3 , 0)

2、下面的代码触发命令按钮cb_OK的clicked事件。

Send(Handle(parent) , 273 , 0 , Handle(cb_OK))

        Cb_OK.TriggerEvent(Clicked!)

 

13、SetProfileString()

功  能：设置初始化文件中指定项的值。

语  法：SetProfileString ( filename, section, key, value )

参  数：filename：string类型，指定初始化文件的名称，可以包括路径，省略路径时，该函数按操作系统的标准路径搜索指定文件；

section：string类型，指定要设置的值所在的节（Section）；

key：string类型，指定要设置的值的名称，不用区分大小写；

default：string类型，指定要设置项的值。

返回值：Integer。函数执行成功时返回1，指定的文件未找到或指定的文件不能访问时函数返回-1。如果任何参数的值为NULL，SetProfileString()函数返回NULL。

用  法：使用SetProfileString()函数可以设置初始化文件中指定项整数设置的值。初始化文件的格式采用PB.INI文件的格式，由节和项组成，下面是PB.INI文件的一部分。

        [PB]

        CompilerWarnings = 1

        DasherInIdentifiers = 1

        DatabaseWarnings = 1

        [HELP]

        HelpOnStartup = 0

        OnLineRegistrationPath = d:\pb9\pb9\olreg

        HelpPath2 = d:\pb9\pb9

        [DataBase]

        DBMS = ODBC

        DataBase = Dgqb

        UserID = dba

        在初始化文件中，节名使用方括号括起来，项目采用下述格式：

          项目名 = 值

        在ProfileInt()函数中，指定节名和项目名时，不要带芳括号。

        如果应用程序想得到指定项目的值，那么请使用ProfileString()函数或ProfileInt()函数。

        示  例：假定应用程序使用C:\PB.INI初始化文件，其内容如上，那么把[DataBase]节UserID项的值设置为dba的语句可以写为：

        SetProfileString(“C:\PB.INI”,”DataBase”,”UserID”,”dba”)

 

14、ShowHelp()

功  能：显示应用程序帮助，该帮助使用Microsoft Windows帮助系统进行操作。

语  法：ShowHelp ( helpfile, helpcommand {, typeid } )

参  数：helpfile：string类型，指定帮助文件的名称；

helpcommand：HelpCommand枚举类型，指定显示帮助的格式。有效取值为：Index! - 显示目录主题，使用该值时不要指定；

typeid；Keyword! - 转移到由指定关键字确定的主题；Topic! - 显示指定主题的帮助typeid：可选项，指定帮助主题。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。如果任何参数的值为NULL，ShowHelp()函数返回NULL。

示  例：1、This statement displays the Help index in the INQ.HLP file:

ShowHelp("C:\PB\INQ.HLP", Index!)

2、This statement displays Help topic 143 in the file EMP.HLP file:

ShowHelp("EMP.HLP", Topic!, 143)

3、This statement displays the Help topic associated with the keyword Part# in the file EMP.HLP:

ShowHelp("EMP.HLP", Keyword!, "Part#")

4、This statement displays the Help search window. The word in the box above the keyword list is the first keyword that begins with M:

ShowHelp("EMP.HLP", Keyword!, "M")

 

15、SignalError()

功  能：触发应用对象的SystemError事件，通常用于代码调试。

语  法：SignalError ( { number }, { text } )

参  数：number：integer类型，可选项，其值将保存到Error对象的number属性中；

text：string类型，可选项，其值将保存到Error对象的text属性中。

返回值：Integer。函数执行成功时返回1，发生错误时返回-1。

示  例：These statements set values in the Error object and then trigger a SystemError event so the error processing for these values can be tested:

int error_number

string error_text

Error.Number = 1010

Error.Text = "Salary must be a positive number."

Error.Windowmenu = "w_emp"

Error_number = Error.Number

Error_text = Error.Text

SignalError(error_number, error_text)

 

16、Yield()

功  能：将控制权转移给其它图形对象，包括非PowerBuilder对象。该函数检测消息队列，如果有消息，就把消息取出。利用该函数可以在执行耗时较长的操作时把控制权转让给其它应用。

语  法：Yield()

返回值：Boolean。如果在消息队列中提取到了消息，那么函数返回TRUE，否则返回FALSE。

用  法：正常情况下，PowerBuilder应用程序在执行一段代码（比如函数或事件处理程序）的过程中不响应用户的操作。对耗时短暂的代码段来说，这种处理方式没有什么不妥的地方，但是，如果某个代码段的执行耗时较长，应用程序又希望为用户提供更多的控制权，那么需要在这段代码中插入Yield()函数，让用户能够进行其它操作，特别在循环执行的代码中更应该如此。

应用程序执行Yield()函数后，如果发现消息队列中存在消息，它将允许对象处理这些消息，处理之后，继续Yield()函数后面代码的执行。因此，代码中插入Yield()函数将降低应用程序的运行效率。

示  例：下面的代码执行一段耗时比较长的过程，在其中我们插入了Yield()函数，当用户单击窗口上的”取消”按钮时，终止这段代码的执行，其中使用共享变量sb_interrupt来指示是否单击了”取消”按钮。

        Integer n

        //sb_interrupt是共享变量

        sb_interrupt = FALSE

        FOR n = 1 TO 3000

            Yield()

            IF sb_interrupt THEN

               //sb_interrupt的值在”取消”按钮的Clicked事件处理程序中修改

               Messagebox(“调试！”,”用户中断！”)

               Sb_interrupt = FALSE

               EXIT

            ELSE

               …  //其他处理

            END IF

        END FOR