Clear Basic : is a new type of programming language like the MS Visual Basic which is designed to speed up the development process. It does this by providing pre-coded objects, methods and properties. Clear Basic is used to customize clarify applications. it allows you to add new functionality at the clarify client application level, such as new forms and controls that access the database in ways that one has customized.

Clear Basic consists of

1. Basic interpreter (translates between code and clarify system).

2. Basic language functionality intrinsic to the interpreter.

3. Objects, methods and properties developed and optimized for the clarify system.

Object : a pre-coded and logically coherent set of behaviors that you can activate by invoking its internal procedures via method calls or by setting values in data fields via property settings.

An object is manipulated via its methods and properties.

Method : a method is a public way to access an object's private internal procedure.

Property : a property is a public way to access an object's private data fields.

Method calls : Object.Method parameter

Property settings : Object.Property = Value

Form : A form is a visible presentation, based on the metaphor of a printed page of items (controls)

that invite user interaction.

Database storage of GUI components : designed by the use if UIEditor and exported to the client's database.

Database storage of Form Code : import code into database using cbExchange. When application is started, both the GUI component and form code component of the system are loaded to the client.

Controls : are visual elements placed on a form.

Events : occur in forms and controls and are caused by user activity. Programming in Clarify follows the Event Driven Model. You write code in response to an event.

Naming convention : Controlname_event_name

1. Clear Basic toolkit (Cbex)

2. Data Exchange (import customer data ffrom legacy databses).

3. ddcomp (the schema compiler)

4. Data dictionary Editor : modifies the database.

5. UiEditor

6. Api toolkit. Allows you to write application that access the database, bypassing the clarify application GUI. Alternative to Clear Basic code. Cannot call API's thru Clear Basic code.

Order :

1. Schema change

2. UI changes

3. Code changes

UIeditor : make sure that the -cb option is specified in the properties icon.

Design Requirements :

Database considerations - tables/ views to be used added, altered

User Interface

Types of clarify forms.

Forms - no contextual objects are automatically linked to it. If it is a new form or you intend to manipulate a different set of contextual objects

Frames - sub form linked to a parent form. New -> Frame automatically inherits all the contextual objects linked to the parent form at creation. backgrounds the parent form. cuts down development and scope for error. contextual objects need to be in the same order as the parent form.

Tab - posed from a tab widget. the form appears within the parent form. also inherits all contextual objects.

Code changes:

cannot update global module during runtime. Changes take effect only upon restart of application.

cannot update form modules that depend on global modules.

required code in all form: form_load for standard clarify code behavior to occur.

check to see if the default code has closed the window (cbDefClosedWindow) or the result of Me.DoDefault statement after it is invoked.

Function names cannot exceed 80 chars. first 20 must be unique.

Stacks space :

local - holds local variables (except strings and arrays)

public - holds public variables incl strings and arrays.

modify it by setting cbStacksize (max = 8K bytes) and cbPublicSize(default = 64K, <>64K) in the env file.

file size = 60000 bytes max.

names of record fields are highly sensitive.

Categories of Contextual objects :

1. Database contextual object - predefined for use with a specific clarify table or view or a specific custom table. You intend to use some or all of the fields.

2. UDT contextual object - can contain about anything within the limits of UDT. (custom lists)

3. Temporary contextual object - stores primitive data that is not linked to the database.(in memory CObj)

Copy by reference - you are actually manipulating the original object. Copy by value - manipulating a copy of the object.

If there is a method, property or object available within Clarify's Clear Basic toolkit, then it should be used instead of whatever comparable entry is documented in the Clear Basic Language Reference. (could be redefined, or it presents a different methodology or possibly some of the BasicScript User Dialogs are not supported).

Naming conventions.

Forms.

1009_4.0_1.0.cbs

Contextual Objects.

Mixed case with no underscore >! 80 char first 20 unique

Cobj_lor_ContactView

Control Names

clb_Employee

Keywords

Start with UpperCase, Dim

Variable Names

Starts with a letter >! 80 first 20 unique

Punctuation not allowed

Exclamation should not be the last character.

the last char can also be $,%,&,#,@, ! ONLY if being used in a type declaration.

Methods and Properties

MixedCase GetField

Event Procedure Names

Control_Event btn_Close_Click()

form_load, init_app

Subroutine Procedure

Punctuation not allowed. ! allowed if not last character.

Function Names

do

Scoping :

modular of form

global.

Every form that is posted gets a maximum stack of 8K. Try to make variables form scoped or global if possible. Also try to use methods/properties wherever possible.Declaring Object variable. use NEW.

Assigning to Object variables : Use SET

Initializing Certain Objects.

RecordType, Itemtype

User Defined Types: are structure definitions created using the TYPE statement. Are equivalent to C language structures (are useful when manipulating data from external sources). Type MyType--End TypeIf declaring UDT's as CObj then add 'Dim Dummy as MyType' in form_load. You must declare at least one variable of UDT type or else the compiler will optimize it out. You must also feed in a definition to the UiEditor if using UDT as a contextual object.

Cannot use UDT as LHS of any expression. Use GetContents.

A contextual object is a memory are linked to a form in order to hold values for a control in the form. You must use contextual objects if you create a new form, frame, tab, controls. You must link contextual objects to the form before you attempt to create controls in the form anytime except runtime).

Source : if you want initial values to be loaded into the control when the form is posted.(DDLB,DDCB,CLB,LB). Not required for Chk B,Com B, label,Tab,Opt B.

Destination : if you want to hold the value that the user selects or enters. You must still write Clear Basic code to get this value and use it.Control Source Destination

check box String Integer

command button string -

custom list varies for each list

drop down combo list string

drop down list list string

label string -

list box list list

multiline text - string

option button string string

textbox - string

you can read and write to a clarify cobj as long as the cobj is not of type list. If list, you can only read from it. New forms require a form_load and Message handler. Frames tabs require only form_load routine. Form activation happens for parent only. During the execution of a Clear Basic procedure, redraw is delayed until the entire procedure is finished in order to obtain better performance. Use Force Redraw method to force execution up to the point where ForceRedraw is called.

Can have only one set of tab widgets in a parent form. Color and size of a tab is fixed. TAB_D_FormId.

Do not write a click event for a tab. If you do so, the tab will be posted as a form. MyWidget.Value = 1 to invoke the tab.

Initializing Forms.

1. Fill lists with static text.

2. Fill text boxes with static text.

3. Enable/Disable controls.

4. Use a specific color scheme.

Accessing the clarify database.

BulkRetrieve: retrieves records from a clarify database. A complete record is obtained.

BulkSave : insert/update/delete records and relate records.

After the bulkretrieve, you must use one of the 3 query methods.

1. SimpleQuery

2. TraverseFromParent3. TraverseFromRoot

BulkRetrieve: Dim YourBulkRetrieve as New BulkRetrieve

Loading Query : Using any of the above mentioned query methods.

Loading Filters:

Retrieving Records: Retrieve Records.

Accessing Records: Use the same index entry. GetRecordList, GetRelatedRecordList

1. Get records of a single type (no related records) OR

2. use it as a first step in building up a TraverseFromRoot, TraverseFromParent

Get all records that have a specific relation to a root record. Only one TraverseFromRoot can be specified in a BulkRetrieve Object.

SimpleQuery,

SetRoot

TraverseFromRoot

GetRecordList

TraverseFromParent: If you need to retrieve several records along with their related records.

SimpleQuery,

TraverseFromParent

GetRelatedRecordList (Returns more than one list)

Can use as many TraverseFromParent/Root as possible (database performance issue)

To save records or relations back to the database. Normally one should batch up the relations and records in a single BulkSave to reduce network round trips.

The transaction is automatically rolled back if the query fails. Retry happens until the transaction succeeds or a certain number of failure occurs.

cbChangeToNew - resets the objid field in the Record so that it will be treated as a new record.

Used it if you copy a record and want that to be treated as a new record for insert.

ByVal and ByRefdefault = ByRef

ByVal Eg For I = 1 to 10

rec1.SetField"id_number","case" & Str(I%)

MyBulkSav.InsertRecord Rec1, cbByValue

Next I

MyBulkSav.Save

If using ByRef, the same record is overwrittem 10 times.

ByRef

MyBulkSav.InsertRecord Rec1

MyBulkSav.InsertRecord Rec2

MyBulkSav.RelateRecords Rec1,Rec2, "relate_this2taht"

If using ByVal, RelateRecords will have no effect on the reords in the BulkSav and they will not get related.

Relating Records:

RelateRecords: Use it if the records you are relating are new records.

RelateRecordsFromId: Use it if you have the objid of the database record that you want to use as the source of a relation, and you want to relate that record to another record in the bulkSave.

BulkSav.RelaterecordsFromId "case", CaseObj, Rec1, "case_notes2notes_log"

RelateRecordsToId: Use it if you have the objid of the database record that you want to use as the target of the relation, and you want to relate that record to another record in the BulkSave.

BulkSav.RelateRecordsToId CaseRec, "notes_log" NoteObjid, "case_notes2notes_log"

RelateRecordFromToId: Use it if you have the objid's of the two database records that you want to relate. No records are placed in BulkSave, so no ByRef.

BulkSav.RelareRecordsFromToId "case",CaseObjid,"notes_log",NoteObjid","case_notes2notes_log"

Unrelating Records: If you delete records in the database, relations are automatically removed. If you do not delete,

ByBulk,UnRelateRecords, Rec1, Rec2, "relate_this2that" ----- Rec1 = Source Rec2 = Target

Database changes:

Form_Save1: intercepts before

1. any database transactions for the default clarify behavior

2. after records and relations are added but before new objids have been assigned

3. Your changes will take effect before any default clarify changes.

Form_Save2: intercepts after

1. Objid's of new records have been assigned, but before records or relations have been committed to the database.

2. Your changes will take effect after default clarify operations assign objid's to new records. Form_Save3: intercepts after records and relations have been committed to the database.

1. Your changes will take effect after default clarify operations are finished.

Don't invoke the save method in any of the Form_save routines.

Form_save1(MyBulksav as BulkSav)

Because every form must be able to handle the Close Message from Clarify, a form code module must have a Message handler.

Min Req

1. cbCloseMesage

2. Case Else - Me.DoDefault

#'s 500 to 4999 are reserved for clarify.

use #'s 10000 to 30000

Sending Messages:

1. Notify - to send message to an unrelated form or to a form that has multiple instances posted.

Other_form.notify cbRefreshMessage

2. NotifyById - to send a message to an unrelated form, or to every instance of a form that has multiple instances posted.

Me.NotifyById 5050 cbRefreshMessage

3. NotifyParent/ Notifychild. - You must set up the parent/ child relationship. SetParent

Me.NotifyChild Message1

Me.NotifyParent Message1

Me.Close cbCloseChildren to close parent and all child forms.

4. NotifyByKey

Me.NotifyByKey FormKey, Message1

Customizing Menubars:Add/Rename/Remove/Associate New Event Procedures/Disable/Append Seperators.

Exporting Global:

Importing Global

cbex -spec global.cbs -G clarify -imp (back to the database)

You can customize menus by including the appropriate Clear Basic code in the initialize_app procedure.

A dim statement to declare each menu that you want to customize.

Application menubarId statements that identify the clarify applications in which the menus are to be customized. (1000 StartUp, 1001 Policies and Cust, 1002 ClearSupport, 1005 Prod Mgr, 1007 ClearLogistics, 1008 ClearQuality, 1011 – ClearContracts, 1012 - ClearSales)

Sub initialize-app()

dim App_Menu as AppMenu

App_Menu.MenuBarId = 1002

App_Menu.AddItem "Edit","Display Form","PressMe"

App.ShowDefaultMenu

End Sub

Edit = Menu label, Display Form = Menu item, PressMe = Event procedure.

MyAppMenu.RenameItem = "menu label", "old_menu_label", "new_label"

MyAppMenu.RemoveItem "menu label", "menu_item"

To associate a new event procedure to a menu item

MyAppMenu.SetFunction "menu_label","menu_item", "new_event_procedure"

MyAppMenu.Enable Menu_label, Menu_item, State

State = true/False

YourAppMenu.AppendSeperator "menu_label"

insert this statement after the statement that defines the menu item.

Exit Clarify and restart to see your changes.

Using UDT in the UIEditor.

1. Use a text Editor to create a file that contains the definition and declaration for each UDT.

2. Invoke the UIEditor with the following option

-c=YourUDTs

1. Check syntax of statemnts in code

2. Compile and import source code

3. Compile and import global

4. Unconditionally overwrite existing code

5. Export source code from database to local files

6. Remove existing code modules from the database.

# source code should be in the same directory as CBEX.exe

# define a directives file (.cbi). It is easier to exp,imp and purge your code.

(format - srcfile.cbs F formId ClarVer userVer)

Invoking CBEX

cbex command_line_options -dir directives_file.cbi

cbex -batch -dir File.cbi

cbex -spec srcfile.cbs -F formId ClarVer UserVer

messages are stored to cbex.log if using -batch option.

cbex -syntax -spec srcfile.cbs -F formId ClarVer UserVer

cbex -spec global.cbs -G clarify

-overwrite

Exporting source code from the database:

cbex -exp -batch -dir File.cbi

cbex -exp -spec srcfile.cbs -F formId ClarVer UserVer

Removing code modules from database

cbex -pur -batch -dir File.cbi

cbex -pur -spec srcfile.cbs -F formId ClarVer UserVer

Debugging:

To generate an SQL log file

place this line in initialize_app

Handling date and Time:

Retrieving Server Time

DateTimeStr = App.CurrentDate

MyDate = CDate(DateTimeStr)

DateTimeStr = CStr(MyDate)

Retrieving Client time:

Use the Time function (date data type)

Time$Function (String)

Functions for date and time manipulation:

DateAdd (add a # of date interval to a date)

DateDiff (subtract )

DatePart (return a portion )

DateSerial (assemble a date from date parts)

DateValue (convert a string to a date)

TimeSerial (Assemble a date and time value from time components)

TimeValue (convert a string to a date and time value)

Accessing External Databases with SQL:

Clarify provides SQLDB object and related methods to allow you to access Clarify databases or foreign databases using SQL(isql).

Declaring SQlDB

dim YourSQLDB as New SQLDB

Connecting

Disconnect

If not returning values

Max length of statement = 6144 chars

Invoking a stored procedure

SqlState = "ngw_insert_act_entry " & "'" & ActCode & "'," & _

ActObjid & "," & _

1

toDB.Select SqlState, ActObjid

Clear Basic language has been created using a product from Summit Software company called Basic Script. Basic script provides the foundation to Clear Basic as well as most of Visual Basic like statements and functions. What Clear Basic adds is a set of objects, their methods and properties as described in the Clear Basic object.

Basic Script checks for an On Error handler within the currently executing subroutine or function.Sub TestProc() On Error GoTo Catch ‘Do something here Exit SubCatch : ‘ Handle ErrorEnd SubCascading Errors ;If On Error Handler is not specified in the currently executing subroutine, then BasicScript returns to the calling procedure and executes the error handler there. The process repeats until a procedure is found that contains the error handler or there are no more procedures.

Resume : This statement resets the error handler transferring the execution to an appropriate place within the current procedure. The error is reset if the procedure exits without first executing Resume.

Where possible, BasicScript has the same error numbers and error messages as Visual Basic. This is useful for porting scripts between environments.

Error$ - query the error number

Err.description – error description.Visual Basic compatible errors – 0 to 799Basic Script errors – 800 – 999

User-Defined errors - > 1000

Most errors c(except some system error can be trapped this way).

Resume Next : causes execution to continue on the line following the line that caused the error.

Goto 0 – causes any existing trap to be removed.Any error trap is active only within the subroutine or function in which it appears.Resume {[0] | Next | label}

0 – causes execution to continue with the statement that caused the error.Next – causes execution to continue with the statement following the statement that caused the error.

Label – causes execution to continue at a specified label.Error errornumber – stimulates the occurrence of the given runtime error.

Err = Value

Sets the value returned by the Err Function to a specific integer value.Err.Clear – clears the property of the object.

Err.Raise – Generates a runtime error, setting the specified properties of the Err object.

Err.Raise [,[source] [,[description] [,[helpfile] [,helpcontext]]]]

Err.description – sets or retrieves the description of the error.

Err.Helpcontext – sets or retrives the help contextID that describes the help topic for information on the error.

Err.Helpfile – Sets or retrives the name of the help associated with the error.

Functions :

Error,Error$ - returns the string containing the text corresponding to the given error number or the most recent error.

Error$ - returns ‘String’, a string

Error – returns a string

Erl() – returns the line number of the most recent error.