Inscribe User s Guide

Transcription

1 Inscribe User s Gide Copyright 1998 Pervasive Software Inc. All rights reserved worldwide. Reprodction, photocopying, or transmittal of this pblication, or portions of this pblication, is prohibited withot the express prior written consent of the pblisher, nless sch reprodction, photocopying, or transmittal is part of a Derivative Software Prodct as defined in the licenses granted in conjnction with the prchase of this pblication and associated software. This prodct incldes software developed by Powerdog Indstries Powerdog Indstries. All rights reserved. Pervasive Software Inc Capital of Texas Highway Astin, Texas USA

2 disclaimer trademarks PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN "AS IS" BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS. Btrieve and XQL are registered trademarks of Pervasive Software Inc. Bilt on Btrieve, Bilt on Scalable SQL, Client/Server in a Box, DDF Ease InstallScot, MicroKernel Database Engine, MicroKernel Database Architectre, Navigational Client/Server, Pervasive.SQL, Scalable SQL, Smart Components, Smart Component Management, Smart Naming, SmartScot, and Xtrieve PLUS are trademarks of Pervasive Software Inc. Microsoft, MS-DOS, Windows, Windows NT, Win32, Win32s, and Visal Basic are registered trademarks of Microsoft Corporation. Windows 95 is a trademark of Microsoft Corporation. NetWare and Novell are registered trademarks of Novell, Inc. NetWare Loadable Modle, NLM, Novell DOS, Transaction Tracking System, and TTS are trademarks of Novell, Inc. All company and prodct names are the trademarks or registered trademarks of their respective companies. Inscribe User s Gide Febrary 1998

3 Contents Abot This Manal Organization Conventions Introdction Featres Components System Reqirements Inscribe Environment Configrations Local Workstation Configration Server-Based Configration Client/Server Configration Development Procedre SBL Development Tools Langage Overview Data Types Data Type Conversions VARIANT Data Type Arrays Nmbers Records Strings Argments Dialog Boxes Defining a Dialog Box Inscribe User s Gide 3 Contents

4 Writing a Dialog Fnction Displaying the Dialog Box Dialog Box Fnctions and Statements Dynamic Data Exchange Object Handling Creating an Object Variable Using Methods and Properties Expressions Nmeric Operators String Operators Comparison Operators Logical Operators Error Handling Trapping Errors SBL Retrns Trapping Errors Within Code Trapping Errors Using an Error Handler Trapping User-Defined Errors Derived Trigonometric Fnctions Statements and Fnctions A SBL and Visal Basic B Inscribe Ttorial Compiling an SBL Script Debgging a Compiled Modle Execting a Compiled Modle C Errors D Calling Exectable Programs from Inscribe Inscribe User s Gide 4 Contents

5 Figres 1-1 Local Workstation Configration Server-Based Configration Client/Server Configration SBLDemo Handling Objects Trapping Errors Trapping User-Defined Errors: Option Trapping User-Defined Errors: Option Inscribe User s Gide 5 Figres

6 Tables 1-1 Fnctional Platform Spport Nmeric Operators String Operators Comparison Operators Logical Operators...45 A-1 Visal Basic v3.0 Constrcts Not Spported by SBL...72 A-2 Visal Basic v4.0 Constrcts Not Spported by SBL...73 Inscribe User s Gide 6 Tables

7 Abot This Manal This manal is intended for software developers sing Inscribe to develop scripts and integrate them with Pervasive Software s database applications. Inscribe ses the Softbridge Basic Langage (SBL), also described in this manal. Yo se Inscribe and SBL to create scripts that atomate a variety of daily tasks. Pervasive Software wold appreciate yor comments and sggestions abot this manal. Please complete the User Comments form that appears at the back, and fax or mail it to Pervasive Software, or send to docs@pervasive.com. Inscribe User s Gide 7 Abot This Manal

8 Organization The following list briefly describes each chapter and appendix in the manal: Chapter 1 Introdction This chapter introdces the Inscribe Interface Engine and Developer Kit. Chapter 2 Langage Overview This chapter describes the essential rles and components of SBL. Chapter 3 Statements and Fnctions This chapter provides a qick reference for the SBL statements and fnctions. Appendix A SBL and Visal Basic This appendix compares SBL with Microsoft Visal Basic. Appendix B Inscribe Ttorial This appendix provides a ttorial for sing the SBL Developer Kit. Appendix C Errors This appendix provides information abot Inscribe error codes. Appendix D Calling Exectable Programs from Inscribe This appendix provides information for Windows NT developers abot how to directly call exectable programs sing the external procedres featre in Scalable SQL 4. This manal also incldes a glossary and an index. Inscribe User s Gide 8 Abot This Manal

9 Conventions Unless otherwise noted, command syntax, code, and code examples se the following conventions: Case Commands and reserved words typically appear in ppercase letters. Unless the manal states otherwise, yo can enter these items sing ppercase, lowercase, or both. For example, yo can type MYPROG, myprog, or MYprog. [ ] Sqare brackets enclose optional information, as in [log_name]. If information is not enclosed in sqare brackets, it is reqired. A vertical bar indicates a choice of information to enter, as in [file name]. < > Angle brackets enclose mltiple choices for a reqired item, as in /D=<5 6 7>. variable Words appearing in italics are variables that yo mst replace with appropriate vales, as in file name.... An ellipsis following information indicates yo can repeat the information more than one time, as in [parameter...]. ::= The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b. Inscribe User s Gide 9 Abot This Manal

10 chapter 1 Introdction Inscribe is a development technology that helps yo create and rn scripts for se with Scalable SQL s external procedres featre. External procedres allow yo to access applications external to a database while yo perform internal database operations. Inscribe ses Softbridge Basic Langage (SBL), a programming langage compatible with Visal Basic, to create scripts. This chapter contains the following sections: Featres Components System Reqirements Inscribe Environment Configrations Development Procedre SBL Development Tools Inscribe User s Gide 10 Introdction

11 Featres Inscribe offers the following featres: Allows yo to distribte application logic by spporting client/server technology. Using external procedres written in Inscribe, yo can divide application logic between client and server systems, allowing data processing to execte on the same system as the database. Allows yo to access external applications (sch as and spreadsheets) and external devices (sch as printers). Yo can also write scripts to qery a Scalable SQL database and convert the data into an HTML docment. Allows yo to move compiled scripts that yo write withot platform-dependent code (sch as message and dialog boxes) to all Scalable SQL platforms with little or no modification. (See Table 1-1 on page 12.) Allows yo to write scripts that se an ODBC interface. This compatibility with ODBC enables yo to access a wide variety of databases. Note Any scripts that yo write for an ODBC interface spport only the Microsoft platforms: Windows v3.x, Windows NT, and Windows 95. Provides a graphical interface for compiling, editing, and debgging SBL scripts with the SBL Development Tools. Inscribe User s Gide 11 Introdction

12 Table 1-1 lists the platforms spported for each fnctional grop. In addition, the following fnctional grops are spported on all platforms: Arrays, Compiler Directives, Control Flow, Dates and Times, Declarations, Errors, Files, Math Fnctions, Strings, Variants. Table 1-1 Fnctional Platform Spport Fnctional Grop Windows v3.x Windows 95 Windows NT NetWare Dialog Boxes Dynamic Data Exchange (DDE) Environmental Control m Objects ODBC Screen Inpt/Otpt z m Date statement, Command, and Randomize only z Beep, Inpt fnction/statement, and Print only Inscribe User s Gide 12 Introdction

13 Components Inscribe has two pieces bndled with Scalable SQL, as follows: The Inscribe engine is bndled with the Scalable SQL engine. The Inscribe engine validates the argments passed to Inscribe procedres. It is mltithreaded and spports mltiple concrrent external procedre calls. It rns on the same machine where Scalable SQL rns, tightly copling yor application logic to yor database. The Inscribe engine incldes an SBL Interpreter, which loads and exectes Inscribe procedres. Like the engine, the SBL Interpreter is mlti-threaded and rns on the same machine where Scalable SQL rns. It provides an optimized environment for execting Inscribe procedres and retrning otpt vales to the engine. The Inscribe Developer Kit is bndled with the Scalable SQL Programming Interfaces. It contains the SBL Development Tools, which inclde an interactive tility that lets yo edit, compile, and debg SBL scripts for bndling with yor applications. Its featres inclde Console and Variables windows for tracing code, code animation, breakpoints, and a dialog resorce editor. The Inscribe Developer Kit also contains a set of ttorial files that help yo create an SBL program that yo can execte from a Scalable SQL trigger. Inscribe User s Gide 13 Introdction

14 System Reqirements The Inscribe engine rns on Windows NT and NetWare operating environments. The SBL Development Tools rn on Windows v3.x, Windows NT, and Windows 95 operating environments. Windows 3.x and Windows 95 are development environments only. This limitation means that yo can only execte or test fnctionality in these environments that is not dependent on the presence of the Scalable SQL engine. All Inscribe engine platforms can execte the applications yo compile with the Development Tools as long as the code does not contain platform-dependent code, sch as dialog boxes. For example, if yo want to rn scripts with identical behavior on Windows NT and NetWare, then yo mst inclde only fnctions that are spported on both platforms. See Table 1-1 on page 12 for more information abot platform spport. Inscribe User s Gide 14 Introdction

15 Inscribe Environment Configrations When yo se Inscribe to execte scripts associated with a database, the Inscribe engine mst rn on the same machine that rns the Scalable SQL engine. In addition, the compiled modles mst be located in the same directory where the.ddf files for the database are located. (That is, the.ddf files do not necessarily have to be on the same machine where Scalable SQL is rnning.) Given these reqirements, the following examples illstrate the possible system configrations. Local Workstation Configration The local workstation configration provides stand-alone operation. All components reside locally, and data files are stored on the workstation s disk drive. Figre 1-1 Local Workstation Configration Yor Application Inscribe Engine Scalable SQL Engine Database Inscribe User s Gide 15 Introdction

16 Server-Based Configration In the server-based configration, all components reside on the server, and data files are stored on the server. Alternatively, the data files cold reside on another server. Figre 1-2 Server-Based Configration Yor Application Inscribe Engine Scalable SQL Engine Database Inscribe User s Gide 16 Introdction

17 Client/Server Configration Yo can set p a client/server configration in which the Inscribe and Scalable SQL engines rn on a server and yor application rns on a client workstation. In this client/ server environment, yor client application can execte Inscribe scripts on the server, bt not on the client. Figre 1-3 Client/Server Configration Inscribe Engine Scalable SQL Engine Yor Application Database Inscribe User s Gide 17 Introdction

18 Development Procedre In general, to develop Inscribe scripts with Scalable SQL, follow these steps: 1. Using the SBL Development Tools, create a Visal Basic compatible script and compile it to create a modle. 2. Copy the compiled modle to the directory that contains the Scalable SQL dictionary (.DDF) files. 3. Using Scalable SQL, isse CREATE PROCEDURE...EXTERNAL statements to define external procedre references for the modle. This information is stored in the X$Proc system table (PROC.DDF file). Refer to the SQL Langage Reference for more information abot this system table and CREATE PROCEDURE syntax. 4. Invoke yor script from the database sing any of the following: w w w Direct Scalable SQL CALL statements Internal stored procedres that execte CALL statements Scalable SQL triggers that execte CALL statements Scalable SQL checks the procedre argments against the procedre prototype and invokes the Inscribe engine to process the call. The Inscribe engine exectes the procedre with the SBL Interpreter and retrns any otpt argments to the caller. Scalable SQL passes on any errors the Inscribe engine retrns and pdates the otpt argments if no errors are retrned. For more information abot Inscribe stats codes, refer to the Stats Codes and Messages manal. Inscribe User s Gide 18 Introdction

19 SBL Development Tools SBLDemo, one of the SBL Development Tools, allows yo to edit, compile, and debg SBL scripts. Figre 1-4 shows the main screen. For more information abot sing the Inscribe Developer Kit, refer to Appendix B, Inscribe Ttorial and the online help. Inscribe User s Gide 19 Introdction

20 Figre 1-4 SBLDemo Inscribe User s Gide 20 Introdction

21 chapter 2 Langage Overview This chapter describes the essential rles and components of the Softbridge Basic Langage (SBL). It contains the following sections: Data Types Arrays Nmbers Records Strings Argments Dialog Boxes Dynamic Data Exchange Object Handling Expressions Error Handling Derived Trigonometric Fnctions Inscribe User s Gide 21 Langage Overview

22 Data Types SBL spports standard Basic nmeric, string, record, and array data. SBL also spports Dialog Records and Objects that the application defines. Yo can declare data types for variables implicitly or explicitly, as follows: Implicitly on first reference by sing a type character. Implicitly on first reference by omitting the type character, in which case the defalt type of VARIANT is assmed. Explicitly by sing the Dim statement. Yo mst explicitly declare variables of a ser-defined type. In any case, the variable can contain data of the declared type only. Data Type Conversions Basic performs atomatic data conversions in the following cases: Between any two nmeric types When converting from a larger type to a smaller type (for example, LONG to INTEGER), a rntime nmeric overflow may occr. Sch an error indicates that the nmber of the larger type is too large for the target data type. Loss of precision is not a rn-time error (for example, when converting from doble to single, or from either FLOAT type to either INTEGER type). Inscribe User s Gide 22 Langage Overview

23 Between fixed strings and dynamic strings When converting a fixed string to dynamic, Basic creates a dynamic string that has the same length and contents as the fixed string. When converting from a dynamic string to a fixed string, Basic may make some adjstments. If the dynamic string is shorter than the fixed string, the reslting fixed string is extended with spaces. If the dynamic string is longer than the fixed string, the reslting fixed string is a trncated version of the dynamic string. String conversions do not case rn-time errors. Between VARIANT and any other data type When reqired, Basic converts VARIANT strings to nmbers. A type mismatch error occrs if the VARIANT string does not contain a valid representation of the reqired nmber. No other implicit conversions are spported. In particlar, Basic does not atomatically convert between nmeric and string data. Use the fnctions Val and Str$ for sch conversions. For more information abot these and other fnctions, refer to the SBL online help. VARIANT Data Type Yo can se the VARIANT data type to define variables that contain any type of data. Yo store a tag with the VARIANT data to identify the type of data that it crrently contains. Yo can examine the tag sing the VarType fnction. The following table describes the tags and their meanings. Tag Name Size of Data Range 0 (Empty) 0 N/A Inscribe User s Gide 23 Langage Overview

24 Tag Name Size of Data Range 1 Nll 0 N/A 2 Integer 2 bytes (short) to Long 4 bytes (long) E9 to 2.147E9 4 Single 4 bytes (float) E38 to E-45 (negative) 1.401E-45 to 3.402E38 (positive) 5 Doble 8 bytes (doble) E308 to -4.94E-324 (negative) 4.94E-324 to 1.797E308 (positive) 6 Crrency 8 bytes (fixed) E14 to 9.223E14 7 Date 8 bytes (doble) Jan 1st, 100 to Dec 31st, String 0 to 32 KB 0 to 32,767 characters 9 Object N/A N/A Any newly-defined VARIANT is Empty by defalt, which signifies that the variable contains no initialized data. An Empty VARIANT converts to zero when sed in a nmeric expression and to an empty string in a string expression. Yo can test whether a VARIANT is ninitialized (that is, Empty) with the IsEmpty fnction. Nll VARIANTs have no associated data and serve only to represent invalid or ambigos reslts. Yo can test whether a VARIANT contains a nll vale with the IsNll fnction. Nll is not the same as Empty, which indicates that a VARIANT has not yet been initialized. Inscribe User s Gide 24 Langage Overview

25 Arrays Yo create arrays by specifying one or more sbscripts at declaration or ReDim time. Sbscripts specify the beginning and ending index for each dimension. If yo specify an ending index only, the beginning index depends on the Option Base setting. Yo reference array elements by enclosing the appropriate nmber of index vales in parentheses after the array name, as follows: arrayname(a,b,c) Dynamic arrays differ from fixed arrays in that yo do not specify a sbscript range for the array elements when yo specify the array s dimension. Instead, yo set the sbscript range sing the Redim statement. With dynamic arrays, yo can set the size of the array elements based on other conditions in yor procedre. For example, yo might want to se an array to store a set of vales the ser enters, bt yo do not know in advance how many vales the ser has. In this case, yo dimension the array withot specifying a sbscript range and then execte a ReDim statement each time the ser enters a new vale. Alternatively, yo can prompt for the nmber of vales a ser has and execte one ReDim statement to set the size of the array before prompting for the vales. If yo se ReDim to change the size of an array and yo want to preserve the contents of the array at the same time, be sre to inclde the Preserve argment to the ReDim statement. If yo se Dim on a dynamic array before sing the array, the maximm nmber of dimensions the array can have is 8. To create dynamic arrays with more dimensions (p to 60), do not se Dim on the array at all; instead, se only the ReDim statement inside yor procedre. For more information abot the Dim and ReDim statements, refer to the SBL online help. Inscribe User s Gide 25 Langage Overview

26 The following procedre ses a dynamic array, varray, to hold cash flow vales the ser enters: Sb main Dim aprate as Single Dim cflowper as Integer Dim msgtext Dim x as Integer Dim netpv as Doble cflowper=inptbox("enter nmber of cash flow periods") For x= 1 to cflowper varray(x)=inptbox("enter cash flow amont for & period #" & x & ":") Next x aprate=inptbox("enter discont rate: ") If aprate>1 then aprate=aprate/100 End If netpv=npv(aprate,varray()) msgtext="the net present vale is: " msgtext=msgtext & Format(netpv, "Crrency") MsgBox msgtext End Sb Inscribe User s Gide 26 Langage Overview

27 Nmbers Nmeric vales are always signed. The following table shows the valid ranges of vales. Type From To Integer -32,768 32,767 Long -2,147,483,648 2,147,483,647 Single e e-45, (negative) 0.0, e e+38 (positive) Doble d d-308, (negative) 0.0, d d+308 (positive) Crrency -922,337,203,685, ,337,203,685, Basic has no tre Boolean variables. Basic considers 0 to be FALSE and any other nmeric vale to be TRUE. Yo can only se nmeric vales as Booleans. Comparison operator expressions always retrn 0 for FALSE and -1 for TRUE. Yo can express integer constants in decimal, octal, or hexadecimal notation. Yo express decimal constants by sing the decimal representation. To represent an octal vale, precede the constant with &O or &o (for example, &O177). To represent a hexadecimal vale, precede the constant with &H or &h (for example, &H8001). Inscribe User s Gide 27 Langage Overview

28 Records A record, or record variable, is a data strctre that contains one or more elements, each of which has a vale. Before declaring a record variable, yo mst define a type. Once yo define the type, yo can declare the variable to be of that type. The variable name shold not have a type character sffix. Yo reference record elements sing dot notation, as follows: varname.elementname Records can contain elements that are themselves records. Dialog records look like any other ser-defined data type. Yo reference elements sing the recname.elementname syntax, where recname is the previosly defined record name and elementname is a member of that record. The difference is that each element is tied to an element of a dialog. The application defines some dialogs; the ser defines others. Inscribe User s Gide 28 Langage Overview

29 Strings Basic strings can be either fixed or dynamic. In either case, strings can vary in length from 0 to 32,767 characters. For fixed strings, yo specify a length when yo define the string, and yo cannot change the length. Also, yo cannot define a fixed string of zero length. Dynamic strings have no specified length. There are no restrictions on the characters yo can inclde in a string. For example, yo can embed in strings the character whose ASCII vale is 0 (NULL). Inscribe User s Gide 29 Langage Overview

30 Argments Yo list argments after the sbrotine or fnction to which they apply. Whether yo enclose the argments in parentheses depends on how yo want to pass the argment to the sbrotine or fnction: either by vale or by reference. If yo pass an argment by vale, the variable sed for that argment retains its vale when the sbrotine or fnction retrns to the caller. If yo pass an argment by reference, the variable s vale is likely to change for the calling procedre. For example, sppose yo set the vale of variable x to 5 and pass x as an argment to a sbrotine, named Mysb. If yo pass x by vale to Mysb, the vale of x is always 5 after Mysb retrns. However, if yo pass x by reference to Mysb, x cold be 5 or any other vale reslting from the actions of Mysb. To pass an argment by vale, se one of the following syntax options: CALL Mysb((x)) Mysb(x) y=myfnction((x)) CALL myfnction((x)) To pass an argment by reference, se one of the following options: CALL Mysb(x) Mysb x y=myfnction(x) CALL myfnction(x) Yo can declare external sbrotines and fnctions (sch as DLL fnctions) to accept argments by vale. In this case, those argments are always passed by vale. Inscribe User s Gide 30 Langage Overview

31 When yo call a sbrotine or fnction that takes argments, yo sally spply vales for those argments by listing them in the order shown in the syntax for the statement or fnction. For example, sppose yo define a fnction as follows: Myfnction(id, action, vale) This syntax shows that the fnction called Myfnction reqires three argments: id, action, and vale. When yo call this fnction, yo spply those argments in the order shown. If the fnction contains jst a few argments, it is fairly easy to remember the order of each of the argments. However, if a fnction has several argments and yo want to be sre the vales yo spply are assigned to the correct argments, se named argments. Named argments are identified by name rather than by position in the syntax. To se a named argment, se the following syntax: namedarg := vale Using this syntax for Myfnction reslts in the following: Myfnction id:=1, action:="get", vale:=0 The advantage of named argments is that yo do not need to remember the original order in which they are listed in the syntax, so the following fnction call is also correct: Myfnction action:="get", vale:=0, id:=1 Named argments have another advantage when calling fnctions or sbrotines that have a mix of reqired and optional argments. Ordinarily, yo need to se commas as placeholders in the syntax for the optional argments that yo do not se. With named Inscribe User s Gide 31 Langage Overview

32 argments, however, yo can specify jst the argments yo want to se and their vales and forget abot their order in the syntax. For example, Myfnction is defined as follows: Myfnction(id, action, vale, conter) In this syntax, yo can se named argments in either of the following forms: Myfnction id:="1", action:="get", vale:="0" Myfnction vale:="0", conter:="10", action:="get", id:="1" Note Althogh yo can shift the order of named argments, yo cannot omit reqired argments. All SBL fnctions and statements accept named argments. In the SBL online help, the argment names are listed in the syntax for each statement and fnction. Inscribe User s Gide 32 Langage Overview

33 Dialog Boxes To create and rn a dialog, complete these steps: 1. Define a dialog record sing the Begin Dialog...End Dialog statements and the dialog definition statements sch as TextBox, OKBtton. 2. Optional: Create a fnction to handle dialog interactions sing the Dialog Fnctions and Statements. 3. Display the dialog sing either the Dialog Fnction or Dialog Statement. The following example code illstrates these steps. Step 1: Define the dialog box Step 2: Write a fnction to handle dialog box interaction Declare Fnction myfnc(identifier$, action, sppvale) Sb Main Begin Dialog NEWDLG dimx, dimy, caption,..myfnc ListBox... ComboBox... OKBtton... CancelBtton... End Dialog Dim dlg as NEWDLG Dim response as Integer response=dialog(dlg) Step 3: If response=-1 then Display the dialog box 'clicked OK btton ElseIf response=0 then 'clicked Cancel btton ElseIf response>0 then 'clicked another command btton End If End Sb Fnction myfnc(identifier$, action, sppvale) '...code to handle dialog box actions End Fnction Inscribe User s Gide 33 Langage Overview

34 Defining a Dialog Box The Begin Dialog...End Dialog statements define a dialog. The last parameter to the Begin Dialog statement is the name of a fnction, prefixed by a period (.). This fnction handles interactions between the dialog and the ser. The Begin Dialog statement spplies three parameters to yor fnction: an identifier (a dialog control ID), the action taken on the control, and a vale with additional action information. Yor fnction shold have these three argments as inpt parameters. For more information abot the Begin Dialog...End Dialog statements, refer to the SBL online help. Writing a Dialog Fnction Yo can write a fnction that defines dialog behavior. For example, yor fnction cold disable a check box, based on a ser s action. The body of the fnction ses the Dlgprefixed SBL statements and fnctions to define dialog actions. Define the fnction itself sing the Fnction...End Fnction statement or declare it sing the Declare statement before sing the Begin Dialog statement. Enter the name of the fnction as the last argment to Begin Dialog. The fnction receives three parameters from Begin Dialog and retrns a vale. Retrn any vale greater than zero to leave the dialog open after the ser clicks a command btton (sch as Help). Displaying the Dialog Box Use the Dialog fnction (or statement) to display a dialog. The argment to Dialog is a variable name that yo previosly dimensioned as a dialog record. The name of the Inscribe User s Gide 34 Langage Overview

35 dialog record comes from the Begin Dialog... End Dialog statement. The retrn vales for the Dialog fnction determine which key was pressed: -1 for OK 0 for Cancel >0 for a command btton If the ser clicks Cancel, the Dialog statement retrns an error, which yo can trap with the On Error statement. Dialog Box Fnctions and Statements The fnction yo create ses the Dlg dialog fnctions and statements to maniplate the active dialog. This is the only fnction that can se these fnctions and statements. Following are the Dlg fnctions and statements: Fnction or Statement DlgControlId DlgEnable Fnction DlgEnable Statement DlgFocs Fnction DlgFocs Statement DlgListBoxArray Fnction DlgListBoxArray Statement Description Retrns nmeric ID of a dialog control. Identifies whether a control is enabled or disabled. Enables or disables a dialog control. Retrns ID of the dialog control having inpt focs. Sets focs to a dialog control. Retrns contents of a list box or combo box. Sets contents of a list box or combo box. Inscribe User s Gide 35 Langage Overview

36 Fnction or Statement DlgText Fnction DlgText Statement DlgVale Fnction DlgVale Statement DlgVisible Fnction DlgVisible Statement Description Retrns the text associated with a dialog control. Sets the text associated with a dialog control. Retrns the vale associated with a dialog control. Sets the vale associated with a dialog control. Identifies whether a control is visible or disabled. Shows or hides a dialog control. Most of these fnctions and statements take a control ID as their first argment. For example, a check box is defined with the following statement: CheckBox 20, 30, 50, 15, "My check box",.check1 With this statement, DlgEnable "Check1", 1 enables the check box, and DlgVale("Check1") retrns 1 if the check box is crrently checked, 0 if not. The IDs are case-sensitive and do not inclde the dot that appears before the ID s definition. Dialog fnctions and statements can also work with nmeric IDs. Nmeric IDs depend on the order in which yo define the dialog controls. For example, if the check box was the first control defined in the dialog record, then DlgVale(0) is eqivalent to DlgVale("Check1"). (The control nmbering begins from 0, and the Caption control does not cont.) Yo find the nmeric ID sing the DlgControlID fnction. For some controls (sch as bttons and text) the last argment in the control definition, ID, is optional. If it is not specified, the text of the control becomes its ID. For example, Inscribe User s Gide 36 Langage Overview

37 yo can refer to the Cancel btton as Cancel if its ID is not specified in the CancelBtton statement. Inscribe User s Gide 37 Langage Overview

38 Dynamic Data Exchange Dynamic Data Exchange (DDE) is a process by which two applications commnicate and exchange data. One application can be yor Basic program. To commnicate with another application, yo mst open a connection, called a DDE channel, sing the statement DDEInitiate. The application mst already be rnning before yo can open a DDE channel. To start an application, se the Shell command. DDEInitiate reqires two argments: the DDE application name and a topic name. The DDE application name is sally the name of the.exe file yo se to start the application, withot the.exe extension. For example, the DDE name for Microsoft Word is WINWORD. The topic name is sally a file name with which to retrieve or send data, althogh there are some reserved DDE topic names, sch as System. Refer to the application s docmentation for a list of available topic names. After yo have opened a channel to an application, yo can obtain text and nmbers (sing DDEReqest), send text and nmbers (sing DDEPoke), or send commands (sing DDEExecte). Becase yo have a limited nmber of channels available at once (depending on the operating system in se and the amont of memory yo have available), yo shold close the DDE channel (sing DDETerminate) when yo have finished commnicating with the application. The other DDE command available in SBL is DDEAppRetrnCode, which yo se for error checking prposes. After retrieving or sending text or execting a command, yo can se DDEAppRetrnCode to make sre the application performed the task as expected. If an error occrred, yor program can notify the ser of the error. Inscribe User s Gide 38 Langage Overview

39 Object Handling Objects are the end prodcts of a software application, sch as a spreadsheet, graph, or docment. Each software application has its own set of properties and methods that change the characteristics of an object. Properties affect how an object behaves. For example, width is a property of a range of cells in a spreadsheet, colors are a property of graphs, and margins are a property of word processing docments. Methods case the application to do something to an object. Examples are Calclate for a spreadsheet, Snap to Grid for a graph, and AtoSave for a docment. In SBL, yo have the ability to access an object and se the originating software application to change properties and methods of that object. Before yo can se an object in a procedre, however, yo mst access the software application associated with the object by assigning it to an object variable. Then yo attach an object name (with or withot properties and methods) to the variable to maniplate the object. The syntax for doing this is shown in the following code example. Inscribe User s Gide 39 Langage Overview

40 Figre 2-1 Handling Objects Step 1: Create an object variable to access the application Step 2: Use methods and properties to act on the objects Sb main Dim visio as Object Dim doc as Object Dim page as Object Dim i as Integer, doccont as Integer Set visio = GetObject(,"visio.application") If (visio Is Nothing) then Set visio = CreateObject("visio.application") If (visio Is Nothing) then MsgBox "Coldn't find visio!" Exit Sb End If doccont = visio.docments.cont For i = 1 to doccont Set doc = visio.docments(i) If doc.name = "myfile.vsd" then Set page = doc.pages(1) Exit Sb End If Next i Set doc=visio.docments.open("myfile.vsd") Set page = doc.pages(1) End Sb Note The examples shown here are specific to the VISIO software application. Object, property, and method names vary from one application to another. For more information abot the applicable names to se, refer to the software docmentation for the application yo want to access. Inscribe User s Gide 40 Langage Overview

41 Creating an Object Variable In Figre 2-1, the Dim statement creates an object variable called visio and assigns the application, VISIO, to it. The SET statement assigns the VISIO application to the variable visio sing either GetObject or CreateObject. Use GetObject if the application is already open on the Windows desktop. Use CreateObject if the application is not open. Using Methods and Properties To access an object, property, or method, se the following syntax: appvariable.object.property appvariable.object.method In Figre 2-1, visio.docments.cont is a vale retrned by the Cont method of the Docment object for the VISIO application, which is assigned to the INTEGER variable doccont. Alternatively, yo can create a second object variable and assign the Docment object to it sing VISIO s Docment method, as the SET statement shows. Inscribe User s Gide 41 Langage Overview

42 Expressions An expression is a collection of two or more terms that perform a mathematical or logical operation. The terms are sally either variables or fnctions that are combined with an operator to evalate to a string or nmeric reslt. Yo se expressions to perform calclations, maniplate variables, or concatenate strings. Expressions are evalated according to precedence order. Use parentheses to override the defalt precedence order. Following is the precedence order (from high to low) for the operators: Nmeric operators String operators Comparison operators Logical operators Nmeric Operators Following are the nmeric operators, presented in high-low precedence order: Table 2-1 Nmeric Operators Operator ^ Description Exponentiation. -,+ Unary mins and pls. *, / Nmeric mltiplication or division. For division, the reslt is a DOUBLE. Inscribe User s Gide 42 Langage Overview

43 Table 2-1 Operator Nmeric Operators contined Description \ Integer division. The operands can be INTEGER or LONG. Mod Modls or Remainder. The operands can be INTEGER or LONG. -, + Nmeric addition and sbtraction. Yo can also se the + operator for string concatenation. String Operators Following are the string operators: Table 2-2 String Operators Operator & Description String concatenation + String concatenation Comparison Operators Following are the comparison operators; these operators can operate on nmeric and string data. Table 2-3 Comparison Operators Operator Description > Greater than Inscribe User s Gide 43 Langage Overview

44 Table 2-3 Operator Comparison Operators contined Description < Less than = Eqal to <= Less than or eqal to >= Greater than or eqal to <> Not eqal to For nmbers, the operands are widened to the least common type. The preferred order is as follows: 1. INTEGER 2. LONG 3. SINGLE 4. DOUBLE For strings, the comparison is case-sensitive and based on the collating seqence that the ser-specified langage ses. The reslt is 0 for FALSE and -1 for TRUE. Inscribe User s Gide 44 Langage Overview

45 Logical Operators Following are the logical operators: Table 2-4 Logical Operators Operator Not And Or Xor Eqv Imp Description Unary Not. Operand can be INTEGER or LONG. The operation is performed bitwise (one s complement). And. Operands can be INTEGER or LONG. The operation is performed bitwise. Inclsive Or. Operands can be INTEGER or LONG. The operation is performed bitwise. Exclsive Or. Operands can be INTEGER or LONG. The operation is performed bitwise. Eqivalence. Operands can be INTEGER or LONG. The operation is performed bitwise. (A Eqv B) is the same as (Not (A Xor B)). Implication. Operands can be INTEGER or LONG. The operation is performed bitwise. (A Imp B) is the same as ((Not A) OR B). Inscribe User s Gide 45 Langage Overview

46 Error Handling SBL contains three error handling statements and fnctions for trapping errors in yor program: Err, Error, and On Error. SBL retrns a code for many of the possible rn-time errors yo might enconter. Refer to Appendix C, Errors for a complete list of codes. In addition to the errors that SBL traps, yo can create yor own set of codes for trapping errors specific to yor program. For example, if yor program establishes rles for file inpt and the ser does not follow the rles, yo can create specific errors to indicate these violations. Yo can trigger an error and respond appropriately sing the same statements and fnctions yo wold se for SBL-retrned error codes. Regardless of the error trapped, yo can handle errors in one of two ways: Place error-handling code directly before a line of code where an error might occr (sch as a File Open statement). Label a separate section of the procedre jst for error handling and force a jmp to that label if any error occrs. The On Error statement handles both options. Trapping Errors SBL Retrns The following example shows the two ways to trap errors. Option 1 places error-handling code directly before the line of code that cold case an error. Option 2 contains a labeled section of code that handles any error. Inscribe User s Gide 46 Langage Overview

47 Figre 2-2 Trapping Errors Option 1: Place errorhandling code within the body of a procedre Option 2: Place errorhandling code at the end of a procedre and Goto it via a label Sb main Dim serdrive,serdir,msgtext in1: serdrive=inptbox("enter drive:",,"c:") On Error Resme Next Err=0 ChDrive serdrive If Err=68 then MsgBox "Invalid Drive. Try Again." Goto in1 End If On Error Goto Errhdlr1 in2: serdir=inptbox("enter directory:") ChDir serdrive & "\" & serdir MsgBox "New defalt directory is:" & serdrive & "\" serdir Exit Sb Errhdlr1: Select Case Err Case 75 msgtext="path is invalid." Case 76 msgtext="path not fond." Case Else msgtext="error" & Err & ":" & Error$ & "occrred." End Select MsgBox msgtext & "Try again." Resme in2 End Sb Trapping Errors Within Code The On Error statement identifies the line of code to go to in case of an error. In Option 1 of this example, the Resme Next parameter indicates that exection contines with the next line of code after the error, and the line of code to handle errors is the If statement. It ses the Err statement to determine which error code is retrned. Inscribe User s Gide 47 Langage Overview

48 Trapping Errors Using an Error Handler The On Error statement sed in Option 2 of Figre 2-2 specifies a label to jmp to in case of errors. The code segment is part of the main procedre and ses the Err statement to determine which error code is retrned. To make sre yor code does not accidentally fall throgh to the error handler, precede it with an Exit statement. Trapping User-Defined Errors Figre 2-3 and Figre 2-4 show the two ways to set and trap ser-defined errors. Both options se the Error statement to set the ser-defined error to the vale 30,000. To trap the error, option 1 places error-handling code directly before the line of code that cold case an error. Option 2 contains a labeled section of code that handles any ser-defined errors. Inscribe User s Gide 48 Langage Overview

49 Figre 2-3 Trapping User-Defined Errors: Option 1 Option 1: Place errorhandling code within the body of a procedre Sb main Dim cstname as String On Error Resme Next in1: Err=0 cstname=inptbox$("enter cstomer name:") If cstname="" then Error Select Case Err Case MsgBox "Yo mst enter a cstomer name." Goto in1 Case Else MsgBox "Undetermined error. Try again." Goto in1 End Select End If MsgBox "The name is: " & cstname End Sb Inscribe User s Gide 49 Langage Overview

50 Figre 2-4 Trapping User-Defined Errors: Option 2 Option 2: Place errorhandling code at the end of a procedre and Goto it via a label Sb main Dim cstname as String On Error Goto Errhandler in1: Err=0 cstname=inptbox$("enter cstomer name:") If cstname="" then Error End If MsgBox "The name is: " & cstname Exit Sb Errhandler: Select Case Err Case MsgBox "Yo mst enter a cstomer name." Case Else MsgBox "Undetermined error. Try again." End Select Resme in1 End Sb Inscribe User s Gide 50 Langage Overview

51 Derived Trigonometric Fnctions Yo can write several trigonometric fnctions in Basic sing the bilt-in fnctions. The following table lists several of these fnctions: Fnction Secant CoSecant CoTangent ArcSine ArcCosine ArcSecant ArcCoSecant ArcCoTangent Hyperbolic Sine Hyperbolic Cosine Hyperbolic Tangent Hyperbolic Secant Hyperbolic CoSecant Hyperbolic Cotangent Compted By: Sec(x) = 1/Cos(x) CoSec(x) = 1/Sin(x) CoTan(x) = 1/Tan(x) ArcSin(x) = Atn(x/Sqr(-x*x+1)) ArcCos(x) = Atn(-x/Sqr(-x*x+1)) ArcSec(x) = Atn(x/Sqr(x*x-1))+Sgn(x-1)* ArcCoSec(x) = Atn(x/Sqr(x*x-1))+(Sgn(x)-1)* ArcTan(x) = Atn(x) HSin(x) = (Exp(x)-Exp(-x))/2 HCos(x) = (Exp(x)+Exp(-x))/2 HTan(x) = (Exp(x)-Exp(-x))/(Exp(x)+Exp(-x)) HSec(x) = 2/(Exp(x)+Exp(-x)) HCoSec(x) = 2/(Exp(x)-Exp(-x)) HCotan(x) = (Exp(x)+Exp(-x))/(Exp(x)-Exp(-x)) Inscribe User s Gide 51 Langage Overview

52 Fnction Hyperbolic ArcSine Hyperbolic ArcCosine Hyperbolic ArcTangent Hyperbolic ArcSecant Hyperbolic ArcCoSecant Hyperbolic ArcCoTangent Compted By: HArcSin(x) = Log(x+Sqr(x*x+1)) HArcCos(x) = Log(x+Sqr(x*x-1)) HArcTan(x) = Log((1+x)/(1-x))/2 HArcSec(x) = Log((Sqr(-x*x+1)+1)/x) HArcCoSec(x) = Log((Sgn(x)*Sqr(x*x+1)+1)/x) HArcCoTan(x) = Log((x+1)/(x-1))/2 Inscribe User s Gide 52 Langage Overview

53 chapter 3 Statements and Fnctions The following table smmarizes the Softbridge Basic Langage (SBL) statements and fnctions by grop. For detailed descriptions of each of these statements and fnctions, refer to the SBL online help. Fnctional Grop Fnction Description Arrays Erase Reinitializes contents of an array. LBond ReDim UBond Retrns the lower bond of an array s dimension. Declares dynamic arrays and reallocates memory. Retrns the pper bond of an array s dimension. Compiler Directives $CStrings Treats a backslash in a string as an escape character, as in the C programming langage. $Inclde $NoCStrings Line Contination Tells the compiler to inclde statements from another file. Tells the compiler to treat a backslash as a normal character. Contines a long statement across mltiple lines. Inscribe User s Gide 53 Statements and Fnctions

54 Fnctional Grop Fnction Description Compiler Directives contined Rem Treats the remainder of the line as a comment. Dates and Times Date Fnction Retrns the crrent date. Date Statement DateSerial DateVale Day Hor IsDate Minte Month Now Second Time Fnction Time Statement Sets the system date. Retrns the date vale for year, month, and day specified. Retrns the date vale for the specified string. Retrns the day of month component of a datetime vale. Retrns the hor of day component of a datetime vale. Determines whether a vale is a legal date. Retrns the minte component of a date-time vale. Retrns the month component of a date-time vale. Retrns the crrent date and time. Retrns the second component of a date-time vale. Retrns the crrent time. Sets the crrent time. Inscribe User s Gide 54 Statements and Fnctions

55 Fnctional Grop Fnction Description Dates and Times contined Timer TimeSerial TimeVale Weekday Year Retrns the nmber of seconds since midnight. Retrns the time vale for hor, minte, and second specified. Retrns the time vale for the specified string. Retrns the day of the week for the specified date-time vale. Retrns the year component of a date-time vale. Declarations Const Declares a symbolic constant. Declare Deftype Dim Fnction...End Fnction Global Option Base Option Compare Forwardly declares a procedre in the same modle or in a dynamic link library. Declares the defalt data type for variables. Declares variables. Defines a fnction. Declares a global variable. Declares the defalt lower bond for array dimensions. Declares the defalt case sensitivity for string comparisons. Inscribe User s Gide 55 Statements and Fnctions

56 Fnctional Grop Fnction Description Declarations contined Option Explicit ReDim Static Sb...End Sb Type Forces all variables to be explicitly declared. Declares dynamic arrays and reallocates memory. Defines a static variable or sbprogram. Defines a sbprogram. Declares a ser-defined data type. Dialog boxes Begin Dialog Begins a dialog definition. Btton BttonGrop CancelBtton Caption CheckBox ComboBox Dialog Fnction Dialog Statement DlgControlId Defines a btton dialog control. Begins definition of a grop of btton dialog controls. Defines a Cancel btton dialog control. Defines the title of a dialog. Defines a check box dialog control. Defines a combo box dialog control. Displays a dialog and retrns the btton pressed. Displays a dialog. Retrns the nmeric ID of a dialog control. Inscribe User s Gide 56 Statements and Fnctions

57 Fnctional Grop Fnction Description Dialog boxes contined DlgEnable Fnction DlgEnable Statement DlgEnd DlgFocs Fnction DlgFocs Statement DlgListBoxArray Fnction DlgListBoxArray Statement DlgSetPictre DlgText Fnction DlgText Statement DlgVale Fnction DlgVale Statement DlgVisible Fnction DlgVisible Statement DropComboBox Identifies whether a dialog control is enabled or disabled. Enables or disables a dialog control. Closes the active dialog. Retrns the ID of the dialog control having inpt focs. Sets focs to a dialog control. Retrns contents of a list box or combo box. Sets contents of a list box or combo box. Changes the pictre in the pictre control. Retrns the text associated with a dialog control. Sets the text associated with a dialog control. Retrns the vale associated with a dialog control. Sets the vale associated with a dialog control. Identifies whether a control is visible or hidden. Shows or hides a dialog control. Defines a drop-down combo box dialog control. Inscribe User s Gide 57 Statements and Fnctions