app builder 2 scripting tools

8/13/2019 App Builder 2 Scripting Tools

1/183

BluePhoenix AppBuilder 2.1.0.

Scripting Tools Reference Guide
http://www.bluephoenixsolutions.com/


2/183

BluePhoenix AppBuilder 2.1.0.Scripting Tools Reference GuideApril, 2003

Corporate Headquarters

BluePhoenix Solutions

Vlierwerf 7B4704 SB RoosendaalThe Netherlands+31 (0) 165 399 401+31 (0) 165 396 308 fax

USA Headquarters

BluePhoenix Solutions USA, Inc.8000 Regency ParkwayCary, NC 27511United States+1 919.380.5100+1 919.380.5111 fax

www.bluephoenixsolutions.com

1992-2003 BluePhoenix Solutions

All rights reserved.

BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company namesmentioned herein are for identification purposes only and are the property of, and may be trademarksof, their respective owners.

Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various

other non-U.S. patents.

The software supplied with this document is the property of BluePhoenix Solutions, and is furnishedunder a license agreement. Neither the software nor this document may be copied or transferred by anymeans, electronic or mechanical, except as provided in the licensing agreement.

BluePhoenix Solutions has made every effort to ensure that the information contained in this documentis accurate; however, there are no representations or warranties regarding this information, includingwarranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes noresponsibi li ty for errors or omissions that may occur in this document. The information in thisdocument is subject to change without prior notice and does not represent a commitment byBluePhoenix Solutions or its representatives.
http://www.bluephoenixsolutions.com/http://www.bluephoenixsolutions.com/


3/183

AppBuilder 2.1.0 Scripting Tools Reference Guide i

TABLE OFCONTENTS

AppBuilder 2.1.0 Scripting Tools Reference Guide

Table of Contents

1 TurboScripter Object Model Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

TurboScripter Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

TurboScripter Object Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

Repository Object Implements IRepo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Enti ty Object Implements ITSEnt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Relation Object Implements ITSRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Trace Object Implements Itrace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7Host Object - Implements IScriptUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8Child Script Object - Implements IScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8TurboHost Implements ITurboHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9CoDraw Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10CoPanel Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

Valid Domain Types and Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14CoCtrl Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17Attribute Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19

FAQs for Scripting Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19

2 Using TurboCycler Def ault Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Starting TurboCycler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1Selecting Generation Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Setting Up Generation Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3Generating Your Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Using Default Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Understanding Default Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4Developing the Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5CRUD Rules Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

GUI Rules/Windows Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8Uti li ties Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10Rename Views, Fields and Rules Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11RenameVeri fy Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11Hierarchy Cloner Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

TurboCycler Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Reviewing Forward Engineering and Transforming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14Generating with TurboCycler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17


4/183

ii AppBuilder 2.1.0 Scripting Tools Reference Guide

3 Using the TurboCycler Developer Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Creating a Generation Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Understanding the Generation Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1Customizing the Generation Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Edit ing and Compil ing a Template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Understanding the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Using the Command Line Compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3Using the Template Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Template Manager Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4Template Manager Work Area. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9

4 TurboCycler Template Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Flow Diagrams Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1Using Conventions and Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Reading a Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Inserting Multiple-line and Single-line Comments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Template Language Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3TEMPLATE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3USAGES Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5HIERARCHY Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6RULE Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9WINDOW Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12

Other Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16COMPONENT Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16FLATFILE Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16KEYWORDS Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17TEXT Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17USE ANY Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

DIALOG Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17Template Block Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

Declaring Local Variables from Any Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21Making Any Block a Callable Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21

Other Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23CALL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-23CALL SERVICE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24SELECT Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24APPEND and REMOVE Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25TRAVERSE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25UPDATE MESSAGE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27SHOWMESSAGE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27

SET Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28

Supporting Statements and Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-28Common Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29Conditional Expression (conditional_expr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31Integer Expression (int_expr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34List Expression (list_expr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36Object Expression (object_expr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-38String Expression (string_expr). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43


5/183


6/183

iv AppBuilder 2.1.0 Scripting Tools Reference Guide


7/183

AppBuilder 2.1.0 Scripting Tools Reference Guide 1-1

CHAPTER

1

TURBOSCRIPTER OBJECT M ODELREFERENCE


TurboScripter provides a scriptable repository interface that can be accessed from the AppBuilderConstruction Workbench or from other tools through COM. VBScript (VisualBasic) or JScript (Java)provide the required language functionality to access the properties and methods of these objects.

This guide contains information on using the scripting tools available in AppBuilder TurboScripter andTurboCycler. It begins with a discussion of TurboScripter and includes the necessary referenceinformation for using it. Because of the similarity to VisualBasic (VB) scripting, it does not includedetailed procedures.

The rest of the guide involves the use of the TurboCycler scripting tool. It begins with instructions onusing the TurboCycler Standard Edition default templates, followed by a description of the TurboCyclerDevelopers Kit, which you use to create your own templates. Use of this guide assumes user familiaritywith a scripting language.

To learn the details of the TurboScripter object model, read the TurboScripter Object Reference.

TurboScripter OverviewTurboScripter provides you with a mechanism to write scripts in VBScript or JavaScript that can accessthe repository, manipulate repository objects, and access other applications that function throughautomation, such as Microsoft Word. Tools within the Construction Workbench have menu options toinvoke TurboScripter and pass repository objects to it. The tools you use to build applications usingTurboScripter are documented throughout this manual.

Topics in this section include:

TurboScripter Object Reference

Valid Domain Types and Values

FAQs for Scripting Tools

Note If you are making a call to an Excel spreadsheet object, Excel must be running or you will get an error.

Note Installation of TurboScripter includes the installation of a number of sample scripts. When a particularobject is used in one of the sample scripts, that script is identified below.


8/183

1-2 TurboScripter Object Model Reference



The TurboScripter objects include:

Repository Object Implements IRepo

Entity Object Implements ITSEnt

Relation Object Implements ITSRel

Trace Object Implements Itrace

Host Object - Implements IScriptUtils

Child Script Object - Implements IScript

TurboHost Implements ITurboHost

CoDraw Object

CoPanel Object

CoCtrl Object

Attribute Object

Repository Object Implem ents IRepo

Query(String ObjectType, String PropName, String Pattern)

Queries the repository for Objects of type ObjectType with the property PropName that have the valuePattern. Returns a Dictionary object containing a list of TSEnt objects returned by the repository. Thislist is keyed by the index of the elements in the list starting from 0. Pattern can contain * as wildcard. Ifthe Property name is a Domained value, the Display Value in the repository model should be used.

Example:

REM *** Following query returns a Dictionary of TSEnt objects of type

REM *** VIEW that have names beginning with HPS

Set myViews = Repo.Query(VIEW, Name, HPS)

REM *** Following query returns a Dictionary of TSEnt objects of type

REM *** FIELD that have their Field_Type property set to 8

REM *** Field_Type is a Domain and Date is the Display Value

Set myDateFields = Repo.Query(FIELD, Field_Type, Date)

Sample: Query.vbs

Find(String ObjectType, String PropName, String Value)Returns the corresponding TSEnt Object. If more than one object matches the criteria, the first object isreturned. If the Property name is a Domained value, the Display Value in the repository model should beused. This is typically used to find a specific object whose unique property value is known.

Sample: Query.vbs


9/183



Get(String Type, String Name)

Returns the TSEnt object with the given Type and Name.

Sample: Query.vbs

Create(String Type, String Name, (optional)DictionaryProperties)

Returns the created object. If the TSEnt object already exists, the existing object is retr ieved andreturned. Display values can be used for Domained properties. To set the properties when creating anobject, fill in the Properties object with the Key as Property Name and Item as Property Value.

Sample: Create.vbs

Delete(String Type, String N ame)

Returns Nothing. Raises Error if the specified object is not found.

Sample: Create.vbs

Commit()

The entire session is committed. When called from the WorkBench, changes done by the other tools arealso committed.

Sample: Create.vbs

Rollback()The entire session is rolled back. When called from the WorkBench, changes done by the other tools arealso rol led back.

Sample: Create.vbs

GetEntityTypes()

Returns a Dictionary object containing all the entity types in the repository as strings. This list is keyedby the index starting from 0.

Sample: Model.vbs

Warning The script author should take care to ensure that objects that have been deleted before are notaccessed after the commit. This could destabilize the workbench.

Warning The script author should take care to ensure that objects that have been deleted beforeare not accessed after the rollback. This could destabilize the workbench.

Rollback does not remove all unwanted objects after cloning by TurboCycler.


10/183



GetRelationTypes()

Returns a Dictionary object containing all the relation types in the repository as strings. This list is keyedby the index of the elements in the li st starting from 0.

Sample: Model.vbs

GetPropertyNames(String ObjectType)

Returns a Dictionary object containing all the property names for this object type. This list is keyed bythe index of the elements in the list starting from 0.

Sample: Model.vbs

GetPropertyType(String ObjectType, String PropName)

Returns the property type as a String. The value is one of STRING, LONG, UNSIGNED_INT,DOMAIN or INTERNAL

Sample: Model.vbs

GetDomainValues(String ObjectType, String PropName)

Returns a Dictionary object containing all the valid Domain values for this property. This DictionaryObject contains the Storage Values of the domain elements as the Key and the Display Value (or UserValue) as the item. Returns an error for properties that do not have a Domain associated.

Sample: Model.vbs

Entit y Object Implements ITSEnt

GetPropertyNam e(String PropName)

Returns the required property as a Variant object. The only variable type in VBScript. The PropNameneeds to be a valid property of this repository object type as published in the repository model.

Sample: Query.vbs

SetProperty(String PropName, Variant PropValue)

Sets the property specified by PropName to the value in PropValue. Returns nothing. Raises an Error ifthe property is invalid or the value is invalid. For properties that have a domain associated with them,

the Display value (or User Value) needs to be specified and NOT the storage value

Sample: Hierarch.vbs


11/183



CreateChild(String Type, String Nam e, String RelationType,(optional) Dictionary Properties, (optional) DictionaryRelationProperties)

Creates a child object of the specified Type and Name. The Propert ies Dictionary can contain theproperties of the child object while the RelationPropert ies Dictionary can contain the propert ies of therelation, for example, Sequence Number of the relation. If the specified object already exists in therepository, this method returns the retrieved object.

Sample: Hierarch.vbs

GetChild(String Type, String Nam e, String RelationType)

Returns an Enti ty Object (TSEnt) that i s a child of the call ing object.

GetChildren(String Type, St ring RelationType, (optional)Dictionary RelationObjects)

Returns a Dictionary object containing the child objects (TSEnt) of the specified type. The indices for

these objects are from 0 to (Count 1). If the RelationObjects is a valid Dictionary, then the Relationobject (TSRel) for each of the corresponding child objects wil l be fi lled in.

GetParent s(String Type, St ring RelationType, (optional)Dictionary RelationObjects)

Returns a Dictionary object containing the parent objects(TSEnt) of the specified type. The indices forthese objects are from 0 to (Count 1). If the RelationObjects is a valid Dictionary, then the Relationobject (TSRel) for each of the corresponding child objects will be filled into RelationObjects. Use thesame key value to access the child object as well as the relation object for that child.

Sample: Rename.vbs

GetType()

Returns the Object Type name of this object as a String.

Sample: gettype.vbs

GetFile(Integer FileType)

Returns the File associated with this object. Valid values for File Type are given below.

Example:If this is a Rule object, then GetFile(7) wil l return the source fi le for this rule as a string.0(RepoText) is a valid file type for all Entity (TSEnt) and Relation (TSRel) objects.1(RepoKeywords) is a valid file type for all TSEnt objects.

Sample: Rename.vbs

Table 1-1 File Type Values

RepoKeywords = 0 RepoText = 1

WindowPanel = 2 ReportSection = 3


12/183



SetFile(Integer FileType, St ring FileStr)

Sets the file associated with this object in the repository to FileStr. This can be used to create RuleSource(Value = 7) files from RULE objects and RepoText(0) and RepoKeywords(1) files from all Entity objects(TSEnt).

Sample: Rename.vbs

DeleteChildRelation(String ChildType, String ChildName,(optional) String RelType)

Deletes the Relation between this Entity object (TSEnt) and the child object identified by ChildType andChildName. If this object and the Child object are connected by more than one type of relation, then theRelType needs to be specified.

DeleteParentRelation(String ParentType, St ring ParentName,(optional) String RelType)

Deletes the Relation between this Entity object (TSEnt) and the parent object identified by ParentTypeand ParentName. If this object and the parent object are connected by more than one type of relation,

then the RelType needs to be specified.

Properties implemented by TSEnt

TSEnt does not have any static properties of its own. It assumes all the valid properties of the repositoryobject that it represents.

Example:

Get the Field_Type property of myField

Set myField = Repo.Get(FIELD, RETURN_CODE)

MyFieldType = myField.Field_Type

Relation Object Implement s ITSRel

GetProperty(String PropNam e)

Returns the required property as a Variant object. The only variable type in VBScript. The PropNameneeds to be a valid property of this repository object type as published in the repository model.

Sample: AddTo Folder.vbs

PhysicalBitmap = 4 DrawingFile = 5

ReportFile = 6 RuleSource = 7

ComponentSource = 8 WindowHelp = 9

DatabaseOptions = 10 ServerOptions = 11

MachineOptions = 12 FormContents = 13

MigrationFile = 14 ClosureScope = 15

ApplicationFolder = 16 ComponentFolderFile = 17

Table 1-1 File Type Values (Continued)


13/183



SetProperty(String PropName, Variant PropValue)

Sets the property specified by PropName to the value in propValue. Returns nothing. Raises an Error ifthe property is invalid or the value is invalid. For properties that have a domain associated with them,the Display value (or User Value) needs to be specified and NOT the storage value

Sample: hierarch.vbs

GetType()

Returns the Relation Type name of this relation as a String.

Sample : gettype.vbs

GetFile(Integer FileType)

Returns the File associated with this object.

Sample : ExtraceFromFolder.vbs

Example: I f this is a COMPONENT_FOLDER_CONTENT object, then GetFile(17) will return thecomponent folder file for this relation object as a string if it is a text file.

SetFile(Integer FileType, St ring FileStr)

Sets the file associated with this object in the repository to FileStr. This can be used to createComponentFolderFile fi les from COMPONENT_FOLDER_CONTENT relation. When retr ievingComponent Folder files, only text files can be retrieved, binary files cannot be retrieved.

Sample : rename.vbs

Trace Object Implem ents Itrace

OutFile

An integer constant that specifies the name of the file to which all trace outputs should be written to.If the file already exists, the existing fi le is deleted and a new file of the same name is opened. To save anexisting trace file, get the OutFileproperty, create a FileSystemObjectwith this name and save it toanother filename. The value of the OutFileproperty is ini tiali zed to the value of the key in the registr y.

HKEY_LOCAL_MACHINE\SOFTWARE\Level 8\Geneva AppBuilder\2.0\IDWB\

SCRIPTING\TURBO SCRIPTER\Trace_File

If there is an invalid value in the registry, then the OutFileproperty is assigned to ts.outin the currentdirectory.

Level

A integer property that specifies the severity of the messages that need to be written to the trace fi le. Thevalid values are:


14/183



TRACE_EXECUTION, TRACE_DEBUG, and TRACE_ALL are integer constants defined in the TSATLtype library. Any other numeric value above 2 is the same as setting the value to 2.

Host Object - Implements IScriptUtils

CreateScript(String FileName, String Language)

Returns a Script object that is initialized to have the same environment as the calling script. This call isused to create a new script object that can be executed from inside this script. The new child script canbe executed by calling the method Run() on the returned Script Object.

Child Script Object - Implements IScript

Run( )

Executes the Child Script object in the same environment as the parent script. This method raises anError i f the execution of the script fails.

Sample: AddToFolder.vbs

AddInputObject(String Type, St ring Nam e)

Adds the repository object specified by Type and Name to the InputObject Dictionary of this child scriptobject.

AddTypeLib(Str ing TypelibID, Long M ajorVersion,Long MinorVersion, (optional) Long Flags)

Adds the specified TypeLibrary to the scope of this script object. Any constants defined in theTypeLibrary can now be used within the script.

AddTopLevelObject(String N ame, Object TopObject)

Adds the specified ActiveX Object to the list of Top Level objects for this script. The script can access theobject using the Name parameter.

Table 1-2 Trace Levels

Numeric

Value Integer Constants Trace File Contents

0 TRACE_EXECUTION Trace errors

1 TRACE_DEBUG Trace errors and informational messages

2 TRACE_ALLTrace detailed error and information messages

Note that this value significantly impacts performance.


15/183



TurboHost Implements ITurboHost

The TurboHost object implements the functionality required to host the scripting engine and serves asthe entry point to the Repo, Script and Trace Objects. The methods and properties of this object can beused from other applications like VB that support COM and are not for use from inside a script.

RepoInit(String RepositoryName, String UserName,String Password)

Connects to the specified repository and returns the repository object. This object is a must to either runscripts or work wi th any repository objects directly.

ScriptRun(String ScriptFileName, String Language,Dictionary InputObjects, Long WindowHandle, (optional)Dict ionary TopLevelObjects)

Executes the specified script. Returns an error on failure. VBScript and JScript are the currentlysupported languages. The Window Handle can be 0 in which case, the handle of the currently active

window will be used. The TopLevelObjects Dictionary contains ActiveX objects keyed by their name.These objects can be used from inside a script just like the default Top Level Objects like Trace orRepo.

ScriptletRun(String ScriptContents, String Language,Dictionary InputObjects, Long WindowHandle, (optional)Dict ionary TopLevelObjects)

Works the same way as ScriptRun except that a string containing the script is passed instead of the filename. This is useful when scripts are generated on the fly by an application.

ScriptSelectAndRun(Dictionary InputObjects,

Long WindowHandle)This method brings up a dialog box containing the scripts in the directory specified in the registr y. Thisdialog also shows the scripts present in the TScripts Component Folder. You can then select the scriptyou want to be executed.

ScriptInit(String ScriptFileName, String Language)

This method returns the Script Object that is initialized to the file name and language specified. Oncethis object is obtained, methods to add input objects, to add top-level objects, and to execute the scriptcan be called.


16/183



Top-level objects added by TurboScripter to the scope of all scripts:

Repository Object Implements IRepoRepository Object for querying, creating or deleting objects in the repository

Trace Object Implements ItraceTrace Object to get and set the trace file and trace level

Host Object - Implements IScriptUtilsHost Object to enable creating a child script

Input or Entity Object Implements ITSEntDictionary object that contains the input Entity objects (TSEnt). Sample:Rename.vbs.

CoDraw Object

The CoDraw Object provides access to Drawing Objects stored in the repository. Currently only readaccess is allowed. From VB or TurboScripts, Drawing Objects can be accessed by callingCreateObject(CoDrawFile.CoDrawFile). This returns the created ICoDrawfile object which can be

used to perform read operations on the drawing.

Open(String Draw ingName, St ring Draw ingType)

Retrieves the specified drawing object and opens it for reading. The DrawingName is the name of theDrawing object. The DrawingType is the value in the Drawing_Type property of this object. Since theDrawing_Type property can only have values from the Drawing_Type domain, the Display value needsto be specified.

Sample: Draw.vbs

GetAllRepoObjects()

Retrieves all the repository objects in the drawing and returns a Dictionary object that contains these asEntity objects (TSEnt).

Sample: Draw.vbs

GetRepoObjects(String Type)

Retrieves the repository objects of the specified Type in the drawing and returns a Dictionary object thatcontains these as TSEnt objects.

Sample: Draw.vbs

Note The CoDraw object reflects the state of the Drawing Object as it is in the repository. If changes are made tothe drawing file from the workbench, these changes need to be committed before the CoDraw Object isopened.


17/183



CoPanel Object

The CoPanel object provides COM/OLE Automation-based access to the various controls and theirproperties. It allows a TurboScript to create, read, update and delete the controls and their properties.They include:

CoPanel Object Control Types

CoPanel Object Colors

CoPanel Object GUI Types

Table 1-3 CoPanel Object Control Types

Control Type Constant

1. CHARTWINDOW ctrlChart

2. CHECKBOX ctrlCheckbox

3. COMBOBOX ctrlCombobox

4. EDITFIELD ctrlEditfield5

5. ELLIPSE ctrlEllipse

6. GROUPBOX ctrlGroupbox

7. HOTSPOT ctrlHotspot

8. LISTBOX ctrlListbox

9. MULTILINEEDIT ctrlMultiLineEdit

10. OLECONTROL ctrlActiveX

11. PUSHBUTTON ctrlPushbutton

12. RADIOBUTTON ctrlRadiobutton

13. RECTANGLE ctrlRectangle

14. SPREADSHEET ctrlMCLB

15. STATICTEXT ctrlStatictext

16. BITMAP ctrlBitmap17. MENU ctrlMenu

18. SUBMENU ctrlSubMenu

19. MENUITEM ctrlMenuItem

20. SEPARATOR ctrlMenuSeparator

21. CELL ctrlCell

22. CELLFIELD ctrlCellField

23. CELLTEXT ctrlCellText

24. XDATA ctrlXData

25. YDATA ctrlYData

26. FOOTINGTEXT ctrlFootingText

27. LEFTMARGINTEXT ctrlLeftMarginText

28. RIGHTMARGINTEXT ctrlRightMarginText

29. HEADINGTEXT ctrlHeadingText


18/183



New Panel(GUIType gui, St ring f ilename)

Creates a new panel of the specified type. The object is created in the repository only after Commit iscalled. This call needs to be called before adding any controls to the panel.

Filename is an optional parameter used to initialize a panel from a template.

Sample: pnl_crt.vbs

OpenPanel(String winName, String winLanguage, GUIType gui)

Opens an existing panel in the repository. The default value for language is .

Sample: pnl_read.vbs

AddControl(ControlType control_type)

Adds a new control of the specified control_type to the panel and returns a Control Object.

Table 1-4 CoPanel Object Colors

Color

1. Default

2. Black

3. White

4. DarkGray

5. Gray

6. LightGray

7. DarkBlue

9. DarkGreen

10. Green

11. DarkCyan

12. Cyan

13. DarkRed

14. Red

15. DarkMagenta16. Magenta

17. DarkYellow

18. Yellow

19. Pink

20. Brown

Table 1-5 CoPanel Object GUI Types

GUI Type

IBM_3270

Workstation

HTML

Note Some functions below have Language parameter. It is introduced for future use.


19/183



Sample: pnl_crt.vbs

AddAtt ribute(String At trbuteName)

Adds the specified attribute to the Panel object and returns the Attribute Object. This method is calledwhen a new attribute that is not in the current Window Model needs to be added to the panel.

DeleteAtt ribute(String A tt ributeName)

Deletes the specified attribute from the Panel object. This can be done for attributes that are currently inthe Window Model, as well as new ones added by the user.

GetAtt ribute(String At tributeName)

Returns the Att ribute Object for the specified att ribute.


DeleteControl(Control ct rl)Deletes the control specified by the ctrl object from the panel

Commit (String WindowN ame, St ring Language)

Saves the panel object in the repository. For new panels, if a panel with the same GUI and language existsunder the WindowName, an error is returned. The panel is updated if an existing panel is opened,updated and committed.

Sample: pnl_crt.vbs

GetAllAttributes()Returns a Dictionary object containing a list of all the Attribute Objects for this panel.

Rollback()

Rolls back all changes made to the panel and returns it to the NewPanel or OpenPanel state.

GetAllControls()

Returns a Dictionary object with a list of all the controls in the panel.

SaveToFile(String PanelFileName, String HelpFileNam e)

Saves the panel to a file named PanelFileName and the help to HelpFileName.

GetDomainValues(String Type)

Given a Domain Type, this call returns a dictionary object containing all the values in the domain.

Refer to the Valid Domain Types and Values.


20/183



GetLanguage()

Retrieves that language property for the current panel object.

SetLanguage(String Language, Boolean overw rite)

Set the language property for the panel. If overwrite is TRUE, the panel will replace an existing panel ofthat language if it already exists.

Paste(VARIANT objects)

Adds objects, supplied in panel fi le format, to the panel. Returns a Dictionary object with a list of thecontrols that were added.

GetDomainTypes()

GetDomainTypes() returns a dictionary of domain type strings.

GetDomainValues()

GetDomainValues() returns a dictionary of values for a given domain type.

These methods are used together to provide Window Painter the valid attribute values for a givenattribute. These values are contained in the Window Painter model.

Refer to the Valid Domain Types and Values.


Here is a list of the current domain types and values used in GetDomainTypes()andGetDomainValues(String Type).The supported values for each type is provided in the linked subtopic.

COUNTRY

Table 1-6 Domain Types and Values

COUNTRY BORDER_TYPE

COORDTYPE FONT

JUSTIFICATION CHARTTYPE

FORMAT STYLE

COLOR STYLE_3270

HSCROLL SELECTIONTYPE

VSCROLL DRAWLINES

Table 1-7 Country Values

SYSTEM ALBANIA

ARGENTINA AUSTRALIA

AUSTRIA BELGIUM


21/183



COORDTYPE

JUSTIFICATION

FORMAT

COLOR

BRAZIL CANADA_ENGLISH

CANADA_FRENCH CHINA

CZECHOSLOVAKIA DENMARK

FINLAND FRANCE

GERMANY GREECE

HUNGARY ICELAND

ITALY JAPAN

NETHERLANDS NEW_ZEALAND

NORWAY POLAND

PORTUGAL ROMANIA

SOUTH_AFRICA SOUTH_KOREA

SPAIN SWEDEN

SWITZERLAND TAIWAN

THAILAND THAILAND_BUDDHIST

TURKEY UNITED_KINGDOM

UNITED_STATES YUGOSLAVIA

CHAR PIXEL

LEFT RIGHT

CASEENTERED UPPER

LOWER FIRSTUPPER

ALLFIRSTUPPER

CUSTOM DEFAULT_COLOR

BLACK WHITE

DARKGRAY GRAY

LIGHTGRAY DARKBLUE

BLUE DARKGREEN

GREEN DARKCYAN

Table 1-7 Country Values


22/183



HSCROLL

VSCROLL

BORDER_TYPE

FONT

CYAN DARKRED

RED DARKMAGENTA

MAGENTA DARKYELLOW

YELLOW PINK

BROWN

SHOW_ALWAYS SHOW_NEVER

SHOW_AS_NEEDED

SHOW_ALWAYS SHOW_NEVER

SHOW_AS_NEEDED

BORDER_NONE BORDER_SIZEABLE

BORDER_DIALOG

CUSTOM SYSTEMFONT8

MODERN8 MODERN10

MODERN12 ROMAN8

ROMAN10 ROMAN12

ROMAN14 ROMAN18

ROMAN24 SWISS8

SWISS10 SWISS12

SWISS14 SWISS18

SWISS24


23/183



CHARTTYPE

STYLE

STYLE_3270

SELECTIONTYPE

DRAWLINES

CoCtrl Object

GetAllAttributes()

Returns a Dictionary object containing a list of all the Attribute Objects for this control.

AddAtt ribute(String At trbuteName)

Adds the specified attribute to the Panel object and returns the Attribute Object. This method is calledwhen a new attribute that is not in the current Window Model needs to be added to the panel.

LINECHART2D BARCHART2D

PIECHART2D STACKEDBARCHART2D

COLUMNCHART2D SMOOTHLINECHART2D

SCATTERCHART2D AREACHART2DBARLINECHART2D HILOWCLOSE2D

CANDLE2D POINTANDFIG2D

LINECHART3D BARCHART3D

PIECHART3D STACKEDBARCHART3D

COLUMNCHART3D AREACHART3D

PERBARCHART3D BARLINECHART3D

DROPDOWN DROPDOWNLIST

SIMPLE

DROPDOWN DROPDOWNLIST

SINGLE MULTIPLE

EXTENDED

NOLINES VLINES

HLINES VHLINES


24/183



GetAtt ribute(String A tt ributeName)

Returns the Att ribute Object for the specified att ribute.


GetType()Returns the ControlType constant (defined above) that specifies this controls type

Sample: pnl_read

DeleteAtt ribute(String A tt ributeName)

Deletes the specified attr ibute from this control. This can be done for att ributes that are curently in theWindow Model as well as new ones added by the user.

GetContents()

Returns a Dictionary Object containing the controls that are embedded in this control. Fails if nocontrols are present.

AddControl(ControlType type)

A control of ControlType type is added to this control.

Sample: pnl_crt.vbs

DeleteControl(Control ct rl)

Deletes the Control specified by ctr l from this control.

DeleteContents()

Deletes all embedded controls in this control.

ChangeParent(IcoCtrl * old, IcoCtrl * new )

Changes a control objects parent.

ChangeType()

Modifies the control type.

Copy()

Creates a SAFEARRAY of BYTEs that correspond to the panel file format for the control.


25/183



At tribute Object

set_Value(VARIANT val)

Sets the Value of this attribute to that specified by val. All variables in VBScript are of type VARIANTwhich is a generic type for all other supported types. This method would be successful as long as the

value is of the right type, for example, String, Integer etc.

Sample: pnl_crt.vbs

get_Value()

Returns the value of the att ribute. If the att ribute is a compound attribute, like Font or Color, then thisvalue would contain an object like Font or Color.

Sample: pnl_crt.vbs

get_Name()

Returns the name of this att ribute


DeleteAttribute()

Removes this attribute from the parent control.

Font Object and Color Object

These are compound attributes and can be treated like a sub-control, since they contain the samemethods that characterize a control object. They have attributes that can be accessed through

GetAllAtt ributes or GetAtt ribute(Str ing AttributeName).

FAQs for Script ing Tools

Frequently asked questions include:

How does a VBScript or JavaScript access the repository?

How can I access the properties of an entity or relation object?

Can I invoke other scripts from a currently executing script?

How do I manipulate or create windows and controls within the windows ?

How do I access drawing files in the Freeway repository?

Can I access the repository from VB?

What is a Dictionary Object that is used ubiquitously in TurboScripter methods?


26/183



How do I obtain a relation object between two objects?

How do I create or modify files under a Component_Folder?

Where do I look for Trace information about a TurboScripter session?

How does a VBScript or JavaScript access the repository?

Scripts in TurboScripter access the repository through the Repo object. Repository objects can bequeried (for example, Repo.Query(FIELD, RETURN_CODE) or created (for example,:Repo.Create( RULE, TS_SAMPLE) from a Repo object. These repository objects are returned asTSEnt objects for entities and TSRel objects for Relations.

How can I access the properties of an ent ity or relation object?

You can get and set properties of an object using GetPropertyorSetProperty. For example, youcould usemyObj.GetProperty(Name)or myRel.SetProperty(Sequence_Number). The

property names used in these methods need to be valid property names according to the Workgrouprepository model. You can get a list of enti ties, relations and their property names by running the samplescript Model.vbs shipped with TurboScripter.

Or you can use the Object.Propertynotation to access the properties of an object. For example,objName = myObj.Name, myRel.Sequence_Number = n.

Can I invoke other scripts from a currently executing script?

Yes. You callHost.CreateScript(ScriptFileName , Language). This creates a new script

object and initializes it to the current environment. Once this is done, you can pass repository objects tothe script by call ingAddInputObjecton the new script object. The new script is executed by callingthe Runmethod.

How do I manipulate or create w indows and controlswi thin the windows ?

You can create, update, read and delete controls within a window through the CoPanel Object. TheCoPanel Object exposes the controls and attributes of the window stored in a panel fi le. The samplescripts pnl_read.vbs , pnl_crt.vbs demonstrate access panel objects/files.

How do I access drawing files in the Freeway repository?

Currently, VBScripts or JScripts can read the repository objects stored within a drawing file. This is donethrough the CoDraw object. The sample script draw.vbs demonstrates how to access an EntityRelationship Drawing (ERD) and retrieve the repository objects within the drawing. Please note that thedrawing file is retrieved from the repository and may not reflect uncommitted changes made to that filein the workbench.

Note The Freeway Service Manager module, gresvcnt.exe, must be running before you can connect to apersonal repository via TurboScripter.

Note The object and property names may differ from those in TurboCycler documentation. TurboScripter usesthe exact names defined by the Workgroup repository.


27/183



Can I access the repository f rom V B?

Yes, you can access the repository from VB or any other tool that supports COM. You need to create theTurboHost object either through the CreateObject method or by declaring a variable of type TurboHost.To declare a variable you first need to add the TSATL library to the references for the VB project. Oncethe TurboHost object has been successfully created, call RepoInit on this object to establish a repositorysession. This method returns the Repo object on success. Now, you can create or query objects from the

repository and manipulate just as you would from a script. The sample project VB_TSRepo shippedwith TurboScripter demonstrates this.

How do I access repository objects passed from theConstruction Workbench?

You can access the InputObject Dictionary object that contains the list of repository objects passed bythe Workbench. This Dictionary has a 0 based index as its key and TSEnt objects as the items.

Can I select a project f or Construct ion Workbench fromTurboScripter?

No, the FWY API does not support this action. From VB, you can access the currently active projectonly. Prior to accessing the repository from VB, you must select an active project from the Workbench orFreeway Explorer. Because a repository session is associated with a project, changing the active projectrequires closing and reopening the session.

What is a Dict ionary Object that is used ubiquitouslyin TurboScripter methods?

The Dictionary Object is a container type created by Microsoft that contains a list of Key, Item pairs. Inmost cases, TurboScripter uses the Key as a zero based index and the item contains the actual value thatis contained. Further information about the Dictionary object is available at the Microsoft Web site or inVBScript documentation.

Example:

REM ** Create a Dictionary object to set the properties of an object

on creation

Set myProps = CreateObject(Scripting.Dictionary)

REM ** The property name is the KEY and the value is the ITEM

MyProps.Add(Field_Type, Small Integer or Integer)

MyProps.Add(Fld_Len, 15)

Set myObj = Repo.Create(FIELD, TS_TEST, MyProps)

How do I obtain a relation object betw een tw o objects?

When calling GetChildren or GetParents, pass in an empty Dictionary Object as the third parameterwhich is optional. When the call returns, this object will contain the relations corresponding to thechildren for the same Key value. (The Relation for the fi rst Child object in the returned Children objectwill be the first element in the Relations object, Relation for the second child will be the second elementin the Relations object and so on.)


28/183



How do I create or modify files under a Component_Folder?

If the Component_Folder does not exist, create a Component_Folder object using Repo.Create. Nowcreate a child of type WEAK_ENTITY via the relation COMPONENT_FOLDER_CONTENT. Setthe PathName property of the COMPONENT_FOLDER_CONTENT relation to the full path name ofthe file you want to store in the repository. Now call SetFile method on the Relation object passing in thetext string containing the fi le contents and the type which is 17(ComponentFolderFile).

Where do I look for Trace informat ion about aTurboScripter session?

The Trace file name and path are determined by the Registry settings for Trace_File under theTurboScripter Key. You can also select Tools > TurboScripter(CTRL+ALT+B) and clicking Optionsinthe Script Select window. A hierarchy object must be selected for the TurboScripter menu item to beavailable. By default it is set to ts.outin the AppBuilder\AD\TSCRIPTS directory. The amount ofinformation in this fi le is dependent on the TRACE LEVEL sett ings in the Options dialog. If you are

debugging a script, you can set this value to DEBUG, however, performance may be effected.

Note As of version 5.0 of VBScript and JScript, binary files are not supported. This restricts the use ofTurboScripter to Text files.


29/183


CHAPTER

2

USING TURBOCYCLERDEFAU LT TEM PLATES


The TurboCycler product is a productivity tool that generates repository objects from other objects inthe repository. The TurboCycler process improves productivity by automating repetitive tasks in thesoftware development lifecycle.

TurboCycler Standard Edition, when combined with the TurboCycler Developers Kit, provides an openarchitecture that lets you generate objects suitable to any development platform and methodology. Thistopic explains the TurboCycler generation process as it applies to the AppBuilder development

environment and i llustrates this process through the functions of the Standard Edition defaulttemplates. This section describes:

Starting TurboCycler how to access TurboCycler from tools in the Construction Workbench

Using Default Templates how to use the predefined templates provided with the product

TurboCycler Tutorial how to use a sample application using TurboCycler

To better understand the generation possibilities of TurboCycler, refer to Chapter 3, Using theTurboCycler Developer Kit .

Starting TurboCyclerWhen TurboCycler is installed, you can access it from the following application development tools:

Database Diagrammer

Enti ty Relationship Diagrammer

Matrix Builder

Process Dependency Diagrammer

State Transition Diagrammer

Window Flow Diagrammer

Select Newor Openand choose the development tool. When the tool window opens, selectAnalysis>TurboCycler.

From Construction Workbench, select an object in the hierarchy and select Tools>TurboCycler.


30/183

2-2 Using TurboCycler Default Templates

Starting TurboCycler

Review the following sections for information about starting TurboCycler:

Selecting Generation Templates

Setting Up Generation Templates

Generating Your Application

Selecting Generation Templates

Access TurboCycler from Construction Workbench using the following procedure.

Procedure - Accessing TurboCycler from Construction Workbench

1. Select Start > Programs > AppBuilder > Construction Workbench.

2. Open a project and select an object within the project or query for an object. Select Tools >TurboCycler. The TurboCyclerSelect Generation Templates window opens (Figure 2-1).

Figure 2-1 TurboCyclerSelect Generation Templates window

3. The Selected Templates and Available Templates list boxes display templates you can use with theselected object type (in Figure 2-1, the object type is Function).

4. Select the templates you want to use with the Addand Removebuttons.

Figure 2-2 Selecting a Template in TurboCycler

If you add additional templates, alter the default templates, or create new templates (using theTurboCycler Developers Kit) , the objects you have created will be available through the queryoption.

5. Select Generate, Setup Templates,or Cancel. Generatestarts the generation process. SetupTemplatesdisplays a window where you select the modules you want to generate (see Setting UpGeneration Templatesbelow). Cancelreturns you to the previous window.

Note You can also right-click the mouse to select TurboCycler.


31/183

Starting TurboCycler


Sett ing Up Generation Templates

To set up your generation template follow the procedure outlined below.

Procedure - Setting up Templates

1. Select Setup Templates. The TurboCycler Generation Template Setup window opens (Figure 2-3).

This window lets you specify precisely what output you want TurboCycler to generate (for example,whether the application should perform an SQL update or an SQL insert, or both) These outputchoices are called modules.

Figure 2-3 Generation Template Setup Window

2. The Object Type list box displays the repository object type and the Generation Templates list boxlists templates for that object type (Figure 2-4). The text in the Template Description box describesthe selected template. The Selected Modules and Available Modules list boxes identify the availablemodules for this object type/template combination. Select the modules you wish to generate with

the Addand Removebuttons.

Figure 2-4 Generation Template Selection

Generating Your Application

After you select the appropriate modules, proceed with the generation as described in the followingprocedure.


32/183


Using Default Templates

Procedure - Generating the Application

1. Select theGeneratebutton in the Select Generation Templates window to start the TurboCyclerprocess.

2. The Rename Object window opens (Figure 2-5).

Figure 2-5 Rename Object Window

During the generation process, a status window notifies you of the generations progress.

3. Select theCancelbutton to stop TurboCycler between modules. You can review the results of theTurboCycler process after completion.


This topic includes:

Understanding Default Templates

Developing the Application

And information about using these default templates:

CRUD Rules Template

GUI Rules/Windows Template

Utilities Template

Rename Views, Fields and Rules Template

RenameVerify Template

Hierarchy Cloner Template

Understanding Def ault Templates

TurboCycler software includes a set of six default templates. You can generate a fully functional referencetable application using all of the six templates. The default templates specify part of the TurboCycler

Caution The TurboCycler process generates objects using names defined by the templates for the objects youselect. If you run TurboCycler more than once, previously generated objects with modifications arereplaced by newly generated objects. Because of this, you must carefully examine the objects

created by a generation. To validate the generation results and make sure that no desired user

modifications have been lost, examine the hierarchy, rule, and window objects. If you are not pleasedwith the results of a generation process, you can roll back the session changes from the Construction

Workbench.


33/183



output and make modifications easier. The default templates are designed for the single byte characters.For templates using 'Str ing Manipulation function' in DBCS environment, you need to modify thedefault templates.

CRUD Rules Template,includes SQL statements (Create, Read, Update, and Delete database accessoperations)

GUI Rules/Windows Template, supplies graphical interface event-handling procedures

Utilities Template, contains message-handling procedures used by generated objects

Rename Views, Fields and Rules Template,modi fies the source of any rules that refer to a renamedFIELD or VIEW object

RenameVerify Template, shows the rules in the repository that need to be modified if the name ofthe selected object is changed

Hierarchy Cloner Template,creates a new hierarchy of repository objects based on an existinghierarchy

The TurboCycler process uses the default templates to create output objects with fully-coded rulesincluding calls to system components as needed, painted windows with predefined styles, and view and

field physical data structures. These objects are automatically related in a logical hierarchy in therepository.

Using Default Templatesdescribes how to use the default templates. It details the output objects thetemplates generate and defines the specific rules, windows, and hierarchies generated by each defaulttemplate.

The source code for each of these templates is included in the TurboCycler Developers Kit. Two sourcecode samples are included in Template Samples on page4-52

Using the default templates, you can generate a functional application, including complete functionhierarchies, detail and list windows, database access rules, and standard utili ties. You can writegeneration templates to automate an unlimited number of processes in the development lifecycle. Youcan also wr ite templates to customize processes like forward engineering, transformation, reverseengineering, and any other process that generates objects in the repository from other repository objects.

Developing the ApplicationBefore starting TurboCycler, perform the usual Construction Workbench modeling steps as follows:

1. Create an enti ty relationship diagram (ERD)

2. Forward engineer the ERD into a database diagram (DBD)

3. Transform the DBD into a hierarchy diagram (HD)

Note Two or more users should not run TurboCycler templates that create and update the same repositoryobjects. This is true for objects that are sent through TurboCycler as well as other objects that the template

may access to update or create. For example, the CRUD template uses common fields and views that areirrespective of the ERD on which it is applied. These fields and views are reused once they have beencreated. If two users run the CRUD template at the same time, the first user locks the common field and

the other users cannot access it, leading to an error message Object exists in the repository in anUncommitted State.


34/183



Step 1 establishes the ERD as a logical model that consists of entities, relationships, properties,identifiers, and data types. In step 2, forward engineering creates a relational model containing tables,keys, and columns. Step 3 is the transformation to a structural model of files, views, and fields.

These steps populate the repository with the information TurboCycler needs to generate a reference-table application. Without TurboCycler, developing applications using these objects requires you towrite rules code yourself to reflect the model.

Encountering Errors

If TurboCycler encounters a repositor y error or other errors that are specific to an object, a message isdisplayed.

If Error is encountered, TurboCycler will stop processing until the error is corrected.

CRUD Rules Template

You can generate CRUD rules (Create, Read, Update, Delete) for any existing file hierarchy in therepository. Because of the traceabil ity information stored in the repository during forward engineeringand transformation, four object types in the repository (files, tables, entities, and many-to-manyrelationships) can generate CRUD rules. If you want to generate CRUD rules from non-file objects, youmust perform the appropriate forward engineering and transformation steps before the generationprocess, or an error message appears.

The CRUD Rules template contains six modules:

Clone Data View Module

SQL Delete Rule Module

SQL Fetch Rule Module

SQL Insert Rule Module

SQL Select Rule Module

SQL Update Rule Module

Clone Data View M odule

Clone Data View creates a view in the repository. The view name is the name of the file (for long filenames, truncated to a maximum of 19 single-byte characters or 8 DBCS characters), plus the suffix

_CDV. This view contains, as its children, all of the fields included in the file data view. AssortedCRUD rules and some GUI rules and windows use the cloned data view to avoid problems of hierarchyambiguity. Figure 2-6shows a generated clone data view and the corresponding file data view.


35/183



Figure 2-6 Generated Clone Data View with its Corresponding Data View

SQL Delete Rule Module

SQL Delete Rule creates a rule with appropriate input view, output view, and rules code that handlesrecord deletion in the table specified by the file implementation name. It determines which file to deletethe record from by the primary key view mapped to its input view. An SQL code is returned from thedelete operation. Figure 2-7shows an example of a delete rule hierarchy.

Figure 2-7 Delete Rule Hierarchy

SQL Fetch Rule Module

SQL Fetch Rule creates a rule with appropriate input view, output view, and rules code. This rule fetchesrecords from the table specified by the file implementation name. The fetch rule is compatible withsmooth scrolling techniques through the use of the NUMBER_OF_RECORDS field in the input view.For each fetch, 50 occurrences of records are fetched according to the parameters mapped to the primarykey view, cloned data view, and FETCH_TYPE field in the rule input view.

You can specify the FETCH_TYPE as blank (which defines a fetch for all records whose key is greaterthan or equal to the key mapped to the input view) or as D (which defines a fetch using a LIKE clauseagainst all fields in the key). The fetch rule returns and maps the SQL code to the field RETURN_CODEif an SQL error occurs. The number of records fetched is returned to the NUMBER_OF_RECORDSfield and all fetched records are returned to the occurring cloned data view in the output view.

SQL Insert Rule M odule

SQL Insert Rule creates a rule with appropriate input view, output view, and rules code. This rule insertsa record in the table specified by the file implementation name. It inserts the record mapped to the

cloned data view of its input view and returns the SQL code from the insert operation.

SQL Select Rule Module

SQL Select Rule creates a rule with appropriate input view, output view, and rules code. This rule selectsa record by primary key from the table specified by the file implementation name. It uses the primarykey mapped to its input view to select a single record in the database table and returns the contents of therecord in the cloned data view of the output view. It returns the SQL code from the select operation.


36/183



SQL Update Rule Module

SQL Update Rule creates a rule with appropriate input view, output view, and rules code. This rulehandles updates to a database record selected by the primary key in the table specified by the fileimplementation name. It sets all fields of the record of the table to the values mapped to the cloned dataview of the rule input view. It returns the SQL code from the update operation.

GUI Rules/Window s Templat e

You can generate GUI rules and windows for any forward engineered and transformed entity hierarchyin the repository. The GUI Rules/Windows template extracts information already defined in the logical,relational, and structural models of the repository. This template uses traceability information definedduring forward engineering and transformation to generate GUI rules and windows from four objecttypes in the repository (entities, many-to-many relations, tables, and files). If any object of these typesdoes not have the required traceability information, you cannot use this template to generate GUI rulesand windows for that object and an error message is displayed.

The GUI Rules/Windows Template contains the following modules:

Detail Display Module

Display Driver Module

Browse Display Module

List Display Module

Query Display Module

Logical Driver Module

Det ail Display Module

Detail Display creates both a rule and a window (with appropriate hierarchies that have references to setsand components) for each entity you specify. This rule and window display data details in yourapplications interface. They display information and allow standard record maintenance (create, read,update and delete). The detail display window usually allows end users to edit all fields in the data view.

The hierarchy you generate for a kernel entity is different than the one for a non-kernel entity. The detaildisplay for a kernel enti ty is an entry point (that i s, a menu choice in the AppBuilder ApplicationExecution menu) into the generated application; therefore, a function and process are generated forevery kernel entity. Because the detail display rule for a kernel entity is the root rule for the generatedprocess, it contains no input or output view. A kernel entity detail display also allows you to select aninstance of the kernel entity using the Open choice in the File menu.

Because the details of a non-kernel entity are meaningful only in the context of another entity, you cannavigate to a non-kernel detail display only from another entity; it does not serve as an entry point intothe application. For this reason, the detail display rule for a non-kernel enti ty contains an input and anoutput view. Also, you cannot open an instance directly from a non-kernel detail display, as it isnecessary to clarify its context through navigation from another object.

A generated detail display window always contains File, Edit, and Options menus. The File menu allowsyou to create a new object, save an object, delete an existing object, and exit the application. The Edit


37/183



menu provides undo and redo facili ties. The Options menu lets you eliminate the status bar that appearsat the top of the detail display.

View or Query menu choices are available when the table implementing the entity contains referred-bykeys (for the View menu) or foreign keys (for the Query menu). You can use View and Query menus tonavigate from object to object (entity to entity) in the application. The status line, located under themenu bar, displays information about current actions.

Display Driver M odule

Display Driver creates a rule (with appropriate hierarchies that have references to sets and components).This rule initializes window parameters and enables or disables objects on the detail window byinteracting with the Detail Display rule. The display driver rule does not have an output view, so noreturn code is passed back to the calling rule.

Browse Display Module

Browse Display creates both a rule and a window (with appropr iate hierarchies that have references tosets and components) for any kernel entity. This rule and window provide a way of looking atinformation for a kernel enti ty wi thout updating the information. You can use this browsing techniquefor object- to-object navigation. Use it only for kernel entities as a non-kernel entitys detail display rulehandles object-to-object navigation. Use the browse display also when navigating to a kernel entity toavoid recursion in the repository.

The browse display window is very similar to a detail display window. However, the browse display offersonly the Exit choice in the File menu. You can perform no other actions including object-to-objectnavigation. For that reason, there is no status line.

List Display M oduleList Display creates both a rule and a window (with appropriate hierarchies that have references to setsand components) for the entity. You use this window to select an instance of this entity from the Querymenu. The li st display rule shows a li st of entity instances that meet the cri teria the primary key specifies.It supports smooth scrolling, so you query the table and select a single instance in the tableimplementing this entity. The list display rule takes as input the primary view of the entity which it usesas search criteria. The output of the list display rule is a single instance of the cloned data view.

The list display window contains a multicolumn list box with one column for every field in the data viewof the fi le corresponding to this entity. The top of the window has an edit f ield for every field in theprimary view that you can use to specify selection criteria for a subset of entity. The menu contains asingle choice for toggling the status line on and off. Use the push buttons at the bottom of the windowto:

Select a set of rows in the list box according to the criteria specified at the top of the window

Select a single row from the list box

Cancel from this window

The status line, located under the menu bar, displays information about current actions.


38/183



Query Display Module

Query Display creates both a rule and a window (with appropriate hierarchies that have references tosets and components) for the entity. Use this rule and window to navigate to this entity from anotherentity, usually through a View menu. The query display rule shows all entity instances that meet thecriteria specified in the primary key. It supports smooth scrolling, so you can specify information toquery the table and select a single instance in the table implementing this entity.

If you select an instance of this enti ty either this entitys detail display (for a non-kernel entity) or browsedisplay (for a kernel entity) is conversed. The query display rule takes as input the cloned data view ofthe entity which it uses as search cri teria (if you specify any). The query display rule does not have anyoutput because it is only for navigation and viewing.

The query display window has a multicolumn list box with one column for every field in the data view ofthe fi le corresponding to thi s entity. Above the mult icolumn li st box there is an edit f ield for every fieldin the primary view. Use it to specify search criteria for a subset of entity instances. The menu contains asingle choice for toggling the status line at the top of the window on and off. Use the push buttons at thebottom of the window to:

Select a set of rows in the list box according to criteria at the top of the window

Select a single row from the list box

Cancel from this window

The status line, located under the menu bar, displays information about current actions.

Logical Driver Module

Logical Driver creates a rule (with appropriate hierarchies that have references to sets and components)that acts as a layer between the detail display and browse display presentation rules and the SQL rules.Logical Driver performs all complex field-to-field mappings when making calls to SQL rules. It takes theaction that is to be performed on the instance along with the entity instance (the cloned data view) in

the input view. If errors occur, it automatically calls the messaging routine defined by the MessageDisplay template.

Ut ilities Template

The Utilities template generates a message-handling rule and window for almost any modal messagethat a rule may need, such as an SQL failure. The only module included in this template is theMessageDisplayModule.

M essage Display ModuleMessage Display creates the HPS_MODAL_MESSAGE rule and window (with appropriate hierarchiesthat have references to sets and components) to display any four-line message to the end user. You canspecify the push but tons to display through the HPS_MESSAGE_TYPES. The output view returns yourresponse to the message.


39/183



Rename V iew s, Fields and Rules Template

Whenever you must change the name of an existing FIELD or VIEW object, use the Field and ViewRename template to automatically modify the source of any rules that refer to the renamed object. Thiscan save you hours of searching and editing.

To change the source of rules that refer to a renamed object:

1. Go to Construction Workbench.

2. Select a single FIELD or VIEW object to rename.

3. Select Tools > TurboCyclerand the Rename Views, Fields and Rulestemplate.

4. When the template displays the Rename window, type in the new name for the object.

5. It automatically modif ies the source of any rules that refer to the object to use the new name. Beforefinishing, the template shows a list of the rules it modified.

6. The Status pane displays the generation process.

7. You can stop TurboCycler generation by selecting Tools > Stop TurboCycler.

Rename Verify Template

The Rename Verify template does not modify any rules or change the name of the selected objectitonly shows which rules in the repository need to be modified if the name of the selected object ischanged.

When you rename views that have a window parent, the window panel is not modified at all. The rulesource change is a blind search and replace.

Hierarchy Cloner Template

The Hierarchy Cloner template creates a new hierarchy of repository objects based on an existinghierarchy. The new hierarchy consists of a mixture of both newly created objects and existing objectsfrom the source hierarchy. Using this template involves:

Understanding the Cloning Process

Using the Hierarchy Cloner

Sett ing Initialization Parameters

For each object in the source hierarchy, cloner relies on pairs of search and replace strings to determinewhether it should reuse the existing object or create a new object based on the existing object.

The Hierarchy Cloner never modifies or has any effect on existing objects in the repository with oneexception: while creating the new hierarchy, cloner may establish a parent/child repository relationbetween a newly created object and an existing object.

Note You can also right-click to select Stop TurboCycler.


40/183



Understanding the Cloning ProcessThis section discusses how cloning works so you know what to expect from the cloning process. Eachobject that cloner examines must meet two conditions to be cloned:

1. The name of the object must be changed after cloner does str ing replacement using the strings yousupply.

2. The type of the object must be in the user-specified list of types to clone.

If either of these conditions is not met, the object is reused and its child objects are not examined.

If the object i s to be cloned, cloner creates a new object of the same type with the cloned name andcopies certain properties from the source object to the cloned object. The new object is attached to the

new object hierarchy and cloning continues by examining children of the source object. If the clonedobject already exists in the repository, it is reused and never modified.

The properties copied are:

Those that are available in TurboCycler

Writable

Not required to be unique by the repository

Thus the template supplied is general purpose in nature and is not geared specifically to any one type ofapplication hierarchy. If you have special requirements for cloning, customize the supplied templateusing the TurboCycler Developers Kit.

Using the Hierarchy Cloner

Use the Hierarchy Cloner template from the Hierarchy Diagrammer to clone application hierarchies.Use it when you would like to make a copy of an existing hierarchy and you can identify one or moresubstrings contained in the names of the existing objects that can be used to guide the cloning process.

Caution When cloning hierarchies containing error, lookup, or define sets, the encoding and display attributevalues is replaced blindly without error checking for value overflow and such. It is your responsibility

to ensure that these values do not overflow and are valid

Note Rollback does not remove all unwanted objects after cloning by TurboCycler.


41/183



The following objects can be cloned:

FUNCTION

PROCESS

RULE

FILE

VIEW

FIELD

SET

VALUE

COMPONENT

WINDOW

In addition to these, the cloner wi ll reuse BITMAP objects but it wil l not clone them. Because clonernever modifies existing objects in the repository, subsequent regeneration of this template has no effect.

Component source will not be cloned.

When cloner executes, a dialog is displayed. The controls and their meanings are listed in Table2-1.

When cloner is finished, the new hierarchy is displayed. In this display, you can browse the newhierarchy and see the objects that were created.

Sett ing Initialization Parameters

Hierarchy Cloner uses the CLONER section in the TURBO.INI to record default settings for the dialog:

[CLONER]

REPLACE=EMPLOYEE COMPANY FIRM

WITH=MANAGER ORGANIZATION COMPANY

TEXT_AND_KEYWORDS=IGNORE

SOURCE_FILES=YES

REUSE=FIELD VALUE COMPONENT

IMPLEMENTATION_NAMES=NO

TRUNCATE_LONG_NAMES=NO

Note Always select a single object and choose TurboCycler Selected from the Analysis menu. Clonerautomatically examines all objects under the selected one. Do not pass multiple objects for cloning.

Table 2-1 Cloner Controls and Descriptions

Control Description

Replace (entry field) The substring to search for

With (entry field) The replacement string to use

Add (push-button) Add the new pair of strings to the list

Delete (push-button) Delete the selected pair of strings from the listMove Up (push-button) Move the selected pair of strings up in the list

Move Down (push-button) Move the selected pair of strings down in the list

Objects to clone (listbox) Objects listed here are candidates for cloning

Objects to reuse (listbox) Objects listed here will never be cloned

Clone (push-button) Begins the cloning process


42/183


TurboCycler Tutorial

The REPLACE entry contains a series of substrings to search for, separated by spaces. The WITH entrycontains one replacement string for each substring in the REPLACE entry. TEXT_AND_KEYWORDSmay be set to:

IGNORE, indicating that created objects have no text or keywords

COPY, indicating that created objects have the same text and keywords as the source object

CLONE, indicating that created objects have the same text and keywords as the source object exceptmodified by the name cloning procedure

If SOURCE_FILES is NO then created objects have identical source files as the source object; if it is YESthen source files are cloned.

The REUSE entry contains a list of object types separated by a single space that are never to be cloned,regardless of their names. The IMPLEMENTATION_NAMES entry may be either YES or NO dependingon whether implementation names and screen li terals should be cloned.

When cloner forms a name that is too long, it either automatically truncates the name or displays adialog asking the user to provide a shorter name. This choice is controlled by theTRUNCATE_LONG_NAMES entry which may be either YES or NO.

Typically, you do not need to look at this fi le since if you select Clonerand Generate, a dialog boxdisplays and this window sett ing is wri tten to TURBO.INI.


TurboCycler software complements and enhances the AppBuilder environment. Because of theircompatibil it ies, the sample TurboCycler tutorial is an extension of the AppBuilder environmentwalkthroughs in the workstation Workbench reference.

The tutorials summarize the automobile rental agency sample from AppBuilder training and show theresults when you use the TurboCycler product with the same repositor y objects. The tutorial that fol lowsassumes that you perform all of the steps for each tool .

The steps are:

Reviewing Forward Engineering and Transforming

Generating with TurboCycler

Review ing Forw ard Engineering and Transforming

The TurboCycler process begins after you forward engineer and t ransform a completed entityrelationship diagram using the Construction Workbench. The following is a review of the buildingprocess. Refer to the AppBuilder documentation and online help for greater detail about building themodels the TurboCycler walkthrough uses.

Defining an Enti ty Relationship Diagram

Forward Engineering an Entity Relationship Diagram

Transforming a DBD


43/183



Defining an Entity Relationship Diagram

1. The fi rst step in designing your application is to create an entity relationship diagram (ERD). Usethe Entity Relationship Diagrammer to create the drawing shown in Figure 2-8.

Figure 2-8 Ent ity relat ionship diagram

2. Choose Select Allin the Edit menu, then chooseOpen as/Hierarchyin the Edit menu to open aconstrained version of the hierarchy.

3. Create the att ributes, identif iers, and data types for the AGENT entity.

4. As you create each data type, double-click its name to display the Edit Type window. Choose thedata format corresponding to the data types name from the list box and then change the data lengthfield if necessary.

5. Create the hierarchies for the RESERVATION and VEHICLE entities shown in Figure 2-9.

Figure 2-9 RESERVATION and VEHICLE entity hierarchies

6. Create the hierarchies for the CUSTOMER and LOCATION entities shown in Figure 2-10.


44/183



Figure 2-10 CUSTOMER and LOCATION entity hierarchies

7. Create the hierarchies for the CORPORATE and INDIVIDUAL entit ies shown in Figure 2-11.

Figure 2-11 CORPORATE and INDIVIDUAL entity hierarchies

8. Open the Construction Workbench window and select Commit Sessions changesin the Sessionmenu. Name the entity relationship drawing RENTAL_ERD.

Forward Engineering an Entit y Relationship Diagram

This section assumes you have created the entity relationship drawing and attributes described inDefining an Entity Relationship Diagram on page2-15.

1. Select the Enti ty Relationship Diagrammer window.

2. Verify each relationship has a cardinality symbol at each end. Make certain the cardinalities are asshown in Figure 2-12.

3. Choose Hierarchy display in the Options menu to show the hierarchy for each enti ty in the drawing.Make sure each entity has the required attribute structures shown previously.

4. Choose For

app builder 2 scripting tools

Documents