V12 Database Engine

for Macromedia Director

tm

version 2.1

Getting Started

(QuickStart.DIR's user manual)

©Integration New Media, Inc. 1995-98

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 2

Preface

Integration New Media Inc. was founded in 1989. We are dedicated to developing new multimedia
solutions for both Mac and Windows and offering technical guidance to multimedia producers.

In 1993, Integration began to specialize in cross-platform component development and at the same
time noted an increasing demand for database management software. V12-DBE is a powerful,
flexible and user-friendly database management system that was developed to fulfill the needs of a
growing market.

We hope that V12-DBE will become your best business partner, offering new and exciting
opportunities to you and your customers.

FAQs

You can find a Frequently Asked Questions (FAQs) section on our web site
www.integration.qc.ca. This section is updated regularly to help you keep up with answers to any
questions or problems you or other users may experience with using V12 Database Engine.

Using this Manual

This manual has been organized to allow you to get the help you need in the most efficient manner.
The first section introduces you to the V12-DBE. The second section includes a QuickStart to help
you get started by giving you a brief overview of how to create a V12 database, importing data, and
browsing and searching the data in the V12-DBE file. The third section includes ready-made
scripts that will be of value to you for your own projects.

If you need more information about databases abd their elements refer to Database Basics in the
User Manual.

Technical Support

Integration New Media Inc. is committed to the satisfaction of V12-DBE users. In developing
materials included in the V12-DBE package, we have tried to anticipate your needs and concerns.
However, your questions and your input are always welcome. If the V12-DBE manuals cannot
answer any of your questions, or if the sample movies provided are not suitable for your specific
needs, our technical support staff will be glad to assist you. We are available between 9:00 a.m. and
5:00 p.m. EST, Monday through Friday. As a registered user, you have free technical support from
any of the following sources for 90 days from the date of purchase. We will do our best to respond
within one business day.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 3

You may contact us by phone, fax, e-mail, or via our WWW site:

•

Phone: [phone], Extension 6

•

Fax: [phone]

•

E-mail: [e-mail], [e-mail]

•

WWW site: www.integration.qc.ca

When contacting us, please be sure to provide the following information:

•

your license number;

•

your name and phone number as listed on your registration card;

•

your fax number and e-mail address, if applicable;

•

the version of V12-DBE you are using;

•

a profile of your Macintosh or PC — type of computer, operating system and version,

quantity of RAM, etc.; and

•

a description of the problem — the specifics of the problem, when it occurs, how severe

the problem is, what error numbers or messages are returned when the problem occurs
and any other details that come to mind.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 4

Licensing and Legalities

In Plain English

•

You can install and distribute unregistered copies of V12-DBE, its manuals and other

related files in as many copies as you wish.

•

You cannot give registered copies of V12-DBE to others, unless that transfer is permanent

and you keep no copies of that registered version (no registration number and no license
file). At any particular time, a V12-DBE license file can be installed on only one
computer.

•

If you are developing a project with V12-DBE, you need your own V12-DBE license

regardless of the fact that other colleagues working on the same project may have V12-
DBE licenses.

•

If your project requires you to create or modify a V12-DBE database structure, you need a

V12-DBE license. If you only need to view or modify the content (records) of a V12-DBE
database, no license is required.

•

The V12-DBE Runtime Kit can be freely distributed by V12-DBE license owners for use

at runtime only, by one user at a time only.

•

If your project requires a third party to distribute or redistribute the V12-DBE Runtime

Kit then the third party must purchase his own V12-DBE license.

•

If V12-DBE is used in an authoring environment, then the user (you or any third party)

must purchase a V12-DBE license.

•

If you are developing a product that will run on both Mac and Windows, you need a V12-

DBE license for each platform. The Mac license includes the PowerMac and 68K
versions. The Windows license includes the Win-16 and Win-32 versions.

•

You must mention "Portions of code are Copyright (c)1995-98 Integration New Media,

Inc." next to your own copyright notice.

•

You must place the "Powered by V12" logo on the packaging of your product or within

your product (in the Credits section, About box or equivalent location). The "Powered by
V12" logo is available on the V12-DBE CD-ROM and on Integration New Media's web
site (http://www.integration.qc.ca).

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 5

In Legalese

PLEASE READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING V12
DATABASE ENGINE. BY USING V12 DATABASE ENGINE, YOU AGREE TO BECOME
BOUND BY THE TERMS OF THIS LICENSE AGREEMENT.

The enclosed computer program(s), license file and data (collectively, "Software") are licensed, not
sold, to you by Integration New Media, Inc. ("Integration") for the purpose of using it for the
development of your own products ("Products") only under the terms of this Agreement, and
Integration reserves any rights not expressly granted to you. Integration grants you no right, title or
interest in or to the Software. The Software is owned by Integration and is protected by
International copyright laws and international treaties.

1. License.

(a) You may install one copy of the Software on a single computer. To "install" the Software means
that the Software is either loaded or installed on the permanent memory of a computer (i.e., hard
disk). This installed copy of the Software may be accessible by multiple computers, however, the
Software cannot be installed on more than one computer at any time. You may only install the
Software on another computer if you first remove the Software from the computer on which it was
previously installed. You may not sublease, rent, loan or lease the Software.

(b) You may make one copy of the Software in Machine readable form solely for backup purposes.
As an express condition of this Agreement, you must reproduce on each copy any copyright notice
or other proprietary notice that is on the original copy supplied by Integration.

(c) You may permanently transfer all your rights under this Agreement to another party by
providing to such party all copies of the Software licensed under this Agreement together with a
copy of this Agreement and the accompanying written materials, provided that the other party
reads and agrees to accept the terms and conditions of this Agreement and that you keep no copy of
the Software. If the Software is an update, any transfer must include the update and all prior
versions.

(d) Your license is limited to the particular platform or operating system and version (collectively
"Version") of the Software you have purchased. Therefore, use of a Version other than the one
encompassed by this License Agreement requires a separate license.

(e) The Software contains a license file (.LIC) which is subject to the restrictions set forth above
and may not be distributed by you in any way. However, Integration grants you a royalty-free right
to reproduce and distribute the files named "V12-DBE for Director.XTR", "V12-DBE for
Director.X32" and "V12DBE-D.X16" (collectively, "Runtime Kit") provided that (i) you distribute
the Runtime Kit only in conjunction with and as part of your own Products; ; (ii) make sure that
the Runtime kit is not usable by more than one user at any time; (iii) own a license for the specific
Version of the Software that contains the Runtime Kit; (iv) agree to indemnify, hold harmless and
defend Integration from and against any claims or lawsuits, including attorney's fees, that arise or
result from the use or distribution of your Products with the Runtime Kit.

(f) Any third party who may distribute or otherwise make available a product containing the V12-
DBE Runtime Kit must purchase its own V12-DBE license.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 6

(g) Any third party who will use the V12-DBE Runtime Kit in an authoring environment must
purchase his own V12-DBE license.

2. Restrictions. The Software contains trade secrets in its human perceivable form and, to protect
them, you may not MODIFY, TRANSLATE, REVERSE ENGINEER, REVERSE ASSEMBLE,
DECOMPILE, DISASSEMBLE OR OTHERWISE REDUCE THE SOFTWARE TO ANY
HUMAN PERCEIVABLE FORM. YOU MAY NOT MODIFY, ADAPT, TRANSLATE, RENT,
LEASE, LOAN OR CREATE DERIVATIVE WORKS BASED UPON THE SOFTWARE OR
ANY PART THEREOF.

3. Copyright notices. You may not alter or change Integration's copyright notices as contained in
V12-DBE. You must include (a) a copyright notice, in direct proximity to your own copyright
notice, in substantially the following form "Portions of code are Copyright (c)1995-98 Integration
New Media, Inc."; or (b) place the "Powered by V12" logo on the packaging of your Products; and
(c) place the "Powered by V12" logo within your Products in the credits section.

4. Acceptance. V12-DBE shall be deemed accepted by you upon delivery unless you provide
Integration, within two (2) weeks therein, with a written description of any bona fide defects in
material or workmanship.

5. Termination. This Agreement is effective until terminated. This Agreement will terminate
immediately without notice from Integration or judicial resolution if you fail to comply with any
provision of this Agreement. Upon such termination you must destroy the Software, all
accompanying written materials and all copies thereof, and Sections 7 and 8 will survive any
termination.

6. Limited Warranty. Integration warrants for a period of ninety (90) days from your date of
purchase (as evidenced by a copy of your receipt) that the media on which the Software is recorded
will be free from defects in materials and workmanship under normal use and the Software will
perform substantially in accordance with the manual. Integration's entire liability and your sole and
exclusive remedy for any breach of the foregoing limited warranty will be, at Integration's option,
replacement of the disk, refund of the purchase price or repair or replacement of the Software.

7. Limitation of Remedies and Damages. In no event will Integration, its parent or subsidiaries or
any of the licensers, directors, officers, employees or affiliates of any of the foregoing be liable to
you for any consequential, incidental, indirect or special damages whatsoever (including, without
limitation, damages for loss of profits, business interruption, loss of business information and the
like), whether foreseeable or not, arising out of the use of or inability to use the Software or
accompanying written materials, regardless of the basis of the claim and even if Integration or an
Integration representative has been advised of the possibility of such damage. Integration's liability
to you for direct damages for any cause whatsoever, and regardless of the form of the action, will
be limited to the greater of US $350.00 or the money paid for the Software that caused the
damages.

THIS LIMITATION WILL NOT APPLY IN CASE OF PERSONAL INJURY ONLY WHERE
AND TO THE EXTENT THAT APPLICABLE LAW REQUIRES SUCH LIABILITY. BECAUSE
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF
LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE
LIMITATION MAY NOT APPLY TO YOU.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 7

8. General. This Agreement will be construed under the laws of the Province of Quebec, except for
that body of law dealing with conflicts of law. If any provision of this Agreement shall be held by a
court of competent jurisdiction to be contrary to law, that provision will be enforced to the
maximum extent permissible, and the remaining provisions of this Agreement will remain in full
force and effect.

9. The parties acknowledge having requested and being satisfied that this Agreement and its
accessories be drawn in English. Les parties reconnaissent avoir demandé que cette entente et ses
documents connexes soient rédigés en anglais et s'en déclarent satisfaits.

The following trademarks are used throughout this manual: Director and Xtra are trademarks of
Macromedia, Inc., FileMaker Pro is a trademark of Claris corp., Windows, Access and MS Excel
are trademarks of Microsoft corp., Macintosh is a trademark of Apple corp., 4th Dimension is a
trademark of ACI, Photoshop is a trademark of Adobe Systems Inc.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 8

Table of Contents

PREFACE .................................................................................................................................... 2

FAQ

S

............................................................................................................................... 2

U

SING THIS

M

ANUAL

........................................................................................................ 2

TECHNICAL SUPPORT ............................................................................................................ 2

LICENSING AND LEGALITIES ............................................................................................... 4

I

N

P

LAIN

E

NGLISH

........................................................................................................... 4

I

N

L

EGALESE

.................................................................E

RROR

! B

OOKMARK NOT DEFINED

.

TABLE OF CONTENTS............................................................................................................. 8

INTRODUCTION: WELCOME TO V12-DBE ......................................................................... 9

S

YSTEM

R

EQUIREMENTS

F

OR

R

UNNING

V12-DBE .......................................................... 9

Macintosh version .............................................................................................. 9
Windows version ................................................................................................ 9

F

ILES

N

EEDED TO

U

SE

V12-DBE................................................................................... 10

I

NSTALLING

V12-DBE ................................................................................................... 10

QUICKSTART .......................................................................................................................... 11

O

VERVIEW

..................................................................................................................... 11

CREATING A V12-DBE DATABASE ..................................................................................... 12

D

ECIDING ON A

D

ATA

M

ODEL

........................................................................................ 12

C

REATING THE

V12 D

ATABASE

F

ILE

.............................................................................. 13

Getting started:................................................................................................. 13

IMPORTING DATA ................................................................................................................. 15

Preparing Data ................................................................................................. 15
Importing Data into the V12-DBE File ............................................................. 15

BROWSING AND SEARCHING DATA.................................................................................. 16

NEXT STEP ............................................................................................................................... 17

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 9

Introduction: Welcome to V12-DBE

Welcome to V12-DBE, the most powerful and user-friendly cross-platform database management
Xtra for use with Macromedia Director™ (version 5.x and later) and
applications on both Macintosh and Windows platforms. V12-DBE is intended for applications
delivered on CD-ROM where data is stored and repeatedly retrieved. However, it is not limited to
CD-ROM applications. If required, applications can be developed in which data can be stored,
modified and retrieved at any time. These applications would then be used on mediums such as
hard drives and removable media.

V12-DBE is used as a back-end to your multimedia productions and for the management of data.
You can develop quick and simple flat database models or more complex relational, multi-indexed
database models. If you are familiar with other database management systems, you will find V12-
DBE very easy to use. If you are only vaguely familiar with database management systems, Section
2 of this manual, "Basic Concepts" will give you an overview of what you need to know.

Typographic conventions

Important terms, such as the names of methods, are in bold, while sample code is indented and
printed in courier.

Note/tip:

You will see special annotations and tips to help you use V12-DBE more
efficiently in boxes like this one.

System Requirements For Running V12-DBE

Macintosh version

Macintosh with System 7.x or later and 1 Mb of free disk-space. On the Macintosh, V12-DBE (and
any other Xtra) will share the same memory allocation as Macromedia Director. For simple
database applications, you do not need to change Director’s memory allocation. For more
advanced development, you might need to increase its memory allocation.

Windows version

Any PC running Windows 3.x (16-bit) or Windows 95/98/NT (32-bit) which has the capability to
run Macromedia Director plus 1 Mb of free disk-space. No memory management is required on
Windows.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 10

Files Needed to Use V12-DBE

One file is required for the development and use of V12-DBE: “V12-DBE.XTR” on the Macintosh,
“V12-DBE.X16” with Windows 3.x (16 bits) and “V12-DBE.X32” with Windows 95/98/NT (32
bits) .

This file constitutes what is referred to as the “Runtime” or the end-user version of V12-DBE for
the Macintosh. The “Development” version requires an additional file – the license file, located in

System:Preferences” folder of your Macintosh. Licensing provides you with the ability to

create new databases.

Installing V12-DBE

Make sure Director is closed.

1. Place the Xtra in Director's Xtras folder,

2. Place the Help files (V12HELP.DIR and V12HELP.V12) in Director's folder.

3. Open Director

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 11

QuickStart

Topics Covered in QuickStart

•

Creating a V12 Database

- Deciding on a Data Model
- Creating the V12 Database File

•

Importing Data

- Preparing Data
- Importing Data into the V12 Database File

•

Browsing and Searching Data in the V12 Database File

•

Scripts

Overview

This section leads you through a simple example of basic operations, such as creating a database
file, importing, and browsing data using V12-DBE. Although our example is quite simple,
remember that V12-DBE is capable of doing much more! Given that this QuickStart is not a
typing exercise, the necessary Lingo scripts are included in the "QuickStart.DIR" movie provided
with this document in the SAMPLES / QUICKSTART folder on the V12-DBE CD. If you are
unfamiliar with database concepts, we recommend that you go through the Database Basics
section in the V12-DBE User Manual.

When using V12-DBE in a project, the standard procedure is to open your database when you
launch your project, and then close it when you exit. In the QuickStart example, the open and
close actions are executed repeatedly for emphasis.

Information relating to screen elements can be obtained by clicking on the "Help" button.

You can exit the QuickStart at any time by clicking on the "Quit" button.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 12

Creating a V12-DBE Database

For your own projects, you can use some of the routines supplied by the QuickStart example to
develop the Lingo scripts necessary to link your Director movie to your V12 database file.

Deciding on a Data Model

Before you begin creating a database, you need to define the information and its structure. This
Quickstart example is based on a database of stationery articles. For simplicity’s sake, each entry
in the database will contain:

•

a name,

•

a category,

•

a description,

•

a price,

•

a catalog number,

•

a supplier identifier,

•

a shipping date,

•

a flag indicating whether the product is available or not.

To structure the information in this example, only one table is required. Remember that V12-DBE
has the capability of including many tables.

Before proceeding to the next step - Creating the database file - we need to make two additional
decisions: what are the types of the above mentioned fields, and which ones must be indexed (for
fast searching and sorting).

•

name is a string

•

category is a string

•

description is a string

•

price is a float (floating point number)

•

catalog number is an integer

•

supplier identifier is an integer

•

shipping date is a date,

•

availability is an integer.

Moreover, name, category and catalog number will be indexed to allow for quick searching a
sorting.

Note

Indexes are used by search operator to minimize searching speed.
QuickStart.DIR uses the contains operator which does not use indexes.
Therefore, the choice of the three indexes above is arbitrary in the case of
QuickStart.DIR.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 13

Creating the V12 Database File

Once the data model is defined, you can proceed with creating the V12-DBE file.

Getting started:

•

Open the "QuickStart.DIR" movie provided with this document.

•

Start the movie.

•

This movie is divided into three sections: “Creating a Database”, “Importing Data” and

•

The Lingo scripts which are in handler form, are located in member 2 of the internal

castlib.

•

Click on "Creating a Database" to go to the database screen.

•

This section will show you how to create a V12 database file from a database definition.

This definition is processed by one of V12’s methods -

mReadDBStructure

. The

definition structure is based on specific information entered after the following tags:
[TABLE], [FIELDS], [INDEXES], [FULL-INDEXES] and [END].

The [TABLE], [FIELDS], [INDEXES] and [FULL-INDEXES] are considered a group, and are
repeated as many times as there are tables to be created.

[TABLE] will always be followed by one line of text because a table can only have one name.
[FIELDS], [INDEXES] and [FULL-INDEXES] can have one or more lines of text because each
table can have one or more fields, and one or more indexes.

The [END] header indicates that the definition is complete.

The QuickStart's database descriptor is:

[TABLE]
Articles

[FIELDS]
catalogNumber integer indexed
productName string indexed
category string indexed
description string
price float
supplierId integer
availability integer
shippingDate date

[END]

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 14

Note:

The above example shows you how to create a V12 database in a
scripting environment (that is, you can fully automate the database
creation process). You may also want to take a look at the V12 Tool
which enables you to create a V12 database and import data to it in a
friendly point-and-click environment.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 15

Importing Data

Before you import data into a database, the data must be prepared to ensure it is in a correct
importing format.

Preparing Data

Once you have defined your data model and created your database, you need to prepare the data
you will be importing into the database. When creating your own database, you would collect and
structure your data with a descriptor for each item (i.e. number, title, etc...) using the application of
your choice. This step can be accomplished by using a word processor, a spreadsheet, or a database
management system. This QuickStart example provides you with prepared data in a TEXT file
called “Articles.txt”.

Tip:

FileMaker Pro, equivalent database management software, is a
convenient tool used to manage and prepare your data. For example,
once the data is structured and verified in FileMaker Pro, you can export
it as a TEXT file in a TAB-delimited format, to be imported into V12-
DBE.

Importing Data into the V12-DBE File

V12-DBE can import data in several formats: TEXT files, V12-DBE and DBF databases. If you
import data in TEXT format, and if you have more then one table in your database, you would
import one separate TEXT file in each table.

Note:

For data contained in text files, the typical record separator is CR/LF
(carriage return /line feed) for Windows, and CR (carriage return) for
Macintosh.
You also have to add one line at the beginning of the TEXT file which
identifies the descriptors of the data that follows.

In this example, we have one TEXT file to import, named "Articles.txt":

•

Click on "Importing Data" to go to the import screen.

•

Click on the “Open” button to open the V12 database file named “Articles.v12”.

•

Click "Import Data" to import the data contained in the TEXT file named “Articles.txt”

•

An alert message will inform you as to whether the procedure was successful or not.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 16

Browsing and Searching Data

At this point, you have a V12 database file that contains all stationery information. This section
will illustrate how to find and display that information.

•

Click on the "Open Database" button to open the "Articles.v12" database.

•

This example offers two ways to search for information in the database:

(1) to search and retrieve specific records from the database based on a set of defined
criteria; and
(2) to retrieve all records from the database.

•

To find records that contain a specific string of text, type that string in the

"String to search" field and Click on the "Find" button.

•

To find all records in the database, click on the "Find All" button.

•

Use the buttons labeled "Next" and "Previous" to browse through the records found.

V12-DBE Getting Started

10/23/98

©Integration New Media, Inc. 1995-98

page 17

Next Step

If you are not very familiar with Lingo, check the V12-DBE Behaviors Library, to see how you can
implement database features into your Director projects without writing a single line of Lingo.

You may also want to take a look at the V12 Tool which enables you to create V12 databases and
import data to them in a friendly point-and-click environment.

If you are already comfortable with Lingo scripting, you may want to proceed to reading the V12-
DBE User Manual.

For more examples of Lingo scripts related to V12 Database Engine, check the Mini-Samplers on
the V12-DBE CD-ROM or Integration New Media's web site (http://www.integration.qc.ca)