Getting Started

Getting Started With GoDB

GoDB is a Multi-Platform Application Development tool. GoDB lets you develop applications you code once and deploy them to multiple platforms without any change.
GoDB SDK comes with an IDE that lets you create, modify, build, run, simulate, debug and deploy your applications to multiple platforms from familiar Microsoft
Windows.

Loading and Running a sample project

Step 1) Start --> Programs --> GoDB --> GStudio

Step 2) File --> Open

   

Step 3) Select the Project to load (Sample1)


Samples are located under the GoDB Installation Folder.

Ex: C:\Program Files\GoDB\Samples\Sample1\

Step 4) Select the Platform to target.

Step 5) Build .

Step 6) Build Results .

Step 7) Run.

Step 8) Log in

Step 9) Home Page.

Step 10) Hello World.

 

Lesson 1

Lesson 1

The basics first.

GoDB is a Multi-Platform Application Builder.


With GoDB you can 
       Develop Once
Deploy to any
popular PDA,Laptop or Desktop.

       Develop Online / Offline and Occasionally Connected applications.


GoDB
VM has four primary components.

1. Microbrowser for rendering forms.
   
   
2. GBasic Scripting engine.
   
   
3. ANSI SQL RDBMS to manage local data.
   
   
4. Smart sync engine to keep local and remote tables and files in sync.

GStudio IDE has the following components.

1. Form Builder.
   
   
2. Simulators for devices/PCs.
   
   
3. Integrated source level debugger.
   
   
4. Single click deployment to multiples devices.

Creating a Project

In this tutorial we will see how to create a simple Hello World application.


Step 1: Launch GStudio


GStudio is the RAD(Rapid Application Development) IDE(Integrated Development Environment) for developing GoDB applications.


Start Menu->Programs->GoDB->GStudio.






Step2: File->New Project.

Select the Project Type "Hello World Application".

Select the Project Directory by clicking on the button next to "Location".

Enter a Project Name in the "Project Name" box

Select the Platforms for which you want to build this project

Click OK button to create the project


Note: You may add additional platforms to the project any time later.








This should create a project, add some startup files.


Lets look at the files that were created now.



Logon.frm All GoDB projects start with a logon screen so that the user can login before using the application.


Home.frm When the user logs in successfully, this page is loaded.
Config.frm,Config.ini These pages are for viewing and storing configuration information. We will see how to use these pages in detail in later chapters.


Now Lets compile and run the project.


Select the Platform,





Compile.





Run





You Should see the Login Screen in the Simulator





Click on Logon Button.





You Should see the Welcome to GoDB Button.


Close the simulator by clicking on the Power button .

---

Writing Event
Handlers

Event handlers in GoDB are GBasic scripts that are invoked when an event on a control is fired.


In the IDE Open home.frm by Double clicking on it in the project tree.






When the form opens up Double click on the "Welcome to GoDB" Button.





This should add a bas file called Home.bas and open up the code editor where you can write GoDB GBasic Scripts.





Type the above code Save, Compile and run the Project. In the simulator when you login and click on the Welcome to GoDB Button you should see a "Hello There" message box.

---

GoDB Files

GoDB Projects have three types of files.


FRM files that have forms.

BAS files that have scripts for event handlers.

BIN files for storing images.


When a project is compiled all these files are bundled into a single BDB file.

The GoDB VM loads and executes this BDB file.


This BDB file is platform neutral so you can copy a BDB file created on one platform say Win32, copy it to an another
platform say Linux your application should run without any change.


GoDB Achieves Platform neutrality by having separate GoDB VMs for separate platforms.


When you distribute your applications you just need to bundle the BDB file and the GoDB VM for the platform you wish to run the application on.

 

Lesson 2

Lesson 2

GBasic Introduction

GBasic is a variant of the Basic Language included in GoDB platform as the scripting language.

Program Structure

GBasic programs are usually associated with a form and have the same name as

that of the form.


For example

Home.Frm will have an associated BAS file in the project called home.bas.

When Home.Frm is loaded, GBasic scripting engine loads home.bas and executes

all statements, till the END statement is not encountered.



Home.bas



a=10

b=20

print a,b

END



sub Button1_click

msgbox "Button clicked"

endsub



The program can also have subroutines that are event handlers for controls

in the form, like a mouse click event on a control.


Event Handlers have names that are of the format ControlName_EventName



Ex: Button0_Click

---

GBasic Variables and Objects

GBasic has two types of variables, numeric and string variables.

                
String variables and functions that return strings always terminate with a $.

                 
Ex: A$,B$, Mid$(a$,1,2) etc

                 
Variables without a $ at the end are considered to be numeric variables.


GBasic has two types of objects , Form Field Objects (Controls on a form) and Database Field objects.


                  
Form field objects precede with a #

                  
Ex: #UID , #UID$ etc.


                  
Database field objects precede with a @

                  
EX: @a.ID, @a.Name$

---

GBasic Operators

For a
Full List of operators Refer to Operator List

Operators For Numeric variables


      + ADD

      - SUB

      * MULT

      / Division

      \ Integer Division

      % MOD

      ^ Integer Exponent



GBasic supports the following Comparison Operators.


       > Greater than

       < Less Than

       = Equal

       <> Not Equal



GBasic supports the following Logical Operators.
     
 AND     OR



Operators For String Variables


+ Append


EX:

     B$="Test1"

     A$=" Hello " +B$


Note: When appending a large number of strings use Concat Function instead of the + operator.


You can also append numeric literals, variables and expressions to strings.


    ' Numeric Literal

    A$=" Hello " + 100.25


    'Numeric Variable

    c=100

    A$=" Hello " + b$ + c


    'Numeric Expressions appended to strings 



c=100
d=200

A$=" Hello " + b$ + (c+d*20)

A$=
(c*10+23) + " Hello There "


A$ = "Ubound of array is " + ubound(st$)


A$ = "Len of String is " +  len("Hello")
A$ = "Len
of String is " +  len("Hello") +20 +" Done "
A$ = "Len of String is "
+  ( len("Hello") +20 ) +" Done "

GBasic supports the following String Comparison Operators.

= Equal

<>  Not Equal


EX:


if a$=b$ then

print "a is equal to b"

endif

String Escaping



Special chars like " etc are
escaped with a back slash '\' in a string Literal.

Ex
a$="Hello
there \"124\" "
a$="Hello there \n"
a$="C:\\Temp\\a.txt"

Special
Chars 

\n  - New Line
\r  - Carriage Return
\t -
Tab
\" - Double Quote
\' - Single Quote
\\ -
Backslash

Other chars can be specified by specifying the HEX value
prefixed \x

EX:
a$="Hello there \x0D
\x0A  "

Special Numeric Statements
You can
use C Style Increment ,Decrement  and Cumulative Numeric
statements

Increment ++
Decrement --
Cumulative Numeric , +=
, -= , *=
etc
Ex:
a++
b--
a+=10
a-=20

Etc: Note these
commands cannot be used in expressions.
Ex: a = b+(c++)
is not allowed.

Numeric Literals in other bases Hexadecimal and
Binary.

GBasic Supports Hex Literals of the format
0xAABBCC
and binary Literals
0b1010

Ex:
' Hex Literal
a=0xEF10D
'
Binary Literal
b=0b10101
'String Append with Hex Literal
a$="Test "
+ 0xEF10 + "*" + 0b10101

' Convert Decimal to Hex
print
Format$("%x",1000)

---

Variable Scope

The variables have three types of scopes

• GLOBAL
  
• LOCAL
  
• PAGE

Any variable that starts with ~ is a global variable and is
accessible from any function, subroutine and from any bas file in the project.

All variables declared outside the subroutines and functions becomes
a page-scope variable. This type of variable is accessible in any function and
subroutine within the same bas file.
Variables created in a function or a sub
have a LOCAL scope. They can be accessed only within the function.



Example


Home.Bas


Gnum1=10
            
'Page Variable - this variable can be accessed only in home.bas file.

~glob=20           
'Global Variable - this variable can be accessed in all the .bas files.



sub test1

   Lnum1=30
        'local variable accessible in test1 sub only

   print Gnum1
     'gNum1 has PAGE scope, so it can be accessed in test1

   print Lnum1

endsub



sub test2

   print Gnum1
'OK

   print ~glob
'OK

   print Lnum1
'ERROR : LNum1 local variable accessible in test1 sub only

endsub





Home2.Bas


sub test3


   print ~glob
'OK - if home.bas was loaded first and ~glob was initialized.

   print Gnum1
'ERROR : Gnum1 is accessible only in home.bas

   print Lnum1
'ERROR : LNum1 local variable accessible in test1 sub in home.bas only

endsub

---

Conditional Statements

GoDB Supports Block IF and Single line IFF statements.


ifConditionthen

   Statements

   Statements

else

   Statements

   Statements

endif

Ex:



if a > 120 then

    print "a is greater than 120"

else

    print "a is less than or equal to 120"

endif

print "Program Continuing"

---

iff condition then Statement1:Statements2

The : operator can be used for separating statements in a single line.


Ex:


iff a > 120 then print "a is greater than 120": goto
!ProceedNext


print "a is less than or equal to 120"
!ProceedNext print
"Program Continuing"

Note: GoDB Labels
start with a !.

---

Loops

GoDB supports two types of
Loops the For next and While Wend.

Loops can be aborted by a
Break Statement.
The control can be transfered to the loop
beginning using a Continue
statement.


For Variable = Start to End [Step Increment]


iff condition then
Break

iff condition then continue


Next



Ex:



for i =1 to 100

print i

next


for i =1 to 100 step 10

iff i > 50 then break

print i

next

---

While Condition

While Condition

    iff
condition then break

    iff condition
then continue


Wend


Ex:



i=0

While i < 10

print i

i=i+1

wend


i=0

While i < 10

print i

iff i > 5 then break

i=i+1

wend

---

Subroutines and Functions

GoDB allows creating modular applications using subroutines and functions.


Subroutines are blocks of code that do not return values.

Functions are blocks of code that return values.


Subroutines are defined as.


SUB SubroutineName(Parameters)



iff condition then return


EndSub


To call a subroutine you have to use the CALL statement.


Ex:


Call test1

End


sub Test1

print "Inside Test "

endsub





Ex Sub with parameters:



Call test1(1,"test")

End


sub Test1(a,b$)

print "Inside Test with numeric and string parameter";a;b$

endsub





Note:
You should not jump out of a sub using a goto statement.

Use Return statement if you want to exit a subroutine.


In GoDB when strings  are passed to a sub or function,
they are passed by reference.
String
literals , String expressions ,
Numeric variables and Numeric Expressions are passed by value.
All arrays variables
are passed by reference.



c$="test"

d=100

Call test1(d,c$)

print "after Test1 ";d;c$

End


sub Test1(a,b$)

print "Inside Test1 ";a;b$

b$="Welcome to GoDB "

a=120

endsub

' Passing Array
dimi
a(10)
a(0)=10
call test2(a)
print "After ";a(0)




End

sub Test2(Dimi b())
print "Before" ;
b(0)
b(0)=20

endsub

You can also pass Integers
and Double Variables to functions/subs by using the ByRef
Keyword..



dimi a
a=10
call test2(a)
print "After
";a


End



sub Test2(ByRefDimi b)
print "Before" ;
b
b=20

endsub 

---

Functions

Functions are defined as



Function FunctionName(Parameters)
  
iff condition then return
   return
100
Endfunction

Starting from
GODB 5.2 You can return values with return statement.

Function
Test 
    return 100
end function

FunctionI
Test1 
    return 100
end function

FunctionF
Test2
    return 100.24
end function

FunctionS
Test4$
    return "Welcome to Hello "
end function


The traditional way of returning value from a function is by
asigning the return value to the function Name.

Function
FunctionName(Parameters)
  
iff condition then return
  
FunctionName = ReturnValue

Endfunction


Functions are called by using them in an expression.


Ex:




t=TestFunc()

print t

End







function TestFunc

print "inside
TestFunc"

TestFunc=10

endfunction





Ex: With parameters



print TestFunc(1,"test")

End



function TestFunc(a,b$)

print "inside TestFunc ";a;b$

TestFunc=a+100

endfunction






Ex: String Functions



print TestFunc$(1,"test")

End







function TestFunc$(a,b$)

print "inside TestFunc ";a;b$

TestFunc$ = b$ +" added in func "

endfunction






Ex: String Functions Passed ByRef




c$="test"

print TestFunc$(1,c$)

print c$

End







function TestFunc$(a,b$)

print "inside TestFunc ";a;b$

TestFunc$ = b$ +" added in func "

b$="Modified in TestFunc"

endfunction

---

Recursion

GoDB

also supports recursion .



Call recsub(1)

End


sub recsub(a)

   iff a >10 then return

   print a

   call recsub(a+1)

endsub

Starting from GoDB 5.2 you can use Recursion
in functions too.

ret=RecFunc(1)

End

face=Courier>FunctionI RecFunc(a)

   iff a >10 then return

   print a

   call RecFunc(a+1)

end Function

---

Dimensioning and Arrays

GoDB Supports creation of Numeric or string arrays using the DIM
statement.

DIMI - Integer Variables
DIMF - Floating
Point Variables
DIMS - String Variables



Numeric Array


Ex:



DimI a(100)


for i=0 to 99

a(i)=i

next


for i=0 to 99

print a(i)

next






Note: GoDB arrays are 0 based so when you declare an array of 100 elements the elements start from 0-99.



Multidimensional Numeric Array



Ex:



DimI a(100,10)






GoDB Supports up to Four Dimensions for Numeric Arrays.
Only single dimensional String arrays are supported.

DimS can be used to define Strings and
String Arrays.

Ex:
DimS a$ ' Single
String
DimS b$(10) ' Array of 10
Strings.
DimS b$(10,5) ' 2-D Array Strings.



One interesting thing about GoDB strings is that they can be accessed as an array of chars. You can also use the Mid$ function to get substrings.




a$="testing 123 "

for i=0 to len(a$)-1

     print a$(i)

next






GoDB Strings are internally stored as Null terminated character strings. You need to consider this while setting characters at different positions.


This will work




a$="123"

a$(0)="A"

print a$






This will not work because there is a null char at a(3) so the print statement will print only till a(3)




a$="123"

a$(4)="A"

print a$






This will work.




a$="123"

a$(3)="A"

a$(4)="\x00"

print a$


Dim can be used to define String
with explicit sizes.

face=Verdana>Ex: String of size 10000




Dim a$(10000)

a$="testing 123 "

print a$











Ex: Array of 10 Strings with 100 chars




Dim a$(10,100)


for i=0 to 9

a$(i)="Hello there " + i

next


for i=0 to 9

print a$(i)

next






Array of strings can also be used like a two dimensional array of characters.




print a$(0,0)





Will print the first
character in the first string.

Multi dimensional strings (upto 3D) can be
declared using the Dim

Ex: 2D Array of 10x10 Strings with 100
chars

Dim a$(10,10,100)

You Can use
Redim to resize numeric arrays and StrExpand to resize Strings.


You can
initialize arrays by assiging the values enclosed in a bracket.

Dim
A(10)=(0,1,2,3,4,5,6,7,8,9)

You can also have new lines for
readability.

Dim
A(10)=(0,1,2,3,4,
                  
5,6,7,8,9)


Strings Arrays.

Dim
st$(10)=("0","1","2","3","4","5","6","7","8","9")

For Multidimensional
Arrays you need to provide the data for all the elements.

Dim
A(9)=(1,2,3,
                
4,5,6,
                
7,8,9)

---

Advanced Subroutines and Labels

GoDB supports jumping using
the GoTo Statements.

iff a=1 then goto !Cond1
iff a=2 then goto
!Cond2
goto !ENDPROG

!Cond1
print "Cond1"
goto
!ENDPROG

!Cond2
print "Cond2"

!ENDPROG

To allow of
jumping based on a variable GoDB supports Label Dereferencing.
Using Label
Dereferencing the label can be decided based on a string variable and a

Dereferencing {
operator.


j$="!Cond"+a
goto {j$}
goto
!ENDPROG

!Cond1
print "Cond1"
goto !ENDPROG

!Cond2
print
"Cond2"

!ENDPROG



Similarly you can use Dereferencing
operator to call Subroutines too.

for i=1 to
3
a$="Test"+i
call
{a$}
next

END


Sub Test1
print
"Test1"
EndSub

Sub Test2
print
"Test2"
EndSub

Sub Test3
print
"Test3"
EndSub

Note: Dereferencing can be done to
Fields, and even Variables.

Field Dereferencing

face=Courier>b$="Grid1" 'Calling Object
Methods
#{b$}.Addrow("Data1,Data2,Data3,Data4,Data5")


face=Verdana>Variable Dereferencing


for i=1 to
10
dimS {"GI"+i+"$"}
Next

for i=1 to
10
 GetImage({"GI"+i+"$"},10,10,20,20)
Next

---

Multiline
Commands

Multiline commands can be written using the _
operator.

a$="Hello There"
_
   "Welcome here"
print a$

iff a>10 and b>10 and _
   
c>20 and d>20 then return

if a>10 and b>10 and
_
    c>20 and d>20 then

print
"Hello"

endif


Note: The _ operator should have a preceding
space and should be followed by a newline and should not have any spaces (or
white spaces) following.

Lesson 3

Lesson 3

Multiplatform Form Builder and Event Handlers

GStudio comes with a powerful Form builder that lets you design Forms visually. Forms in GoDB are text files with XML tags
that correspond to different controls that GoDB Supports. When you add a text box to the Form a XML tag corresponding to a text box is created.



Ex:



<TEXT NAME="USERNAME" VALUE="012345678"/>





GoDB Supports the following Controls.


A quick summary of the widgets

Standard Controls

	Label	Used to Display Labels.
	Text	Edit Box for capturing Data From the user.
	Password	Edit Box for capturing Password From the user.
	Radio	Radio Button. Controls with the same name are grouped.
	Check	Check Box.
	Button	Standard Button
	Image
	Frame box	Used to group controls.
	Link	Used to Navigate between pages. URL property determines the new page.
	Read Only	Readonly box for displaying results etc.
	Popup Box	Popup to display help and alert Messages.
	Script	To Associate a different Bas File to the form.

UI Enhancement Controls

	Divider	To Display a Divider between controls
	Poly Line	Special control to display polygons.
	Title Text	To set the title for the form.

Enterprise Controls

	MultiLine	Edit Box for capturing Multiline Data From the user.
	List Box	DropDown List box.

Data Related and Special Controls

	Look Up Table (LUT)	Used to Display a Popup to select master items like Products,Customers etc.
	Embedded Grid	Grid that can be embedded in a form.
	Calculator Box	Popup calculator Control for entering numeric data and calculations.
	Date	Popup Datebox Control to select date.
	Sign Box	Popup Sign box control to capture Signature.
	Grid	Full screen grid to display reports etc.

Form Submit Controls

	Hidden	Hidden box for holding temporary values.
	Submit Button	To Submit the values of a form to an internet site or to another page.
	Cancel Button	To Clear the values entered in a form.

Building Forms

This section will demonstrate the process of creating a form, dropping controls and creating event handlers.


Step 1) Create a New project

Step 2) Open Home.txt and select the "Welcome to GoDB" button and delete it.

Step 3) Drop three label controls and Change their values to Enter Number 1 , Enter Number 2 and Result.








Step 4) Drop a Button Control, Drop three text controls and empty the value attributes for the text controls.





Step 5) Right click on the Calc Button -> Script Wizard -> On Click.





Alternatively for Click events you can just double Click on the control.


This should open up home.bas with a empty event handler.

Sub Button1_Click

' Add Handler Code Here

End Sub






Add the following Code to the event handler




Sub Button1_Click

#text3=#text1+#text2

End Sub






Compile and run the application. Enter data in the text boxes and hit the button. The third editbox should show the
sum of the numbers entered in the first two edit boxes.


Certain issues remain with this app. First the edit boxes allow characters.

Second the content in the result edit box can be modified. A common way to handle this is to make the edit boxes accept only numeric values and the result box
readonly.Here is how this can be done.




Select the text box and locate the validate property , click on the ... button and select the Numeric Check Box and hit
ok. Repeat this for the second text box too.







Select the third text box and make Disabled attribute to Yes. Alternatively you can also use a Readonly box for the result.

---

Multiplatform Forms

The form builder in GoDB can be used to create Forms that have different layout in different platforms.


The Master Form is common for all the platforms.


To adjust the layout for a different platform just select the appropriate platform tab.









The blue guide line indicates the screen boundaries for the platform.


Here we can see that the form has to be redesigned for palm.


Simply reposition or change the attributes of the controls to suit your platform screen size.





You can see that we have changed the X and Y positions in the Palm Form. This is indicated by the BOLD font in the attribute names.


If you want to remove any attribute you have to do it in the Master page.


When the project is compiled based on the platform selected for compilation the attributes from the appropriate Form will be used.







During the design process sometimes you might want to apply the value of a specific attribute to
all the platforms.This can be done by selecting the attribute in the Property list window and clicking on the A button.


If you want to apply all the attributes in a specific control in a platform to all the platforms you can select the control and Right click
-> Apply to all platforms.



You can also restore the default settings for a control by selecting the control and Right click
-> Revert all to default.



You can remove unwanted platforms by right clicking on the platform tab and selecting Remove Platform.







You can add a new platform you can right clicking on the platform tab and selecting Add Platform.







In the popup just select the platforms you want to add or
remove and hit OK.

---

Debugging

GStudio has a powerful built in debugger with break points, watch points etc. Lets see how a program can be
debugged using GStudio.



Copy the following code and paste it in home.bas





i=10

j=20

end



Sub Button1_Click

dim lvar

   lvar=10

   #text3=#text1+#text2

   print i

   print lvar

End Sub





You can set a Breakpoint by clicking on the left margin or pressing F9 key.







Now Compile the project and click on Start Debug.






This will launch the simulator in debug mode. When you login you should be able to see the Program Trace, That is the Blue markers in the Left Margin.







Now Click on the Button in the simulator.







This should stop the execution at the break point.







You can see the variables and fields in the Watch Window.



  



When the Execution is suspended by a break point you can use the debug aids to Control the execution.



Click on  to "Step Into" a Call Statement


Click on  to "Step Over" a Call Statement


Click on  to "Step out" of a Subroutine


Click on  to execute till the current cursor position


Click on  to Continue Execution from the current break point 


Click on  to Stop the Debug session


Click on  to Restart the Debug Session


To reset a breakpoint simply click on the red dot using your mouse or press F9 key.

---

Form Events

The above examples
demonstrated Events that Fields generate, similarly
the forms also generate
events that are common to all the controls like Mouse Click etc.

To
Generate Form Event Handlers Right click on the form when no controls are

selected.

>

Form_Load Event is called when the form
is loaded.

Form_Keypress  Event is called the
user presses any key.

GetKey() Function can be used to identify the key
pressed.
KeyHandled method determines if the events are bubbled to
the
next control or not.

Sub Form_KeyPress
' Add Handler
Code Here
' keycode = GetKey()
' KeyHandled(1)
End Sub

face=Verdana>Form_MouseClick , Form_MouseUP and Form_MouseMove

Events are generated for mouse events.
GetX() and GetY()
functions return the X,Y location of the mouse.
face=Verdana>MouseHandled method determines if the events are
bubbled to
the next control or not. For Example of a user clicked on a
button
Form_MouseClick is called first and if mouse is handled in
this
event handler you can choose not to process the Button_Click
Event.


Sub Form_MouseClick
' Add Handler Code Here
' x
= GetMouseX(0)
' y = GetMouseY(0)
' MouseHandled(1)
End
Sub

Form_Paint Event is called when
the Microbrowser is painted,
All the drawing routines like DrawLine
FillRect etc should be coded here.



Starting with GoDB 3.6 Form_RMouseClick and Form_RMouseUp

Have been added to handle right mouse clicks on platforms that

support it.

---

Form Navigation

GoDB uses a microbrowser for rendering forms,


Add a new form to the project. Right click on project explorer and select Add Form.





In the open dialog enter the name Main.
Select Yes when prompted for creating a file.


Double click on the Main.Frm in the project explorer add a few controls to the form and save.


Now open Home.FRM and add a Link Control . Change the value attribute for this control to
Load Main. Change the URL attribute to !main.frm.


In godb all references to local files should start with a !.




Note: When Changing primary properties use the
Master page. Use the platform pages only for properties that differ from the
Master. This is to avoid errors where you might change a property in PalmOS page
and compile a Pocket PC project and wonder why the property change does not
work.


Alternatively you can just dragdrop a file from the
project explorer
on to the form and this will create a link control.




Compile and run the project.