INFORMIX
Informix Guide to GLS Functionality
Introduction
Home Contents Index Master Index New Book

Documentation Conventions

 This section describes the conventions that this manual uses. These conventions make it easier to gather information from this and other Informix manuals.

The following conventions are covered:

Typographical Conventions

This manual uses the following standard set of conventions to introduce new terms, illustrate screen displays, describe command syntax, and so forth.
Convention Meaning

KEYWORD

All keywords appear in uppercase letters in a serif font.

italics

Within text, new terms and emphasized words appear in italics. Within syntax diagrams, values that you are to specify appear in italics.

boldface

Identifiers (names of classes, objects, constants, events, functions, program variables, forms, labels, and reports), environment variables, database names, filenames, table names, column names, icons, menu items, command names, and other similar terms appear in boldface.

monospace

Information that the product displays and information that you enter appear in a monospace typeface.

KEYSTROKE

Keys that you are to press appear in uppercase letters in a sans serif font.

This symbol indicates the end of feature-, product-, platform-, or compliance-specific information.

Tip: When you are instructed to "enter" characters or to "execute" a command, immediately press RETURN after the entry. When you are instructed to "type" the text or to "press" other keys, no RETURN is required.

Icon Conventions

Throughout the documentation, you will find text that is identified by several different types of icons. This section describes these icons.

Comment Icons

Comment icons identify warnings, important notes, or tips. This information is always displayed in italics.

Icon Description

The warning icon identifies vital instructions, cautions, or critical information.

The important icon identifies significant information about the feature or operation that is being described.

The tip icon identifies additional details or shortcuts for the functionality that is being described.

Feature and Platform Icons

Feature and platform icons identify paragraphs that contain feature-specific or platform-specific information.
Icon Description

Identifies information that is specific to an Informix Asian Language Support (ALS) database or application.

Identifies information that relates to the Native Language Support (NLS) feature.

Identifies information that is specific to the UNIX platform.

Identifies information that is specific to Windows environments: Windows NT, Windows 95, and Windows 3.1 (Win32s).

These icons can apply to a row in a table, one or more paragraphs, or an entire section. A symbol indicates the end of the feature- or platform-specific information.

Command-Line Conventions

This section defines and illustrates the format of commands that are available in Informix products. These commands have their own conventions, which might include alternative forms of a command, required and optional parts of the command, and so forth.

Each diagram displays the sequences of required and optional elements that are valid in a command. A diagram begins at the upper-left corner with a command. It ends at the upper-right corner with a vertical line. Between these points, you can trace any path that does not stop or back up. Each path describes a valid form of the command. You must supply a value for words that are in italics.

You might encounter one or more of the following elements on a command-line path.

(1 of 2)

Element Description

command

This required element is usually the product name or other short word that invokes the product or calls the compiler or preprocessor script for a compiled Informix product. It might appear alone or precede one or more options. You must spell a command exactly as shown and use lowercase letters.

variable

A word in italics represents a value that you must supply, such as a database, file, or program name. A table following the diagram explains the value.

-flag

A flag is usually an abbreviation for a function, menu, or option name or for a compiler or preprocessor argument. You must enter a flag exactly as shown, including the preceding hyphen.

.ext

A filename extension, such as .sql or .cob, might follow a variable that represents a filename. Type this extension exactly as shown, immediately after the name of the file. The extension might be optional in certain products.

( . , ; + * - / )

Punctuation and mathematical notations are literal symbols that you must enter exactly as shown.

' '

Single quotes are literal symbols that you must enter as shown.


A reference in a box represents a subdiagram. Imagine that the subdiagram is spliced into the main diagram at this point. When a page number is not specified, the subdiagram appears on the same page.

A reference to SQLR in this manual refers to the Informix Guide to SQL: Reference. Imagine that the subdiagram is spliced into the main diagram at this point.

A shaded option is the default action.

Syntax within a pair of arrows indicates a subdiagram.

The vertical line terminates the command.

A branch below the main path indicates an optional path. (Any term on the main path is required, unless a branch can circumvent it.)

A loop indicates a path that you can repeat. Punctuation along the top of the loop indicates the separator symbol for list items.

A gate (

) on a path indicates that you can only use that path the indicated number of times, even if it is part of a larger loop. Here you can specify size no more than three times within this statement segment.

How to Read a Command-Line Diagram

UNIX
Figure 1 shows a command-line diagram that uses some of the elements that are listed in the previous table.

Figure 1
Example of a Command-Line Diagram

To construct a command correctly, start at the top left with the command setenv. Then follow the diagram to the right, including the elements that you want. The elements in the diagram are case sensitive.

Windows
These platforms use a different syntax to set environment variables. They do not use the setenv command. Many Informix products on Windows environments use the SETNET32 graphical tool to set environment variables. However, the following steps are still useful to show how to follow command-line syntax.

Figure 1 diagrams the following steps:

    1. Type the word setenv.

    2. Type the word INFORMIXC.

    3. Supply either a compiler name or pathname.

    After you choose compiler or pathname, you come to the terminator. Your command is complete.

    4. Press RETURN to execute the command.

Sample-Code Conventions

 Examples of SQL code occur throughout this manual. Except where noted, the code is not specific to any single Informix application development tool. If only SQL statements are listed in the example, they are not delimited by semicolons. For instance, you might see the code in the following example:

To use this SQL code for a specific product, you must apply the syntax rules for that product. For example, if you are using the Query-language option of DB-Access, you must delimit multiple statements with semicolons. If you are using an SQL API, you must use EXEC SQL at the start of each statement and a semicolon (or other appropriate delimiter) at the end of the statement.

Tip: Ellipsis points in a code example indicate that more code would be added in a full application, but it is not necessary to show it to describe the concept being discussed.
For detailed directions on using SQL statements for a particular application development tool or SQL API, see the manual for your product.

Character-Representation Conventions

Throughout this manual, examples show how single-byte and multibyte characters appear. Because multibyte characters are usually ideographic (such as Japanese or Chinese characters), this manual does not use the actual multibyte characters. Instead, it uses ASCII characters to represent both single-byte and multibyte characters. This section provides general information about how this manual represents multibyte and single-byte characters abstractly. For a definition of multibyte and single-byte characters, see the "Glossary."

Single-Byte Characters

This manual represents single-byte characters as a series of lowercase letters. The format for representing one single-byte character abstractly is:

In this format, a stands for any single-byte character, not for the letter "a" itself.

The format for representing a string of single-byte characters is as follows:

In this format, a stands for the first character in the string, and z stands for the last character in the string. For example, if the string Ludwig consists of single-byte characters, the following format represents this 6-character string abstractly:

Tip: The letter "s" does not appear in alphabetical sequences that represent strings of single-byte characters. The manual reserves the letter "s" as a symbol that represents a single-byte white-space character. For further information, see "White Space in Strings".

Multibyte Characters

 This manual does not attempt to show the actual appearance of multibyte characters in text, examples, or diagrams. Instead, the following convention shows abstractly how multibyte characters are stored:

One to four identical uppercase letters, each followed by a different superscript number, represent one multibyte character. The superscripts show the first to the nth byte of the multibyte character, where n has values between two and four. For example, the following symbols represent a multibyte character that consists of two bytes:

The following notation represents a multibyte character that consists of four bytes (the maximum length of a multibyte character):

The following example shows a string of multibyte characters in an SQL statement:

This statement creates a database whose name consists of five multibyte characters, each of which is two bytes long. For more information on how to use multibyte characters in SQL identifiers, see "Naming Database Objects".

Single-Byte and Multibyte Characters in the Same String

If you are using a multibyte code set, a given string might be composed of both single-byte and multibyte characters. To represent these mixed strings, this manual simply combines the formats for multibyte and single-byte characters.

For example, suppose that you have a string with four characters. The first and fourth characters are single-byte characters while the second and third characters are multibyte characters that consist of two bytes each. The following format represents this string:

White Space in Strings

 White space is a series of one or more space characters. A GLS locale defines what characters are considered to be space characters. For example, both the TAB and blank might be defined as space characters in one locale, but certain combinations of the CTRL key and another character might be defined as space characters in a different locale.

The convention for representing single-byte white spaces in this manual is the letter "s." The following notation represents one single-byte white space:

In the ASCII code set, an example of a single-byte white space is the blank character (ASCII code number 32). To represent a string that consists of two ASCII blank characters, the manual uses the following notation:

The following notation represents a multibyte white-space character:

In this format s1 represents the first byte of the white-space character, while sn represents the last byte of the white-space character, where n has values between two and four. For example, the following notation represents one 4-byte white-space character:

Trailing White Spaces

 Combinations of characters and white spaces can occur in quoted strings, in CHAR columns that contain fewer characters than the defined length of the column, and in other situations. For example, if a CHAR(5) column in a single-byte code set contains a string of three characters, the string is extended with two white spaces so that its length is equal to the defined length of the column, as follows:

The following example shows the representation for a string of five characters (three characters of data and two trailing white spaces) in a multibyte code set where each of the characters and white-space characters consists of two bytes:

Sometimes a string can contain both single-byte and multibyte white-space characters. In the following example, the string is composed of these elements: three single-byte characters (abc), a single-byte white-space character (s), a multibyte white-space character (s1s2), two single-byte white-space characters (ss), and one multibyte white-space character (s1s2):



Informix Guide to GLS Functionality, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.