SBasic Command Families

For a full list of the commands in each family, as well as examples see the Sesame Programming Guide

Array Commands

Formal Array Information

If you have declared an array (see the Variables section in the Sesame Programming Guide), commands such as Dims, DimLimit, ElementType can return information about its dimensions and type. Formal arrays require that you know in advance how large your array needs to be. In situations where the dimensions may vary, SBasic provides Dynamic Arrays (below).

Generic Arrays

A Generic Array is a reference to an existing array variable, and can be used to sort an array of any element type. Because it is a reference to the array, rather than the array itself, SBasic does not have direct access to it. Use a Generic Array only if you want to pass an array to another function as an argument.

SBasic includes a set of access functions that can get values from a Generic Array and set elements (values) in arrays. To get an idea of how these functions can be used in a subroutine designed for generic arrays, see the Using Generic Arrays sample program in Appendix 2 of the Sesame Programming Guide.

Dynamic Arrays

Dynamic Arrays are not variables that you declare. They are created, destroyed and accessed using SBasic functions. They allow you to create and use arrays that are sized at runtime based on factors such as field value or the result of a calculation.

String Arrays

In many situations, you might find StringArrays more intuitive and easier to deal with than the more formal arrays above. A StringArray is simply a list separated values (usually by a semicolon(;)).The String Array family of commands provides powerful tools to work with this list

var aa as string
	aa = "one;two;three;four"

This could also be a string array of field/layout element names, items for a selection list, etc. When creating string arrays, care must be taken to avoid spaces on either side of the semicolon separator.

Using StringArray commands you can: find/get one or more values out of a the list, add/edit/delete values in the list, change the order of the values in the list, find out how many values are in the list, strip the duplicate values out of the list, change the separator, or work with more than one list at a time.

Binary Math Commands

Allow you to operate on the individual bits in an integer. Very valuable for storing a series of yes/no choices in a very compact way.

Date/Time Commands

Use these to get and work with dates and times. Can be used to work with dates and times that appear in your own data, to return values from your local or server computer, as well as return portions of dates, such as the month or day of the week.

Sesame's internal date format is YYYY/MM/DD. If you use Text/String functions such as @Right or @Left to operate on dates, you should do so using this format. For example, to assemble a date which is the first day of the current month:

var vTheFirst as Date
	vTheFirst = @Left(@Date, 8) + "01"

Drawing Commands

Provide a number of low level drawing capabilities that allow you to draw directly on your forms. Typically, each command accepts an element and a set of pixel coordinates. The element serves as an "anchor" point for the drawing. The coordinates are relative to the position of this element, though the drawing is not limited to the confines of the element. Once a drawing is done, it will be remembered and refreshed when the form is drawn until you either clear the drawing or close the form.

Use drawing commands to provide information or visual representations of your data. Allow you to draw a variety of pictures, charts, predefined or user-defined shapes, text on your forms to provide messages/instructions, and control the color and font of drawn items.

Element Attributes Commands

These are the properties of layout elements, including color, position, etc. Provide tools you can use to control the look and some of the behaviors of your forms and reports as they are used.

Some Element Attribute commands operate on individual elements. These can be used to do things like make an element visible based on the User ID, change the color of an element, or set search criteria that will be filled in if you return to the Retrieve Spec. Many of these attributes already have separate commands (such as Visibility) that can be used, but this family of commands allow you to affect any attribute of an element by learning only one command, even if more attributes are added to elements later on.

// Change the label of an element
#include "sbasic_include.sbas"

	Attribute(Company, ATTR_ID_LABEL, "Company Name")
	ForceRedraw()

Some Element Attribute commands allow you to work on a single element, while others operate on groups of elements. The latter allow you to affect settings like ReadOnly or Visibility on your entire form, or create custom Undo capabilities. For a list of modifiable element attributes, see the Sesame Programming Guide.

Element Reference Commands

Many SBasic commands require a reference to the actual element as an argument (as opposed to the value in that element), such as the Element Attribute and the User Interface commands. Element Reference commands return and work with references to the elements on your form, allowing you to create generic ways to provide element references to other commands that require them. Using this family of commands you can get and use a list of element names based on different criteria, get information about an element, and create and manage a reference to an element.

Event Management Commands

These provide control over how Sesame handles different events, such as a key being pressed. They also allow you to trigger your SBasic event programming without actually causing the event itself, for example, triggering a command button on a different form. With this family of commands you can control which keystrokes Sesame responds to, set a program to run on a timer, tell Sesame to notice additional events and run a program when they occur, get information about the last event, and trigger code on other forms.

External Database Application Management Commands

There are several families of External Database Application management commands or "X-Commands". Each family serves a different purpose, but they all operate on records in an external database - which may be in a different application, another database in the current application, or even the same database in which you are currently working.

Application Commands

Using the Application commands you can load (open) and unload external applications (DeferredOpenApplication, UnloadApplication).

XResultSet Commands

The XResultSet family of commands are the most flexible of the X-commands. If you are using any other commands for external database access, consider using these instead - they allow you to retrieve records, get and set values, delete records, reparent natural child records, and more. Because these commands access the database records directly, you don't need a form to do things like mass update a group of records, sort, or even run a report. They are also faster than the other X-commands, in most cases. The XResultSet commands also provide flexible search criteria.

To use these commands, first get a result set by using a command like @XResultSetSearch. Then, use the handle (a number that tells Sesame which group of records you want to work with) that is returned in the other XResultSet commands you call. When you are finished with a particular group of record, release your result set with XResultSetClose.

In addition to the above, using these commands you can also manage and navigate the records in a result set, get and change values in the result set records, and print a report in an external database.

X-Lookup Commands

The commands in the X-Lookup family retrieve values from an external database. They differ in the number of records they return, the number of values from each record they return, and what they do with the returned values. Some of the commands in this family include statement as well as function versions. Statements do not return a value. Functions make the retrieved value available. (For more on statements and functions, see the XLookup Commands section in the Sesame Programming Guide). The function versions of the "X" family commands are more versatile than their statement counterparts. For example, you can place an @XLookup function inside another function which then uses the retrieved value in further processing.

Note: If an "X" family statement cannot retrieve the external value, the target or destination element will remain unchanged. In contrast, if an "X" family function is unsuccessful, it will return an empty value (""), and the target of the assignment, if any, will be blanked. For this reason, these functions should be used with a conditional, such as If something <> "" (is not blank) then do the lookup. The something is usually a reference to the key in the current record that the program will use to find the matching external record. If the key is blank, the function will return a blank value. In such a case, you might not want the existing value in the current record to be changed (blanked).

Most of the commands in this family take four arguments - filename, key, ext_key, and source. A few also take a fifth - target. For an explanation of these arguments, see the Sesame Programming Guide.

With this family of commands you can: get a single value from the first matching record, get a single value from all matching records, get multiple values from the first matching record, and get multiple values from all matching records.

File I/O Commands

Allow you to create, append to, read and delete external text files from programming. With these commands you can generate entries in a log file when certain conditions are (or aren't) met, store and update subsidiary information in plain text files and bring them into your applications, read the contents of a delimited text file into an SBasic array, parse out the individual values, then distribute them to your database elements, as well as many others.

Financial Commands

The financial commands provide functions that are specific to financial calculations, such as loans, amortization and interest calculations.

Forms/Records Commands

Provide tools for you to manage your form values, subform values, records and result set navigation from SBasic. In general, commands that begin with "Form" or "@Form" allow you to specify a particular form. Those that do not - operate on the current form. This family of commands allows you to work with values or records, and navigate result sets.

Macros and Program Control Commands

Provides essential tools for automating your applications. Macro commands run a macro. Program control commands perform an automation task, or transfer focus and program control to another element.

Mathematical Commands

Provides a variety of mathematical functions. In addition to general math, these functions also include trigonometry, the ability to round numeric values, work with a list of numeric values, and generate a random number.

Menu Tree Commands

Enable the programmer to manipulate the items on Sesame's Command Menu tree. They allow you to control which commands are available and how they appear. They can be used in conjunction with @UserID, @Group and/or @UserParameter to make different menu choices available to different users.

Network Commands

These commands can be used to interact with websites, manage email, communicate with other Sesame servers, etc. They include email, alternate Sesame server, FTP, HTTP, and TCP/IP.

Operating System Commands

Allow you to interact with your operating system to perform tasks like file management and work with external programs.

Printing Commands

If you want to enhance an application by adding the ability for users to print merge letters, data, summaries, reports or formatted documents on-the-fly, this family of commands has the tools. These commands also include easy ways to merge your data into external documents and to print out your forms as well as controlling print settings, getting information about the current page, and selecting a printer.

Reports Commands

Most of SBasic works in almost any context, however, there are a few commands that apply specifically to reports. With these commands you can: make a report break based on whatever criteria you want, print out a report with or without user interaction, and postprocess the HTML in a report before it's sent to the printer.

Spec Management Commands

When you retrieve records, sort, import, export, etc., you use a Spec to set the options and specific behavior for the task. Outside of SBasic, you work with your Specs using the Spec Manager and the Spec Window. To work with your Specs in programming, you use the Spec Management commands. Each type of Spec has a pair of SBasic commands to load and run that type of Spec. There is also a single command that can load and run any kind of Spec, as well as performing a variety of other operations.

State Information Commands

"State" refers to "how things are now".
The State Commands are designed to answer questions such as:
"What mode am I in?"
"Which database is this?"
"Who is using me now?"
"What was the last Invoice Number used?"
"Are things changed/blank/unique?"
"What is my Form doing/allowed to do?"
"Did an error just occur?"
...and so on

Text/String Commands

Works with pieces of text, also called strings. Many SBasic programming tasks involve taking apart, putting together or otherwise manipulating text. These commands provide the tools to do so. With Text/String commands you can: measure, replace or remove part of, find something in, or change the look of the text, as well as produce particular characters.

Typecast Commands

Explicitly instruct Sesame to treat a particular value as a certain type. This is important when working with different types of values. Sesame will try to guess what you intend, but it is better to not make computers guess. These commands are useful for adding a piece of text to a number, concatenating two numbers together (rather than adding them), or subtracting dates to get the numbers of days between them.

User Interaction Commands

Communicating with the user is a common programming requirement. This command family offers the tools for getting and giving information. You can show a message, ask for information, offer a list of choices, make your own custom dialog box, and intercept keystrokes.

User Interface Commands

Provides tools to control how the Sesame interface looks and what options it offers you as you work. Also includes tools to control the look and behavior of your forms.

Element Commands

Affect elements that you create on your Forms and Reports. For example you can: change the look, size, position or behavior of your elements. You will also find additional commands for Text, Subform, Tab Group, Image, and List elements (such as Combo Boxes and List Boxes).(See the Element Attributes Commands for a wider range of controllable attributes.)

Menubar, Application Menu and Command Tree Commands

Affect parts of Sesame itself, including the menubar and the Command Tree. With these commands you can: show a panel of customized buttons instead of the Command Tree, change the Sesame Menu Bar or Command Tree state, and make a different Sesame Tab than the Application Menu the default Sesame Tab.

Sesame Interface Commands

Commands to change the behavior of the Sesame interface. With these commands you can: change the wording or language of Sesame interface elements, enable/disable warnings, change where a popup list appears, or play a sound.

Memory Menu Commands

List of values that appears when you press Alt-Enter. Normally, Sesame maintains this list for you, but you can control it with the commands in this section.

XML Commands

Because XML is an extremely common format, the XML files used and created by Sesame are useable in many other applications and programs, and vice-versa. Unlike HTML, which has a set of predefined tags, XML allows the author to define their own tags and notes, based on the needs of their application. These commands are able to read, create and parse XML file formats.