uniPaaSV15 StudyGuide

STUDY GUIDE
Fundamentals of uniPaaS v1.5
Last Revision: February 17, 2009 Developed by: Roberto Ramrez marionette_66@operamail.com
Page 2
Page 3
Table of Contents
About this Study Guide and Course............................................................................5 Part 1 Introduction to uniPaaS................................................................................9
LESSON 1 THE MAGIC CONCEPT...............................................................................................................9 LESSON 2 INSTALLATION, SETUP LESSON 3 INTRODUCTION
TO AND
EXECUTION...........................................................................................17
DEVELOPING PROJECTS.......................................................................................41
Part 2 uniPaaS Programming................................................................................59

LESSON 4 MODEL REPOSITORY...............................................................................................................59 LESSON 5 DATA REPOSITORY................................................................................................................73 LESSON 6 AUTOMATIC PROGRAM GENERATOR (APG)......................................................................................85 LESSON 7 NAVIGATING
UNIPAAS
............................................................................................................99
LESSON 8 THE RUNTIME....................................................................................................................107 LESSON 9 PROGRAMMABLE LOOP CONCEPT HOW LESSON 10 THREE STEPS
FOR UNIPAAS
PROGRAMS WORK.......................................................121
WRITING
MAGIC PROGRAM............................................................................125
LESSON 11 FORM DESIGN..................................................................................................................137 LESSON 12 COLUMN, UPDATE, VERIFY

AND
REMARK OPERATIONS......................................................................149
LESSON 13 ONE-TO-ONE DATABASE RELATIONSHIP (1:1)...............................................................................167 LESSON 14 WRITING

A
LOOKUP PROGRAM................................................................................................179
LESSON 15 WRITING BATCH PROGRAMS...................................................................................................211 LESSON 16 WRITING SUB-TASKS...........................................................................................................227 LESSON 17 WRITING REPORT PROGRAMS.................................................................................................241 LESSON 18 CREATING HELP SCREENS......................................................................................................251 LESSON 19 CREATING LESSON 20 CREATING
A A
MENU SYSTEM...................................................................................................257 SECURITY SYSTEM................................................................................................261

AN UNIPAAS
LESSON 21 DEPLOYING
APPLICATION........................................................................................271
Page 4
APPENDIX SECTION..............................................................................................281
APPENDIX A THE ENGINE EXECUTION RULES..............................................................................................281 APPENDIX B DETAILED ENGINE FLOWS.....................................................................................................287 APPENDIX C HOW
UNIPAAS
PREPARES
THE
DATA VIEW..................................................................................295
EXERCISE SECTION..............................................................................................297
EXERCISE 1 CREATING MODELS.............................................................................................................297 EXERCISE 2 CREATING TABLES..............................................................................................................298 EXERCISE 3 CREATING DATA ENTRY PROGRAMS...........................................................................................302 EXERCISE 4 MODIFYING DATA ENTRY PROGRAMS (WITH VALIDATE).....................................................................303 EXERCISE 5 MODIFYING DATA ENTRY PROGRAMS (WITH LINK)..........................................................................304 EXERCISE 6 CREATING LOOKUP PROGRAMS................................................................................................305 EXERCISE 7 CREATING CLEANUP BATCH PROGRAMS.......................................................................................307 EXERCISE 8 CREATING SEARCH PROGRAMS.................................................................................................308 EXERCISE 9 CREATING
AN
ORDER ENTRY PROGRAM......................................................................................310
EXERCISE 10 CREATING REPORT PROGRAMS...............................................................................................311
FEEDBACK FORM..................................................................................................313
Page 5
About this Study Guide and Course

Welcome the word of uniPaaS. The Study Guide for the Fundamentals of uniPaaS course is designed to provide the student (that's you!) with a basic understanding of the concept behind this application development tool, as well as the necessary tools and exercises to start developing projects with it. uniPaaS is unique in that it frees the developer (that's you again) from the repetitive, time-consuming task of conventional programming methodologies. What does this mean? What are the features that enable this capability? What are the implications of such a radical idea? These questions will be dealt with in the first part of this course. At the end of this training, you will have developed an application that will work with several data sources\tables, covering data validation, 1:1 (one-to-one) and 1:M (one-to-many) relationships, referential integrity, screen design, menu system, batch processes, reports, on-line help, rights-based security system and deployment of your application. This course should include the following material:

Study Guide Fundamentals of uniPaaS (this document) uniPaaS Installation program Text files with sample data
This document only contains information about the fundamentals of uniPaaS programming; therefore, it does not cover the complete set of characteristics, features and modules that uniPaaS has to offer; this information can be found on the following places:

On-line Help. While inside uniPaaS, you can press the <F1> key to get information about your current screen. Reference Manuals. Once the installation of uniPaaS is completed you will find inside its directory a folder called Support, on this folder you will find several files on Adobe's Acrobat format Internet. There are several web sites and Internet communities of uniPaaS Programmers (Magicians) ready to be help new developers, the following table shows several of these places:
Magic User List. The de facto international standard meeting place for Magic developers - independently maintained. Subscribe at: http://groups.yahoo.com/group/magicu-l/join
Magic uniPaaS for iSeries Users List. magic400-l Magic RAD software for AS400 Users Subscribe at: http://groups.yahoo.com/group/magic400-l/join
Page 6
Magic Sales/Business Forum Magic RAD Software Sales List Subscribe at: http://groups.yahoo.com/group/magics-l/join Craig Matin's Web Site Long time Magic programmer and Jedi Knight. http://magicusergroup.com http://craigmartin.com/ Knowledge Base for the MagicUserGroup http://www.ng-sw.de/mg-wikka/HomePage
Typographical Conventions
The following table will show the different type fonts used on this manual and their significance:
Type Style Italic
Means...
Menu names, or the name of options. For example: File | New Project means select the New Project entry from the File menu. Italic type also signals a new term and it is also used for references in the text to names of publications, such as the Mastering uniPaaS document.
Courier Bold ALL CAPITALS Initial Capitals <Enter> <Shift+F3>
Anything that you must type exactly as it appears Placeholders for information you are expected to provide to uniPaaS. For example: ... enter in the Last Name field the name for the person you are looking for Full paths and file names from your computer The name of tables, programs, models, screens. The name of a key on your keyboard. The combination of two keys on your keyboard that you have to press by holding down the first key while you press the second key
Page 7
Manual Notes
Throughout this manual you will find sections that will contain important notes, step-by-step instructions or exercises, just to mention some. The following table shows an entry for each one of these sections:
Icon
Description
Perform the following operations as described It is possible that a problem will occur at this moment, if so, this section may have the solution. A helpful hint for the current section A piece of information that should not be forgotten
A task or exercise to perform It is possible that an error will occur at this moment, if so, this section may have the solution.
Where the Main Topics of this Manual are Explained

If you are brand new to uniPaaS, Lesson 1 is a must for you. It will explain the characteristics that make uniPaaS so different from any other programming tools. While Lesson 2 covers the installation, configuration and registration of your new copy of uniPaaS, Lesson 3 describes the menu system and the short-cut keys. Lesson 4 will give us an overview of the steps to create a new Project. The creation of Models and Data Sources for our Project will take place in Lessons 5 and 6. We will start working with programs in Lessons 7, first by letting uniPaaS create the program automatically, and then we will develop our programs ourselves following Lessons 8 to 11 Basic operations of uniPaaS to be able to retrieve, update and validate information are covered in Lesson 12. Lesson 13 will deal with one-to-one relationships between data sources. Lookup programs are explained in Lesson 14, while Batch programs are described in Lesson 15; Sub-tasks and report programs start at Lesson 16 and 17 respectively.
Page 8
The creation of a Help System is handle in Lesson 18, Menus in Lesson 19; the Security System is covered in Lesson 20 and the deployment of our application in Lesson 21. While the Appendix section have information about the inner-workings of the uniPaaS engine, the Exercise section has instructions on the creation of our first Project.
Feedback Form
Each time this class is tough or this manual is read, we want to make it better. Please take one or two moments and fill up the feedback form at the end of this Manual and let us learn from you on how to improve this document, what to change, and what to leave alone. Thanks Roberto Ramrez
Page 9
Part 1 Introduction to uniPaaS

Lesson 1 The Magic Concept
PURPOSE OF THIS LESSON To introduce the concept and methodology behind the Magic Engine KEY TERMS Table-Driven Methodology Code-Free Application Non-Procedural Operations OBJECTIVES To understand uniPaaSs unique table repository mechanism and approach to programming Understand the uniPaaS Application Engine components and their interrelationship Be aware of some of the major benefits of the table repository mechanism CONTENT OUTLINE 1.1.1 Introduction What is uniPaaS? 1.1.2 The Magic Concept The Evolution of Software Development Tools The Magic Application Engine Nearly Code-free Programming 1.1.3 Features and Benefices of the Magic Methodology Speed and Productivity Portability with Rich Internet Application (RIA) The Magic Database Gateway Rapid Application Development and Deployment (RADD) for Maximum Productivity
Page 10
1.1.1 Introduction What is uniPaaS?

You asked that fine question right there. uniPaaS (also known as eDeveloper or Magic) is an application development tool, a programming language. uniPaaS is focused to the creation of applications that will manipulate information from a data source (Database, text file, XML file, etc.) Applications like Contact Management, an Inventory System, a Call Center, or an Accounting System, can be developed, tested, and deployed in record time thanks to uniPaaSs approach to programming. If you want to create a printer driver, a MP3 player, a movie player, an RPG game, or an Operative System, uniPaaS may not the correct tool to develop these kinds of applications. Long time ago (in the mid-80s) at the center of the explosion of programming languages like Ingress, C++, dBaseIV, Smalltalk, Omnis 7, Clarion, Clipper, Dataease, R:Base, Superbase, Foxbase and Uniface; Magic's development tool was described as a Post 4GL Programming Tool that does not generate code (GL stands for Generation Language). Now days, the concept to Generation Language is hardly mentioned in marketing materials, white papers or brochures that try to explain the characteristics of such languages. Nevertheless, the features that best described Magic's tool then, remain unmatched today with uniPaaS. Unlike conventional programming languages, applications in uniPaaS are designed over a set of predefined rules that must be followed, not procedures that must be executed. In other words, applications are created by describing them, not by programming them.
1.1.2 The Magic Concept

The concept behind uniPaaS is a unique technology of development and implementation, on which an Engine reads the information from your application and executes those operations following a set of preset rules; such rules can be modified to match the developers requirements for the application. You can think of this application engine as a pre-written program that performs all of the basic and lowlevel functions required in most programs, such as opening and closing files, reading, locking, and writing records, and so on. Many programs in uniPaaS will only require the definition of which file(s) (or tables) you wish to access and which fields (or columns) you wish to display or modify on the screen. This Engine has already around 90% of the instructions that will be required for the execution of the majority of the applications in the industry; this means that the developer only needs to enter the remaining 10% of the logic for the application, allowing him/her to create applications at a great speed.
Page 11
Figure 1. uniPaaS's pre-written logic counts for about 90% of the total logic for your application. The remaining the logic that the programmer has to enter, is divided in two parts: 1. Modifying the behavior of each program, by changing predetermined properties on several sections of the program based on constant values, program variables or logical expressions. 2. Using any one of the 12 available operations in uniPaaS to create the logic that the program will follow to accomplish the require behavior. All the logic that is defined by the programmer, the layout of the screens, the pull down menus, reports, on-line help, security system, etc., all of them reside inside tables called Repositories. There is a Repository table to declare variables (called the Model Repository), there is a Repository table where to declare tables or data files (called the Data Repository), there is another set of tables to create your programs, your menus, on-line help and security; the only free-text zones that your will find in uniPaaS will be the Expression Editor to define logical functions and the Comments screen. The Evolution of Software Development Tools The task of simplifying programming started with code as the basic concept: a programmer had to use the machines language - code - to tell it what to do. The programmers code controlled every detail related to the physical aspects of the computing hardware. The very first programming concept that dramatically reduced the programmers burden was the symbolic language. Assemblers mechanically translated human-readable symbols into machine-readable binary-coded instructions. Compilers eased the programmers job by allowing the use of programming languages at a higher level of abstraction. However, the output of all these translations still had to be linked, loaded, and operated manually. Tools evolved to enhance productivity by increasing the level of abstraction. The goal was to allow the developers to concentrate on the logic of the application and to reduce the concern with the physical environment and to reduce mundane repetitive efforts. The concept: Increase the burden on tools to decrease the burden on programmers. Operating Systems were developed as general-purpose software engines to execute "application" programs when presented to them as executable modules.
Page 12
As the industry evolved, Relational Database Management Systems (RDBMSs) were introduced to further allow a higher level of abstraction by providing the means to describe the database requirements at a logical level. Conceptually, here too, the RDBMS is a runtime module that is a special-purpose software engine designed specifically to handle database functions. The next productivity gain was achieved with the development of fourth generation languages introducing another level of abstraction, in which much of the programming efforts are alleviated by on-screen functions and end-user interactions that are handled at a higher level. Conceptually, the 4GL deployment module is a special purpose software engine specifically designed to handle screen functions and enduser interactions. The concept: Increase the burden on engines to decrease the burden on programmers.
The Magic Application Engine We have just seen how the solutions to three distinct software issues - operating systems, database management systems, and 4GLs, have all found a solution in a single unifying concept: Engines. The questions that now beg to be asked are:
Can an engine be devised that will decrease the burden on programmers to such an extent that it creates a new programming paradigm? Can an application engine be created that will provide the platform-independent benefits typically associated with a virtual machine, that will increase application development productivity?
You will be able to answer these questions at the end of this course. Nearly Code-Free Programming Ever since first-generation translation tools evolved, the executable structure of computer application code has been very different from the structure entered by the programmer. However, in the case of uniPaaS, notions such as source code, compiled code, object code, semi-compiled code, pseudo code, meta-language code, and executable modules, all can be discarded. The structure in which the programmer enters the application code and the structure in which it is presented to the Magic Application Engine for execution are conceptually identical. There is no intermediate process between saving the code entered by the programmer and its execution. It is important to note that uniPaaS has reduced the syntax of the language while retaining the semantics, thus eliminating the typical overhead associated with interpreted languages. In uniPaaS, most of the processing time is spent executing the specific functions of the application. These functions are built-in as part of the Engine, and are implemented as highly optimized compiled native code. At the same time, the functions are sufficiently parameterized allowing developers to describe a wide range of applications.
Page 13
The fact that the entire description of the application, including the logic, the business rules, the screens (also called forms), and the data, are executed by Magic's Engine, further contributes to its renowned speed of development. All these features add up to the following facts:

Compilers and linkers are eliminated from the application development proces Capital investment in hardware for compilers and linkers is eliminated Developers can concentrate on functionality and on the business requirements, rather than on code and low-level "how to" instructions Each part of an application can be tested the moment its description has been entered, saving tedious "edit-compile-link-run" iterations End-users can participate actively in prototyping the application
1.1.3 Features and Benefits of the Magic Methodology

Speed and Productivity Writing and debugging procedural code is a time-consuming process. uniPaaS replaces code with tables; this is referred to as a Descriptive Programming Language. In the majority of the cases, developing applications in uniPaaS is 10 (ten) times faster compared to procedure-based programming languages. The reason for this is due to the fact that many standard programming tasks are automated:

Entering and displaying data Building menus Error checking Opening and closing files, reading and writing records Data validation Screen manipulation and update Processing Transactions And more
With uniPaaS, it is easy to make mayor changes to an application. All the changes in one section of the application are inherited or carried throughout the rest of the application. Applications can be modified and evaluated with no delay in between.
Page 14
Portability with Rich Internet Application (RIA) uniPaaS gives you development speed, ease of maintenance, end-user empowerment and satisfaction. Using the Rich Internet Application (RIA) capabilities of uniPaaS, the same application logic can be easily deployed on several platforms.
Figure 2. The same Application Logic can be read and execute on different platforms using the uniPaaS Engine The following table shows the different Platforms and Operative Systems supported by uniPaaS:
Microsoft Windows (on Intel) Windows 2000 Windows XP Windows 2003 (Standard Edition) Windows Vista Windows 2003 (64 bit Server Edition) Unix IBM AIX- 5.2 on PowerPC processors Sun Solaris 2.8 on SPARC processors Linux Red Hat Advanced server 3 on Intel processors IBM iSeries iSeries V5R3 and above on IBM servers with PowerPC processors
Engine Type Client (GUI) and Server Client (GUI) and Server Client (GUI) and Server Client (GUI) and Server Server Engine Type Server Server Server Engine Type Server
Page 15
The Magic Database Gateway To be fully portable, an application must be able to run on different databases. The Magic Database Gateway provides transparent access to common file managers and Relational Database Management Systems (RDBMSs).
Figure 3. The same Application Logic can access information for any DBMS just by selecting the appropriated Database Gateway
Page 16
The following table shows the different Databases supported by uniPaaS:
Microsoft Windows Oracle 9i (OCI 32bit only) Oracle 10g (OCI 32bit only) Oracle 11g (OCI 32bit only) Microsoft SQL Server 2000 Microsoft SQL Server 2005 Microsoft SQL Server 2008 MySQL 5.x ODBC 3.0 and above DB2 UDB 8 DB2 UDB 9 Pervasive 8 Pervasive 2000 Pervasive 9 Pervasive 10 DB2/400 V4.4 and above AS/400 ISAM V3.2 and above
IBM AIX Server Oracle 9i (OCI 32bit only) Oracle 10g (OCI 32bit only) DB2 UDB 8.1 Sun Solaris Server Oracle 9i (OCI 32bit only) Oracle 10g (OCI 32bit only) Linux Server Oracle 9i (OCI 32bit only) Oracle 10g (OCI 32bit only) DB2 UDB 8.2 ODBC 2 and above
Rapid Application Development & Deployment (RADD) for Maximum Productivity For many years now we have seen the demise of the traditional "Waterfall" approach to the design, development, and delivery of applications to end-users. The classical methods of application development, such as the "Waterfall" method, which forced end-users to determine their requirements early in the development cycle, did not provide the flexibility required by the emerging dynamic organization. Rapid Application Development & Deployment (RADD) was intended to provide the business environment with an alternative to the traditional method, thus enabling end-user involvement at all stages through iterative prototyping techniques. The fact that all modern tools endorse this approach is ample proof of its effectiveness. From its initial conception, the Magic programming tool was designed to support Rapid Application Development and Deployment. Its unique table-driven architecture facilitates a dynamic and iterative approach to development where users can be involved in the development process and see their applications evolve in front of their eyes.
Page 17
Lesson 2 Installation, Setup and Execution

PURPOSE OF THIS LESSON Learn how to install, register and setup uniPaaS KEY TERMS Licenses Database Manager System (DBMS) Database Gateways The MAGIC.INI File OBJECTIVES Verify systems requirements Install uniPaaS Setup your own License Configure uniPaaS to use the DBMS of your choice CONTENT OUTLINE 1.2.1 Introduction 1.2.2 System Requirements 1.2.3 The uniPaaS CD 1.2.4 uniPaaS Installation 1.2.5 Directory Structure 1.2.6 Activation of the Database Gateways 1.2.7 Entering your License 1.2.8 The Magic.ini File
Page 18
1.2.1 Introduction
This lesson will cover the contents of the uniPaaS CD, the installation procedure, and the different versions of uniPaaS, the initial setup, and the registration process.
1.2.2 System Requirements

The following table shows the minimum system requirements for the installation of the Studio version of uniPaaS: Platform: Processor: RAM: HD Free Space: Screen Resolution: Network Protocol: Other Software for Web Development: Windows 2000/XP/2003(Standard Edition)/Vista Pentium @ 1GHz of speed 512 MB or more 300 MB (Minimum recommended) 1024 x 768 (Minimum recommended) TCP/IP Web Servers: Personal Web Server, IIS or Apache. Support Software: .NET Framework (Web and RIA development is not covered on this course)
1.2.3 The uniPaaS CD

The uniPaaS CD provided with this training material will contain the following folders: CDs Root Folder Itl_Support\ Java\ Contains the installation files for Magic's uniPaaS Contains support files for the Italian language for the AS\400 platform Contains the Java environment and the Systinet application. Systinet allows uniPaaS applications to connect to Web Services and become a Web Service as well. Contains support files for the Thai language for the AS\400 platform
Thai_Support\
Page 19
Follow these steps to be able to see the contents of the uniPaaS CD without executing the installation process
1. Insert the uniPaaS CD on your CD drive and hold down the <Shift> key until the light on this drive stops blinking, this will prevent the automatic installation of uniPaaS to start. If the installation anyway, close it 2. On your computers Desktop, double click on the My Computer icon 3. Right click on your CD Drive and select the option Explore
1.2.4 uniPaaS Installation

To start the installation process of uniPaaS, place the uniPaaS CD on the CD drive of your computer, the installation process will start automatically. If the installation process does not start automatically follow these steps 1. On your computers Desktop, double click on the My Computer icon 2. Right click on your CD Drive and select the option Explore 3. Double click on the file named SETUP.EXE; it also maybe named: uniPaaS_015.EXE
Now, we will go step-by-step over the installation of uniPaaS on our computer. Please be aware that the above on-line presentation and the following screen shoots, could make reference to a different uniPaaS product/version from yours.
Page 20
This will be the first screen that the installation process will show us, press the Next button to continue
Figure 4. Installation starts The next screen will display this software license agreement, if you agree with this license, select the correspondent option and press the Next button to continue.
Page 21
Figure 5. License Agreement From the same uniPaaS CD you can install several uniPaaS Products; depending on our development and/or deployment needs, we will need to select the appropriated product. Select the uniPaaS Studio product and press the Next button to continue.
Page 22
Figure 6. Product Selection The Studio part of uniPaaS allows us to develop and test our applications, the Deployment Client part of uniPaaS is only used to run our applications in a Client\Server environment, the Server part of uniPaaS is used to run applications on a remote server, this remote server will receive request from Internet or uniPaaS clients and reply with an answer, Product Components includes several component available for uniPaaS.
Page 23
Never select the Typical option. We will select the Custom, option from the Type of Setup, press the Next button to continue.
Figure 7. Type of Setup
Page 24
Select the directory where do you want to install uniPaaS. For this example, we will install it on the directory C:\MAGIC\UNIPAAS1.5 press the Next button to continue.
Figure 8. Installation Directory Note: You can select any other path for the installation of uniPaaS.
Page 25
On this screen, we can fine-tune the installation of uniPaaS. Depending on the selection that we made on the previous product screen, some items will appear unchecked by default.
Figure 9. Component Selection The following table explains each one of these components and if they are selected for this course or not; once we have made the appropriated selections, press the Next button to continue.
Page 26
Component Name Deployment Modules

Studio Modules Browser based deployment RIA Deployment Middleware Gateways Internet Requesters
Component Description Install the uniPaaS Runtime so we can execute our applications.
Installs the uniPaaS Studio so we can develop our applications. Allows our application to use the Browser Client feature on the Internet. Installs modules required for the uniPaaS Runtime Rich Internet Application engine. Allows our application to listen and process requests from the Internet or third-party software. Will create a virtual directory in your Web Server that points to the folder where the Magic requesters are stored. If you have a Web Server program like Microsofts IIS, the installation process will make the necessary configuration to this program. If you are going to install IIS after the uniPaaSs installation, you will have to make these modifications manually.
Select
Yes Yes Yes Yes Yes/
Yes/
Database Gateways Bundled Products
Will allow our application to store and retrieve information on any of the supported Database Manager Systems uniPaaS bundles some programs with its installation: BD2 Express. Free database to develop, and deploy CVS. Free version of the Control Version System Magic Optimizer. The limited version of this program allows you to check your Project for problems and suggests changes for improvement RM converter. If you have an application in a previous version of Magic (eDeveloper 9.4) you can use this program to convert it into a uniPaaS Project FlexLM is third-party software that Magic utilizes to manage the use of its products
Yes/
FlexLM License Server
No This program is no longer used since eDeveloper version 9.4 SP3 On-line Documentation Hardware Protection Browser Methodology Demo iSeries Products Messaging Component Fundamentals of uniPaaS v1.5 These are a group of .PDF files that contains reference material about the Magic uniPaaS product This is only required for South America and overseas; the US version of uniPaaS does not require hardware protection This is a sample Project that uses the Browser technique to deliver web applications; some configuration is required. Allows uniPaaS to access data and program stored in an iSeries system. Allows Magic to send and receive messages to different Messaging servers: MSMQ, JMS, Web Sphere Yes No No
Yes
Page 27
Component Name WinRunner Support
Web Services Framework
Component Description If you already have Mercury Interactive's testing tool WinRunner, you must install this option so it can work with uniPaaS. Will allow our application to become a Web Server provider and\or consumer
Select
No Yes
Install the ALL the options from this section Depending on your environment, select the option that you want to install.
Even when we have chosen to install all the options in the Internet Requesters and the Web Services Framework, this training manual will not deal with Internet or Web services programming.
Page 28
On this screen, you can select the language(s) on which the uniPaaS interface will be displayed. Press the Next button to continue.
Figure 10. Language Selection Do not confuse this screen with the Multi Lingual Support (MLS) feature that uniPaaS offers. The MLS functionality can translate the screens text of the same application into different languages to different users at the same time.
Page 29
Depending on the selection made in the Components screen, the following screen may not be displayed. If displayed, we will choose to install the uniPaaS Broker as an Executable and press the Next button to continue.
Figure 11. uniPaaS Broker Installation The uniPaaS Broker is required for the development and deployment of Internet, Partitioning and RIA applications. The Broker works as the Phone Operator that will connect all the request coming from the Internet with available threads from one or many uniPaaS Runtime Engines running on a single or multiple servers. On a development environment is recommended to install the uniPaaS Broker as an Executable, so the programmer can see registered engines, available threads, total number of requests and usage information. On a deployment environment, installing the uniPaaS Broker as a service makes more sense since the Broker will be executed without the need for a user to log into the computer. Performance-wise, there is no difference between installing the Broker as an executable or as a Service.
Page 30
Depending on the selection made in the Components screen, the following screen may not be displayed. Select the name for the different alias folders that will contain different files to support the RIA functionality and press the Next button to continue.
Figure 12. Alias Folder Names Note: It is recommended to use the default names for the different alias folders.
Page 31
Select the name for the folder that will contain the uniPaaS icons and press the Next button to continue.
Figure 13. Program Folder Note: The above Figure may denote a different program folder from your own installation.
Page 32
Next, we need to specify the location of our license file. For this course, we will Use demo license. Later on the course, we will apply a real license to bypass the limitations of the demo license; press the Next button to continue.
Figure 14. License File Note: The above Figure may denote a different path and file name from your own installation. The demo license does not limit the use of the features of uniPaaS, the limitation is enforced on the size of our Project:

Maximum number of Data Sources (Tables or data files) is 20 Maximum number of Programs is 150 Maximum number of records per Data Source is 500
Page 33
A summary of our selections for the installation of uniPaaS will be displayed. Press the Next button to start the installation process.
Figure 15. Installation Summary Note: The above Figure may denote different summary information from your own installation.
Page 34
1.2.5 Directory Structure

All the files that belong to uniPaaS are stored inside the installation directory specified. The following table explains the structure of this directory; please notice that you may not have some of these directories: uniPaaSs Root Folder\ Add_On\ Browser_Client_Cache\ Builders\ cvs_client Gateways\ Projects\ RIACache\ RIAModules\ Scripts\ This is the root directory. It contains all the executables and configuration files for uniPaaS to be able to run This directory holds component applications included in the Magic Development environment This directory contains cached XML files used for Browser Client applications This is the default directory that will store any components that you can create in uniPaaS This directory contains the client software from a version control system This directory contains all the installed Magic Gateways This directory will contain all the projects that you will develop using uniPaaS This directory will store Cached files to speed up the communication between the client and the server This directory contains Java and .NET modules that will enable the RIA functionality on the client side. This directory contains Web Server\Services Server-Side supporting files required to run Magic as a Web Application Server and/or Web Service This directory contains Web Services Client-Side supporting files required to connect our project to a Web Service This directory contains supporting files for uniPaaS (language, colors, fonts, actions), On-line help and .PDF documents This directory contains the required files to make WinRunner work with uniPaaS (if installed)
SoapClientModules\
Support\
WinRunner\
Page 35
1.2.6 Activation of the Database Gateways

Once you have installed both, the Gateway(s) and the DBMS of your choice, you will need to activate the desired Gateway(s).
Follow these steps to activate/deactivate the uniPaaS Gateways
1. Close any uniPaaS Studio and Runtime that might be running 2. Go to Start | Programs | uniPaaS | Edit MAGIC.INI (This MAGIC.INI file is located in the root of the uniPaaS folder and you can open it manually if you wish to.) 3. Locate a section called [MAGIC_GATEWAYS] near to the end of this file 4. Use the following table to match a Gateway entry with your DBMS:
Magic Gateway
MGDB00=GATEWAYS\MGBTRIEVE.DLL MGDB03=GATEWAYS\MGMYSQL.DLL MGDB06=GATEWAYS\MGDB400.DLL MGDB13=GATEWAYS\MGORACLE.DLL MGDB16=GATEWAYS\MGEAC32.DLL MGDB18=GATEWAYS\MGDB2.DLL MGDB19=GATEWAYS\MGODBC.DLL MGDB20=GATEWAYS\MGMSSQL.DLL MGDB21=GATEWAYS\MGMEMORY.DLL
Database Manager System

Btrieve (Pervasive Transactional Engine) MySQL DB\400 Oracle (ver. 8 and up) AS\400 connectivity DB2 ODBC (Access, Clipper, Dbase, FoxBASE, etc.) Microsofts SQL (version 7.x and up) uniPaaS's own Memory Database
5. To activate a Gateway, just delete the semicolon (;) that is located at the beginning of its line 6. To deactivate a Gateway, just place a semicolon (;) at the beginning of its line 7. Verify that the specified .DLL file for the active Gateway actually exist on their referenced paths
8. Save the changes made to the MAGIC.INI file. uniPaaS will load all the uncommented Gateways the next time you run
Page 36
Execute the uniPaaS Studio, go to the pull down menu Help | About and compare the list of Loaded Modules with the uncommented Gateways
Failed to load driver...
Not because we have enabled a Database Gateway it means that we will be able to use it For example: If we enable the DB2 Gateway but we do not have this database installed in our computer, uniPaaS will send an error telling us that it Failed to load driver for DB2 In order to solve this problem we will need to either, install the DB2 Database software in our computer or disable this Gateway entry
Page 37
1.2.7 Entering you License

uniPaaSs license information is contained inside a file called LICENSE.DAT, this file is located in the root of its installation directory. If you open this file with any text editor, you will see information similar to this: SERVER MYSERVER ANY TCP:744 DAEMON MAGIC lmg.exe FEATURE MGDEMO MAGIC 1.000 01-jan-0 1 FB8E30711613D6DAC92D \ VENDOR_STRING=PT=MGDEMO,C=3FFFFFF,P=N,MR=500,MP=150,MD=20,MC=3 \ DUP_GROUP=NONE ISSUER="Demo license" ck=3 SN=612345675 FEATURE MGCSTK MAGIC 1.000 30-jan-2009 1 221406E8262BFEAAD0A4 \ VENDOR_STRING="PT=MGCSTK,C=3FFFFFF,P=N ,M=1,SSL=N" OVERDRAFT=0 \ DUP_GROUP=UHD ISSUER=Demo License ck=185 SN=128260491 FEATURE MGENT1 MAGIC 1.000 30-jan-2009 5 278466289761D14C0ADD \ VENDOR_STRING="PT=MGENT1,C=3FFFFFF,P=N ,M=0,SSL=N" OVERDRAFT=0 \ DUP_GROUP=NONE ISSUER=DEMO ck=218 SN=928260582 Figure 16. Sample License File On the above figure we can see three different licenses or features: MGDEMO, MGCSTK and MGENT1. A single LICENSE.DAT file can contain several licenses for many uniPaaS Products, like: Studio, Runtime for Client\Server applications, Runtime for Partitioning applications, etc. Every uniPaaS product has its own Feature\License Name:
Feature/ License Name MGRIA

MGCSTK MGDEMO MGENT1 ENT_USRV1 ENT_PSRV2 ENT_PSRV1
Product Description
RIA Extension Light uniPaaS Client\Server Toolkit uniPaaS Demo Toolkit and Runtime uniPaaS Enterprise Server Light uniPaaS Enterprise Server uniPaaS Partitioning Server uniPaaS Partitioning Server
Characteristics
Runs applications using the Rich Internet Application functionality Creates any application (C\S and Web), access all DBMSs Creates small applications (C\S and Web) based on the DEMO License, access all DBMSs Runs any size application in a Enterprise Web environment (Windows and Linux Servers), access all DBMSs Runs any size application in a Enterprise Web environment (Unix and AS\400 Servers), access all DBMSs Runs any size application in a Partitioning Environment (Windows and Linux Servers), access all DBMSs Runs any size application in a Partitioning Environment (Unix and AS\400 Servers), access all DBMSs Lesson 2 Installation, Setup and Execution
Page 38
Follow these steps to extract and apply your acquired uniPaaS licenses
1. Close uniPaaS 2. Open the email message sent by your salesperson at Magic; in there you will find an attached file called LICENSE.ZIP, save this file inside your uniPaaS installation folder for save keeping 3. Once saved, open this compressed file and locate a text file with a name similar to: 327805268.TXT. If you bought more than one license, you will find several files like this one If you find a second .ZIP file inside the first one, the text file will be inside of it. 4. Open this text file(s) 5. Inside this file you will find a paragraph similar to this: FEATURE ENT_STD MAGIC 10.000 01-jan-0 1 87616618WE8FDFF7098 \ VENDOR_STRING="PT=MGCSTK,C=3FFFFFF,P=N \ ,M=1,SSL=N,MED=31-dec-2007,BC=98748688F2WE24359861" \ OVERDRAFT=0 DUP_GROUP=UHD ISSUER=" uniPaaS Demonstration " ck=209 \SN=727805244 6. Copy this paragraph into you clipboard and close this text file. Do not copy the two lines at the top of the file that start with SERVER and DAEMON 7. In the root of your uniPaaS installation folder, you will find a file called LICENSE.DAT; open this file with any text editor
8. At the end of this file, create a new line and paste the information that you just copied into your clipboard. Make sure that you do not have duplicated Feature names. Take notice of the Feature\License Name for the license that you want to use with your Studio or Runtime. Save the changes made to the LICENSE.DAT and close it 9. In the root of your uniPaaS installation folder, you will find a file called MAGIC.INI, open it with any text editor 10. Look for an entry called LicenseName. Set the value for this setting with the same name as the Feature\License that you want to use. Save the changes made to this file 11. The next time we execute uniPaaS (Studio or Runtime), it will use the this specified license
Execute uniPaaS (Studio or Runtime), go to the pull down menu Help | About and verify that the license used is the same as the one you specified
Page 39
1.2.8 The Magic.ini File

Before we start creating new Projects we are going to take a look at the main configuration file for uniPaaS, the MAGIC.INI file. The MAGIC.INI file is located in the same folder where uniPaaS resides, every time uniPaaS is executed, it will read all its information and keep its information in memory. When uniPaaS is close, it will write it back to the physical file. The following table lists some of its entries inside the [MAGIC_ENV] section and suggests some changes:
Entry Name
Owner DateMode
Description
The name of the company where uniPaaS resides Default mode to display Date information, possible options are: A = American E = Europa and Latin America S = Scandinavian B = Buddhist
Change it to
Your company name Your country's date format
NumberOfRecentProjects Limits the number of Projects displayed in the Welcome screen CenterScreenInOnline AllowTesting ActivateRequestsServer Instructs a program to display a located record in the center of its screen. Instructs to uniPaaS to connect with the testing software.
25 Y N
This setting controls whether uniPaaS will try to N connect to a request broker as an enterprise server. Since this manual will no cover Internet any topics, this setting is not required.
Page 40
Page 41
Lesson 3 Introduction to Developing Projects

PURPOSE OF THIS LESSON Introduce the methodology of developing projects in uniPaaS. KEY TERMS Project Models Tables Unique Key Properties Computer Aided Programming Program Generator OBJECTIVES Name the four steps in the creation of a project Name the menus available only in Studio CONTENT OUTLINE 1.3.1 Introduction 1.3.2 Step to Create a Project The Inheritance Mechanism 1.3.3 Building the Groundwork for a New Project Defining Logical Names Defining Databases Defining a Project Opening the Project
Page 42
1.3.1 Introduction
A Project in uniPaaS can be an address book, an inventory system, an accounting program, a system to manage a store, a game, a phone messaging system, a dispatching system, etc. You could also connect several small Projects in order to create a bigger Project; for example: a Customers Project, a Vendors Project, and an Inventory Project can all call each other to retrieve information and\or execute programs from their counterparts. Inside a Project the developer creates the variables (fields) in which the user will enter information, the tables where the information will be saved, the logic that will control the behavior of the programs that will manipulate this information, the menus to guide the user to these program, a help system and finally, a security system. Each one of these pieces of information will be displayed on different tables to the developer while the Studio, behind the scenes, stores them into XML files inside a folder called Source. Fortunately for us, we do not need to deal with the raw information of all these files since uniPaaS will present them to us in a friendly format.
1.3.2 Steps to Create a Project

The creation of a uniPaaS project could include the following four steps: 1. Creating Models A Model is an object (a variable to store information, a field on a screen, a graphical control, a screen itself, etc.), each Model has a group of properties that will be used across the project. The properties of these Models are reflected when we use them in the creation of Data Sources and Programs. 2. Creating Data Sources The second phase of the development of a project is the definition of Data Sources. A Data Source is a place where information resides; a Data Source could be a data file, a database table or a XML file. The definition (structure) of a Data Source must be declared inside uniPaaS before it can be accessed. It is recommended to use a Model, while defining each column\field for each Data Source. 3. Creating Programs The third phase is the creation of Programs. Programs are tools that the end-users will employ to manipulate the information contained on the different Data Sources. The developer will create the logic that will decide the functionality of each Program.
Page 43
It is recommended to use a Model, while defining any virtual or parameter variables. There are four types of Programs in uniPaaS: 1. On-line a program that interacts with the user by receiving and displaying information on the screen. 2. Batch a program with a defined behavior, this program does not require interaction with the user to be able to work. 3. Browser a program that runs on the web out of a browser (must be Microsoft's Internet Explorer), but it behaves as an On-line program. (This type of program is not covered on this course). 4. RIA Client a program that runs on different platforms (Computer, PDA, Cell phone, etc.), and request information from a remote uniPaaS server. (This type of program is not covered on this course). 4. Creating Menus The Menus are navigation tools for the end-user, to be able to execute a program. The developer creates Menus, defines their properties, and what program will be executed when selected. The Inheritance Mechanism The Inheritance Mechanism in uniPaaS is a feature that automatically synchronizes the relationship between the different Repositories inside a Project when a change is made.
Figure 17. Hierarchy in the Inheritance Mechanism
Models should be the base of every single Project
Page 44
Since a Model is the definition of an object that can be used on a Data Source and\or a Program, any modification to a Model will be carried out towards the Data Sources and Programs For example: if you have a Model called First Name, and it is used in 10 different Data Sources and 100 different Programs, you can go the Model Repository and increase its length (for example), once this change is saved, uniPaaS will automatically do the following:

Go to each Data Source that uses this Model and update its definition. Ask the developer if uniPaaS should convert the physical database to comply with the change made. Go to each Program that has a variable based on this Model and convert its definition to comply with the change. Notice that it will not modify the size or location of these fields on the Program's screen, it will only allow the user to enter more information into it (based on this example).
On the same token, if you make a modification to a Data Source, uniPaaS will go to each Program that uses this Data Source and make the required modifications to comply with the change made. The inheritance mechanism offers the following benefices while developing a project: 1. Saves development time. Once you have created a Model, the developer does not need to retype the properties of this object every time is used inside the Project. 2. Easy of maintenance. Almost any modification performed to a Model, will be immediately reflected to any object related to it. 3. Standardization of the project. By utilizing Models as the base for a project, the developer ensures consistency during the developing phase.
Page 45
1.3.3 Building the Groundwork for a New Project

As any other development tool, uniPaaS can create, execute and maintain different Projects, each one of these Projects may have one or many Data Sources, and each of these Data Sources can be located on different folders in your computer, on different computers, and/or using different DBMSs; at the same time the project could make reference to physical files stored inside a specific directory. uniPaaS has a very efficient and easy way to organize the access to physical files and DBMSs with the concept of Logical Names and Databases.
Logical Names are global variables available to all the projects that share the same configuration file (the same MAGIC.INI file). They are mainly used to specify the location of physical files.
Since Logical Names entries are not stored inside the Project but in the MAGIC.INI file, under a section named [MAGIC_LOGICA_NAMES], there is not need to open the Project in order to make a change to a Logical Name entry.
Databases can help us organize and maintain the location of different Data Sources within our Projects. Similarly to the Logical Names concept, we can change the definition of these Databases with our the need to open the Project; for example: we can tell our Project to use the Test data stored in Server1 instead of the Live data from Server2 just by changing a single Database entry.
If we are using Pervasive.SQL\Btrieve as our DBMS, we will use a combination of Logical Names and Databases as a way to point to the physical location where our data files are stored (C:\DATA\, H:\APPS\ DATA\, etc.) If we use any other DBMS like: Oracle, MSSQL, ODBC, etc., we will only use a Database entry to hold the information about the Database Server, how to login, and the Database or Data Source Name. Once we have defined our Logical Names and Databases in uniPaaS, we will associate them into our new project and the Data Sources inside of it.
Execute uniPaaS (Studio or Runtime), go to the pull down menu Help | About and verify that the license used is the same as the one you specified
Even when is not imperative the setup specific Logical Names or Databases for every Project, it is a good maintenance and programming technique that will make the process of moving our Projects from one environment to another much easier
Even when is not imperative the setup specific Logical Names or Databases for every Project, it is a good maintenance and programming technique that will make the process of moving our Projects from one environment to another much easier
Page 46
Defining Logical Names We are going to define a Logical Name called MyComicStore_Data we will use this Logical Name as the pointer to the location where our data files are located. Logical Names are stored in the MAGIC.INI file, under a section named [MAGIC_LOGICAL_NAMES]. If we want to, we can open the MAGIC.INI file and modify the Logical Names directly, but we need to make sure that both the Studio and the Runtime are closed, otherwise, our changes may not be saved. If you are planning to use a DBMS other than Btrieve\Pervasive.SQL, it is not necessary to create a Logical Name.
Follow these steps to create a Logical Name
1. Open the uniPaaS Studio 2. Go to the pull down menu Options | Settings | Logical Names 3. Create a brand new line on this table by pressing the <F4> key 4. On the Name column for the newly added line, type MyComicStore_Data 5. On the Translation column, type: %WorkingDir%Data\ Make sure that the string %WorkingDir% is typed exactly as showed; also, do not forget to type the backslash at the end of the path 6. Press the OK button to save these changes
Page 47
Figure 18. Logical Names As mentioned before, the Logical Name MyComicStore_Data will be used to point to the physical location of data files that will be use by our project; this location could be: C:\DATA\ or F:\EDEV\MYSTORE\DATA\ or even \\SERVER\APPS\DATA\. Most of the time, a valid path is the only thing that the Translation column needs for a Logical Name to work. In this training manual, we are going to try to keep all the external files for this Project inside the same directory as the Project itself; this will reduce the maintenance cycle every time we move or deploy a Project into a new environment. Here is where the WorkingDir Logical Name makes its appearance. The WorkingDir is an internal Logical Name in uniPaaS, we can see it being displayed in the top part of this window. This Logical Name will always point to the root directory for the Project that the Runtime is running at this moment; we will learn more about the Projects directory once we create our first Project. In the Translation column we surrounded this logical name with the percent (%) character to tell uniPaaS that this is a Logical Name and we will like to replace its string (WorkingDir) with the actual path were the current project resides, the final result could look like this: C:\MAGIC\UNIPAAS\PROJECTS\ MYCOMICSTORE\ On the same token, the Logical Name MyComicStore_Data will be translated into: C:\MAGIC\UNIPAAS\ PROJECTS\MYCOMICSTORE\DATA\ when we execute the Project in Runtime. From this point forward, the Logical Name MyComicStore_Data will always point to a folder called Data under the directory where the current project is located.
Page 48
Any directories specified for Logical Names must be created manually; uniPaaS will not create new directories.
The name of a Logical Name is always case-sensitive. Their Translation may be case-sensitive depending of the operative system.
There is no naming convention for Logical Names; but since they are shared across projects, is convenient to denote to which Project they belong to.
To make reference to a Logical Name any place within your Project, surround its name with the percent (%) character
Page 49
Defining Databases Following the way Logical Names work, Databases are shared across all the projects that utilize the same configuration file (the same MAGIC.INI file). Databases in uniPaaS are utilized to configure the connection between the Data Sources in a Project and their correspondent physical data files, SQL Servers, Databases or ODBC entries. For example: we could define in our Project a Database called Accounting which will use Btrieve to access its files from the T:\ACCTG\ drive; another Database called Inventory that will use MSSQL to access its tables from a different sever; and finally, a Database called Customers that will use ODBC to access the information from a third-party software, etc. Later on, if we decide to move the location of anyone of these databases we just need to apply such modification to its Database entry, and since Databases entries are stored in the MAGIC.INI file, under a section named [MAGIC_DATABASES] there is not need to open the Project or.
Before making any changes to the Database and\or the Logical Name using uniPaaS, we must be sure that no other Studio or Runtimes are running at that moment; otherwise, our changes may not be saved After making changes to the Database and\or Logical Name entries it is recommended to close uniPaaS completely
The following pages will show you how to create a Database entry to connect to a Data Source using Btrieve\Pervasive.SQL, MSSQL or ODBC; please only perform the one that matches your environment.
Page 50
Follow these steps to create our Database (for Btrieve\Pervasive.SQL Databases)
1. Open uniPaaS, but do not open any Project 2. Go to the pull down menu Options | Settings | Databases 3. Create a brand new line on this table by pressing the <F4> key 4. On the Name column for the newly added line, type MyComicStore 5. On the DBMS column, press the <F5> key and select Btrieve 6. Clear the information from the Database Name column since is not required for the Btrieve DBMS 7. On the Location column, type: %MyComicStore_Data%
8. Press the OK button to save these changes
Page 51
Follow these steps to create our Database (for MSSQL Databases)
1. Open uniPaaS, but do not open any Project 2. Go to the pull down menu Options | Settings | Databases 3. Create a brand new line on this table by pressing the <F4> key 4. On the Name column for the newly added line, type MyComicStore 5. On the Database Name column type unipaascourse 6. On the DBMS column, press the <F5> key and select MicrosoftSQLServer 7. Press the <Alt+Enter> keys to go to the properties of this entry
8. In the Login tab, type the Database Server name or IP address, the User Name and the User Password that uniPaaS will use to connect to this server 9. In the SQL tab, check the box called Check Existence 10. Press the OK button to save these changes
Page 52
Follow these steps to create our Database (for ODBC connections) 1. Open the ODBC Data Source Administrator screen of your system and setup an ODBC connection called unipaascourse. Configure this entry to connect to any available DBMS on your system (MySQL, Access, FoxBase, etc.) 2. Open uniPaaS 3. Go to the pull down menu Options | Settings | Databases 4. Create a brand new line on this table by pressing the <F4> key 5. On the Name column for the newly added line, type MyComicStore 6. On the Database Name column type unipaascourse (the name of the ODBC entry) 7. On the DBMS column, press the <F5> key and select ODBC
8. Press the <Alt+Enter> keys to go to the properties of this entry 9. In the SQL tab, check the box called Check Existence 10. Press the OK button to save these changes
There is no relation between the name of a Database, the name of a Logical Name, and the name of our Project We only decided for them to have similar names for ease of use and maintenance
uniPaaS will not inform you if you entered an invalid Logical Name in the Location column or any other place. If you used an invalid Logical Name, uniPaaS will return an empty string when you try to translate it.
Page 53
Figure 19. Databases Note: The above figure denotes the three possible configurations covered in this manual, you should have only the entry that corresponds to your DBMS The Name column is how any Project will be able reference and use these Database entries. The Data Source Type column, tells uniPaaS if this entry will try to connect to a regular database (Btrieve, Oracle, MSSQL, ODBC, etc.) or to an XML File. The Database Name column only applies to SQL-type Databases and ODBC; it is not irrelevant if you are using Btrieve as your DBMS. When need it, this setting specifies the actual name of the database that we are trying to connect to on a SQL-type Server, or the name of the Data Source that we want to connect to via ODBC. The specified Database Name has to exist as a Database on the SQL Server or as a Data Source in ODBC since uniPaaS will not create them
The DBMS column tells uniPaaS what Gateway to use to connect to this database. We can choose it from the DBMS List by pressing the <F5> key on this field. This list will only show Magic Gateways that were loaded successfully.
Page 54
If you do not see the DBMS entry that you need on this list, go to the section: 1.2.6 Activation of Magic Gateways to enable the missing Database Gateway
In the Location column, we need to specify the physical location on which the files associated to this Database are located. This setting only applies if you are connection to a Btrieve data file or to an XML file; if you are using DB\400, then the Library Name will go in here.
If the Location column is empty, Btrieve data files and XML files will be saved inside the root directory for uniPaaS
Figure 20. Database Properties - Login The Database Server field must have the name or IP address for the server that we want to connect to. The User Name field must have the name of a valid user to connect to the database server. The User Password field must have a valid password to connect to the database server.
Page 55
We can use Secret Logical Names instead of the real values for these fields in order to hide their information. Secret Logical Names are explained in Lesson 21 Creating a Security System
Figure 21. Database Properties - SQL The Check Existence option will tell uniPaaS to check for the existence of a table every time is accessed by the project; if the table does not exist uniPaaS will create it, otherwise, it will just access it as specified by the program. If uniPaaS tries to open a table that does not exist, you will receive the error message similar to this: Invalid object name 'unipaascourse..Customers'.
Page 56
Defining a Project We are going to create a Project called MyComicStore. You can have spaces on the name of our project if you wish to. Follow these steps to create our Project
1. Open uniPaaS 2. Go to the pull down menu File | New Project 3. On the Project Name field type: MyComicStore 4. Leave the Location field with its default value, this way, the project will be stored within the uniPaaS directory, under the Projects folder 5. Press the OK button to save these changes
Figure 22. New Project Window Note: The above Figure may denote a different Location from your own installation. If you get a confirmation window asking you to create the Location path, answer Yes
Page 57
At the end of this process, if you open the folder specified in the above Location field, you will see the following information:
Figure 23. The Project Folder Note: The above Figure may denote a different Folder name from your own installation.
Page 58
Opening the Project Once we have created our Project, we can see its name in the title bar of the uniPaaS windows and in the status bar at the lower-left corner. If we close the Project, we can open it again by selecting it from the list of Recent Projects. This list of Projects is maintained by uniPaaS automatically and it is stored inside your Windows registry.
Figure 24. The uniPaaS Studio Note: The above Figure may denote a different Project File from your own installation.
Page 59
Part 2 uniPaaS Programming

Lesson 4 Model Repository
PURPOSE OF THIS LESSON To understand how to use and define Models KEY TERMS Class Attribute Format Alpha Attribute Numeric Attribute Date Attribute Time Attribute Range OBJECTIVES Define the required Models for our Project CONTENT OUTLINE 2.4.1 Introduction 2.4.2 Creating Models 2.4.3 Classes and Attributes 2.4.4 Picture Usage 2.4.5 Syntax Rules for Constructing Pictures 2.4.6 Ranges
Page 60
2.4.1 Introduction
In this lesson, you will see how Models will play a fundamental part in the process of developing a Project and, in particular, how the Model Repository makes the development and maintenance of the Project a lot easier. Besides being able to create Models of variables to be used within the application, uniPaaS offers the ability to create Models for user screens, help screens, HTML forms, GUI Controls, etc. This lesson will just cover the creation of Models to be used as data manipulation variables. Data Consistency and Validation By defining data elements in the Model Repository, Magic developers can rest assured that data definition, display format, and data validation will be consistent throughout all subsequent data sources, forms (screens), reports, and programs. For example: By defining a phone number data type in the Model Repository with an associated picture or display format of (###) ###-####, the developer needs only to refer back to that Model in order to get the correct display format for input/output data. If a change to the Phone Number Model is required, the developer only needs to change the Phone Number Model. Once the change is done, uniPaaS will check all the tables and programs for the occurrence of the Phone Number Model and update each one automatically, including physical data conversion of tables. Making these changes uniformly throughout the system maintains data consistency and integrity.
Page 61
2.4.2 Creating Models

To create Models in uniPaaS we can use both, the mouse or the keyboard; the following steps will show you how to create a Model using just the keyboard:
Follow these steps to create the Customer Number Model
1. Open the project 2. Press the <Shift+F1> keys to go to the Model Repository 3. Create a new line by pressing the <F4> key 4. On the Name column, type: Customer Number 5. On the Class column, select Field 6. On the Attribute column, select Numeric 7. Press the <Alt+Enter> key to go the Properties Panel for this Model
8. On the Property Panel, inside the Detail section, in the Picture field, type: #9 9. Press <Enter> to return to the Customer Number Model
Page 62
Figure 25. The Model Repository In the Name column type the name for this Model; it can be up to 30 characters and it can contain upper and lowercase characters, numbers and spaces. The Class column tells uniPaaS what kind of Model it is; a Field, a Help Screen, a GUI Screen, a Tab Control, a Button, etc. The Attribute narrows down the specifics of this Model for the selected Class
Page 63
2.4.3 Classes and Attributes

Each Model in our project can be defined with different Classes. For a Model, a Class is the way you specify what kind of Model it is, a variable, the screen of a program, a control in a form, a help screen, etc. Depending of the Class of a Model, you can select different Attributes. The following section shows some of the Classes available in the Model repository and their Attributes:
Help
User help screens. There are two kinds of attributes:
Attribute Internal Windows
Description Uses an internal Magics screen to display help to the user Call a help screen from an external .HLP file.
Page 64
Field
Fields are used to store information inside a Table, and to display information on screens. Fields have several possible attributes:
Attribute Alpha
Description A string of alphanumeric characters. The maximum length for virtual variables is either 32Kb, the amount of available memory, or maximum column and row lengths of the underlying database.
Unicode is a universal character set designed to encompass all written languages. It also supports many classical and historical texts in written languages. An integer or decimal number. Magic supports up to 18 digits, with the condition that the number of whole digits and decimal digits are each rounded up to the nearest even number. A field usually stored internally as a single byte with value either 0 or 1. Use logical attributes when you are storing pairs of values, such as TRUE/FALSE, Black/White, and Yes/No. Logical attributes are usually accessed more quickly than their equivalent Numeric attributes. 0 represents FALSE and 1 represents TRUE. An attribute that Magic stores internally as Numeric although it can also be specified as a String attribute. The numeric date attribute is a counter of days since 01/01/1901. The fact that a Date attribute is stored as a numeric value lets Magic perform date calculations with ease. A Date attribute is translated to its visible value only when it is displayed. An attribute that Magic stores internally as a counter of seconds since midnight. You can use a Time attribute to represent either duration of time or an absolute time value. Just as with Date attributes, Time attributes can be subtracted from one another, and values can be added to or subtracted from them. A Time attribute is translated to its visible value only when it is displayed. A Binary Large Object. An attribute that contains binary information not created in Magic, and of unknown size. Magic stores the information as is, without understanding the contents. A common use for Blob attributes would be to store OLE objects or image bitmaps. Functions cannot act on Blob attributes with the exception of the NULL() function that will return TRUE to signify an empty blob. A BLOB field that is used to create an instance of an OLE COM object. A BLOB field that is used to create an instance of an ActiveX COM object. A Vector is a single column array that lets you store and retrieve data from a specified cell index. The Vector attribute is based on the BLOB attribute with an additional cell model property.
Unicode Numeric
Logical
Date
Time
Blob
OLE ActiveX Vector
Page 65
GUI Display
This Model has all controls that can be placed on a screen. Their attributes are:
Attribute Form Edit Static Push Button Check Box Radio Button Tab List Box Combo Box Line Slider Table Column Image OLE Rich Edit Tree ActiveX SubForm
Description A GUI screen, a Print Form, or a template to import\export information An Edit control where the user can enter or view information A control with constant data A Push Button control A Check Box control A Radio Button control A Tab control A List Box control A Combo Box control A Line control A Slider control A Table control (also called Data Grid) A Column control inside a Table An Image control An OLE control A Rich Edit Control A Tree control An ActiveX control A control that will display information from a different Task or Program
Page 66
2.4.4 Picture Usage

A Picture is a string of characters that tells a Field Model how to define the format of an attribute. You can specify the Picture format in the Picture dialog, which can be accessed from the Picture property in the Details section of the Field Properties sheet. These are some examples of Fields with different Pictures:
Sample Field Name Last Name

City
Attribute Type Alpha

Alpha
Picture
XXXXXXXXXXXXXXX or 15 or X15 UXXXXXXXXX or UX9 or U1X9
Description
A 15-character alphanumeric string A 10-character alphanumeric string; first character will be forced to be upper-case A 30-character alphanumeric string; all characters will be forced to be lower-case 3-digit integer field A Date field forced to be entered in American Format Date field (its format will depend on the Date Mode setting from the pull down menu Options | Settings | Environment | International) A numeric field that can store 3 whole digits and 2 decimals, the percent (%) character will be displayed to the right of this number An Alpha field forced to receive only numeric characters; the data will be formatted to the U.S. Phone.
Email Address
Alpha
LLLLLLLLLLLLLLLLLLLLLLLLLLLLLL or L30 ### or 3 or #3 MM/DD/YYYY ##/##/####
Order Number Order Date Due Date
Numeric Date Date
Percent
Numeric
###.##% or 3.2% or #3.#2% or #3.2% or 3.#2%
Phone Number
Alpha
(###) ###-####
Each Picture is compose of three types of characters: 1. Symbolic characters interpreted as Functional Directives. 2. Symbolic characters interpreted as Positional Directives. 3. Characters used with their proper value as Mask Characters. For a Field class, each attribute has its own set of picture directives.
Page 67
A Functional Directive is a picture character that is interpreted the same way regardless of its location in the picture. For example, in the following five pictures: N#### ####N ##N## N#4 N4
Functional Directives
Each one of these pictures defines the same 4-digit numeric integer attribute. The N character is the Functional Directive that specifies that the attribute may contain negative values. The exact location of N inside the picture string is irrelevant, as is the location of any other functional directive.
All functional directives must appear in upper case
Positional Directives
A Positional Directive is a picture character used as a placeholder, therefore, it is interpreted with respect to its position in the picture string. For example, in the following three pictures: As their name denotes, the position of any Positional Directive is critical All Positional Directives must appear in upper case UXX XUX XXU
Each one of these pictures defines a different 3-character Alpha attribute. The positional directive U for an Alpha attribute instructs uniPaaS to convert the character corresponding to the U position to upper case during data entry from the keyboard. The picture UXX forces the conversion of the first typed character to be upper case, while the picture XUX forces the conversion of the second typed character, and so on.
As their name denotes, the position of any Positional Directive is critical All Positional Directives must appear in upper case
Page 68
Mask Characters
Any character that appears in a picture string and is neither a Functional or a Positional directive for the specific attribute is considered as a Mask Character. Mask characters are inserted into the actual attribute value during display. For example, the string $##### defines a 5-digit numeric integer attribute that is always displayed with a preceding dollar sign.
The position of a mask character is critical. Specifying the dollar sign at the rightmost position of the picture: #####$, causes the dollar sign to be displayed at the rightmost position of the field. Mask Characters influence neither the size of the stored attribute nor its internal representation; in other words, Mask Characters are not saved into the data. Mask Characters may appear several times in a picture.
2.4.5 Syntax Rules for Constructing Pictures

Case Sensitivity
Functional and Positional Directives must always be specified in upper case letters. Lower case letters are interpreted as mask characters only. For example:

The picture XXXXX defines a 5-character Alpha attribute. The picture XXxXX defines a 4-character Alpha attribute with the intermixed mask character x. As mentioned before, the x character will not be saved into the data.
Escape Characters
The escape character (\) explicitly specifies that the character immediately following it is a Mask Character. This allows you to override the implied meaning of the directive character and to use a Mask Character instead. For example:
The picture XX\XXX defines a 4-character Alpha attribute with the Mask Character X in the middle. This picture shows the character (\) telling uniPaaS to interpret the X that follows as a Mask Character and not as a Picture Character. Suppose that we have a four-digit numeric field containing a weight expressed in pounds and we want to display the letters Lb to the right of the value. If we simply specify the picture ####Lb, uniPaaS will interpret the L as the Lower Case Directive, which is not what we want. The correct picture for our needs will be: ####\Lb. To utilize the escape character (\) as a Mask Character by itself, simple specify it twice as in (\\)
Page 69
Count Value
The Count Value is a quick method of repeating the same character consecutively in a picture. The Count Value is a number that we place after a Mask Character, this number indicates how many times the Mask Character must be repeated. For example:

$#4 X6 X3U2
means: $#### means: XXXXXX means: XXXUU
The Count Value can be used for both, Positional Directives and Mask Characters. The following tables summarizes the Positional and Functional Directives for the different attributes of a Field class Model:
Alpha Attribute
Directive X(n) U(n) L(n) #(n) A Description Holds a place Holds a place Holds a place Holds a place Automatically information.
for any alphanumeric character for any alphanumeric uppercase character for any alphanumeric lowercase character for any numeric character moves the cursor to the next field if the current one is filled up with
Numeric Attribute
Directive #(n)
. C N P(c)
Z(c)
-(prefix),(suffix);
+(prefix),(suffix);
A
Description Holds a place for any numeric (0,1,2,3...8,9) or arithmetic (. , - + * /) characters. Indicates the location of the decimal point This directive instructs uniPaaS to insert commas as thousands separators in the field. This directive tells Magic that this variable may contain negative values. This directive instructs uniPaaS to pad the remaining of the available space on this field with the specified character In the case that the value of this field is zero\empty, this directive will instruct uniPaaS to fill it up with the specified character If you want to denote negative values with something other than the minus (-) sign, enter the string that will be displayed before the amount (prefix) and\or after the amount (suffix) If you want to denote positive values, enter the string that will be displayed before the amount (prefix) and\or after the amount (suffix) Automatically moves the cursor to the next field if the current one is filled up with information.
Page 70
Date Attribute
Directive YY YYYY
MM MMM... DD DDD DDDD +(prefix),(suffix); W WWW... / Z(c) T
A MM/DD/YY DD/MM/YY YY/MM/DD DD-MM-YY YY.DDD ##/##/##
MMMMMMMMMM^DD DD,^YYYY MMMMMMMMMM^DD DD,^YYYYT WWWWWWWWWW^ -^WW WWWWWWWWWW^ -^WWT
Description A place holder of the number of the year (0-99) A place holder for the number of the year, represented in full format (e.g. 1993) A place holder for the number of the month in a year (1-12) Month displayed in full name form (up to 10 Ms in a sequence). e.g. January, February. If the month name is shorter than the number of Ms in the string, the rest of the M positions are filled with blanks. A place holder for the number of the day in a month (1-31) The number of the day in a year (1-366) The ordinal day number in a month displayed as 1st, 2nd, 3rd, 4th, etc. If you want to denote positive values, enter the string that will be displayed before the amount (prefix) and\or after the amount (suffix) Day number in a week (1-7) Name of day in a week (e.g. Monday, Tuesday). The string can be from 3 to 10 Ws. If the name of the day is shorter than the number of Ws in the string, the rest is filled with blanks. Date separator position. The system will replace this character with the character defined in the Environment dialog as the Date separator. In the case that the value of this field is zero\empty, this directive will instruct uniPaaS to fill it up with the specified character This directive instructs uniPaaS to remove any blanks created by the positional directives WWW... (weekday name), MMM... (month name), or DDDD. Since these positional directives must be specified in the picture string using the maximum length possible, unwanted blanks may be inadvertently created for names shorter than the specified length. Automatically moves the cursor to the next field if the current one is filled up with information. Forces the data to be entered and displayed in this format. Forces the data to be entered and displayed in this format. Forces the data to be entered and displayed in this format. Forces the data to be entered and displayed in this format. Forces the data to be entered and displayed in this format. Forces the data to be entered and displayed in the format specified in the Date Mode: 04/21/97, when the Date Mode setting is set to American 21/04/97, when the Date Mode setting is set to European 97/04/21, when the Date Mode setting is set to Scandinavian Forces the data to be entered and displayed in this format. For example: April^^^^^^21st,^1997 Forces the data to be entered and displayed in this format. For example: April^21,^1997 with trimming directive Forces the data to be entered and displayed in this format. For example: Monday^^^^-^21 Forces the data to be entered and displayed in this format. For example: Monday^-^21 with trimming directive
Page 71
Please note that: The character ^ denotes blank spaces. The Date Mode setting can be changed in the Options | Settings | Environment | International screen
Time Attribute
Directives HH MM SS :
PM
Z(c)
A
Description Place holder for the hour (0-99) Place holder for the minutes (0-59) Place holder for the seconds (0-59) Time separator position. Magic replaces this character with the character defined in the Environment Time Separator attribute. Placeholder for the AM/PM attribute. PM restricts the maximum value of the HH directive to 12 AM or PM In the case that the value of this field is zero\empty, this directive will instruct uniPaaS to fill it up with the specified character Automatically moves the cursor to the next field if the current one is filled up with information.
2.4.6 Ranges
Apart for controlling the format on which a field can accept and display information, we can also validate the actual information that the user can enter into them.
Continuous vs. Discrete Ranges

We can assign a range of values to a Model and this range can be either Continuous (for example: 1 to 10, 100 to 999, or 3 to 6) or Discrete (for example: Blue, Red, Yellow, or Green)
While defining a Discrete Range it should not have spaces within the different options. An invalid Discrete Range is: Blue, Red, Yellow, Green A valid Discrete Range is: Blue,Red,Yellow,Green
Page 72
To define a Continuous Range we will separate the Minimum and Maximum valued with the (-) character, no spaces An invalid Continuous Range is: 1 - 10 A valid Continuous Range is: 1-10 If we are dealing with negative numbers, we must use the escape (\) character An invalid Continuous Range is: -4-1 A valid Continuous Range is: \-4-\-1
After we have created our Models we should check them for errors; park our cursor on the (#) symbol at the top of the Model Repository table and press the <F8> key to check all the entries on this screen.
Follow the instructions detailed in the section: Exercise 1
Page 73
Lesson 5 Data Repository

PURPOSE OF THIS LESSON To introduce the Data Repository, its components and features KEY TERMS Keys Key Segments Columns OBJECTIVES Define sources, columns and indexes in the Data Repository Name the advantages and disadvantages of using indexes CONTENT OUTLINE 2.5.1 Introduction 2.5.2 Creating Data Sources 2.5.3 Creating Columns 2.5.4 Creating Indexes
Page 74
2.5.1 Introduction
This lesson describes the Data Repository and its components: data files\tables, fields\columns, and keys\ indexes. The Data Repository contains the definitions for all the data files\tables used throughout the Project. These data tables can reside on different computers, using different operating systems, and different DBMSs.
2.5.2 Creating Data Sources

If the Tables that we want to use in our application already exist inside a SQL or ODBC Database, we can tell uniPaaS to read their definition into our Data Repository, that way, we do not have to re-type their definitions. Be aware that uniPaaS will not try to create or match Models to the columns of the tables read. To manually create Data Sources in uniPaaS we can use both, the mouse or the keyboard; the following steps will show you how to create a Data Source using just the keyboard:
Follow these steps to create a Customers Data Source
1. Open our project 2. Press the <Shift+F2> keys to go to the Data Repository 3. Create a new line by pressing the <F4> key 4. On the Name column, type: Customers 5. On the Data source name column, a) type: Customers.dat if we are using Btrieve as our DBMS or b) type: Customers if we are using an SQL-type DBMS or ODBC 7. On the Database column, press the <F5> key and select MyComicStore
There is no relationship between the name the Name column, and the name of the physical table in the Data source name column.
Page 75
Depending of the DBMS that we are using, it is possible that the dot (.) character in .dat will not be allowed as a valid character. Verify this with your Database Administrator
Figure 26. The Data Repository Note: It is possible that the above figure may be different to your configuration, depending on the DBMS that we are using. Use the Name column to label your Data Sources with the most meaningful non-cryptic name possible. This name can be up to 30 characters, and it can contain upper and lowercase characters, numbers and spaces The name typed in the Data source name column is the name of the physical data file\table file. The naming convention for a table depends on the operative system and the DBMS used to access it.
Page 76
Be careful in the Data Repository
By default, uniPaaS always tries to keep the definition of a Data Source and the actual physical table in synchronization; therefore:
If we delete an entry in the Data Repository, uniPaaS will ask us if we also want to delete the physical table assigned to it. If we change the name typed in the Data source name column, uniPaaS will try to rename the physical table\file assigned to it. If we add, delete or modify a column or index from a Data Source, uniPaaS will export the information from the associated physical table, drop\delete the table, recreate it, and import the data back to it in order to reflect this change.
We can disable this behavior by un-checking a setting called Change Tables in Toolkit located on the Options tab for the Properties of the Database:
Figure 27. The Database Properties Window appears after pressing <Alt+Enter> on a Database entry Fundamentals of uniPaaS v1.5
Page 77
During the development phase, is a good idea to leave the option Check Definition checked; by doing this, uniPaaS will ensure that its definition and the physical table structure are the same. If the definitions between the physical table uniPaaS do not match, uniPaaS will display the error message: Definition Mismatch, data source:, or, it will point out the added column for this Data Source
Figure 28. Definition Mismatch between uniPaaS's definition and its physical Table
Page 78
Definition mismatch, data source: filename or Invalid column name: column name
This error means that the definition of a Table in uniPaaS does not match the definition of its physical Table To solve this problem we can execute anyone of the following actions:
Delete the physical Table and let uniPaaS recreate it by pressing <Ctrl+G>keys on the related Data Source entry Delete this Table from uniPaaS but do not delete the physical Table assigned to it; park your cursor at the top of the Data Repository Table (cursor should be blinking on the (#) symbol), then go to Options | Get Definition pull down menu and get the definition of this Table. uniPaaS can only perform this operation for SQL-type tables and ODBC connections Instruct uniPaaS not to check if these definitions are different by un-checking the setting called Change Tables in Toolkit, located on the Options tab for the Properties of the Database
Page 79
2.5.3 Creating Columns

Columns are individual pieces of information stored in a Data Source; each group of Columns in a Data Source is called a Record or Row. Each Data Source must have at least one Column defined.
To create Columns in a Data Source we can use both, the mouse or the keyboard; the following steps will show you how to create a Column using just the keyboard: Follow these steps to create Columns inside the Customers Data Source
1. Open our project 2. Press the <Shift+F2> keys to go to the Data Repository 3. Select the Customers entry and park your cursor in the Columns tab 4. Create a new line by pressing the <F4> key 5. Press the <F5> key while parked in the Model column and select the Customer Number Model 6. Repeat the steps 4 and 5 to create the remaining of the Columns for this Data Source:

First Name Last Name Address Line 1 (use the Model Address Line) Address Line 2 (use the Model Address Line) City State ID Phone Number
Once we have assigned a Model to a Column, we can change its name or properties.
Page 80
Figure 29. Creation of Columns for a Data Source Use the Name column to label your columns with the most meaningful, non-cryptic name possible. This name can be up to 30 characters, and it can contain upper and lowercase characters, numbers and spaces. If we are using any DBMS other than Btrieve (like MSSQL, Oracle or ODBC), it is very possible that there will be naming convention rules that must be followed before naming these columns. If so, each column entry will have a property called DB Column name; this field holds the actual name that will be inside the physical table. After we typed the name for each one of our columns, uniPaaS will copy this name into the DB Column name property removing all spaces and special characters; nevertheless, we should consult our Database Administrator for the naming convention rules for the current DBMS
In the Properties of this Column, you will find a property called DB Column Name; for SQL-type databases, this is the actual name of the column as it will be defined in the underlying database.
Page 81
2.5.4 Creating Indexes

Indexes, also called keys, are utilized to speed up the process of sorting and searching information within a Table
To create Indexes in a Data Source we can use both, the mouse or the keyboard; the following steps will show you how to create a Index using just the keyboard: Follow these steps to create an Index inside our Customers Data Source
1. Open our application 2. Press the <Shift+F2> keys to go to the Data Repository 3. Select the Customers Data Source and park your cursor in the Indexes tab 4. Create a new line by pressing the <F4> key 5. In the Name column, type: Customer Number 6. In the Type column, select: Unique 7. Press the <F5> key while parked in the Name column to enter the Segments section of this Index (at the bottom part of this screen)
8. Create a new line by pressing the <F4> key 9. While parked in the Column column press the <F5> key to jump to the Columns section (on the right side of this screen); and select the Customer Number Column 10. Repeat steps 4 to 9 to create the remaining Indexes with their Segments:
Name: Customer Name Segments: a.Last Name b.First Name Name: Phone Number Segment: a.Phone Number
Type: Non-Unique
Type: Non-Unique
11. Check the Primary Key box for the first unique type index on this Data Source
Page 82
Figure 30. Creation of Indexes for a Data Source Use the Name column to label our Indexes with the most meaningful non-cryptic name possible. This name can be up to 30 characters, and it can contain upper and lowercase characters, numbers and spaces. If we are using any DBMS other than Btrieve, it is very possible that we will have to comply with naming conventions for naming Indexes. Each Index entry has a property called DB Index name (by pressing the <Alt+Enter> keys); here we will see the actual name that will be used for the physical table. After we typed the name for each one of our Indexes, uniPaaS will copy this name into the DB Index name property removing all spaces and special characters; nevertheless, we should consult our Database Administrator for these naming conventions. The maximum number of Indexes per Data Source and the maximum number of Segments per Index are different for each DBMS.
Page 83
The advantages of using Indexes are:
Uniqueness. Specify an Index with the Type Unique and the DBMS will ensure that no other record will have the same value. An error message in the status bar of uniPaaS will be displayed if the user attempts to enter a duplicated record. Fast Record Search. Using an Index to locate a record is much faster than trying to find it by reading every record in the table sequentially Fast Record Sorting. Similar to searches, sorting the information using an Index will give us an almost instantaneous result.
The disadvantages of using Indexes are:

Use of Disk Space. Each Index requires additional disk space to store related information. Slower Updates and Creations. The more Indexes we have in a Data Source, the longer it takes to insert a new records, this is because the DBMS has to create and save Index-related information. There is a limit in the number of Indexes the DBMS can support. The underlying DBMS limits the number of Index segments in a Data Source. Some DBMSs store their Index information into separated files.
After we have created our Tables, park the cursor on the (#) symbol at the top of the Data Repository and press the <F8> key to check them for errors.
Page 84
Page 85
Lesson 6 Automatic Program Generator (APG)

PURPOSE OF THIS LESSON To introduce the functionality of the APG, and how to apply it during development KEY TERMS APG Import Export OBJECTIVES Use the APG from the Data Repository Use the APG from the Program Repository CONTENT OUTLINE 2.6.1 Introduction 2.6.2 Using APG in the Data Repository 2.6.3 Importing text file into a Data Source 2.6.4 Using APG in the Program Repository
Page 86
2.6.1 Introduction
The Automatic Program Generation (APG) is one of the many powerful tools in your Studio. The APG lets us create fully functional file maintenance, query, web based, and import/export programs in seconds. The APG can be used to create simple lookup programs to view existing data and can be use as the initial step for larger, more complex programs.
2.6.2 Using APG in the Data Repository

From the Data Repository, we can generate a quick maintenance program for a single or multiple Data Source(s) to see their information. Calling the Program Generator This section will show us how to call the program generator from the Data Repository screen. Follow these steps to call the APG for the Customers Data Source
1. Open our project 2. Press the <Shift+F2> keys to go to the Data Repository 3. Select the Customers entry 4. Press the <Ctrl+G> key to generate a program based on this Data Source 5. Press the OK button on the Program Generator screen
Page 87
Figure 31. Automatic Generation of a program from a single Data Source We can also generate a program for each one of our Data Sources: Follow these steps to call the APG for all our Data Sources
1. Open our project 2. Press the <Shift+F2> keys to go to the Data Repository 3. Park your cursor at the top of this table; the cursor should be blinking on the (#) sign 4. Press the <Ctrl+G> key to call the Program Generator screen. 5. Select All for the Tag data sources field 6. Press the OK button
Page 88
Figure 32. Generation of a program for each Data Source On the Program Generator screen we can specify what Data Source and what type of program we will like to generate: Tag data sources This option will let us choose how many Data Sources we want to use:
Several. A Data Source Selection screen will let us choose (using the <Space Bar> key) what Data Source(s) we want to include in this generation. All. uniPaaS will generate a program for each entry in the Data Repository. None. This is the default setting and it will not generate any programs.
Page 89
Mode There is only one Mode: Generate. This option generates a program for each one of the selected Data Sources, each program will be saved into the Program Repository but they will not be run.
Options This entry tells the program what functionality is going to perform:

Browse. Generates a program designed for On-line data entry and maintenance. Export. Generates a program to save the data contained in each selected Data Source into a text file. The data is exported to an operating system text file with a column delimited default format. Import. Generates a program to import data contained in an operating system text file to its respective Data Source. The expected format for this file is column delimited. Print. Generates a program to print the data contained on its respective Data Source to the default printer. Browser Client. This option generates a Browser-based program. uniPaaS will generate the HTML template file to be used by the program. Rich Client. This option generates a Rich Internet Application program.
Display The entry tells the program how to display the information on the screen:

Line. Displays the records as rows inside a Table. Many rows can be displayed on a single screen. Screen. Displays only one record at a time on the screen. None. No information is displayed on the screen.
Style The field on the screens can be generated with a 2D or 3D style. Use Model Select the Model for a Form, if any, as a base for the screens for program(s) to be generated. Form Size Specifies if the size of the form\screen for each program to be generated will be based on its Content or the selected Model. Caption Shows a text in the screen with the name of the program. Lesson 6 Automatic Program Generator (APG)
Page 90
Failed to open lock file, data source: filename
If we get this error message in uniPaaS, it means that we are trying to access a physical file (using Btrieve as our DBMS or XML File), but the specified folder either does not exist or we do not have permissions to access it. To solve this problem try the following:

Check that all our Logical Names are pointing to the correct directory Check that the Translation for all our Logical Names have a trailing backslash \ Check that all our Databases are using the correct Logical Names; remember that they are case-sensitive Using Windows Explorer, try to access the specified directory and compare this directory path with the one in the Logical Name
Invalid object name '{databasename}..{tablename}'.

If we get this error message in uniPaaS, it means that we are trying to access a table (using SQL-type DBMS), but the specified table does not exist. To solve this problem follow these steps: 1. 2. 3. 4. 5. 6. 7. Close the uniPaaS project, but do not close uniPaaS Go to the pull down menu Options | Settings | Databases Select the entry that you are using in the Data Sources (i.e.: MyComicStore) Press the <Alt+Enter> keys to go to the properties of this entry In the SQL tab, check the box called Check Existence Press the OK button to save these changes Open the project and try to do an APG on the Data Source that gave you the error
Page 91
2.6.3 Importing Text Files into Tables

We are going to use the APG functionality to import information from some text files into our Data Sources, so we can have some data to play with. On the Magic CD you will find a folder called CLASS directory, inside of it you will see a TEXTS folder, copy this TEXTS folder into our Project's directory.
Figure 33. Copy the Text Folder from the Course CD, into the Project's Directory Inside this folder you will find a text file for each one of our Data Sources. These text files are in column format, which means that the size for each of our columns in our Data Sources (First Name with 20 characters., Last Name with 30 characters., State ID with 2 characters, etc.) has to match the format of these text files in order to have a successful importation. If we created the Models in our application matching the specifications from Exercise 1, we should have no problem seeing correct data in our Data Sources.
Page 92
Figure 34. Contents of the CUSTOMERS.TXT file
Follow these steps to import text information into the Customers Data Source
1. Open our project 2. Press the <Shift+F2> keys to go to the Data Repository 3. Highlight the Customers table entry and press the <Ctrl+G> keys to generate a new program 4. Set the Mode to Execute 5. Set the Option to Import 6. Press the <F5> key in the Text file field and locate the file CUSTOMERS.TXT. The Text file field will be updated with the full path and filename 7. Press the OK button
8. In the confirmation window Start execution?, press the Yes button 9. In the confirmation window Execute again?, press the No button
Page 93
Figure 35. Executing an importation program
Page 94
Figure 36 Executing the importation program
Page 95
Figure 37. Do not execute the importation program again There is no option in the APG settings to import a comma or double-quote-comma delimited text files; we will need to create a program by hand to be able to accomplish this.
Page 96
2.6.4 Using APG in the Program Repository

We can trigger the APG functionality from the Program Repository as well. The APG can be executed only when our cursor is parked on a brand new program.
Follow these steps to call the APG from the Program Repository
1. Open our project 2. Press the <Shift+F3> keys to go to the Program Repository 3. Go to the last entry on this table and press the <F4> key to create a new line 4. Press the <Ctrl+G> keys to generate a new program
Figure 38. Generating a program from the Program Repository
Page 97
The Program Generator window displayed here is similar to the one shown from the Data Repository. Since we are in the Program Repository already, uniPaaS knows that we want to generate a program; however, we still need to select a Data Source from the Data Repository, the options of operation, the display type and so on.
Import all the text files from the TEXT folder into their respective Data Sources
After importing all the text files into their respective Data Sources, perform an APG to each program and choose the Display Mode as Screen and then as Line
Page 98
Page 99
Lesson 7 Navigating uniPaaS

PURPOSE OF THIS LESSON To get familiar with the screens and menu displayed in uniPaaS and learn how to use the mouse and keyboard to navigate between them KEY TERMS Menu Bar Zoom <F5> Wide Field <F6> Status Line Screen Mode Line Mode Magic Action OBJECTIVES Describe menus and their structure Use mouse and/or keyboard to access menus and dialog boxes Understand the Message line indicators Be able to navigate with the mouse and well as with the keyboard Understand the action of the arrow, Tab and movement keys CONTENT OUTLINE 2.7.1 Introduction 2.7.2 uniPaaS Menus 2.7.3 The Shortcut Keys in uniPaaS 2.7.4 The uniPaaS Window (Studio Mode)
Page 100
2.7.1 Introduction
uniPaaS displays lots of information on its screens. This lesson applies to both the Studio development system and the Runtime deployment system. This section of the course is designed to give you an understanding of the information provided on uniPaaSs main screen. Both the developer and the enduser will need to be familiar with the screens and their conventions. All menus options are accessible using the pull down menu and shortcut keys, some of them have an icon in the tool bar. In this lesson, you will learn how to use both the mouse and the keyboard to get from one function to another. Keep in mind that the following navigation information is based on the default keyboard-mapping file provided with uniPaaS.
2.7.2 uniPaaS Menus

The contents of the Menus are different depending if we are using the uniPaaS Studio with a Project open, with no Project open, or if we are using the uniPaaS Runtime. These are the menus that uniPaaS displays as soon we execute the Studio: File New Project Open Project <Ctrl+O> Close Project Application Properties Version Control Create Cabinet Export\Import Printer Setup Recent Projects Exit System <Alt+F4> Edit Cancel <Ctrl+F2> Undo Editing <Alt+Back> Cut <Ctrl+X> Copy <Ctrl+C> Paste <Ctrl+V> Create Line <F4> Delete Line <F3> Select All <Ctrl+A> Zoom <F5> Wide <F6> Properties <Alt+Enter> Quick Access Options Settings Fundamentals of uniPaaS v1.5 Cancels any data typed in the current screen Cancels the data typed in the current field Copies the current data selection into the clipboard and deletes it from the screen Copies the current data selection into the clipboard Writes the contents of the clipboard into the current field Creates a new line / record Deletes the current line / record Selects all the information from the current field Executes the Zoom action Widens the size of the current field Show the properties of the current line Allows you to locate and jump to an entry Opens a wizard-like window to create a new project Opens a project Close the current project Opens the application properties dialog Opens a project from the Version Control System Create Cabinet for the current project Shows you listing with the most recent open Projects Opens the Print Setup Dialog List all the accessed projects so far Closes Magic
Page 101
Environment Colors Fonts Keyboard Mapping Server Services Visual Connection Communications DBMS Databases Logging Logical Names Languages Printers HTML Styles Print Attributes Checker Messages Preferred Events Secret Names User Groups User IDs Logon Help Help Topics Help What is New Help on the Web Developer Resources Set License About uniPaaS Opens the first page of the Online Help Opens the Online Help related to the current screen Opens in a browser information about the new features in uniPaaS Opens the first page of the Online Help on a browser Opens in a browser information about uniPaaS resources in information Allows you to set a current license Show the current version, license, and gateways loaded Opens Opens Opens Opens Opens Opens Opens server Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens Opens the the the the the the the the the the the the the the the the the the the the the the main configuration screen of Magic repository of colors repository of fonts repository of keyboard mapping repository of uniPaaS Servers repository of uniPaaS Services screen to visually connect a service with a repository of Communications repository of Database Manager Systems repository of Databases repository of Logging repository of Logical Names repository of Languages repository of Printers repository of HTML styles repository of Printer Attributes repository of Checker Messages Preferred events repository repository of Secret Names repository of User Groups repository of Users Login screen of uniPaaS
Page 102
2.7.3 The Shortcut Keys

The shortcut keys in uniPaaS can trigger a different action depending if you are in Studio or in Runtime mode. The following table shows theses keys and their actions for both execution modes:
Shortcut F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 Ctrl+A

Ctrl+B Ctrl+C Ctrl+D Ctrl+E Ctrl+F Ctrl+G Ctrl+H Ctrl+I Ctrl+J Ctrl+K Ctrl+L Ctrl+M Ctrl+N Ctrl+O Ctrl+P Ctrl+Q Ctrl+R Ctrl+S Ctrl+T Ctrl+U Ctrl+V
Developer (Studio) On-line Help Edits Node Deletes the current line / record Creates a new line / record Zoom Expands the view of the current field Executes the current program Check the syntax of the current program Toggle Breakpoints Step (in Debugger Mode) Step Into (in Debugger Mode) Enter\View a Comment Selects all the data of the current field or controls in the current screen. Opens the SQL Assist window
Copy to clipboard Defines Expressions for a program Finds references for the current entry Calls the Automatic Program Generation (APG) Creates Header Line Opens the Input/Output Devices window Allows to Jump to a different line number Locates a record in the current table Edits the Main form of a program Locates the next record in the current table Opens a Project. In the Form, attaches controls to Table. Opens the Task Properties Opens the SQL Command window Changes the value of the Range and Location on the current program Saves the Program Sorts the current data view User Events Paste information from clipboard
End-User (Runtime) On-line Help

Deletes the current line / record Creates a new line / record Zoom Expands the view of the current field
Selects all the data of the current field
Copy to clipboard In create mode, duplicates the data from the previous record Switches the program to Create mode. Defines Expressions for Range and Location
Redirects the output of the program Changes the current index for a program Locates a record in the current table Switches the program to Modify mode Locates the next record in the current table Opens a Project Opens the Print Data dialog box Switches the program to Query mode Changes the value of the Range on the current program Sorts the current data view Assigns NULL value to the current field Paste information from clipboard
Page 103
Shortcut Ctrl+X Ctrl+Y Ctrl+Z Ctrl+Home
Ctrl+End Shift+F1 Shift+F2 Shift+F3 Shift+F4 Shift+F5 Shift+F6 Shift+F7 Shift+F11 Ctrl+F1 Ctrl+F2 Ctrl+F3 Ctrl+F4 Ctrl+F5 Ctrl+F6 Ctrl_F7 Ctrl+F8 Ctrl+F9 Ctrl+F10 Ctrl+F11 Ctrl+F12 Ctrl+1 Ctrl+2 Ctrl+3 Ctrl+4 Ctrl+5 Ctrl+6
Developer (Studio) Cuts the current selected item(s)

Places the cursor on the first record of the table Places the cursor on the last record of the table Opens the Model Repository window Opens the Data Repository window Opens the Program Repository window Opens the Help Screens Repository window Opens the Rights Repository window Opens the Menu Repository window Opens the Components Repository window In debugger mode, Step Out Cancels any modifications Closes the current window Goes inside the program specified in the Call Program operation Execute the Project Shows the next Checker Message Add the current variable to the Watch windows In a program switches to the Data View tab. In Expression Editor, opens the Functions List. In a program switches to the Logic tab. In Expression Editor, opens the Event List. In a program switches to the Forms tab. In Expression Editor, opens the Keyboard List. In Expression Editor, opens the Rights List. In the Form, moves the current control forward. In Expression Editor, opens the Control Name List. In the Form, moves the current control backward. In Expression Editor, opens the Data Source List. In the Form, moves the current control to the back.
End-User (Runtime) Cuts the current selected item(s)

Places the cursor on the first entry of a table Places the cursor on the first entry of a table
Closes the current window
Page 104
Shortcut Ctrl+7
Ctrl+8 Ctrl+9 Alt+F1 Alt+F2 Alt+F3 Alt+F4 Alt+F8 Alt+F12 Alt+Back Ctrl+Shift+B Ctrl+Shift+F Ctrl+Shift+E Ctrl+Shift+G Ctrl+Shift+H Ctrl+Shift+J Ctrl+Shift+L Ctrl+Shift+M Ctrl+Shift+N Ctrl+Shift+O Ctrl+Shift+P Ctrl+Shift+R Ctrl+Shift+T Ctrl+Shift+V Ctrl+Shift+F7 Ctrl+Shift+F5 Ctrl+Shift+F9 Ctrl+Shift+Tab Alt+Ctrl+H Alt+Ctrl+N Alt+Ctrl+P Alt+Ctrl+V Alt+Ctrl+F7
Developer (Studio) In Expression Editor, opens the Program List. In the Form, moves the current control to the front. In Expression Editor, opens the Error List. In the Form, displays the Z-order. In Expression Editor, opens the Menu List. In the Form, fits the control to size. Opens/Closes the Navigation window Opens/Closes the Property Sheet window Opens/Closes the Checker window Closes uniPaaS Verify the syntax of the remaining items Opens/Closes the Comments window Cancels the changes to the current field Creates a Bookmark for the current item Opens the Find Text dialog box Opens the Export\Import dialog box Opens the Composite Generators Wizard In the Form, aligns controls Horizontal Center Opens the dialog window to Jump to a Folder In the Form, aligns controls to the Left Moves an entry Locate Previous row Overwrites an entry Opens the Application Properties dialog window Opens the Repeat Entry dialog window In the Form, aligns controls to the Right In the Form, aligns controls to the Top In the Form, aligns controls Horizontal Center Execute the program in Browser Jumps back to the original caller program Resets the Runtime Engine Jumps to the previous window In the Form, sets an Horizontal Equal Spacing Jumps to the next Header Line Jumps to the previous Header Line In the Form, sets a Vertical Equal Spacing In Debugger Mode, breaks the execution
End-User (Runtime)
Closes uniPaaS Cancels the changes to the current field
Page 105
The Zoom function is a default functionality available in uniPaaS not only for the developer but also for the end-user. Most of the time, this action is associated with the presentation of additional information related to the current field or control.
Page 106
2.7.4 The uniPaaS Window (Studio mode)

The uniPaaS window displays different screens containing information and commands for the developer to use in the various modules. During the development of an application, the use of the Navigator panel is indispensable.
Figure 39. The Studio's screen
If the Navigator screen is not visible, we can call it by pressing the <Alt+F1> keys or by selecting View | Navigator.
If we want to merge the Navigator and the Property window, just drag the Property window and place it on top the Navigation one.
Page 107
In the lower part of the uniPaaS screen, we can see information related to the current application, in both the Studio,
Figure 40. Studio's Task Bar and the Runtime.
Figure 41. Runtime's Task Bar
Page 108
Page 109
Lesson 8 The Runtime

PURPOSE OF THIS LESSON To introduce the second mode of operation of uniPaaS, the Runtime End User mode KEY TERMS Screen Mode Line Mode Query Mode Browse Keys Program Mode Sorting Incremental Search Range and Locate Templates OBJECTIVES Describe the Modify, Query, and Create modes Find Records Using the Locate and Range Operations Recover from the Duplicate Index error CONTENT OUTLINE 2.8.1 Introduction 2.8.2 Entering the Runtime Mode 2.8.3 Browsing Data in Runtime 2.8.4 Field Editing 2.8.5 Creating Records 2.8.6 Deleting Records 2.8.7 Searching Records 2.8.8 Locate Operation 2.8.9 Changing Indexes and Sorting 2.8.10 Ranging Operation
Page 110
2.8.1 Introduction
This section explains the pull down menu structure and all the standard features available at Runtime mode to the end-user mode.
2.8.2 Entering the Runtime Mode

While in the Studio, we can execute (Runtime Mode) a selected program by choosing the pull down menu Debug | Run, or by pressing the <F7> shortcut key; we can also execute the entire project by selecting the pull down menu Debug | Run Project, or by pressing the <Ctrl+F7> shortcut key. These are the available menus while in Runtime mode: File Open Application Close Application Printer Setup Exit System <Alt+F4> Edit Cancel <Ctrl+F2> Undo Editing <Alt+Back> Cut <Shift+Del> Copy <Ctrl+Ins> Paste <Shift+Ins> Create Line <F4> Delete Line <F3> Select All <Ctrl+A> Zoom <F5> Wide <F6> Ditto Set to NULL OLE Options Modify Records <Ctrl+M> Create Records <Ctrl+C> Query Records <Ctrl+Q> Locate a Record <Ctrl+L> Locate Next <Ctrl+M> Range of Records <Ctrl+R> View by Key <Ctrl+K> Sort Records <Ctrl+S> Redirect Files Print Data Begin Table Fundamentals of uniPaaS v1.5 Changes the status of the program to Modify mode Changes the status of the program to Create mode Changes the status of the program to Query mode Changes the status of the program to Locate mode Locates the next matching record in the current program Changes the status of the program to Range mode Allows to change the current key used by the program Allows to sorting records in the current program Redirects the output of the program to a different device Opens a wizard-like screen to send the current displayed information to a printer or a file Parks the cursor on the first row of the data view Cancels any data typed in the current screen Cancels the data typed in the current field Copies the current data selection into the clipboard and deletes it from the screen Copies the current data selection into the clipboard Writes the contents of the clipboard into the current field Creates a new line / record Deletes the current line / record Selects all the information from the current field Executes the Zoom action Widens the size of the current field While creating a new record, it copies the information above it Updates the current field to its NULL value Allows the manipulation of OLE objects Opens Closes Opens Closes a Magic Application the Magic application currently open the Printer configuration screen Magic
Page 111
Previous Screen Previous Row Next Row Next Screen End Table Settings Logon Window Close All Next Window <Ctrl+Tab> Previous Window <Ctrl+Shift+Tab> More Windows If MDI is enable, closes all Windows If MDI is enable, goes to the next window If MDI is enable, goes to the previous window If MDI is enable, opens the dialog box to select a window Parks the cursor on the previous screen of the data view Parks the cursor on the previous row\record Parks the cursor on the next row\record Parks the cursor on the next screen of the data view Parks the cursor on the last row\record of the data view Opens the settings menu Opens the Login dialog box
Besides the pull down menus, the developer and the end-user can access the majority of these commands via the icons in the tool bar.
Page 112
2.8.3 Browsing Data in Runtime

uniPaaS makes it easy for end users to browse through, and examine records. Data can be displayed in two basic ways:
Screen Mode
In screen mode, uniPaaS displays only one record on the screen at a time.
Figure 42. Execution of a Program in Screen Mode
Page 113
Line Mode
In line mode, uniPaaS can display several records on the screen at a time. The current record is the one highlighted.
Figure 43. Execution of a Program in Line Mode
Page 114
2.8.4 Field Editing

Usually a program starts in Query mode, the current mode of a program is displayed in the status bar. If the user wants to modify the information from the Table he\she must switch to Modify or Create mode. Modify Mode - <Ctrl+M> To be able to modify existing information on a screen, the program must be in Modify mode. Once the information has been modified, there are three ways to save it into the Data Source:

When the user presses the <Esc> key to close the current program. When the cursor jumps to another record by pressing the <PgUp> or <PgDn> keys in screen mode; or the <> or <> keys in line mode. When changing or re-instating the current program mode.
Transactions will play an important part of the data manipulation process; Transactions tell uniPaaS when the information will be send to the Data Source to be saved
<Tab> The user can press the <Tab> key to move the cursor to the next field, or by pressing the <Shift+Tab> keys, the user can move the cursor to the previous field. Cancel the Field Data Entry - <Alt+Backspace> Press the <Alt+Backspace> key to cancel the changes made on the current field. This option is only available if the cursor has not jumped to another field. <Home> The cursor moves to the beginning of the current field. <End> The cursor moves to the end of the current field. <>/<> The cursor moves within the information of the current field. <Del> Deletes the character to the right of the cursor, or all the characters currently selected by the user. <Backspace> Deletes the character to the left of the cursor, or all the characters currently selected by the user.
Page 115
<Ctrl+F2> Press the <Ctrl+F2> keys to cancel\undo any changes you made to the current record. When you press <Ctrl+F2>, the record is restored to its original state. This option is only available if the user has not jumped to another record.
2.8.5 Creating Records

Create Mode - <Ctrl+E> Create mode lets you add new records to your Data Source. Once in Create mode, existing records will not be displayed on the screen and you only see records that you have added in the current session. Use the <PgDn> in Screen Mode to leave the newly created record and add another new record, in Line Mode use the down arrow <>.
Duplicate index, data source:... or Constraint failure, data source:...

This error means that you have attempted to create a record with a duplicate unique index If you get stuck on the screen because of this message, go to Edit | Cancel to cancel this record's information.
Create Line - <F4> While in Modify mode, you can press the <F4> key to add new records and still see the existing ones. <PgDn>/<> While in Modify mode, and if the cursor is parked on the last record, you can press the <PgDn> in Screen Mode or the <> key in Line Mode to create a new record.
2.8.6 Deleting Records

Delete Mode - <F3> Press the <F3> key to delete a record. You can only delete records in Modify mode. Since deletions are permanent, you must confirm the deletion by pressing the <Y> key or the Yes button in the confirmation screen. You can delete several records at a time but first you need to select these records by keeping pressed the <Shift> key while moving up or down the list of records with the <PgUp>, <PgDn> or the arrow keys; then, just press the <F3> key and confirm the deletion process.
Page 116
2.8.7 Searching Records

Query Mode - <Ctrl+Q> Programs in Query mode do not allow the user to modify the information displayed on the screen. While in Query mode, the user can utilize a powerful built-in feature called Incremental Search. Incremental Search allows the user to locate a record by typing the information that he\she is looking for. At the same time, uniPaaS can change the key that the program is using to quickly match the Column on which the user is typing. By default Incremental Search will be case-sensitive for alpha fields; in numeric fields, the user may need to type the complete information that he\she is looking for before uniPaaS displays a matching record. Depending on the configuration of your DBMS, these behaviors may act differently. If the user tries to do an Incremental Search on non-indexed Columns, it is possible that uniPaaS may ask the user for a confirmation before trying to search for this information. If there are many records on this Data Source this process may take a while. Query by Example uniPaaS also allows you to search for a particular record (Locate) or for a group of records (Range). The form into which you enter the Locate or Range criteria is called a Template. Depending of the configuration of the current DBMS, data search can be case-sensitive. We can use the star (*) character at the end of an alpha field for wild card searching. For example: searching for CARL* will locate or range information from CARLAAAAAAA through CARLzzzzzzz.
2.8.8 Locate Operation

<Ctrl+L> To locate a record in a table, press the <Ctrl+L> or use the Options | Locate menu. <Ctrl+L> takes you to a Locate Template mode. Enter the data to be located, and press <Enter> to start the search. If no exact match is found, the next record is selected. If there is no next record (past the end of the table), the first record is selected. This option is different from the Incremental Search because you can specify more that one criterion (field) in the template to locate the requested record. <F7> and <F8> To switch between the minimum and maximum location we can press the <F7> and <F8> keys respectively. This kind of range is called Continuous Range since it is defined between two different values. In the status bar of uniPaaS we can see the current range on which were are typing information to be located; we will be on the Loc From mode as soon as we press the <Ctrl+L> keys or the <F7> key
Figure 44. Locate From status bar Fundamentals of uniPaaS v1.5
Page 117
and we can change to the Loc To mode when we press the <F8> key
Figure 45. Locate To status bar <Ctrl+Shift+L> Once a record has been located, you can press the <Ctrl+Shift+L> keys to jump to the next record that matches the current locate criteria. To clean up the information typed in the Locate Template, press the <Ctrl+L> keys (to show the current Locate information); then we press <F3> (to delete the Locate information on this template), and finally press <Enter> (to accept the changes made.) Non-Continuous Location When we need to locate records in a Non-Continuous Range, we must use a Locate Expression. To define a Locate Expression we need to be in the Locate Template screen (<Ctrl+L>), then we can press the <Ctrl+E> keys or we can use the pull down menu Options | Define Expression. On the Expression Rules screen, we can create a logical expression that will return to us a noncontinuous set of data. For example, we could type the expression: First Name=Bob OR First Name=Bobby OR First Name=Robert As a result, we will be able to locate only records that match this expression.
Figure 46. Locate Expression screen
Page 118
In the Expression Rules screen, you can press the <F5> key to display all the fields available to the user, and <Ctrl+1> to display a list of functions
2.8.9 Changing Indexes and Sorting

Changing Indexes - <Ctrl+K> Before performing the Locate or Range operations, you can change to the optimal key by pressing the <Ctrl+K> keys. This lets you view the existing keys and select the one that best suits your needs. uniPaaS automatically will try to optimize the key if you do not select it manually. The first segment of the key that uniPaaS selects must be the one of the criteria (Columns) that is used in Locate or Range Templates. Otherwise, the key is not optimized.
Figure 47. Changing Indexes
Page 119
Sorting Records - <Ctrl+T> Sorting records allows us to visualize the information in a more efficient way, depending of our needs. When we press the <Ctrl+T> keys, uniPaaS will display a table on which the user can place one or several fields from the current table, uniPaaS will use them to sort the information on this way.
Figure 48. Sorting Records The sorting of the information is saved on temporary memory tables, these tables that will be deleted as soon the program closes; the user can manually delete these sorting tables by pressing the <F3> key on the desired Sort entry.
Page 120
Figure 49. Temporary Index
Page 121
2.8.10 Range Operation

Range Records - <Ctrl+R> Range allows us to limit the number of records in our Data view. Only records that match the specified criteria will be displayed. If no records are found, the message No records within the defined range is displayed in the status bar. To create a range we can press the <Ctrl+R> keys or we can use the pull down menu Options | Range of Records. When we press the <Ctrl+R> keys, uniPaaS will clean the current screen and show the Range Template screen. Using one or several Columns can specify a range. <F7> and <F8> To change between the minimum (Range From) and maximum (Range To) ranges press the <F7> and <F8> keys respectively. This kind of range is called Continuous Range, since is defined between two different values. In the status bar for uniPaaS we can see which part of the range we are typing the information in; as soon we pressed the <Ctrl+R> keys we will be in the Range From part;
Figure 50. Range From status bar we can switch to the Range To part of the range when we press the <F8> key
Figure 51. Range To status bar Non-Continuous Range When we want to show records within a Non-Continuous Range, we must use the Range Expression. To define a range expression we just press the <Ctrl+E> key or use the pull down menu Options | Define Expression, while in Range mode.
Page 122
Figure 52. Range Expression screen On the Expression Rules screen, we can create an expression that will return to us a non-continuous range of data. For example, we could type the expression: First Name='Bob' OR First Name='Bobby' OR First Name='Robert' As a result, the program will only show records that match this expression. To clean up the information typed in the Range Template, press the <Ctrl+R> keys (to show the current Range information); then we press <F3> (to delete the Range information on this template), and finally press <Enter> (to accept the changes made.)
Page 123
Lesson 9 Programmable Loop Concept How uniPaaS Programs Work

PURPOSE OF THIS LESSON To master the methodology behind the Loop concept in order to write and run a uniPaaS program KEY TERMS On-line Batch Task Toolkit Menus OBJECTIVES Access the Program Repository Navigate between the Task Properties, Execution and Forms Table Understand the Magic Programmable Loop Concept CONTENT OUTLINE 2.9.1 Introduction 2.9.2 The Programmable Loop Concept 2.9.3 On-line vs. Batch Programs 2.9.4 12 Operations vs. Hundreds of Commands 2.9.5 Relational Tables Instead of Text Editors
Page 124
2.9.1 Introduction
The loop concept methodology is at the core of the Magic philosophy, it minimizes the time that it takes for a person to start creating complex programs in uniPaaS and is a crucial element in making it a Rapid Application Development (RAD) tool. Other factors that make uniPaaS unique are:

Only has 12 operations instead of hundreds of commands The programming is done inside Relational Tables instead of text editors The Magic Runtime Engine The Magic Gateways
No matter how many others programming languages you know, you will always find the Magic approach unique. The most important concept you will learn in this lesson is that all Magic programs are written the same way; there are some basic rules and tables we need to master to be able to write them. Following a few simple rules will guarantee our success, speed, and ease of programming. It is possible that programmers with many years of experience in procedural languages will suffer from the Where is the command? syndrome. They will keep looking for a way to open files, begin to read a file, start a transaction, declare variables, and initialize pointers, etc., because they expect to have to deal with these tasks. uniPaaS performs many of these tasks automatically and this is the reason why you should become familiar with all the rules that Magic follows when a program is executed.
2.9.2 The Programmable Loop Concept

What is the programmable loop concept? It refers to the fact that every Magic program is a loop by itself. Every program in Magic will start its execution, it will cycle once, twice, or as many times as we specify executing its operations, and then it will exit. On the same token, a Magic program automatically opens the specified Data Source, selects the requested record(s), parks the cursor in the first record, checks for the end-of-file, optionally locks the records before they are updated, and closes the Data Source at the end of the program. There are two main nested loops in every Magic program: 1. The Task Loop executed ONCE per program or task 2. The Record Loop executed ONCE per record or row Each one of these cycles has an entry point (called Prefix) and a exit point (called Suffix). Inside these points we can execute operations and functions that will make the program behave the way we want it.
Page 125
The following is a description of the entry and exit points of the Programmable Loop: TASK PREFIX (Beginning of the Task Loop) This is executed only ONCE at the beginning of each program or task, prior to reading the first record from the selected Data Source. RECORD PREFIX (Beginning of the Record Loop) This is executed after a record is read from the Data Source and before the user has control over the program. RECORD SUFFIX (End of the Record Loop) This is executed after the user commits the record and before it is written to back to the Data Source. This is the only optional section of the programmable loop. Magic executes the Record Suffix if at least one of the following conditions is true:

The record was modified by the user The user deleted the record. If the user deletes a modified record that has not being saved, the Record Suffix will be executed twice, once in Modify mode and then in Delete mode This is a Batch program This is a On-line program, and the option Selection Table (Task Properties | Advanced) set to Yes, and the user pressed the <Enter> key This is a On-line program and the option Force Record Suffix (Task Control | Behavior) is set to Yes
TASK SUFFIX (End of the Task Loop) This is executed only ONCE at the end of each program or task, by this time the connection to the Data Source has been closed already.
More detailed information about the Programmable Loop Concept can be found in Appendix A
Page 126
2.9.3 On-line vs. Batch Programs

On-line programs are designed for user interaction and they require keyboard input to run. Examples of these programs are file maintenance, data entry screens, lookup and query programs.
On-line tasks terminate when the user presses the <Esc> key, or when the user presses the <Enter> key and if the Selection Table option set to Yes.
Batch programs require no user interaction. Once they start, they run to completion without any keyboard input. Examples of Batch programs are reports, actualization of records and import/export programs.
Batch tasks end when all records of the Main Data Source are processed within the specified range, or when the End Task and Evaluate Conditions are evaluated to True. There are other two types of programs in uniPaaS: Browser and RIA but we will not be covered on this course.
2.9.4 12 Operations vs. Hundreds of Commands

Compared to other languages which have anywhere from hundreds to thousands of operations (reserved words), with only 12 operations, uniPaaS might seem inadequate at first; however, you will soon be convinced by using the Magic methodology that the number of operations is not indicative of the power of the language.
2.9.5 Relational Tables Instead of Text Editors

The usual tasks for any compiler are to make sure that you enter the correct number of parentheses, commas, and other characters in your programming code. The Magic development system is composed of about 20 different tables. Each of these unique tables has full context-sensitive help attached to every option. In addition, each table knows about the information contained in all other related tables and can validate and check the syntax of your entries. This adds a level of complexity, when compared to traditional development tools, which requires you to spend a lot of time in their text editor. In Magic, you must first navigate to the correct table and then create the appropriate entries. You will learn later that a program (or task) consists of the Execution Table plus about a dozen related tables.
Page 127
Lesson 10 Three Steps for Writing a Magic Program

PURPOSE OF THIS LESSON Understanding and applying the three steps for writing a program in Magic KEY TERMS The Program Repository 3 Steps to Create a Program Task Tree Task Properties Main Source Selection Operation Controls OBJECTIVES Write a program in Magic using 3 Steps Know the functionality of the Column Operation Check the syntax and run a program Learn how to place fields on the Form Editor screen CONTENT OUTLINE 2.10.1 Introduction 2.10.2 The Program Repository 2.10.3 Creating a New Program Step One Select the Main Source Step Two Select the Columns Step Three Design the Form 2.10.4 Saving the Program 2.10.5 Checking the Syntax 2.10.6 Running the Program
Page 128
2.10.1 Introduction
We have learned in a previous lesson how use the Automatic Program Generator (APG) to create a fully functional program. In this lesson, we will learn how to write a similar On-line program from scratch. We will find that there are only a few simple steps required to write programs in Magic. Before we write our first program, we need to emphasize two important concepts: 1. All Magic programs, no matter how complex, are written the same way. 2. Magic programs are both modular and reusable by definition. Therefore, the easiest way to create a complex program is to write a simple one, test it, and then go back and add more logic to it until the program is complete. This is the recommended approach while learning uniPaaS.
2.10.2 The Program Repository

All of our application logic is stored in Programs, and they are stored in the Program Repository. This repository can be accessed by going to the pull down menu entry Workspace | Programs or by pressing the <Shift+F3> keys, or by clicking the Program option from the Navigator panel.
Figure 53. The Program Repository.
Page 129
The Program Repository table displays the name of each program, its folder, public name, a check-box to specify if the program will be called from the Internet, and the date and time of the last performed modification. At the top of the list, you will see a program called the Main Program. This Main Program is always present on any application build in eDeveloper v9.x and up, it is always at the top of the list. We can use this program to create and store global variables; Magic executes this program every time we run a program or the entire Project in Runtime mode.
2.10.3 Creating a New Program

We can create a new program by pressing the <F4> key while we are parked in the Program Repository and entering the name of the program. It does not make any difference where you add a new program because Magic automatically renumbers all occurrences of other programs. Follow these steps to create a new Program
1. Open our project 2. Press the <Shift+F3> keys to go to the Program Repository 3. Go to the last entry on this table and press the <F4> key to create a new line 4. Type the name: My Customer's Program
The name of a Program can be up to 30 characters, and it could contain upper and lowercase characters, numbers and spaces There are 3 basic steps to the creation of any program: 1. First, we will select the Main Data Source for our program, this will be the Data Source that we want to browse, modify, delete, print, export or import. 2. Second, we will specify the Data View, in other words, what Columns or Fields from the Data Source we will like to work with. 3. And third, we will design the screen (known as a Form) that will be presented to the user. The rest of this lesson will follow these steps in order to create a brand new program.
Page 130
Step One - Select the Main Source Every program in uniPaaS can only have one Main Source. Follow these steps to complete the first step in the creation of a program: The selection of a Main Source
1. Press the <F5> key to open our program. Since this is a brand new program, the Task Properties screen will appear automatically 2. Hit the OK button 3. Park your cursor on the Main Source field and press the <F5> key to show a list of Data Sources 4. From the Data Source List screen, select the entry that will be the Main Data Source for our program, in this case select: Customers. By default, the first Index on this Data Source will be use
Figure 54. Step 1, selection the Main Data Source Fundamentals of uniPaaS v1.5
Page 131
Step Two Select the Columns To be able to select any Columns or fields, we are going to use the most common operation in uniPaaS, the Column Operation. The purpose of the Column operation is to establish the Data View. The Data View is the set of records that will be worked on by the program; these records may be printed, exported, deleted, updated or just presented to the user in the screen.
The Column, Virtual and Parameter Operations are only available in the Data View tab
Follow these steps to complete the second step in the creation of a program: The selection of the Columns
1. Park your cursor in the Main Source header section in the Data View tab 2. Press the <F4> key to create a new line 3. Press the <C> key to choose the Column Operation 4. Press the <Tab> key and enter the number of the desired column, or press the <Tab> key and press the <F5> key to show the Column Selection List for the Main Data Source 5. Repeat steps 10 to 12 in order to select the remaining of the Columns\Fields for the current Table:

First Name Last Name Address Line 1 Address Line 2 City State ID Phone Number
Page 132
Figure 55. Step 2, selection the Columns or the Data View
Step Three Place the Columns on the Form Every program in Magic has a Main Form, this Main Form is the default GUI screen that is displayed to the user when the program runs. While we are inside a program, there are several of ways to get to this Form: 1. Press the <Ctrl+M> keys 2. Go to the pull down menu Options | Edit Main Form 3. Press the <Ctrl+3> keys, select the last entry on this table and press the <F5> key Pressing the <Ctrl+3> keys will open the Forms tab. This screen displays all the Forms\Screens for the current program and all its ancestors; since the Main Program is parent to all other programs, we will see its Form all the time. The Main Form of our program is usually the one with the same name as this program, and always has a Class = 0.
Page 133
Figure 56. The Forms Tab In uniPaaS we refer to both, On-line screens and printed report layouts as Forms because they are defined the same way. Each line in this table represents a Form, or a section of a Form.
Page 134
No matter how we get to the Main Form, we are now looking at a blank screen where we can place all the forms controls and data fields:
Figure 57. Step 3, designing for the Main Form We are going to create a Screen mode program, in other words, a screen that will display only one record at a time. A Line mode program will allow us to see several records on the same screen, this type of screen will be covered later. A Control is a defined object that you can place on a Form. It can display data from a variable, perform a function, or just display a text label. By selecting and placing controls, you can create attractive dialog boxes, screen displays, and printed forms. All the available controls are listed in the Controls palette under the Controls tab, and all available variables\columns are under the Variables tab.
Page 135
Follow these steps to complete the third step in the creation of a program: The creation of the Form.
1. Select the Variables tab from the Controls palette 2. Select the desired Variable to be placed on the form (do not drag it!) 3. Click on the form where we want can to place this Variable 4. Repeat steps 15 to 16 in order to place the remaining variables on the current Form:

Customer Number First Name Last Name Address Line 1 Address Line 2 City State ID Phone Number
Figure 58. Placing variables on the screen
Page 136
Do not worry about the alignment of the fields for now; also, when we select Variables, uniPaaS automatically will create a Text Control (also known as an Static Control) with the name of its Variable.
If we hold down the <Shift> key while placing a Variable on the form, its Text Control will no be created
We have plenty of control over the Forms appearance including the fonts, colors, border style size, position, etc. Each Control on the Form has a set of Properties that we can manipulate to comply with our requests. If we have a Control selected, we can see and its Properties and change them; if we have a group of Controls selected, we can only see and change the common properties to those Controls.
2.10.4 Saving the Program

The modifications that we have made to this program will be saved when we close it. There are several ways to do this: 1. By pressing the <Esc> key and confirming that we want to save the changes made until we are in the Program Repository 2. By pressing the <Shift+F3> keys to save the current program and go to the Program Repository 3. By pressing the <Ctrl+S> keys to save the current program and remain inside of it 4. By selecting the pull down menu Options | Save and Close Obj to save the current program and go to the Program Repository 5. By selecting the pull down menu Project | Programs to save the current program and go to the Program Repository
2.10.5 Checking the Syntax

Pressing the <F8> key will check our program for errors. It is always good idea to check a program prior to running it; failure to do so may cause the Runtime to crash. If the program successfully passes the checker, we are ready to run it. If our program fails the checker, we will be placed at the error point.
2.10.6 Running the Program

While in the Program Repository table, we can run the current highlighted program by selecting the pull down menu Debug | Run, or pressing the <F7> key. The program will run and we will see our Customer data entry screen. This is where we can test the programs behavior and note any required modifications. Fundamentals of uniPaaS v1.5
Page 137
Figure 59. Executing our first program At this stage, we have successfully created our first program following the three basic steps: Choose a Data Source to manipulate, choose the Columns to use in the program, create the Form to display the information. There is no need to compile, or link the program before running it; just make the required modifications, save it, and run it.
Page 138
Page 139
Lesson 11 Form Design

PURPOSE OF THIS LESSON To introduce options available in designing a form using the Table Control and the Control Properties Dialogs KEY TERMS Control Palette Variable Palette Command Palette Color Palette Static Controls Dynamic Controls Control Properties OBJECTIVES Use the options available when placing a field on a screen Make a Line Mode screen, using the Table Control CONTENT OUTLINE 2.11.1 Introduction 2.11.2 Form Properties 2.11.3 Type of Controls 2.11.4 Control Properties 2.11.5 Manipulation of Controls Align the Controls in a Form 2.11.6 Line Mode Forms
Page 140
2.11.1 Introduction
This lesson will deal with the different Form Controls available in uniPaaS. We will learn about the options when placing a variable on the screen, how to make a line mode program screen (to display many records on a single screen), how to display fields that are wider than the screen itself and how to use static Controls to enhance the screen design.
2.11.2 Form Properties

Before we proceed, we need to take a good look at Form's properties. To see the properties of the Form itself we need to have no control selected while in the Form of the program.
Figure 60. Properties of the program's Main Form
While no controls are selected, you can use the arrow keys <>, <>, <>, <> to move the position of a Form, press <Enter> to set it
Page 141
While no controls are selected, you can hold down the <Shift> key and use the arrow keys <>, <>, <>, <> to resize a Form, press <Enter> to set it
2.11.3 Type of Controls

uniPaaS also offers a wide variety of graphical controls that we can use to display, group and navigate within the information presented on the screen.
Figure 61. Available Controls for a Main Form
Page 142
The following table describes each one of the items on the Controls Pallet:
Icon
Description The selection tool in the Control palette. Use this tool to select or un-select a control. You must select a control in order to move, resize, delete, or to zoom into the Control Properties dialog. It is normally used in combination with the <Shift> or <Ctrl> keys
Inserts a box for radio buttons. The options on this control can be based of a Table Draws a static rectangle. You can add static text to the rectangle and specify its position in the rectangle in the Control Properties dialog. Define the rectangles color in the Color property of the Control Properties dialog Inserts a table control into the form. You can place other control types, such as edit controls, and push buttons on a table control Inserts an edit control. You can attach this type of control to a variable or an expression in the Data property of the Control Properties dialog Inserts a tab control. Using this control, we can show/hide different controls assigned to each one of its tabs. Draws a static ellipse. You can add static text to the ellipse and specify its position in the ellipse in the Control Properties dialog. To define the ellipses color, set the Color property in the Control properties dialog Inserts a graphic image control Inserts a static text control Inserts a list box control Draws a graphic line. To define the lines color, set the Color property in the Control properties dialog Inserts an OLE container Inserts a push button that the user clicks to launch an action in the application Inserts a combo box Inserts a vertical slider with direction arrows
Page 143
Icon Description Inserts a rich text control containing static text that can be formatted during development. The formatting of a rich text control is not implemented on the control as a whole, but only during the editing of the selected text of the control
Inserts a Check box that the user can toggle on/off. Use this type of control to represent logical variables or expressions Draws a static rectangular box to group a number of controls together visually. You can include a label to describe the group Inserts a horizontal slider with direction arrows Inserts a rich edit control that contains a variable or expression. This control is implemented as a rich text control when the text originates from a BLOB variable or expression Inserts a Tree control that displays the records from the Main Table in a tree style with parent and child nodes Inserts a Subform control to display the Form from another Task or Program in a seamless way Inserts a Browser control to display web sites or documents stored on a web site, this control is only available for a RIA type of program
If the Class of the current Form is greater that zero several of these Controls may not available for use.
Page 144
2.11.4 Control Properties

Each one of the controls that we can place in the screen has its own set of properties. There are properties that are common to all the controls (like: color, position, size, etc.), and properties that are unique to each control.
Figure 62. Properties of a Control We can press the <F1> key to request more information about each one of the properties for the Form.
Page 145
2.11.5 Manipulation of Controls

uniPaaS has a series of commands to facilitate the manipulation of the different graphical controls.
Figure 63. Commands Pallets The following table describes each one of the items on the Commands Pallet:
Icon
Description Aligns all selected controls to the left side of the selection frame
Aligns all selected controls to the left side of the selection frame Aligns all selected controls to the horizontal center of the form Spaces all selected controls equally horizontally within the selection frame Aligns all selected controls to the right side of the selection frame Stretches all selected controls to the width of the widest control selected Stretches all selected controls to the height of the tallest control selected Aligns all selected controls along the top of the selection frame Aligns all selected controls along the top of the selection frame Aligns all selected controls to the vertical center of the form Spaces all selected controls vertically within the selection frame Aligns all selected controls along the bottom of the selection frame Shrinks all selected controls to the width of the narrowest control selected Shrinks all selected controls to the height of the shortest control selected Sends a selected control one layer forward in the form
Page 146
Icon Description Brings a selected control one layer back in the form
Brings a selected control to the front of the form Brings a selected control to the back of the form Displays the Z-order of the controls in the form Enables the automatic Z-order of controls in the form Shows/hides the dividers on printing forms Undo the last modification Redo the last modification Links the selected control to another one Unlinks the selected control Attaches to the table control the selected control(s) Highlights the Parent control of the selected control Resizes the current control to fit its format Enable\Disable Automatic Tab Order Display\Hide Tab Order
Align the Controls in a Form Now we are going to use these Commands to improve upon the Form's design for the first program that we created:
Page 147
Follow these steps to align the controls placed on a Screen Mode Form
1. Zoom into the program 2. Press the <Ctrl+M> keys to go to the Main Form of this program 3. Using the keyboard or the mouse, enlarge this Form 4. Press the <Ctrl+A> keys to select all the Controls on the Form 5. Place the mouse pointer on top of anyone of the selected controls (do not place the mouse on an empty space), and drag it to the lower left corner of the screen. All the selected controls will move at the same time 6. Un-select all the controls by a clicking on any empty space on the Form 7. Select all the Text Controls on the Form by either:
Making a box with the mouse pointer that will contain or touch all the Text Controls Holding down the <Ctrl> key, while clicking on every Text Control on the Form
7.
Place the mouse pointer on top of any of the selected controls (do not place the mouse on an empty space), and drag it to the upper left corner of the Form
8. While we still have all the Text Controls selected, press the button (from the Commands palette) to align all the selected Controls to the left-most selected Control 9. While we still have all the Text Controls selected, press the button (from the Commands palette) to stretch all the selected Controls to match the longest selected Control 10. Un-select all the selected Controls by making a click on any empty space on the Form 11. Select all the Edit Controls on the Form by:
Making a box with the mouse pointer that will contain or touch all the Edit Controls Holding down the <Ctrl> key, while clicking on every Edit Control on the Form
12. Place the mouse pointer on top of any of the selected controls (do not place the mouse on an empty space), and drag it in front of their Text Controls
Page 148
13. While we still have all the Edit Controls selected, press the button (from the Commands palette) to align all the selected Controls to the left-most Control 14. Press the <Ctrl+A> keys to select all the Controls on the Form 15. Press the button (from the Commands palette) to stretch all the selected Controls to match the tallest selected Control 16. Using the mouse, reduce the size of the Form by dragging its lower-right corner 17. Press the <Shift+F3> keys to save all the changes made
If we execute this program, its screen should look like this:
Figure 64. Aligned Controls in the program
Page 149
2.11.6 Line Mode Forms

Besides being able to display information one records at a time, we can create a Line Mode Form that will display several records on a Table. Follow these steps to create a Line Mode Program:
1. Create a brand new program on which the Main Source is the Customers Data Source, and select all its Columns in the Data View Tab 2. While inside the program, press the <Ctrl+M> keys to go to the Main Form of this program 3. Hide the Properties panel by clicking on the little x that appears on its upper-right corner or by pressing the <Alt+F2> keys. We do this to utilize all the available space on the screen 4. Using the mouse, enlarge this Form by dragging its lower-right corner
5. Click on the button (from the Controls palette) to place a Table Control in the upperleft corner of the Form; expand this Control to be as wide as the Form itself 6. Click on the Variable Tab (from the Controls palette) to display the list of Variables 7. Click on the Customer Number variable (do not drag it!), and click on top of the Table control
8. Click on the First Name variable (do not drag it!), and click on top of the Customer Number column 9. Click on the Last Name variable (do not drag it!), and click on top of the First Name column 10. Click on the Address Line 1 variable (do not drag it!), and click on top of the Last Name column 11. Click on the Phone Number variable (do not drag it!), and click on top of the Address Line 1 column 12. Select the Table Control by clicking on it, using the mouse resize this control to fit the columns that we just placed on it 13. Reduce the size of the Form to fit the Table Control, if necessary 14. Press the <Shift+F3> keys to save all the changes made 15. To bring back the Property panel, press the <Alt+F2> keys
Page 150
If we execute this program, its screen should look like this:
Figure 65. Executing a program in Line mode
Page 151
Lesson 12 Column, Update, Verify and Remark Operations

PURPOSE OF THIS LESSON To get familiar with the selection and use of variables, and how to update and test their values KEY TERMS Remark Operation Column Operation Condition Column Expression Table Verify Operation Update Operation OBJECTIVES Use the Verify operation to validate data entry Use the Expression Table to add logical and mathematical functionality to Magic programs CONTENT OUTLINE 2.12.1 Introduction 2.12.2 Selecting Variables The Column Operation Allow Parking Setting Tab Into and Allowed Direction Setting Initialization Column (Init) Range Columns Implementation of the One-to-Many Relationship Locate Columns 2.12.3 Expression Table The Four Components of an Expression 2.12.4 Data Validation The Verify Operation Control and Variable Logical Units 2.12.5 Updating Variables The Update Operation Using the Update Operation 2.12.6 Documenting our Programs The Remark Operation
Page 152
2.12.1 Introduction
In a previous lesson, we learned how to write a File Maintenance\Browse program. This lesson will add to our knowledge by explaining some of the options available when using the Column operation. In addition, we will be introduced to the Expression Table and learn about two new operations: Verify and Update.
2.12.2 Selecting Variables

The Column Operation The Column operation is used to establish the Data View and to select the columns from a Data Source to be used in this task. We can also create temporary variables; such variables can be created using the Virtual or Parameter operation. We can create three different types of Variables in a program:

Column. It selects only columns\fields declared inside a Data Source. Virtual. It creates Virtual (temporary) variables. Magic will create these variables when the program is executed and it will delete them when the program finishes. Parameter. It creates Parameter (also temporary) variables. These variables behave the same way as Virtual variables, with the only exception that a Calling Program will be able to see them.
Allow Parking Setting By default, the user will be able to park the cursor on every Column from the Main Source and on every Virtual\Parameter variable declared in the Data View tab. We can disable this ability by setting the option Allow Parking to No; we can also assign an Expression to this column so it will be dynamically evaluated at Runtime mode.
Figure 66. Allow Parking Property
Page 153
Tab Into and Allowed Direction Setting The Tab Into and Allowed Direction settings allows further control over the insertion operation beyond the logical condition we can put in the Allow Parking setting, because they permit conditioning of movement, and direction of the cursor.
Figure 67. The Tab into and Allowed direction Properties When the Tab Into setting has the value of Yes or an Expression that evaluates to True, the Runtime will allow the cursor to park on this field by pressing the <Tab> or <Shift+Tab> keys. If it has the value of No or an Expression that evaluates to False, this field can only be accessible by clicking on it with the mouse. The Allowed Direction setting takes in consideration the direction of the cursor when it wants to park on a control, this setting has three possible values:
When Allowed Direction is Forward Only

Backward Only Both Directions
uniPaaS allows the cursor to land on the control... If the cursor is moving forwards according to the Tab Order
If the cursor is moving backwards according to the Tab Order Regardless of the direction of the cursor
The Allow Parking setting has priority over the Allow Direction and Tab Into settings
Using the Last Name Edit Control from the screen, modify the information on these settings and see how the program behaves
Page 154
Initialization Column (Init) The Init property is a way to initialize the value of Columns or Variables in the program. When the program is executed, the Runtime will evaluate all Init Expression and it will assign their values to the specified Column or Variable. There is no need to use the equal (=) sign inside the Expression, the Init column acts as the equal operator between the Column\Variable and the Expression.
INITIALIZATION AT THE BEGINNING OF THE TASK Initialization works different depending if we are dealing with a Column or a Variable (Virtual or Parameter)
Column Variable - uniPaaS evaluates the Init expression and assigns its value to the Column variable from the Main Source when: 1. The task runs in Create mode and before the record is displayed on the screen. 2. The task runs in Modify mode and the Expression assigned to this Column is recomputed. Column variables inside a Link operation will be initialized with the Init expression only if the Link operation fails. We will see the Link operation on the next Lesson.
Virtual Variables Since these variables are always created on the fly, uniPaaS evaluates the Init expression and assigns its value to the Variable in all modes of operation (Create, Modify, Query) but before the record is displayed on the screen. Parameter Variables These variables behave the same way as Virtual variables. Again, the only difference is that a calling program can see these variables.
A Virtual Variable that is not been initialized keeps its value during the execution of the task. uniPaaS adopts this approach to Virtual variables to support the use of these variables as accumulators or counters. INITIALIZATION DURING USER INTERACTION THE RECOMPUTE ENGINE In addition to initialize Columns and Variables at the beginning of the task, the Init property will keep updating the information of Columns\Variables while the user interacts with the program just like in a spreadsheet. When any of the variables participating in an Init expression changes its value during Data View or Record Suffix Levels, uniPaaS re-computes the expression and updates the Column\Variable associated to the Int expression.
Page 155
The Re-compute engine is a very powerful tool and it follows a specific set of rules:
The re-computing mechanism only works forward; in other words, Init expressions are recomputed if any of their component (Columns and\or Variables) have been modified and if the modified component (Columns and\or Variables) has been declared prior to the declaration of the Columns\Variable with the Init expression. The next Figure illustrates the scenarios when the Initialization process will work and when it will not work.
Figure 68. Initialization only works if all the Columns\Variables used on the Init expression are declared above the Column\Variable with the Init expression In the Record Suffix, any updates to the value of Columns\Variables in the Record Suffix Level will cause re-computation of all the Init expressions that these Columns\Variables participate in.
Range Columns Placing Expressions in the Range Columns is a way to customize the tasks data view. They will define a continuous subset of records from the physical files selected for the Data View. There are two Range Columns, the first column represents the lower range value and the second column represents the upper range value for the current Column\Variable. The assigned Expressions must evaluate to a value matching the Column\Variables attribute. We can also use a complex logical Expression to create a non-continuous range in the Range/Locate Window; we can assign this expression by pressing the <Ctrl+R> keys or using the pull down menu in the Task | Range/Locate | Expressions Expressions used to Range a Column\Variable are evaluated at the beginning of the task. Be sure that all Columns\Variables participating in expressions contain valid values when the task is executed. These Column\Variables can be selected from a parent task, they can be arguments passed by another task or any constant value.
Page 156
Implementation of the One-to-Many Relation uniPaaS implements one-to-many relationship by calling subtasks and using Expressions in the Range Columns One-to-Many relationships will be covered on a later Lesson. Locate Columns Similar to the Range Columns, we can assign Expression for the two Locate Columns, one for the lower value and the other for the upper value. uniPaaS will try to find a record the matches the specified criteria. Unlike Range, Locate allows the end-user to see to records outside the domain of lower\upper Expressions. If we specified both, lower and upper Locate, Expressions for a Column and no record meets the specified criteria, the processing cursor will move to the first record with a higher value than the upper expression value and the message Record not found Positioned at next is displayed in the status bar. If no record with a higher than the upper Expression exists, the cursor will move to the first record in the data view and the message Record not found - Positioned at beginning is displayed. If we specify only a lower Locate Expression and a matching record could not be found, the processing pointer moves to the first record with a higher value, but no message is displayed. If we specify only an upper Locate expression and a matching record could not be found, the cursor moves to the first record of the Data View.
By default, uniPaaS displays the Located record at the top the Table Control, if we want to display this record centered within the Table Control, we need to go to the pull down menu Settings | Environment | Preferences and set the Center Screen in On-line property to Yes
Page 157
2.12.3 Expression Rules Table

When we press the <F5> key while in a property or setting inside our program we will jump to the Expression Rules window. The Expression Rules is the repository that contains logic, arithmetic and data manipulation functions. Each Expression on this screen can be reused on different parts of the same program. In addition, we can open this screen by just pressing the <Ctrl+E> keys while in a program.
Figure 69. The Expression Rules Window
Page 158
While in the Expressions Table, we can display several other windows showing a list of Columns\Variables, Functions, User Events, etc.; we can select them from the pull down menu Insert, by pressing any of the icons at the top of this window, or by using the following short-cut keys:
Short-Cut Key
<Ctrl+0> or <F5> <Ctrl+1> <Ctrl+2> <Ctrl+3> <Ctrl+4> <Ctrl+5> <Ctrl+6> <Ctrl+7> <Ctrl+8> <Ctrl+9> <Ctrl+0> <Ctrl+ Minus>
Window
Variables Functions Internal Events Shortcuts Rights Controls Data Sources Programs Errors Menus Forms Logical Names
The Four Components of an Expression An Expression could contain any of the following components, either by themselves or in combination with other components: 1. Columns\Variables. We can choose any of the available Columns\Variables by pressing the <F5> key and selecting it, or just by typing the correspondent letter for the desired Column\Variable. 2. Functions. We can see a list of functions by pressing the <Ctrl+1> keys. All these functions have a parenthesis after their name; for some functions, a constant value or the letter of a variable is required. Some example of functions are: DATE() It will return the current system date LEFT(A,3) It will return the first three characters of the alpha variable A STAT (0,CMODE) Queries the mode of the current program. If the current program is in Create mode it will return the value True; otherwise, it will return the value False STR(B,6.2) Returns the numeric variable B as a string, based on the picture of 6.2 3. Operations. We can use several arithmetic functions like: +, -, *, /; and logical operations like: AND, OR, NOT, =, <, etc. 4. Literals. Literals helps uniPaaS to distinguish between a constant text value and another type or value, for example: Fundamentals of uniPaaS v1.5
Page 159
'TRUE'LOG By using the literal LOG, uniPaaS knows that this is the logical value of True, not the text TRUE. 'FALSE'LOG By using the literal LOG, uniPaaS knows that this is the logical value of False, not the text FALSE '12'PROG By using the literal PROG, uniPaaS knows that we are making reference to program 12, and not just the text 12 '01/02/03DATE With the literal DATE, uniPaaS makes the distinction between the text 01/02/03 and the actual date of 01/02/2003 '05:12:10TIME With the literal TIME, uniPaaS makes the distinction between the text 05:12:10 and the actual time value of 05:12:10 The rules for the creation of Expressions are as follow:

Expressions are not case sensitive. uniPaaS does not recognize the use of the double quotes (). The order of the expressions in the Expression screen is not relevant. uniPaaS will rearrange all the references to the already assigned expressions automatically. After typing an Expression is recommended to press the <Tab> key or click on the Show button. If no mistakes were encountered, the Expression will be displayed in the lower part of this same window; if an error was found, a message will appear in the status bar and the cursor will park where the error was detected
uniPaaS has more that 450 functions, these functions are divided into several categories: Numeric, String, Basic, Database, Security, etc. The following list is just a sample of some of these functions and their use: String Functions allows us to manipulates the contents of Columns\Variables with an Alpha attribute: LEFT(A, number of characters) Returns the specified number of characters from a sting counting from left to right If A=SOFTWARE and number of characters=3 Result is: SOF RIGHT(A, number of characters) Returns the specified number of characters from a string counting from right to left If A=SOFTWARE and number of characters =3 Result: ARE MID(A, start position, length) Returns a section of a string If A=SOFTWARE, start position=3 and length=4 Result: TWAR
Page 160
TRIM(A) Remove blank characters from a string If A= SOFTWARE Result: SOFTWARE uniPaaS always places blank spaces at the end of the data in an alpha Column\Variable. A&B Concatenates two or alpha Columns\Variables If A=SOFTWARE and B=AND HARDWARE Result: SOFTWARE AND HARDWARE TRIM(A)& &B Removes blank characters from one string and concatenates it to a another If A=SOFTWARE and B=AND HARDWARE Result: SOFTWARE AND HARDWARE UPPER(A) Converts an string into its uppercase letters. If A=Software Result: SOFTWARE Numeric Functions allows to perform operations with Columns\Variables with a Numeric attribute: MIN(A,B,C,...) Returns the minimum value from a list of values. If A=3, B=33 and C=12 Result: 3 STR(A,4.2C) Converts a numeric value into an alpha string with the specified picture. If A=3234 Result: 3,234.00 VAL(A,10) Converts an alpha string into a numeric value with the specified picture. If A='3234' Result: 3234 Date and Time Functions perform operations with date and time values: DATE() Returns the current system date Result: 04/18/2002 DSTR(A, WWWWWWWW, MMMMMMMM DD, YYYY) Convert a data field into an alpha string with the specified format. If A=04/07/2003 Result: 'Wednesday, April 7, 2003' TIME() Returns the current system time Result: 06:20:45
Page 161
Tasks Functions return the status of execution of a program and or task: STAT(0,CMODE) Check if the status of the current task is in Create mode Result: True if the current task is in Create mode; False, if the current task in not in Create mode. STAT(1,QMMODE) Check if the status of the parent task is either Query or Modify mode Result: True if the parent task is in Query or Modify mode; False, if the parent task in not in Query or Modify mode. LEVEL(0) Returns the level of execution of the current task Result: 'RP' if the level of execution of the current task is Record Prefix 'RS' if the level of execution of the current task is Record Suffix 'TP' if the level of execution of the current task is Task Prefix 'TS' if the level of execution of the current task is Task Suffix Conditional Functions return a value depending if the result of the evaluated condition: IF (A=1,Customer,Vendor) Return a value depending if the condition is True or False Result: If the value of the variable A is 1, the result will be the string Customer, otherwise the string Vendor. CASE (A,1,Customer,2,Vendor,Publisher) Depending of the value of the variable A this function will return a different string Result: If the value of the variable A is 1, the result will be the string Customer, if the value of the variable A is 2, the string will be Vendor, otherwise the string Publisher
Page 162
2.12.4 Data Validation

Even when uniPaaS can validate the data entered by the user in a field based on its attribute (alpha, numeric, date, etc.), its format (U25, UL24, N8.2, MM/DD/YYYY, etc.), and its range of values (0-10), on many occasions this is not enough. In other words, the data that the user types can be in the correct format and range, but maybe it does not have the correct value that the program expects based on our requirements. The Verify Operation The Verify Operation is utilize to communicate with the end-user. It provides a simple interface to display information, ask questions, warn the user about a situation or even stop the execution of a process. There are three Modes of operation for this Operation: 1. Error mode will stop the processing of the current logic and return the cursor to its last insertion point 2. Warning mode will display a message to the user, once the user has acknowledge this message the program will continue its current logic 3. Revert mode will display a message to the user, once the user has acknowledge this message the program will bounce back executing any operation that encounters in Backward mode until it reaches the top of the current Logical Unit. If we want to validate the information that the user typed into a field, we need to decide when do we want to tell the user about a problem with the data, we have two basic options:
After the user finish typing information in the current screen and before the record is saved into the Data Source, or As soon as the user exits the current field
If we decide to alert the user before the records is saved into the Data Source, the Record Suffix Level will be the perfect place to put this operation. If we will like to stop the user on his\her tracks and do not let him\her continue inputting data until the problem is fixed, none of the current Logical Units that we seen so far (Task or Record) will not work for us; we need a new Logical Unit, the Control\Variable Unit. Control and Variable Logic Units The Control and Variable Logic Units allows us to execute logic and operations while the user has control over the screen. While the Task Unit executes operations at the beginning and end of a Task, and the Record Unit executes operations before and after the user has control over the screen; the Control and Variable Units will execute operations before and after the cursor parks on a specified control on the screen. These are their different Levels:
Page 163
Control Prefix. Here we can place the operations that the engine will execute before the cursor lands on a particular control. Control Suffix. In this Level we can set operations that the engine will execute at the end of the control, that is, just before the cursor wants to leave the current control. Control Verification. The operations set in here are performed whenever the cursor is taken away from the current control and whenever the control is passed through in Fast mode; also, this Level is executed before the Control Suffix. Fast Mode is triggered when the user jumps (using the mouse pointer) from one control on the screen to another. When this happens, the engine will execute any Control Verification Logical Unit specified between the control where the cursor was and the control where the cursor wants to be.
Variable Change. In the Variable Changed Level, we can place the operations that we want to execute if the user changed the value on the specified Control.
The Cnd property at the Header Line itself works as the main on\off switch for any one of these Levels. If it is set to Yes or to an Expression that will evaluate as True, the operations inside this Level will be executed; if it is set to No or to an Expression that will evaluate as False, the operations inside this Level will not be executed. On the same token, any operation that has a Cnd property set to No or to an Expression that will evaluate as False will not be executed.
Page 164
Follow these steps to create a Verify Operation for the Last Name Control
1. Open the program 2. In the Logic tab, create a new Header Line by pressing the <Ctrl+H>keys and selecting a Control Logical Unit with a Suffix Level 3. Select the Last Name as the Control name 4. Press the <F4> key to create a new line under this Header. On this new line, press the <E> key to select the Verify operation 5. In the Mode Property, select Error 6. In the Text Property, enter: Last Name cannot be left blank 7. In the Display Property, select Box
8. In the Condition column, press the <F5> key and create a new the expression: X='' (where X represents the letter that corresponds to the Column Last Name)
Figure 70. Create a Verify Operation inside a Control Suffix Logical Level In the Text Property we can type a brief message that will be displayed to the user; this is a static message. If we want to have a dynamic message, park the cursor in the number 0, just to the right of the Text property, press the <F5> key to create a dynamic string Expression that will be evaluated during Runtime.
Page 165
In the Mode Property will control the behavior of this operation; there are three different modes:
Error mode will display the message to the user and restrict the movement of the cursor until the condition for this operation is False. Warning mode will display the message to the user without restricting the cursor's movement. Revert mode will return the cursor to the handled Control and it will execute the operations that precede the Verify Operation in reverse order, back to the first operation in the Logical Level.
In the Display option, we can choose how the message will be displayed to the user; we have two options:

Box will display the message in a window in the middle of the screen. Status will display the message in the status bar of the uniPaaS window.
In the Condition property we can place an Expression that will suppress this operation. If the Expression returns a True value, the Verify operation will be executed, if it returns a False value, the Verify operation will not be executed. The Image property allows us to choose the icon that will be displayed on the message window. The Buttons property allows us to choose what buttons will be displayed on the message window.
Page 166
2.12.5 Updating Variables

The Update Operation The Update Operation is utilized to change the value of Columns\Variables. The most common places to use this operation are in the Control Unit, while the user is entering information in the screen, and in the Record Suffix Level, before the data is save to the disk. Using the Update Operation Similarly to the Verify Operation, we need to choose when do we want to update our Column\Variable with new information, it could be:

Before the record is presented to the user (Record Prefix Level), As soon as the user enters, exits, or updates a Control (Control Unit), or After the user finish typing information on the current screen and before the record is saved into the disk (Record Suffix Level)
As an example, we are going to add the logic to this program to update the State ID field with the value of CA, if and only if, the State ID field is empty. This operation should happen after the user is done with the record and before it is save to the disk; in other words, the Record Suffix Level.
Follow these steps to create an Update Operation for the State ID Control
1. Open the program 2. In the Logic tab, create a new Header Line by pressing the <Ctrl+H> keys and selecting a Record Logical Unit with a Suffix Level 3. Press the <F4> key to create a new line under this Header. On this new line, press the <U> key to select the Update Operation 4. Tab to the right and press the <F5> key to select the variable State ID 5. Press the <F5> key in the With property to open the Expressions table. Create a new expression with the text: CA. 6. Press the <F5> key in the Condition property to open the Expressions table. Create a new Expression that will test if the State ID Column is empty or not, for example: X= (where X represents the letter that corresponds to the State ID Column)
Page 167
Figure 71. Create an Update Operation inside a Record Suffix Level The Incremental property for Update operation will tell uniPaaS how to update the selected Column\Variable:
The option No will instruct uniPaaS to update the selected Column\Variable with the chosen Expression. The option Yes will tell uniPaaS to choose one of the following actions: a) If the execution mode of the current task is Create, uniPaaS will update the selected Column\Variable with the chosen expression. b) If the execution mode of the current task is Modify, uniPaaS will update the selected Column\Variable with the difference between its current value and the value of the chosen expression. c) If the execution mode of the current task is Delete, uniPaaS will subtract the value of the chosen Expression from the current value of the selected Column\Variable.
If the Force Update property is set to Yes or to an Expression that will evaluate True, uniPaaS will not allow the user to cancel the data entry after this operation has been executed. With a value of No or False the user will be able to press <Ctrl+F2> to cancel the current data input. In the Condition property we can select the values Yes, No, or assign it to an Expression; if the expression returns a True value, the operation will be executed, if the expression returns a False value, the operation will not be executed. Please take notice of the limitations of this Operation:
The Update Operation is only available on the Record Prefix, Record Suffix, Control and Variable Levels. The Incremental mode property is only relevant for On-line tasks. The Update Operation in Incremental mode should always be used inside the Record Suffix level; this way, uniPaaS will only execute this operation when the user has changed the data view. When using the Update Operation in Incremental mode (to accumulate the totals of an amount for the parent task), make sure to set the Force Update property to Yes to prevent the cancellation of the parent record (order header record) after we have saved child records (order line records). Lesson 12 Column, Update, Verify and Remark Operations
Page 168
2.12.6 Documenting our Programs

Just because uniPaaS has so few operations it does not mean that is not necessary document or write comments on each program. The Remark Operation The Remark Operation is used to enter lines of text on any one of the execution Levels in a program. As its name suggests, uniPaaS will ignore these lines during execution. It is recommendable to place comments inside all our programs not just for us, the original developer, but also for any other developer that will have access to this Project.
Follow these steps to create a comment in our program
1. Open our program and park the cursor on the Main Source line, in the Data View Tab 2. Create a brand new line 3. Select the Remark operation and press the <Tab> key to start entering text 4. If our comments does not fit the current line, repeat steps 2 and 3
Figure 72. Document the Data View Tab
Page 169
Figure 73. Document the Record Suffix Level
We can press the <F12> key to enter longer comments into an entry for each one of the Repositories (Models, Data, Programs, etc.), and also, into each one of the execution Levels in a program; pressing the <Alt+F12> keys will display them on a window
Page 170
Page 171
Lesson 13 One-to-one Database Relationship (1:1)

PURPOSE OF THIS LESSON To introduce the steps for the creation and usage of Link Operations KEY TERMS Link Write Link Create Link Query Locate Expression Referential Integrity OBJECTIVES Name the three steps for the creation of a Link Operation Select the fields to display information Name the two ways to validate information in Magic CONTENTS OF THIS LESSON 2.13.1 Introduction 2.13.2 The Link Operation 2.13.3 Steps for the creation of a One-to-One Relationship 2.13.4 Validate Data Input
Page 172
2.13.1 Introduction
So far, we have only dealt with a single Data Source per program. If we will like to display the name of state for a customer, this will require to make a connection to two different Data Sources: one to the Customers and one to the States. Since every Customer record can be related to one and only one State record, this means that there is a one-to-one relationship between the Customers and the State Data Source. To create 1:1 (one-to-one) relationships in uniPaaS we will use the Link Operation. This operation can be used to validate information, and to create and\or to query records stored in other Data Sources.
2.13.2 The Link Operation

The Link operation is only available in the Data View tab since it is utilized to create the data view for a program. The Link operation is the only non-procedural operation in uniPaaS Re-compute of a Link Operation The same re-compute engine that updates Columns\Variables via the Init column is going to re-evaluate any Link Operation to try to bring the correct information when the value of a field, or fields, that are used in the Locate column within the Link operation changes. Please note that these fields must be declared before the Link Operation that uses them. Init Expressions when the Link operation fails If the Link Operation fails, in other words, when this operation could not find the requested record in the Linked Data Source, all its Init Expressions are evaluated and assigned to those Columns.
2.13.3 Steps for the creation of a One-to-One Relationship

As mentioned before, the Link operation will use uniPaaS's Re-compute Engine to keep the information retrieved from the Link updated at all times; for this reason, it is recommended to create the Link operation after the Column\Variable operation that is going to be used to locate the record that the Link will use. On this example we will work with two Data Sources: Customers and States. The Customer source has the following Columns: Customer Number First Name Last Name State ID Phone Number The States source has the following Columns: State ID State Name
Page 173
On this scenario, there is a 1:1 (one-to-one) relationship between Customers and States. Each record in the Customer source can be related to one and only one record in the States source. The State ID column is the common field between these two sources. The objective is to display not only the State ID for every Customer but also the related State Name as well. Since the State Name is not stored in the Customers source, every time we want to see this information, we must bring this information from the States source. In other words, we need to locate a State ID (from the States source) based on the value of the State ID Column (from the Customers source).
Follow these steps to create a one-to-one relationship: 1. Define a Link Operation
1. Open the Customers program and go to the Data View tab 2. Park the cursor on the State ID Column. 3. Create a brand new Header Line <Ctr+H> and press the <L> key to select the Link Query operation 4. In the Data source number property press the <F5> key o select the States Data Source. 5. Press the <F5> key on the Index property and select the State ID key. 6. Park your cursor on the Locate From column for the State ID Column, inside the Link operation. 7. Press the <F5> key to open the Expressions table; create a new expression that will point to the State ID Column from the Customer Data Source.
8. Assign this same expression to the Locate To column for the State ID Column inside the Link operation. 9. Create a new line just below the State ID Column inside the Link operation. 10. Select the column State Name 11. Save the modifications made to this program
Page 174
Figure 74. Creating a Link Query Operation There are five types of Link Operations in uniPaaS:
Query This Link is used to only query records from the specified Data Source, if the record is found, it will read it; if the record does not exist, the Link operation will fail and no information is retrieved. Write This type of Link will first try to locate the specified record on the linked Data Source, if the record is found it will read it; if the record was not found, the Link operation will create it on the linked Data Source. Create This Link, as its name says, is always going to create a new record in the linked Data Source regardless if the record exists or not. Use it when you are sure that no duplicate data errors will occur. Inner Join This type of Link will work the same as the Query option, but uniPaaS will use the capabilities of the RDBMSs to retrieve the information. Left Outer Join Same as the above option, uniPaaS will use the capabilities of the RDBMSs to retrieve the information Since eDeveloper version 9.3 SP4, the Studio now lets us define the Link Left Outer Join operation for non SQL Tables.
This feature makes uniPaaS more flexible when working with different DBMS systems, and enables us to define the Link operation to work as Left Outer Join for SQL Tables and as a Link Query for ISAM Tables The Index property will instruct the Link to use a specific Index to retrieve the information. After selecting an Index, uniPaaS will bring up all the Columns assigned to it.
Page 175
The Direction property tells uniPaaS how to sort the information while trying to locate the specified record. If the value of this option is Default, uniPaaS will use the direction for the selected Index (usually bringing the first record that is located), if this option is Reverse, it will reverse the direction of the selected Index (usually bringing the last record within the specified location). The Success Indication property is optional. By pressing the <F5> key on this property, we can select a Column\Variable that will be updated with the value of True or 1 if the Link was successful, or with False or 0 if the Link was not successful. This variable has to be declared with a Logical or Numeric Attribute The value in the Condition property could prevent the Link Operation to be executed at all. If the value of the Condition column is set to Yes or to an Expression that will return True, the Link operation will be executed. If the Condition column is set to No or to an Expression that will return False, the following events will be performed:
The Link operation is not executed and it behaves as if the Link failed to locate the requested record The variable in the Returned Value option, if any, will be updated with the value of False or 0 Any Update operation that tries to update any Columns within the Link operation will not be executed If the Condition property for a Link Operation is changed to False at the end of the Record Suffix, any updates to columns within the Link operation will be not taken in consideration while saving the information to the Data Source.
The Locate From and Locate To columns are utilized to find a specific record form the linked Data Source. When the Evaluate Link property is set to Task, the Condition property for the Link operation will be evaluated only once, before the Data View is retrieved. If the Condition returns a False, the link will not be executed. If the Condition is evaluate to True, the Link Operation will be executed but it will not be recomputed regardless if the user changes any information on the screen. When the property is set to Record and should the link Condition evaluate to True, the Link Operation will be executed normally. If the link Condition evaluates to False, the Link Operation will not be executed.
If we execute this program now, it will run the same way as before since this modification has not affected its visible behavior
To be able to see if the Link Operation is really working we need to place the State Name Column (from the States Data Source) on the screen so we can see what information is being retrieved.
Page 176
Follow these steps to create a one-to-one relationship: 2. Display retrieved information on the Screen
1. Open the Customers program and go to its Main Form 2. Press the <Ctrl+M> keys to go to the Main Form of this program 3. From the Variables pallet select the State Name field from the States Table 4. While holding down the <Shift> key place this field next to the State ID Edit Control. By doing this, the Text Control related to this field will not be created 5. Save the modifications made to this program
Figure 75. Creating a Link Query Operation
Run this program and verify that the State Name field is always displaying the correct information based on the current State ID
By default, uniPaaS does not allow the user to park the cursor on linked columns.
Page 177
2.13.4 Validate Data Input

The Link Operation allows the developer to setup one-to-one relationships fairly easy between two Data Sources, but one thing this operation does not do is preventing the user to enter invalid information (i.e. typing QW in the State ID field). If the user enters an invalid information in the State ID field, the Link to the States table will fail and the State Name field will return no information, but it will not stop the user to save this record. This kind of validation has to be performed by hand. This is a two stage process in which we need to detect or raise a flag if the Link Operation failed (due to a non-existent State ID), and then, inform the user of this situation. First, we need to create a flag variable that will store the result of the Link Operation, then we need to connect this variable to the Success indicator property from the Link Operation.
Follow these steps to validate user input: 1. Detect Link Result
1. Open the Customers program and go to the Data View tab 2. Create a brand new virtual variable with the following settings: Set Field description to L:State ID is OK Set Attribute to Logical 3. Set the Success indication property from the Link Query Operation to the virtual variable that we just created 4. Save the modifications made to this program
Page 178
Figure 76. Define an On-line Query program It is customary to type the L: string at the beginning of the name of a virtual variable when this variable will receive the result of a Link Operation, but is not really required. Any variable that will be connected to the Link Operation via the Success indication must be declared with a Logical or Numeric Attribute; in this manual we used the Logical Attribute.
Please notice that we did not use any Model for the creation of this virtual variable, simply because we have not created a Model with these characteristics, nevertheless, the program will work and no error will be displayed You can go back and create a Model entry that will support this and any other flag variables
Page 179
Figure 77. Connect Virtual variable to the Link Operation Once the Success indication property is attached to the virtual variable, the Link Operation will automatically update this variable with the value of True\1 or False\0 depending if the link was successful or not.
Now that we know the result of the Link Operation, (via the Virtual variable), the only thing we need to decide is when do we want to tell the user that there is something wrong with his\her data entry:

Immediately after the user enters data into the State ID field or Before saving the current record
We are going to modify the logic or this program so we can see each one of these to behaviors.
Page 180
Follow these steps to validate user input: 2. Inform user of data error (during data entry)
5. Open the Customers program and go to the Logic tab 6. Create a brand new Header Line with the following settings: Set Unit to Control Set Level to Suffix Set Control Name to State ID from the Customers Table 7. Under this new Header Line, create a new operation with the following settings: Set Operation to Verify Set Mode to Error Set Text to State ID does not exist in the States Table Set Condition to an Expression NOT (X); substitute X with the letter that corresponds to the virtual variable L:State ID is OK
8. Save the modifications made to this program
Figure 78. Validate data during data entry
Page 181
There are some important points that should be reviewed:
Any operation(s) under a Control Suffix Logic Unit will execute as soon as the user wants to move the cursor away from the specified Control, in this case, the State ID field from Customers The Verify Operation in Error Mode will prevent the execution of any other logic in this program until the condition for this operation evaluates to False. Since we want to execute the Verify Operation when the Link Operation fails, in other words, when the variable L:State ID is OK is false, we can represent this logic in two different ways: 1. X = 'FALSE'LOG or 2. NOT (X) where X makes reference to the L:State ID is OK variable
Run this program and verify that the user cannot save the current record if the data entered in the State ID field is not valid This validation should occur as soon as the user wants to move the cursor away from this field
Next, we are going to modify this logic to perform the validation of the State ID field before the user wants to save the current record.
Follow these steps to validate user input: 3. Inform user of data error (before saving current record)
9. Open the Customers program and go to the Logic tab 10. Move the Verify Operation from the Control Suffix Logic Unit, into the Record Suffix Logic Unit 11. Delete the Control Suffix Logic Unit 12. Save the modifications made to this program
Page 182
Figure 79. Validate data before leaving the current record By moving the Verify Operation logic to the Record Suffix we have told the program to execute this operation only when the user wants to leave the current record.
Run this program and verify that the user cannot save the current record if the data entered in the State ID field is not valid This validation should occur when the user tries to move to a different record or tries to close the program
Page 183
Lesson 14 Writing a Lookup Program

PURPOSE OF THIS LESSON Introduce and understand the process of the creation of a Lookup Program and its use KEY TERMS The Zoom Event The Call Program Operation Select Program Control Property Select Program Model Property Push Button OBJECTIVES To create a Lookup Program To describe three different ways to call a Program To make the Lookup program available in the entire project To call a program using the Zoom event and by pressing a Button on the screen LESSON CONTENT 2.14.1 Introduction 2.14.2 The Flow of a Lookup Program 2.14.3 Steps for the Creation of a Lookup Program 2.14.4 How to call a Program (or any program) Use the Call Operation with the <F5> key Use the Call Operation with a Push Button Control User the Select Program property from the Control itself User the Select Program property from the Model Differences Between these Four Methods
Page 184
2.14.1 Introduction
This lesson will show us the behavior of a Lookup Program, the different steps for its creation, and the different ways to call it. A Lookup program is also know as a Selection program.
2.14.2 The Flow of a Lookup Program

A Lookup program allows the user to query information from a Data Source, select a specific record and bring it back to the program that initiated the call. The lifetime of a Lookup Program can be summarized on these stages: 1. While the user is in a data entry program, he\she can park the cursor on a field and press the <F5> key or double click on it to call a Lookup program related to the current field. 2. Inside this Lookup program, the user can browse the information displayed on the screen to locate the desired record. The majority of the Lookup programs do not allow the user to modify, create or delete records. 3. By pressing the <Enter> key or double clicking on a record, the user will indicate to the program that he\she wants to select the current record. The selected record is passed back to the field of the calling program. 4. By pressing the <Esc> key, the Lookup program will close without selecting the current record, and no information will be passed to the calling program.
Page 185
2.14.3 Steps for the Creation of a Lookup program

The creation of a Lookup program in uniPaaS is always the same. The following steps will outline what do we need to do to create a Lookup program, for example a States Lookup program that will be called from the State ID field. Follow these steps to create a Lookup Program: 1. Create an On-line Program in Line mode
1. Create a brand new program and name it: Lookup States 2. The Task Type for this program will be Online 3. The Initial Mode for this program will be Query 4. Make the States Data Source the Main Source for this program, bring all its columns to the data view and create a screen that will show its two columns inside a Table Control
Figure 80. Define an On-line Query program
Page 186
Figure 81. Bring all Columns to the Data View
Figure 82. Create a Line Mode screen Usually this type of programs only displays two fields on the screen, the field with a unique value, and the field with a description.
Run this program and verify that this is program displays all records from the States Table in Query mode
Page 187
Follow these steps to create a Lookup Program: 2. Create a Parameter variable to exchange information
5. Just below the Main Source entry, create a new Parameter variable using the State ID Model. Call this new Parameter: P:State ID
Figure 83. Create a Parameter Variable The attribute of this Parameter variable must be the same as the variable that is going to be used to send information to it; otherwise, we will encounter a definition mismatch while trying to update it. It is customary to declare Parameter variables at the top of the Data View tab; but in reality, they can be declared on any place inside the Data View tab. At the same time, the P: prefix used in the name of the variable is only used to denote that this is a Parameter variable, but is not really required.
Follow these steps to create a Lookup Program: 3. Change the value of the Select table option to Yes 6. Press the <Ctrl+P> keys to open the Task Properties screen 7. In the General tab, change the value of the Selection table option to Yes
Page 188
Figure 84. Set the Selection table option to Yes By doing this, the behavior of the program will change from what we have experienced so far; now this program will behave in the following way:
When the user presses the <Enter> key, the Record Suffix Level will be executed and the program will end. If the user presses the <Esc> key, the Record Suffix Level will not be executed, and the program will end.
Run this program and verify that you can close this program by pressing the <Enter> key
Page 189
Follow these steps to create a Lookup Program: 4. Update the Parameter with the user selection
8. On the Record Suffix Level, add an Update Operation that will update the value of the Parameter variable P:State ID with the current record value State ID
Figure 85. Update the Parameter Variable with the user selection Since the Record Suffix Level will be executed when the user presses the <Enter> key, but not when the user presses the <Esc> key; this is the perfect spot to place the logic that will update, or not, the Parameter variable with the current record selection.
Follow these steps to create a Lookup Program: 5. Do not allow the user to add or modify any information 9. Press the <Ctrl+P> keys to open the Task Properties screen 10. In the Options tab, change the value of the Allowed Modes setting Modify, Create, and Delete to No
Page 190
Figure 86. Do not allow data modification on this Task By doing this, the program will remain in Query mode and the user will not be able to change the mode of operation to Create, Modify, or Delete.
Run this program and verify that you cannot change the mode of this program to Create or Modify and, therefore, cannot delete any record from this Table
Page 191
Follow these steps to create a Lookup Program: 6. Place a Select and Cancel buttons on the screen (Optional) 11. Go to the Data View tab and declare two Virtual variables that will use the Models Select (Button) and Cancel (Button) respectively. 12. Press the <Ctrl+M> keys to go to the Main Form of this program 13. From the Controls palette, select the Variables tab, select the Select (Button) variable and place it below the Table Control. 14. Select the Cancel (Button) variable and place it below the Table Control
Figure 87. Adding Variables as push buttons
Page 192
Figure 88. Adding buttons to a Lookup Table program
Run this program and verify that you can close this program by pressing the OK and Cancel buttons
Page 193
2.14.4 How to Call a Program Lookup Program (on any program)

Apart to be able to execute programs from a Menu, we can call an uniPaaS program in four different ways: 1. 2. 3. 4. We We We We can can can can use use use use the the the the Call Program operation triggered by pressing the <F5> key Call Program operation triggered via a Push Button Control and a Event Select Program property of a Control from the program's screen Select Program property of a Model from the Model Repository
We will use all four methods to accomplish the same goal and at the end of this section we will compare these methods to each other so we can see their functionality and limitations. 1. Use the Call Operation with the <F5> key Since we want to call a program by pressing the <F5> key, the first thing that we need to do is to capture the Zoom event so we can connect this event to the Call Program operation; this Zoom event is internally issued by uniPaaS every time we press the <F5> key. We are going to capture this Zoom event not inside our current program, but in the Main Program of our Project; by doing this, we can reuse this logic across our Project without the need to repeat this step.
Follow these steps to use the Call Operation with the <F5> key: 1. Create an User Event to capture the Zoom event from the Main Program 1. Open the Main Program of our project 2. Press the <Ctrl+U> keys to open the User Events table 3. Create a new line and fill up its settings as follows: Set Description to <Zoom> Set Trigger Type to Internal Press the <F5> key in the Trigger and select the event Zoom Set Force Exit to Editing
Figure 89. Creating a User Event to capture the Zoom Event
Page 194
The Description column can contain any name that we want. For this course we will use the name <Zoom> just to denote that we are capturing this internal event. With the Trigger type set to Internal and Trigger set to Zoom, we will capture uniPaaS's own Zoom event and redirect it as a user event. In other words, when the user presses the <F5> key a user event called <Zoom> will be risen. We set the Force Exit column to Editing to ensure that uniPaaS will refresh the information on the control that we are parked on after pressing the <F5> key; otherwise, the user will need to <Tab> away from this field to see its updated value.
Follow these steps to use the Call Operation with the <F5> key: 2. Trigger a Call Program operation when the <Zoom> User Event is detected
4. Open the Customers program 5. In the Logic Tab, press the <Ctrl+H> keys to create a new Header Line for an Event and fill up its settings as follows: Set Event to the User Event called <Zoom> Set the Control Name to State ID; by doing this, we assure that the <Zoom> event will only take effect while the cursor is parked on the State ID Control 6. Press the <F4> key to create a new line under this new Header 7. Press the <C> key to select the Call Operation, and select the Program option
8. Select the Lookup States program as the program to be called 9. Press the <F5> key on the Arguments option; create a new line and assign it the column for the State ID field from the Customers Data Source
Page 195
Figure 90. Capture the Zoom event from the State ID Control and call the Lookup States Program using the Call Program operation There are five types of Call Operations:

Task. It calls sub-tasks that are immediate children of the current program. Program. It calls another uniPaaS program within the current project. The differences between calling programs and calling subtasks are:
Programs share information by passing arguments\parameters, while subtasks inherit access to all their ancestor variables automatically. Anyone can call a Program, while subtasks are permanently attached to their parent task and cannot be called by other programs\tasks.
By Exp. This type of call is similar to the Call Program option; with the difference that Call Exp can call different programs dynamically based on an expression that will evaluate the number of the program to call. By Name. Similar to the By Exp option, but in this case and expression will dynamically give us the Public Name of the program to call. Remote. The Call Remote operation can call an uniPaaS program from a different project that can be located on another computer or server either locally or on a different server. The Application Partitioning Services of uniPaaS must be configured to receive this call.
The Arguments screen is divided into two tables; the table on the right shows the Parameters that the called program is expecting to receive, while the left table will contain the Columns, Variables or Expressions that we want to send to this program.
Page 196
Figure 91. The Arguments screen from a Call Program Operation The Skip check box is used to send no information to its correspondent parameter. The Form property is optional and shows the identification number of a Form in the calling task. If we leave the default setting of 0, then the Main Form of the called program will appear. If we specify a number in this option, then the corresponding Form will be used as the window to contain the called task's Main window. This Form should have no Controls at all. The Return property is also optional. It gives the programmer the ability to select any kind of variable from the tasks Variable list. If the called program has a Return Value set, this value will be received into this variable.
Run this program and verify that you can call the Lookup States program by pressing the <F5> while parked on the State ID field Also verify that pressing <Enter> or the OK button in the Lookup States program, it will bring the selected record back to the State ID field; and by pressing <Esc> or the Cancel button this operation will not be performed
Page 197
2. Use the Call Operation with a Push Button Control Instead of using a short-cut key, we can decide to use a Push Button Control to call a specific program. There are two types of behaviors for Push Buttons in uniPaaS: one behavior is to allow the user to park his\her cursor on the button and activate it by pressing the <Enter> key, the <Space> bar, or clicking it with the mouse pointer; the second behavior is not to allow the cursor to be parked on the button, as a result, the only way the user can active it is to click on it with the mouse pointer. We are going to create a Not Parkable button first, and then, we are going to change it to be parkable. This method resembles the previous one on which we will capture an event, but this time, triggered by pressing a button.
Follow these steps to use the Call Operation with a Push Button (No Park): 1. Create an User Event to capture a custom Lookup States events from the Main Program
1. Open the Main Program of our project 2. Press the <Ctrl+U> keys to open the User Events table 3. Create a new line and fill up its settings as follows: Set Description to: Lookup States Set Trigger Type to None Set Force Exit to Editing
Figure 92. Creating an User Event The Description column can contain any name that we want. The Trigger Type is set to None because none of the other options fit the requirement for this event, which is, being called by a Push Button Control. We set the Force Exit column to Editing to ensure that uniPaaS will refresh the information on the field that was updated by pressing the button.
Page 198
Following the same technique as before, we declared this event inside the Main Program so every other program\task in this project can re-use its logic. Follow these steps to use the Call Operation with the a Push Button (No Park): 2. Assign the Lookup States event to a Non Parkable Push Button Model
4. Press the <Shift+F1> keys to open the Model Repository 5. Go to the Lookup States (No Park Button) Model and set its Raise Event property to the User Event Lookup States that we just created
Figure 93. Assigning User Event to Model
Page 199
There are three important things to mention here: 1. Any Model declared with a Class of GUI Display and a Attribute of Push button, is by definition, a not parkable button. 2. By attaching an event to a push button Model, it will cause a call of this event every time this button is pressed. 3. Any modifications made to this Model, will be reflected across the entire project.
Follow these steps to use the Call Operation with the a Push Button (No Park): 3. Place the Push Button Model on the screen
6. Open the Customers program 7. Press the <Ctrl+M> keys to go to the Main Form of this program
8. Right-click on the Push Button Control from the Controls pallet and select the option Lookup States (No Park Button). By doing this, we have told uniPaaS what will be the Push Button definition that we want to use for now 9. Left-click on the Push Button control from the Controls pallet and place it next to the State Name Edit Control
Figure 94. We can select a different definition for a Push Button.
Page 200
Figure 95. The label and properties of this Push Button are inherited from its Model
Run this program and verify that you cannot park your cursor on this button Also, since we have not instructed the program what to do when the Lookup States event is being called, verify that no operation is executed
Page 201
Follow these steps to use the Call Operation with the a Push Button (No Park): 4. Capture the event risen by the Push Button and trigger a Call Program operation 10. Go to the Logic tab and create a new Event logic unit with this information: Set Type to User, set Event to Lookup States 11. Under this event create a new line with the following Operation: Set Operation: Call Program Set Program ID to 3 Lookup States Set one Argument with the Variable: State ID from Customers
12. Save the changes made to this program
Figure 96. Capture the Lookup States Event triggered by the Push Button and call the Lookup program
If we run this program, we will see that the user cannot park the cursor in the Lookup States button; nevertheless, the Lookup States program is being called when the user clicks on it
Page 202
That is the way we create non-parkable buttons in uniPaaS. And the only reason why we cannot park our cursor on it, is because this control (the push button) is not connected to any variable from the Data View tab. This same rule applies to all data controls: Radio button, Edit, Tab, List Box, Combo Box and Check Box; if there is no column, variable or parameter behind a control, this control is not parkable. Now we are going to see what it takes to create a parkable button. Follow these steps to use the Call Operation with the a Push Button (Park): 1. Assign the Lookup States event to a Parkable Push Button Model
1. Press the <Shift+F1> keys to open the Model Repository 2. Go to the Lookup States (Button) Model and go to the properties for the GUI Display property, in other words, press the ... button for the GUI Display property. 3. Set the Raise Event property to the User Event Lookup States
Figure 97. Assign User Event to Model
Page 203
Please be aware of the following: 1. The Lookup States (Button) Model really is an Alpha Field with a size of 15 characters 2. What sets this Alpha Field apart from other Alpha Fields is the value in its GUI Display property; since we defined it as Push Button, instead of the default Edit, this Field will look and behave as a Push Button when is placed on a GUI screen 3. In addition, by setting the Raise Event property to call the Lookup States Event, every time this button is pressed uniPaaS will issue this event 4. The information in the Default Value property for this Alpha Field will become the label for its button 5. Any modifications made to this Model, will be reflected across the entire project
Follow these steps to use the Call Operation with the a Push Button (Park): 2. Declare a parkable Push Button on the program
4. Open the Customers program 5. At the bottom of the Data View Tab, create a new line for a Virtual variable and use the definition from the Model Lookup States (Button) 6. Press the <Ctrl+M> keys to go to the Main Form of this program 7. Delete the Lookup States Push Button control; this is the not parkable button from the previous exercise
8. From the Variables pallet select the Lookup States (Button) variable and place it in front of the State ID field. A Push Button control should appear. 9. Save the changes made to this program
Page 204
Figure 98. Create Virtual Variable based on the parkable Push Button Model
Page 205
Figure 99. Place parkable Push Button Model on the screen
Run this program and verify that you can park your cursor on this button and when it is pressed, the call to the Lookup States program is executed
Now that you know how to create parkable and non-parkable buttons, you can decide when to use them on your future applications.
3. Use the Select Program property from the Control itself Yet, another way to call a program is to connect the actual Control from the screen to the program that we want to call; the final result will be the same as in the previous steps.
Before we proceed, we should go back to the Customers program and set the Condition column for the Event <Zoom> Level to No, so this event will be disable
Page 206
Figure 100. Disable the <Zoom> Event logic Since we are going to use another way to call a program from a field itself, we have to disable the logic that previously listened for a Zoom event while in the State ID field.
Run this program and verify that pressing the <F5> key on the State ID field, it does not call the Lookup States program anymore
Follow these steps to assign a Program to a Control on the Screen
1. Open the Customers program 2. Press the <Ctrl+M> keys to go to the Main Form of this program 3. Select the State ID Edit control 4. Set the Select program property to use the Lookup States program
Page 207
Figure 101. Use the Select program property of a Control to call a the Lookup States Program
The property called Select mode, just below the Select Program one, instructs uniPaaS when the call to the program will be made:
Before uniPaaS will call the selected program when the user presses the <F5> key on this Control, when this program is terminated, the cursor will remain on the same Control. After uniPaaS will call the selected program when the user presses the <F5> key on this Control, when this program is terminated, the cursor will jump to the next available Control. Prompt uniPaaS will call the Lookup program as soon as the cursor parks on this Control.
Run this program and verify that pressing the <F5> key on the State ID field, it executes the call to the Lookup States program Test this same program while using the other options from the Select mode property
Page 208
Please notice that there is no place to specify what argument(s) we will be passing to the calling program; by default, the field that has the Select program property is the one that is sent as an argument
4. Use the Select Program property from the Model The last instance of calling a program by pressing the <F5> key will be by assigning the program that we want to call not to a Control on the screen but to the Model for that Control.
Before we proceed, we should go back to the Customers program, to the Select Program property for the State ID Control, and select the option Inherit after pressing the little button next to this entry; the value for this property should return to 0 By doing this, the Select program property line should now be displayed in black color instead of blue. While the blue color in properties denotes that the inheritance connection has been broken, a black color property indicated that the inheritance connection between this Control and its Model is up and running.
Page 209
Figure 102. Reestablish the Inheritance connection between the State ID Control on the screen and the Models that supports it
Run this program and verify that pressing the <F5> key on the State ID field, it does not call the Lookup States program anymore
Follow these steps to assign a Program to a Model
1. Press the <Shift+F1> keys to go to the Model Repository and locate the Model for the State ID Field 2. Set the Select program property to use the Lookup States program
Page 210
Figure 103. Use the Select program property of a Model to call a the Lookup States Program
Run the Customers program and verify that pressing the <F5> key on the State ID field, it executes the call to the Lookup States program
Based on this modification, we just told the project that any Control on the screen that is based on the State ID Model has the capability to call the Lookup States program by pressing the <F5> key.
Run the Customers program and verify that pressing the <F5> key on the State ID field, it executes the call to the Lookup States program
Page 211
Go to the Data Repository and Generate a Browse program for the Customers and the Publishers Tables, verify that pressing the <F5> key on the State ID field it executes the call to the Lookup States program Execute any other program that we have developed where the State ID is on the screen and verify the the same behavior is present
Due to the modification in the Model Repository, we have created a problem: Since we told uniPaaS to call a program when the user presses the <F5> key from any Control that uses the State ID Model, this means that the user can make this call from the Lookup States program itself In other words, pressing the <F5> key on the Lookup States program will cause a recursive call to itself
Execute the Lookup States program and test if by pressing the <F5> key on the State ID field, it executes a recursive call to itself
Page 212
Figure 104. Pressing the <F5> key on the State ID field causes a recursive call To fix this problem, now we need to tell uniPaaS not to call the Lookup States program if the user is parked on the State ID Control from the States Data Source.
Page 213
Follow these steps to prevent a recursive call from the Lookup States program
1. Press the <Shift+F2> keys to go to the Data Repository 2. Highlight the State Data Source and press select the State ID column 3. Set the value for the Select Program property to 0
Figure 105. Break the inheritance only for the Select program property Now that we have modified the properties for this column alone, pressing the <F5> key on the State ID column from the States Data Source will not have a recursive call.
Execute the Lookup States program and verity that pressing the <F5> key on the State ID field, does not execute a recursive call to itself
Page 214
Differences between these four Methods Every one of these method gets the job done, and they have their own advantages and limitations:
Assigning a program to a Model or Control can only call programs, it cannot call Sub-tasks; the other two methods that uses the Call Program operation can also call Sub-task. Assigning a program to the Zoom event or to Push Button requires several steps of programming every time is needed; assigning a program to a Model or Control takes only one step of programming and takes effect on the entire project or program. Assigning a Program to a Model or Control can only pass one argument: the value associated to this Model or Control; the other two methods that uses the Call Program operation can pass any number of arguments, as variables or expressions.
Page 215
Lesson 15 Writing Batch Programs

PURPOSE OF THIS LESSON To introduce the process of writing batch programs and understand their use. KEY TERMS Batch Programs OBJECTIVES Create a Batch Program Describe the differences between an On-line and a batch program LESSON CONTENT 2.15.1 Introduction 2.15.2 Creating a Batch Program Write a Clean up program Write a Data Synchronization Program Terminate a Batch Program
Page 216
2.15.1 Introduction
Until now, we have only worked with On-line programs, this lesson will deal with Batch programs. One of the many advantages of uniPaaS is how ease and fast is to write batch programs. Most development systems allow you to create simple entry and query forms but require considerable effort when writing batch-processing programs. To create a Batch program we can follow the same steps as in the creation of an On-line program: Select Main Source, select the Columns for the Data View, and design the Form, if any. Since this is a Batch program, no cursor parking will be available on the screen; the amount of information to be displayed could be kept to a minimal or show no screen at all.
2.15.2 Creating a Batch Program

A Batch program does not require user-interaction once it is running; some of the many uses of Batch programs are:

Reports Update and Reconciliation Programs Copying Records from one Table to another Deleting Records Exporting Records Importing Records
Write A Clean up Program We can instruct Batch programs to perform a single operation or a group of operations according with a set of rules that we have specified. For this section, we are going to create a Batch program that will execute several operations using the Customers Data Source: 1. Delete any record that has a 0 in the Customer Number field. 2. Clear out the Phone Number field if its current data is less than 10 characters. 3. Clear out the State ID field if its data does not match a record in the States Table. The objective of these rules is to clean up bad or erroneous information that may be saved inside the Customers Data Source. We are going to develop and test this Batch program one step at a time:
Page 217
Follow these steps to clean the data from the Customer Table: 1. Delete records where Customer Number is 0
1. Create a brand new program called: B:Clean up Customers Table 2. In the Task Properties screen, change the Task Type option to Batch 3. Set the Main Source to Customers and bring to the Data View the following 3 columns: Customer Number State ID Phone Number 4. In the Task Properties screen, switch to the Behavior Tab, press the <F5> key in the Force record delete property and assign it the expression: X=0 where X will represent the Customer Number Column from the Customers Table
Figure 106. This program will read all records from the Customers Table
Page 218
Figure 107. The Force record delete option instructs the program to delete the current record from the Main Source if its setting has the value of Yes or an Expression that evaluates to True during Runtime
Create a record in the Customers Table with a Customer Number equal to 0, verify that the record is saved, run this program and then confirm that the record was deleted
Page 219
When we set a program to be Batch, uniPaaS automatically changes the value of two settings from the Task Properties screen to keep the user interaction to a minimal:
In the Interface tab, the Open Task Window property is set to No. By doing this, the program will not display its Main Form to the user while running. In the Options tab, the Options property is set to No. With this setting disable, uniPaaS will not display to the user two confirmation windows, one at the beginning of the execution asking to verify the execution of the program, and one at the end, asking to re-execute the program.
Enable the these two settings and run the program again to see how its behavior changes
The next step is to clean up the Phone Number field if it does not contain a valid phone number.
Follow these steps to clean the data from the Customer Table: 2. Delete records where the Phone Number contains less than 10 characters
5. Open the existing B:Clean up Customers Table program 6. In the Record Suffix Logic Unit create a new Header Line and use the Update Operation to assign a blank string value (represented by two single quotes: '') to the Phone Number field under the condition: Len(Trim(X))<10 where X will represent the Phone Number Column from the Customers Table
Figure 108. The Update operation in the Record Suffix will delete any information from the Phone Number Column if it does not meet our criteria The Len function returns the size of an alpha string\variable, but it does not make a distinction between empty spaces and actual data; therefore, we need to use the Trim function to take out any empty spaces from the field before calculating its length.
Page 220
Be aware that the Record Suffix Level is always executed in Batch programs regardless of the Mode of Operation (Query, Modify, Create, etc.)
Create several records in the Customers Table with a Phone Number with less that 10 characters, verify that the records were saved, run this program and then confirm that the information for this column is gone from those records
The last thing this program will do is validate the information from the State ID field against the States Table.
Follow these steps to clean the data from the Customer Table: 3. Clear out the State ID field if its data does not match a record in the States Table
7.
Open the existing B:Clean up Customers Table program
8. In the Data View Tab use the Link Query Operation to connect to the States Table. Locate a State ID record from the States Table based on the State ID from the Customers Table. 9. Create a new Logical Virtual Variable and connect it to the Link operation so it will return the value of True if the link was successful or False if the link was not successful. 10. Inside the Record Suffix Logic Unit use the Update Operation to assign a blank string value (represented by two single quotes: '') to the State ID field from the Customers Table under the condition that: NOT (X) where X will represent the Logical Virtual Variable
Page 221
Figure 109. While the Link Query operation will establish a one-to-one relationship between the Customers and the States Table, the Virtual Variable will store the result of the link
Figure 110. The Update operation in the Record Suffix will delete any information from the State ID Column if it does not meet our criteria
Create several records in the Customers Table where the State ID doest not match any entry in the States Tables, verify that these records were saved, run this program and then confirm that the information from this column is gone for those records
Page 222
Write A Data Synchronization Program The next program that are we are going to build will recalculate the Extended Price Column for all the records in the Order Line Table.
If we take a look at the information inside the Order Lines table, we can see that the Extended Price for every record is 0 instead of the result of the operation (Qty Ordered * Unit Price)
Follow these steps to create a Batch program to recalculate the Extended Price Column
1. Create a brand new program called: B:Recalculate Extended Price 2. In the Task Properties screen, change the Task Type option to Batch 3. Set the Main Source to Order Line and bring to the Data View the following columns: Qty Ordered Unit Price Extended Price 4. In the Logic Tab create a brand new Header Line for the Record Suffix Level 5. In the Record Suffix Level, update the Extended Price Column with the result of the expression: Qty Ordered * Unit Price
Figure 111. This program will read all records from the Order Line Table
Page 223
Figure 112. The Record Suffix will update the Extended Price Column with the correct amount
Run this program and then verify that the Extended Price column has the correct information
Terminate a Batch Program While On-line program are terminated or closed when the end-user presses the <Esc> key, Batch programs will terminate once they have finished reading\processing all the available records from the Main Source that fall within the specified range. There is a way to tell uniPaaS to terminate a program (On-line or Batch) when a certain condition or expression returns the value of True. We need to create a Batch program to test this new behavior on, this new program should have the following characteristics: 1. Read all records from the Customers Data Source 2. Display on the screen the Columns: Customer Number, First Name and Last Name 3. At the end of the program, show to the user the number of records that were read\processed
Follow these steps to create a Batch program to count the number or records read\processed
1. Create a brand new program called: B:Count Customers 2. In the Task Properties screen, change the Task Type option to Batch 3. Set the Main Source to Customers and bring to the Data View the following columns: Customer Number First Name Last Name 4. Create a Form for this program with a Table Control so we can see several records at once
Page 224
5. In the Task Properties screen, in the Interface Tab set the Open task window option to Yes 6. In the Task Suffix, use the Verify Operation to display the number of records read\processed by the program by using the expression: 'Total Records: '&Trim(Str(Counter(0),'10C'))
Figure 113. This program will read all records from the Customers Table
Figure 114. This program will show all records from the Customers Data Source in a table control
Page 225
Figure 115. The last thing this program will do is to inform the user of the number of records read\processed
Figure 116. Allow this Batch program to open its window
Page 226
Figure 117. Display a confirmation dialog before and after the program runs We use the Verify Operation to display information to the user and the Counter(0) function to count the number of records read\processed so far; unfortunately the Verify Operation only displays strings and the Counter(0) function only returns numbers. The Expression Trim(Str(Counter(0),'10C')) not only converts the resulting number from the Counter(0) function into a string but it also removes any unnecessary empty spaces.
If we run this program, we should see the program's screen displaying all the records from the Customer's Data Source Once all records have been read\processed, a warning window will tell us how many they were
Page 227
Figure 118. A Warning window will tell the user the number of records read\processed The next step will be for us to instruct this Batch program to close\exit after processing a specified number of records, for example: 5 records.
Follow these steps to instruct the Batch program to close\exit after 5 records
1. Open the existing B:Count Customers program 2. In the Task Properties screen, assign the expression Counter(0)=5 to the End task condition setting
Page 228
Figure 119. When the expression used in the End task condition setting returns the value of True, the program will close\exit Every program in uniPaaS uses the End task condition and the Evaluate condition settings to decide when the program should be terminated. First, if the End task condition is set to Yes or assigned an expression that evaluates to True, the program will end, that's it. It will execute the Record Suffix Logic Unit, if needed it, then the Task Suffix, and then the program will close. Second, the Evaluate condition setting tells the program when to check if it needs to terminate; in other words, it tells the program when to evaluate the End task condition setting to see if it is Yes or True.
If Evaluate condition is
Before entering record After updating record Immediately when condition is changed
The program will evaluate the End task condition

Before executing the Record Prefix Logic Unit After executing the Record Suffix Logic Unit Within each Logic Unit (Task Prefix, Record Prefix, Control Verification, Variable Change, etc.) and after any Operation within these Units.
Page 229
Run this program and modify it so the window with the record count and the number of records displayed on the screen matches
Page 230
Page 231
Lesson 16 Writing Sub-tasks

PURPOSE OF THIS LESSON To learn how to create programs with more than one task. KEY TERMS Call Subtask The Subform Control One to Many Relationship Incremental Update
OBJECTIVES Create a sub-task Synchronize the information between the Parent program and the Child Task LESSON CONTENT 2.16.1 Introduction 2.16.2 Creating a Sub-task 2.16.3 The Screen of a Sub-task 2.16.4 Calling a Sub-task Incremental Update
Page 232
2.16.1 Introduction
Each program that we created so far cycles with only one Data Source; if we need to display or process multiple records from another Data Source we must use a Sub-task. For example: to connect one record from the Order Header Data Source with all the related records in the Orders Lines Data Source, we will have to create two programs, one with the Order Header source as its Main Data Source, and the other with the Order Line source as its Main Data Source. This type of relationship is called one-to-many (1:M). For every record in the Order Header Data Source we could have one or many related records in the Order Line Data Source.
Even when we can use the Link operation to connect to different Data Sources, this operation only retrieves one record
There are three key concepts in the use of a sub-task (also called Child program):
A sub-task is required when we need to establish an one-to-many relationship between two Data Sources. A sub-task will behave in the same way as any other program in uniPaaS; with the limitation that a sub-task can only be called from its parent program. A sub-task can see and modify any variables from any of the programs above it.
For this lesson, we are going to create an Order Entry Program. Here, the user will enter information into both Data Sources, the Order Header and Order Line. First, we need to have already created an Order Header Program with a screen similar to this:
Page 233
Figure 120. Order Header Program The logic behind this screen is as follows: 1. The Main Source for this program is the Order Header 2. There is a Link to the Customers Data Source in order to retrieve the information for the current Customer 3. On the screen, the Customer Name field contains the concatenation of the Last Name and the First Name for the current Customer 4. The is another Link to the States Table to bring the State Name for the current Customer 5. The Order Date column is initialized to today's date 6. The user cannot park on the Order Date control, the Customer Information, or the Order Total Amount control.
Page 234
2.16.2 Creating a Sub-Task

Remember that a sub-task is similar to any other program in uniPaaS. It has its own Main Source, properties, controls, expressions, variables, forms and events; the only difference is that just its parent program can call it and execute it, nobody else.
Follow these steps to setup the one-to-many relationship: 1. Create a Sub-Task under the Parent program
1. Open the Order Entry program 2. On the Navigator panel, right-click on the name of this program and select the option Create Line. If the Navigation panel is not open press the <Alt+F1> keys 3. Since we are creating a new Task, the Task Properties screen will appear. In the Task Name field type the name: Order Line 4. For the Main Source select the Order Line Data Source 5. Bring up to the Data View Tab all the columns for this Source
Figure 121. Creating a new Sub task
Page 235
Figure 122. Setting up a connection to the Order Lines Data Source
Page 236
2.16.3 The Screen of a Sub-Task
While we are in the Sub-task, if we go to the Forms Tab, we can see not only the screen of this sub-task, but also the screen of any other program above us. On the same token, we will be able to see all the Columns\Variables declared in the programs above this sub-task. While placing Columns\Variables on our screen, it is important to pay attention what Columns\Variables belongs to what task.
Figure 123. The Forms Tab shows all Forms above this Sub-task
Page 237
The next step is to create a screen for this sub-task that will allow access to its information, make sure the screen for this task is similar as the following Figure:
Figure 124. Creating a Line Mode screen for the Sub-task
Page 238
2.16.4 Calling a Sub-Task

Not because we have just created a Sub-task for our program, uniPaaS will know when to call it and what information to display, we need to configure this logic ourselves.
If we execute our Order Entry program on its current state, we will see that the Order Line screen is not being displayed because the sub-task is never called.
We are going to use a Form Control called Subform to call this Sub-task. This Form Control will instruct the parent program when to call the Sub-Task and its appearance on the screen.
Follow these steps to setup the one-to-many relationship: 2. Place the Subform Control on the Parent Screen
6. Open the Order Header program and press the <Ctrl+M> keys to go to its Main Form; do not go the Order Lines Sub task. 7. Click on the Subform Control from the Controls Pallet, and place it on the Screen
8. Arrange its size and position as shown in the next Figure
Page 239
Figure 125. Place the Subform Control on the parent program
Follow these steps to setup the one-to-many relationship: 3. Configure the Subform Control 9. Click on the Subform Control to display its properties and configure them as follows: Set the Connect to property to Sub Task Set the PRG/TSK num property to 1, the Order Line task For the Arguments property send only one argument, the Order Number Column from the Order Header Data Source
Page 240
Figure 126. Configure the Subform Control to call the Sub-task and pass the Order Number as an argument The Arguments and the Automatic Refresh property of the Subform are responsible for keeping the information of the parent and the child tasks in sync. When the Automatic Refresh property set to Yes, uniPaaS will call the Sub-task every time the value of the variables\expressions that we are sending as Arguments are changed. If its value for the Automatic Refresh were set to No, we will need to manually issue a Subform Refresh event in order to display the correct information from the child task. With the Border Style property set to No Border and the Auto Fit property set to As Control, we will ensure that the screen from the Sub-task will appear flushed inside the screen of the parent task.
If we run the Order Entry program on its current state, we will see the Order Line task is being called, but is displaying all the available records from the Order Line Data Source regardless of what is the current order number
Page 241
This behavior is due to two factors: 1. The Order Line sub-task has no Parameter declared to received the Argument (the Order Number column) that we are sending from the Order Entry program. 2. There is no logic in the Order Line sub-task that will range of information that we want to see on the screen at any given time. The following step will fix this problem.
Follow these steps to create a one-to-many relationship: 3. Range the information displayed in the Sub-task
10. Open the Order Line sub-task and click on the Data View Tab 11. Above the declaration of the first Column, create a Parameter variable using the Order Number Model. Call this new Parameter: P:Order Number 12. Range the Order Number Column, from the Order Line Source, based on the information from the Parameter variable just created
Figure 127. Create a Parameter in the Sub-task to receive the passing Argument, and range the subtask information based on this parameter
Now, if we run the Order Entry program, we will see the Order Line screen displaying only records related to the current Order Number from its parent program
Page 242
If we try to create new records in the Order Line sub-task we can see that the Order Number Column is waiting for us to enter the order number for this new record If we leave its information blank or type a number different from the current order's number, this line item record will not be associated to the current order above
The next step will ensure that any new record created on the sub-task will be automatically connected to the current record from the parent program and without the need for the user to type this information every time.
Follow these steps to create a one-to-many relationship: 4. Assign new child records to its parent record
13. Open the Order Line sub-task and click on the Data View Tab 14. Initialize the Order Number Column based on the information from the Parameter variable
Figure 128. Initialize the Order Number from Order Lines base on the Order Number from Order Header
Now when we try to create new line items for any order, we will see the Order Number Column is initialized automatically based on its parent's value
The last step will delete the Order Number Column from the Order Line sub-task's screen. Since we have ensured the correct initialization of this column, there is no need for the user to enter information or even see it on the screen.
Page 243
Follow these steps to create a one-to-many relationship: 5. Delete non-necessary information
15. Open the Order Line sub-task and press the <Ctrl+M> keys to open its Main Form 16. Click on the Order Number Edit Control (do not select the Table Control) and press the <Delete> key to delete this control
Figure 129. The Order Lines screen without the Order Number Column The next piece of logic that we will implement into this program will keep the Order Total Amount Column in synchronization with the sum of all the Extended Price amounts for the current order. Incremental Update Every time the user adds, deletes, or modifies the Unit Price and\or the Quantity Ordered of a line item in the sub-task, we will like it to be reflected in the Total Order Amount Column in the parent task. This can be easily accomplished by using the Update Operation.
Follow these steps to create a one-to-many relationship: 6. Keep the Order Total Amount in synchronization
17. Open the Order Lines sub-task and create a Record Suffix Level, if not already present 18. Create a new line using the Update Operation 19. Set it to update the Order Total Amount Column from the parent program with the expression: Qty Ordered * Unit Price 20. Set the Incremental property to Yes
Page 244
Figure 130. Add logic in the Record Suffix to synchronize the Order Total Amount An Update Operation in Incremental mode is not going to overwrite the value of a Column\Variable with an Expression, instead, it is going to add or subtract a value from it based on the following rules:
In Create Mode (while adding a new order line) The value of the expression will be added to the current value of the Column\Variable. In Delete Mode (while deleting an existing order line) The value of the expression will be subtracted from the value of the Column\Variable. In Modify Mode (while modifying an existing order line) If the value of the expression was modified, uniPaaS will either add or subtract the difference between the original value of this expression and its new value from the Column\Variable.
The Update Operation in Incremental mode only works in On-line programs and it will not synchronize existing orders that have an incorrect value in the Order Total Amount Column To fix the data from existing orders, a batch program must be created to recalculate their value
Follow the instructions detailed in the section: Exercise 8 and Exercise 9
Page 245
Lesson 17 Writing Report Programs

PURPOSE OF THIS LESSON To introduce the process of writing report programs and understand their use KEY TERMS Header Line Detail Line Footer Line Form Output I/O Devices OBJECTIVES Create a Report Program Describe the functions and options of the Form Output operation and I/O Table LESSON CONTENT 2.17.1 Introduction 2.17.2 Creating a Print Program I/O Devices Table The Form Output Operation
Page 246
2.17.1 Introduction
A report program is a Batch program that usually sends the information from a data source to a printer, to a file, or to an external device.
2.17.2 Create a Print Program

To create a print\report program we can follow the same steps as in the creation of an On-line and batch program: select Main Source, select columns to manipulate, and place fields on the form/report layout.
Follow these steps to create a Print Customers Program 1. Create Batch program
1. Create a new Batch program and call it: B:Print Customers 2. Set the Main Source to Customers 3. Bring to the Data View the following columns: Customer Number First Name Last Name Address Line 1 Phone Number
Figure 131. Read all records from the Customers Table
Run this program and verify that no output has been sent to the printer and no window is displayed
Page 247
The following step will show us how to create the layout of our printout. We can define the layout of a printout the same way we define the layout of our screens.
Follow these steps to create a Print Customers Program 2. Create Form with the layout of the print-out
4. Open the B:Print Customers program 5. Go to the Forms Tab and create a brand new line; the name for this line is irrelevant but is customary to have the same name as the program 6. Set the Width and Height properties for this Form to 163 and 10 respectively 7. Zoom in this Form and place a Table Control with all the Columns from the Data View
8. Select only Table Control and change its Style property to Windows 3-D
Figure 132. Create a new form with Class = 1
Figure 133. Place a Table Control on the Form Lesson 17 Writing Report Programs
Page 248
As previously explained, a Form in uniPaaS is used to define the screen for a program or to define the layout of the information that will be sent\received by the program. In this case, we just designed the printout for the information that we will sending to a printer. There can only be one Class 0 Form per program (this is the Main Form or screen for this program), but there can be any number of Forms with a Class greater than 0. The purpose of the Class is to associate different Forms as part of a single report or output. For example, if we were to create the following entries:
Name Print Customer Detail Print Customer Header Print Customer Footer Export Customer Detail Export Customer Header Export Customer Footer
Class 1 1 1 2 2 2
Area Header Footer Detail Header Footer Detail
Interface Type GUI Output GUI Output GUI Output Text-based Text-based Text-based
We have specified two sets of reports: one will go to the printer, and the other will go to a text file. Forms with the same Class number (any same number) are considered by uniPaaS part of the same report. The Area column is a way to label each Form according to its printing position. In addition, uniPaaS will automatically print the Header Form after every new page, but only if they are declared in the following order: Header, Footer and Detail. The Interface Type column defines the type of Controls and format that we are able to place on it and, more or less, how is this Form going to be used. The possible options are:
Text-based. Allows only Text, Edit, Line, and Rectangle Controls. Used primarily to write\read information to\from a text file. GUI Output. Allows Text, Edit, Line, Rectangle, Picture, Table and RTF Controls. Used primarily to output information to a graphical printer. Frame Set. Allow no Controls, only the definition of Frames in HTML pages. Used exclusively in the output of HTML pages. Merge. Allow no Controls. Used primarily to merge Magic Tags from a HTML page with data from the program and send the resulting merged page to a Web Browser.
The reason why we set the Width property to 163 is because 163 Dialog Units (see the Form Units property) is equal to about 11.5 inches (standard width for a letter size piece of paper). If you will like to see the measurements of a Form in Inches rather than Dialog Units, you can change the Form Units property at any time, it will not affect the position of the Controls on the Form. We set the Height to 10 Dialog Units just to have enough room to place a Table Control on it.
Page 249
Since we have a Table Control on this Form, uniPaaS automatically will expand the size of this Table Control and the Form itself to accommodate as many records per page as possible
Run this program and verify that no output has been sent to the printer and no window is displayed
I/O Devices Table Similar to the doors of a kitchen in a restaurant, usually labeled as IN or OUT; I/O Devices in uniPaaS are the doors that will allow information to get out of uniPaaS or into uniPaaS. Since in this program we want to send information from uniPaaS to a printer, we need to define an I/O Device entry that will reflect this direction.
Follow these steps to create a Print Customers Program: 3. Create an I/O File to output the information
9. Open the B:Print Customers program 10. Press the <Ctrl+I> keys to go to the I/O Files table 11. Create a brand new line; the name for this line is irrelevant but is customary to name it as the device is directed to. 12. Set the Media property to Graphic Printer 13. Press the <Alt+Enter> keys on this entry and set the Print Preview option to Yes
Page 250
Figure 134. Create a new I/O Device entry to output information to a printer
Figure 135. Set the Print Preview option to Yes to save some trees Fundamentals of uniPaaS v1.5
Page 251
This I/O Device entry is our door to a printer. We specified the Print Preview option to Yes to send the pint out to the screen before sending it to the printer. This Name column will hold any name that we want as an identification for this entry. The Media column will specify the type of source\destination for this information's entry, possible values are:

Graphic Printer. Creates a graphical information output that can be sent to a graphical printer. Printer. Creates a character-base output that can be sent to a matrix printer or a file. Console. Sends the output to a window in the user's computer. File. Writes\Reads information to\from a flat file. Requester. Sends the output back to the user's web browser that initiated the execution of this program. XML Direct Access. Allows the program to access the information of a XML-type file. Variable. Allows the program to access the information of a Blob variable containing XML-type information.
The Printer column will point uniPaaS to the actual printer that we want to user for this I/O Device entry. If we Zoom in the Printer column we will see a default list of four printers, these printers are defined outside our Project, and they are stored inside MAGIC.INI file. We can open this Printer repository from the pull down menu Options | Settings | Printers. In this repository we can create an entry for each kind of printer available to our system, for example:
Name Invoicing Reporting Sales Labels
Queue HP 5000 Series HP 1000 series Epson 120FX Dynamo
The Name column can contain any name to identify this printer, the Queue column will contain the name of the printer as specified in the Window's Printer Panel (Start | Control Panel | Printers). A printer entry with no information in the Queue column will send the information to the default printer for this computer. By putting these two pieces together, the I/O Device entry and a Printer entry, the program now has enough information to send the data to the correct destination. Since this information is located in the MAGIC.INI file, outside the Project itself, uniPaaS makes it very easy to redirect the output from one printer to another without the need to change the logic or even opening the project
Page 252
The Access column defines the direction for the flow of information. The possible values are:

Read. The information will flow into uniPaaS. Write. The information will flow out of uniPaaS. An I/O Device entry with a Media set to File and Access set to Write will overwrite the contents of the specified file if exits every time the program is executed. Append. The information will flow out of uniPaaS. An I/O Device entry with a Media set to File and Access set to Append will not overwrite the contents of the specified file if exists, it will just append information at the end of the file.
The Format column defines which control characters will be included automatically into an output or input file. The possible values for this option are:
Page. Means that Top of Form control characters will appear when a page ends and End of Line control characters will appear for every line. Line. Means that only End of Line control characters will appear for every line. None. Means that no control characters will be added to the information to be sent.
The Expression column points to an Expression containing the full path and filename of a file that will be either read by or written to, depending of the information in the Access column. Using an Expression in an I/O entry with Write Access, will redirect the output for that I/O to the specified file. The PDlg property is relevant only for a Media set to Graphic Printer. The value of Yes will instruct uniPaaS to call the Windows print dialog screen, allowing the end-user to change the default print properties. The value of No specifies that a Windows print dialog will not appear to the end-user, and that the print properties will be transferred directly to the specified printer without end-user interaction. The use of an Expression allows a dynamic value for this setting. The Rows column (only available for Media set to Printer and Console) defines the number of rows or lines per page\screen (i.e. the number of printed lines between two successive Top of Form control characters). The default is 0, which produces an output of 60 lines of data, including a 3-line header area and a 3-line footer area.
Page 253
The Form Output Operation The Form Output Operation will bring together both, the design of a Form with the configuration of an I/ O Device, to accomplish our goal.
Follow these steps to create a Print Customers Program: 4. Use the Form Output Operation
14. Open the B:Print Customers program 15. Go to the Logic Tab and create a new Header Line for the Record Suffix Level 16. Create a new line under this Header and use the Form Output Operation with the following settings: Set the Form property to: 3 Print Customers Set the I/O property to: 1 To Printer Set the Page property to: Page
Figure 136. Create the logic to sent the information from this program to the printer Since we want to print each record after is read from the Customers Data Source, and because the Record Suffix Logic Unit is executed after each record, this is the perfect place to issue the operation that will output this information to a printer, screen or file.
If we place this operation in the Record Prefix Logic Unit instead of the Record Suffix, will have the same result The Page property determines the program's behavior whenever an End of Page state occurs. This property is relevant only if the I/O Device specified in this operation has a Media of Printer, Graphical Printer or Console.
Page 254
uniPaaS has an internal event called the End of Page state (EOP). This state occurs when the Form about to be outputted is larger than the space remaining on the current page. This Page property has three possible values:
Automatic. This is the default option. uniPaaS jumps to a new page when the End of Page state is reached and continues printing. Skip. Before outputting every Form, uniPaaS checks if there is sufficient space left on the current page to accommodate the Form in full. If enough space is available, uniPaaS outputs the information; otherwise, it will skip the Form without writing it to the output media. Top. uniPaaS will jump to a new page before sending every Form to the output media. This causes the Form to be printed at the top of a new page. We can force page breaks in a report with this setting.
Run this program with a different value of the Page property every time and see how the program behaves
Page 255
Lesson 18 Creating Help Screens

PURPOSE OF THIS LESSON To introduce the designing and assignation of Help Screens KEY TERMS Prompt Help Toolkit Help Internal Help Windows Help OBJECTIVES Distinguish between Prompt, Toolkit, Internal, and Windows Help Locate the two places to attach Help so it is inherited system-wide LESSON CONTENT 2.18.1 Introduction 2.18.2 Creating a Help Screen Assignation of Help Screens
Page 256
2.18.1 Introduction
A help system is always important for an application. uniPaaS has its own help system to present information to the user in order to guide him\her to navigate in the application and manipulate its data. uniPaaS can also display the information stored in an external help file (.HLP or .CHM) developed with third-party programs.
2.18.2 Creating a Help Screen

Since the Help system is a repository by itself, the same help entry can be used on several different controls or screens. Follow these steps to create a Help System: 1. Create entries in the Help Repository
1. Press the <Shift+F4> keys to open the Help Screens repository. 2. Create three new lines, and assign the following settings to them:

Set the Name property to: Customer Number Set the Type property to: Internal Set the Text property to: Enter the Number for this Customer Set the Name property to: First Name Set the Type property to: Prompt Set the Text property to: Enter the First Name of this Customer Set the Name property to: Last Name Set the Type property to: Tooltip Set the Text property to: Enter the Last Name of this Customer
Page 257
Figure 137. Creating Help entries If we press the <F5> key while in the Text property of an Internal entry, you will see the help screen that will be displayed to the end-user when he\she presses the <F1> key. By modifying the properties of this entry we can changes the position, size, and color of this window. This Name column will hold an identification name for this entry. The Type column instructs this entry how is going to behave. Possible values are:
Prompt. They are automatically displayed in the status bar of the uniPaaS window when the cursor parks on the control assigned to it. Internal. uniPaaSs own help screens will appear when the user presses the <F1> key on the control assigned to it. Windows. This type will invoke a help system file (.HLP or .CHM) developed with a third-party program. Tooltip. They are automatically in a floating rectangle when the end-user places the cursor over a control assigned to it. URL. Specifies the HTML page that will be open when <F1> is invoked from a Browser Client program.
Page 258
Assignation of Help Screens uniPaaS's inheritance mechanism will decide where a Help entry will become available, depending of where we assign a Help entry, in other words:
If we assign a Help entry to a Model, it will take effect on every Column, Variable and Parameter that uses this Model across the project. If we assign a Help entry to a Column in a Data Source, it will take effect on every Program that uses this Column across the project. If we assign a Help entry to a Variable, a Parameter, or a Form's Control, it will take effect only on that Program.
Follow these steps to create a Help System: 2. Associate a Help Entries
3. Press the <Shift+F1> keys to open the Model Repository 4. Go to the Customer Number Model and assign its Help screen property to its help entry 5. Go to the First Name Model and assign its Help prompt property to its help entry 6. Go to the Last Name Model and assign its Tooltip property to its help entry
Page 259
Figure 138. Assigning Help entries to a Model
Run the project and make these Help entries appear on the screen
Page 260
Page 261
Lesson 19 Creating a Menu System

PURPOSE OF THIS LESSON To introduce the design and functionality of a Menu System KEY TERMS Pull Down Menu Context Menu Shortcut Key Hot Character OBJECTIVES Know the differences between pull down menus and context menus LESSON CONTENT 2.19.1 Introduction 2.19.2 Creating a Menu System Type of Menu Entries Properties of the Menu System
Page 262
2.19.1 Introduction
A menu system allows the end-user to execute programs that will allow him\her access to the information stored on the different Data Sources. uniPaaS has its own menu system to accomplish this task. We can create as many Menus as we want and we can assign these menus to screens, or Controls on screen.
2.19.2 Creating a Menu System

Follow these steps to create a Menu entries for our programs
1. Press the <Shift+F6> keys to open the Menu Repository 2. Press the <F5> key on the Default Pull down menu entry to open it. Here we will see the standard menu system that is displayed in Runtime Mode. 3. Park the cursor on the &Options menu entry, and create a new line. 4. Press the <F5> key in the Program Menu Parameters and select the Customers Program.
Figure 139. Creating a Menu entry to call a program
Page 263
Run the project and verify that we can execute our program using the newly added Menu entry
Types of Menu Entries There are six different menu options:

Program. This option will call any program from the Program Repository. OS Command. This option will execute an operating system call. Event. It raises any of the declared Events in the Main Program. Separator. The resulting menu will contain a horizontal line at this position. Menu. This is an end-user menu name. For a pull down menu at the top level, the name in the Name in Menu parameter for a Menu type entry will appear on the Menu bar. For other levels, the name in the Name in Menu parameter becomes a line of text in a menu which, when active and selected, will invoke the display of the related menu. Windows List. Since uniPaaS can keep many windows open at the same time, this menu entry will allow the user to manage them; just like you can manage several open documents using your text editor.
The Acc Key option is used to define a combination of keys to act as a short key to the menu entry.
We can specify a letter in the name to be underlined by putting an ampersand (&) character before the letter. When the menu is displayed at runtime, typing this letter will be equivalent to selecting the entry. For example, a menu with the name of C&ustomers will be displayed as Customers, in addition, we can execute this entry by pressing the <Alt+U>keys.
Page 264
Properties of the Menu System While on a Menu system entry, we can press the <Alt+Enter> keys to displays its Properties. These properties can be used to enhance or fine tune how our Menu system will behave on different scenarios.
Figure 140. Properties of a Menu entry
Page 265
Lesson 20 Creating a Security System

PURPOSE OF THIS LESSON To enable the security features in uniPaaS to prevent the execution of programs or modification of data depending on the assigned rights KEY TERMS Right User Right Group Right Public Right Super Right OBJECTIVES Know the steps in the creation of users, rights and groups Know how to create Rights into the application Know how to enforce the assigned user-rights and prevent program execution or data modification LESSON CONTENT 2.20.1 Introduction 2.20.2 Creating a Rights-Based Security System 2.20.3 Working with Secret Names
Page 266
2.20.1 Introduction
uniPaaS offers its own security system to allow the developer to create a basic system with users, rights and groups.
2.20.2 Creating a Right-Base Security System

The first step in creating a security system for our Project is to log into uniPaaS as the Supervisor of the system.
Follow these steps to create a security system for our project: 1. Log into uniPaaS as Supervisor
1. Close the current project but do not close uniPaaS 2. Go to the pull down menu Options | Logon 3. Enter supervisor in the User ID field and press the OK button
Figure 141. Login into the uniPaaS system
By default, the supervisor user in uniPaaS does not have a password assigned to it
Once we have logged successfully into uniPaaS we will be able to see the current User ID in the status bar.
Page 267
The Next step is to create some security rights for our project.
Follow these steps to create a security system for our project: 2. Create new rights into the Rights Repository
4. Open our project 5. Go to the Rights Repository and create five new entries in this table with the following settings:

Set the Name property to: Access to Customer Set the Key property to: accesscust Set the Public property to: Yes Set the Name property to: Create a Record Set the Key property to: Create Set the Public property to: Yes Set the Name property to: Modify a Record Set the Key property to: modify Set the Public property to: Yes Set the Name property to: Delete a Record Set the Key property to: delete Set the Public property to: Yes Set the Name property to: See Phone Number Set the Key property to: seephone Set the Public property to: Yes
Figure 142. Create rights for the project
Page 268
The Rights Repository is the centralized location where all the rights for the current application are stored and maintained. This Name column will hold an identification name for this entry. The Key column holds up to 10 characters, this is the internal name for each entry The Public column will instruct uniPaaS what rights will appear when any user requests to see them (Public = Yes), and what rights will be hidden from this user (Public=No). Enable\Disable Features in the Project To finalize the setup our security system, we need to enable\disable different features of our project using the rights created in the Rights Repository. Follow these steps to create a security system for our project: 3. Enable\Disable features from our project
6. Open the program: My Customer's Program 7. Make the following modifications to its Task properties screen:

Set the Initial Mode setting from the General tab to: Query Set the Modify setting from the Options tab to an Expression: RIGHTS('Modify a Record'RIGHT) Set the Create setting from the Options tab to an Expression: RIGHTS('Create a Record'RIGHT) Set the Delete setting from the Options tab to an Expression: RIGHTS('Delete a Record'RIGHT)
7.
Go to the Main Form of this program and modify the following property from the Phone Number Edit Control:
Set the Visible property to: RIGHTS('See Phone Number'RIGHT)
8. Go to the Menu Repository, go to the properties of the menu entry that call this program and make the following modification:
Set the Rights property to: Access to Customers
Page 269
Figure 143. Set the initial mode of this program to Query mode The only reason we are changing the mode of this program from Modify to Query is allow this program to run regardless if the current user does not have assigned the Create, Modify or Delete rights.
Page 270
Figure 144. Allow the user to Modify, Create and Delete data based on the rights for the current user The Rights function queries the current user's security settings for a specific right, if the user has this right the function will return a True value, otherwise it will return a False value.
Page 271
Figure 145. Make the Phone Number Edit Control visible based on the rights for the current user After creating all the required rights and assigning them to different features for our program we need to create a couple of users and assign some of these rights to them.
Page 272
Follow these steps to create a security system for our project: 4. Create Users and assign rights to them 9. Go to Options | Settings | User IDs 10. Create three new entries in this table with the following settings:

Set the User ID column to: Alan Set the following rights: accesscust, seephone Set the User ID column to: Brian Set the following rights: accesscust, create, modify, seephone Set the User ID column to: Chris Set the following rights: accesscust, modify, delete
Figure 146. Create users and assign rights to them Please notice that during the assignation of rights, even when we were able to press the <F5> key to see all available rights, only Public rights were displayed; in the other hand, if we remember the information we typed into their Key column we can make use them. Fundamentals of uniPaaS v1.5
Page 273
Log into uniPaaS as each one of the different users, then run the project and verify the behavior of the program
2.20.3 Working with Secret Names

At the beginning of this course we learned how Logical Names are very useful to keep settings that can drive the behavior of our Project, and that the majority of the configuration for our Project (Databases, Printers, etc.) resides inside a text file called MAGIC.INI. Since this MAGIC.INI file is not protected at all, any user can open it and see its information. Sometimes we will need to keep important information like access keys, user names and passwords, away from the eyes of regular users but keeping the flexibility that Logical Names give us, this is where Secret Names jump into action. Secret Names are only available to the Supervisor of uniPaaS, once we have logged into the system as Supervisor, the menu option Options | Settings | Secret Names will become available.
Figure 147. Entering Secret Names
Page 274
Secret Names are intended for use where there is a need to hide information from unauthorized users, these entries can be used for Project file access keys, user password fields, servers/DB properties and Data file access keys. The Secret Name repository is identical to the Logical Name repository, except:

Access to the Secret Name repository is allowed only to the Supervisor. Secret Names are stored in the security file that is specified as an Environment setting (by default: USR_STD.ENG). This security file is encrypted. A Secret Name can be used only in authorized fields: In the Password field while configuring the uniPaaS Broker While configuring a LDAP connection In the User Name and Password fields while configuring a Database While configuring an Access Key for the Project While configuring a SOAP Client Module While using the HTTPGet and HTTPPost functions uniPaaS will try to resolve a logical name through the Secret Name repository before searching for it in the Logical Name repository
Once we have created our Secret Names we can go back to the Database configuration and used them to secure our connectivity information:
Figure 148. Using Secret Names to hide Database login information
Page 275
Lesson 21 Deploying an uniPaaS Application

PURPOSE OF THIS LESSON To show the general steps in deploying an uniPaaS application on different environments KEY TERMS Deployment (Runtime) License Manager Cabinet File OBJECTIVES Know the different ways to install and configure uniPaaS Runtime Know how to register uniPaaS Know how to setup uniPaaS for Runtime use Know how to Shrink-wrap your Applications LESSON CONTENT 2.21.1 Introduction 2.21.2 Generating the uniPaaS Cabinet File Accessing the Cabinet File 2.21.3 Installing the uniPaaS Runtime 2.21.4 Registration of uniPaaS 2.21.5 Shrink-wrapping an uniPaaS Application
Page 276
2.21.1 Introduction
Installing a Magic/uniPaaS Application is not that different in comparison to installing any other databaseoriented program. There are several pieces of software that must be installed and configured in order to make them work together as one:
DBMS. The Database Management System that your Project will use to store information in the different tables. uniPaaS Runtime. The executable file that the user will run to be able to work with the Application. uniPaaS Cabinet File and Supporting Files. The uniPaaS Cabinet File by itself and any other external files or third-party executables that the Application will require to run the same way it ran during Development (Studio) mode.
2.21.2 Generating the uniPaaS Cabinet File

As we have seen, every piece of information about Models, Data Sources, Programs, etc. is stored in XML files inside the Source folder, since these files are no encrypted, any one could open these files and see the information inside of them. uniPaaS introduced a format for deploying an Application called the uniPaaS Cabinet File (.ECF). This file that can only be read by the uniPaaS Runtime and provides several other advantages:

All the XML files from the Source folder are compressed and protected into a single file. The size of the Cabinet File is reduced dramatically (around 10% of the size of all XML files) In order to update a site with a new version of our application, we only need to send a single Cabinet file to our customer
Follow these steps to create a Cabinet File
1. Open our Project 2. Check every Repository in the Project making sure that there are no errors 3. Go to the pull down menu File | Create Cabinet and save it on the same directory where the .edp file already resides
Page 277
Figure 149. Creating a Cabinet File from our Project
Once created, the Cabinet file cannot be modified
Accessing the Cabinet As mentioned before, only the uniPaaS Runtime can read and process the information of a .ECF file; follow these steps to open your application using the uniPaaS Runtime
Follow these steps to open a Cabinet File using the Runtime
1. Execute the uniPaaS Runtime from the list of your short-cuts, or by executing the UNIRTE.exe file located in the installation directory for uniPaaS 2. Go to the pull down menu File | Open Application 3. Locate the .ecf file that we created earlier and open it
We are now running our Application in a full Runtime environment.
Page 278
We can instruct the Runtime to automatically open a Cabinet file by specifying its full path and name in the Options | Settings | Environment | System | Start Application setting.
2.21.3 Installing the uniPaaS Runtime

At the beginning of this course, during the installation of uniPaaS, we choose to install the uniPaaS Studio option to be able to develop and test uniPaaS Projects; as a result, we got two main executables: the uniStudio.exe for development and the uniRTE.exe for deployment\testing. If we were to choose to install the uniPaaS Runtime option, the only difference in the installation process will be that we will only get one main executable, the uniRTE.exe. There installation of your Project could be either Stand Alone or Network:
Stand Alone Installation is the easies of installations. All the parts that compose the application will reside on the same computer: DBMS, Runtime, Cabinet File and Support files. Network Installation implies that several users will be running the Runtime System, reading the same Cabinet File and accessing the same tables from the DBMS. Since we will be dealing with several computers, maintenance of the system always has to be taken in consideration.
Another important element of our Project is the connectivity to the DBMS. Each DBMS is installed and configured differently. If the environment on which we are going to install our Application has already installed a DBMS, we will ask the administrator for his/her help in the configuration process. If the DBMS that our application will use is not installed on the users environment, we will ask the administrator of the network to assist us during the installation. Most of the time, DBMS installation requires administrator rights to perform this process. Installation of the uniPaaS Runtime If we are going to deploy a regular GUI application (no Web Servers or Web Services), the installation of the uniPaaS Runtime is very easy due to two factors: 1. uniPaaS keeps all its supporting files inside the same installation folder, in other words, no files are saved inside the Windows, the System32 or any other folders. 2. No especial Windows Registry entries are required for the execution of the Runtime. Based on this information, we could take the folder where uniPaaS is installed, copy it to another system, and execute it right away. If the Runtime is installed on a Server, the only configuration required on a Workstations will be:
Read access to the directory where the Runtime resides.
Page 279
If the environment does not support the Universal Naming Convention system (UNC), every workstation must have the same drive/directory mapping to the Runtime directory. A shortcut to the UNIRTE.EXE file with the start in field pointing to the same directory where the Runtime resides.
Out of the box, the MAGIC.INI file has some entries (like the [MAGIC_GATEWAYS] section) that are hard-coded to the directory where uniPaaS is installed; when uniPaaS is executed from a workstation, these entries may not be valid and cause lots of trouble. We can change their settings from this: MGDB00=F:\Magic\10_1sp2\Gateways\MGBtrieve.dll to this: MGDB00=Gateways\MGBtrieve.dll Without hard-coding the full path of a file, uniPaaS will assume that the Gateway folder resides inside the directory from where was called
2.21.4 Registration of uniPaaS

After the installation of the Runtime software is completed, we need to register it with a License. A License tells the Runtime how to behave, what limitations to impose to the Application and how many users will be allowed at the same time. Without registration, uniPaaS product (Studio or Runtime) will work with the default Demo License; this license does not limit the features of uniPaaS but the number of Tables, records or rows per Table, programs and types requests that our application can manage. The installation of a license for a Runtime environment is the same as the one explained in Lesson 2: Installation, Setup and Execution For every deployment of an application that you will do, you will need to get a license from Magic Software
2.21.5 Shrink-wrapping an uniPaaS Application

As we know, uniPaaS does not generate any executable files, which implies that the end-use has to perform two installations: install the Runtime, and install our Application files. At the beginning of this course we saw the complexity of installing uniPaaS in our computer and we may want to spare the end-user from performing this task and take on the installation of the Runtime ourselves.
Page 280
It is possible to create an installation process that will install, configure both, the uniPaaS Runtime and our Application files without the user having to know anything about uniPaaS, Logical Names, or the MAGIC.INI file. Manual Installation and Configuration If we decide to create an installation package ourselves, it means that for every release of a uniPaaS patch, update and upgrade, we need to create our own update process so the end-user can apply it on his/her system. In other words, we will create a package with this changes, and give it to our users in a easy to install format. Required Runtime Files The regular installation of the uniPaaS Runtime creates many files that the end-user will never need and they will just waste space on their system. The following table shows the minimum files that are required to run the Runtime:
Page 281
Directory
Root of uniPaaS\
Filename
CONVERT.DLL Easy32mg.dll FreeImage.dll gdiplus.dll libeay32.dll License.dat lmgr327a.dll Magic.ini MG_OCX.dll MGActDir.dll MgComCreator.dll MgCrypto.dll MgDb2Desc.dll MgDb2400Desc.dll MgFreeImage.dll mgicudt32.dll mgicuuc32.dll MgLdap.dll MGmerge.dll mgnet.dll MgOraDesc.dll MGresrc.dll mgrqgnrc015.dll Mgschemaparser.dll MgSQLDesc.dll mgstations.exe MgTlsRsc.dll MGVAR.ocx mgxerces-c_2_6.dll Msg2Mgic.exe msvcr71.dll nsldap32v50.dll PDFCreatorPilot3.dll ssleay32.dll UniRTE.exe WMQseriesC.dll WMQseriesS.dll zlibwapi.dll (All files)
Add_On\ReportGenerator (required only if your application uses the ReportGenerator) Gateways\
Only select the .DLL files that matches the DBMS(s) used to store information)
Page 282
Directory Filename
Scripts\ (All files) (required only if your application receives requests from other uniPaaS applications or the Internet) Support\ acs_pc.eng acs400.eng act_rnt.eng act_std.eng as2eb.eng clr_int.eng clr_rnt.eng clr_std.eng epson.atr fnt_int.eng fnt_rnt.eng fnt_std.eng lj3.atr mgconstw.eng prn_std.eng str_pc.eng usr_std.eng
Without the extra files, the amount of space required by the uniPaaS Runtime can be reduced from 150 MB. down to 50 MB.
Page 283
On-the-Fly Configuration We know that the MAGIC.INI file contains all the configuration settings that tells the Studio\Runtime where is the project\application, where are the database tables, what is the configuration of the DBMS, etc. Even when is easy enough to use a text editor program, like Notepad, to open the MAGIC.INI file and make the changes that we need, there are other methods to include our configuration to a Runtime environment: Command Line Using Command Line options, we can set a session-specific configuration for the Runtime. uniPaaS can accept configuration options from the command line using the same identifiers used by the MAGIC.INI file. Values received from the command line override those read from the MAGIC.INI file but they do not change the information set in this file. The syntax is: uniRTE.exe /Setting=Value /Setting=Value
Setting Any valid entry from the MAGIC.INI file. The Property name may contain a section name. If a section name is specified, then the property is localized in that section. If no section name is specified, the [MAGIC_ENV] section is assumed by default. = - The separator between setting identifier and its value. No spaces are allowed between the setting identifier, the separator, and the value. Value - The value to be assigned to the property.
Using the following example: uniRTE.exe /Owner=Company ABC /StartApplication=*c:\app\app.ecf /[MAGIC_LOGICAL_NAMES]App_Dir=*c:\app\ we are changing the Owners name setting, we are going to execute the application called app.ecf located in the c:\app\ folder, and we are setting a value for the logical name Root_Dir. The Operating System command line may be too short to hold all the necessary options. DOS, for example, allows only up to 128 characters in the command line.
The start (*) character at the beginning of the path value will ensure that uniPaaS does not read the (\) character as an escape character.
Page 284
Mini INI file Instead of typing all the different settings as parameters for the Runtime in the command line, we can place this information inside a file and tell the Runtime to read it. The syntax is: uniRTE.exe @filename
@ - This symbol instructs uniPaaS to read the following file and treat it as an addendum to the real Magic.ini filename - The full path and name of Mini INI file. The contents of this file should follow the same rules as the above Command Line option. Different options should be on different lines inside the file, for example: /Owner=Company ABC /StartApplication=*c:\app\app.ecf /[MAGIC_LOGICAL_NAMES]Root_Dir=*c:\magic\app\
Using the following example: eDevRTE.exe @c:\anyfolder\anyname.ini the Runtime will read the regular MAGIC.INI file and then it will read the ANYNAME.INI file from the specified location, if there are any duplicate settings between these files, the Runtime will use the information from the ANYNAME.INI file. The settings inside the Mini INI file will not be copied into the MAGIC.INI If we make any modifications in the Options | Settings section while in the Runtime, they will be saved into the MAGIC.INI file, leaving the Mini INI file untouched.
Page 285
APPENDIX SECTION
Appendix A The Engine Execution Rules
The information contained on this section can be found in the On-line Help document for uniPaaS; it explains how the engine executes each level of the task cycle. To be able to write complex programs in uniPaaS it is indispensable to know all the execution rules that govern the uniPaaS Engine, their functionality, execution timing, and limitations.
The Execution Engine (Loops) and Logic Unit
Every single program in uniPaaS has a set of Loops and Logic Unit:
Loops allow every single program to cycle through the different Logic Units as many times as specified by the Engine Rules, our logic, or the data that is been processed. There a two main Loops:

The Task Loop executes only once every time a program is executed. The Record Loop executes as many times as specified by our logic or the data that is been processed.
Logic Units are placeholders within each Loop where we can store logic\operations, the logic\operations will be executed according to the Engine Rules. Every Loop has two Logic Units, one at the beginning of the Loop and one at the end:
The Task Prefix Logic Unit executes its logic only once per program, at the beginning of the execution of the program The Task Suffix Logic Unit executes its logic only once per program, at the end of the execution of the program The Record Prefix Logic Unit executes its logic as many times as specified by our logic or for every record that is been processed, but before the can interact with the data The Record Suffix Logic Unit executes its logic as many times as specified by our logic or for every record that is been processed, but after the user is done interacting with the data but before is saved to the Database.
The Figure below shows the main Logic Units within the program's execution engine and their sequence within the execution of the program.
Page 286
Based on the rules detailed above and this diagram, now we know where can we place different types of logic\operations inside our program to get the desired result. 1. Where should we place the logic that will display a message to the user once a printing job is completed? 2. Where should we place the logic that will clear out variables like Number of Orders Processed and Orders Total Amount before we execute a Total Sales Report program? 3. Where should we place the logic that will validate data inputted by the user before it gets saved into the Database? 4. Where should we place the logic that will count the number of records printed by a program? The operations inside each Logic Unit are only part of many other activities performed behind the scenes by the Engine during execution, for example: database management operations, connectivity to external resources, event handling, etc. We have seen how the four basic Logic Units inside every program can give us the ability to execute our logic at several stages of execution. Some programs may require more finesse (specially On-line programs) while trying to execute logic-based end-user's interaction with the program's screen.
Answers:
1. Task Suffix 2. Task Prefix 3. Record Suffix 4. Record Prefix or Record Suffix
Page 287
The User Interaction Level is where the end-user has control over the program; this is where the user is allowed to enter data, move from field to field, press buttons, etc. uniPaaS allow us to execute logic while the program is in the Level by giving us another set of Logical Units called Control and Variable Change There are four Logical Units for Controls and one Logical Units for Variable Change:

The Control Prefix Logical Unit executes its logic before the cursor lands on a Control\Field The Control Verification Logical Unit executes its logic before the cursor tries to move away from a Control\Field and when the Engine scans this Control\Field in Fast Mode The Control Suffix Logical Unit executes its logic before the cursor tries to move away from a Control\Field The Variable Change Logical Unit executes its logic if the Variable's value was changed and before the cursor tries to move away from its Control\Field
The Figure below shows the order in which the different User Interaction Logic Units are executed when the cursor moves in and out of a Control\Field on a screen.
Page 288
The following descriptions will tell us under which conditions the Engine executes each Logic Unit and what steps are performed.
Task Logic Unit\Loop

The engine executes the following steps once per task at the begging of the task. Task Prefix Logic Unit 1. If the task is called by another task, accept any parameters into Virtual\Parameter variables. 2. Establish the task Data View, that is, which records will be processed by this task and how they shall be sorted. 3. Execute all the operations of the Task Prefix Logical Unit in the order in which they appear:
If this is an On-line task in Modify or Query mode, compute Init and Link expressions and determine how many records can fit on the screen, according to the layout of the screen. If the type for this task is set to Browser, the Chunk Size Expression property in the Task Properties screen determines the number of records that can be fetched.
4. Execute the Record Level\Loop Task Suffix Logic Unit 1. Execute all the operations of the Task Suffix Logical Unit in the order in which they appear. 2. Exit the task
Record Logic Unit\Loop

The engine executes the following steps once for every record the end-user browses in On-line tasks; for Batch tasks, once for every record included in the Data View. Record Initialization Level 1. Fetch the record into memory, so that its field values are available for processing. 2. Evaluate the Init expressions of Virtual variables and update their values. 3. If the End Check parameter is equal to Before, evaluate the expression assigned to the End Task parameter, if the value is True exit this task, otherwise, continue with the next step. 4. Execute all operations from the Record Prefix Logical Unit. 5. If the task is in Create mode, evaluate the Init expressions of the Column operations and update their values. 6. Compute all Links for the current record.
Page 289
Record Termination Level 1. Execute the operations in the Record Suffix Logic Unit based on the following conditions:

If this is a Batch task, execute all the operations in the Record Suffix Logic Unit. If this is an On-line task, execute the Record Suffix Logic Unit only if the current record has been changed. uniPaaS considers the current record to be changed if any of the following actions happened: a) The end-user edited a field, by either typing a value into it or activating the Field Editor on it. b) An Update operation of any kind modified a the value of a Column\Variable\Parameter. c) An Update operation of any kind was executed in a subtask of the current task and modified a Column\Variable\Parameter. d) An Input Form operation inserted data into a Column\Variable\Parameter. e) The Force Record Suffix property, set in the Task Properties screen, evaluates to True.
2. Handle record deletion. Record Deletion in On-line Tasks In an On-line task, when the end-user chooses to delete a record, the engine activates the following Delete procedure: a) if the record has not been modified, execute the Record Suffix Logical Unit only once, in Delete mode. b) if the record has been modified, Execute the Record Suffix Logical Unit in Modify mode, in order to perform any Update operation defined there, then, Execute the Record Suffix Logical Unit a second time, now in the Delete mode, in order to perform any delete-related operations, such as deleting child records in one-to-many relations, or Update operations using the Incremental mode. Record Deletion in Batch Tasks a) if the initial mode of the task is Delete, execute the Record Suffix Logical Unit once in the Delete mode. b) if the Force Record Delete property becomes True: Execute the Record Suffix Logic Unit in Modify mode, in order to perform any Update operation defined there, Execute the Record Suffix Logical Unit a second time now in Delete mode in order to perform any delete-related operations.
Page 290
Is not until the end of the Record Suffix Logical Unit that a record will be committed to its Database Table.
Control Logic Unit\Loop

The Control Loop is relevant only for On-line tasks; there are three different levels: 1. Control Prefix will execute any operations detailed on this level before the cursor lands on this control. 2. Control Suffix will execute any operations detailed on this level before the cursor leaves the current control. 3. Control Verification will execute any operations detailed on this level before the cursor leaves this control or when the engine processes this control in Fast Mode.
Variable Logic Unit

The Variable Logic Unit executes when the value of a variable is modified either by a user or an Update Operation.
Page 291
Appendix B Detailed Engine Flows

The information contained on this section can be found in the On-line Help for uniPaaS, and explains how the engine executes each Logic Unit within the execution of the Engine The engines execution steps depend on the type of task, On-line or Batch, and on the required mode of operations. Due to these differences, the various situations are described separately. Once you have found the situation you want to examine, you wont have to choose between too many different paths. The only exception to this rule concerns the On-line Query mode. It is identical to the Modify mode with an important difference in that all fields may accept incremental Locate input. No disk updates occur in Query mode. Batch programs with an initial task of Query do not write to disk, all tables are opened in Read Access regardless of their task table repository definitions. Program with Modify or Query modes behave the same and they are described together.
On-line Program\Task Flow

This section details the behavior of On-line programs or tasks in their different modes of operation. On-line Task - Modify or Query Mode A: INITIALIZATION OF TASK 1. Virtual\Parameter variables are assigned argument values received from the calling task, if any. Virtual\Parameter variables which do not receive parameter values are set to zero if Numeric, to blank if Alpha, to NULL if Blob, to False if Logical. 2. All database tables, which are included in the tasks Data Source repository Main Source, linked sources, and other database tables - are opened. 3. The task Data View is defined according to the Column operations from Main Source, Link Operations and Virtual variables. 4. The Range Lower/Upper expressions are evaluated first to set the Data View limits, then, the SQL Where Clause also sets data view limits for range expressions. 5. The I/O Devices are opened. 6. The operations inside the Task Prefix Logic Unit are executed, if any. 7. Any Sort rules set by the developer are executed.
8. If there is a Table Control on the Program\Task's Form, the engine will read as many records as this Table has rows; otherwise, it will only read one record.
Page 292
B: INITIALIZATION OF RECORD 1. A record is fetched. If no record is found to match the specified range criteria in the task data view, the engine switches to Create mode. 2. The Data View record is constructed by using: the Main Source and Link Operations. Any Virtual variables whose Init expressions are evaluated. 3. If the Evaluate Condition parameter is equal to Before or Immediate, the expression assigned to the End task condition parameter is checked. If its value is True, the engine goes to phase E: TERMINATION OF TASK, otherwise it will continue normal operation. 4. The Operations in the Record Prefix Logical Unit are executed, if any. C: USER INTERACTION 1. All operations that precede the Column operation of the entry where the insertion point has to park are executed in Fast mode. 2. While the user moves from control to control inside the current record, any operations specified in the following Logical Units will be executed accordingly:

Control Prefix Control Suffix Control Verification Variable Change
3. The end-user can terminate the record interaction in one of the following ways:

Closing the program's screen Issuing an Exit Action Switching to a different Mode of Operation than the current one (Create, Modify, Query, etc.) Jumping to a different record Pressing the key(s) mapped to the Next Field Action when the insertion point is on the last Control on the screen and the Record Cycle parameter in Task Control is set to No. Pressing the <Enter> key while the program is set to be a Selection Table.
D: TERMINATION OF RECORD 1. If the data view was modified or if the Force Record Suffix parameter is set to Yes: The Record Suffix Logic Unit is executed in Modify mode, Any modified records (for both Main Source and Linked Sources) are written to disk. 2. If the record was deleted by the user or the Force Record Delete parameter is set to Yes: If there was no modification to the current record, the Record Suffix Logical Unit is executed in Delete mode; otherwise, If the current record was modified, the Record Suffix Logical Unit is executed first in Modify mode, and then in Delete mode.
Page 293
3. The task goes to phase E: TERMINATION OF TASK if any to the following conditions are true: The Evaluate condition property is set to After or Immediate and the End task condition is evaluated to True or The end-user issued an Exit Event 4. If the task did not terminated it moves back to phase B: INITIALIZATION OF RECORD to process the next record. E: TERMINATION OF TASK 1. All operations from the Task Suffix Logic Unit are executed, if any. 2. All I/O Devices are closed. 3. All Data Sources are closed. 4. Temporary sort files are closed and deleted, if any. 5. The task terminates. On-line Task - Create Mode A: INITIALIZATION OF TASK 1. Virtual variables are assigned argument values received from the calling task, if any. Virtual variables which do not receive argument values are set to zero if Numeric, to blank if Alpha, to NULL if Blob, and to False if Logical. 2. All data sources that are included in Data View Tab are open. 3. The task Data View is defined according to the Column operations from the main Data Source, and Linked Sources. The Range Lower/Upper expressions are evaluated to set the Data View limits. The SQL Where Clause also sets data view limits for range expressions. 4. I/O Devices are opened. 5. All operations from the Task Prefix Logical Unit are executed, if not changing modes. 6. The programmer's Sort operations are performed. B: INITIALIZATION OF RECORD 1. The Data View record is constructed by: Evaluating the Init expressions of the Column variables. Resetting the Column variables that do not have Init expression. Evaluating the Init expressions of the Virtual variables. Fetching the linked rows. 2. If the Evaluate condition property is set to Before or Immediate, then, the expression assigned to the End Task condition property is evaluated. If it is True, the engine goes to the Appendix B Detailed Engine Flows
Page 294
phase E: TERMINATION OF TASK; otherwise, continues the normal operation. 3. All operations from the Record Prefix Logic Unit are executed. C: USER INTERACTION 1. All operations that precede the Column operation of the entry where the insertion point has to park are executed in Fast mode. 2. While the user moves from control to control inside the current record, any operations specified in the following levels will be executed accordingly: Control Prefix Control Suffix Control Verification Variable Change 3. The end-user terminates record interaction in one of the following ways: Selecting Exit Switching to a different Mode of Operation (Create, Modify, Query, etc.) Pressing the key(s) mapped to the actions: Previous Line, Next Line, Previous Page, Next Page, Begin Page, End Page, Begin Table, End Table. Pressing the key(s) mapped to the Next Field action when the insertion point is on the last field and the Record Cycle property is set to No. Pressing the <Enter> key while the program is set to be a Selection Table 4. When the end-user terminates the interaction with the current record: If the current record was modified, or the expression assigned to the Force record suffix property evaluates to True, or if the program is set as a Selection Table and the user pressed the <Enter> key, then the engine will scan in Fast mode the rest of the operations of the Data View Tab from the current column to the last entry in this Tab. D: TERMINATION OF RECORD 1. If the Data View was modified or if the Force Record Suffix property is set to Yes: The operation in the Record Suffix Logic Unit are executed in Modify mode, Modified Data View records (of both Main Source and Linked Sources) are written to disk. 2. If the record was deleted by the user or the Force Record Delete property is set to Yes: If there was no modification to the current record, Record Suffix Logical Unit is executed in Delete mode; If the current record was modified, the Record Suffix Logical Unit is executed in first in Modify mode, then in Delete mode. 3. If the Evaluate condition is set to After or Immediate, the End task condition is evaluated. 4. The task is set to terminate if one of the following situations are true: The end-user issues the Exit event. The expression in the End task condition property returned the value of True
Page 295
5. If the task actually terminates, control goes to phase E: TERMINATION OF TASK, otherwise it moves back to phase B: INITIALIZATION OF RECORD. E: TERMINATION OF TASK 1. All operations from the Task Suffix Logic Unit will be executed. 2. All I/O Devices are closed. 3. All Data Sources are closed. 4. Temporary sort files are closed and deleted, if any 5. The task exits.
Batch Task Flow

Batch Task Modify, Query or Delete Mode A: INITIALIZATION OF TASK 1. Virtual variables are assigned argument values received from the calling task if any. Virtual variables which do not receive argument values are set to zero if Numeric, to blank if Alpha, to NULL if Blob, and to False if Logical. 2. All Data Sources that are included in Data View Tab are open. 3. The task Data View is defined according to the Column operations from the main Data Source, and Linked Sources. The Range Lower/Upper expressions are evaluated to set the Data View limits. The SQL Where Clause also sets Data View limits for range expressions. 4. If the Allow Options property is set to Yes, the Start Execution dialog is displayed to the user. If the user selects the option No the engine goes to phase C: TERMINATION OF TASK step number 6. 5. The programmer's Sort operations are performed. 6. I/O Devices are opened. 7. The On-Change flag is set to True.
8. All operations from the Task Prefix Logic Unit are executed. B: EXECUTION OF RECORD 1. The record is fetched. If no record is found in the task Data View, the engine switches to phase C: TERMINATION OF TASK.
Page 296
2. The record view is constructed by using the main Data Source, Liked Sources and Virtual variables. The Virtual variables are initialized with the values resulting from their Init expression evaluation. 3. If the Evaluate Condition property is set to Before or Immediate, the expression assigned to the End task condition is evaluated. If it is True, the engine executes the phase C: TERMINATION OF TASK; otherwise, it will continue normal operation. 4. If the On-Change condition flag is set, the engine executes all lower On-Change Prefix Logic Units, from high to low. 5. All operations from the Record Prefix Logic Unit are executed. 6. If Initial Mode parameter is Query, the Record Suffix Logic Unit is executed and the engine jumps to step 9. 7. If Initial Mode parameter is not Delete: Record Suffix Logic Unit is executed in Modify mode, Modified Data View records from the Main or Linked Sources are written to disk.
8. If the Initial mode parameter is set to Delete, or if the Force record delete parameter is set to Yes: Record Suffix Logic Unit is executed in Delete mode, The record is committed to the Database. 9. If the Evaluate condition parameter is set to After or Immediate, the expression assigned to the End task condition is evaluated. If it is True, the engine goes to the phase C: TERMINATION OF TASK; otherwise, it will continue normal operation. 10. The On-Change condition is checked. If it is True, the On-change flag is set and the engine executes all lower On-Change Suffix Logic Unit, from bottom to top. 11. The engine goes to execute phase B: EXECUTION OF RECORD. C: TERMINATION OF TASK 1. All On-Change Suffix Logic Units are executed once, from bottom to top, provided that at least one record has been processed. 2. If the Records per page parameter are different than 0, the Engine fills the required number of detail lines to match this value. 3. All operations from the Task Suffix Logic Unit are executed. 4. I/O Devices are closed. 5. If the Allow Options parameter is set to Yes, the Execute Again dialog is displayed to the user. If the user selects the option Yes the engine goes back to execute phase A: INITIALIZATION OF TASK from step 6. 6. All data sources are closed. Fundamentals of uniPaaS v1.5
Page 297
7.
Temporary sort files are closed and deleted, if any.
8. The task exits. Batch Task - Create Mode A: INITIALIZATION OF TASK 1. All data sources included in the Data View Tab are opened. 2. The task's Data View is defined according to the Column operations from the Main and Linked Sources. The Range Lower/Upper expressions are evaluated to set the Data View limits. 3. If the Allow Options parameter is set to Yes, the Start Execute window is displayed to the user. If the user selects the option No, the engine goes to execute the phase C: TERMINATION OF TASK from step 5; otherwise, it will continue normally. 4. The programmers sort operations are performed. 5. All I/O Devices are opened. 6. All Virtual variables are reset. 7. All operations from the Task Prefix Logic Unit are executed.
B: EXECUTION OF RECORD 1. All Column variables are initialized. 2. If the Evaluate condition parameter is set to Before or Immediate, the expression assigned to the End task condition is evaluated. If it is True, the engine goes to the phase C: TERMINATION OF TASK; otherwise, it will continue normal operation 3. All operations inside the Record Prefix Logical Unit are executed. 4. The Record Suffix Logical Unit is executed in Create mode. 5. Modified data view records, from the Main or Linked sources, are committed to their Database. 6. If the Force record delete parameter is set to Yes, the Record Suffix Logic Unit is executed in Delete mode. 7. The current Main Source record is deleted and committed to its Database.
8. If the Evaluate condition parameter is set to After or Immediate, the expression assigned to the End task condition parameter is evaluated. If it is True, the engine goes to the phase C: TERMINATION OF TASK; otherwise, it will continue normal operation. 9. The engine goes back to execute phase B: EXECUTION OF RECORD.
Page 298
C: TERMINATION OF TASK 1. If the Records per page parameter are different than 0, the engine fills the required number of detail lines to match this value. 2. All operations inside the Task Suffix Logic Unit are executed. 3. All I/O Devices are closed. 4. If the Allow Options parameter is set to Yes, the engine displays the Execute Again window to the user. If the user selects OK, the engine goes back to execute phase A: INITIALIZATION OF TASK from step 4. 5. All Data Sources are closed. 6. Temporary sort files are closed and deleted, if any 7. The task exits.
Page 299
Appendix C How uniPaaS Prepares the Data View

When uniPaaS starts a task, the engine identifies which records will be included in the Data View Editor before executing operations in the Task Prefix logic units. It does this as follows: 1. It examines the data view operations, looking for Column operations for variables from main and linked tables, and Virtual operations and parameters, and includes all these variables in the Logical Record and Row. 2. uniPaaS evaluates the Task Range expression and any Range lower and upper expressions in their order of appearance in the Data View Editor. These Range criteria limit the records that can be included in the data view. If you make Range active during runtime, the end-user can further limit the range of records included in the data view. For a data view created form an SQL table, uniPaaS also evaluates and performs the uniPaaS and the DB added where clauses. 3. If you have entries in the Sort repository, the engine sorts the data according to the specified index segments. If you make the Sort function active during runtime, end-users can perform their own sorts over the data view record. Only records that comply with the range criteria are sorted. The uniPaaS task may be based on a SQL statement defined in the uniPaaS SQL Command task object. In this case, the data view is prepared by the SQL database to which the SQL statement is director and all the standard uniPaaS data view preparation is bypassed. However, uniPaaS maintains normal operation in the states after the data view preparation stage. The variables used for such a SQL-based data view are usually virtual variables, because the data view is not based on the usual structure that uniPaaS recognizes a data source definition in the Data repository.
Data View Tuning

The Range expression in the Range Window provides a more flexible way to define the record set in the task data view. When the Range expression is not a lower/upper value pair, it may contain noncontiguous ranges and set other complex conditions based on any of the logical records variables. The Task Range Order field allows you to set the actual sequence, ascending or descending, in which records will be displayed and processed. If both the Task Range property and Select Range lower/upper expressions are specified, the engine will use them all in an AND relation to determine the set of records for the data view. Other range fields are described below:

Field models have a Range field in the Field Model Properties sheet. The Column list lets you enter a range value for a column entry for a data source. The SQL Where Clause determines a range based on SQL syntax using uniPaaS variables
The Record Data view Instance

When the engine processes a particular logical record from the task data view, that instance of the data view includes values for the variables in the Variable list. The term logical record is used to distinguish this instance. A logical record contains one set of values including values from any linked tables, from the overall task data view.
Appendix C How uniPaaS Prepares the Data View
Page 300
Page 301
EXERCISE SECTION
Exercise 1 Creating Models
Create a Model for each one of the items on the following table:
# 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
17 18 19 20 21 22
Model Name Customer Number First Name Last Name Address Line State ID State Name City Phone Number Publisher Number Publisher Name Item ID Item Description Qty Available Unit Price Order Number Order Date
Order Total Amount Order Line Qty Ordered Extended Price Percent Discount Select (Button)
Attribute Numeric Alpha Alpha Alpha Alpha Alpha Alpha Alpha Numeric Alpha Alpha Alpha Numeric Numeric Numeric Date
Numeric Numeric Numeric Numeric Numeric Alpha
Picture #9 UX19 UX29 X30 UUA X20 X30 (###) ###-#### #9 X40 U15 X30 5C N6.2C #9 ##/##/####
N7.2C #3 #3 N6.2C 3.2% X10
Notes
Set its Default Value to: 00/00/0000 if using Btrieve as your DBMS
23
Cancel (Button)
Alpha
X10
24 25
Lookup States (No Park Button) Lookup States (Button)
Push button Alpha
N/A X15
* The Raise Event property is located inside the GUI Display property to see it.
Set its Range from 0 to 100 Enter it as follows: 0-100 Set its Default Value to: &OK Set its GUI Display to: Push Button * Set its Raise Event to: Select Set its Default Value to: &Cancel Set its GUI Display to: Push Button * Set its Raise Event to: Cancel Set its Class to: GUI Display Set its Format to: &Lookup States Set its Default Value to: &Lookup States Set its GUI Display to: Push Button Leave the Raise Event blank GUI Display property, press the ... button next to the
Press the <F5> key on the property Raise Event, set the Event Type to: Internal, then, press the <F5> key on the Event field and select the desired event. Once you have created all these Models; park you cursor at the top of the Model Repository table (our cursor should be blinking next to the # symbol) and press <F8> to check them. Exercise 1 Creating Models
Page 302
Exercise 2 Creating Tables

Create all the Tables of our application following each of the definitions below: Data Source 1.- Customers (Data source name: Customers) Columns Definition # Column Name Based on Model 1 Customer Number Customer Number 2 First Name First Name 3 Last Name Last Name 4 Address Line 1 Address Line 5 Address Line 2 Address Line 6 City City 7 State ID State ID 8 Phone Number Phone Number Index # 1 2 3 Definition Index Name Customer Number Customer Name Phone Number
Segments Customer Number Last Name First Name Phone Number
Type Unique Non-Unique

Non-Unique
If you are using a SQL-type DBMS, check the Primary Key box for the unique index, also, set the Null Allowed property to Yes for every column that is not part of the primary key. Data Source 2.- Publishers (Data source name: Publishers) Columns Definition # Column Name Based on Model 1 Publisher Number Publisher Number 2 Publisher Name Publisher Name 3 Contact First Name First Name 4 Contact Last Name Last Name 5 Address Line 1 Address Line 6 Address Line 2 Address Line 7 City City 8 State ID State ID 9 Phone Number Phone Number Index # 1 2 3 4 Definition Index Name Publisher Number Publisher Name Contact Name Phone Number
Segments Publisher Number Publisher Name Last Name First Name Phone Number
Type Unique Non-Unique Non-Unique

Non-Unique
If you are using a SQL-type DBMS, check the Primary Key box for the unique index, also, set the Null Allowed property to Yes for every column that is not part of the primary key.
Page 303
Data Source 3.- Inventory Columns Definition # Column Name 1 Item ID 2 Item Description 3 Qty Available 4 Unit Price 5 Publisher Number Index # 1 2 3 Definition Index Name Item ID Item Description Publisher Number (Data source name: Inventory)
Based on Model Item ID Item Description Qty Available Unit Price Publisher Number Segments Item ID Item Description Publisher Number Type Unique Non-Unique Non-Unique
If you are using a SQL-type DBMS, check the Primary Key box for the unique index, also, set the Null Allowed property to Yes for every column that is not part of the primary key. Data Source 4.- Order Header Columns Definition # Column Name 1 Order Number 2 Customer Number 3 Order Date 5 Percent Discount 6 Order Total Amount Index # 1 2 3 Definition Index Name Order Number Customer Number Order Date (Data source name: Order_Header)
Based on Model Order Number Customer Number Order Date Percent Discount Order Total Amount
Segments Order Number Customer Number Order Date
Type Unique Non-Unique Non-Unique
Exercise 2 Creating Tables
Page 304
Data Source 5.- Order Line Columns Definition # Column Name 1 Order Number 2 Order Line 3 Item ID 4 Qty Ordered 5 Unit Price 6 Extended Price Index Definition # Index Name 1 Order Number 2 Item ID (Data source name: Order_Line)
Based on Model Order Number Order Line Item ID Qty Ordered Unit Price Extended Price
Segments Order Number Order Line Item ID
Type Unique
Non-Unique
If you are using a SQL-type DBMS, check the Primary Key box for the unique index; also, set the Null Allowed property to Yes for every column that is not part of the primary key. Data Source 6.- States Columns Definition # Column Name 1 State ID 2 State Name Index # 1 2 Definition Index Name State ID State Name (Data source name: States)
Based on Model State ID State Name
Segments State ID State Name
Type Unique Non-Unique
Page 305
Exercise 3 Creating Data Entry Programs

Create the following programs so the user can enter data into the different Tables in the application.
Customer Entry
Create a program that will allow the user to add, modify, and delete records from the List of Customers Table. This program should follow these characteristics:

Display the fields Customer Number, First Name, and Last Name inside a table; the rest of the fields should be outside the Table Control Do not display the Minimize and Maximize buttons for the screen
Publisher Entry
Create a program that will allow the user to add, modify, and delete records from the List of Publishers Table. This program should follow these characteristics:

Display the fields Publisher Number, and Company Name inside a table; the rest of the fields should be outside the Table Control Do not display the Minimize and Maximize buttons for the screen
Inventory Entry
Create a program that will allow the user to add, modify, and delete records from the Inventory Table. This program should follow these characteristics:

Display the all the fields inside a table Do not display the Minimize and Maximize buttons for the screen
State Entry
Create a program that will allow the user to add, modify, and delete records from the States Table. This program should follow these characteristics:

Display the all the fields inside a table Do not display the Minimize and Maximize buttons for the screen
Exercise 3 Creating Data Entry Programs
Page 306
Exercise 4 Modifying Data Entry Programs (with Validate)

Make the following modifications to each one of these programs:
Customer Entry
This program should follow these validations:

Inform and prevent a user to save a record with an empty Customer Number Inform and prevent a user to save a record with an empty First Name and/or Last Name Inform and prevent a user to enter information in the field Address Line 2, if Address Line 1 is empty
Publisher Entry

Inform and prevent a user to save a record with an empty Publisher Number Inform and prevent a user to save a record with an empty Company Name Inform and prevent a user to enter information in the field Address Line 2, if Address Line 1 is empty
Inventory Entry

Inform and prevent a user to save a record with an empty Item ID Inform and prevent a user to save a record with an empty Item Description
State Entry

Inform and prevent a user to save a record with an empty State ID Inform and prevent a user to save a record with an empty State Description
Page 307
Exercise 5 Modifying Data Entry Programs (with Link)

Make the following modifications to each one of these programs:
Customer Entry

Inform and prevent a user to save a record with an State ID value that does not exist in the States Table, except for an empty State ID Display the State Name of the current State ID to the right of this field but do not allow the user to modify it
Inventory Entry

Inform and prevent a user to save a record with a Publisher Number value that does not exist in the Publishers Table, except for a Publisher Number equal to zero Display the Company Name of the current Publisher Number to the right of this field but do not allow the user to modify it
Exercise 5 Modifying Data Entry Programs (with Link)
Page 308
Exercise 6 Creating Lookup Programs

Create the following programs to permit the user to select a record from the different Tables in the application.
Customer Lookup
Create a program that will allow the user to select a record from the Customers Table. This program should follow these characteristics:

Display only three fields: Customer Number, First Name, and Last Name; all of them inside a table Do not display the Minimize and Maximize buttons for the screen Display the screen in the upper-right corner of the monitor Do not allow the user to modify the information on this screen By pressing the <Enter> key or by pressing a [OK] button, the lookup program will terminate bringing the selected record to the calling program By pressing the <Esc> key or by pressing a [Cancel] button, the lookup program will terminate without bringing the selected record to the calling program If the calling program is running in Query mode, do not update any information on that program
Publisher Lookup
Create a program that will allow the user to select a record from the Publishers Table. This program should follow these characteristics:

Display only two fields: Publisher Number, and Company Name; all of them inside a table Do not display the Minimize and Maximize buttons for the screen Display the screen in the upper-right corner of the monitor Do not allow the user to modify the information on this screen By pressing the <Enter> key or by pressing a [OK] button, the lookup program will terminate bringing the selected record to the calling program By pressing the <Esc> key or by pressing a [Cancel] button, the lookup program will terminate without bringing the selected record to the calling program If the calling program is running in Query mode, do not update any information on that program
Inventory Lookup
Create a program that will allow the user to select a record from the Inventory Table. This program should follow these characteristics:

Display only three fields: Item ID, Item Description and Qty Available; all of them inside a table Do not display the Minimize and Maximize buttons for the screen Display the screen in the upper-right corner of the monitor Do not allow the user to modify the information on this screen By pressing the <Enter> key or by pressing a [OK] button, the lookup program will terminate bringing the selected record to the calling program By pressing the <Esc> key or by pressing a [Cancel] button, the lookup program will terminate without bringing the selected record to the calling program Do not allow the user to select an record with a Qty Available < 1 If the calling program is running in Query mode, do not update any information on that program
Page 309
State Lookup
Create a program that will allow the user to select a record from the State Table. This program should follow these characteristics:

Display only two fields: State ID, and State Name; all of them inside a table Do not display the Minimize and Maximize buttons for the screen Display the screen in the upper-right corner of the monitor Do not allow the user to modify the information on this screen By pressing the <Enter> key or by pressing a [OK] button, the lookup program will terminate bringing the selected record to the calling program By pressing the <Esc> key or by pressing a [Cancel] button, the lookup program will terminate without bringing the selected record to the calling program If the calling program is running in Query mode, do not update any information on that program
Assign all these Lookup programs to their respective fields, either by adding Call operations or by changing the property of the respective Models.
Exercise 6 Creating Lookup Programs
Page 310
Exercise 7 Creating Cleanup Batch Programs

Create the following Batch programs to maintain the information from the different Tables in the application.
Customer Cleanup
At the end of the execution of this program, display the total number of records read and the total number of records modified for each one of the following processes:

Delete records where Customer Number is 0 Clear out the field Phone Number if its current data is less that 10 characters Clear out the field State ID if its current data does not match a record in the States Table
Publisher Cleanup

Delete records where Publisher Number is 0 Clear out the field Phone Number if its current data is less that 10 characters Make the first character of the City uppercase; for example, it will change the value irvine to Irvine Clear out the field State ID if its current data does not match a record in the States Table
Inventory Cleanup

Delete records where Item ID is empty Clear out the field Publisher Number if its current data does not match a record in the Publishers Table
State Cleanup
Delete records where State ID is empty
Order Cleanup

Delete records from the Order Header and Order Line, where Order Number is empty Clear out the field Customer Number if its current data does not match a record in the Customers Table Recalculate the value of the field Order Total Amount based on the sum of all the Extended Amount values from the Order Line Table that correspond to each order.
Create a Batch program called System Cleanup that will call all the above Batch programs.
Page 311
Exercise 8 Creating Search Programs

Create the following programs to permit the user to search for information from the different Tables in the application. Each search program will consist of two tasks: A front-end program where the user will type the information that he/she wants to locate, and a sub-task that will display the result of the search. These two programs should be displayed as a single screen.
Customer Search
Create a program that will allow the user to search records from the Customers Table. This program should follow these characteristics:

The only search-able fields will be: Customer Number, First Name, Last Name and Phone Number The user can press a [Clear] button to clear the values of all the search-able fields When the user presses the <Ctrl+Enter> keys or clicks on a [Search] button, the lower window will display the result of this search The user should not be able to modify any information in the result window
Publisher Search
Create a program that will allow the user to search records from the Publishers Table. This program should follow these characteristics:

The only search-able fields will be: Publisher Number, Contact First Name, Contact Last Name and Company Name The user can press a [Clear] button to clear the values of all the search-able fields When the user presses the <Ctrl+Enter> keys or clicks on a [Search] button, the lower window will display the result of this search The user should not be able to modify any information in the result window
Inventory Search Create a program that will allow the user to search records from the Inventory Table. This program should follow these characteristics:

The only search-able fields will be: Item ID, Item Description and Publisher Number The user can press a [Clear] button to clear the values of all the search-able fields When the user presses the <Ctrl+Enter> keys or clicks on a [Search] button, the lower window will display the result of this search The user should not be able to modify any information in the result window
Exercise 8 Creating Search Programs
Page 312
State Search
Create a program that will allow the user to search records from the State Table. This program should follow these characteristics:

The only search-able fields will be: State ID, and State Name The user can press a [Clear] button to clear the values of all the search-able fields When the user presses the <Ctrl+Enter> keys or clicks on a [Search] button, the lower window will display the result of this search The user should not be able to modify any information in the result window
Orders Search
Create a program that will allow the user to search records from the Order Header Table. This program should follow these characteristics:

The only search-able fields will be: Order Number, Order Date and Customer Number The user can press a [Clear] button to clear the values of all the search-able fields When the user presses the <Ctrl+Enter> keys or clicks on a [Search] button, the lower window will display the result of this search The user should not be able to modify any information in the result window
Page 313
Exercise 9 Creating an Order Entry Program

Make the following modifications to the Order Entry Program:

Initialize the Order Date with the current system date. Do not allow the user to enter information in the Unit Price field. Do not allow the user to enter information in the Extended Price field. Do not allow the user to enter information in the Order Total Amount field. Do not allow the user to enter a Qty Order greater than the Qty Available for the current Item ID. The Extended Price field should always be equals to: Qty Ordered * Unit Price. If the user enters a Percent Discount value, the Order Total Amount should be updated accordingly. In the Table control, in the form for the sub-task add the Item Description field from the Inventory Table. Initialize the Unit Price field that is displayed on the screen with the Unit Price from the Inventory Table for the current Item ID. Do not allow the user to leave the Item ID empty.
Exercise 9 Creating an Order Entry Program
Page 314
Exercise 10 Creating Report Programs

Create the following Batch programs to allow the user to print information from the different Data Sources in the project. These Batch programs will receive several parameters, these parameters will tell the report what records to print.
Customer Report
Create a program that will allow the user to print records from the Customers Table. This program should follow these characteristics:

It will receive three parameters: Customer Number, First Name, Last Name and Phone Number This program will print any records that matches the received information on these parameters The layout of the report will be a table containing only the fields: Customer Number, First Name, Last Name, and Phone Number. Each page of the report will print a header, the header will contain the following information: Date and Time when this program was executed, a Title for this report, and Page Number In the footer of the last page of the report the number of records printed should be displayed
Publisher Report
Create a program that will allow the user to print records from the Publishers Table. This program should follow these characteristics:

It will receive three parameters: Publisher Number, Contact First Name, Contact Last Name and Publisher Name This program will print any records that matches the received information on these parameters The layout of the report will be a table containing only the fields: Publisher Number, Contact First Name, Contact Last Name and Publisher Name Each page of the report will print a header, the header will contain the following information: Date and Time when this program was executed, a Title for this report, and Page Number In the footer of the last page of the report the number of records printed should be displayed
Inventory Report
Create a program that will allow the user to print records from the Inventory Table. This program should follow these characteristics:

It will receive three parameters: Item ID, Item Description and Publisher Number This program will print any records that matches the received information on these parameters The layout of the report will be a table containing only the fields: Item ID, Item Description and Publisher Number Each page of the report will print a header, the header will contain the following information: Date and Time when this program was executed, a Title for this report, and Page Number In the footer of the last page of the report the number of records printed should be displayed
Page 315
State Report
Create a program that will allow the user to print records from the State Table. This program should follow these characteristics:

It will receive two parameters: State ID, and State Name This program will print any records that matches the received information on these parameters The layout of the report will be a table containing all the fields of this Table Each page of the report will print a header, the header will contain the following information: Date and Time when this program was executed, a Title for this report, and Page Number In the footer of the last page of the report the number of records printed should be displayed
Orders Report
Create a program that will allow the user to print records from the Order Header and Order Line Tables. This program should follow these characteristics:

It will receive two parameters: Order Number, Customer Number This program will print any records that matches the received information on these parameters This report will print the information from the Order Header Table and all the records from the Order Line Table related to the same order number; just like a regular invoice layout
Go back to each one of the Search programs and add a Print button to their screen. This new button will call their respective Print programs and pass the required parameters to print specific records.
Exercise 10 Creating Report Programs
Page 316
Page 317
FEEDBACK FORM
Course Name:____________________________ Instructor's Name:____________________________ Company Name:__________________________________________________ Date:______________ 1. Was the class relevant to your needs? Very relevant Relevant No relevant at all
2. What was your level of experience using this tool before coming into the class? Fairly proficient Intermediate Basic Little or no knowledge 3. How was the quantity of information presented on this course? Too much Just right Not enough, because:__________________________ 4. How was the instructors pace during the course? Too fast Just right Too slow 5. How useful was this training manual? Very useful Useful Not useful, because:____________________________
6. How would you rate the instructors knowledge of the material? Expert Average Beginner 7. How would you rate the overall learning experience? Learned a lot Learned something Learned very little, because:_____________________ 8. I will like to add the following topics to this class:
9. I wish the class didn't sped so much time in:
10. I wish the class could have spent more time in:
11. If I were to take another class of uniPaaS, I will like it to covert the following topics:
12. Additional Comments:

Send your comments to: marionette_66@operamail.com
FEEDBACK FORM

uniPaaSV15 StudyGuide

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

uniPaaSV15 StudyGuide

Загружено:

Авторское право:

Доступные форматы

STUDY GUIDE

Fundamentals of uniPaaS v1.5

Fundamentals of uniPaaS v1.5

Part 2 uniPaaS Programming................................................................................59

LESSON 11 FORM DESIGN..................................................................................................................137 LESSON 12 COLUMN, UPDATE, VERIFY

LESSON 13 ONE-TO-ONE DATABASE RELATIONSHIP (1:1)...............................................................................167 LESSON 14 WRITING

MENU SYSTEM...................................................................................................257 SECURITY SYSTEM................................................................................................261

ORDER ENTRY PROGRAM......................................................................................310

EXERCISE 10 CREATING REPORT PROGRAMS...............................................................................................311

Fundamentals of uniPaaS v1.5

About this Study Guide and Course

About this Study Guide and Course

Type Style Italic

Courier Bold ALL CAPITALS Initial Capitals <Enter> <Shift+F3>

Fundamentals of uniPaaS v1.5

Where the Main Topics of this Manual are Explained

About this Study Guide and Course

Fundamentals of uniPaaS v1.5

Part 1 Introduction to uniPaaS

Lesson 1 The Magic Concept

1.1.1 Introduction What is uniPaaS?

1.1.2 The Magic Concept

Fundamentals of uniPaaS v1.5

Lesson 1 The Magic Concept

Fundamentals of uniPaaS v1.5

1.1.3 Features and Benefits of the Magic Methodology

Lesson 1 The Magic Concept

Fundamentals of uniPaaS v1.5

Lesson 1 The Magic Concept

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

Lesson 2 Installation, Setup and Execution

1.2.2 System Requirements

1.2.3 The uniPaaS CD

Fundamentals of uniPaaS v1.5

1.2.4 uniPaaS Installation

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Figure 7. Type of Setup

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

Component Name Deployment Modules

Database Gateways Bundled Products

FlexLM License Server

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

Fundamentals of uniPaaS v1.5

Lesson 2 Installation, Setup and Execution

1.2.5 Directory Structure

Fundamentals of uniPaaS v1.5

1.2.6 Activation of the Database Gateways

Follow these steps to activate/deactivate the uniPaaS Gateways

Database Manager System

Lesson 2 Installation, Setup and Execution

Failed to load driver...

Fundamentals of uniPaaS v1.5

1.2.7 Entering you License