# `CANCEL` — `CURSOR`

## Contents

- `CANCEL` — Cancels a database transaction
- `CAPTION` — Sets an application’s caption
- `CHR$` — Converts a charcode to a string
- `CLEARFLAGS` — Clears system flags
- `CLOSE` — Closes the current database view
- `CLS` — Clears the text window
- `CMD$` — Command line arguments
- `COMMITTRANS` — Commits the current database transaction
- `COMPACT` — Compacts a database file
- `CONTINUE` — Jump to loop test condition
- `CONST` — Declares a constant
- `COPY` — Copies files
- `COS` — Cosine
- `COUNT` — Counts records in the current data file
- `CREATE` — Creates a table in a database
- `CURSOR` — Sets the text cursor

## `CANCEL` — Cancels a database transaction

Usage: `CANCEL`

Marks the end of a database’s `INSERT` or `MODIFY` phase and discards the changes made during that phase.

## `CAPTION` — Sets an application’s caption

Usage: `CAPTION caption$,languageCode%`

Specifies an application’s public name (or caption) for a particular language, which will appear below its icon on the Extras bar and in the list of ‘Programs’ in the ‘New File’ dialog (assuming the setting of `FLAGS` allows these) when the language is that used by the machine. `CAPTION` may only be used inside an `APP`...`ENDA` construct.

The language code specifies for which language variant the caption should be used, so that the caption need not be changed when used on a different language machine. If used, for whatever language, `CAPTION` causes the default caption given in the `APP` declaration to be discarded. Therefore `CAPTION` statements must be supplied for every language in which the application is liable to be used, including the language of the machine on which the application is originally developed.

The values of the language code should be one of the following:

`KLangEnglish%` | 1 | `KLangPortuguese%` | 13
`KLangFrench%` | 2 | `KLangTurkish%` | 14
`KLangGerman%` | 3 | `KLangIcelandic%` | 15
`KLangSpanish%` | 4 | `KLangRussian%` | 16
`KLangItalian%` | 5 | `KLangHungarian%` | 17
`KLangSwedish%` | 6 | `KLangDutch%` | 18
`KLangDanish%` | 7 | `KLangBelgianFlemish%` | 19
`KLangNorwegian%` | 8 | `KLangAustralian%` | 20
`KLangFinnish%` | 9 | `KLangBelgianFrench%` | 21
`KLangAmerican%` | 10 | `KLangAustrian%` | 22
`KLangSwissFrench%` | 11 | `KLangNewZealand%` | 23
`KLangSwissGerman%` | 12 | `KLangInternationalFrench%` | 24

These constants are supplied in Const.oph.

The maximum length of `caption$` is 255 characters. However, you should bear in mind that a caption longer than around 8 characters will not fit neatly below the application’s icon on the Extras bar.

See `APP`. See also OPL applications.

## `CHR$` — Converts a charcode to a string

Usage: `a$=CHR$(x%)`

Returns the character with character code `x%`.

You can use it to display characters not easily available from the keyboard. For example, the instruction `PRINT CHR$(133)` displays an ellipsis (...).

The full character set for EPOC is in Character codes.

## `CLEARFLAGS` — Clears system flags

Usage: `CLEARFLAGS flags&`

Clears the flags given in `flags&` if they have previously been set by `SETFLAGS`, returning to the default.

See `SETFLAGS`.

## `CLOSE` — Closes the current database view

Usage: `CLOSE`

Closes the current view on a database. If there are no other views open on the database then the database itself will be closed. See `SETFLAGS` for details of how to set auto-compaction on closing files.

If you’ve used `ERASE` to remove some records, `CLOSE` recovers the memory used by the deleted records, provided it is held either in the internal memory, or on a memory disk.

## `CLS` — Clears the text window

Usage: `CLS`

Clears the contents of the text window.

The cursor then goes to the beginning of the top line. If you have used `CURSOR OFF` the cursor is still positioned there, but is not displayed.

## `CMD$` — Command line arguments

Usage: `c$=CMD$(a%)`

Returns the command-line arguments passed when starting a program. Null strings may be returned. `a%` is one of the constant values `KCmdAppName%`, `KCmdUsedFile%`, or `KCmdLetter%` defined in `Const.oph`. `CMD$(KCmdUsedFile%)` and `CMD$(KCmdLetter%)` are only defined for OPL applications.

The value returned by `CMD$` and its meaning depends on the value of `a%`:

``KCmdAppName%`` | 1 | Returns the full path name used to start the running program.
``KCmdUsedFile%`` | 2 | Returns the full path name of the file to be used by an OPL application. For example, if `CMD$(3)=R` (see below), a default filename, including path, is passed in `CMD$(2)`.
``KCmdLetter%`` | 3 | Returns one of the values below, and indicates the kind of command which was used to start the application.

If an application passes `KCmdLetter%` to `CMD$`, the return value is one of:

`KCmdLetterCreate$` | "`C`" | Application was started as a result of a `Create new file` command in the shell.
`KCmdLetterOpen$` | "`O`" | Application was started by opening a file belonging to it in the system screen.
`KCmdLetterRun$` | "`R`" | Application was run directly from the Extras bar, by opening the application itself in the system screen, or from the Program editor.

The constants are defined in Const.oph.

See also `GETCMD$` and OPL applications.

## `COMMITTRANS` — Commits the current database transaction

Usage: `COMMITTRANS`

Commits the transaction on the current view.

See also `BEGINTRANS`, `ROLLBACK`, `INTRANS`.

## `COMPACT` — Compacts a database file

Usage: `COMPACT file$`

Compacts the database `file$`, rewriting the file in place. All views on the database and the hence the file itself should be closed before calling this command. This should not be done too often since it uses considerable processor power.

Compaction can also be done automatically on closing a file by setting the appropriate flag using `SETFLAGS`.

## `CONTINUE` — Jump to loop test condition

Usage: `CONTINUE`

Makes a program immediately go to the `UNTIL`... line of a `DO`...`UNTIL` loop or the `WHILE`... line of a `WHILE`...`ENDWH` loop i.e. to the test condition.

Example:

See also `BREAK`.

## `CONST` — Declares a constant

Usage: `CONST KConstantName=constantValue`

Declares constants which are treated as literals, not stored as data. The declarations must be made outside any procedure, usually at the beginning of the module. `KConstantName` has the normal type-specification indicators (`%`, `&`, `$` or nothing for floating-point numbers). `CONST` values have global scope, and are not overridden by locals or globals with the same name: in fact the translator will not allow the declaration of locals or globals of the same name. By convention, all constants should be named with a leading `K` to distinguish them from variables.

It should be noted that it is not possible to define constants with values smaller than -32768 (for integers) and -214748648 (for long integers) in decimals, but hexadecimal notation may be used instead (i.e. values of `$8000` and `&80000000` respectively).

## `COPY` — Copies files

Usage: `COPY src$,dest$`

Copies the file `src$`, which may be of any type, to the file `dest$`. Any existing file with the name `dest$` is deleted. You can copy across devices. You can also use wildcards if you wish to copy more than one file at a time.

If `src$` contains wildcards, `dest$` may specify either a filename similarly containing wildcards or just the device and directory to which the files are to be copied under their original names.

Example: To copy all the files from internal memory (in `\opl`) to `d:\me\`:

        COPY "c:\opl\*","d:\me\"

(Remember the final backslash on the directory name.)

There are more details of full file specifications in More on file specification.

## `COS` — Cosine

Usage: `c=COS(x)`

Returns the cosine of `x`, where `x` is an angle in radians.

To convert from degrees to radians, use the `RAD` function.

## `COUNT` — Counts records in the current data file

Usage: `c%=COUNT`

Returns the number of records in the current data file. This number will be 0 if the file is empty.

If you try to count the number of records in a view while updating the view an ‘Incompatible update mode’ error will be raised (This will occur between assignment and `APPEND` / `UPDATE` or between `MODIFY` / `INSERT` and `PUT`).

## `CREATE` — Creates a table in a database

Usage: `CREATE tableSpec$,log,f1,f2`,...

Creates a table in a database. The database is also created if necessary. Immediately after calling `CREATE`, the file and view (or table) is open and ready for access.

`tableSpec$` contains the database filename and optionally a table name and the field names to be created within that table. For example:

        CREATE "clients FIELDS name(40), tel TO phone", D, n$, t$

The filename is clients. The table to be created within the file is phone. The comma-separated list, between the keywords `FIELDS` and `TO`, specifies the field names whose types are specified by the field handles (i.e. `n$`, `t$`).

The name field has a length of 40 bytes, as specified within the brackets that follow it. The tel field has the default length of 255 bytes. This mechanism is necessary for creating some indexes. See `dBase.opx` — Database handling for more details on index creation.

The filename may be a full file specification of up to 255 characters. A field name may be up to a maximum of 64 characters long. Text fields have a default length of 255 bytes.

`log` specifies the logical file name `A` to `Z`. This is used as an abbreviation for the file name when you use other data file commands such as `USE`.

See also Database File Handling.

## `CURSOR` — Sets the text cursor

Usage: any of

        CURSOR ON
        CURSOR OFF
        CURSOR id%
        CURSOR id%,asc%,w%,h%
        CURSOR id%,asc%,w%,h%,type%

`CURSOR ON` switches the text cursor on at the current cursor position. Initially, no cursor is displayed.

You can switch on a graphics cursor in a window by following `CURSOR` with the ID of the window. This replaces any text cursor. At the same time, you can also specify the cursor’s shape, and its position relative to the baseline of text.

`asc%` is the ascent — the number of pixels (-128 to 127) by which the top of the cursor should be above the baseline of the current font. `h%` and `w%` (both from 0 to 255) are the cursor’s height and width.

If you do not specify them, the following default values are used:

`asc%` | Current font’s ascent.
`h%` | Current font’s height.
`w%` | `KCursorTypeNotFlashing%`

If `type%` is given, it can have these effects:

`KCursorTypeNotFlashing%` | 2 | Not flashing.
`KCursorTypeGrey%` | 4 | Grey.

These constants are supplied in Const.oph.

You can add these values together to combine effects — if `type%` is 6 a grey non-flashing cursor is drawn. Using `1` for `type%` just displays a default graphics cursor, as though no type had been specified.

An error is raised if `id%` specifies a bitmap rather than a window.

`CURSOR OFF` switches off any cursor.