# `IABS` — `IOYIELD`

## Contents

- `IABS` — Absolute value of an integer expression
- `ICON` — Sets an application’s icon
- `IF`...`ENDIF` — Conditional loop
- `INCLUDE` — Includes a header file
- `INPUT` — Reads a value from the keyboard
- `INSERT` — Inserts a blank record into a database
- `INT` — Gets the integer part of a floating point value (as an integer)
- `INTF` — Gets the integer part of a floating point value (as a floating point number)
- `INTRANS` — True if the current view is in a transaction
- `IOA` — Asynchronous I/O request
- `IOC` — I/O request with guaranteed completion
- `IOCANCEL` — Cancels an outstanding IO request
- `IOCLOSE` — Closes a file
- `IOOPEN` — Creates or opens a file
- `IOREAD` — Reads from a file
- `IOSEEK` — Seeks to a position in a file opened for random access
- `IOSIGNAL` — Signals completion of asynchronous I/O function
- `IOW` — Synchronous I/O request
- `IOWAIT` — Waits for an asynchronous I/O function to complete
- `IOWAITSTAT` — Waits for an `IOC` or `IOA` to complete
- `IOWAITSTAT32` — Waits for asynchronous OPX procedure 32 bit status word to complete
- `IOWRITE` — Writes bytes in a buffer to a file
- `IOYIELD` — Ensures asynchronous functions have a chance to run

## `IABS` — Absolute value of an integer expression

Usage: `i&=IABS(x&)`

Returns the absolute value, i.e. without any sign, of the integer or long integer expression `x&`.

For example `IABS(-10)` is `10`.

See also `ABS`, which returns the absolute value as a floating-point value.

## `ICON` — Sets an application’s icon

Usage: `ICON mbm$`

Gives the name of the bitmap file `mbm$`, also known as an EPOC Picture file, to use as the icon for an OPL Application.

If the `ICON` command is not used inside the `APP`…`ENDA` structure, then a default icon is used, but the rest of the information in the `APP`..`ENDA` construct is still used to specify the other features of the OPL application.

`mbm$` is a multi-bitmap file which can contain up to three bitmap/mask pairs - the sizes are 24, 32 and 48 squares. These different sizes are used for the different zoom levels in the system screen. The sizes are read from the `MBM` and the most suitable size is zoomed if the exact sizes required are not provided or if some are missing.

In fact, you can use `ICON` more than once within the `APP`...`ENDA` construct. The translator only insists that all icons are paired with a mask of the same size in the final `ICON` list. This allows you to use pairs of `MBM`s containing just one bitmap as produced by the Sketch application. For example, you could specify them individually:

        APP ...
        ICON "icon24.mbm"
        ICON "mask24.mbm"
        ICON "icon32.mbm"
        ICON "mask32.mbm"
        ICON "icon48.mbm"
        ICON "mask48.mbm"
        ENDA

or with pairs in each `MBM`:

        APP ...
        ICON "iconMask24"
        ICON "iconMask32"
        ICON "iconMask48"
        ENDA

or with all the bitmaps as just one `MBM`, as would normally be the case if prepared on the PC using `bmconv` and `aiftool` (see ../../adk/OtherTools-ref/Tool_Ref_Bmconv.html and ).

This command can only be used between `APP` and `ENDA`.

See OPL applications for more details of OPL applications.

## `IF`...`ENDIF` — Conditional loop

Usage:

        IF condition1
              ...
        ELSEIF condition2
              ...
        ELSE
              ...
        ENDIF

Does either

- the statements following the `IF` condition

or

- the statements following one of the `ELSEIF` conditions (there may be as many `ELSEIF` statements as you like none at all if you want)

or

- the statements following `ELSE` (or, if there is no `ELSE`, nothing at all). There may be either one `ELSE` statement or none.

After the `ENDIF` statement, the lines following `ENDIF` carry on as normal.

`IF`, `ELSEIF`s, `ELSE` and `ENDIF` must be in that order.

Every `IF` must be matched with a closing `ENDIF`.

You can also have an `IF`...`ENDIF` structure within another, for example:

        IF condition1
              ...
        ELSE
              ...
              IF condition2
                    ....
              ENDIF
              ...
        ENDIF

`condition` is an expression returning a logical value for example `a<b`. If the expression returns logical true (non-zero) then the statements following are executed. If the expression returns logical false (zero) then those statements are ignored. For more details about logical expressions, see Operators and logical expressions.

## `INCLUDE` — Includes a header file

Usage: `INCLUDE file$`

Includes a file, `file$`, which may contain `CONST` definitions, prototypes for OPX procedures and prototypes for module procedures. The included file may not include module procedures themselves. Procedure and OPX procedure prototypes allow the translator to check parameters and coerce numeric parameters (that are not passed by reference) to the required type.

Including a file is logically identical to replacing the `INCLUDE` statement with the file’s contents.

The filename of the header may or may not include a path. If it does include a path, then OPL will only scan the specified folder for the file. However, the default path for `INLCUDE` is `\System\Opl\`, so when `INCLUDE` is called without specifying a path, OPL looks for the file firstly in the current folder and then in `\System\Opl\` in all drives from `Y:` to `A:` and then in `Z:`, excluding any remote drives.

See `CONST`, `EXTERNAL`. See also Using OPL Extensions (OPXs).

## `INPUT` — Reads a value from the keyboard

Usage: `INPUT variable`
or `INPUT log.field`

Waits for a value to be entered at the keyboard, and then assigns the value entered to a variable or data file field.

You can edit the value as you type it in. All the usual editing keys are available: the arrow keys move along the line, Esc clears the line and so on.

If inappropriate input is entered, for example a string when the input was to be assigned to an integer variable, a `?` is displayed and you can try again. However, if you used `TRAP INPUT`, control passes on to the next line of the procedure, with the appropriate error condition being set and the value of the variable remaining unchanged.

`INPUT` is usually used in conjunction with a `PRINT` statement:

        PROC exch:
              LOCAL pds,rate
              DO
                    PRINT "Pounds Sterling?",
                    INPUT pds
                    PRINT "Rate (DM)?",
                    INPUT rate
                    PRINT "=",pds*rate,"DM"
                    GET
              UNTIL 0
        ENDP

Note the commas at the end of the `PRINT` statements, used so that the cursor waiting for input appears on the same line as the messages.

#### TRAP INPUT

If a bad value is entered (for example `"abc"` for `a%`) in response to a `TRAP INPUT`, the `?` is not displayed, but the `ERR` function can be called to return the value of the error which has occurred. If the Esc key is pressed while no text is on the input line, the ‘Escape key pressed’ error (number -114) will be returned by `ERR` (provided that the `INPUT` has been trapped). You can use this feature to enable someone to press the Esc key to escape from inputting a value.

See also `EDIT`. This works like `INPUT`, except that it displays a string to be edited and then assigned to a variable or field. It can only be used with strings.

## `INSERT` — Inserts a blank record into a database

Usage: `INSERT`

Inserts a new, blank record into the current view of a database. The fields can then be assigned to before using `PUT` or `CANCEL`.

## `INT` — Gets the integer part of a floating point value (as an integer)

Usage: `i&=INT(x)`

Returns the integer (in other words the whole number) part of the floating-point expression `x`. The number is returned as a long integer.

Positive numbers are rounded down, and negative numbers are rounded up for example `INT(-5.9)` returns `-5` and `INT(2.9)` returns `2`. If you want to round a number to the nearest integer, add 0.5 to it (or subtract 0.5 if it is negative) before you use `INT`.

See also `INTF`.

## `INTF` — Gets the integer part of a floating point value (as a floating point number)

Usage: `i=INTF(x)`

Used in the same way as the INT function, but the value returned is a floating-point number. For example, `INTF(1234567890123.4)` returns `1234567890123.0`

You may also need this when an integer calculation may exceed integer range.

See also `INT`.

## `INTRANS` — True if the current view is in a transaction

Usage: `i&=INTRANS`

Finds out whether the current view is in a transaction. Returns -1 if it is in a transaction or 0 if it is not.

See also `BEGINTRANS`.

## `IOA` — Asynchronous I/O request

Usage: `r%=IOA(h%,f%,var status%,var a1,var a2)`

This has the same form as `IOC`, but it returns an error value of the request is not completed successfully. `IOC` should be used in preference to `IOA`.

See also: I/O functions and commands.

## `IOC` — I/O request with guaranteed completion

Usage: `IOC(h%,f%,var status%,var a1,var a2)`

Make an I/O request with guaranteed completion. The device driver opened with handle `h%` performs the asynchronous I/O function `f%` with two further arguments, `a1` and `a2`. The argument `status%` is set by the device driver. If an error occurs while making a request, `status%` is set to an appropriate values, but `IOC` always returns zero, not an error value. .An `IOWAIT` or `IOWAITSTAT` must be performed for each `IOC`. `IOC` should be used in preference to `IOA`.

See also: I/O functions and commands.

## `IOCANCEL` — Cancels an outstanding IO request

Usage: `r%=IOCANCEL(h%)`

Cancels any outstanding asynchronous I/O request (`IOC` or `IOA`). Note, however, that the request will still complete, so the signal must be consumed using `IOWAITSTAT`.

See also: I/O functions and commands.

## `IOCLOSE` — Closes a file

Usage: `r%=IOCLOSE(h%)`

Closes a file with the handle `h%`.

See also: I/O functions and commands.

## `IOOPEN` — Creates or opens a file

Usage: `r%=IOOPEN(var h%,name$,mode%)`

Creates or opens a file called `name$`. Defines `h%` for use by other I/O functions. `mode%` specifies how to open the file. For unique file creation, use `IOOPEN(var h%,addr%,mode%)`

See also: I/O functions and commands.

## `IOREAD` — Reads from a file

Usage: `r%=IOREAD(h%,addr&,maxLen%)`

Reads from the file with the handle `h%`. `address%` is the address of a buffer large enough to hold a maximum of `maxLen%` bytes. The value returned to `r%` is the actual number of bytes read or, if negative, is an error value.

See also: I/O functions and commands.

## `IOSEEK` — Seeks to a position in a file opened for random access

Usage: `r%=IOSEEK(h%,mode%,var off&)`

Seeks to a position in a file that has been opened for random access. `mode%` specifies how the offset argument `off&` is to be used. Values for `mode%` may be found in the I/O functions and commands. `off&` may be positive to move forwards or negative to move backwards. `IOSEEK` sets the variable `off&` to the absolute position set.

Note the following example when you use `#`:

        ret%=IOSEEK(h%,mode%,#ptrOff&)

passing the long integer `ptrOff&`.

See also 32-bit addressing, I/O functions and commands.

## `IOSIGNAL` — Signals completion of asynchronous I/O function

Usage: `IOSIGNAL`

Signals an asynchronous I/O function’s completion.

See also: I/O functions and commands.

## `IOW` — Synchronous I/O request

Usage: `r%=IOW(h%,func%,var a1,var a2)`

The device driver opened with handle `h%` performs the synchronous I/O function `func%` with the two further arguments.

See also: I/O functions and commands.

## `IOWAIT` — Waits for an asynchronous I/O function to complete

Usage: `IOWAIT`

Waits for an asynchronous I/O function to signal completion.

See also: I/O functions and commands.

## `IOWAITSTAT` — Waits for an `IOC` or `IOA` to complete

Usage: `IOWAITSTAT var stat%`

Waits for an asynchronous function, called with `IOC` or `IOA`, to complete.

See also: I/O functions and commands.

## `IOWAITSTAT32` — Waits for asynchronous OPX procedure 32 bit status word to complete

Usage: `IOWAITSTAT32 var stat&`

Takes a 32-bit status word. `IOWAITSTAT32` should be called only when you need to wait for completion of a request made using a 32-bit status word when calling an asynchronous OPX procedure.

N.B.: The initial value of a 32-bit status word while it is still pending (i.e. waiting to complete) is &80000001 (`KStatusPending32&` in Const.oph. For a 16-bit status word the ‘pending value’ is -46 (`KErrFilePending%`).

See also: I/O functions and commands.

## `IOWRITE` — Writes bytes in a buffer to a file

Usage: `r%=IOWRITE(h%,addr&,length%)`

Writes `length%` bytes in a buffer at `address%` to the file with the handle `h%`.

See also: I/O functions and commands.

## `IOYIELD` — Ensures asynchronous functions have a chance to run

Usage: `IOYIELD`

Ensures that any asynchronous handler set up with `IOC` or `IOA` is given a chance to run. `IOYIELD` must always be called before polling status words, i.e. before reading a 16-bit status word if `IOWAIT` or `IOWAITSTAT` have not been used first.

See also: I/O functions and commands.