CodeCurve User's Manual
Copyright  1999 Celtech Software

Table of Contents Field, please update in your word processor

Overview
CodeCurve is a form-based system script language for Windows95. It provides a framework of standard programming conditional statements, plus many additional features in the form of global statements and functions as well as specialty objects, powerful language extensions that provide services for a wide array of system features.
Command-Line Parameters and DOS ErrorLevel
When a .COD file executes, all command-line parameters are available in the string array Argv$[]. Determine the number of array elements using the ArraySize command To return an exit code to DOS when the .COD terminates, use the Exit command.
Missing Functions
As of December 7, 1996, CodeCurve supports properties. Properties can replace many existing functions which were used to perform Get/Set tasks. As each new property is created to replace existing functions, the help file documentation for those functions are removed. The functions themselves will continue to be supported by the engine for compatibilty, but they will not be documented.
Programming with CodeCurve
This series of topics covers most, if not all, of the material you will need to know to program with CodeCurve. For a walk-through on writing a small, but fairly sophisticated script, see Sample Script Tutorial.
Topics
Creating a New Script
Executing Scripts
Stopping Scripts
Numbers
Strings
Variables
Constants
Arrays
Structures
Methods
Properties
Testing and Branching
Dealing with Errors
Objects
Forms
User-Defined Procedures
The Windows API and Third-Party DLLs

Creating a New Script
The easiest way to create a new script is to simply open the CodeCurve script editor. The default script is always a new, empty script.
Another convenient way to create a new script is to open any Explorer folder, click on it with the right mouse button, select New and then select "CodeCurve Code File." When the new script appears, type in a useful name and press ENTER. Click on the new script with the right mouse button and select Edit to open the script in the CodeCurve editor.
See Also
COD File Basics
Executing Scripts
There are two ways to execute a script:
In the editor, press F5.
Or, in a Windows folder, double-click the script with the left mouse button.
See Also
Script Compiler
Stopping Scripts
There are a number of reasons why you would want to halt a script from executing, therefore, there are a number of ways to do it. Read further to learn the different ways to stop scripts from executing.
While running a script or compiled script
The best way to halt a script while it is running is to bring one of the script's form to the foreground and press the Pause key. This will pause the script and allow you to continue execution or terminate the script. If you decide to terminate the script, it will stop with very little chance of doing any real harm; all objects will be destroyed properly.
If pressing the Pause key does not pause your script (as is often the case if there is no form showing), simply press CTRL-ALT-DEL, select "Obasic" in the task list and click "End Task". This will generate a break message to the engine and the script will pause as though you had pressed the Pause key.
Running a script in the debugger
While debugging a script, you'll often want to stop the script to inspect variables, analyze loops and/or to just put an end to runaway code. A good way to stop a script in the debugger is to set breakpoints and let the engine stop itself. However, if your script is a runaway, the debugger gives you two options: selecting either "Pause Execution" or "Halt Execution" from the Debug menu.
The Pause key still works while debugging and it often works just as well as using the debugger to stop the script.
See Also
Debugging
Numbers
Numbers in CodeCurve are double float values with a range of 1.7E +/- 308 (15 digits). They may be expressed using literals, algebraic expressions and/or boolean expressions. You may include the use of number variables, number properties and return values from number functions anywhere in the expression. Numbers are used to set variable values, property values, as parameters to methods, and in test expressions.
See
Math Operators
Bitwise Operators
Example of a numerical expression
A# = B# - (2 * SqRoot(9)) / 3 + 1
Strings
Strings may be expressed using literals values, alone or as an expression using the '+' symbol to concatenate them. You may include the use of string variables, string properties and return values from string functions anywhere in the expression. Strings are used to set variable values, property values, as parameters to methods, and in test expressions.
When a number appears in a string expression, the value of the number is converted into an ASCII character. The example below shows ASCII value 34 (double quote character) at either end of the string expression.
Example of using numbers in a string expression
A$ = 34 + Str(C#) + ".  Now is the time " + B$ + 34
Character Escapes
An oftentimes easier way to insert quotes into string literals is to use two quotes, which will compress into a single quote in the resulting string.
Example of putting quotes a string expression
A$ = """Now is the time """
Another way to insert odd characters into a string is to use character escapes. Character escapes are special sequences which appear in the middle of a literal string that causes the sequences to condense into a single, but otherwise difficult to include, character. Character escapes take the form: "^$, where $ is a single letter from A-Z. The sequence condenses into a character, with values ranging from 1 (letter A) to 26 (letter Z).
A List of Common Character Escapes
"^C
Break signal

"^G
Alarm or bell

"^H
Backspace

"^I
Tab or indent

"^J
Newline

"^K
Vertical tab

"^L
Formfeed

"^M
Return

Variables
Variables are where values are stored during script execution. They may be of type number or string. Variables are either global or object members. You may assign values to them and later use them in any valid expression where strings or numbers are expected.
String variables must end in '$' and number variables must end in '#'. If you attempt to use a variable which has not yet been set, an error occurs.
See
Assignment Operator
Example setting and using variables
A$ = 34 + Str(C#) + ".  Now is the time " + B$ + 34
Constants
Constants are like numbers variables with one major difference: you may not set them; they maintain constant values. Another difference is you append them with the '@' symbol, rather than '#'.
Example using constants
MsgBox("Message", mbYesNo@)
Arrays
An array is a collection of values which, individually, act as variables. Like variables, they may be of type string or number. Items in the array are accessed using a subscript operator '[ ]'. A single array is maintained as an object; they are used with the subscript operator, but may also be acted upon as objects. Array objects have an entire set of methods which help you manipulate them.
To create an array use the New operator to create an object of type StringArray or NumArray. The first item in an array is always 1.
See
Array
NumArray
Example creating a new string array
New List As StringArray
Example adding a new item to the string array
List.Add "First Item"
Example setting the value of an item in a string array
List$[1] = "First Item"
Example using an item in a string array
MsgBox(List$[1])
Structures
A structure is a user-defined type which describes a single block of memory. Use the struct keyword to define structure types, and then use the Record object to create objects which make use of them.
Structures definitions always begin with the keyword struct and end with the keyword endstruct. They take the form:
struct TypeName$
  MemberName[Type# [, Size#]]
endstruct
Where MemberName is the name of a field in the structure and Type# is the field type. Enclose the Type#/Size# information in brackets '[]'. Size# is required for fields of type stString@ and stVoid@. See Structure Types for a list of the constants used to specify the field Type#.
Example
struct PersonStruct
  ID[stLong@]
  Name[stString@, 32]
endstruct

new Person as Record PersonStruct
Person.ID# = 1
Person.Name$ = "John Doe"
Structure Types
Structure Field Type Constants
stByte@
1-byte unsigned integer

stChar@
1-byte signed integer

stWord@
2-byte unsigned integer

stShort@
2-byte signed integer

stDWord@
4-byte unsigned integer

stLong@
4-byte signed integer

stSingle@
4-byte floating-point number, ranged 3.4E +/- 38 (7 digits)

stDouble@
8-byte floating-point number, ranged 1.7E +/- 308 (15 digits)

stDateTime@
Same as stDouble@, standard CodeCurve date/time value

stString@
NULL-terminated C-style string buffer, requires a Size# parameter

stVoid@
Untyped memory buffer, requires a Size# parameter

Methods
Methods are procedures that execute a particular task. They may be global or are available as members of an object. When you call a method, you may be required to provide parameter values; method descriptions appear elsewhere in this help file and will show you how to call them.
Some methods are functions. Functions return a value, either string or number. You may use functions in any valid expression where strings or numbers should appear. When you call a function, you must include parenthesis '( )' around the entire parameter set.
The other type of method is a statement. Statements are called like functions except they do not return a value and you do not provide parenthesis when calling them.
Example calling a number function
A# = B# - (2 * SqRoot(9)) / 3 + 1
Example calling a string function
A$ = 34 + Str(C#) + ".  Now is the time " + B$ + 34
Properties
Properties are similar to variables with the main exception that, typically, setting or getting usually invokes a hidden method rather than accessing a variable directly. Like variables, they may be of type number or string and can be either global or object members.
Properties, by their nature, may be read-only or write-only. In certain cases, it is not possible to set the value of a property even though it is there and can be used like a variable. In even rarer cases, you might be able to set the value of a property but not able to retrieve it.
Example setting a string property
Form.Title$ = "New Form Title"
Example using a string property
MsgBox(Form.Title$)
Example using a read-only number property
A# = Form.Handle#
Testing and Branching
Conditional and branching statements allow you to control the flow of your script. You can use If...Then...Else to test a condition, Select...Case to switch execution based on a value or simply GoTo/GoSub to a different point in the script.
See
Conditional and Branching Statements
Dealing with Errors
When an error occurs during script execution, an exception is thrown. Without special handling, exceptions cause script execution to halt. You may catch these exceptions if it possible to handle the error and continue script execution.
See
Error Handling
Objects
Objects are entities which encapsulate a related group of tasks. They are named like variables, but they have member methods, variables and properties. Objects may be members of other objects, and their syntax is the full object path starting from the highest object down to the object the operation is performed on. For example, if object Foo had one child object named Bar and Bar had a member function named Wubba(), you would call that one member function like so: Foo.Bar.Wubba().
Object collections are child objects which appear as an array of objects. Arrays share a similar name and you use a numerical index to access individual object items. They are very similar to string or number arrays, except that each item is, itself, an object rather than just a simple data item. If object Foo had an array of child objects named Bar, you would access the first Foo's Wubba() function like so: Foo.Bar{0}.Wubba(). The index parameter is wrapped in scroll braces, and indexing begins with 0. String and number arrays use the square brackets '[ ]', but object collections use scroll braces '{ }'. Object collections are typically used with OLE objects, but they may appear anywhere.
A global, or static object is one that is always available. It is created before the script begins to execute.
A dynamic object, or object type is one that must be created using New before it can be used.
All objects have two read-only string properties named ObjectName$ and ObjectType$ which returns the code name and object type name of the object, respectively. This is useful when you have a reference to an object using the set command or through an object array such as Form.Controls.
See Also
Extension Objects
Example calling a global object member method
Clipboard.SetText "Clipboard Text"
Example creating a dynamic object and calling a member method
New List As StringArray
List.Add "First Item"
Example setting a dynamic object member property
Form.Title$ = "New Form Title"
Forms
Script files contain forms that can be edited using the CodeCurve script editor. When the script is executed, the forms are represented by Form objects.
See
Form
Form Editor
User-Defined Procedures
Procedures are methods which are defined within the script itself. They are called the same way built-in methods are called.
All variables inside the procedure are global. The parameters passed to a procedure are also global, as is the return value. In essence, a procedure is nothing more than a GoSub to a label. The difference is that the jump is made more convenient through the use of parameter passing and, in the case of functions, a return value.
Creating a Procedure
Procedures begin with the statement Proc and end with EndProc.
The name of the procedure follows the Proc statement, ending with either a $, for a string-type return value; #, for a number-type return value; or nothing, which indicates a statement.
Following the procedure name are the parameters the procedure will accept. To define which parameters the procedure accepts, provide a series of variables. Each variable should end with either $ or #, depending on whether the parameter is a string or number. When the procedure is called, these variables are filled with the parameter values given when the procedure is called.
To return a value, set the variable Result the desired return value. Result$ is for string procedure, Result# is for number procedures.
To cause a procedure to return before the EndProc statement is encountered, use Exit.
Example user-defined statement
ShowError "This is an error!"

Proc ShowError Msg$
  MsgBox(Msg$)
EndProc
Example user-defined number function
A# = GetAge()

Proc GetAge#
  Ret# = AgeDlg.Show(fsModal@)
  If Ret# <> idOK@ Then
    ThrowError "User cancelled age input!"
  EndIf
  Result# = Val(AgeDlg.GetText(201))
EndProc
Example user-defined string function
B$ = GetName()

Proc GetName$
  Ret# = NameDlg.Show(fsModal@)
  If Ret# <> idOK@ Then
    ThrowError "User cancelled name input!"
  EndIf
  Result$ = NameDlg.GetText(201)
EndProc
The Windows API and Third-Party DLLs
The Windows API is contained mostly in DLLs which may be accessed using the DLL object. The DLL object also allows you to call any third-party DLL.
See
DLL
COD File Basics
CodeCurve scripts begin with the CodeCurve editor that creates .COD files which the interpreter executes. The .COD file represents a single block of basic code and any number of forms.
Forms are automatically attached to global Form objects and are initially invisible when the .COD file is executed. You can call any member functions of the Form object to manipulate the form window or ignore it and execute only code. The name of the Form object is set in the editor.
Code executes from the top and terminates when the end of the code is reached or an Exit command is executed.
Any saved .COD file can be edited with a right mouse-button click and selecting Edit. Double-clicking or right-clicking and selecting Run will execute the .COD file.
Script Compiler
Registered Version Only
CodeCurve Professional has the ability to compile scripts into stand-alone executables from within the CodeCurve .COD editor. The resulting EXE may be executed on any Windows95-equipped computer, even if that computer does not have CodeCurve installed on it. To create a compiled script, from within the editor, press CTRL-F5 and provide a new EXE name for the script when prompted.
Script Icons
You can assign an icon to your script by selecting "Script Icon" from the "File" menu. Once assigned, the icon is saved with your script and used as the default icon when you compile your script in a stand-alone executable. The icon will also be used as the window icon of all forms in your script, as well as the icon used when you display forms in the system tray.
Note: At the present time, script icons must be exactly 32x32 pixels and 16-colors only. This limitation may change in the future.
Assignment Operator
=
Assigns a value to a variable

Math Operators
Syntax: Op1 (operator) Op2
Operators
-
Subtraction, returns Op2 subtracted from Op1

+
Addition, returns Op1 and Op2 added together (also used to concatenate strings)

*
Multiplication, returns Op1 multiplied by Op2

/
Division, returns Op1 divided by Op2

%
Modulus, returns the remainer of Op1 divided by Op2

Bitwise Operators
Using a bitwise operator causes the number(s) involved with the expression to be stripped of any decimal value and are treated as 4-byte unsigned integers.
Syntax: Op1 (operator) Op2
Operators
&
And, returns a value whose on bits are those which are both on in Op1 and Op2
0110 & 1010 returns 0010

|
Or, returns a value whose on bits are those which are on in either Op1 or Op2
0110 | 1010 returns 1110

!
Xor, returns a value whose on bits are those which are on in Op1 but off in Op2
0110 ! 1010 returns 0100

>>
Right-shift bits, returns a value whose bits are those in Op1 shifted to the right Op2 times
0010 >> 1 returns 0001

<<
Left-shift bits, returns a value whose bits are those in Op1 shifted to the left Op2 times
0001 << 1 returns 0010

Test Expressions
A test expression evaluates to either True or False. Statements like If, While and Assert evaluate test expressions to determine which course of action to take. You may test numbers or strings by comparing them to other numbers and strings. Numbers may be tested against True or False; if a number is non-zero, it is equal to True, otherwise it equates to False.
Test expressions may appear together using And and Or statements. Using And requires all expressions to evaluate to True in order for the entire expression to evaluate to True. Each separate expression is evaluated from left to right. Evaluation stops when one expression returns False or all expressions return True.
Using Or requires that only one expression evaluates to True in order for the entire expression to evaluate to True. Each separate expression is evaluated from left to right. Evaluation stops when one expression returns True or all expressions return False.
See Also
Boolean Operators
Examples
' single-line If expressions, all are True
if 10 < 20 then MsgBox("True")
if 10 = true then MsgBox("True")
if 0 = false then MsgBox("True")

' standard If expression using the And operator, expression is True
if 10 < 20 and 30 <> 40 then
  MsgBox("True")
else
  MsgBox("False")
endif


' While loop using the Or operator, expression is False
while 10 > 20 or 30 = 40
  MsgBox("Looping")
endwhile

' Assert
assert 10 = 20
Boolean Operators
Syntax: Op1 (operator) Op2
Operators
=
Equals, returns TRUE if Op1 equals Op2

<
Less Than, returns TRUE if Op1 is less than Op2

>
Greater Than, returns TRUE if Op1 is greater than Op2

<=
Less Than Or Equal, returns TRUE if Op1 is less than or equal to Op2

>=
Greater Than Or Equal, returns TRUE is Op1 is greater than or equal to Op2

<>
Not Equal, returns TRUE if Op1 is not equal to Op2

Extension Objects
Extension objects (.OBXs) are external libraries which link into the CodeCurve interpreter engine to behave like built-in dynamic and static objects. Programmatically, there is no difference between an internal object and one linked externally.
The ability to extend itself using a open-ended architecture is one of the more powerful features of CodeCurve. Not only does this extensibility give script programmers a long future with CodeCurve, it allows developers of other Windows95 applications to make their applications part of CodeCurve's functionality. Extension objects use the CodeCurve API provided by the interpreter engine DLL.
There are three ways to register an extension object for use with CodeCurve:
By running the setup program provided with the extension object.
From within the Editor, go to the Utilities|Register Extension menu.
Using a script command, RegisterExtension.
CodeCurve SDK:
The CodeCurve-005 SDK gives Windows95 application programmers using Visual C++ and Delphi the ability to add scripting to their applications as well as provide script programmers a way to manipulate their applications externally using ordinary CodeCurve scripts. Full source code for a dummy extension object is provided plus a how-to manual for creating your own extension objects from scratch.
Sample Script Tutorial
This tutorial is designed to walk you through the creation of a small CodeCurve script. It will cover many, but not all topics related to CodeCurve script programming. Follow along through each step of the tutorial.
Steps
Step 1 - Create the New Script
Step 2 - Prepare the Form
Step 3 - Set the File Specification
Step 4 - Create the User-Defined Procedure
Step 5 - Retrieve the File List
Step 6 - Sort the File List
Step 7 - Add the File List to the Form List Box
Step 8 - Provide a Default Selection
Step 9 - Display the Form
Step 10 - Return the Selected File
Step 11 - Calling the Procedure
Step 12 - Display the Result
Step 1 - Create the New Script
Create a new CodeCurve script and open it in the CodeCurve editor. See Creating a New Script for help.
Delete this line which appears in all new scripts:
ReturnedBy$ = Form1.Show(fsModal@)
Step 2 - Prepare the Form
This example script will use only one form: the default form. It will need one list box named "ListBox1" and one OK button.
Click the tab marked "Form1"
From the "Resources" menu, select "List Box"
Place the new List Box in the upper-left area of the form
Again from the "Resources" menu, select "Button"
Place the new button to the right of the list box
Click the button marked "Make OK" in the properties window
Click the tab marked "Code" to return to the code portion of the script
Step 3 - Set the File Specification
Our first variable is SearchPattern$, a string variable. We are setting its value to be a file search specification that will later be used to retrieve a list of files from a directory.
Add this line to your script:
SearchPattern$ = "C:\*.*"
Step 4 - Create the User-Defined Procedure
The script will contain one user-defined procedure whose purpose will be to display a list of files and return a single selected file back to the caller. To do this, we must add code to outline the procedure implementation.
Add this code to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
EndProc
Notice the procedure name, SelectFile, ends with a '$' symbol, indicating the procedure is a string function. It also takes one parameter in FileSpec$.
Step 5 - Retrieve the File List
The next step is to add code to retrieve the list of files that will be displayed to the user. We will need to call a global method, ListFiles, which will perform a directory listing and create a new string array containing all files found which match the given file search specification.
Add this line to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
EndProc
Notice that the second parameter is simply named Files. Files will be a newly-created string array when ListFiles returns and will contain all the files that were found.
Step 6 - Sort the File List
We will want the list to be sorted.
Add this line to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort
EndProc
Step 7 - Add the File List to the Form List Box
The listing of files must be displayed to the user, so we must add all items in the string array Files to the list box in the form. We call two commands to do this, ClearList and AddListArray. ClearList is called for safety; AddListArray appends items to the list box, so we must be sure that the list box contains nothing but the file list.
Add this code to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files
EndProc
Notice that with both ClearList and AddListArray, we must pass the name of the list box control.
Step 8 - Provide a Default Selection
To make the form easier to use by the end-user, we should provide a default list box selection. List boxes have no items selected initially; the user must click on a line or you can select a line specifically in code.
Because the string array Files may not have any files at all (no files matched the file search specification), we should test that the number of items in Files is not 0 before we attempt to provide a default selection. For this we use the If statement to test the Count# property of Files.
Add this code to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files

  If Files.Count# > 0 Then
    Form1.ListBox1.SelectedIndex# = 1
  EndIf
EndProc
Step 9 - Display the Form
Now we need to show the form.
Add this line to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files

  If Files.Count# > 0 Then
    Form1.ListBox1.SelectedIndex# = 1
  EndIf

  Form1.Show(fsModal@)
EndProc
Step 10 - Return the Selected File
In order for the procedure SelectFile to be useful, it must return the name of the file the user selected in the form. Procedures use Result$ and Result# to return values to the caller. All we need to do is set Result$ to the file name selected in the list box.
Add this line to your script:
SearchPattern$ = "C:\*.*"

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files

  If Files.Count# > 0 Then
    Form1.ListBox1.SelectedIndex# = 1
  EndIf

  Form1.Show(fsModal@)

  Result$ = Form1.ListBox1.SelectedText$
EndProc
Step 11 - Calling the Procedure
The user-defined procedure is complete and now we can use it in our script. It is called just like a built-in string function; we will save the return value in the variable File.
Add this line to your code:
SearchPattern$ = "C:\*.*"

File$ = SelectFile(SearchPattern$)

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files

  If Files.Count# > 0 Then
    Form1.ListBox1.SelectedIndex# = 1
  EndIf

  Form1.Show(fsModal@)

  Result$ = Form1.ListBox1.SelectedText$
EndProc
Step 12 - Display the Result
Now that we have called the procedure and have the return value, we can display the selection to the user. We will call MsgBox to do this and we'll provide the constant value mtInformation@ to display only the information icon and an OK button.
Add this line to your code:
SearchPattern$ = "C:\*.*"

File$ = SelectFile(SearchPattern$)

MsgBox(File$, mtInformation@)

Proc SelectFile$ FileSpec$
  ListFiles FileSpec$, Files
  Files.Sort

  Form1.ListBox1.Lines.Clear
  Form1.ListBox1.Lines.Concat Files

  If Files.Count# > 0 Then
    Form1.ListBox1.SelectedIndex# = 1
  EndIf

  Form1.Show(fsModal@)

  Result$ = Form1.ListBox1.SelectedText$
EndProc
This completes the sample script tutorial! To test your script from within the editor, simply press F5, click the button marked "Yes" to save the script and execute it.
Form Editor
The form editor edits forms embedded within a .COD file. See the Form object reference using Form objects in script code.
See
Editing Controls
Graphic Elements
Setting the Tab Order
Testing the Form
Editing Controls
Add controls to a form by selecting a control tool from the Resources menu and dropping the control on the form. Size and move controls into position using the mouse or keyboard arrow keys.
See
Buttons
Statics
Text Boxes
Check Boxes
Radio Buttons
List Boxes
Combo Boxes
Tips
The editor automatically snaps to a virtual snap grid which makes alignment and proper sizing easier. The SHIFT key prevents move and size actions from snapping to the snap grid. The CTRL key offsets the snap grid to align with the point of origin.
This is useful when the handle you are moving is not aligned with the grid, but you want the movement to snap at grid intervals.
Buttons
Buttons are used to obtain input from the user. When Form.Show is called, the name of the last button the user clicked is returned. This allows you to take special actions based on which button the user selected. If the form was shown modally, clicking a button also closes the form. if shown semi-modally or non-modally, the last button clicked is returned, but the form remains showing.
As with any child control, if the Window Text contains an ampersand '&', the character immediately following it will be used as an ALT-? hotkey shortcut.
Properties
Window Text
Name
ID
Default:
Causes the button to be default for the form (Usually the OK button)

Use Tab Stop
Start of Group
Make OK
Select this to set the property settings for this button to the default settings for the OK
button: Window Text = "OK", Name = "OKBtn", Child ID = 1, Default is on.

Make Cancel
Select this to set the property settings for this button
to the default settings for the Cancel button: Window Text = "Cancel",
Name = "CancelBtn", Child ID = 2, Default is off.

Statics
Statics are used to display text in the form.
Properties
Window Text
Name
ID
Show Border
Displays the Static's border.

Right-Align
Right aligns the text within the bounds of the static.

Left-Align
Left aligns the text within the bounds of the static.

Center-Align
Center aligns the text within the bounds of the static.

Text Boxes
Text boxes are used to prompt the user for text input. The user's response can be extracted using the Text property.
Properties
Window Text
Name
ID
Auto Horizontal Scroll
Allows the text to scroll off to the left when text entered exceeds the bounds of the text box.

Auto Vertical Scroll
Allows the text to scroll down when text entered exceeds the bounds of the text box.

Use Tab Stop
Start of Group
Read Only
Prevents the user from changing the control's text.

Single-Line Only
Limits the text box to a single line of text.

Multi-Line
Allows multiple lines within the text box.

Password Characters
Text entered will appear as stars to prevent prying eyes.

Normal
Text remains the same as it is entered.

Lowercase
All text is forced to lowercase.

Uppercase
All text is forced to uppercase.

Check Boxes
Check boxes are used to solicit optional response from the user. See IsChecked.
Properties
Window Text
Name
ID
Show Text On Left
Moves the text to the left of the Check Box (does not display this way in the editor).

Use Tab Stop
Start of Group
Normal
A normal Check Box switches between on and off.

Tri-State
A tri-state Check Box switches between on, off, and indeterminate.

Radio Buttons
Radio buttons act as a group when the first button in the tab order of a series of buttons has the group style turned on. The group ends when a control of another type or another radio button with the group style turned on is encountered. All other buttons in the group (excepting the first) should have their group style turned off.
To make a group of radio buttons, first set the tab order so they're all together and in the order you would like. Turn on the group attribute for the first button, the one with the lowest tab order number. For the rest of the buttons in the group, turn off the group attribute.
They are used a lot like Check Boxes. The difference is that only one button in a group of radio buttons can be selected. See IsChecked and SelectedIndex.
Properties
Window Text
Name
ID
Show Text On Left
Displays the text to the left of the Radio Button (does not display this way in the editor).

Use Tab Stop
Start of Group
List Boxes
List boxes are used to solicit input from the user through by prompting them to select one of a list of items. Add items to the list box using the Lines member object. The user's response can be extracted using the List Box form member object.
Note: List boxes ignore their own window text. You must set list items using the AddList command.
Properties
Window Text
Name
ID
Disable No-Scroll
If this and the Scroll Bar property are turned on, a scroll bar will appear even if the
List Box isn't full.

No Integral Height
Normally, a List Box will adjust its size so it displays the nearest whole line.
Check this to stop the adjustment.

Sort Lines
Check this so the items in the List Box are sorted alpha-numerically.

Multiple Selections
Allows more than one line to be selected at a time.

Use Tab Stop
Start of Group
Always Show Scroll Bar
Makes scroll bar appear when necessary. A scroll bar will appear always if Disable No-Scroll
is also checked.

Combo Boxes
Combo boxes solicit input from the user like List Boxes that must be pulled down before the user can see the available choices. They may also contain an edit area for the user to type their response. Add items to the combo box using the Lines member object.
Note: Combo boxes of the drop-down list style behave like list boxes and ignore their own window text. If they are of the drop-down style, they use the window text in their edit area. If the combo box is of the drop-down list style, use SelectedText to extract the user's response. If it is of the drop-down style, use Text to extract the response.
Properties
Window Text
Name
ID
Disable No-Scroll
If this and the Scroll Bar property are turned on, a scroll bar will appear even if the
Combo Box isn't full.

No Integral Height
Normally, a Combo Box will adjust its size so it displays the nearest whole line.
Check this to stop the adjustment.

Sort Lines
Check this so the items in the Combo Box are sorted alpha-numerically.

Use Tab Stop
Start of Group
Always Show Scroll Bar
Makes scroll bar appear when necessary. A scroll bar will appear always if Disable No-Scroll
is also checked.

Drop-Down
The user will be able to type in a selection or pick a selection from the list.

Drop-Down List
The user will only be able to pick a selection from the list.

Window Text
Buttons, Statics, Check Boxes, Radio Buttons, Text Boxes and sometimes Combo Boxes use the Window Text property to set their text value at run-time. List Boxes ignore the Window Text property. Window text is limited to 255 characters.
Name
Name is the text name of the control. It is used in script code as a means of easily identifying them. With the previous version of CodeCurve (CodeCurve), controls had only child IDs. They were a little hard to remember, so a system of named controls was introduce. All methods of the Form object (previously known as the Dialog object) accepted only the child ID of a control. The new Form object can accept either the child ID (for backwards compatibility) or the text name.
ID
Note: A new system of named controls makes the child ID of a control virtually obsolete. However, since Windows still uses child IDs to identify controls, they may still be useful to some script programmers.
The child ID is used to identify the control by various commands. Child IDs start at 101 and increment from there. The default [OK] and [Cancel] buttons Child IDs are 1 and 2 respectively per Windows convention. You can change the Child ID for any control to any value, but be careful not to have two controls with the same ID.
Use Tab Stop
When the tab stop is on, the control will be stopped at when the user tabs through the form.
Start of Group
When a control has its Group style turned on, it is the first control in a group of controls. Grouped controls can be selected using the arrow keys and it is standard practice to turn off the Tab Stop style for all controls in a group except for the first control (which has the Group style turned on).
Graphic Elements
Forms can display graphic images and text with a rich array of properties. Graphic elements are bitmaps and can pasted into the editor from the Windows clipboard or loaded from .BMP files. Banners are similar to a simple static control, except that it allows you to use different fonts and colors.
See
Graphics
Banners
Graphics
Graphics are bitmap elements which are stored with the script and displayed with their parent form at run-time.
You can create a Graphic by selecting Graphic from the Resources menu, or pressing SHIFT-INS when there is a bitmap image on the windows clipboard.
Properties
Name
The text name of the graphic element.

Draw Effect
Can display the image in it's original state, stretched to fit its
rectangular boundaries or as a series of tiled images within its boundaries.

Load Image
Changes the bitmap image of the graphic.

Banners
Banners are flexible text elements which are stored with the script and displayed with their parent form at run-time.
You can create a Banner by selecting Banner from the Resources menu, or pressing SHIFT-INS when there is text on the windows clipboard.
Properties
Name
The text name of the graphic element.

Text
The text to display.

Font
Used to change the font name, style and color.

Background Color
Color of the rectangle area beneath the text.

Alignment
Can specify that the text should display on the left, right or centered within the rectangle
boundary.

Draw Transparent
If checked, draws the text only, leaving the images beneath to show through.

Setting the Tab Order
Turn on tab order mode from the Edit menu. Change the tab order of a control by selecting it with the mouse and pressing the PAGE UP and PAGE DOWN keys. The tab order controls which control gains the input focus when the user presses the TAB key.
Testing the Form
Load the form into test mode from the Edit menu. The form which appears on-screen is a real window shown in the exact way it will look during installation.
Code Editor
The code editor is that part of the editor where all the script code is edited. It is literally loaded with features designed to make programming more efficient and pleasant.
The editing area itself features complete support for the Windows clipboard, including cut, copy and paste. It also features undo, which allows you to undo any changes you make to your script code (up to 128 changes).
Searching and navigation are made simpler through standard find and replace features. You can zoom to any line number instantly and you can also mark lines that you wish to return to quickly using the jump feature.
Finding And/Or Replacing Text
Finding and replacing text is done through the Edit menu. Select which action you wish to perform and follow the prompts.
One special feature is the ability to continue a previous search by simply pressing F3 (Find Again). A similar feature is CTRL-F3 which finds the next occurance of the word found at the current cursor position. Pressing F3 continuously will find each occurance of the word.
Zooming to Specific Points In Code
You can zoom to a specific line in the script code by pressing CTRL-G. A dialog will appear asking you for a line number to zoom to. This is useful when you are reviewing a printout of script code and wish to jump to a printed line number.
Another extremely useful feature is the ability to mark lines and jump to them at any time. If you press CTRL-F2, the current line will be marked as jump line. Pressing just F2 will jump from one jump line to the next. If you are working in different areas of a script at the same time and they are not very close to each other, this feature makes zooming back and forth much simpler.
Macro Recorder
The macro recorder is an interesting and powerful feature of O'Basic. For users unfamiliar with programming and/or basic-language syntax, this is a great way to get started writing useful scripts that immediately add to your productivity.
Using the Macro Recorder
The recorder is pretty straight-forward. You turn on recording and begin your work. When you turn off recording, all keyboard and mouse actions you performed are converted into script code which is then pasted into the editor. When you execute the script, your actions are repeated exactly as you had originally performed them.
Editing recorded scripts
Once your actions are recorded as script code, you can edit the script because it is, naturally, nothing more than an CodeCurve script. At the very least, you might want to decrease the pauses between actions to speed up replay. You might also want to replace actions which performed tasks such as launching applications, etc, with built-in CodeCurve commands to perform the same thing (but with better control).
A note of caution
While powerful, the macro recorder can also be dangerous. The recorder does record your actions exactly, with the same timing that you performed them. Any recorded script which is played back can fail for a number of reasons, some of which I'll explain now. For example, if the recorder sees you click in a window and records that click, upon playback, that window might not be in the same exact position. The click might be lost or it might go to another window or control where the click is extremely unwelcome. Timing is also a problem. If the recorder sees you typing just 2 seconds after you launch an application, upon playback it might take 10 seconds for that same application to load and the keystrokes might either be lost or they could go to another application where, again, they are very much not wanted. CodeCurve's macro recorder pays close attention to the timing of your actions and the windows in which they occured. For the most part, there is nothing to worry about, but do be warned that if you don't inspect your recorded code and you execute the script fearlessly, you may be in for a surprise.
Summary Information
Summary data such as title, author, company and copyright are kept with every script. This information is for general identification and can be accessed at run-time through the Application object. You can change this information through the File menu by selecting Summary Information.
Utilities Menu
The utilities menu is where various CodeCurve utilities are available, but it is also customizable. You can add, delete and edit menu entries to launch external documents and programs.
Adding/Editing Utility Menu Entries
From the Utilities menu, select Customize Utilities
Select New to create a new menu entry
or
Select Delete to remove an existing entry
Once an item is selected, use the up/down arrows to change its position.
Title is the name which appears on the utilities menu.
File is the document or program to be launched when the menu entry is clicked. If it is a file, leave the Parameters field empty.
Parameters are any additional parameters you wish to be passed to the program in the File field.
Work Dir is where the current directory should be changed to just prior to launching the program or document.
Short Cut is a keyboard shortcut to assign to the custom menu entry. Any keystroke sequence you enter in this field is recorded. Avoid using shortcuts already in use by the editor.
Variables are values known to the editor only at design-time that can be used in either the File, Parameters or Work Dir fields.
Utility Menu Entry Variables
Add variables to menu entry fields by clicking on the variables combo box and holding the left mouse button down. While holding the left mouse down, "drag" the selected variable to any accepting field.
$AppDirectory specifies the drive and directory only of the editor EXE. Any backslashes are removed.
$AppFileName specifies the file name and extension of the editor EXE.
$AppFullPath specifies the full path to the editor EXE. This is a combination of the $AppDirectory and $AppFileName variables.
$DocDirectory specifies the drive and directory only of the current script. Any backslashes are removed.
$DocFileName specifies the file name and extension of the current script.
$DocFullPath specifies the full path to the current script. This is a combination of the $DocDirectory and $DocFileName variables.
Script File Security
CodeCurve-005 has features that allow you to distribute your scripts with various security features so that others using or viewing your scripts cannot compromise the security of copyrights you may hold on them.
By default, scripts are completely unlocked and may be viewed or edited by anyone. This default lack of security is for ease of use and to prevent the unwary user from locking a script without realizing he/she has done so and perhaps not being able to unlock it because of a forgotten password.
When a script is locked, the locking mechanism applies the password you enter the next time you save and will continue to do so until you explicitly unlock it. You may unlock a script at any time through the File|Locking menu.
Locking Scripts for Viewing Only
To lock your script for viewing only:
From the editor's File menu, select Locking
Select Protect as View-Only
Enter a password in the Password dialog and press OK
The script may be executed and opened in the editor, but any changes made will not be saved, thus making it impossible for anyone to modify the script directly. The script code is not encrypted because it is can be viewed and is therefore not secure.
Locking Scripts Completely
To lock your script completely:
From the editor's File menu, select Locking
Select Lock Completely
Enter a password in the Password dialog and press OK
The script is completely secure. It may be run, but it cannot be viewed or edited. The script code is also encrypted so it cannot be extracted using a hex editor. Note: Because the script code is encrypted, it must be de-crypted at run-time and that will slow down the load and execution time of a script by a very short time.
Debugging
Debugging is an invaluable tool in locating bugs and general problems with your script. It works by allowing you to break execution of your script at various points and inspect script expressions, such as variables and object properties.
Any time you run a script from within the editor, you are running the script in debug mode. You can apply any of the debugging principles discussed in this topic during, and only during, script execution from within the editor.
The two main ways you break script execution is by inserting breakpoints in the script code and by stepping from line to line during execution. Breakpoints are spots you select in the script code where you wish the editor to pause so you can inspect variables. Stepping typically occurs after a breakpoint has been reached; you simply execute the script line-by-line. Each point where the editor stops during stepping is, essentially, a breakpoint. During both times, you are permitted to inspect.
When you are at a stop point during execution, you may inspect. The act of inspection is really just a matter of passing a short expression to the CodeCurve engine for evaluation. Any number or string return value is displayed in the inspection dialog. This is useful during debugging because it allows you verify the value of particular variables which may or may not contain correct values.
Adding Breakpoints
To add a breakpoint, simply highlight the line in your code where you wish the debugger to pause. From the Debug menu, select Toggle Breakpoint (or just press F9). If you repeat this step, the breakpoint is removed.
Inspecting
When you are at a stop point in the debugger, you can inspect by selecting Inspect Expression from the Debug menu (or just press F7). In the inspect dialog, type any variable (include the $ or #) and press Enter. The value of that variable is displayed. Expression inspection is not limited to variables. You can also display object properties and even call functions to determine their return value.
Stepping
Once a script is stopped in the editor, you may continue execution line-by-line by selecting Execute Line from the Debug menu (or just press F8). Just like with breakpoints, you can inspect at any point where a script is stopped in the debugger.
Template File
The file named "Template.cod" found in the CodeCurve directory is the script file Windows95 uses when creating a new script in a windows folder. You create new scripts this way by right-clicking anway in a windows folder, selecting New, CodeCurve-005 Script. This file is not used when creating a new script from within the editor.
Conditional and Branching Statements
If
For
While
Repeat
Select
Break
Continue
Proc
Exit
Goto
GoSub
Return
If
The If statement evaluates a boolean expression and jumps execution to the point immediately following the required Then statement if the expression evaluates to True. If the expression evaluates to False, execution jumps to either the point immediately after the required EndIf statement or the optional Else statement (if present).
Note: If only one statement is called immediately after Then, it appears on the same line as Then and there is no Else, you may omit the EndIf statement. This is known as a "single-line If"
Calling Break causes execution to jump immediately after the If statement's corresponding EndIf. When Break is used with a "single-line If", execution jumps to the point immediately after the next outermost block.
See
Test Expressions
Example:
If TestVal# < 32 Then MsgBox("Error in TestVal")
Example:
If TestVal# < 32 Then
  MsgBox("Error in TestVal")
Else
  MsgBox("Success!")
EndIf
For
The For statement is used as a counting loop to execute a block of code for a fixed number of passes. It begins by setting a variable to an initial value, executing the block of code beginning on the next line and incrementing or decrementing the counting variable each time it discovers the required EndFor statement. It continues to re-execute the block until the counting variable has reached its target value.
Calling Break causes execution to jump immediately after the For loop's corresponding EndFor. Calling Continue causes execution to jump to the point where the For loop is evaluated, executing the loop again if necessary.
For blocks may be nested to a theoretical 8192 levels.
Note: EndFor replaces Next, which is still supported.
Example:
For Counter# = 1 To 5
  MsgBox("This is pass " + Str(Counter#))
EndFor
While
While evaluates a conditional statement in the same way that If does, but continuously executes all code in the following block ending with the While's matching EndWhile statement. The loop executes until the expression at While evaluates to False. This is in contrast to Repeat, which executes until its expression evaluates to True.
Calling Break causes execution to jump immediately after the While loop's corresponding EndWhile. Calling Continue causes execution to jump to the point where the While loop is evaluated, executing the loop again if necessary.
See
Test Expressions
Example:
I# = 1
While I# <= 5
  MsgBox("This is pass " + Str(Counter#))
I# = I# + 1
EndWhile
Repeat
Repeat continuously executes all code in the following block ending with the Repeat's matching Until statement. The conditional expression between Until and a matching EndRepeat statement is evaluated and the loop continues executing until it evaluates to True. This is in contrast to While, which executes until its expression evaluates to False. The Repeat loop executes at least one time before Until evaluates the expression which may or may not terminate the loop.
Calling Break causes execution to jump immediately after the Repeat loop's corresponding EndRepeat. Calling Continue causes execution to jump to the point where the Repeat loop is evaluated (after Until), executing the loop again if necessary.
See
Test Expressions
Example:
Repeat
  Result# = MsgBox("Continue loop?", mbYesNo@)
Until Result# = idNo@ EndRepeat
Select
Select is a branching statement that directs execution to a Case block. An expression is evaluated and a Case statement with a matching expression is searched for. If a matching Case is found, execution jumps to that block and continues through the next Case, optional Case Else or required EndSelect statement. Use Select to simplify a series of If statements testing the same expression repeatedly.
Case statements may use the OR boolean evaluator to permit more than one value to match the Select expression. Other operators such as AND may not be used.
Calling Break causes execution to jump immediately after the Select statement's corresponding EndSelect.
See Also
Test Expressions
Example
Select Case 1
  Case 1 Or 10
    MsgBox("Case 1 or 10")
  Case 2
    MsgBox("Case 2")
  Case Else
    MsgBox("Case Else")
EndSelect
Break
Break is used inside "block" type of statements to cause execution to jump to the point immediately after the block. This statement can be used to jump out of If, Select, For, While, Repeat, and Try blocks.
Example:
A# = 1

If A# = 1 Then
  Break
  MsgBox("A# = 1") ' break prevents execution
EndIf


Select Case 1
  Case 1
    Break
    MsgBox("Case 1") ' break prevents execution
  Case 2
    MsgBox("Case 2")
EndSelect

For A# = 1 to 3
  If A# = 2 Then Break ' break stops after one pass
  MsgBox(Str(A#))
EndFor
Continue
Continue is used inside looping "block" type of statements to cause execution to reevaluate the loop and continue executing the loop if possible. This statement can only be used to reevaluate For, While and Repeat blocks.
Example:
For A# = 1 to 3
  If A# = 2 Then Continue
  MsgBox(Str(A#)) ' skipped when A# = 2
EndFor

A# = 1
While A# <= 3
  If A# = 2 Then Continue
  MsgBox(Str(A#)) ' skipped when A# = 2
EndWhile
Proc
Proc marks the beginning of a user-defined procedure. For more information about procedures, read User-Defined Procedures.
Exit
Global Syntax
Exit [ErrorLevel#]

Proc Syntax
Exit

If called within a procedure, exits the procedure. If called outside a procedure, the program terminates immediately. If the global Exit's ErrorLevel# parameter is provided, the numeric value is returned to DOS when CodeCurve terminates. ErrorLevel# values other than 0 are assumed to be an indication of error to other DOS programs.
See
Stopping Scripts
Application.Terminate
Example
'    exits the program with a success value
If Ret# = 0 Then
  Exit 0
EndIf
Goto
Goto can force execution to jump to a Label defined elsewhere in the program. Once a Goto finds a matching label, execution continues on from the Label forward.
Example:
Goto SkipPoint
  MsgBox("Before Skip")
SkipPoint:
  MsgBox("After Skip")
GoSub
Return
GoSub works just like Goto, but the point the GoSub was called is stored and can be returned to using the Return statement. If a Return statement is not encountered, GoSub behaves exactly like Goto. The following example shows the second MsgBox message first, loops back to the first and then ends the program.
Example:
Gosub SkipPoint
  MsgBox("Before Skip")
  End
SkipPoint:
  MsgBox("After Skip")
  Return
Dynamic Allocation Statements
New
Delete
Set
Reset
Dim
ArraySize
New
Delete
Syntax
New ObjectName As ObjectType [constructor parameters...]

Syntax
Delete ObjectName

Used to create and destroy instances of dynamic objects. ObjectName is the name of the new object you will use in your code, ObjectType is the name of the type of object. When destroying objects, pass the ObjectName to Delete.
Some objects, such as the Clipboard object, are static and have only one instance; you cannot create a new object based on their type. Other objects, such as the Port and DDEClient objects, are only object types and you must create an object based of their type to use them.
Some dynamic objects require parameters to be passed on the line where they are created. Consult the documentation on each dynamic object for information about parameters they may require.
Example:
'    This examples tests for the existence of a
modem on COM1
New Modem As Port "COM1"
Modem.WriteString("AT" + 13)
Ret# = Modem.WaitFor("OK", 2)
Delete Modem
Set
Reset
Syntax
Set NewObjectName To ObjectName

Syntax
Reset NewObjectName

Set creates an object which refers to an existing object. The new object is treated exactly like the real object it refers to, although the object reference is handled different internally. Reset deletes the object reference; it does not affect the real object itself.
Example:
' Reduces typing when changing a form object
set TB as Form1.TextBox1
TB.Text$ = "Text"
Dim
Syntax
Dim ArrayName#[Size]

Syntax
Dim ArrayName$[Size]

Use Dim to create string and number arrays. Once created, the arrays always exist unless Dim is used with the same array name and type (string or number) a second time, in which case the array will overwritten. Many CodeCurve commands use string arrays as information buffers.
This method of array creation is obsolete. Use New to create objects of type StringArray or NumArray instead.
Example:
'    writes a series of lines to a text file
Dim Text$[3]
Text$[1] = "This is line one"
Text$[2] = "This is line two"
Text$[3] = "This is line three"
WriteFileLines("C:\Windows\Desktop\Test.txt", Text)
ArraySize
Syntax
# = ArraySize(Array)

Returns the number of elements in a string or number array. This function is obsolete. See Array.Count for the current method of retrieving an array's size.
Example:
Count# = ArraySize(Argv)
String Commands
String Manipulation Commands
String Conversion Commands
String Information Commands
String Manipulation Commands
Space
String
Mid
Left
Right
ParseTok
Encode
Decode
SoundEx
String Formatting Commands
FormatStr
FormatPath
Clock.Format
String Conversion Commands
UCase
LCase
LTrim
RTrim
Str
Hex
Oct
String Information Commands
Len
Asc
Chr
Pos
IsAlpha
IsAlphaNum
IsDecNum
IsHexNum
IsLower
IsUpper
IsSpace
MatchText
CompareText
Space
Syntax
$ = Space(Count#)

Returns a string padded with Count# number of space (ASCII 32) characters.
Example:
A$ = Space(32)
String
Syntax
$ = String(Char$, Count#)

Returns a string padded with Count# number of the first character appearing in Char$.
Example:
A$ = String(".", 32)
Len
Syntax
# = Len(String$)

Returns the length of String$.
Example:
C# = Len(A$)
Asc
Syntax
# = Asc(Char$)

Returns the ASCII value of the first character n Char$.
Example:
C# = Asc(A$)
Chr
Syntax
$ = Chr(ASCII#)

Returns a string made up of one character whose ASCII value is ASCII#.
Example:
A$ = Chr(65)
Mid
Syntax
$ = Mid(String$, Start#[, Length#])

Returns a string extracted from String$ starting at the 1-based index Start# for Length# characters. If Length# is omitted, the rest of the string from Start# is returned.
Example:
B$ = Mid(A$, 1, 3)
Left
Syntax
$ = Left(String$, Length#)

Returns a string made up of the left Length# characters in String$.
Example:
B$ = Left(A$, 3)
Right
Syntax
$ = Right(String$, Length#)

Returns a string made up of the right Length# characters in String$.
Example:
B$ = Right(A$, 3)
UCase
Syntax
$ = UCase(String$)

Returns String$ in uppercase letters.
Example:
B$ = UCase(A$)
LCase
Syntax
$ = LCase(String$)

Returns String$ in lowercase letters.
Example:
B$ = LCase(A$)
LTrim
Syntax
$ = LTrim(String$)

Returns String$ after removing any whitespace characters from the beginning of the string. Whitespace characters are those whose ASCII values are 9-13 and 32. This includes TAB, RETURN and SPACE characters.
Example:
B$ = LTrim(A$)
RTrim
Syntax
$ = RTrim(String$)

Returns String$ after removing any whitespace characters off the end of the string. Whitespace characters are those whose ASCII values are 9-13 and 32. This includes TAB, RETURN and SPACE characters.
Example:
B$ = RTrim(A$)
ParseTok
Syntax
$ = ParseTok(StringVarName, Tokens$ [, SkipLeading#]])

Parses a string variable using Tokens$ as delimiters. The returned string consists of all characters to the left of the value of StringVarName up to the first character found in Tokens$. The value of StringVarName is changed to the remainder of its original value, excluding the string extracted.
If SkipLeading is provided and TRUE (default), ParseTok will skip past token characters found at the beginning in StringVarName. If FALSE, tokens found at the beginning of the string are considered part of the parse.
Example:
'  P1$ will equal "Piece1" and P2$ will equal
"Piece2"
A$ = "Piece1;Piece2"
P1$ = ParseTok(A, ";")
P2$ = ParseTok(A, ";")
FormatStr
Syntax
$ = FormatPath(Pattern$ [, ...])

Creates a formatted string given a Pattern and any number of additional parameters. Additional parameters must be provided for each format character found in the Pattern.
Formatting characters take the form: $[w][.p]S|N. The w specifies a width modifier and the p specifies a precision modifier. Neither w or p is required. See the table for details. Format characters must be terminated either by S for string or N for number. For every S or N formatting characters, a parameter of that type must appear after the entire format string.
To generate a '$' character inline, place two '$$' together and they will compress into one in the final string.
Formatting characters and their meaning
$S
A string parameter was supplied. Width means the minimum number of characters in the entire
string, after precision is applied (padded with spaces to the left). Precision means the maximum
number of characters to take from the left of the string parameter provided.

$N
A numerical parameter was supplied. Width means the minimum number of characters in the entire
string, after precision is applied (padded with zeros to the left). Precision means the
number of digits to show to the right of the decimal.

Example:
FormatStr("$N", 1) ' Result: "1"
FormatStr("$5.2N", 1) ' Result: "01.00"

FormatStr("$S", "ABC")              ' Result: "ABC"
FormatStr("$5.2S", "ABC")           ' Result: "   AB"
FormatStr("$5.2S, $5.2N", "ABC", 1) ' Result: "   AB, 01.00"
FormatPath
Syntax
$ = FormatPath(FilePath$, Pattern$)

Parses a file path and returns a formatted string using the component values of FilePath. Pattern specifies literal text and format characters. Formatting characters are replaced by values extracted from FilePath$.
To generate a '$' character inline, place two '$$' together and they will compress into one in the final string.
Formatting characters and their meaning
$D
The drive letter of FilePath, followed only by ":"

$P
The directory of FilePath, preceded and followed with "\"

$F
The file name part of FilePath, with no extension

$E
The extension of the file name in FilePath, preceded with a period

Example:
'  A good way to generate a text
'  data file name, takes the path
'  of the current script and replaces
'  the extension with .txt
DateFile$ = FormatPath(Application.FileName$, "$D$P$F.txt")
Encode
Syntax
$ = Encode(Password$, Value$)

Encodes Value$ using Password$ to return a unique string value. The encoded return value is a 7-bit ASCII string twice the length of Value$. The encryption method is a moderately secure, but fairly simple algorithm.
Note: Celtech Software assumes no responsibility for the security of information encrypted using this routine.
See Also
Decode
Array.Encode
Example:
Password$ = "MyPassword"
Text$ = "This text is encrypted"

Text$ = Encode(Password$, Text$)
MsgBox(Text$)

Text$ = Decode(Password$, Text$)
MsgBox(Text$)
Decode
Syntax
$ = Decode(Password$, Value$)

Decodes Value$, a string encrypted by Encode using Password$ to return the original string value.
See Also
Encode
Array.Decode
SoundEx
Syntax
$ = SoundEx(Value$)

Converts a string into its SoundEx value. SoundEx is a coding system used to create associations between words which may sound or may be spelled similarly.
Example:
SX$ = SoundEx("Smithers")
Str
Syntax
$ = Str(Num#[, Width#[, Precision#]])

Returns the string representation of a number. Width# (default = 1) is the minimum of characters in the return string. Precision# is the exact number of characters that should appear to the right of the decimal.
Example:
B$ = Str(1.1, 4, 2)
Hex
Syntax
$ = Hex(Num#)

Returns the string representation of a number in hexadecimal form. The number is changed to an integer for the conversion.
Example:
B$ = Hex(32)
Oct
Syntax
$ = Oct(Num#)

Returns the string representation of a number in octal form. The number is changed to an integer for the conversion.
Example:
B$ = Oct(32)
Pos
Syntax
# = Pos(SubStr$, SrcStr$)

Returns the 1-based index where SubStr$ starts in SrcStr$. If SubStr$ is not found, returns 0.
Example:
A# = Pos("Waldo", "Where's Waldo?")
IsAlpha
Syntax
# = IsAlpha(Char$)

Returns TRUE if the first character in Char is an alphabetic character in the range 'a'-'z' or 'A'-'Z'.
IsAlphaNum
Syntax
# = IsAlphaNum(Char$)

Returns TRUE if the first character in Char is an alpha-numeric character in the range 'a'-'z', 'A'-'Z' or '0'-'9'.
IsDecNum
Syntax
# = IsDecNum(Char$)

Returns TRUE if the first character in Char is a decimal numeric character in the range '0'-'9'.
IsHexNum
Syntax
# = IsHexNum(Char$)

Returns TRUE if the first character in Char is a hexadecimal numeric character in the range '0'-'9', 'a'-'f' or 'A'-'F'.
IsLower
Syntax
# = IsLower(Char$)

Returns TRUE if the first character in Char is a lowercase alphabetic character in the range 'a'-'z'.
IsUpper
Syntax
# = IsUpper(Char$)

Returns TRUE if the first character in Char is an uppercase alphabetic character in the range 'A'-'Z'.
IsSpace
Syntax
# = IsSpace(Char$)

Returns TRUE if the first character in Char is a whitespace character in the range 9-13 (TAB through RETURN) or is a space character (ASCII 32 or ' ').
MatchText
Syntax
# = MatchText(Text$, Spec$ [, IgnoreCase#])

Returns TRUE if Text matches the pattern given in Spec. Search may contain wildcard characters such as * and ?. If IgnoreCase is specified and is TRUE (default), MatchText will test regardless of upper or lowercase.
Example:
' all expressions return TRUE
  Name$ = "Billy Joe Bob"
  Matched# = MatchText(Name$, "B*")
  Matched# = MatchText(Name$, "*b")
  Matched# = MatchText(Name$, "*joe*")

CompareText
Syntax
# = CompareText(Str1$, Str2$ [, IgnoreCase#])

Compares Str1 and Str2, returning 0 if Str1 and Str2 are the same,  0 if Str1 is greater than Str2. If IgnoreCase is specified and is TRUE (default), CompareText will test regardless of upper or lowercase.
Number Commands and Math Functions
Number Commands
StrVal
HexVal
OctVal
Rnd
Math Functions
Abs
ArcCos
ArcSin
ArcTan
Cos
HyperCos
Sin
HyperSin
Tan
HyperTan
Exp
Hypot
Log
Log10
SqRoot
Ceiling
Floor
Average
StrVal
Syntax
# = StrVal(Num$)

Returns the numerical value of a string. The string must be a decimal number in string form.
Example:
C# = StrVal("-100")
HexVal
Syntax
# = HexVal(Num$)

Returns the numerical value of a string. The string must be a hexadecimal number in string form.
Example:
C# = HexVal("1D")
OctVal
Syntax
# = OctVal(Num$)

Returns the numerical value of a string. The string must be an octal number in string form.
Example:
C# = OctVal("24")
Rnd
Syntax
# = Rnd(Max#)

Returns a random number from 0 to Max# - 1.
Example:
C# = Rnd(49)
Abs
Syntax
# = Abs(Num#)

Returns the absolute value of a number. If the number is a negative, it is returned as a positive, otherwise it is simply returned.
Example:
C# = Abs(-100)
ArcCos
Syntax
# = ArcCos(Num#)

Returns the arccosine of Num#.
Example:
C# = ArcCos(9)
ArcSin
Syntax
# = ArcSin(Num#)

Returns the arcsine of of Num#.
Example:
C# = ArcSin(9)
ArcTan
Syntax
# = ArcTan(Num#)

Returns the arctangent of Num#.
Example:
C# = ArcTan(9)
Cos
Syntax
# = Cos(Num#)

Returns the cosine of Num#.
Example:
C# = Cos(9)
HyperCos
Syntax
# = HyperCos(Num#)

Returns the hyperbolic cosine of Num#.
Example:
C# = HyperCos(9)
Sin
Syntax
# = Sin(Num#)

Returns the sine of Num#.
Example:
C# = Sin(9)
HyperSin
Syntax
# = HyperSin(Num#)

Returns the hyperbolic sine of Num#.
Example:
C# = HyperSin(9)
Tan
Syntax
# = Tan(Num#)

Returns the tangent of Num#.
Example:
C# = Tan(9)
HyperTan
Syntax
# = HyperTan(Num#)

Returns the hyperbolic tangent of Num#.
Example:
C# = HyperTan(9)
Exp
Syntax
# = Exp(Num#)

Returns the exponential function of Num#.
Example:
C# = Exp(9)
Hypot
Syntax
# = Hypot(Side1#, Side2#)

Returns the length of the hypotenuse of a right triangle, given the length of its two sides.
Example:
C# = Hypot(2, 2)
Log
Syntax
# = Log(Num#)

Returns the natural logarithm of Num#.
Example:
C# = Log(9)
Log10
Syntax
# = Log10(Num#)

Returns the base-10 logarithm of Num#.
Example:
C# = Log10(9)
SqRoot
Syntax
# = SqRoot(Num#)

Returns the square root of Num#.
Example:
C# = SqRoot(9)
Ceiling
Syntax
# = Ceiling(Num#)

Rounds Num# up to the nearest integer value and returns the value.
Example:
'  C# will equal 2
C# = Ceiling(1.1)
Floor
Syntax
# = Floor(Num#)

Rounds Num# down to the nearest integer value and returns the value.
Example:
'  C# will equal 1
C# = Floor(1.1)
Average
Syntax
# = Average(Num1#, Num2# [, ... ])

Returns the average of a series of numerical values. A minimum of two values must be provided, but there is no maximum.
Example:
Avg# = Average(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
Error Handling
Errors which are due to a function or statement's inability to perform its task properly throw an K exception, causing script execution to halt at that point. Such errors may be both thrown and caught in the script for handling. Exceptions caused by invalid parameter values or syntax errors may not be caught.
Variables
ErrMsg
ErrFile
ErrLine
ErrPrompt
Statements
Try
Catch
Throw
Resume
Assert
Allow
ErrMsg
Type
ErrMsg$

Holds the descriptive text of the last error or warning.
ErrFile
Type
ErrFile$

Holds the name of the file in which the last error or warning occured.
ErrLine
Type
ErrLine#

Holds the line number where the last error or warning occured.
ErrPrompt
Type
ErrPrompt$

Holds the entire text of the last error or warning.
Try
The Try statement is used to catch any exceptions which may be thrown within the Try/EndTry block of script code. If an exception is thrown internally or by the script using the Throw statement, executions halts at the point where the exception was thrown and resumes at the Try/EndTry block's matching Catch statement. If no exception is thrown, the matching Catch statement is skipped.
Calling Break causes execution to jump immediately after the Try statement's corresponding EndTry.
See Also
Catch
Example:
'  this code *will* throw an exception because you
cannot remove the console device
Try
  Remove "con"
Catch
  MsgBox("Could not remove the console device!")
EndTry
Catch
If an exception is thrown inside a Try/Catch block, execution switches to the Catch block. Otherwise, Catch blocks are ignored when encountered in script code.
See
Try
Throw
Throw is used to throw a custom exception from within the script. If the Throw statement is wrapped in a Try/Catch/EndTry block, execution will be redirected to the Catch statement.
Example:
Throw "Houston, we have a problem."
Resume
When an exception is thrown, the Resume command may be used with the Catch section of a Try/Catch block to return the program to the point immediately after where the exception was thrown. This is useful for catching errors and forcing the script to continue executing as though no errors actually occured.
Example:
'  this bit code does only one thing:
'  show a message box
Try
  Remove "con"                  'cannot remove
console, will throw an error
  MsgBox("No worries mate!")    'executes because
resume returns execution to this point
Catch
  Resume
EndTry
Assert
Assert evaluates a test expression and throws a generic exception if the test evaluates to False.
See
Test Expressions
Example:
'  this code throws an error
  Assert 1=0
Allow
Allow permits the next statement to execute while ignoring any low-priority exceptions. It works the same as encasing a single statement with a Try/Catch/EndTry block.
Example:
'  this line does nothing, the exception is ignored
allow throw "This is an exception"
Stream and File I/O Commands
Stream I/O commands work with the standard input and output streams and are redirectable.
Console
Print
GetChar
GetString
IsKeyDown
IsKeyOn
ShowConsole
HideConsole
File
ReadFileLines
WriteFileLines
Print
Syntax
Print Output$

Writes Output$ to the standard output.
Example:
Print "This text goes to the console window"
GetChar
Syntax
$ = GetChar()

Returns the next key pressed at the keyboard.
Example:
Key$ = GetChar()
GetString
Syntax
$ = GetString()

Returns a string typed at the keyboard, storing all characters until RETURN is pressed.
Example:
Keys$ = GetString()
IsKeyDown
Syntax
# = IsKeyDown(Key$)

Returns TRUE if the specified Key$ is currently being pressed. Only the first usable key found in Key$ is used. Key$ may be an ASCII character or one of the keyboard escape codes.
Example
Keyboard Escape Codes
Example
IsDown# = IsKeyDown("\[F1]")
IsKeyOn
Syntax
# = IsKeyOn(Key$)

Returns TRUE if the specified Key$ is currently toggled on. Only works with toggle-style keyboard keys such as "NUMLOCK" or "CAPSLOCK". Only the first usable key found in Key$ is used. Key$ may be an ASCII character or one of the keyboard escape codes.
Example
Keyboard Escape Codes
Example
CapsOn# = IsKeyOn("\[CAPSLOCK]")
ShowConsole
Syntax
ShowConsole

The console is a DOS window which is typically opened only when an CodeCurve command is called which requires the console window or when an external DOS program is executed. Once opened, it stays open until the script terminates or it is explicitly closed. ShowConsole simply opens the console window, making it ready for use by a later command or program.
See
HideConsole
Example:
ShowConsole
HideConsole
Syntax
HideConsole

Closes the console window opened during script execution.
See
ShowConsole
Example:
HideConsole
ReadFileLines
Syntax
ReadFileLines FileName$, Array

Reads a text file into a string array. If the array already exists, it is overwritten; otherwise it is created. Each line in the file represents an element in the array.
Example:
'    redirects the output from the SET command to a file
'    and then loads the file into the array
Exec("SET > temp.tmp")
ReadFileLines "temp.tmp", EnvVars
WriteFileLines
Syntax
WriteFileLines FileName$, Array

Writes a string array to new text file. If the file already exists, it is overwritten; otherwise it is created.
Example:
WriteFileLines "temp.tmp", EnvVars
File System Commands
ChDir
MkDir
RmDir
Cwd
Copy
Move
Rename
Remove
Array.ReadFromFile
Array.WriteToFile
Image.ReadFromFile
Image.WriteToFile
GetFileExists
GetFileSize
GetFileAttributes
SetFileAttributes
GetDiskSize
GetDiskFreeSpace
GetDiskType
GetDiskVolumeName
GetDiskSerialNumber
GetLogicalDrives
Dir
ListFiles
GetShortFileName
GetLongFileName
GetTempFileName
GetTempDir
GetWinDir
GetSysDir
GetFileVersion
FormatPath
ChDir
Syntax
ChDir Path$

Changes the current working directory to Path$. If a drive letter is specified, the current drive is also changed.
Example:
ChDir "C:\Windows"
MkDir
Syntax
MkDirPath$

Creates the new directory Path$. This function fails if Path$ already exists.
Example:
MkDir "C:\MyDir"
RmDir
Syntax
RmDirPath$

Deletes the directory Path$. Path$ must point to an existing, empty directory.
Example:
RmDir "C:\MyDir"
Cwd
Syntax
$ = Cwd()

Returns the ful path, including drive letter, of the current working directory.
Example:
CurDir$ = Cwd()
Copy
Syntax
Copy SrcFile$, DestFile$

Copies a file named by SrcFile$ to a new file named by DestFile$.
Example:
Copy "C:\Test.txt", "C:\Test.old"
Move
Syntax
Move SrcFile$, DestFile$

Moves a file named by SrcFile$ to a new file named by DestFile$. If DestFile$ already exists or the drive specification is on a different drive volume than that of SrcFile$, an exception is thrown.
Example:
Move "C:\Test.txt", "C:\Test.old"
Rename
Syntax
Rename SrcFile$, DestFile$

Renames SrcFile$ to DestFile$.
Example:
Rename "C:\MyFile.tmp", "C:\MyFile.txt"
Remove
Syntax
Remove File$

Deletes the file File$.
Example:
Remove "C:\MyFile.tmp"
GetFileExists
Syntax
# = GetFileExists(FileName$)

Returns 1 if FileName$ exists. This command also works on directories.
Example:
IsThere# = GetFileExists("C:\MyFile.tmp")
GetFileSize
Syntax
# = GetFileSize(FileName$)

Returns the size, in bytes, if FileName$ exists. Otherwise returns -1.
Example:
Size# = GetFileSize("C:\MyFile.tmp")
GetFileAttributes
Syntax
$ = GetFileAttributes(FileName$)

Returns a string which indicates the file attributes of FileName$. The string consists of a series of letters each of which, when present, indicate that an attribute is "on" for the file.
Any of the following letters may appear in the return string:
A
File's archive bit is set

C
File is compressed

D
File is a directory

H
File is hidden

R
File is read-only

S
File is a system file

Example:
Attr$ = GetFileAttributes("C:\MyFile.tmp")
SetFileAttributes
Syntax
SetFileAttributes FileName$, Attr$

Sets the attributes for FileName$. Attr$ is a string which consists of a series of letters, each of which indicate which attribute to turn "on."
Any of the following letters may appear in Attr$:
A
Turn on the file's archive bit

H
Mark the file as hidden

R
Mark the file as read-only

S
Mark the file as a system file

Example:
' marks the file as read-only and turns on its archive bit
SetFileAttributes "C:\MyFile.tmp", "AR"
GetDiskSize
Syntax
# = GetDiskSize(Drive$)

Returns the size of Drive$, in bytes.
Example:
Size# = GetDiskSize("C:\")
GetDiskFreeSpace
Syntax
# = GetDiskSize(Drive$)

Returns the number of unused bytes for Drive$.
Example:
FreeSize# = GetDiskFreeSpace("C:\")
GetDiskType
Syntax
# = GetDiskType(Drive$)

Returns a number indicating Drive$'s type.
The return value may one of the following:
dtUnknown@
Disk type is not known

dtRemovable@
Disk media is removable (floppy)

dtFixed@
Disk is fixed (hard drive)

dtRemote@
Disk is remotely connected (network drive)

dtCDROM@
Disk is a CD-ROM drive

dtRamDisk@
Disk is a temporary drive located in memory

Example:
DiskType# = GetDiskType("C:\")
GetDiskVolumeName
Syntax
$ = GetDiskVolumeName(Drive$)

Returns the volume label of Drive$.
Example:
Label$ = GetDiskVolumeName("C:\")
GetDiskSerialNumber
Syntax
# = GetDiskSerialNumber(Drive$)

Returns the serial number of Drive$.
Example:
SerNum# = GetDiskSerialNumber("C:\")
GetLogicalDrives
Syntax
GetLogicalDrives DriveArray

Creates a new string array containing the drive letters of all logical drives available on the system.
Example:
GetLogicalDrives Drives
MsgBox(Drives$[1])
Dir
Syntax
$ = Dir([FileSpec$])

Returns the first file found matching the pattern given in FileSpec$. FileSpec$ may contain wildcard characters such as * and ?. To continue listing files that match the FileSpec$ pattern, omit FileSpec$ in subsequent calls. Even though a drive and directory may be given in FileSpec$, only the file name of files matching the pattern are returned.
See
ListFiles
Example:
'  Finds all files ending with .txt
'  in the root directory of C:
  New Files As StringArray
  File$ = Dir("C:\*.txt")
  While File$ <> ""
    Files.Add File$
    File$ = Dir()
  EndWhile
ListFiles
Syntax
ListFiles FileSpec$, Array [, Flags# ]

Lists an entire directory's contents and stores the result in a new string array. FileSpec is the wildcard file specification to list. Array is the new string array to create. Flags is an optional value which, if specified, filters the list of files found. The default value for Flags is an OR of all possible constant values.
Flags may be any combination of these constant values:
lfNormal@
Includes files with no attributes

lfDirectory@
Includes directories

lfHidden@
Includes hidden files

lfSystem@
Include system files

lfReadOnly@
Includes files with the read-only attribute set

lfArchive@
Includes files with the archive attribute set

Example:
ListFiles "C:\*.*", Dirs, lfDirectory@
GetShortFileName
Syntax
$ = GetShortFileName(FileName$)

Returns the short file name (8.3) of FileName$. If FileName$ is already the short name, GetShortFileName simply returns that name.
Example:
File$ = GetShortFileName(File$)
GetLongFileName
Syntax
$ = GetLongFileName(FileName$)

Returns the K long file name of FileName$. If FileName$ is already the long name, GetLongFileName simply returns that name.
Example:
File$ = GetLongFileName(File$)
GetTempFileName
Syntax
$ = GetTempFileName(Directory$)

Creates a new, empty file with a unique, unused name in the specified directory and returns the file name.
Example:
TempFile$ = GetTempFileName("C:\Temp")
GetTempDir
Syntax
$ = GetTempDir()

Returns the path used as the Windows temporary directory. Does not include a backslash. This path is typically: "C:\Windows\Temp"
Example:
TempDir$ = GetTempDir()
GetWinDir
Syntax
$ = GetWinDir()

Returns the path of the Windows directory. Does not include a backslash. This path is typically: "C:\Windows"
Example:
WinDir$ = GetWinDir()
GetSysDir
Syntax
$ = GetSysDir()

Returns the path of the Windows system directory. Does not include a backslash. This path is typically: "C:\Windows\System"
Example:
SysDir$ = GetSysDir()
GetFileVersion
Syntax
GetFileVersion File$, Array

Retrieves the 64-bit version number of the file given by File$. The value is stored in a 4-item number array, given by Array. The high byte of the major version is stored in the first item in the array, the low byte of the major version is stored in the second, the high byte of the minor version is stored in the third, and the low byte of the minor version is stored in the fourth.
Example:
GetFileVersion "C:\Windows\System\OBEngine.dll", Ver
Windows Shell Commands
System
DOSSpawn
WinSpawn
WinExec
ShellExec
MsgBox
MsgBeep
PlaySound
SetEnv
GetEnv
SetCaption
FindWindow
SendKeys
SendMouse
OpenDialog
SaveDialog
BrowseFolder
CreateLink
SetWallPaper
FileOperation
ExitWindows
GetWINVersion
System
Syntax
System CommandLine$ [, Array ]

Calls COMMAND.COM to execute a command as if it were entered on the DOS command-line.
If the optional parameter Array is provided, all console output is captured during execution and saved as a new string array. Each line sent to the console by the child process is added as an element of the array.
See Also
DOSSpawn
WinSpawn
WinExec
ShellExec
Example:
'    performs a DIR command which will find all files with a .TMP
'    extension and display them in a bare format. The TempFiles
'    array catches the output.  Each file found is stored in TempFiles
'    as an array element for easy retrieval.
System "DIR /s /b /-p *.tmp", TempFiles
DOSSpawn
Syntax
# = DOSSpawn(CommandLine$ [, Array ])

Spawns to execute a .COM, .EXE, .BAT or .CMD program. This function waits and returns the exit code of the spawned program. An exit code of anything other than 0 usually indicates an error. Similar to WinSpawn, this command opens the console so console input and output can take place.
If the optional parameter Array is provided, all console output is captured during execution and saved as a new string array. Each line sent to the console by the child process is added as an element of the array.
See Also
System
WinSpawn
WinExec
ShellExec
Example:
'    simple call to PKZIP
ErrorLevel# = Exec("PKZIP -rpu WINBACK.ZIP C:\Windows\*.*")
WinSpawn
Syntax
# = WinSpawn(CommandLine$)

Spawns to execute a .COM, .EXE, .BAT or .CMD program. This function waits and returns the exit code of the spawned program. An exit code of anything other than 0 usually indicates an error. Similar to DOSSpawn, this command leaves the console close because it is assumed the program being spawned is a Windows program, and does not require console I/O.
If the optional parameter Array is provided, all console output is captured during execution and saved as a new string array. Each line sent to the console by the child process is added as an element of the array.
See Also
System
DOSSpawn
WinExec
ShellExec
Example:
'    simple call to PKZIP
ErrorLevel# = Exec("PKZIP -rpu WINBACK.ZIP C:\Windows\*.*")
WinExec
Syntax
WinExec CommandLine$ [, Wait# ]

Creates a Windows process using CommandLine$. If Wait# is specified and not 0 (FALSE), execution will pause until the process is terminated. Wait# default is 0.
See Also
System
DOSSpawn
WinSpawn
ShellExec
Example:
'    load Notepad to edit a text file and wait
WinExec "Notepad C:\Temp.txt", 1
ShellExec
Syntax
ShellExec Document$ [, Verb$ [, Wait# ] ]

Exeutes a verb on a document using the Windows shell. If Verb$ is specified, it may indicate the action to take upon the document. If Wait# is specified and not 0 (FALSE), execution will pause until the process is terminated. Wait# default is 0.
See Also
System
DOSSpawn
WinSpawn
WinExec
Example:
'    load Notepad to edit a text file and wait
ShellExec "C:\Temp.txt", "open", 1
MsgBox
Syntax
# = MsgBox(Message$ [, Type# [, Title$ ]])

Displays a Windows message box containing the Message$ text. Type#, if provided, controls which icon and buttons appear on the message box. Title$, if provided, specifies the title the message box should show.
Type# can be a combination (OR) of one or more of these constant values:
mbAbortRetryIgnore@
ABORT, RETRY and CANCEL buttons

mbOK@
OK button

mbOKCancel@
OK and CANCEL buttons

mbRetryCancel@
RETRY and CANCEL buttons

mbYesNo@
YES and NO buttons

mbYesNoCancel@
YES, NO and CANCEL buttons

mbDefButton1@, mbDefButton2@, mbDefButton3@, mbDefButton4@
Change the default button to be pressed with the ENTER key

mtError@
STOP icon

mtWarning@
EXCLAMATION icon

mtInformation@
INFORMATION icon

mtQuestion@
QUESTION icon

The return value depends on which button the user clicked to close the message box. It can be one of the following values:
idAbort@
ABORT button pressed

idCancel@
CANCEL button pressed

idIgnore@
IGNORE button pressed

idNo@
NO button pressed

idOK@
OK button pressed

idRetry@
RETRY button pressed

idYes@
YES button pressed

Example:
Response# = MsgBox("Do you really want to do that?", mbYesNo@ | mtQuestion@)
MsgBeep
Syntax
MsgBeep [Type#]

Plays one of the Windows sounds which corresponds to Type#. Type# is optional and if it is not provided, a standard beep using the computer speaker will be played.
Type# can be any one of these constant values:
mbOK@
OK sound

mtError@
STOP sound

mtWarning@
EXCLAMATION sound

mtInformation@
INFORMATION sound

mtQuestion@
QUESTION sound

Example:
MsgBeep mtError@
PlaySound
Syntax
PlaySound Name$, Type@

Plays a .wav sound. Name$ can be either the filename of a .wav file or the alias of a system sound, depending on Type@'s value. Processing does not continue until the sound finishes playing.
If Type@ is sndFile@, Name$ is the name of a .wav file.
If Type@ is sndAlias@, Name$ is the alias of a system sound. Name$ can be any alias found in the Windows registry, but it is typically one of these values (wrap them in quotes for CodeCurve):
.Default
AppGPFault
Close
EmptyRecycleBin
MailBeep
Maximize
MenuCommand
MenuPopup
Minimize
Open
RestoreDown
RestoreUp
SystemAsterisk
SystemExclamation
SystemExit
SystemHand
SystemQuestion
SystemStart
Example:
'    plays the sound associated with the system exclamation,
'    or warning sound
PlaySound "SystemExclamation", sndAlias@
SetEnv
Syntax
SetEnv VarAndValue$

Adds or changes an environment variable's text value. VarAndValue$ must be in the form "Variable=Value."
Example:
SetEnv "PATH=" + GetEnv("PATH") + ";C:\MyDir"
GetEnv
Syntax
$ = GetEnv(Variable$)

Returns the text value of an environment variable.
Example:
Path$ = GetEnv("PATH")
SetCaption
Syntax
SetCaption Title$

Changes the title of the 32-bit console window open while a .COD executes.
Example:
SetCaption "My Program"
FindWindow
Syntax
FindWindow WindowTitle$

Searches for a window whose title begins with WindowTitle$. If a window is found, it is brought to the foreground.
Example:
FindWindow "Microsoft Word"
SendKeys
Syntax
SendKeys Keys$ [ , Pause# ]

Sends a series of keystrokes to the system, which will be posted to the currently active window. If provided, Pause is the number of seconds to wait between characters. Pause may be a fractional value (default is 0.05 seconds).
SendKeys may send simple ASCII characters or any one of the keyboard escape codes which represent non-ASCII or extended keys. Special character codes must be preceded with a single BACKSLASH (' \ '). To send one BACKSLASH, use two BACKSLASHes (' \\ ').
When \^, \@ or \+ appears before an ASCII character or one of the keyboard escape codes, all the keys are sent as a group with the ASCII/keyboard escape code.
See
Keyboard Escape Codes
Keyboard Escape Codes
Keyboard Escape Codes
\^
Control key

\@
Alt key

\+
Shift key

\[F##]
Any key F1-F...

\[TAB]
Tab key

\[BACK]
Backspace key

\[ESC]
Escape key

\[INS]
Insert key

\[DEL]
Delete key

\[HOME]
Home key

\[END]
End key

\[PAGEUP]
Page Up key

\[PAGEDOWN]
Page Down key

\[UP]
Up arrow key

\[DOWN]
Down arrow key

\[LEFT]
Left arrow key

\[RIGHT]
Right arrow key

\[PRINTSCREEN]
Print Screen key

\[SCROLLLOCK]
Toggles Scroll Lock key

\[NUMLOCK]
Toggles Num Lock key

\[CAPSLOCK]
Toggles Caps Lock key

\[PAUSE]
Pause key

Example
'    This example brings MS Word to the foreground and
'    opens a file named "C:\Docs\Test.doc"
FindWindow "Microsoft Word"
SendKeys "\@foC:\\Docs\\Test.doc" + 13
SendMouse
Syntax
SendMouse Button$, X#, Y# [ , Pause# ]

Sends a button click or double-click to the system, which will be posted to the currently active window. X and Y are where the button action should take place in absolute screen coordinates. If provided, Pause is the number of seconds to wait before sending the button action. Pause may be a fractional value (default is 0.05 seconds).
SendMouse may send left- or right-mouse button clicks. Special button names determine which button action will be posted. Only one button action may be posted with each call to SendMouse, although double-clicks may be sent with a single call.
LC
Single left-mouse button click

LDC
Double left-mouse button click

RC
Single right-mouse button click

RDC
Double right-mouse button click

Example
'    This example brings Notepad to the foreground and
'    closes it through the system menu, assuming
'    Notepad is maximized
FindWindow "*Notepad"
SendMouse "LDC", 8, 8
OpenDialog
Syntax
$ = OpenDialog([ Filter$ [, FileName$ [, Title$ [, MultiSelect#]]]])

Presents an "Open" file dialog. Filter$ is a file filter string in the form: "Filter One (*.one)|*.one|Filter Two (*.two)|*.two" FileName$, if specified, is the default file name to open. Title$, if specified, is the caption of the dialog (default is "Open").
If MultiSelect# is provided and TRUE, multiple files may be selected by the user. In this case, all files are returned, separated by carriage-return/line-feed characters. If you assign the return value to the Text property of a string array, the array will contain one item for each file name selected.
Returns the file name selected by the user. An empty return string indicates the user cancelled the dialog.
Single-Select Example:
File$ = OpenDialog()
MsgBox(File$)
Multiple-Select Example:
new Files as StringArray
Files.Text$ = OpenDialog("All Files (*.*)|*.*", " ", "Open File", True)
for I# = 1 to Files.Count
  MsgBox(Files$[I#])
endfor
SaveDialog
Syntax
$ = SaveDialog([ Filter$ [, FileName$ [, Title$ ]]])

Presents an "Save As" file dialog. Filter$ is a file filter string in the form: "Filter One (*.one)|*.one|Filter Two (*.two)|*.two" FileName$, if specified, is the default file name to save. Title$, if specified, is the caption of the dialog (default is "Save As").
Returns the file name selected by the user. An empty return string indicates the user cancelled the dialog.
Example:
File$ = SaveDialog()
BrowseFolder
Syntax
$ = BrowseFolder([ RootPath$ [, Label$ ] ])

Presents a "Browse for Folder" dialog. RootPath$, if specified, is the base path for the dialog; the user will not be able to browse higher than the root. Label$, if specified, is instructional text which will be shown immediately above the browse tree.
Example:
Path$ = BrowseFolder("C:\Windows\Favorites")
CreateLink
Syntax
CreateLink RealFileName$, LinkFileName$ [, Description$ [, WorkingDirectory$ [,
Arguments$ [, IconFileName, IconFileIndex# ]]]]

Creates a Windows95 shortcut. LinkFileName$ is a ".lnk" file that will be created, pointing to RealFileName$. Optional parameters include a description for the link.
The working directory and command-line arguments can be specified, as well as an alternate icon to display for the shortcut. IconFileName$ is an icon file (EXE, DLL, ICO) and IconFileIndex# specifies an index into the icon file where the icon is located (0 is the first icon found).
Example:
'    This example creates a shortcut to paint
'    brush and puts it in the Start Menu
CreateLink "C:\Windows\PBrush.exe",
"C:\Windows\Start Menu\Paint Brush.lnk"
SetWallPaper
Syntax
SetWallPaper BMPPath$

Changes the desktop wallpaper to use the .BMP file given by BMPPath$.
Example:
SetWallPaper "C:\Windows\Stone.bmp"
FileOperation
Syntax
FileOperation OpID#, From$, To$, Flags

Performs a Windows95 file operation through the shell. OpID specifies what action will take place. From$ is the name of the source file and To$ is the name of the destination file. Flags are additional values used to control the action.
OpID can be any one of these values:
foCopy@
Copies file given by From$ to the location To$

foDelete@
Deletes file given by From$

foMove@
Moves file given by From$ to the location To$

foRename@
Renames file given by From$ to the name To$

Flags can be any combination of these values:
fofNoConfirmation@
The shell does not ask the user for confirmation of the operation

fofNoConfirmMkDir@
If a directory must be created, shell does not prompt user

fofRenameOnCollision@
If the destination file name conflicts with an existing file name, renames automatically

fofSilent@
Performs all operations silently

Example:
FileOperation foCopy@, "C:\Windows\Desktop\File.txt", "A:\", fofRenameOnCollision@
ExitWindows
Syntax
ExitWindows Flags#

Performs an exit from Windows in a manner described by Flags#.
Flags# must be one of the following values:
ewLogOff@
Shuts down all process in the current security context and logs the user off

ewPowerOff@
Shuts down the system and turns off the power

ewReboot@
Shuts down and restarts the system

ewShutDown@
Shuts down the system to where it is safe to turn off the power

Example:
ExitWindows ewShutDown@
GetWINVersion
Syntax
GetWINVersion Array

Retrieves the K 64-bit K version number of the current running Windows system. The value is stored in a 4-item number array, given by Array. The high byte of the major version is stored in the first item in the array, the low byte of the major version is stored in the second, the high byte of the minor version is stored in the third, and the low byte of the minor version is stored in the fourth.
Example:
GetWINVersion Ver
Graphics Commands
The following commands and objects comprised CodeCurve's support for graphics.
The color commands encode and decode RGB values which may be used both with CodeCurve and any windows API calls.
Global Commands
MakeRGBColor
GetRColor
GetGColor
GetBColor
Not much here
Objects
Image
MakeRGBColor
Syntax
# = MakeRGBColor(R#, G#, B#)

Builds an RGB (red, green, blue) value using the values given by R# (red), G# (green) and B# (blue). The result is a complete color value which can be used by other CodeCurve graphic commands.
Example:
' Returns the RGB for dark-gray
DGray# = RGB(128, 128, 128)
GetRColor
Syntax
# = GetRColor(RGB#)

Returns the red value of a complete RGB color value.
GetGColor
Syntax
# = GetGColor(RGB#)

Returns the green value of a complete RGB color value.
GetBColor
Syntax
# = GetBColor(RGB#)

Returns the blue value of a complete RGB color value.
Miscellaneous Statements
Rem
Sleep
SleepUntil
Eval
Run
IsStringVar
IsNumberVar
IsStringArray
IsNumberArray
IsObject
IsLicensed
GetUserName
GetCPUType
RegisterExtension
Rem
Syntax
Rem

Causes the remainder of the line to be ignored; it is treated as a "remark." Used for commenting sections of the the source code. The character ' also acts as a comment character, causing everything after the ' to be ignored. The character ' also acts as a remark.
Example:
REM This is a comment
'   This is also a comment
Sleep
Syntax
Sleep Seconds# [, QuitOnMsg#]

Causes the script to stop executing and allow other Windows processes to run for Seconds#. The number of seconds may be fractional, but the precision is limited to thousandths of a second. If optional parameter QuitOnMsg is provided and is TRUE, the sleep will terminate whenever the user has performed any sort of input.
Example:
Sleep 5
SleepUntil
Syntax
SleepUntil DateTime# [, QuitOnMsg#]

Causes the script to stop executing and allow other Windows processes to run until the time given by DateTime# has arrived. DateTime# is a standard CodeCurve date/time value. If optional parameter QuitOnMsg is provided and is TRUE, the sleep will terminate whenever the user has performed any sort of input.
Example
' stops script for 2 seconds
SleepUntil Clock.SystemTime# + Clock.Time(0, 0, 2)
Eval
Syntax
Eval Macro$

Interprets a macro as though it were part of the script. All variables and objects available in the script at the point Macro$ is executed are also available to Macro$. Labels are discarded during execution of the macro and restored when the macro is finished executing.
See also
Array.Eval
Array.EvalForEach
Example:
Msg$ = "This is a macro!"
Macro$ = "MsgBox(Msg$)"
Eval Macro$
Run
Syntax
Run CMDLine$

Executes another script (.COD) file. CMDLine$ is a single-string containing any parameters that should be passed to the engine, and must include as the first parameter: the file name of the script. Remaining parameters are parsed and made available to the child script in the Argv$ string array.
If any catchable exception is thrown in the child script, you may catch it in the parent script as you normally would; using Try/Catch/EndTry or simply Allow.
Note: If any single parameter contains spaces, it must be wrapped in quote characters. The engine considers the space character (ASCII 32) a delimiter when parsing unless it appears inside quotes. The quotes are ultimately discarded.
For simplicity, if you wanted to run a script file named "C:\MyScript.cod", the call would be:
Run "C:\MyScript.cod"
But if the script file were named "C:\Program Files\My Application\Main.cod", you would need to wrap the script file name in quotes, making the call:
Run 34 + "C:\Program Files\My Application\Main.cod" + 34
The number, because it used where a string is expected, is automatically translated into an ASCII character. ASCII 34 is the quote character.
Example:
Run "C:\Backup.cod"
IsStringVar
Syntax
# = IsStringVar(Name)

Returns TRUE (1) if Name is an existing CodeCurve string variable.
Example:
TestExists# = IsStringVar(Test)
IsNumberVar
Syntax
# = IsNumberVar(Name)

Returns TRUE (1) if Name is an existing CodeCurve number variable.
Example:
TestExists# = IsNumberVar(Test)
IsStringArray
Syntax
# = IsStringArray(Name)

Returns TRUE (1) if Name is an existing CodeCurve string array.
Example:
TestExists# = IsStringArray(Test)
IsNumberArray
Syntax
# = IsNumberArray(Name)

Returns TRUE (1) if Name is an existing CodeCurve number array.
Example:
TestExists# = IsNumberArray(Test)
IsObject
Syntax
# = IsObject(Name)

Returns TRUE (1) if Name is an existing CodeCurve object.
Example:
TestExists# = IsObject(Test)
IsLicensed
Syntax
# = IsLicensed()

Returns TRUE (1) if the CodeCurve installation running the current script is registered. Returns FALSE (0) if the running version of CodeCurve is shareware.
Example:
Reg# = IsLicensed()
GetUserName
Syntax
$ = GetUserName()

Returns the name of the network user for this machine.
Example:
User$ = GetUserName()
GetCPUType
Syntax
# = GetCPUType()

Returns a number which indicates the type of CPU used by the system. The return value may be any one of the following values:
ptIntel_386@
CPU is an Intel 386

ptIntel_486@
CPU is an Intel 486

ptIntel_Pentium@
CPU is an Intel Pentium

ptMIPS_R4000@
CPU is a MIPS R4000

ptAlpha_21064@
CPU is an Alpha 21064

Example:
CPU# = GetCPUType()
RegisterExtension
Syntax
RegisterExtension ExtensionFile$

Registers the .OBX named by ExtensionFile$ for use with CodeCurve. Any new objects or object types register by the extension are available for use immediately.
Example:
RegisterExtension "C:\Windows\System\ODBC.obx"
Object Types
This is a list of the object types built-into the CodeCurve engine. For more information about objects, see Objects.
Objects
Application
Archive
Array
Clipboard
Clock
DDEClient
DLL
File
Form
Heap
IniFile
Image
MailSlot
OLEObject
Port
Printer
Registry
Socket
Status
Application
Application is a global object which represents the current script.
Properties
Handle
FileName
ExeFileName
Title
Author
Company
Copyright
ScreenWidth and ScreenHeight
MouseX and MouseY
Methods
ProcessEvents
Terminate
Application.Handle
Type
Application.Handle#

(read-only)
The module handle of the CodeCurve interpreter engine.
Example
hApp# = Application.Handle#
Application.FileName
Type
Application.FileName$

(read-only)
The full path name of the current script.
Example
Script$ = Application.FileName$
Application.ExeFileName
Type
Application.ExeFileName$

(read-only)
The full path name of the executable responsible for loading the CodeCurve engine and launching the script. The engine is contained in a DLL which is often loaded by an executable. If the script engine runs a script loaded by an EXE such as the editor, the standard launching EXE or as a compiled script, this property returns the original EXE file name.
Example
Script$ = Application.ExeFileName$
Application.Title
Type
Application.Title$

(read-only)
The script title, as entered into the summary information dialog when it was last edited.
Application.Author
Type
Application.Author$

(read-only)
The script author's name, as entered into the summary information dialog when it was last edited.
Application.Company
Type
Application.Company$

(read-only)
The company responsible for creating the script, as entered into the summary information dialog when it was last edited.
Application.Copyright
Type
Application.Copyright$

(read-only)
Copyright information for the script, as entered into the summary information dialog when it was last edited.
Application.ScreenWidthand ScreenHeight
Type
Application.ScreenWidth#

Application.ScreenHeight#

(read-only)
Returns the width and height of the monitor screen in pixels.
Application.MouseX and MouseY
Type
Application.MouseX#

Application.MouseY#

Gets and sets the mouse cursor position. Values are in screen coordinates (absolute), or relative to the upper-left corner of the screen.
Example:
'  Moves the mouse cursor to the
'  absolute 10, 10 position
Application.MouseX# = 10
Application.MouseY# = 10
Example:
'  Displays the mouse cursor's
'  absolute current position
MsgBox(Str(Application.MouseX#) + ", " + Str(Application.MouseY#))
Application.ProcessEvents
Syntax
Application.ProcessEvents

Allows the system to process messages for other windows currently open on the system. This is useful during loops, to allow the script to yield processing time to other applications so that they can perform tasks while the script is running. This is not critical under Windows95 or Windows NT, but it may sometimes be useful to allow CodeCurve forms to be painted properly during extensive loops.
Example
Application.ProcessEvents
Application.Terminate
Syntax
Application.Terminate

Stops executing the current script.
See
Stopping Scripts
Exit
Example
Application.Terminate
Archive
Syntax
New Archive ArchiveFile$

Archive is a dynamic object which reads and writes archive files using the deflate compression method. You must create an object of type Archive using New. Supply the archive file name to the constructor.
If the archive file does not exist, it will be created. If the file extension is omitted, ".ARK" will be appended to it.
Note: Utilities for both DOS and Windows that manage .ARK files handled by the Archive object are available at http://www.celsoft.com/downloads.html.
Example:
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
See
SetMode
AddFiles
ExtractFile
ExtractAllFiles
ShowStatus
HideStatus
Archive.SetMode
Syntax
Archive.SetMode

Controls how the archive object compresses and decompresses archive files. The constants shown below may be combined with the '|' (bitwise OR) operator and passed to SetMode. The default mode of an archive object is 0, meaning none of the options shown are set.
IncludeHiddenSystemFiles@
Compressing: includes any system or hidden files found.

SelectOnlyModifiedFiles@
Compressing: narrows file selection to files with their archive bit set.

ClearArchiveBit@
Compressing: clears the archive bit of any files added to archive file.

RecurseDirectories@
Compressing/Decompressing: searches all sub-directories/expands all sub-directories.

OverwriteNewerFiles@
Decompressing: causes files to be decompressed even if a newer file already exists.

Example:
'  this sets the archive mode to back-up all
'  files with the archive bit set, including
'  hidden or system files and then clears
'  the archive bit of the files backed-up
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
Archive.SetMode IncludeHiddenSystemFiles@ |
SelectOnlyModifiedFiles@ | ClearArchiveBit@ | RecurseDirectories@
Archive.AddFiles
Syntax
Archive.AddFiles FileSpec$ [, ExcludeArray ]

Adds one or more files to the archive file controlled by the archive object.
FileSpec$ may include wildcard characters such as '*' and '?'. If no directory is specified, the current working directory is presumed. If the RecurseDirectories@ value was passed to SetMode, all sub-directories of the specified directory (or the current working directory) are searched for files matching FileSpec$. ExcludeArray is a string array which, if provided, specifies which files should NOT be added to the archive. Strings in ExcludeArray may use wildcard characters.
Example:
'  this backs up all modified .C and
'  .CPP files found on drive C:
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
Arc.SetMode IncludeHiddenSystemFiles@ | SelectOnlyModifiedFiles@ | ClearArchiveBit@ | RecurseDirectories@
Arc.AddFiles "C:\*.c"
Arc.AddFiles "C:\*.cpp"
Archive.ExtractFile
Syntax
Archive.ExtractFile FileName$

Extracts a file with the name given by FileName$. When searching inside the archive file for FileName$, the directory part of the file name is ignored. For this reason, more than one file may be extracted as a result of this call.
The directory where the file was before it was compressed is stored in the archive file, not include the drive letter. When a file is extracted, the directory structure for the file is recreated using the current working directory as the base directory.
Example:
'  this restores AUTOEXEC.BAT, but only if the
'  current file is missing or is older than
'  the one in the archive file
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
Arc.ExtractFile "Autoexec.bat"
Archive.ExtractAllFiles
Syntax
Archive.ExtractAllFiles

Extracts all files found in the archive file.
The directory where each file was before it was compressed is stored in the archive file, not include the drive letter. When a file is extracted, the directory structure for the file is recreated using the current working directory as the base directory.
Example:
'  this restores all files in the archive
'  to the path C:\Temp.  Sub-directories will be
'  reconstructed in C:\Temp.
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
ChDir "C:\Temp"
Arc.ExtractAllFiles
Archive.ShowStatus
Syntax
Archive.ShowStatus

Displays a status dialog showing the progress of archive operations such as when adding or extracting files to/from an archive file.
See Also
HideStatus
Example:
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
Arc.ShowStatus
Arc.ExtractAllFiles
Archive.HideStatus
Syntax
Archive.HideStatus

Hides the status dialog shown by ShowStatus.
Example:
New Arc As Archive "C:\Windows\Desktop\Backup.ark"
Arc.ShowStatus
Arc.ExtractAllFiles
Arc.HideStatus
Array
StringArray Syntax
New StringArray

NumArray Syntax
New NumArray

StringArray and NumberArray are objects which provide additional functionality to arrays otherwise not available through the language itself. All arrays, no matter how they were created, are dynamic objects.
The first item in any array is 1.
Name/Value Indexing for String Arrays
Arrays contain multiple items which can be accessed using the syntax: Array$[Index#] (string arrays) or Array#[Index#] (number arrays). This syntax gets or sets the entire value of the item at Index#. However, string arrays have another method of indexing using Name/Value pairs.
If a string array contains the item "Line1=This is line 1", then the syntax Array$["Line1"] will return "This is line 1." You may also use Name/Value indexing to set values. This is useful for reading values from an array that has read an entire INI file section, but it is generally useful for storing/retrieving named values in any string array.
Example
New Lines As StringArray
Properties
Count
Text (string array only)
Total (number array only)
Average (number array only)
Min and Max (number array only)
Methods
Add
Insert
Delete
ReadFromFile (string array only)
WriteToFile (string array only)
Clear
Concat
ParseTok (string array only)
Encode (string array only)
Decode (string array only)
Find (string array only)
ReplaceAll (string array only)
Sort (string array only)
Eval (string array only)
EvalForEach
Array.Count
StringArray Type:
StringArray.Count#

NumArray Type
NumArray.Count#

Gets or sets the number of items in the array. If Count is set to a number higher than the number of items currently in the array, the array grows. If Count is set to a number lower, the array is truncated.
Example:
Lines.Count# = 100
Example:
Lines# = Lines.Count#
Array.Text
StringArray Type:
StringArray.Text$

Gets or sets the the entire string array as a single string containing each item as carriage-return/line-feed terminated lines.
Example:
'  sets the array to have two items
Lines.Text$ = "This is line 1" + 13 + "This is line 2"
Example:
'  copies the array's entire
'  contents to the clipboard
Clipboard.Text$ = Lines.Text$
Array.Total
NumArray Type
NumArray.Total#

(read-only)
Gets the total sum of all items in the number array.
Example:
Total# = Lines.Total#
Array.Average
NumArray Type
NumArray.Average#

(read-only)
Gets the average value of all items in the number array.
Example:
Avg# = Lines.Average#
Array.Minand Max
NumArray Type
NumArray.Min#

NumArray.Max#

(read-only)
Returns the minimum (Min) and maximum (Max) values found in the array. If no items are present (array is empty), then zero is returned.
Array.Add
StringArray Syntax
StringArray.Add Item$

NumArray Syntax
NumArray.Add Item#

Adds a new item to the end of the array, increasing the array's size by one.
Example:
Lines.Add "New Line"
Array.Insert
StringArray Syntax
StringArray.Insert Item$, Position#

NumArray Syntax
NumArray.Insert Item#, Position#

Inserts a new item into the array at Position. All items after Position# are shifted down, as the array grows by one.
Example:
Lines.Insert "New Line", 1
Array.Delete
StringArray Syntax
StringArray.Delete Position#

NumArray Syntax
NumArray.Delete Position#

Deletes the item at Position#, shrinking the array's size by one.
Example:
Lines.Delete 1
Array.ReadFromFile
StringArray Syntax
StringArray.ReadFromFile FileName$

Reads a text file into the string array. The array is cleared before loading the file. Each line in the file represents an element in the array.
Example:
'    redirects the output from the SET command to a file
'    and then loads the file into the array
New EnvVars As StringArray
Exec("SET > temp.tmp")
EnvVars.ReadFromFile "temp.tmp"
Array.WriteToFile
Syntax
StringArray.WriteToFile FileName$

Writes the string array to new text file. If the file already exists, it is overwritten; otherwise it is created.
Example:
EnvVars.WriteToFile "temp.tmp"
Array.Clear
StringArray Syntax
StringArray.Clear

NumArray Syntax
NumArray.Clear

Empties the array, leaving it with a size of 0.
Example:
Lines.Clear
Array.Concat
StringArray Syntax
StringArray.Concat OtherArray

NumArray Syntax
NumArray.Concat OtherArray

Appends all items in OtherArray to the array, increasing the array's size as necessary.
Example:
Lines.Concat UserLines
Array.ParseTok
StringArray Syntax
StringArray.ParseTok Text$, Tokens$ [, SkipLeading#]

Parses Text$ using characters found in Tokens$ as delimeters. The entire value of Text$ is parsed until no more tokens can be found. Parsed pieces of Text$ are added to the string array until parsing is complete.
If SkipLeading is provided and TRUE (default), ParseTok will skip past token characters found at the beginning in StringVarName. If FALSE, tokens found at the beginning of the string are considered part of the parse.
Note: This command works with string arrays only.
Example:
'  Lines will contain three new
'  items: Line1, Line2 and Line3
Lines.ParseTok "Line1;Line2;Line3", ";"
Array.Encode
StringArray Syntax
String.Array Encode Password$

Encodes the entire array using Password$. Each string item in the array become 7-bit ASCII strings, each twice the length of their original value. The encryption method is a moderately secure, but fairly simple algorithm.
Note: Celtech Software assumes no responsibility for the security of information encrypted using this routine.
See Also
Array.Decode
Encode
Example:
Password$ = "MyPassword"
ReadFileLines "C:\MyFile.txt", FileLines

FileLines.Encode Password$
MsgBox(FileLines.Text$)

FileLines.Decode Password$
MsgBox(FileLines.Text$)
Array.Decode
StringArray Syntax
StringArray.Decode Password$

Decodes the entire string array, encrypted by Encode using Password$, to the string items to their original values.
See Also
Array.Encode
Decode
Array.Find
StringArray Syntax
# = StringArray.Find([ Search$[ , IsCaseSensitive# ]] )

Returns the 1-based index of the first item found in the array matching the pattern given in Search. Search may contain wildcard characters such as * and ?. If IsCaseSensitive is specified and is FALSE, the search will locate lines regardless of case, otherwise the case is also matched (default is TRUE). To continue searching for items that match the Search pattern, omit Search in subsequent calls. When no (more) items can be found, Find returns 0.
Note: This command works with string arrays only.
Example:
'  Read the user's AUTOEXEC.BAT
'  and looks for references to the
'  Z: drive
  ReadFileLines "C:\Autoexec.bat", Lines
  Index# = Lines.Find("Z:", False)
  While Index# > 0
    MsgBox(Lines$[Index#])
    Index# = Lines.Find()
  EndWhile
Array.ReplaceAll
StringArray Syntax
# = StringArray.ReplaceAll(Search$, Replace$)

Replaces all instances of the string given by Search$ with the string given by Replace$. Returns the number of occurences replaced.
Note: This command works with string arrays only.
Example:
Lines.ReplaceAll("<Name>"", Name$)
Array.Sort
StringArray Syntax
StringArray.Sort [nFlags]

Sorts a string array using the quick-sort algorithm. nFlag (optional), if specified, determines how the sort will be performed. The default value for nFlags is 0.
Combine these values with the OR (|) operator for nFlags:
soCaseSensitive@
Considers upper or lower case when comparing strings (non-case sensitive is default).

soReverseOrder@
Sorts the array in descending order (ascending order is default).

Note: This command works with string arrays only.
Example:
'  lists all text files in the Windows directory
'  and sorts them
ListFiles "C:\Windows\*.txt", TextFiles
TextFiles.Sort
Array.Eval
StringArray Syntax
StringArray.Eval

Interprets the string array as though it were a multi-line text buffer and part of the script, called a macro. All variables and objects available in the script at the point the macro is evaluated are also available during execution. Labels are discarded during execution of the macro and restored when the macro is finished executing.
See also
Eval
EvalForEach
Example:
'    This example reads a text file and instructs
'    the interpreter to execute it as a script
New MyArray As StringArray
MyArray.ReadFromFile "test.txt"
MyArray.Eval
Array.EvalForEach
StringArray Syntax
StringArray.EvalForEach Macro$

NumArray Syntax
NumArray.EvalForEach Macro$

Interprets Macro$ repeatedly, once for each item in the array. Each time the macro is executed, a variable named is ArrayItem is set to the current array item being processed. If called with a string array, then the variable name is ArrayItem$; if called with a number array, the variable is named ArrayItem#.
See also
Eval
Example:
'  displays a series of message boxes
New MyArray As StringArray
MyArray.Add "Line 1"
MyArray.Add "Line 2"
MyArray.Add "Line 3"
MyArray.EvalForEach "MsgBox(ArrayItem$)"
Clipboard
The Clipboard object gives you the ability to cut and paste text to and from the Windows Clipboard. Because there is only one Windows Clipboard, the Clipboard object is global.
Properties
Text
Methods
Clear
RegisterFormat
IsFormatAvailable
SizeOfFormat
SetBuffer
GetBuffer
Clipboard.Text
Type
Clipboard.Text$

Gets or sets the text on the clipboard.
Example copying text to the clipboard
Clipboard.Text$ = "John"
Example pasting text from the clipboard
Name$ = Clipboard.Text$
Clipboard.Clear
Syntax
Clipboard.Clear

Empties the clipboard of its current contents.
Clipboard.RegisterFormat
Syntax
# = Clipboard.RegisterFormat(Format$)

Registers a new data type with the Windows clipboard. The return value is a special ID needed when setting/getting data on the clipboard.
Example:
SpecialCF# = Clipboard.RegisterFormat("My Special Data Type")
Clipboard.IsFormatAvailable
Syntax
# = Clipboard.IsFormatAvailable(Format#)

Returns TRUE (1) if data currently on the clipboard is available in the specified format ID. The Format# must be one of the pre-defined formats listed below or one that was previously registered with RegisterFormat by a script or another program.
Example:
IsAvail# = Clipboard.IsFormatAvailable(SpecialCF#)
Pre-Defined Clipboard Formats
cfText@
cfBitmap@
cfMetaFile@
cfSYLK@
cfDIF@
cfTIFF@
cfOEMText@
cfDIB@
cfPalette@
cfPenData@
cfRIFF@
cfWave@
cfUnicodeText@
cfEnhMetaFile@
cfHDrop@
cfLocale@
Clipboard.SizeOfFormat
Syntax
# = Clipboard.SizeOfFormat(Format#)

Returns the size, in bytes, of the format available on the clipboard.
See
IsFormatAvailable
Clipboard.SetBuffer
Syntax
Clipboard.SetBuffer Buffer#, Size#, Format#

Sets the data Buffer# on the clipboard, copying Size# bytes. Format# is a Windows data type format previously registered with RegisterFormat.
See Also
Heap
Example:
Clipboard.SetBuffer P#, 1024, SpecialCF#
Clipboard.GetBuffer
Syntax
Clipboard.GetBuffer Buffer#, Size#, Format#

Retrieves the data buffer from the clipboard, copying Size# bytes to the memory address given by Buffer#. Format# is a Windows data type format previously registered with RegisterFormat.
See Also
Heap
Example:
Clipboard.GetBuffer P#, 1024, SpecialCF#
Clock
Clock is a global object which provides time and date services. It uses a number value whose integer part is the number of days since the year 0000, and whose fractional part is the time of day (86,400 seconds in one day). This way of storing the time and date makes them fairly simple to manipulate using simple math.
Time/Date Values and Their Meaning
1 = One day
1 / 24 = One hour
(1 / 24) / 60 = One minute
((1 / 24) / 60) / 60 = One second
Properties
SystemTime
Methods
Year
Month
Day
Hour
Minute
Second
Weekday
IsLeapYear
Time
Date
GetFileTime
SetFileTime
Format
Clock.SystemTime
Type
Clock.SystemTime#

Gets or sets the current time.
Example:
'  Due 120 days from now
NoteDue# = Clock.SystemTime# + 120
Clock.Year
Syntax
# = Clock.Year(Time#)

Returns the current year from a number given in the clock format Returns 0 if nothing is specified for Time#.
Example:
NoteDue# = Clock.Now() + 120
YearDue# = Clock.Year(NoteDue#)
Clock.Month
Syntax
# = Clock.Month(Time#)

Returns the current month from a number given in the clock format Returns 0 if nothing is specified for Time#.
Example:
NoteDue# = Clock.Now() + 120
YearDue# = Clock.Year(NoteDue#)
MonthDue# = Clock.Month(NoteDue#)
Clock.Day
Syntax
# = Clock.Day(Time#)

Returns the current day from a number given in the clock format Returns 0 if nothing is specified for Time#.
Example:
NoteDue# = Clock.Now() + 120
YearDue# = Clock.Year(NoteDue#)
MonthDue# = Clock.Month(NoteDue#)
DayDue# = Clock.Day(NoteDue#)
Clock.Hour
Syntax
# = Clock.Hour(Time#)

Returns the hour ( 1 - 24 ) from a number in the clock format. Returns 0 if nothing is specified for Time#.
Example:
Hour# = Clock.Hour(Clock.Now)
Clock.Minute
Syntax
# = Clock.Minute(Time#)

Returns the minute from a number in the clock format. Returns 0 if nothing is specified for Time#.
Example:
Hour# = Clock.Hour(Clock.Now)
Minute# = Clock.Minute(Clock.Now)
Clock.Second
Syntax
# = Clock.Second(Time#)

Returns the second from a number in the clock format. Returns 0 if nothing is specified for Time#.
Example:
Hour# = Clock.Hour(Clock.Now)
Minute# = Clock.Minute(Clock.Now)
Second# = Clock.Second(Clock.Now)
Clock.Weekday
Syntax
# = Clock.WeekDay(Time#)

Returns a number (1 thru 7, Sunday thru Saturday) to represent the day of the week given a number in the clock format. Returns 0 if nothing is specified for Time#.
Example:
NoteDue# = Clock.Now() + 120
WeekDayDue# = Clock.WeekDay(NoteDue#)
'    Fix due date at Friday of that work week
NoteDue# = NoteDue# + (6 - WeekDayDue#)
Clock.IsLeapYear
Syntax
# = Clock.IsLeapYear(Time#)

Returns TRUE (1) if the year for Time# is a leap year, otherwise returns FALSE (0).
Example:
Leap# = Clock.IsLeapYear(Clock.SystemTime#)
Clock.Time
Syntax
# = Clock.Time(Hour#, Minute#, Second#)

Converts the hour, minute, and second into the clock format. Returns 0 if Hour#, Minute#, and Second# are not specified.
Example:
NoteDue# = Clock.Now() + 120
'    Fix time due at 6:00 PM
NoteDue# = (NoteDue# - (NoteDue# % 1)) +
Clock.Time(18, 0, 0)
Clock.Date
Syntax
# = Clock.Date(Year#, Month#, Day#)

Converts the year, month and day into the clock format. Returns 0 if Year#, Month#, or Day# are missing.
Example:
'    Sets DueDate# to June 2, 1999
DueDate# = Clock.Date(1999, 6, 2)
Clock.GetFileTime
Syntax
# = Clock.GetFileTime(FileName$)

Returns the date and time the file was last modified in the clock format. On Error, returns 0.
Example:
LastModified# = Clock.GetFileTime("MyFile.txt")
Clock.SetFileTime
Syntax
Clock.SetFileTime FileName$, Time#

Sets the last modified date and time of a file specified by FileName$ to the time and date given in Time#.
Example:
Clock.SetFileTime "MyFile.txt", Clock.Now()
Clock.Format
Syntax
$ = Clock.Format(Time#, Pattern$)

Formats a number given in clock format into a string using special formatting characters.
To generate a '$' character inline, place two '$$' together and they will compress into one in the final string.
Formatting characters and their meaning
$m
Month in short string format (Jan, Feb , etc)

#y
Year as number without century

$M
Month in long string format (January, February, etc)

#Y
Year as number with century

$d
Day in short string format (Sun, Mon, etc)

#m
Month as number

$D
Day in long string format (Sunday, Monday. etc)

#d
Day of month as number

$p
am or pm

#h
Hour 01-12

$P
AM or PM

#H
Hour 01-24

#n
Minutes 00-59

#s
Seconds 00-59

Example:
CurTime# = Clock.Now()
Msg$ = Clock.Format(CurTime#, "Current time and date: $D, $M #d, #Y, at #h:#n:#s $P")
MsgBox(Msg$, mbOK@)
DDEClient
Syntax
New DDEClient Server$, Topic$

DDEClient is a dynamic object which maintains a client-side conversation with a DDE server. You must create an object of type DDEClient using New. Supply the server and topic name to the constructor.
Example:
New ProgMan As DDEClient "PROGMAN", "PROGMAN"
See
Execute
Request
DDEClient.Execute
Syntax
DDEClient.Execute Cmd$

Sends an execute Cmd$ to the DDE server.
Example:
'  creates or activates a
'  Program Manager group named "TestGroup"
ProgMan.Execute "[CreateGroup(" + 34 + "TestGroup" + 34 + ")]"
DDEClient.Request
Syntax
$ = DDEClient.Request(Item$)

Sends an request to the DDE server for the value associated with Item$ and returns the response as a string.
Example:
'  returns a list of existing
'  Program Manager groups and displays them
Groups$ = ProgMan.Request("Groups")
MsgBox(Groups$)
DLL
The DLL object handles the loading and unloading of DLLs and provides an interface to call functions K exported by the DLL. Because virtually the entire Windows API is contained within DLLs, this object gives you complete access to it.
A single DLL object handles the loading and unloading of a single DLL. When you create a new DLL object, a corresponding DLL is loaded; when you delete the object or the script terminates, the DLL is unloaded.
Only one method is available initially to the DLL object: Declare. Declare links to an exported function within the DLL and requires a declaration of the function's return type and parameter types. Once declared, a function then becomes a method of the object and can be called directly in script code.
Note: CodeCurve does not provide help on the Windows API.
Example:
'  Loads USER32.DLL, an important Windows API DLL
New UserDLL As DLL "USER32.DLL"
'  Unloads the DLL
Delete UserDLL
See
Declare
DLL.Declare
Syntax
DLL.Declare FunctionName$, Parameters$ [, Reverse# ]

Links a new object method to the exported function given by FunctionName$. If the function is not found, an exceptional error is thrown.
Parameters$ is a string which describes the data types of the function's return value and parameters. The string is a series of comma-separated codes which are described in detail in DLL Parameter Declarations.
Reverse# is an optional parameter which tells the DLL object how to push parameters on the stack when an exported DLL function is called. By default, Reverse# is set to TRUE (1), meaning the parameters are passed right-to-left; this is the PASCAL calling convention. Setting Reverse# to FALSE (0) will cause the parameters to be passed left-to-right; the standard C calling convention.
There is no limit to the number of times Declare may be called with an object to link to functions exported by the DLL.
Example:
'  Loads USER32.DLL, links to the standard Windows
'  MessageBox function and then displays a message
'  box.  NOTE: the function name for MessageBox
'  ends with A to denote that we will link with
'  the version that accepts ANSI strings, rather
'  than UNICODE strings.  UNICODE functions may
'  end with a W.

New UserDLL As Dll "USER32.DLL"
UserDLL.Declare "MessageBoxA", "NU4, NU4, S, S, NU2"
UserDLL.MessageBoxA(0, "Test", "Test", 0)
DLL Parameter Declarations
Parameter declarations are strings which contain a series of comma-delimited codes. The first code in the series indicates the function's return type. Remaining codes indicate function parameters.
Parameter types can be either Void, String or Number. Strings and Numbers can be passed directly to the function by value, or by address. If a parameter is passed by value, a pointer to the parameter is pushed on the stack, rather than the value of the parameter itself. Strings are always passed as pointers, but passing a string explicitly by address allows the new value of the string buffer to be returned.
See
More On Passing Parameters By Address
CodeCurve type codes and the Windows data types they represent:
V
VOID

void

Return type only, nothing is returned

S, @S
LPSTR

LPCSTR

4-byte pointer to string

NU1
BYTE

unsigned char

1-byte unsigned integer

@NU1
BYTE *

unsigned char *

pointer to 1-byte unsigned integer

NS1
char

1-byte signed integer

@NS1
char *

pointer to 1-byte integer

NU2
WORD

WPARAM

UINT

unsigned short

2-byte unsigned integer

@NU2
WORD *

WPARAM *

UINT *

unsigned short *

pointer to 2-byte unsigned integer

NS2
short

2-byte signed integer

@NS2
short *

pointer to 2-byte signed integer

NU4
DWORD

LPARAM

ULONG

BOOL

unsigned long

4-byte unsigned integer

@NU4
DWORD *

LPARAM *

ULONG *

BOOL *

unsigned long *

pointer to 4-byte unsigned integer

NS4
long

4-byte signed integer

@NS4
long *

pointer to 4-byte signed integer

More On Passing Parameters By Address
When a parameter declaration is prefixed with '@', a 4-byte pointer to a variable is passed, rather than simply a value. This allows the DLL function to put a value into the address of the variable. When the function returns, that value will be available in the variable.
Whenever a DLL function parameter is prefixed with '@', the name of a variable must be provided, and the variable must already exist. For example, if a parameter is declared as NU4, then you may simply pass any valid expression which results in a number value, such as Var#. But if it declared as @NU4, then you must pass only a variable name, such as Var.
Strings are always passed as pointers, but there is a good reason at times for prefixing the parameter declaration with '@'. Without '@', the string buffer is discarded when the function returns. As well, any expression resulting in a string value may be provided, such as Var$. However, when the declaration is prefixed with '@', the string buffer is returned to the variable which must be passed by name in the parameter, such as Var.
Example
Notice the first code in the parameter declaration string is 'NU4'. That indicates the function's return type as a DWORD, or 4-byte unsigned integer. The second code, 'S', indicates the first parameter, which is simply a string pointer. The third code, @S, or second function parameter, you'll notice, is a string pointer being passed by address. This means the function will be modifying the string buffer and we will, of course, be interested in the buffer's new value. The last code and third parameter, NU4, is also a DWORD; it provides the function with the size of the buffer in the second parameter.
This function call will convert the long path name C:\Program Files to an 8.3 short file name. The short file name will be available in the variable Path$, when the function returns. Notice that before we make the function call, we create a 256-byte string buffer using the String command. This gives the function a place to write the new short file name.
New KrnlDLL As Dll "KERNEL32.DLL"
KrnlDLL.Declare "GetShortPathNameA", "NU4, S, @S, NU4"
Path$ = String(" ", 256)
KrnlDLL.GetShortPathNameA("C:\Program Files ", Path, 256)
MsgBox(Path$)
EMailLetter
EMailLetter is a powerful dynamic object which lets you create email letters and deliver them over the internet.
After creating the initial EMailLetter object, define desired header properties such as Subject and Priority and then set the text of the letter using the Body property. If you would like to attach files to the letter, use AddFileAttachment. When the letter is ready, you can either generate a letter file for your own internal use, or deliver directly to a recipient on the internet. The letter will be delivered using the SMTP protocol.
Constructor
EMailLetter ServerAddress$, FromAddress$ [, FromName$]
Example
Properties
ServerAddress
FromAddress
FromName
Header
Body
Subject
Organization
ReplyTo
Priority
Methods
AddFileAttachment
ClearFileAttachments
GenerateFile
Send
EMailLetter Example
Short Example
New Letter As EMailLetter "myisp.com", "myemail@myisp.com", "My Name"

Letter.Body$ = "This is a letter from CodeCurve's EMailLetter object"
Letter.Subject$ = "EMailLetter Test"
Letter.Priority# = empHigh@

Letter.AddFileAttachment "C:\Windows\Desktop\ForPersonOne.txt", "For You"

Letter.GenerateFile "C:\Windows\Desktop\SentToPersonOne.txt"
Letter.Send "personone@anyisp.com", "Person One"

Detailed Example
' create letter object, setting server address
' and sender information
New Letter As EMailLetter "myisp.com", "myemail@myisp.com", "My Name"

' re-set server address and sender information
' this is redundant, but is here for example
Letter.ServerAddress$ = "myisp.com"
Letter.FromAddress$ = "myemail@myisp.com"
Letter.FromName$ = "My Name"

' set the letter body
' shown is all three ways to do this, only one is needed
Letter.Body$ = "This is a letter from CodeCurve's EMailLetter object"
Letter.Body.Text$ = "This is a letter from CodeCurve's EMailLetter object"
Letter.Body.Add "This is a letter from CodeCurve's EMailLetter object"

' set the letter subject in the header
' shown are the two ways to do this, only one is needed
Letter.Subject$ = "EMailLetter Test"
Letter.Header$[Subject] = "EMailLetter Test"

' set your organization in the header
' shown are the two ways to do this, only one is needed
Letter.Organization$ = "My Company"
Letter.Header$[Organization] = "My Company"

' set the reply-to field in the header
' shown are the two ways to do this, only one is needed
Letter.ReplyTo$ = "myemail@myisp.com"
Letter.Header$[Reply-To] = "myemail@myisp.com"

' set the letter priority in the header
' shown are the two ways to do this, only one is needed
Letter.Priority# = empHigh@
Letter.Header$[X-Priority] = "1"

' add file attachment to letter
Letter.AddFileAttachment "C:\Windows\Desktop\ForPersonOne.txt", "For You"

' save letter as file
Letter.GenerateFile "C:\Windows\Desktop\SentToPersonOne.txt"

' send letter to person one
Letter.Send "personone@anyisp.com", "Person One"

' clear attachment so we can send letter again
Letter.ClearFileAttachments

' add a different file attachment
Letter.AddFileAttachment "C:\Windows\Desktop\ForPersonTwo.txt", "For You"

' again save letter as file
Letter.GenerateFile "C:\Windows\Desktop\SentToPersonTwo.txt"

' send letter to person two
Letter.Send "persontwo@anyisp.com", "Person Two"

EMailLetter.ServerAddress
Syntax
EMailLetter.ServerAddress$

Gets or sets the address of the SMTP server used to deliver the letter. This value is also set when the EMailLetter object is constructed.
EMailLetter.FromAddress
Syntax
EMailLetter.FromAddress$

Gets or sets the email address of person sending the letter. This value is also set when the EMailLetter object is constructed.
See Also
FromName
EMailLetter.FromName
Syntax
EMailLetter.FromName$

Gets or sets the name of person sending the letter. This value is also set when the EMailLetter object is constructed, although it is not required.
See Also
FromAddress
EMailLetter.Header
Header is a string array which represents all the name and value settings in the email letter header. The array uses string indexing, meaning the array should consist of nothing but "Name=Value" style strings. For example, the Subject of the letter is sent with the header, so the subject is stored in the Header object as "Subject=The Text of the Letter Subject".
The most popular header settings can be set by setting properties of the EMailLetter object directly. However, in case you need to set a header value the object does not provide for, this gives you direct access to the header.
See
Example
EMailLetter.Body
Syntax
EMailLetter.Body$

Gets or sets the body of the letter text. Body is a string property of the EMailLetter object AND a child string array object. So, you can also modify the body using string array member properties and methods as well as directly using the Body property.
See
Example
EMailLetter.Subject
Syntax
EMailLetter.Subject$

Gets or sets the subject of the letter. Subject directly manipulates the Header object.
See
Example
See Also
Header
EMailLetter.Organization
Syntax
EMailLetter.Organization$

Gets or sets your company name in the letter header. Organization directly manipulates the Header object.
See
Example
See Also
Header
EMailLetter.ReplyTo
Syntax
EMailLetter.ReplyTo$

Gets or sets Reply-To field in the letter header. ReplyTo directly manipulates the Header object.
See
Example
See Also
Header
EMailLetter.Priority
Syntax
EMailLetter.Priority#

Gets or sets the priority of the letter. Priority directly manipulates the Header object.
Constant priority values:
empLow@
5

empNormal@
3

empHigh@
1

See
Example
See Also
Header
EMailLetter.AddFileAttachment
Syntax
EMailLetter.AddFileAttachment SourceFileName$ [, Description$]

Adds a file attachment to the letter using Base64 MIME encoding. SourceFileName specifies the file to attach. Description, if provided, will be used as an alternate title for the file.
Any number of files may be attached to the letter. Be aware that MIME encoding increases the size of the letter by about twice the size of the file itself.
See
Example
EMailLetter.ClearFileAttachments
Syntax
EMailLetter.ClearFileAttachments

Removes all file attachments from the letter.
See
Example
EMailLetter.GenerateFile
Syntax
EMailLetter.GenerateFile DestFileName$, ToAddress$ [, ToName$]

Saves the entire letter as a text file to the name provided in DestFileName, including all file attachments and header settings. ToAddress and ToName are included in the letter header.
See
Example
EMailLetter.Send
Syntax
EMailLetter.Send ToAddress$ [, ToName$]

Sends the letter in its entirety to the recipient given in ToAddress. If ToName is provided, the To field in the header will use the recipient's name and address, otherwise the field will contain only the address.
If you show the Status dialog just prior to calling Send, the user will have the option to cancel sending of the letter and the EMailLetter object will display progress information.
Display the Status object to allow the user to cancel sending and to display progress information. If the user cancels the operation, Send throws an exception.
See
Example
See Also
Status
ExternalWindow
The primary purpose of the ExternalWindow object is to make controlling applications remotely an easier task. It connects to a window by either searching for a title name or attaching directly to a window handle. Methods and properties of an ExternalWindow object occur directly on the attached window itself.
Connection Syntax
new Object as ExternalWindow SearchSpec$ [ , ByClass# ]

Attach Syntax
new Object as ExternalWindow WindowHandle#

If you use the connection syntax to create a new ExternalWindow object and ByClass is not provided or is FALSE, SearchSpec specifies a window title to search for and may contain wildcard characters such as '*' and '?'. Where '*' appears, any set of characters will match. Where '?' appears any one character will match. If ByClass is TRUE, SearchSpec specifies a window class name and then it may NOT contain any wildcard characters; the class name must be an exact match with a window. Whether ByClass is TRUE or FALSE, the first match found terminates the search successfully.
If you use the attach syntax, simply pass any window handle.
Properties
Handle
Title
Class
Left, Top, Width and Height
WindowState
Methods
Show
Hide
Close
Activate
SendKeys
SendMouse
SendMessage
Example
' connection syntax to connect to
' any open notepad file, searching
' for a window title
new Win as ExternalWindow "*Notepad"
Example
' connection syntax to connect to
' any open notepad file, searching
' for a window class name
new Win as ExternalWindow "Notepad", true
Example
' attach syntax to connect to
' internal form
new Win as ExternalWindow Form1.Handle#
ExternalWindow.Handle
Type
ExternalWindow.Handle#

Gets or sets the window handle (HWND) of the attached window. You may change this window handle at any time.
Example:
'  Windows API way of changing the window title
New DLL As Dll "USER32.DLL"
DLL.Declare "SetWindowTextA", "NU4, NU4, S"
DLL.SetWindowTextA(ExternalWindow.Handle#, "New Title")
ExternalWindow.Title
Type
ExternalWindow.Title$

Gets or sets the caption of the attached window.
Example:
'  CodeCurve way of changing the window title
ExternalWindow.Title$ = "New Title"
ExternalWindow.Class
Type
ExternalWindow.Class$

(read-only)
Returns the class name of the attached window.
Example:
'  Displays the window class name
'   of the attached window
MsgBox(ExternalWindow.Class$)
ExternalWindow.Left, Top, Width and Height
Type
ExternalWindow.Left#

ExternalWindow.Top#

ExternalWindow.Width#

ExternalWindow.Height#

Positions the attached window by controlling its origins and dimensions. Changing the Left# property changes how far the window is from the left side of the screen.
Example:
'  Moves window to the upper-left
'  corner of the screen
ExternalWindow.Left# = 0
ExternalWindow.Top# = 0
ExternalWindow.WindowState
Type
ExternalWindow.WindowState#

Returns or changes the state of the attached window.
WindowState may be one of the following values:
wsNormal@
Window is neither maximized nor minimized.

wsMinimized@
Window is shown minimized (iconic).

wsMaximized@
Window is shown maximized.

ExternalWindow.Show
Syntax
ExternalWindow.Show

Makes the attached window visible and places it in its normal state.
ExternalWindow.Hide
Syntax
ExternalWindow.Hide

Makes the attached window invisible.
ExternalWindow.Close
Syntax
ExternalWindow.Close

Closes the attached window.
ExternalWindow.Activate
Syntax
ExternalWindow.Activate [ToForeground#]

Activates the attached window. If ToForeground is specified and is TRUE, the window is activated and forced into the foreground, otherwise it is merely activated and will only appear in the foreground if the window's thread is already in the foreground.
Example:
ExternalWindow.Activate True
ExternalWindow.SendKeys
Syntax
ExternalWindow.SendKeys Keys$ [ , Pause# ]

Sends a series of keystrokes to the associated window. This functions works exactly like the global SendKeys command, but it ensures that all keystrokes will go to the attached window.
See
SendKeys (global command)
ExternalWindow.SendMouse
Syntax
ExternalWindow.SendMouse Button$, X#, Y# [ , Pause# ]

Sends a button click or double-click to the associated window. This functions works exactly like the global SendMouse command, but it ensures that all mouse actions will go to the attached window.
See
SendMouse (global command)
ExternalWindow.SendMessage
Syntax
# = ExternalWindow.SendMessage(Msg#, WParam#, LParam#)

Sends a message using the Windows API to the window attached to the object. Msg# is the message number to send (usually WM_...). WParam# and LParam# are additional values to send with the message; their value and meaning depends on the message being sent. Returns the value returned by the API SendMessage call.
If the message requires that a structure is passed to WParam or LParam, see the Heap object on how to construct memory buffers.
For more information on using SendMessage, see your Windows API documentation.
File
The File object type is used to create dynamic file objects which allow you to read/write any file. Files are opened in binary mode, but methods such as ReadString and WriteString treat the file as a text file. The constructor takes a True/False argument that causes the object's text methods to treat the file as a unix text file (unix file lines are delimited with linefeed (ASCII(10) characters while DOS file lines are delimited with return/linefeed (ASCII(13)/ASCII(10)) pairs.).
Syntax
New Object$ As File FileName$ [, AsUnix# ]

FileName$ is opened for reading/writing if possible. If the file cannot be written to, it is simply opened for reading. If the file does not exist, it will be created. If AsUnix# is provided and is True, text methods such as ReadString and WriteString will use unix style line termination (default is False).
The file remains open until the object is deleted. No other applications can access the file until you delete the object.
Properties
Handle
FileName
Methods
WriteString
ReadString
WriteNum
ReadNum
WriteBuffer
ReadBuffer
WriteCompressedFile
ReadCompressedFile
GetLength
GetPos
SetPos
Flush
File.Handle
Type
File.Handle#

(read-only)
The file handle (HFILE) of the open file object.
File.FileName
Type
File.FileName$

The file name of the open file object.
File.WriteString
Syntax
File.WriteString String$

Writes String$ to the file as a though the file were a text file; writing begins at the current file pointer position. If in DOS mode, appends ASCII(13)+ASCII(10). In opened in unix mode, appends ASCII(10).
Example:
File.WriteString "This is a line of text"
File.ReadString
Syntax
$ = File.ReadString([ Max# ])

Reads a line of text from the file beginning at the current file pointer position. Reading ends until either the line terminator is found (ASCII(13)+ASCII(10) for DOS mode, ASCII(10) for unix mode) or until the end of the file is reached. If Max# is provided, reading stops when Max# characters have been read if the line terminator has not been reached.
Example:
Line$ = File.ReadString()
File.WriteNum
Syntax
File.WriteNum Number#, Type#

Writes the value of Number# to the file as a binary integer. Type# specifies how many bytes to copy and whether the number is signed or unsigned.
Type# may be any one of the following values:
fnByte@
Write as a 1-byte unsigned integer

fnChar@
Write as a 1-byte signed integer

fnWord@
Write as a 2-byte unsigned integer

fnShort@
Write as a 2-byte signed integer

fnDWord@
Write as a 4-byte unsigned integer

fnLong@
Write as a 4-byte signed integer

Example:
File.WriteNumber 0, fnByte@
File.ReadNum
Syntax
# = File.ReadNum(Type#)

Reads a binary integer from the file. See WriteNum for possible values for Type#.
Example:
A# = File.ReadNum(fnByte@)
File.WriteBuffer
Syntax
# = File.WriteBuffer(Buffer#, Size#)

Writes Size# number of bytes from the memory address given by Buffer# to the file as binary data. Returns the number of bytes actually written.
Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Written# = File.WriteBuffer(P#, 1024)
File.ReadBuffer
Syntax
# = File.ReadBuffer(Buffer#, Size#)

Reads Size# number of bytes from the file into the memory address given by Buffer#. Returns the number of bytes actually read.
Buffer# should be the memory address of a buffer sufficiently large enough to hold the number of bytes being requested. Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Read# = File.ReadBuffer(P#, 1024)
File.WriteCompressedFile
Syntax
# = File.WriteCompressedFile(SourceFileName$)

Writes the file identified by SourceFileName as a compressed buffer to the file. No information about the file (time stamp, attributes) are stored; only the contents of SourceFileName itself. Returns the number of compressed bytes written.
Example:
File.WriteCompressedFile("Test.exe")
File.ReadCompressedFile
Syntax
# = File.ReadCompressedFile(DestFileName$)

Reads a compressed buffer from the file and writes it as a new file to DestFileName. Returns the number of compressed bytes read from the file.
Example:
File.ReadCompressedFile("Test.exe")
File.GetLength
Syntax
# = File.GetLength()

Returns the current size of the open file, in bytes.
Example:
Size# = File.GetLength()
File.GetPos
Syntax
# = File.GetPos()

Returns the current file pointer position, in bytes offset from the beginning of the file.
Example:
Pos# = File.GetPos()
File.SetPos
Syntax
File.SetPos Offset#, Origin#

Moves the file pointer position by Offset# bytes from Origin#. To move the pointer forward, use a positive number. To move backwards through the file, use a negative number.
Origin# may be any one of the following constants:
fpFromBegin@
New position is calculated from the beginning of the file

fpFromCurrent@
New position is calculated from the current file pointer position

fpFromEnd@
New position is calculated from the end of the file

Example:
'  moves to end of file
File.SetPos 0, fpFromEnd@
File.Flush
Syntax
File.Flush

Forces any data written to the file to be written to the physical drive. Files are often buffered, meaning that while writing to a file, the data is not written immediately to the disk. Flushing offers a way to ensure the data goes to the disk.
Example:
File.Flush
Form
Forms
Forms are static objects which represent the forms designed in .COD file. They are pre-loaded and ready to show or otherwise manipulate using the commands listed.
Forms typically do not return unless the user has closed it from the system menu, clicked a push-button, double-clicked a list box or clicked a menu item. When the form returns from Show, the return value is the name of the last control acted upon by the user. The value returned from the Show command is the name of the control which caused the return.
Controls
Controls contained on a form are represented by child objects. Each control has its own child object which, through a set of properties and methods, can be used to manipulate the controls and obtain information about them.
Graphics placed on the form are available as child Image objects.
See
Form Child Controls
Form Menus
Image
Menus
Menus created in the form editor are displayed with each form at run-time. If a menu item is clicked, as with push-buttons, the form returns the name of the menu item causing the return. If a hot-key is associated with a menu item, pressing the hot-key sequences will also cause the form to return as if the menu item itself were clicked.
Form Properties
Handle
Title
Left, Top, Width and Height
ClientWidth and ClientHeight
MouseX and MouseY
WindowState
Form Methods
Show
Hide
Activate
Refresh
GetControlIDFromName
GetControlHandleFromName
GetControlNameFromID
Form Child Controls
Form controls are child objects which represent the controls contained on a parent form. Controls are added and edited using the Forms editor in the CodeCurve editor. At run-time, controls which were part of a form created in the CodeCurve editor are attached to objects so that they are more easily manipulated in script code. These objects are "child" objects of the parent form object.
Using form control objects are just about as easy as using any other object. The only difference is that their names are preceded with the name of the form object. For example, where you might change a form's caption using:
Form.Title$ = "My Form"
...to change a control's window text, you would write:
Form.Static.Text$ = "My Label"
All controls have the standard properties and methods listed below. Controls such as text boxes, check boxes, radio buttons, list boxes and combo boxes have an additional set of properties and methods which are available only to them. These special control objects are subclassed from the standard control object, so they can still use the standard properties and methods.
Graphics which are placed on forms are not available as controls. Instead, graphics are associated with an Image object. The graphic may be modified through the Image object only.
Form Control Properties
Controls
ControlCount
Control Properties
Handle
ChildID
ObjectName
ObjectType
Text
Left, Top, Width and Height
IsFocused
IsEnabled
IsVisible
CheckState (check boxes only)
IsChecked (check boxes and radio buttons only)
SelectedIndex (radio buttons only)
Lines (list boxes and combo boxes only)
SelectedText (list boxes and combo boxes only)
SelectedIndex (list boxes and combo boxes only)
SelectedText (text boxes only)
SelectStart (text boxes only)
SelectLength (text boxes only)
Control Methods
SetFocus
SelectIndex (list boxes and combo boxes only)
GetSelectedStrings (list boxes and combo boxes only)
GetSelectedIndexes (list boxes and combo boxes only)
SetTabStops (list boxes only)
Form Menus
Menus are extremely simple to use in CodeCurve. Created in the editor, at run-time menus appear on the form and perform much like Buttons. When a menu item is selected by the user, the name of the menu item is return from Show. This allows the script to take action based on the user selection.
Form.Controls
Type
Form.Controls

(read-only)
Child object array representing all controls on the form. The array index begins at 0 and continues to Form.ControlCount
Example:
'  Form1 has one control named Button1
'  both message boxes display the same name
MsgBox(Form1.Controls{1}.ObjectName$)
MsgBox(Form1.Button1.ObjectName$)
Form.ControlCount
Type
Form.ControlCount#

(read-only)
The number of items in array Form.Controls.
Form.Control.Handle
Type
Form.Control.Handle#

(read-only)
The window handle (HWND) of the control object.
Example:
'  Windows API way of changing the control's text
New DLL As Dll "USER32.DLL"
DLL.Declare "SetWindowTextA", "NU4, NU4, S"
DLL.SetWindowTextA(Form.TextBox.Handle#, "New Text")
Form.Show(fsModal@)
Form.Control.ChildID
Type
Form.Control.ChildID#

(read-only)
The child ID of the control object. Child ID's are how Windows identifies child windows contained on dialogs, and are rarely used with CodeCurve.
Form.Control.ObjectName
Type
Form.Control.ObjectName$

(read-only)
Returns the object name of the control.
Example:
MsgBox(Form.TextBox.ObjectName$)
Form.Control.ObjectType
Type
Form.Control.ObjectType$

(read-only)
Returns the object type name of the control.
Example:
MsgBox(Form.TextBox.ObjectType$)
Form.Control.Text
Type
Form.Control.Text$

Returns or changes the window text of the associated control. All controls have window text, but not all controls display or use their window text. List boxes and list-style combo boxes do not make use of their window text at all. Editable combo boxes use their window text as the text box portion of their window area.
Example:
'  Change the text box's value
Form.TextBox.Text$ = "Your Name Here"
Form.Control.Left, Top, Width and Height
Type
Form.Control.Left#

Form.Control.Top#

Form.Control.Width#

Form.Control.Height#

Positions the control by controlling its origins and dimensions. Changing the Left# property changes how far the control is from the left in the form's client area.
Example:
'  Fills form with text box
Form.TextBox.Left# = 0
Form.TextBox.Right# = 0
Form.TextBox.Width# = Form.ClientWidth#
Form.TextBox.Height# = Form.ClientHeight#
Form.Control.IsFocused
Type
Form.Control.IsFocused#

(read-only)
Returns TRUE if the control currently has the input focus, otherwise returns false.
See Also
SetFocus
Form.Control.IsEnabled
Type
Form.Control.IsEnabled#

Returns or changes the enabled state of the control. To disable a control, set this property to FALSE; to enable the control, set it to TRUE.
Form.Control.IsVisible
Type
Form.Control.IsVisible#

Returns or changes whether or not a control is visible. To hide a control, set this property to FALSE; to display the control, set it to TRUE.
Form.Control.SetFocus
Syntax
Form.Control.SetFocus

Gives the control the input focus.
Example:
Form.TextBox.SetFocus
See Also
IsFocused
Form.CheckBox.CheckState
Type
Form.Control.CheckState#

Returns or changes the checked state of a check box control. Check state may be any of the following values:
0
Unchecked

1
Checked

2
Indeterminate (grayed)

Form.CheckBox/RadioButton.IsChecked
Type
Form.Control.IsChecked#

Returns or changes the checked state of the check box or radio button. To set a check, set this property to TRUE; to remove a check, set it to FALSE. Setting a radio button to checked causes all other radio buttons in its group to be unchecked.
See Also
SelectedIndex
Form.RadioButton.SelectedIndex
Type
Form.Control.SelectedIndex#

Returns or changes which radio button within a group is currently checked.
A group of radio buttons is any set of buttons arranged together by tab order. The first radio button in the set has the group style turned on, while the rest have their group styles turned off. Any radio button with its group style turned on indicates the beginning of a radio button group. All radio buttons between that first button and the next control which is either not a radio button or which has its group style turned on are considered part of the group.
If SelectedIndex is 1, the first radio button in the group will be checked. If SelectedIndex is 2, the second button will be checked, and so on. To uncheck all radio buttons in the group, set SelectedIndex to 0.
All radio buttons within a group will use the same SelectedIndex value; that is, SelectedIndex operates on the group as a whole, so it doesn't matter which radio button in the group it is used with.
Form.ListBox/ComboBox.SelectedText
Type
Form.Control.SelectedText$

(read-only)
Returns the selected line(s) in a list box or combo box as a single string. Multiple lines, if present, are delimited by carriage return/linefeed pairs, making the returned text suitable for assignment to the Text property of any string array.
Edit-style combo boxes should use the control's Text property to retrieve the selected value. However, list-style combo boxes should use SelectedText.
Form.ListBox/ComboBox.SelectedIndex
Type
Form.Control.SelectedIndex#

Returns or selects a line(s) in a list box or combo box. If used with a combo box or single-line list box, SelectedIndex indicates the currently selected line. If used with a multi-line list box, this property either returns the last line selected or selects a line without de-selecting any other lines.
Form.TextBox.SelectedText
Type
Form.Control.SelectedText$

Returns or changes the selected text in the text box. If no text is selected, setting this property simply inserts text at the current cursor location.
Form.TextBox.SelectStart
Type
Form.Control.SelectStart#

Returns or changes the start of the selection in a text. The selection start is 1-based, the leftmost position is 1. Selection begins at SelectStart and continues for the distance given by SelectLength.
Form.TextBox.SelectLength
Type
Form.Control.SelectLength#

Returns or changes the length of the selection in a text. Selection begins at SelectStart and continues for the distance given by SelectLength.
Form.ListBox/ComboBox.SelectIndex
Syntax
Form.Control.SelectIndex Index#, Select#

Turns selection of the line indicated by Index# on if Select# is TRUE, or off if Select# is FALSE.
Form.ListBox/ComboBox.Lines
Lines is a child object of list box and combo box objects. It represents lines in the boxes as a standard CodeCurve string array. All of the method and properties of the string array object are available with Lines. Use Lines to add, remove, sort, and otherwise manipulate the control.
Standard language syntax regarding string arrays is completely available with the Lines object member.
See
String Array
Example:
Form.ListBox.Lines.Add "New Line"
Form.ListBox.Lines$[1] = "Changed Line"
Form.ListBox.Lines.Add "Another Line"
Form.ListBox.Line.Sort
MsgBox(Form.ListBox.Lines.Text$)
Form.ListBox/ComboBox.GetSelectedStrings
Syntax
Form.Control.GetSelectedStrings Array

Saves all the selected lines in the list box or combo box as a new string array. This method returns the same values as the SelectedText property.
Form.ListBox/ComboBox.GetSelectedIndexes
Syntax
Form.Control.GetSelectedIndexes Array

Saves the indexes of all the selected lines in the list box or combo box as a new number array.
Form.ListBox.SetTabStops
Syntax
Form.Control.SetTabStops Tab1# [ , Tab2#...]

Sets tab stop values for the list box. Tab stops can be used to create columns in a list box if lines contain tab characters. Tab stop values are given in pixels but because of the Windows system of using dialog units, actual tab stop locations will not be precise. There is no limit to the number of tab stops that can be set.
Form.Handle
Type
Form.Handle#

(read-only)
The window handle (HWND) of the form object.
Example:
'  Windows API way of changing the form title
New DLL As Dll "USER32.DLL"
DLL.Declare "SetWindowTextA", "NU4, NU4, S"
DLL.SetWindowTextA(Form.Handle#, "New Title")
Form.Show(fsModal@)
Form.Title
Type
Form.Title$

Gets or sets the caption of the form.
Example:
'  CodeCurve way of changing the form title
Form.Title$ = "New Title"
Form.Show(fsModal@)
Form.Left, Top, Width and Height
Type
Form.Left#

Form.Top#

Form.Width#

Form.Height#

Positions the form by controlling its origins and dimensions. Changing the Left# property changes how far the form is from the left side of the screen.
Example:
'  Moves form to the upper-left corner of the screen
Form.Left# = 0
Form.Top# = 0
Form.ClientWidth and ClientHeight
Type
Form.ClientWidth#

Form.ClientHeight#

(read-only)
Returns the width and height of the form's client area.
Example:
'  Fills form with text box
Form.TextBox.Left# = 0
Form.TextBox.Right# = 0
Form.TextBox.Width# = Form.ClientWidth#
Form.TextBox.Height# = Form.ClientHeight#
Form.MouseX and MouseY
Type
Form.MouseX#

Form.MouseY#

Gets and sets the mouse cursor position. Values are in client coordinates, or relative to the upper-left corner of the form window's client area.
Example:
'  Moves the mouse cursor to the 10, 10 position
'  within the form's client area
Form.MouseX# = 10
Form.MouseY# = 10
Example:
'  Displays the mouse cursor's current position
'  (within the form's client area)
MsgBox(Str(Form.MouseX#) + ", " + Str(Form.MouseY#))
Form.WindowState
Type
Form.WindowState#

Returns or changes the state of the form.
WindowState may be one of the following values:
wsNormal@
Form is neither maximized nor minimized.

wsMinimized@
Form is shown minimized (iconic).

wsMaximized@
Form is shown maximized.

Form.Show
Syntax
$ = Form.Show([ ShowCommand# ])

Displays the form (makes it visible).
ShowCommand# can be any of these values. They will determine when Show returns and what the value means:
fsNonModal@
Returns immediately, leaving the form showing while continuing
to execute the script. The return value is the last control acted upon by the
user, but the return value will be cleared after it is retrieved once.

fsModal@
Shows the form and halts execution until the form is closed, a
button is pushed or a list box is double-clicked. The form will close before
Show returns. The return value is the control which caused Show to return.

fsSemiModal@
Shows the form exactly like fsModal@ does. When Show
returns, however, the form remains on the screen and it goes into a state
exactly like fsNonModal@.

fsCmdSemiModal@
Behaves exactly like fsSemiModal@ does except that almost any control interaction will
cause Show to return. If the return value specifies any control other than the form itself,
a push button or a menu item, the event which caused the return should not be relied upon.

fsTrayIcon@
Places the form as an icon in the system tray, pausing the script. When the icon is
clicked, the form becomes visible and non-modal, returning control to the script immediately.

Example:
'  shows the form and saves the control
'  name of the button which closed the
'  form in Ctrl$
Ctrl$ = Form.Show(fsModal@)
Form.Hide
Syntax
Form.Hide

Closes a non-modal form.
Example:
Form.Hide
Form.Activate
Syntax
Form.Activate [ToForeground#]

Activates the form. If ToForeground is specified and is TRUE, the form is activated and forced into the foreground, otherwise it is merely activated and will only appear in the foreground if the script is already the active application.
Example:
Form.Activate True
Form.Refresh
Syntax
Form.Refresh

Causes the form to repaint itself.
Form.GetControlIDFromName
Syntax
# = Form.GetControlIDFromName(Name$)

Returns the child ID of the control specified by Name$.
Form.GetControlHandleFromName
Syntax
# = Form.GetControlHandleFromName(Name$)

Returns the window handle (HWND) of the control specified by Name$.
Form.GetControlNameFromID
Syntax
# = Form.GetControlNameFromID(ID#)

Returns the text name of the control specified by ID#.
Heap
The Heap object is a global object which provides a related group of memory-management functions. Use it to allocate and deallocate memory buffers, as well as read and write to and from them. Memory buffers are useful when numbers or strings are too primitive, such as when reading/writing with the Registry object or when calling DLL functions.
Methods
Alloc
AllocString
ReAlloc
Free
SizeOf
Set
Copy
WriteNum
WriteString
ReadNum
Readstring
Heap.Alloc
Syntax
# = Heap.Alloc(Size#)

Allocates a buffer of Size# bytes. Return value is the address of the memory buffer.
See Also
Free
Example:
P# = Heap.Alloc(128)
Heap.AllocString
Syntax
# = Heap.AllocString(Src$)

Allocates a buffer large enough to hold the string Src$ and copies the string into that buffer. The buffer size is the length of the string + 1. The extra byte is needed to hold a NULL terminating character. Return value is the address of the memory buffer.
See Also
Free
Example:
P# = Heap.AllocString("C:\Windows\Desktop\File.txt")
Heap.ReAlloc
Syntax
# = Heap.Alloc(Buffer#, Size#)

Changes the size of an existing Buffer# to Size# bytes. Return value is the new address of the memory buffer.
See Also
Free
Example:
P# = Heap.ReAlloc(P#, 1024)
Heap.Free
Syntax
Heap.Free Buffer#

Frees a memory buffer allocated with Alloc, AllocString or ReAlloc.
Example:
Heap.Free P#
Heap.SizeOf
Syntax
# = Heap.SizeOf(Buffer#)

Returns the size of a memory buffer allocated with Alloc, AllocString or ReAlloc.
Example:
Size# = Heap.SizeOf(P#)
Heap.Set
Syntax
Heap.Set Buffer#, Char#, Length#

Sets all bytes of Buffer# to the value of Char# for up to Length# bytes.
Example:
Heap.Set P#, 0, 1024
Heap.Copy
Syntax
Heap.Copy BufDest#, BufSrc#, Length#

Copies all bytes in BufSrc# to BufDest#. Length# is the maximum number of bytes to copy.
Example:
Heap.Copy P#, A#, 1024
Heap.WriteNum
Syntax
Heap.WriteNum Buffer#, Number#, Type#

Writes the value of Number# to Buffer# as an integer. Type# specifies how many bytes to copy and whether the number is signed or unsigned.
Type# may be any one of the following values:
hnByte@
Write as a 1-byte unsigned integer

hnChar@
Write as a 1-byte signed integer

hnWord@
Write as a 2-byte unsigned integer

hnShort@
Write as a 2-byte signed integer

hnDWord@
Write as a 4-byte unsigned integer

hnLong@
Write as a 4-byte signed integer

To access different sections of the buffer, use simple arithmatic to increment the buffer address.
Example:
'  Write a byte of zero to the fourth byte location
Heap.WriteNum P# + 3, 0, hnByte@
Heap.WriteString
Syntax
Heap.WriteString Buffer#, Text$

Writes Text$ as a NULL-terminated string to Buffer#.
To access different sections of the buffer, use simple arithmatic to increment the buffer address.
Example:
'  Write a string starting at the first byte location
Heap.WriteString P#, "ABC"
Heap.ReadNum
Syntax
# = Heap.ReadNum(Buffer#, Type#)

Reads an integer from Buffer#. See WriteNum for possible values for Type#.
To access different sections of the buffer, use simple arithmatic to increment the buffer address.
Example:
A# = Heap.ReadNum(P# + 4, hnByte@)
Heap.Readstring
Syntax
$ = Heap.ReadString(Buffer#)

Reads a NULL-terminated string from Buffer#.
To access different sections of the buffer, use simple arithmatic to increment the buffer address.
Example:
A$ = Heap.ReadString(P#)
IniFile
Syntax
New IniFile FileName$

IniFile is a dynamic object which provides read/write access to .INI files. You must create an object of type IniFile using New, passing the name of the .INI file the object will control to the constructor.
Example:
New WinIni As IniFile "C:\Windows\win.ini"
Properties
FileName
Methods
WriteNum
WriteString
ReadNum
ReadString
ReadKeys
ReadSectionNames
ReadKeyNames
DeleteSection
DeleteKey
IniFile.FileName
Type
IniFile.FileName$

Gets or sets the INI file name used when performing read/write operations.
Example changing INI file name
WinIni.FileName$ = "C:\Windows\MyScript.ini"
Example getting INI file name
FN$ = WinIni.FileName$
IniFile.WriteNum
Syntax
IniFile.WriteNum Section$, Key$, Value#

Write Value# to Key$ in Section$ of the .INI the object controls.
Example:
WinIni.WriteNum "My Section", "NumberValue", 123
IniFile.WriteString
Syntax
IniFile.WriteString Section$, Key$, Value$

Write Value$ to Key$ in Section$ of the .INI the object controls.
Example:
WinIni.WriteString "My Section", "StringValue", "123"
IniFile.ReadNum
Syntax
# = IniFile.ReadNum(Section$, Key$[, DefaultValue#])

Returns the number value of Key$ in Section$ of the .INI the object controls. If provided, DefaultValue# is returned when Key$, Section$ or the .INI does not exist.
Example:
Value# = WinIni.ReadNum("My Section", "NumValue")
IniFile.ReadString
Syntax
$ = IniFile.ReadString(Section$, Key$[, DefaultValue$])

Returns the string value of Key$ in Section$ of the .INI the object controls. If provided, DefaultValue$ is returned when Key$, Section$ or the .INI does not exist.
Example:
Value$ = WinIni.ReadString("My Section", "StringValue")
IniFile.ReadKeys
Syntax
IniFile.ReadKeys Section$, Array

Creates a global string array named Array and fills it with the keys and values found under Section$ in the .INI the object controls. Keys and values appear in the array as "Key=Value", and is suitable for use with string array name indexing.
Example:
WinIni.ReadKeys "My Section", Keys
IniFile.ReadSectionNames
Syntax
IniFile.ReadSectionNames Array

Creates a global string array named Array and fills it with the section names of all sections in the .INI the object controls.
Example:
WinIni.ReadSectionNames SectionNames
IniFile.ReadKeyNames
Syntax
IniFile.ReadKeyNames Section$, Array

Creates a global string array named Array and fills it with the key names found under Section$ in the .INI the object controls.
Example:
WinIni.ReadKeyNames "My Section", SectionKeys
IniFile.DeleteSection
Syntax
IniFile.DeleteSection Section$

Deletes the entire Section$ found in the .INI the object controls.
Example:
WinIni.DeleteSection "My Section"
IniFile.DeleteKey
Syntax
IniFile.DeleteKey Section$, Key$

Deletes the key named by Key$ from Section$.
Example:
WinIni.DeleteKey "My Section", "MyKey"
Image
Syntax
New Image Width#, Height#

An Image object is a bitmap surface which may be drawn upon using any of the methods listed below.
The Image object is available in two forms: as a dynamic object which can be used to generate graphic images in memory or as static child objects which are associated with form bitmap graphics.
Graphics embedded in forms while in the script editor are available at run-time as Image objects. Any drawing performed on a form graphic will change the image while the script is executed.
Properties
Handle
CellHeight and CellWidth
ImageWidth and ImageHeight
X and Y
ForeColor and BackColor
PenWidth
Methods
SetFont
WriteStringLine
WriteStringRect
DrawLine
DrawRect
DrawRoundRect
DrawFillRect
DrawEllipse
DrawImage
ReadFromFile
WriteToFile
CopyToClipboard
PasteFromClipboard
See Also
Example of using the Image object
Image.Handle
Syntax
Image.Handle#

(read-only)
Returns the Windows GDI device context handle associated with the image. This handle is used by windows API drawing commands.
Image.CellHeightand CellWidth
Syntax
Image.CellHeight#

Image.CellWidth#

(read-only)
Returns the cell dimensions (height and width, respectively) of a single character cell in pixels.
See
Example of using the Image object
Image.ImageWidthand ImageHeight
Syntax
Image.ImageHeight#

Image.ImageWidth#

(read-only)
Returns the dimensions (height and width, respectively) of the entire image in pixels.
See
Example of using the Image object
Image.Xand Y
Syntax
Image.X#

Image.Y#

Gets or sets the current cursor position expressed in the current units of measurement.
See
Example of using the Image object
Image.ForeColorand BackColor
Syntax
Image.ForeColor#

Image.BackColor#

Gets or sets the color values used when drawing lines and filling areas. Values are expressed in RGB (red, green, blue).
See
Graphics Commands
Example of using the Image object
Image.PenWidth
Syntax
Image.PenWidth#

Gets or sets the width of the pen used to draw lines.
See
Example of using the Image object
Image.SetFont
Syntax
Image.SetFont FontName$, PointSize#, Attributes#

Changes the font used when drawing text. FontName$ is any available Windows font, such as Arial, Times New Roman, etc. PointSize# is the size of the font in points. Attribute controls additional formatting the font should use (default is faNormal@).
faNormal@
Font uses no special formatting

faBold@
Font appears bold

faItalic@
Font appears italicized

faUnderline@
Font appears underlined

faStrikeOut@
Font appears with a line through it, as though struck-out

See
Example of using the Image object
Image.WriteStringLine
Syntax
Image.WriteStringLine Text$ [ , XPos#, YPos#]

Writes Text$ on the image. If optional parameters XPos and YPos are given, the text is printed at that position, otherwise printing occurs at the current cursor position. XPos and YPos are expressed in pixels. After drawing, the current cursor position is updated.
See
Example of using the Image object
Image.WriteStringRect
Syntax
Image.WriteStringRect Text$, XPos#, YPos#, Width#, Height#, Alignment#

Writes Text$ on the image within the rectangle area given by XPos, YPos, Width and Height. Alignment determines how the text is aligned within the rectangle area. XPos, YPos, Width and Height are expressed in pixels. Unlike most other text printing commands, the current cursor position is not updated by this method.
Alignment may be any one of the following values:
taLeft@
taCenter@
taRight@
See
Example of using the Image object
Image.DrawLine
Syntax
Image.DrawLine XOffset#, YOffset#

Draws a straight line from the current cursor position to the offsets. XOffset and YOffset are not absolute position values; they are relative to the current cursor position. XOffset and YOffset are expressed in pixels. The thickness of the pen is controlled by the PenWidth property.
See
Example of using the Image object
Image.DrawRect
Syntax
Image.DrawRect X#, Y#, Width#, Height#

Draws a rectangle at X, Y of the dimensions given by Width and Height. X, Y, Width and Height are expressed in pixels. The rectangle is drawn using the current ForeColor and PenWidth and is filled using the current BackColor.
See
Example of using the Image object
Image.DrawRoundRect
Syntax
Image.DrawRoundRect X#, Y#, Width#, Height#, CornerWidth#, CornerHeight#

Draws a rounded rectangle at X, Y of the dimensions given by Width and Height and using CornerWidth and CornerHeight to draw tangent arcs at each corner of the rectangle. All values are expressed in pixels. The rectangle is drawn using the current BackColor and PenWidth and is filled using the current BackColor.
See
Example of using the Image object
Image.DrawFillRect
Syntax
Image.DrawFillRect X#, Y#, Width#, Height#

Draws a rectangle at X, Y of the dimensions given by Width and Height. X, Y, Width and Height are expressed in pixels. The rectangle is not given a border but is filled using the current BackColor.
See
Example of using the Image object
Image.DrawEllipse
Syntax
Image.DrawEllipse X#, Y#, Width#, Height#

Draws an ellipse at X, Y within the rectangle bounded by Width and Height. X, Y, Width and Height are expressed in pixels. The ellipse is drawn using the current ForeColor and PenWidth and is filled using the current BackColor.
See
Example of using the Image object
Image.DrawImage
Syntax
Image.DrawImage X#, Y#, ImageObject

Draws another image on the current image at the location given by X and Y. X and Y are expressed in pixels. ImageObject is the name of another Image object.
See
Example of using the Image object
Image.ReadFromFile
Syntax
Image.ReadFromFile FileName$

Loads the BMP file given by FileName and makes it the current image.
See
Example of using the Image object
Image.WriteToFile
Syntax
Image.WriteFromFile FileName$

Writes the current image as a BMP file, creating or overwriting the file given by FileName.
See
Example of using the Image object
Image.CopyToClipboard
Syntax
Image.CopyToClipboard

Copies the bitmap stored in the Image object to the clipboard.
Image.PasteFromClipboard
Syntax
Image.PasteFromClipboard

Replaces the bitmap stored in the Image object with the bitmap currently on the clipboard.
Example of using the Image object
The following script shows how to use the Image object as both a dynamic object and as a child object of a Form object. The example assume a script has been created with one form named Form1 which has one graphic named Graphic1.
' create a memory image and load forest.bmp into it
new Img as Image 10, 10
Img.ReadFromFile "C:\Windows\Forest.bmp"

' initialize image properties
Form1.Graphic1.PenWidth# = 20
OldColor# = Form1.Graphic1.ForeColor#
Form1.Graphic1.ForeColor# = MakeRGBColor(255, 0, 0)
Form1.Graphic1.BackColor# = MakeRGBColor(0, 255, 0)

' draw a fat, red line
Form1.Graphic1.X# = 30
Form1.Graphic1.DrawLine 50, 0

Form1.Graphic1.PenWidth# = 1
Form1.Graphic1.ForeColor# = OldColor#

' draw forest.bmp onto the form graphic
Form1.Graphic1.DrawImage 30, 30, Img

' draw a series of shapes
Form1.Graphic1.DrawRect 10, 10, 20, 20
Form1.Graphic1.DrawFillRect 30, 30, 20, 20
Form1.Graphic1.DrawRoundRect 50, 50, 20, 20, 10, 10
Form1.Graphic1.DrawEllipse 70, 70, 20, 40

' write text two different ways
Form1.Graphic1.SetFont "Times New Roman", 16, faNormal@
Form1.Graphic1.WriteStringLine "Hello", 50, 120
Form1.Graphic1.WriteStringRect "Hello", 0, 120,
  Form1.Graphic1.ImageWidth#, Form1.Graphic1.CellHeight#, taCenter@

' save the resulting form graphic as a new BMP file
Form1.Graphic1.WriteToFile "C:\Windows\Desktop\Test\Test2.bmp"

' show the form to display the new image
Form1.Show(fsModal@)
JetDatabase
The JetDatabase object is used to open or create a Microsoft AccessTM database file. It is used only in conjunction with the JetTable object.
Note: Use of the JetDatabase and JetTable objects requires that you have Data Access Objects (DAO) installed on your system. If you have installed MS Access on your system, you already have DAO installed.
Using The JetDatabase/JetTable Objects
Example
Constructor
JetDatabase FileName$, Action
FileName$ is the name of the database file. Action can be Create, to create a new database, or Open to open an existing one.
Properties
DatabaseName
Methods
CreateQuery
DeleteTable
DeleteQuery
JetDatabase.DatabaseName
Syntax
JetDatabase.DatabaseName$

(read-only)
Returns the file name of the database.
See
Example
JetDatabase.CreateQuery
Syntax
JetDatabase.CreateQuery QueryName$, SQL$

Adds a new query definition to the database. QueryName$ is the user name of the query, and SQL$ is an SQL statement to assign to the query. The SQL statement should be a regular "SELECT" statement, which can include fields from other tables, a "WHERE" statement and a "SORT BY" statement.
See
Example
JetDatabase.DeleteTable
Syntax
JetDatabase.DeleteTable TableName$

Deletes the table definition given by TableName$ from the database.
See
Example
JetDatabase.DeleteQuery
Syntax
JetDatabase.DeleteQuery QueryName$

Deletes the query definition given by QueryName$ from the database.
See
Example
JetTable
The JetTable object, in conjunction with the JetDatabase object, allows you native access to Microsoft(r) Access(tm) database files.
Note: Use of the JetDatabase and JetTable objects requires that you have Data Access Objects (DAO) installed on your system. If you have installed MS Access on your system, you already have DAO installed.
Using The JetDatabase/JetTable Objects
Example
Constructor
JetTable JetDB, TableName$, Action
JetDB must be an opened JetDatabase object. TableName$ is the user name of a table or query in the database. Action can be Create, to create a new table, or Open to open an existing one. If a table by the name given is not available, the Table object attempts to open a query by that same name.
Properties
TableName
IsReadOnly
CanBookmark
BOF
EOF
Methods
CreateField
CreateIndex
MapMember
CreateStructFields
SetRecordFieldValues
GetRecordFieldValues
Add
Edit
Update
Cancel
Delete
MoveFirst
MoveLast
MoveNext
MovePrev
Find
SetBookmark
GotoBookmark
GetNumFieldValue
SetNumFieldValue
GetStringFieldValue
SetStringFieldValue
JetDatabase/JetTable Example
Available Examples
JetTable Example of Creating a New Database
JetTable Example of Adding/Editing Records
JetTable Example of Creating a New Database
Creating a New Database
' delete the database just in case
allow Remove "Test.mdb"

' create the new database
new DB as JetDatabase "Test.mdb", Create

' create a new table
new TB as JetTable DB, "People", Create

' define a struct to use with
' the new table
struct PersonStruct
  ID[stLong@]
  Name[stString@, 32]
endstruct

' create some fields
' create the ID field separately
' so we can make it an autoinc and
' the primary index
TB.CreateField "ID", jftAutoInc@, true
TB.CreateStructFields PersonStruct

' create an index for the name field
TB.CreateIndex "Name", false

' create a query that lists everyone
' whose names starts with "Bob"
DB.CreateQuery "Bobs", "SELECT * FROM People WHERE Name Like ""Bob*"""
JetTable Example of Adding/Editing Records
Adding/Editing Records
' open the database
new DB as JetDatabase "Test.mdb", Open

' open the "People" table
new TB as JetTable DB, "People", Open

' define a struct to use with
' the table
struct PersonStruct
  ID[stLong@]
  Name[stString@, 32]
endstruct

' create instance of PersonStruct
new Person as Record PersonStruct

' add a record using
' the table property way
TB.Add
TB.Name$ = "Andy"
TB.Update

' using a Record object
TB.Add
Person.Name$ = "Bob"
TB.SetRecordFieldValues Person
TB.Update

' setting a field value directly
TB.Add
TB.SetStringFieldValue "Name", "Chuck"
TB.Update

' change the first record
TB.MoveFirst
TB.Edit
TB.Name$ = "Anthony"
TB.Update
Using The JetDatabase/JetTable Objects
Creating The JetTable Object
First, create a JetDatabase object to open or create a new Access(tm) database. Then, create a JetTable object to open or create a table, or open a query in the database.
Creating/Opening New Tables and Queries
Creating new tables is different from opening them. When you open a table, you have immediate access to the table. When you create a new table, the table does not really exist until you create at least one field definition. Once the table has at least one field definition, you may perform other actions on the table such as add records, create indices, etc.
Opening a query is simple. You just pass the name to the constructor of the Table object as if you were opening a table. Tables and queries cannot have the same name in the database, so if the object cannot open a table by the name you give, it attempts to open a query.
Creating a new query is far simpler, although radically different from creating new tables. Creating new tables is a little complicated because you have to provide field definitions for the table. So, new tables are created through the table object. Queries, however, are created through the database object using the CreateQuery command.
Adding Field Definitions
Once you have an opened or created a Table object, you can add new field definitions to the table (not query) using CreateField. Once a table is opened fully you can create new field indexes using CreateIndex. Another, more powerful way to create fields is to define a structure and use CreateStructFields to create a bunch of new fields based on the structure definition. The struct keyword and Record object work hand-in-hand, so the same struct you use to create new fields would also probably be the struct you use to create a new Record object that you can use to set/retrieve field values with.
Adding/Editing Records
Now that you have an open table (with fields defined) or query, you can add new records to the database using Add or edit existing records using Edit.
Scrolling Through The Table
To scroll through the records in the table or query, use the MoveFirst, MoveLast, MoveNext, and MovePrev commands. Be sure to test BOF and EOF when scrolling, to tell if you have scrolled outside the list of records.
Accessing Field Values
When you are at a record and want to view or edit field values, you can do it two ways. If the name of the field has no spaces, the field value is available as a member property of the Record object. Meaning, if the table or query has a field named "Name", you can using Table.Name$ to set or get the value contained in the record field. If the field has spaces in the name, you can map it to a new field name which will allow you to still access the value as a property if you use the MapMember command. Otherwise, you will have to use GetNumFieldValue, SetNumFieldValue, GetStringFieldValue, or SetStringFieldValue.
Searching
If you want to find a specific record, you can scroll to a record using Find. Find is powerful, using wildcard characters (like '*' and '?') which should be familiar to many.
Bookmarking
Once you are at a record that you want to remember the location of, but need to scroll elsewhere, you can set a bookmark to scroll directly back to the record. See SetBookmark and GotoBookmark.
JetTable.TableName
Syntax
JetTable.TableName$

(read-only)
Returns the user-name of the table or query.
See
Example
JetTable.IsReadOnly
Syntax
JetTable.IsReadOnly#

(read-only)
Returns FALSE if you can edit records in the table or query, otherwise returns TRUE.
See
Example
JetTable.CanBookmark
Syntax
JetTable.CanBookmark#

(read-only)
Returns TRUE if you can set bookmarks to locate records in the table or query, otherwise returns FALSE.
See
Example
JetTable.BOF
Syntax
JetTable.BOF#

(read-only)
Returns TRUE when the table or query is scrolled before the first record in the table.
See
Example
EOF
JetTable.EOF
Syntax
JetTable.EOF#

(read-only)
Returns TRUE when the table or query is scrolled past the last record in the table.
See
Example
BOF
JetTable.CreateField
String Field Syntax
JetTable.CreateField FieldName$, Type#, Size# [, PrimaryIndex#]

All Other Fields Syntax
JetTable.CreateField FieldName$, Type# [, PrimaryIndex#]

Use CreateField to add new fields to a table (not query). You can add new fields to an existing table, or one you create by passing Create to the JetTable constructor. Type# specifies the field type. PrimaryIndex#, if provided and is TRUE, will cause the field to be made the primary index for the table. Size# is used for fields of type jftText@, and specifies the size in bytes of the field.
Constants for Type#:
jftAutoInc@
An Auto-incrementing number field, useful for generating unique IDs

jftBool@
A number field which can only be TRUE or FALSE

jftByte@
A 1-byte unsigned number field

jftShort@
A 2-byte signed number field

jftLong@
A 4-byte signed number field

jftCurrency@
A floating-point number field used for calculating monetary values

jftSingle@
A 4-byte floating-point number field

jftDouble@
An 8-byte floating-point number field

jftDate@
A floating-point number field used for dates/times (uses CodeCurve date/times)

jftText@
A fixed-length string field, requires Size# parameter

jftMemo@
A variable-length string field, DOES NOT require size parameter

See
Example
JetTable.CreateIndex
Syntax
JetTable.CreateIndex FieldName$ [, IsUnique#]

Creates an index for the field named by FieldName$. IsUnique#, if provided and TRUE (default) forces values in the field to be unique, meaning no duplicate values will be allowed.
See
Example
JetTable.MapMember
Syntax
JetTable.MapMember MemberName$, FieldName$

Creates a member property named by MemberName$ which represents the field given by FieldName$.
All fields which have only letters (no spaces) for names are already member properties of the Table object. For those fields which have spaces in their names, you can use this function to map those fields to non-spaced names.
See
Example
JetTable.CreateStructFields
Syntax
JetTable.CreateStructFields StructName

Creates a series of new fields in the table (not query). Every field in the structure definition given by StructName is duplicated in the table, if possible. Field names, types and sizes are duplicated, wherever possible. Existing field names are skipped. Use this method when you want to generate a new table definition quickly.
See
Example
JetTable.SetRecordFieldValues
Syntax
JetTable.SetRecordFieldValues RecordObject

Changes the values of a series of fields by copying member variable values from the Record object. Any member variable in RecordObject whose name matches a field in the table is copied into the field. Use this function when you are editing a table or query record and want to update the field values quickly.
See
Example
GetRecordFieldValues
JetTable.GetRecordFieldValues
Syntax
JetTable.GetRecordFieldValues RecordObject

Retrieves the values of a series of fields into the member variables of the Record object. Any field in the table or query whose name matches a member variable in RecordObject is copied into the Record object. Use this function when you are scrolling through a table or query and want to retrieve field values quickly.
See
Example
SetRecordFieldValues
JetTable.Add
Syntax
JetTable.Add 

Appends a new record to the end of the table or query and puts the Table object in edit mode.
See
Example
Update
Cancel
JetTable.Edit
Syntax
JetTable.Edit 

Puts the Table object in edit mode at the current table or query record.
See
Example
Update
Cancel
JetTable.Update
Syntax
JetTable.Update 

Takes the Table object out of edit mode, saving changes to the current table or query record.
See
Example
Add
Edit
JetTable.Cancel
Syntax
JetTable.Cancel 

Takes the Table object out of edit mode, but destroys any changes made to the current table or query record.
See
Example
Add
Edit
JetTable.Delete
Syntax
JetTable.Delete 

Deletes the current record. If successful, you must scroll to another record.
See
Example
JetTable.MoveFirst
Syntax
JetTable.MoveFirst 

Makes the first record in the table or query the current record.
See
Example
JetTable.MoveLast
Syntax
JetTable.MoveLast 

Makes the last record in the table or query the current record.
See
Example
JetTable.MoveNext
Syntax
JetTable.MoveNext 

Scrolls to the next record, making it the current record.
See
Example
JetTable.MovePrev
Syntax
JetTable.MovePrev 

Scrolls back to the previous record, making it the current record.
See
Example
JetTable.Find
Number Field Syntax
# = JetTable.Find([FieldName$, Number#])

String Field Syntax
# = JetTable.Find([FieldName$, Pattern$])

Searches the entire table or query, matching the field named by FieldName$ against the value provided. For jftText@ and jftMemo@ fields, Pattern$ specifies a wildcard pattern (including '*' and '?'). For all other fields, the value of Number# is used.
The first time you call Find, specify FieldName$ and either Pattern$ or Number# to search for the first record that matches in the table or query. Subsequent calls to Find should have no parameters, to continue the search from the last matching record.
See
Example
JetTable.SetBookmark
Syntax
JetTable.SetBookmark Bookmark$

Marks the location of the current record, saving the location using the Bookmark$ name provided. There is no limit to the number of bookmarks you can set.
See
Example
GotoBookmark
JetTable.GotoBookmark
Syntax
JetTable.GotoBookmark Bookmark$

Scrolls directly to the previously set Bookmark$.
See
Example
GotoBookmark
JetTable.GetNumFieldValue
Syntax
# = JetTable.GetNumFieldValue(FieldName$)

Returns the value of the field named by FieldName$ for the current record.
Since fields whose names have no spaces are automatically available as member properties of the object, and since those that do have spaces in their names can be mapped using MapMember, this function is largely redundant.
See
Example
JetTable.SetNumFieldValue
Syntax
JetTable.SetNumFieldValue FieldName$, Value#

Sets the value of the field named by FieldName$ to Value#.
Since fields whose names have no spaces are automatically available as member properties of the object, and since those that do have spaces in their names can be mapped using MapMember, this function is largely redundant.
See
Example
JetTable.GetStringFieldValue
Syntax
$ = JetTable.GetStringFieldValue(FieldName$)

Returns the value of the field named by FieldName$ for the current record.
Since fields whose names have no spaces are automatically available as member properties of the object, and since those that do have spaces in their names can be mapped using MapMember, this function is largely redundant.
See
Example
JetTable.SetStringFieldValue
Syntax
JetTable.SetStringFieldValue FieldName$, Value$

Sets the value of the field named by FieldName$ to Value$.
Since fields whose names have no spaces are automatically available as member properties of the object, and since those that do have spaces in their names can be mapped using MapMember, this function is largely redundant.
See
Example
MailSlot
Syntax
New MailSlot MailPath$, Mode

MailSlot is a dynamic object which provides system/network mailslot messaging. You must create an object of type MailSlot using New, passing the mailslot name to the constructor. A second parameter determines whether the object will be creating or opening a mailslot. If Mode is CREATE, the object may only read from the mailslot. If Mode is OPEN, the object may only write to it.
The name of the mailslot must include the computer name where the mailslot resides. An object which creates (owns) a mailslot must specify the local computer (\\.\); opening objects may use any computer name. A mailslot name takes the form: \\.\mailslot\[path]name
Where "." represents the computer name. All mailslot names must be preceded with the \mailslot path. Additional paths may be specified; they will be created as necessary.
Example:
New Slot As MailSlot "\\.\mailslot\Fred", OPEN
Slot.WriteString "See you on monday!"
See
WriteString
ReadString
WriteBuffer
ReadBuffer
WaitFor
WaitForMany
Flush
MailSlot.WriteString
Syntax
MailSlot.WriteString Text$

Writes Text$ to the MailSlot object.
Example:
MailSlot.WriteString "ATDT123-4567" + 13
MailSlot.ReadString
Syntax
$ = MailSlot.ReadString(WaitSeconds#)

Reads all characters up to, but not including, the next return character (ASCII 13). Any linefeed characters encountered are discarded. If WaitSeconds# has passed before a return character is found, the function returns an empty string.
Example:
Line$ = MailSlot.ReadString(2)
MsgBox(Line$)
MailSlot.WriteBuffer
Syntax
# = MailSlot.WriteBuffer(Buffer#, Size#)

Writes Size# number of bytes from the memory address given by Buffer# to the MailSlot object. Returns the number of bytes actually written.
See Also
Heap
Example:
Wrote# = MailSlot.WriteBuffer(P#, 1024)
MailSlot.ReadBuffer
Syntax
# = MailSlot.ReadBuffer(Buffer#, Size#)

Reads up to Size# number of bytes from the MailSlot object and writes them to the memory address given by Buffer#. Returns the number of bytes actually read.
See Also
Heap
Example:
Read# = MailSlot.ReadBuffer(P#, 1024)
MailSlot.WaitFor
Syntax
# = MailSlot.WaitFor(TestString$, WaitSeconds#)

Scans characters coming into the port buffer and returns TRUE (1) if the string is found before WaitSeconds# passes, otherwise returns FALSE (0).
Example:
Found# = MailSlot.WaitFor("Hello", 20)
MailSlot.WaitForMany
Syntax
# = MailSlot.WaitFor(WaitSeconds# [, TestStrings$, ... ] )

Scans characters coming into the port buffer and waits for one of an unlimited number of TestStrings$ values. If one of the TestStrings$ values is found before WaitSeconds# elapses, the index of the value is returned, otherwise 0 is returned. The first TestString$ value returns 1, the second returns 2 and so on.
Example:
Found# = MailSlot.WaitForMany(45, "Hello", "Bye")
MailSlot.Flush
Syntax
MailSlot.Flush

Empties incoming mailslot buffer.
Example:
MailSlot.Flush
Mutex
Syntax
New Mutex Name$

Creates a named mutex which can be used to create locks in memory to preserve resources. A mutex is often used when one or more scripts might access a common resource, such as a file. If both scripts create a mutex using the same name and attempt to lock the mutex, only one script will continue and can safely use the resource. The other script will pause until either the mutex is unlocked or a time-out occurs. Once the other script gains access to the resource, it can safely use it until it unlocks the mutex.
Example:
new ConfigLock as Mutex "CONFIG.SYS"
Methods
Lock
Unlock
Mutex.Lock
Syntax
Mutex.Lock Timeout#

Attempts to lock the mutex. If the mutex is available, the lock occurs and processing continues immediately. If it is not, processing pauses until the mutex is unlocked by another process which has locked it. If Timeout seconds has passed before the mutex becomes available, an exception is thrown.
Example:
new ConfigLock as Mutex "CONFIG.SYS"
ConfigLock.Lock 15
Mutex.Unlock
Syntax
Mutex.Unlock

Unlocks a mutex locked by the same script.
Example:
new ConfigLock as Mutex "CONFIG.SYS"
ConfigLock.Lock 15
' perform tasks here
ConfigLock.Unlock
OLEObject
OLEObjects are dynamic and must be created using the New statement. Use OLEObject to connect to OLE-automation enabled servers. Methods and properties exposed by the OLE object server become methods and objects of the OLEObject object.
Most pointer and number types are converted to/from the CodeCurve number type. The exception is OLE's BSTR type; they are converted to strings, unless BSTR is a BYREF type and a return value, in which case the type reverts to an CodeCurve number.
BYREF types that are method parameters are passed in CodeCurve as variable references; that is, you do not pass an expression, but a variable of a compatible type. The variable passed must have no $ or # appended; just the name is passed. Upon return, the variable will contain a new value, if the OLE object method changed it.
Any named OLE object property of type IDispatch which is exposed by the object can be accessed using nested object names. For example, if an OLEObject named Access is connected to an "Access.Application" server, the IDispatch property "Forms" can be accessed using the syntax: Access.Forms. One property of Forms is Count#, so it is accessed: Access.Forms.Count#. Forms is also an object collection, so you can use standard CodeCurve object collection syntax to access individual forms of the Access object; for example: Access.Forms{0}.Caption$ returns the caption of the first form showing in Access. See Objects for more information on nested objects and object collections.
CodeCurve is not responsible for providing documentation on OLE object methods and properties. The OLEObject object is functional, but primitive and, at this time, type information for all exposed members cannot be guaranteed.
Connection Syntax
new Object as OLEObject ID$, Context# [ , LoadCMD# ]

Attach Syntax
new Object as OLEObject IDispatch#

ID$ can be either the ProgID or CLSID of the OLE object. Context# specifies the object's context. LoadCMD# specifies how to load the object (default is objLoadServer@).
If the Attach Syntax is used, IDispatch# specifies the address of an IDispatch object. IDispatch might come from an OLE object property, method or it might come from somewhere else. No matter how you receive the IDispatch pointer, you can pass it to OLEObject and have a working OLE object in CodeCurve.
Context# can be either of these values (Connection Syntax):
ctxInProcServer@
used for DLL and OCX style objects

ctxLocalServer@
used for EXE style objects

LoadCMD# can be either of these values (Connection Syntax):
objLoadServer@
loads a new instance of the server before connecting

objBindServer@
binds to an already-loaded server

Example
'  This example assumes Access is
'  installed and there is a database named
'  Acme.mdb.  Notice that the entire
'  object interface is provided by Access.
'  This code will use OLE automation to
'  tell MS Access to open a database,
'  then open a form named "Customers"
'
' create the Access object and connect it to already open
' instance of MS Access97, if possible.  on exception,
' tell OLEObject to load the server
try
  new Access as OLEObject "Access.Application.7", ctxLocalServer@, objBindServer@
catch
  new Access as OLEObject "Access.Application.7", ctxLocalServer@, objLoadServer@
endtry

'  open the database, ignoring any errors
allow Access.OpenCurrentDatabase "C:\DB\Acme.mdb"

'  open the form named "Customers"
Access.DoCmd.OpenForm "Customers"
Port
Syntax
New Object$ As Port COMPort$

Port is a dynamic object which provides simple serial port I/O. You must create an object of type Port using New, passing the COM port name to the constructor.
Example:
New Modem As Port "COM2"
Properties
Handle
Port
BreakChars
IgnoreChars
BreakOnNull
Methods
SetState
WriteString
ReadString
WriteBuffer
ReadBuffer
WaitFor
WaitForMany
Flush
Port.Handle
Type
Port.Handle#

(read-only)
Returns the underlying port handle for the object.
Port.Port
Type
Port.Port$

(read-only)
Returns the port to which the Port object is connected.
Port.BreakChars
Type
Port.BreakChars$

Gets or sets the string used to determine when ReadString should terminate. BreakChars$ is ASCII 13 (return) by default. If ReadString reads a character which appears in this string, reading is terminated.
See
ReadString
Port.IgnoreChars
Type
Port.IgnoreChars$

Gets or sets the string used to determine which characters ReadString should discard. IgnoreChars$ is ASCII 10 (newline) by default. If ReadString reads a character which appears in this string, the character is discarded and reading continues.
See
ReadString
Port.BreakOnNull
Type
Port.BreakOnNull#

Gets or sets the value which determines whether ReadString should discard NULL characters read, or break reading on them. By default, BreakOnNull# is FALSE. If BreakOnNull# is TRUE, reading terminates when ReadString reads a NULL character. If FALSE, ReadString simply discards NULL characters and continues reading.
See
ReadString
Port.SetState
Syntax
Port.SetState Baud#, Parity, Bits#, StopBits#

Configures the serial port to which the Port object is connected. Parity can be any single character: N=no parity, O=odd, E=even, M=mark, S=space.
Example:
Modem.SetState 19200, N, 8, 1
Port.WriteString
Syntax
Port.WriteString Text$

Writes Text$ to the Port object.
Example:
Port.WriteString "ATDT123-4567" + 13
Port.ReadString
Syntax
$ = Port.ReadString(WaitSeconds#)

Reads all characters until one which matches a character in the BreakChars$ (ASCII 13 (return) by default) property is encountered. Any characters read which match any character in the IgnoreChars$ (ASCII 10 (newline) by default) property are discarded. If the property BreakOnNull# is TRUE (FALSE by default), reading also terminates if a NULL character is read, otherwise NULL characters are discarded.
If WaitSeconds# has passed before a proper string termination occurs, all characters read up to that point are returned.
See
BreakChars
IgnoreChars
BreakOnNull
Example
Line$ = Port.ReadString(2)
MsgBox(Line$)
Port.WriteBuffer
Syntax
# = Port.WriteBuffer(Buffer#, Size#)

Writes Size# number of bytes from the memory address given by Buffer# to the Port object. Returns the number of bytes actually written.
See Also
Heap
Example:
Wrote# = Port.WriteBuffer(P#, 1024)
Port.ReadBuffer
Syntax
# = Port.ReadBuffer(Buffer#, Size#)

Reads up to Size# number of bytes from the Port object and writes them to the memory address given by Buffer#. Returns the number of bytes actually read.
See Also
Heap
Example:
Read# = Port.ReadBuffer(P#, 1024)
Port.WaitFor
Syntax
# = Port.WaitFor(TestString$, WaitSeconds#)

Scans characters coming into the port buffer and returns TRUE (1) if the string is found before WaitSeconds# passes, otherwise returns FALSE (0).
Example:
'  simple test to detect modem presence
Port.WriteString("AT")
Found# = Port.WaitFor("OK", 2)
Port.WaitForMany
Syntax
# = Port.WaitFor(WaitSeconds# [, TestStrings$, ... ] )

Scans characters coming into the port buffer and waits for one of an unlimited number of TestStrings$ values. If one of the TestStrings$ values is found before WaitSeconds# elapses, the index of the value is returned, otherwise 0 is returned. The first TestString$ value returns 1, the second returns 2 and so on.
Example:
'  dial and wait for a number
'  of possible modem messages
Port.WriteString("ATDT123-4567")
Found# = Port.WaitForMany(45, "CONNECT", "BUSY", "NO DIALTONE", "ERROR")
Port.Flush
Syntax
Port.Flush

Empties incoming serial port buffer.
Example:
Modem.Flush
Printer
Syntax
New Printer

Printer is both a dynamic and static object which provides printing functionality through any available Windows printers. The static object is connected to the printer assigned as the default Windows printer.
Properties
Name
Handle
Orientation
PaperSize
PaperBin
Copies
Units
CellHeight and CellWidth
PaperHeight and PaperWidth
X and Y
Methods
WriteString
WriteStringLine
WriteStringRect
SetFont
DrawLine
BreakPage
BreakDoc
ShowSetupDialog
ShowPrintDialog
See Also
Example of using the Printer object
Printer.Name
Syntax
Printer.Name$

Gets or sets the printer name associated with the printer object. If used to set the printer name, all printing will be done with the new printer specified.
Note: Do not attempt to change the printer name while printing. Make the change prior to calling any print commands such as WriteStringLine or DrawLine.
See
Example of using the Printer object
Printer.Handle
Syntax
Printer.Handle#

(read-only)
Returns the Windows GDI device context handle associated with the printer.
Printer.Orientation
Syntax
Printer.Orientation#

Gets or sets the orientation of the paper used to print upon.
Orientation may be any one of the following values:
poPortrait@
poLandscape@
See
Example of using the Printer object
Printer.PaperSize
Syntax
Printer.PaperSize#

Gets or sets the size (type) of the paper used to print upon.
Note: Do not attempt to change the paper size while printing. Make the change prior to calling any print commands such as WriteStringLine or DrawLine.
PaperSize may be any one of the following values:
psLetter@
Letter, 8 1/2- x 11-inches

psLegal@
Legal, 8 1/2- x 14-inches

psA4@
A4 Sheet, 210- by 297-millimeters

psCSHeet@
C Sheet, 17- by 22-inches

psDSheet@
D Sheet, 22- by 34-inches

psESheet@
E Sheet, 34- by 44-inches

psLetterSmall@
Letter Small, 8 1/2- by 11-inches

psTabloid@
Tabloid, 11- by 17-inches

psLedger@
Ledger, 17- by 11-inches

psStatement@
Statement, 5 1/2- by 8 1/2-inches

psExecutive@
Executive, 7 1/4- by 10 1/2-inches

psA3@
A3 sheet, 297- by 420-millimeters

psA4Small@
A4 small sheet, 210- by 297-millimeters

psA5@
A5 sheet, 148- by 210-millimeters

psB4@
B4 sheet, 250- by 354-millimeters

psB5@
B5 sheet, 182- by 257-millimeter paper

psFolio@
Folio, 8 1/2- by 13-inch paper

psQuarto@
Quarto, 215- by 275-millimeter paper

ps10x14@
10- by 14-inch sheet

ps11x17@
11- by 17-inch sheet

psNote@
Note, 8 1/2- by 11-inches

psEnv9@
#9 Envelope, 3 7/8- by 8 7/8-inches

psEnv10@
#10 Envelope, 4 1/8- by 9 1/2-inches

psEnv11@
#11 Envelope, 4 1/2- by 10 3/8-inches

psEnv12@
#12 Envelope, 4 3/4- by 11-inches

sEnv14@
#14 Envelope, 5- by 11 1/2-inches

psEnvDL@
DL Envelope, 110- by 220-millimeters

psEnvC5@
C5 Envelope, 162- by 229-millimeters

psEnvC3@
C3 Envelope, 324- by 458-millimeters

psEnvC4@
C4 Envelope, 229- by 324-millimeters

psEnvC6@
C6 Envelope, 114- by 162-millimeters

psEnvC65@
C65 Envelope, 114- by 229-millimeters

psEnvB4@
B4 Envelope, 250- by 353-millimeters

psEnvB5@
B5 Envelope, 176- by 250-millimeters

psEnvB6@
B6 Envelope, 176- by 125-millimeters

psEnvItaly@
Italy Envelope, 110- by 230-millimeters

psEnvMonarch@
Monarch Envelope, 3 7/8- by 7 1/2-inches

psEnvPersonal@
6 3/4 Envelope, 3 5/8- by 6 1/2-inches

psFanfoldUS@
US Std Fanfold, 14 7/8- by 11-inches

psFanfoldStdGerman@
German Std Fanfold, 8 1/2- by 12-inches

psFanfoldLglGerman@
German Legal Fanfold, 8 1/2- by 13-inches

See
Example of using the Printer object
Printer.PaperBin
Syntax
Printer.PaperBin#

Gets or sets the paper storage bin used to draw the paper into the printer.
Note: Do not attempt to change the paper bin while printing. Make the change prior to calling any print commands such as WriteStringLine or DrawLine.
PaperBin may be any one of the following values:
pbAuto@
pbLower@
pbCassette@
pbManual@
pbEnvelope@
pbMiddle@
pbEnvManual@
pbOnlyOne@
pbFirst@
pbSmallFmt@
pbLargeCapacity@
pbTractor@
pbLargeFmt@
pbUpper@
pbLast@
See
Example of using the Printer object
Printer.Copies
Syntax
Printer.Copies#

Gets or sets the number of copies the printer should print. Not all printers support this feature.
Note: Do not attempt to change the number of copies while printing. Make the change prior to calling any print commands such as WriteStringLine or DrawLine.
See
Example of using the Printer object
Printer.Units
Syntax
Printer.Units#

Gets or sets the units of measurement used when reporting or specifying the printer cursor location. By default, Units is set to mmText@.
Units may be any one of the following values:
mmText@
1 unit equals 1 device pixel

mmTwips@
1440 units equals 1 inch (1/20 of a font point)

mmEnglish@
1 unit equals 1 inch, accurate to 1/1000 of an inch

mmMetric@
1 unit equals 1 millimeter, accurate to 1/10 of an inch

See
Example of using the Printer object
Printer.CellHeight and CellWidth
Syntax
Printer.CellHeight#

Printer.CellWidth#

(read-only)
Returns the cell dimensions (height and width, respectively) of a single character cell expressed in the current units of measurement.
See
Units
Example of using the Printer object
Printer.PaperHeight and PaperWidth
Syntax
Printer.PaperHeight#

Printer.PaperWidth#

(read-only)
Returns the dimensions (height and width, respectively) of current paper size expressed in the current units of measurement. The paper size is the size of the entire page, including any unprintable areas.
See
PaperSize
Units
Example of using the Printer object
Printer.X and Y
Syntax
Printer.X#

Printer.Y#

Gets or sets the current printer cursor position expressed in the current units of measurement.
See
Units
Example of using the Printer object
Printer.WriteString
Syntax
Printer.WriteString Text$

Writes Text$ as if the printer were a line printer. Carriage-return (ASCII 13), linefeed (ASCII 10) and tab (ASCII 9) characters are interpreted to reposition the print cursor. Page break characters (ASCII 12) are interpreted to start a new printing page. After printing, the current printer cursor position is updated.
This method is provided partially for backwards-compatibility with the older Printer object which connected only to line printers, but also for ease-of-use to those who are more familiar with simple line printers.
See
Example of using the Printer object
Printer.WriteStringLine
Syntax
Printer.WriteStringLine Text$ [ , XPos#, YPos#]

Writes Text$ to the printer. If optional parameters XPos and YPos are given, the text is printed at that position, otherwise printing occurs at the current printer cursor position. XPos and YPos are expressed in the current units of measurement. After printing, the current printer cursor position is updated.
See
Units
Example of using the Printer object
Printer.WriteStringRect
Syntax
Printer.WriteStringRect Text$, XPos#, YPos#, Width#, Height#, Alignment#

Writes Text$ to the printer within the rectangle area given by XPos, YPos, Width and Height. Alignment determines how the text is aligned within the rectangle area. XPos, YPos, Width and Height are expressed in the current units of measurement. Unlike most other text printing commands, the current printer cursor position is not updated by this method.
Alignment may be any one of the following values:
taLeft@
taCenter@
taRight@
See
Units
Example of using the Printer object
Printer.SetFont
Syntax
Printer.SetFont FontName$, PointSize#, Attributes#

Changes the font used when printing. FontName$ is any available Windows font, such as Arial or Times New Roman, etc. PointSize# is the size of the font in points. Attributes control additional formatting the font should use (default is faNormal@).
faNormal@
Font uses no special formatting

faBold@
Font appears bold

faItalic@
Font appears italicized

faUnderline@
Font appears underlined

faStrikeOut@
Font appears with a line through it, as though struck-out

See
Example of using the Printer object
Printer.DrawLine
Syntax
Printer.DrawLine XOffset#, YOffset#

Draws a thin, straight line from the current printer cursor position to the offsets. XOffset and YOffset are not absolute position values; they are relative to the current printer cursor position. XOffset and YOffset are expressed in the current units of measurement.
See
Units
Example of using the Printer object
Printer.BreakPage
Syntax
Printer.BreakPage

Stops printing on the current page and begins printing on a new one. The previous page is fed to the printer and all subsequent print commands will occur on the new page.
See
Example of using the Printer object
Printer.BreakDoc
Syntax
Printer.BreakDoc

Stops all printing and feeds the last page to the printer. All subsequent print commands will occur as a new print job. This method may also be used to release the current printer.
See
Example of using the Printer object
Printer.ShowSetupDialog
Syntax
Printer.ShowSetupDialog

Displays a print setup dialog for the printer associated with the object. If the user cancels the dialog an exception is thrown, otherwise the new settings will take effect.
Note: Do not attempt to show this dialog while printing. Show it prior to calling any print commands such as WriteStringLine or DrawLine.
See
ShowPrintDialog
Example of using the Printer object
Printer.ShowPrintDialog
Syntax
Printer.ShowPrintDialog

Displays a standard print dialog for the printer associated with the object. If the user cancels the dialog an exception is thrown, otherwise the new settings will take effect.
Note: Do not attempt to show this dialog while printing. Show it prior to calling any print commands such as WriteStringLine or DrawLine.
See
ShowSetupDialog
Example of using the Printer object
Example of using the Printer object
This example shows how to create a new printer object, set properties and print using various print commands.
new Prn as Printer  ' create new printer object

Prn.Orientation# = poLandscape@ ' initialize properties
Prn.PaperSize# = psLetter@
Prn.PaperBin# = pbLower@
Prn.Copies# = 1

allow Prn.ShowSetupDialog ' prompt the user with setup dialogs
Prn.ShowPrintDialog

MsgBox("This example will print on printer: " + 34 + Prn.Name$ + 34)

Prn.Units# = mmEnglish@ ' measure in inches

'   print like a line-printer
Prn.WriteString "This is printed as simple line text" + 13 + 10
Prn.WriteString "Column 1" + 9 + 9 + "Column 2" + 9 + 9 + "Column 3"

Prn.WriteStringLine "This is exactly 2 ", 2, 2  ' print positioned
Prn.WriteStringLine "inches down and right"     ' and non-positioned

Prn.SetFont "Arial", 10, faBold@  ' use a specific font

CenterY# = Prn.PaperHeight# / 2

' print text in the middle of the page
Prn.WriteStringRect "Center of page 1", 2, CenterY# - (Prn.CellHeight# / 2),
  Prn.PaperWidth# - 4, Prn.CellHeight#, taCenter@

Prn.X# = 2  ' draw a rectangle around it
Prn.Y# = CenterY# - (Prn.CellHeight# / 2)
Prn.DrawLine Prn.PaperWidth# - 4, 0
Prn.DrawLine 0, Prn.CellHeight#
Prn.DrawLine -(Prn.PaperWidth# - 4), 0
Prn.DrawLine 0, -Prn.CellHeight#

Prn.BreakPage ' feed paper to new page

' print more text in the middle of the page
Prn.WriteStringRect "Center of page 2", 2, CenterY# - (Prn.CellHeight# / 2),
  Prn.PaperWidth# - 4, Prn.CellHeight#, taCenter@

Prn.X# = 2  ' draw another rectangle
Prn.Y# = CenterY# - (Prn.CellHeight# / 2)
Prn.DrawLine Prn.PaperWidth# - 4, 0
Prn.DrawLine 0, Prn.CellHeight#
Prn.DrawLine -(Prn.PaperWidth# - 4), 0
Prn.DrawLine 0, -Prn.CellHeight#

Prn.BreakDoc  ' end the print job
Record
The Record object is used to manipulate a single block of memory which can be used by other CodeCurve functions and objects, or passed to the Windows API. It is very similar to manipulating a block of memory allocated by the Heap object, but is much simpler and more powerful.
Using The Record Object
Record Example
Constructor
Record [StructName]
Properties
Address
Size
Methods
Assign
Alloc
Copy
MapMember
CopyToClipboard
PasteFromClipboard
AddressOf
OffsetOf
SizeOf
Record Example
Example
' defined a structure
struct PersonStruct
  ID[stLong@]
  Name[stString@, 32]
endstruct

' create a record based on PersonStruct
new Person as Record PersonStruct

' create a 1-character string member variable
Person.MapMember "Initial", stString@, 2, Person.OffsetOf("Name")

' set mapped member variable values
Person.ID# = 1
Person.Name$ = "John Doe"

' display person's initial
MsgBox("Initial: " + Person.Initial$)

' create new clipboard format
CF# = Clipboard.RegisterFormat("PersonStruct")

' copy person record to clipboard
Person.CopyToClipboard CF#

' paste person record into new person record
new PersonCopy as Record PersonStruct
PersonCopy.PasteFromClipboard CF#

' prove paste worked
MsgBox("Name: " + PersonCopy.Name$)

' display person record address/size
AddressSize$ = Str(Person.Address#) + "/" + Str(Person.Size#)
MsgBox("Person Address/Size: " + AddressSize$)

' display name member variable address/size
AddressSize$ = Str(Person.AddressOf("Name")) + "/" + Str(Person.SizeOf("Name"))
MsgBox("Name Field Address/Size: " + AddressSize$)
Using The Record Object
Typically, to use the Record object, you do one of two things:
1) Define a struct and create a new Record object passing the struct name to the constructor.
2) Create a new Record and call Alloc to allocate a memory buffer, then use MapMember to define member variables.
The easiest, and the most versatile way is to use the struct method. See the documentation on Structures for information on how to define a struct type.
Once you have created an object of type Record, and have mapped member variables available, you can set and retrieve member variable values as real members of the Record object. For example, if a Record object named "Person" has a string member variable named "Name", you can access the variable like so:
Person.Name$ = "John Doe"
MsgBox(Person.Name$)
A really useful way to use the Record object is to pass the object's Address# member property to Windows API functions (imported using the DLL object) which expect a pointer to a structure. Not only will the API function receive the structure values, since it's a memory address value, if the function modifies any structure fields, you will instantly have all of the new values. This is a much easier way to pass structure pointers to the API than using memory allocated by the Heap object.
The Record object also works directly with the JetTable object, making editing and retrieving database record values much simpler.
Record.Address
Syntax
Record.Address#

(read-only)
Returns the memory buffer address used by the Record object.
See
Example
Record.Size
Syntax
Record.Size#

(read-only)
Returns the size of the memory buffer used by the Record object.
See
Example
Record.Assign
Syntax
Record.Assign Buffer#, Size#

Tells the Record object to manipulate an external memory buffer, rather than its own internally allocated buffer. Buffer# is the memory address, and Size# is the byte size of the buffer. The Record object will not free the external memory buffer as it would normally do.
If an internal memory buffer already exists for the object, it will be freed.
Any member variables already mapped into the record object which extend beyond the new size limit will be removed and will not be available to the object.
See
Example
Record.Alloc
Syntax
Record.Alloc Size#

Allocates an internal memory buffer to be used by the Record object. Size# is the size of the new memory buffer.
If an internal memory buffer already exists for the object, it will be freed.
Any member variables already mapped into the record object which extend beyond the new size limit will be removed and will not be available to the object.
See
Example
Record.Copy
Syntax
Record.Copy SrcBuffer#, SrcSize#

Copies an external memory buffer into the Record object's own internal buffer. SrcBuffer# is the memory address of the external memory buffer and SrcSize# is the size of the buffer.
See
Example
Record.MapMember
Number Syntax
Record.MapMember MemberName$, Type# [, Start#]

String or Void Syntax
Record.MapMember MemberName$, Type#, Length# [, Start#]

Creates a new member variable which will use a sectional area of the Record object's memory buffer. MemberName$ is the name of the new member variable. Type# is the type of variable to create. Length# is used for string and void types only, and specifies the size of the buffer area to use. Start#, if provided, specifies where in the buffer the variable is located. If Start# is not provided, the variable will be located after the last variable created using the MapMember method.
If you create the Record object with a struct name parameter, all named fields of the struct will be pre-mapped as members of the Record object, although you can still use MapMember to add new member variables.
When creating a field of type stString@, remember that the last byte of the buffer field will be used for a NULL-character. Thus, if you need to be able to store a 32-character string, you should specify the field size as 33.
See Structure Types for a list of the constants used to specify the member Type#.
See
Example
Record.CopyToClipboard
Syntax
Record.CopyToClipboard Format#

Copies the Record object's memory buffer to the clipboard. Format# is the registered clipboard format to specify when copying. See the Clipboard object for more information about the available formats.
See
Example
Record.PasteFromClipboard
Syntax
Record.PasteFromClipboard Format#

Copies data from the clipboard into the Record object's memory buffer. Format# is the registered clipboard format to specify when pasting. See the Clipboard object for more information about the available formats.
See
Example
Record.AddressOf
Syntax
# = Record.AddressOf(MemberName$)

Returns the memory address of the member variable specified by MemberName$. The memory address returned will be somewhere inside the Record object's memory buffer.
See
Example
Record.OffsetOf
Syntax
# = Record.OffsetOf(MemberName$)

Returns the offset, in bytes, where the member variable starts from the Record object's memory buffer address. The first member variable's offset is usually 0.
See
Example
Record.SizeOf
Syntax
# = Record.SizeOf(MemberName$)

Returns the amount of memory used by the member variable specified by MemberName$.
See
Example
Registry
Dynamic-Version Syntax
New Registry Key$

The Registry object is both a dynamic and static object which provides access to Windows' extended registry. The dynamic version allows you to create a registry object that operates only at a certain level in the registry hierarchy, eliminating the need to specify the full key name with each operation.
Key$ parameters must include the name of a base key in the registry. The possible values are:
Root
Same as HKEY_CLASSES_ROOT

Current
Same as HKEY_CURRENT_USER

Local
Same as HKEY_LOCAL_MACHINE

Users
Same as HKEY_USERS

Static Version Example:
'  this does the same thing the
'  dynamic-version example does
Registry.WriteString("Current\Software\Celtech Software\Scripts", "MySubKey", "This is a sub key!")
Dynamic Version Example:
'  this does the same thing the
'  static-version example does
New AppReg As Registry "Current\Software\Celtech Software\Scripts"
AppReg.WriteString("MySubKey", "This is a sub key!")
Properties
KeyName
Methods
Find
WriteString
ReadString
WriteNum
ReadNum
WriteBuffer
ReadBuffer
ReadSections
ReadValues
ReadSectionNames
ReadValueNames
DeleteSection
DeleteValue
Registry.KeyName
Dynamic-Version Type
Registry.KeyName$

Gets or sets the base key used when performing read/write operations. This property only works with dynamically-created Registry objects.
Example changing registry key name
MyReg.KeyName$ = "Current\Software\My Company\My Script"
Example getting registry key name
Key$ = MyReg.KeyName$
Registry.Find
Syntax
# = Registry.Find([Filter$ [, CaseSensitive#]])

Searches the entire registry for any string which matches Filter. Filter may contain wildcard characters such as '*' and '?'. If CaseSensitive is provided and is TRUE, the text must also match upper and lower case characters as well.
If Filter is provided, the search starts at the beginning of the registry. When a match is found, you may call Find again without Filter and the search will start just where the last match was found.
When a match is found, Find returns TRUE and the found key name is stored in the object property FoundKey. If a match was found in a key's value list, the name of the value is returned in FoundValue as well. Find returns FALSE when there are no more matches found.
Display the Status object to allow the user to cancel the search and to display progress information. If the user cancels the operation, Find returns FALSE and Status.Cancelled is set to TRUE.
Example
' initially "dumb" Registry object
New Reg As Registry ""

' show status dialog
Status.Show

' begin search and loop
Found# = Reg.Find("*obasic*", False)
While Found# = True ' something was found
  ' open the key found
  Reg.KeyName$ = Reg.FoundKey$

  ' create a user-friendly key/value ID
  KeyPath$ = Reg.FoundKey$ + "." + Reg.FoundName$

  ' read the value at the key/value found
  KeyValue$ = Reg.ReadString(Reg.FoundName$)

  ' display key/value ID and value found there
  MsgBox(KeyPath$ + "=" + KeyValue$)

  ' continue search
  Found# = Reg.Find()
EndWhile

Registry.WriteString
Static-Version Syntax
Registry.WriteString Key$, Name$, Value$ [, AsBinary#]

Dynamic-Version Syntax
Registry.WriteString Name$, Value$ [, AsBinary#]

Writes Value$ to the Name$ entry in the registry. If Name$ does not exist, it will be created. The dynamic version of the registry object must not specify the Key$ parameter. Name$ allows you to specify the named sub-key of Key$ (extended registry feature). If Name$ is an empty string, this function will write to Key$ old-registry style.
If AsBinary# is TRUE (not 0), the string will be written as a binary, rather than a string type.
Example:
Registry.WriteString "Root\.txt", "", "MyTextEditorFile"
Registry.ReadString
Static-Version Syntax
$ = Registry.ReadString(Key$, Name$ [, DefaultValue$])

Dynamic-Version Syntax
$ = Registry.ReadString(Name$ [, DefaultValue$])

Returns the value of Name$ in the registry. Name$ specifies the named sub-key of Key$. The dynamic version of the registry object must not specify the Key$ parameter. If Name$ is an empty string, the default sub-key (old-registry style) value is returned. If the key is not found or other error occurs, DefaultValue$ is returned.
Example:
TxtAssoc$ = Registry.ReadString("Root\.txt", "")
Registry.WriteNum
Static-Version Syntax
Registry.WriteNum Key$, Name$, Value# [, AsBinary#]

Dynamic-Version Syntax
Registry.WriteNum Name$, Value# [, AsBinary#]

Writes Value# to the Name$ entry in the registry. If Name$ does not exist, it will be created. The dynamic version of the registry object must not specify the Key$ parameter. Name$ allows you to specify the named sub-key of Key$ (extended registry feature). If Name$ is an empty string, this function will write to Key$ old-registry style.
If AsBinary# is TRUE (not 0), the number will be written as a binary, rather than a double-word type.
Example:
Registry.WriteNum "Current\Software\MyCo\MyApp", "Counter", 1
Registry.ReadNum
Static-Version Syntax
# = Registry.ReadNum(Key$, Name$ [, DefaultValue#])

Dynamic-Version Syntax
# = Registry.ReadNum(Name$ [, DefaultValue#])

Returns the value of Name$ in the registry. Name$ specifies the named sub-key of Key$. The dynamic version of the registry object must not specify the Key$ parameter. If Name$ is an empty string, the default sub-key (old-registry style) value is returned. If the name is not found or other error occurs, DefaultValue# is returned.
Example:
Count# = Registry.ReadNum("Current\Software\MyCo\MyApp", "Counter")
Registry.WriteBuffer
Static-Version Syntax
Registry.WriteBuffer Key$, Name$, Buffer#, Size#

Dynamic-Version Syntax
Registry.WriteBuffer Name$, Buffer#, Size#

Writes Size# number of bytes from the memory address given by Buffer# to Name$ entry in the registry as a binary. If Name$ does not exist, it will be created. The dynamic version of the registry object must not specify the Key$ parameter. Name$ allows you to specify the named sub-key of Key$ (extended registry feature). If Name$ is an empty string, this function will write to Key$ old-registry style.
Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Registry.WriteBuffer "Current\Software\MyCo\MyApp", "Buffer", P#, 1024
Registry.ReadBuffer
Static-Version Syntax
# = Registry.ReadBuffer(Key$, Name$, Buffer#, Size#)

Dynamic-Version Syntax
# = Registry.ReadBuffer(Name$, Buffer#, Size#)

Reads Size# number of bytes from the Name$ entry in the registry as a binary to the memory address given by Buffer#. The dynamic version of the registry object must not specify the Key$ parameter. Returns the number of bytes actually read.
Buffer# should be the memory address of a buffer sufficiently large enough to hold the number of bytes being requested. Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Read# = Registry.ReadBuffer("Current\Software\MyCo\MyApp", "Buffer", P#, 1024)
Registry.ReadSections
Static-Version Syntax
# = Registry.ReadSections Key$, Array

Dynamic-Version Syntax
# = Registry.ReadSections Array

Creates a global string array named Array and fills it with the sub-keys, and their associated values, of the key given by Key$. Sub-keys and values appear in the array as "Key=Value", and is suitable for use with string array name indexing.
Example:
Registry.ReadSections "Current\Software\MyCo\MyApp", Sections
Registry.ReadValues
Static-Version Syntax
# = Registry.ReadValues Key$, Array

Dynamic-Version Syntax
# = Registry.ReadValues Array

Creates a global string array named Array and fills it with the values names, and their associated values, of the key given by Key$. Names and values appear in the array as "Key=Value", and is suitable for use with string array name indexing.
Example:
Registry.ReadValues "Current\Software\MyCo\MyApp", Values
Registry.ReadSectionNames
Static-Version Syntax
# = Registry.ReadSectionNames Key$, Array

Dynamic-Version Syntax
# = Registry.ReadSectionNames Array

Creates a global string array named Array and fills it with the sub-key names of the key given by Key$.
Example:
Registry.ReadSectionNames "Current\Software\MyCo\MyApp", SectionNames
Registry.ReadValueNames
Static-Version Syntax
# = Registry.ReadValueNames Key$, Array

Dynamic-Version Syntax
# = Registry.ReadValueNames Array

Creates a global string array named Array and fills it with the value names of the key given by Key$.
Example:
Registry.ReadSectionNames "Current\Software\MyCo\MyApp\Counter", ValueNames
Registry.DeleteSection
Static-Version Syntax
Registry.DeleteSection Key$, Section$

Dynamic-Version Syntax
# = Registry.DeleteSection Section$

Deletes the sub-key named given by Section$ from the registry. The sub-key is either a sub-key of the key attached to the dynamic object a sub-key of Key$. The sub-key must be empty.
Example:
Registry.DeleteSection "Current\Software\MyCo\MyApp", "Counter"
Registry.DeleteValue
Static-Version Syntax
Registry.DeleteValue Key$, Name$

Dynamic-Version Syntax
# = Registry.DeleteValue Name$

Deletes the value named by Name$ from Section$.
Example:
Registry.DeleteValue "Current\Software\MyCo\MyApp\Counter", "User1"
Status
Status is a static object used to display a status dialog. The dialog's caption, message and progress bar may all be modified to notify the user of the status of an operation.
Status displays a cancel button which allows the user to cancel some internal operations. Even if there are no internal routines running for the user to cancel, the Cancelled property of the Status object is set to TRUE, for use within the script.
Properties
Handle
Title
Message
Percent
Cancelled
Methods
Show
Hide
Status.Handle
Type
Status.Handle#

(read-only)
The window handle (HWND) of the status dialog object.
Example:
'  Windows API way of changing
'  the status dialog title
New DLL As Dll "USER32.DLL"
DLL.Declare "SetWindowTextA", "NU4, NU4, S"
DLL.SetWindowTextA(Status.Handle#, "New Title")
Status.Show
Status.Title
Type
Status.Title$

Gets or sets the caption of the status dialog.
Example:
'  CodeCurve way of changing the status dialog title
Status.Title$ = "New Title"
Status.Show
Status.Message
Type
Status.Message$

Gets or sets the message displayed in the status dialog. The message may be up to two lines long.
Example:
Status.Message$ = "Now processing:" + 13 + "  Third operation"
Status.Percent
Type
Status.Percent#

Gets or sets the percentage of the progress bar displayed. This value may be 0 through 100.
Example:
Status.Percent# = 50
Status.Cancelled
Type
Status.Cancelled#

Returns TRUE if the user clicked the Cancel button, otherwise FALSE. You can reset this value to FALSE at any time.
Example:
Status.Canceled# = False
if Status.Cancelled# = True then MsgBox("User cancelled operation!")
Status.Show
Syntax
Status.Show [ShowProgress#]

Displays the status dialog. Whenever the status dialog is shown, the progress bar is returned to 0, showing no progress. If ShowProgress is provided and is FALSE, the progress bar on the status dialog will be hidden, otherwise it will be shown.
Example:
Status.Show
Status.Hide
Syntax
Status.Hide

Hides the status dialog.
Example:
Status.Hide
Socket
Socket is a dynamic object that is itself a Winsock socket capable of communicating over a TCP/IP network such as the Internet. Communication is limited to passing text strings to and from a server. A dynamic socket, itself, can behave as either a client or server.
You must create an object of type Socket using New.
Example:
New Server As Socket
Properties
Handle
Port
Address
BreakChars
IgnoreChars
BreakOnNull
Connected
Buffered
Telnet
Methods
Connect
Listen
Close
Link
WriteString
ReadString
WriteBuffer
ReadBuffer
WaitFor
Socket.Handle
Type
Socket.Handle#

(read-only)
Returns the underlying SOCKET handle for the object.
Socket.Port
Type
Socket.Port#

(read-only)
Gets the port number the socket is currently connected through, client or server.
Example:
Port# = Server.Port#
Socket.BreakChars
Type
Socket.BreakChars$

Gets or sets the string used to determine when ReadString should terminate. BreakChars$ is ASCII 13 (return) by default. If ReadString reads a character which appears in this string, reading is terminated.
See
ReadString
Socket.IgnoreChars
Type
Socket.IgnoreChars$

Gets or sets the string used to determine which characters ReadString should discard. IgnoreChars$ is ASCII 10 (newline) by default. If ReadString reads a character which appears in this string, the character is discarded and reading continues.
See
ReadString
Socket.BreakOnNull
Type
Socket.BreakOnNull#

Gets or sets the value which determines whether ReadString should discard NULL characters read, or break reading on them. By default, BreakOnNull# is FALSE. If BreakOnNull# is TRUE, reading terminates when ReadString reads a NULL character. If FALSE, ReadString simply discards NULL characters and continues reading.
See
ReadString
Socket.Address
Syntax
Socket.Address$

(read-only)
Gets the IP address of a connected socket, client or server.
Example:
Addr$ = Client.Address$
Socket.Connected
Syntax
Socket.Connected#

(read-only)
Returns TRUE if the socket is connected.
Socket.Buffered
Syntax
Socket.Buffered#

Returns TRUE if the connected socket will save characters received for retrieval. If FALSE, all characters are discarded as they come in unless they were re-routed using the Link command. By default, Buffered is always TRUE unless the Link command has been used in which case Buffered is always FALSE. You can turn buffering on and off by setting this property.
Socket.Telnet
Syntax
Socket.Telnet#

Returns TRUE if the connected socket will treat the connection as if it were using the telnet protocol. Some telnet servers require negotiation upon connection by a client which is very standard, but not easy to handle in CodeCurve code. Setting Telnet# to TRUE causes the Connect method to handle initial negotiations with the server, putting the connection in basically a text stream state. You can toggle whether Connect will handle telnet negotiations by setting Telnet# TRUE or FALSE.
Socket.Connect
Syntax
Socket.Connect Address$, Port#

Attempts to connect to a server located at Address$ on Port#. Port numbers 1-1024 are reserved for specific protocols such as FTP, Telnet, HTTP, etc. If you want to create client/server scripts using CodeCurve, it's recommended that you use a port number higher than 1024.
Note: If you are having trouble connecting to a telnet server, you might need to set the Telnet property to TRUE just before calling Connect.
Port constants are provided for common, known port numbers (although it is not likely you will use these constants often with the Socket object):
Constants and their TCP/IP port number values:
ippEcho@
7

ippDayTime@
13

ippFTP@
21

ippTelnet@
23

ippSMTP@
25

ippNameServer@
42

ippFinger@
79

ippHTTP@
80

ippPOP2@
109

ippPOP3@
110

ippUUCPPath@
117

ippNNTP@
119

ippSNMP@
161

ippIRC@
194

ippTalk@
517

ippUUCP@
540

Example:
New Client As Socket
Client.Connect "microsoft.com", ippEcho@
Socket.Listen
Syntax
Socket.Listen Address$, Port# [, WaitSeconds#]

Causes socket to become a server by listening for attempted client connections. Address$ and Port# are where the server will be waiting.
WaitSeconds# is optional and 0 by default. If WaitSeconds# is provided and non-0, the script will pause and the socket will listen until either a client socket connects, or the specified time elapses. If WaitSeconds# is not provided, or is 0, the listen function will return immediately, but the socket will listen for a client to connect for the life of the socket object.
Example:
'  This example assumes the IP address,
'  yours will be different
New Client As Socket
Client.Listen "128.128.128.28", 1025
Socket.Close
Syntax
Socket.Close

Closes an open socket connection.
Example:
New Client As Socket
Client.Connect "microsoft.com", ippEcho@
Client.Close
Socket.Link
Syntax
Socket.Link SocketObject

Connects two socket objects together, re-routing all data to each other. SocketObject is the name of an existing, connected Socket object. Useful for creating scripts that watch data being passed. NOTE: commands like ReadString and WaitFor will not work with objects connected using Link until you re-enable buffering for the object using Buffered.
Example:
' this is a skeleton for a telnet script
' use a telnet program to connect to your
' local IP address
New Client As Socket
New Server As Socket

Client.Listen "123.456.789.0", ippTelnet@, 30 ' use local IP
Server.Connect "anybbs.com", ippTelnet@
Server.Link Client
Server.Buffered# = true

while Server.Connected# = true and Client.Connected# = true then
  Line$ = Server.ReadString(10)
  ' do something with the line from the server
endwhile

Socket.WriteString
Syntax
Socket.WriteString Text$

Sends a text string out a connected socket. The socket may be connected as a client or server using Connect or Listen, respectively. If you are communicating from one CodeCurve script to another, it is recommended you always append each string with ASCII(13) (return char) so the other script will receive the string immediately.
Example:
Client.WriteString "This is a test!" + 13
Socket.ReadString
Syntax
$ = Socket.ReadString(WaitSeconds#)

Reads all characters until one which matches a character in the BreakChars$ (ASCII 13 (return) by default) property is encountered. Any characters read which match any character in the IgnoreChars$ (ASCII 10 (newline) by default) property are discarded. If the property BreakOnNull# is TRUE (FALSE by default), reading also terminates if a NULL character is read, otherwise NULL characters are discarded.
If WaitSeconds# has passed before a proper string termination occurs, all characters read up to that point are returned.
See
BreakChars
IgnoreChars
BreakOnNull
Example
Line$ = Server.ReadString(2)
MsgBox(Line$)
Socket.WriteBuffer
Syntax
# = Socket.WriteBuffer(Buffer#, Size#)

Writes Size# number of bytes from the memory address given by Buffer# to the connected socket. Returns the number of bytes actually written.
Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Written# = Socket.WriteBuffer(P#, 1024)
Socket.ReadBuffer
Syntax
# = Socket.ReadBuffer(Buffer#, Size#, Secs#)

Reads Size# number of bytes from the connected socket into the memory address given by Buffer#. Returns the number of bytes actually read. If Secs# number of seconds has passed before Size# number of bytes have been read, the function will return with the buffer only partially filled.
Buffer# should be the memory address of a buffer sufficiently large enough to hold the number of bytes being requested. Buffer# can be any memory address, but most likely it will be a buffer allocated by the Heap object.
See Also
Heap
Example:
Read# = Socket.ReadBuffer(P#, 1024, 4)
Socket.WaitFor
Syntax
# = Socket.WaitFor(TestString$, WaitSeconds#)

Scans characters coming through a connected socket and returns TRUE (1) if the string is found before WaitSeconds# passes, otherwise returns FALSE (0).
Example:
'  simple test to detect echo server connection
New MySock As Socket
MySock.Connect("provider.com", ippEcho@)
MySock.WriteString("Hello!" + 13)
Found# = MySock.WaitFor("Hello!", 2)
Compatibility Issues With CodeCurve
CodeCurve-005 is fully backwards compatible with scripts written with CodeCurve.
Compatibility: The Engine DLL
The interpreter engine is now named OBEngine.dll. A new system of versioning that will allow the engine to interface more cleanly to various extension objects expecting different versions of the DLL. Maximum compatibility between .OBXs and the engine is maintained, but incompatibilities are noticed with more accuracy and the job of getting the right update is no longer a guessing game.
Compatibility: .COD Files
CodeCurve-005 .COD files are in a new format, but both the editor and engine can still read older script files. Of course, CodeCurve doesn't know about the new format, so you cannot create scripts using CodeCurve-005 and expect them to run with CodeCurve.
Compatibility: Dialogs
Dialogs are now called Forms. Forms use named controls now, and control names should be used with all function that used to require child IDs. However, you can use either names or IDs; CodeCurve-005 will interpret either.
Compatibility: The If Statement
CodeCurve-005 now supports a single-line If statement. There must be no EndIf, and the one call allowed should be one the same line as Then. This will break scripts that use single-line Ifs which are terminated by EndIf. Actually, there was an original bug where EndIf could be interpreted as a parameter to any function call that accepted optional parameters. Anyone experiencing this would surely know and would have, by trial and error, fixed the problem. However, I could not allow this bug to persist, so I made it an either-or choice: either make it a one-line If or put the statements in a Then block on lines by themselves. If you want the elegance of one- line Ifs, don't terminate it with EndIf and don't try using Else. Just write it:
if 1 = true then DoSomething
Compatibility: Extension Objects
As of CodeCurve 97.003, extension objects must specifically written for CodeCurve-005. A new system of versioning makes this necessary. The new system will actually query the .OBX to see if it is compatible with the current version of CodeCurve. If the .OBX is not compatible, it is possible to upgrade either the .OBX or the CodeCurve engine, and you will be told which action you need to take. To help enforce the use of only versioning extension libraries, the engine DLL was renamed to OBEngine.dll, thus making it likely older .OBXs can't even be loaded.
The uninstaller for CodeCurve will clear everything referring to CodeCurve out of the registry, including extension factories and objects. If you want to continue using extension objects you installed for CodeCurve, you must install updated versions of them. They are all available at http://www.celsoft.com/obasic/.
The Archive object is built-in to the engine now, so the Archive extension object is redundant. However, the .OBX is used by WinArk.exe, so it can't be deleted (yet). A new WinArk.exe is going to be made available when CodeCurve-005 is officially released, and it will use the archive services provided by OBEngine.dll, rather than Archiver.obx.
Registering CodeCurve
How To Order
To order a license for development of CodeCurve scripts by a single-user/on a single machine: http://www.celsoft.com/obasic/order
To order a site license for development of CodeCurve scripts by an unlimited/unknown number of users at a single location/company: http://www.celsoft.com/obasic/ordersite
Visit Celtech Software's on-line order page at http://www.celsoft.com/order.html.
Expiration
CodeCurve never expires, but it will refuse to execute .COD files which are older than 30 days. You may continue creating new .COD files and use them for up to 30 days using the shareware version of CodeCurve-005. However, after 30 days, you must register in order to continue executing your expired .COD files.
What Do I Get When I Register?
You get a single-user license for all commercial 97.x versions of CodeCurve-005 (standard license),and the use of your .COD files which are older than 30 days. Upgrades are provided free via email or for the cost of shipping/handling through postal mail. Multi-user site licenses are available to reduce the cost of purchasing multiple single-user licenses of CodeCurve.
Note: CodeCurve scripts developed by registered users may be distributed, compiled or uncompiled, freely. There are no licensing/distribution restrictions placed on scripts created by registered users.
You also gain access to the extension objects which ship with CodeCurve. The shareware version installs these objects, but use of them requires a standard CodeCurve-005 registration license.
Why Should I Register?
Because the shareware version of CodeCurve is for evaluation only. You are given a 30-day evaluation period during which you can play with CodeCurve to be sure it's what you need. After the 30 days, you must register or remove CodeCurve from your system.
Technical Support
Technical support is available by Internet email only at this time. If you have any questions on using CodeCurve, write to info@celsoft.com.
Copyright Statement
CodeCurve-005, Copyright  1994-1997 Celtech Software.
All Rights Reserved.
INSTALLATION OF THE SHAREWARE VERSION OF CodeCurve-005 ON YOUR COMPUTER SYSTEM IMPLIES AGREEMENT WITH THE TERMS AND CONDITIONS BELOW.
DISTRIBUTION OF CodeCurve-005, ITS ACCOMPANY PROGRAMS AND DOCUMENTATION IS CONSIDERED AS IS. CELTECH SOFTWARE OFFERS NO WARRANTIES OF ANY KIND, EXPRESSED OR IMPLIED. THIS INCLUDES, BUT IS IN NO WAY LIMITED TO, WARRANTIES OF CodeCurve-005'S MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. UNDER NO CIRCUMSTANCES WILL CELTECH SOFTWARE BE LIABLE FOR ANY DAMAGES WHICH RESULT FROM THE USE OF THIS PROGRAM OR THE INABILITY TO USE IT. EXCLUSION FROM LIABILITY INCLUDES, BUT IS NOT LIMITED TO, LOST PROFITS, LOST SAVINGS, OR ANY OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES.
The product name "CodeCurve" is used to describe the shareware version of the CodeCurve-005 software program and the files which are distributed as being part of CodeCurve owned by Celtech Software.
CodeCurve is distributed as Shareware. It is not free, freeware, or in the public domain. You may use CodeCurve for a trial period of thirty days, at no cost to you, to determine if it fits your needs. If you decide to use CodeCurve, you are expected to register it and pay the applicable registration fee.
You may not modify or dis-assemble CodeCurve, nor distribute any modified or dis- assembled versions of CodeCurve.
You may distribute CodeCurve only if CodeCurve is in its entirety and no other files are distributed as being part of CodeCurve.
U.S. Government RESTRICTED RIGHTS: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software clause at 252.227-7013.

Index Field, please update in your word processor