# `ABS` — `ATAN`

## Contents

- `ABS` — Absolute value of a floating point number
- `ACOS` — Arccosine
- `ADDR` — Address of variable
- `ADJUSTALLOC` — Adjust memory allocation
- `ALERT` — Alert dialog
- `ALLOC` — Allocates a cell on the heap
- `APP` — Defines an application
- `APPEND` — Adds a record to a data file
- `ASC` — Gets a character code from a string
- `ASIN` — Arcsine
- `AT` — Positions the text cursor
- `ATAN` — Arctangent

## `ABS` — Absolute value of a floating point number

Usage: `a=ABS(x)`

Returns the absolute value of a floating-point number that is, without any `+`/`-` sign for example `ABS(-10.099)` is `10.099`

If `x` is an integer, you won’t get an error, but the result will be converted to floating-point for example `ABS(-6)` is `6.0`. Use `IABS` to return the absolute value as a long integer.

## `ACOS` — Arccosine

Usage: `a=ACOS(x)`

Returns the arc cosine, or inverse cosine (COS-1) of `x`.

`x` must be in the range -1 to +1. The number returned will be an angle in radians. To convert the angle to degrees, use the `DEG` function.

## `ADDR` — Address of variable

Usage: `a&=ADDR(variable)`

Returns the address at which `variable` is stored in memory.

The values of different types of variables are stored in bytes starting at `ADDR(variable)`. See `PEEK` for details. The return type of this function should be a long integer, however if the 64K memory limit is set via `SETFLAGS`, `a&` is guaranteed to fit into an integer.

See `UADD`, `USUB`.

## `ADJUSTALLOC` — Adjust memory allocation

Usage: `pcelln&=ADJUSTALLOC(pcell&,off&,am&)`

Opens or closes a gap at `off&` within the allocated cell `pcell&`, returning the new cell address or zero if out of memory. `off&` is 0 for the first byte in the cell. Opens a gap if the amount `am&` is positive, and closes it if negative. An error will be raised if the cell address argument is not in the range known by the heap.

See also `SETFLAGS` if you require a 64K limit to be enforced on 32-bit target devices. If the flag is set to restrict the limit, `pcelln&` is guaranteed to fit into an integer.

See `ALLOC`. See also Dynamic memory allocation.

ARM

Cells are allocated lengths that are the smallest multiple of four greater than the size requested because the ARM processor requires a four-byte word alignment for its memory allocation. The ARM processor is used in the Psion Series 5 and other EPOC devices.

## `ALERT` — Alert dialog

Usage: any of

        r%=ALERT(m1$,m2$,b1$,b2$,b3$)
        r%=ALERT(m1$,m2$,b1$,b2$)
        r%=ALERT(m1$,m2$,b1$)
        r%=ALERT(m1$,m2$)
        r%=ALERT(m1$)

Presents an alert — a simple dialog — with the messages and keys specified, and waits for a response. `m1$` is the message to be displayed on the first line, and `m2$` on the second line. If `m2$` is not supplied or if it is a null string, the second message line is left blank.

Up to three keys may be used. `b1$`, `b2$` and `b3$` are the strings (usually words) to use over the keys. `b1$` appears over an Esc key, `b2$` over Enter, and `b3$` over Space. This means you can have Esc, or Esc and Enter, or Esc, Enter and Space keys. If no key strings are supplied, the word `CONTINUE` is used above an Esc key.

The return value, `r%`, is one of the following:

`KAlertEsc%` | 1 | The Esc key.
`KAlertEnter%` | 2 | The Enter key.
`KAlertSpace%` | 3 | The Space bar.

These constants are supplied in Const.oph.

## `ALLOC` — Allocates a cell on the heap

Usage: `pcell& = ALLOC(size&)`

Allocates a cell on the heap of the specified size, returning the pointer to the cell or zero if there is not enough memory.

See also `SETFLAGS` if you require a 64K limit to be enforced on 32-bit target devices. If the flag is set to restrict the limit, `pcelln&` is guaranteed to fit into an integer.

See `ADJUSTALLOC`, `REALLOC`, and `FREEALLOC`. See also Dynamic memory allocation.

ARM

Cells are allocated lengths that are the smallest multiple of four greater than the size requested because the ARM processor requires a four-byte word alignment for its memory allocation. The ARM processor is used in the Psion Series 5 and other EPOC devices.

## `APP` — Defines an application

Usage:

        APP caption,uid&
        ...
        ENDA

Begins definition of an OPL application. `caption` is the application’s name (or caption) in the machine’s default language. Note that although `caption` is a string, it is not enclosed in quotes.

`uid&` is the application’s UID. For distributed applications, official reserved UIDs must be used. These can be obtained by contacting Symbian Ltd (see OPL applications for details of how to do this).

All information included in the `APP` … `ENDA` structure will be used to generate a `.AIF` file which specifies the applications caption in various languages, its icons for use on the System screen and its setting of `FLAGS`.

See `CAPTION`, `ICON`, `FLAGS`.

See also OPL applications for more details of OPL applications.

## `APPEND` — Adds a record to a data file

Usage: `APPEND`

Warning: This function is deprecated and included only for compatibility with older versions of the OPL language. `INSERT`, `PUT`, and `CANCEL` should be used in preference to `APPEND` and `UPDATE`, although `APPEND` and `UPDATE` are still supported. However, note that `APPEND` can generate a lot of extra (intermediate) erased records. `COMPACT` should be used to remove them, or alternatively use `SETFLAGS` to set auto-compaction on.

Adds a new record to the end of the current data file. The record which was current is unaffected. The new record, the last in the file, becomes the current record.

The record added is made from the current values of the field variables `A.field1$`, `A.field2$`, and so on, of the current data file. If a field has not been assigned a value, zero will be assigned to it if it is a numeric field, or a null string if it is a string field.

Example:

        PROC add:
              OPEN "address",A,f1$,f2$,f3$
              PRINT "ADD NEW RECORD"
              PRINT "Enter name:",
              INPUT A.f1$
              PRINT "Enter street:",
              INPUT A.f2$
              PRINT "Enter town:",
              INPUT A.f3$
              APPEND
              CLOSE
        ENDP

To overwrite the current record with new field values, use `UPDATE`.

See Database File Handling for more details. See also `INSERT`, `MODIFY`, `PUT`, `CANCEL`, `SETFLAGS`.

## `ASC` — Gets a character code from a string

Usage: `a%=ASC(a$)`

Returns the character code of the first character of `a$`. Alternatively, use `A%=%char` to find the code for `char` - e.g. `%X` for ‘X’. If `a$` is a null string (`""`) `ASC` returns the value 0.

Example: `A%=ASC("hello")` returns 104, the code for `h`.

See also: Character codes.

## `ASIN` — Arcsine

Usage: `a=ASIN(x)`

Returns the arc sine, or inverse sine (SIN-1) of `x`.

`x` must be in the range -1 to +1. The number returned will be an angle in radians. To convert the angle to degrees, use the DEG function.

## `AT` — Positions the text cursor

Usage: `AT x%,y%`

Positions the cursor at `x%` characters across the text window and `y%` rows down. `AT 1,1` always moves to the top left corner of the window. Initially, the window is the full size of the screen, but you can change its size and position with the `SCREEN` command.

A common use of `AT` is to display strings at particular positions in the text window. For example:

        AT 5,2 :PRINT "message".

- `PRINT` statements without an `AT` display at the left edge of the window on the line below the last `PRINT` statement (unless you use `,` or `;`) and strings displayed at the top of the window eventually scroll off as more strings are displayed at the bottom of the window.
- Displayed strings always overwrite anything that is on the screen - they do not cause things below them on the screen to scroll down.

Example:

        PROC records:
              LOCAL k%
              OPEN "clients",A,name$,tel$
              DO
                    CLS
                    AT 1,7
                    PRINT "Press a key to"
                    PRINT "step to next record"
                    PRINT "or Q to quit"
                    AT 2,3 :PRINT A.name$
                    AT 2,4 :PRINT A.tel$
                    NEXT
                    IF EOF
                          AT 1,6 :PRINT "EndOfFile"
                          FIRST
                    ENDIF
                    k%=GET
              UNTIL k%=%Q OR k%=%q
              CLOSE
        ENDP

## `ATAN` — Arctangent

Usage: `a=ATAN(x)`

Returns the arc tangent, or inverse tangent (TAN-1) of x.

The number returned will be an angle in radians. To convert the angle to degrees, use the `DEG` function.