Xbasic

Description

Guides for using Xbasic.

Name
Description
A Tutorial in Xbasic

Xbasic is Alpha Anywheres built-in programming language. Out of the box, Alpha Anywhere is a powerful database and application development software package. You can use Alpha Anywhere for lots of different information management needs without doing any programming by using the Alpha Anywhere menus, commands, and Genies.

Addressing Types

There are four basic types of addressing available in Alpha Anywhere.

Building Multi-Tenant Applications - Dynamic Connection Strings

A multi-tenant application is an application that is shared by many different customers. Salesforce.com is a good example of a multi-tenant application. There are typically two different approaches to building a multi-tenant application. These are:

Canceling Events

All of the events whose names are prefixed with "Can" can be canceled, thus preventing the event from occurring. The CANCEL()command is used to cancel an event.

Change In Way AEX Files are Used in a Web Application

Describes how to alter an application to work without a5w_load_aex(), which is no longer needed.

Check the logs

The Application Server can record a variety of useful information in different log files. The value of these log files in detecting and troubleshooting any problems is immeasurable. Many times, application users will not report what they presume to be minor errors, or they may not even be aware of something like a missing image which, if present, would enhance the usability or appearance of the application.

Classes

Classes are easy to define and use in your applications. When you open the Script Editor, you will notice that the toolbar has two new icons (4th and 5th icon in the image below) for creating new classes and new enumerations.

Classes in Namespaces

In Implementing an Xbasic Class we defined a class:

Creating a Login Page

Code examples and a short guide on how to create a login page.

Declaring a Variable

Before a variable is used either by a script or in an expression, it must be declared. A variable can be declared either explicitly (as a formal declaration in a script, a table, a set, a form, or an application) or implicitly (by assigning it a value for the first time in a script). In general, a variable declaration must specify two things: the name of the variable, and the type of data the variable will contain.

Developing Applications with Xbasic

An index of pages relating to developing applications in Xbasic.

Functions and Expressions

Functions are pre-defined operators which can be used in an expression to perform an operation. Expressions, which are similar to mathematical equations, are used throughout Alpha Anywhere to specify search criteria, put records in a particular order, link tables in a set, and more.

How Pages are Rendered

Perhaps you wonder what happens to the Xbasic code that you put into an A5W page. Perhaps you ask yourself, "How does the browser know what to do with Xbasic?". The answer is that the Application Server processes the Xbasic code and replaces it with standard HTML and JavaScript.

Implementing an Xbasic Class

Following the design logic discussed in Designing an Xbasic Class, we can implement the beginning of an Xbasic class to call a stored procedure as follows. Note that not all the desired features have been implemented, as discussed in the "to do" comments. In the first section, we define the class with global scope, and the two member properties. Notice that one property is completely protected, and the other has mixed visibility. We could have omitted the global scope modifier, as it is the default.

Making Statements Conditional

The most common and useful conditional statement in the Xbasic language uses the IF ... THEN ... ELSE ... END IF syntax. The statement begins by testing whether an expression is True (evaluates to .T.). If the expression is True, the Application Server executes the statement after the THEN clause. If the expression is False (.F.), the Application Server executes the statement after the ELSE clause. The following example uses the DATE() function to return the current date. It then uses the CDOW() function to determine if the current day is "Saturday".

How to make User-Defined Functions Available to a Web Application

The Alpha Five HTML Editor, and any code window in Alpha Five, will automatically detect and recognize UDFs (User-Defined Functions) defined in the current database function library.

"Maximum Stack Depth Exceeded" Error Message

The "maximum stack depth exceeded" error message can occur if you put a script on the OnFetch event and you scroll through records quickly, or if you put a script on a button and then press the button repeatedly. There may be other ways in which the error can occur. The error occurs because the script is invoked a second time before the current instance of the script has finished executing.

Xbasic - OLE Automation - Implementing Callback Event Handlers in Xbasic

This topic discusses how you can write Xbasic code to handle callback events when running OLE automation code.

Parameters that Can be Passed to Global Functions

You can pass any Alpha Anywhere variable type to a Global Function. This includes variables of type:

Parsing XML Documents with Xbasic

Alpha Anywhere has a powerful XML parser built-in that can be used as an alternative to the Microsoft XML parser. The advantage of the Xbasic XML parser is that it can use all of the powerful string functions in Xbasic. The Microsoft XML parsers are more complex to use because you have to use OLE Automation.

Passing Variables by Reference

It is possible to pass variables by reference, using the byref keyword. If the receiving function changes the value of the variable, the sending function will see those changes. Assume you have the following function named test().

Preventing an Event From Firing Twice

Sometimes an object's event will fire more than once. If this causes your code to run more than once, the following strategy will fix the problem. In your autoexec script add the following code.

Protected Variables

The Application Server supports 'protected' variables. Any variable name that starts with ' protected ' (e.g. ' protectedIsLoggedOn ') can only be set using Xbasic code in a page, and cannot be set from the URL. For example: http://myserver/page1.a5w?session.protectedIsLoggedOn=yes will not create the variable ' session.protectedIsLoggedOn '.

Retrieving a Pointer to a Control

There are several ways to get the pointer to the control. The first way is to use the .CHILD() method and name the control. These examples refer to a button control, but other types of controls work the same way.

Scripts vs Functions

Scripts and functions are different in several important aspects.

Setting the Script Recording Level

You can determine whether the Script Recorder records operations (such as Append, Copy, Export etc.) as Low level, or high level Xbasic commands. For example:

Subclasses and Inheritance

In Designing an Xbasic Class we offhandedly asked "Do we need 14 subclasses, one for each different database API?" and answered "It's one way to go." Let's explain what subclasses are, and why are they useful. Subclasses are classes derived from a base class. In Xbasic, that is done with the INHERITS keyword:

Testing and Using an Xbasic Class

In general, it's good to test Xbasic code of any sort first in an Interactive window. When you find good sequences for testing, you can copy them into Xbasic scripts, along with notes about the expected output. Your Xbasic scripts can easily include code to set up and tear down test databases.

The Code Editor

You write Xbasic scripts in the Code Editor. The Code Editor is a multi-tabbed window that allows you to edit multiple scripts at the same time. The Code Editor always includes at least one tab called the Interactive window where you can test individual lines of Xbasic code and see immediate results. For more information on using the Interactive window, see Testing Xbasic Statements in the Interactive Window.

Transform Code Utility

The Code > Transform command is a very powerful script editing tool for advanced Xbasic programmers. This utility has several built-in functions.

Understanding and Using Dot Variables

After you create a pointer variable, you may add to it any number of "child" variables of different types. These are known as dot variables.

Understanding Data Types

The Xbasic programming language supports 11 types of variables (see Variable Data Types and Scope ). You will find yourself using the following types of variables.

Understanding the Programming Process

Hopefully, you (the developer of a database application) realize that Web Publishing allows you to create applications without actually programming. The various genies, utilities, and Action Scripting allow you to generate programs by dealing with design issues at a higher level, and letting the Application Server generate and run the necessary programs in the background.

Auto-Load Compiled Library

Here is an example of how you might use the Auto-Load Compiled Library: Say that you have developed an application called MyApp (the database is called MyApp.adb ). You are now ready to distribute your application to your customers, but you want to make sure that they cannot see any of the source code of your application.

Using ADO (ActiveX Data Objects) with Xbasic

Looks at connection objects, SQL commands, the recordset object, updating records, inserting records

Using Ask Variables

In this example, you will create an Xbasic script that prompts the user for the name of the customer, and then prints the corresponding mailing label. This lesson uses Xbasic scripting (not Action Scripting) and is intended for users with some experience with Xbasic.

Using the Xbasic Code Editor

The Xbasic Code Editor is used to write Xbasic scripts in applications. It includes features, such as syntax highlighting and auto-complete, to make it easy to read and write Xbasic.

Using the Xbasic Explorer to View Object Properties

To determine the list of properties associated with an object, use the Xbasic Explorer. To display the Xbasic Explorer, select View > Code editor from the Control Panel menu. For example, if you have a form called Customer, navigate in the Xbasic Explorer to Objects > Windows > Customer > Properties to see a list of the properties associated with the form (as shown below):

Using the Xbasic Window

By default, the Xbasic window shows the Raw Xbasic code for the operation. Raw Xbasic means the code shown is the exact code for the currently defined operation. It's a direct translation of what's in your Operation Card. The Raw Xbasic view is great for seeing what's going on behind-the-scenes when you are creating an Operation, but Raw Xbasic has little meaning outside the Operation Card. That's where the Processed Xbasic view comes in. Using the radio buttons, you can switch the view between Raw Xbasic, Processed Xbasic, and Processed without Confirmation dialogs.

Using Xbasic to Select a Record and Display a Form

Button1 runs Xbasic code that loads the Invoice form to display the details of the invoice selected in the embedded browse.

Variable Indirection

Variable indirection refers to the situation when you want to manipulate a variable, but the name of the variable that you want to operate on is stored in another variable. The following session in the Alpha Anywhere Interactive window illustrates the point.

Variable Scoping and Nested WITH ... END WITH Commands

When you nest WITH ... END WITH commands, it is important to understand how Xbasic treats variables DIMmed in different name-spaces. If a WITH ... END WITH command is nested within another WITH ... END WITH construct, the inner name-space is called the child name-space and the outer name-space is the parent name-space. Any variable that is DIMmed in the parent name-space will be visible in the child name-space. Any variable that is DIMmed in the child name-space will not be visible in the parent name-space (unless the variable name is prefixed with the name-space name, as in: name-space.variable ). The following Xbasic script demonstrates this. In this script, "A" is the parent name-space and "B" is the child name-space. The variable, firstname is DIMmed in the parent name-space. It is therefore visible in the child name-space.

Viewing Xbasic Code Generated by a Procedure

Instructions for viewing Xbasic code generated by a procedure.

Working with .Net Arrays

Arrays in Xbasic use one-based indexing. In other programming languages, arrays are zero-indexed. In this guide, you will learn how to work with .Net arrays in Xbasic.

Writing Dialog Event Scripts

Web publishing applications only. Form event scripts provide an opportunity to respond to or process the input from a dialog (form) web component. You can run scripts when the following events occur.

Writing Expressions

When you pass an expression to a function or method, you are passing a line of Xbasic code as a character string. as result, whether the expression is used to filter or order records, whether it evaluates to a character or a logical value, the argument is type C (character). There are several principles that you should understand when writing an expression argument.

Xbasic - DIMMing Variables

A change has been made in how Xbasic operates when DIMMing a dot variable. If the user has not explicitly specified the scope in the DIM statement, Alpha Anywhere will now try to see if the dot variable parent container already exists in all scopes (GLOBAL, SHARED, etc. ) and if so, it will DIM the variable in that scope rather than creating a new locally scoped variable. It is possible that this change will break an existing application in some way. We think that chance of this breaking existing applications is extremely small, but if so, the change to your Xbasic to fix the problem will likely be very simple, as explained below. The following example will illustrate the point.

Xbasic Change Record

The Xbasic Change Record action changes the contents of a record without opening a form or browse. The user does not have to be aware that changes are being made.

Xbasic Class Syntax

The syntax in this article describes Xbasic classes in Backus-Naur Form (BNF).

Xbasic Features

Alpha Anywhere now supports GUIDs as an intrinsic Xbasic data type (designated as type 'K'), just as Character, Numeric, Logical, Time, etc. are intrinsic Xbasic data types. Support for GUID data types is important for Active-Link tables as some SQL databases use GUIDS for primary keys. You can DIM a variable as a GUID, (e.g. DIM varname as K), or you can use the curly bracket notation to specify a value of type 'K' (just as curly bracket notation is used to specify a Date value). The following Interactive window session shows examples:

Xbasic Script Context

When you run a script that is attached to a toolbar button, the script has the same context as the active window. The aliases this and parentform, used in a script attached to a toolbar button, refers to the active window. For example, assume that you have a toolbar with this Xbasic code attached to one of the buttons on the toolbar:

Xbasic with Classes

You should find the new Xbasic classes to have most of the capabilities of classes in C#, Java, and Visual Basic .NET without being too complex to understand. In general, object-oriented programming and classes attempt to make software more robust and reusable. They do this in a number of ways.