Document Conventions | Xbase++

Each statement, directive, command, function, class, and operator is an item. Items are arranged in alphabetical order by name. If there are synonyms (e.g., LastRec() and RecCount()), each item is replicated in full. Methods supported by different classes are also replicated in full, but have class-specific information added. Each item begins on a page by itself so you can easily find the item you need.

Each entry is divided into the subsections listed below. If a subsection is inappropriate for a particular item, it is omitted.

Each item is listed with the name of the item followed by a short description describing the purpose or action of the item.

Syntax defines a prototypical usage of the specified item with metasymbols for user input. If the item is a function or method, it is specified followed by a return value metasymbol. See the Symbols and Conventions section below for more information on metasymbols and other special symbols used in the syntax representations.

See also is an alphabetical list of items or item groups related to the usage of the current item.

The structure of items is designed to facilitate use based on the level of expertise you may have with an item. If you are experienced, a quick glance at the item name, short descriptor, and syntax sections should give enough information. If you are less experienced, read the more detailed information thoroughly.

This document uses symbols and metasymbols to specify items in a general way. Symbols identify special items and behaviors. For example, keywords and metasymbols enclosed in square brackets are optional. The following is a complete list of symbols used in syntax:

Symbol	Description
<>	Indicates an item you supply, such as a variable name or literal value.
( )	Within syntax specification, indicates function argument list. At the end of syntax specification, describes multiple behaviors.
[ ]	Indicates optional item or list.
{ }	Indicates a code block or a literal array.
\|\|	Indicates a code block argument list.
-->	Indicates a function return value.
...	Repeated elements if followed by a symbol. Intervening code if followed by a keyword.
,	List item separator.
\|	Indicates two or more mutually exclusive options.
@	Indicates that an argument must be passed by reference.

Metasymbols describe the general nature of basic syntax elements. A metasymbol is a data type designator followed by a logical descriptor. The data type designation is a prefix chosen from the table below.

Prefixes are always lowercase and logical descriptors are always capitalized. Logical descriptors describe the meaning of the argument the metasymbol represents. For example, cString represents any character string and cCompanyName is a string holding a company name. If an argument supports more than one data type a prefix symbol is specified for each datatype (WHEN blPreValid). If an argument is specified as a list of options separated by the '|' character then the parameter is polymorph. Each list element corresponds to one of the data types supported, and is specified with the respective prefix followed by the logical descriptor. For example, DbSelectArea( <nWorkArea> | <cAlias> ) --> NIL.

Argument types are specified using a general data type designator. If a character string must be defined as a literal character expression in parentheses, the corresponding metasymbol still is cString. However, the syntax which must be used to define the argument is specified in the description of the argument.

Type Prefix	Description
a	Array
b	Code block
c	Character expression
co	Class object
d	Date expression
e	Interval
exp	Expression of any type
l	Logical expression
m	Memo field
n	Numeric expression
o	Object
t	Timestamp
u	Undetermined
x	Extended expression

The Xbase++ language reference uses capitalization and type styles to distinguish between language elements and discussion of them. The following list defines the convention for each element:

Element Example	Description
Abs(<nNumber>)	Syntax specification
<nNumber>	Metasymbol in syntax specification and text
COPY TO	Keywords, defines and commands are all uppercase in syntax and text
customer *)	Table and field names are always lowercase
Traditionally, Xbase languages use uppercase or mixed case names for tables and fields. This naming scheme can still be found in some of the code sections contained in this documentation. However, modern database management systems often are case-sensitive, so upper or mixed case names should no longer be used!

Changed sections in the documentation are marked in red color.

This documentation uses a color scheme for classifying the current grade of the various product features. A feature can be a command, function, method, class, operator or a chapter in the programming guide.

Each feature is classified regarding its overall grade which covers implementation, automated validation/verification as well as sample and documentation status. The resulting feature grade is denoted by color codes which are applied to the header section of the page documenting the respective feature. The following sections show all available color codes.

The color codes outlined above have the following meanings:

The feature is usable without restrictions.

The feature is safe to be used in production. However, the documentation may be incomplete or the sample code is missing.

The feature may be used in production and for developing new code. The interfaces are stable and future changes are not likely. However, some capabilities may be broken or do not behave as documented. The documentation is incomplete but correct.

Usage of the feature in production environments implies some risks. The feature is a work in progress and its interfaces or behavior may change in future updates. The documentation may be incomplete or wrong.

This classification scheme allows developers to decide whether a certain feature is safe to be used in a given context. For example, a certain feature may be perfectly usable for a certain use-case, even though its documentation has not been finalized. Similarly, the risk of future behavioral changes may be acceptable under specific circumstances.

Getting started or problem resolution support is provided for all features of a released product irrespective of the grade associated with a specific feature.

In order to give developers an idea about the overall Xbase++ platform, the documentation contains information on all features, regardless of whether or not the features are available in the product edition that is installed.

Some features may not be available in the installed product. Other features may be included in the installed content, but usage may be prohibited under the license terms of the current product.

The product level required to get access and redistribute a certain feature is shown in the header section of the page documenting the respective feature.

The images shown are examples of what the documentation might look like for a feature included in the Foundation and the Professional levels of Xbase++, respectively. The classification is determined by the words "Foundation" (upper image) and "Professional" (lower image) in the heading section of the respective page.

Organization of Reference Items

Symbols and Conventions

Variable Name Prefixes and Metasymbols

Typography

Feature Grades

Rights of use for Features