# `SysRam1.opx` — Additional OPL functionality

## Contents

- Overview

- Compatibility

- `DbFind&:`
- `DbFindField&:`
- `GetThreadIdFromCaption&:`
- `ExternalPower&:`
- `LCNearestLanguageFile$:`
- `LCLanguage&:`
- `OsVersionMajor&:`
- `OsVersionMinor&:`
- `OsVersionBuild&:`
- `RomVersionMajor&:`
- `RomVersionMinor&:`
- `RomVersionBuild&:`
- `GetFileSize&:`
- `DTDatNameFull$:`
- `DTMonthNameFull$:`
- `DTIsLeapYear&:`
- `LCDateSeparator$:`
- `LCTimeSeparator$:`
- `LCAmPmSpaceBetween&:`

## Overview

This OPX is supplied with the EPOC OPL SDK, and does not exist in current EPOC ROMs. To use this OPX, you must include the header file `SysRam1.oxh` and distribute `SysRam1.opx` with your program.

`SysRam1.opx` contains utility functions for working with locale preference settings, OS and ROM version numbers, captions and dates; it also contains error-free versions of the `FIND` and `FINDFIELD` keywords.

### Compatibility

ER5 WINS OPXs are not useable on the ER3 EPOC Emulator, and ER3 WINS OPXs will not work on the ER5 Emulator. However, ER5 MARM OPXs will work on ER3 EPOC devices, and ER3 MARM OPXs will work under ER5.

## `DbFind&:`

Usage: `f& = DbFind&:(string$)`

Note: this procedure replaces `FIND` as `FIND` contains bugs when searching for large strings (or small strings when searching many fields).

Searches the current view for fields matching `a$`. The search starts from the current record, so use `NEXT` to progress to subsequent records. `DbFind&:` makes the next record containing `string$` the current record and returns the number of the record found. Capitals and lower-case letters match.

You can use the wildcards:

? | matches any single character
* | matches any group of characters

To find a record with a field containing `Dr` and either `BROWN` or `BRAUN`, use:

        F& = DbFind&:("*DR*BR??N*")

`DbFind&:("BROWN")` will find only those records with a field consisting solely of the string "`BROWN`".

You can only search string fields.

`DbFind&:` returns the position of the found record in the current view.

See also `DbFindField&:`.

## `DbFindField&:`

Usage: `f& = DbFindField&:(string$,start&,num&,flags&)`

Note: this procedure replaces `FINDFIELD` as `FINDFIELD` contains bugs when searching for large strings (or small strings when searching many fields).

Like `DbFind&:`, finds a string, makes the record with this string the current record, and returns the number of this record.

`string$` is the string for which to search: the search will be carried out in `num&` fields in each record, starting at the field with number `start&` (1 is the number of the first field). `start&` and `num&` may refer to string fields only and other types will be ignored. The `flags&` argument specifies the type of search as explained below. If you want to search in all fields, use 1 for `start&` and for `num&` use the number of fields you used in the OPEN/CREATE command.

`flags&` can be built by using or more of the following values:

`KFindBackwards%` | 0 | Backwards from current record.
`KFindForwards%` | 1 | Forwards from current record.
`` | 2 | Add to above to mean: Search starts at the appropriate end of the file.
`KFindBackwardsFromEnd%` | 2 | Backwards from end of file (`2+KFindBackwards%`).
`KFindForwardsFromStart%` | 3 | Backwards from start of file (`2+KFindForwards%`).
`KFindCaseDependent%` | 16 | Search is case-dependent. This means that the record will exactly match the search string in case as well as characters

These constants are supplied in Const.oph.

Add `KFindCaseDependent%` to the value of `flags&` given above to make the search case-dependent, where case-dependent means that the record will exactly match the search string in case as well as characters. Otherwise the search will be case-independent which means that upper case and lower case characters will match.

`DbFindField&:` returns the position of the found record in the database.

See also Database manipulation.

## `GetThreadIdFromCaption&:`

Usage: `t& = GetThreadIdFromCaption&:(Caption$,previous&)`

Finds the thread Id of an application by its caption as specified in the APP...ENDA construct. This allows OPL apps to properly handle help files. See `GetThreadIdfromOpenDoc` of `System.opx` for more information.

## `ExternalPower&:`

Usage: `p& = ExternalPower&:`

Returns -1 if external power (mains) is present or 0 if not.

## `LCNearestLanguageFile$:`

Usage: `LCNearestLanguageFile$:(file$)`

The last two characters of the filename supplied are replaced with the language code if such a file exists, otherwise `file$` is left unmodified.

## `LCLanguage&:`

Usage: `c& = LCLanguage&:`

Returns the machines language code. Constants for the language codes are described in `CAPTION`.

## `OsVersionMajor&:`

Usage: `ov& = OsVersionMajor&:`

Returns the major version number for the Operating System.

## `OsVersionMinor&:`

Usage: `ov& = OsVersionMinor&:`

Returns the minor version number for the Operating System.

## `OsVersionBuild&:`

Usage: `ov& = OsVersionBuild&:`

Returns the build number of the Operating System.

## `RomVersionMajor&:`

Usage: `rv& = RomVersionMajor&:`

Returns the major version number for the ROM.

## `RomVersionMinor&:`

Usage: `rv& = RomVersionMinor&:`

Returns the minor version number for the ROM.

## `RomVersionBuild&:`

Usage: `rv& = RomVersionBuild&:`

Returns the build number of the ROM.

## `GetFileSize&:`

Usage: `s& = GetFileSize&:(file$)`

Returns the size in bytes of the supplied file, `file$`.

## `DTDatNameFull$:`

Usage: `d$ = DTDayNameFull$:(Day&)`

Returns a day name in full. The `Day&` argument is the day number, as for `DAYNAME$`.

## `DTMonthNameFull$:`

Usage: `m$ = DTMonthNameFull$:(Month&)`

Returns a month name in full. The `Month&` argument is the day number, as for `MONTHNAME$`.

## `DTIsLeapYear&:`

Usage: `leapy& = DTIsLeapYear&:(year&)`

Returns -1 if `year&` is a leap year or 0 if it isn’t.

## `LCDateSeparator$:`

Usage: `dsep$ = LCDateSeparator$:(index&)`

Returns the local date separator. `index&` can be between 0 and 3 inclusive and corresponds to the position of the separator, as follows; 0 day 1 month 2 year 3.

## `LCTimeSeparator$:`

Usage: `tsep$ = LCTimeSeparator$:(index&)`

Returns the local time separator. `index&` can be between 0 and 3 inclusive and corresponds to the position of the separator, as follows; 0 hour 1 minute 2 second 3.

## `LCAmPmSpaceBetween&:`

Usage: `sp& = LCAmPmSpaceBetween&:`

Returns -1 if there should be a space between the time string and AM/PM in the current locale, or 0 if there should not.