# `SCI$` — `SUM`

## Contents

- `SCI$` — Converts a number to scientific format
- `SCREEN` — Changes the size of the text window
- `SCREENINFO` — Gets information about the text screen
- `SECOND` — Gets the current time in seconds
- `SECSTODATE` — Converts seconds to date
- `SETDOC` — Sets a file to be a document
- `SETFLAGS` — Sets an application’s flags
- `SETPATH` — Sets the path for file access
- `SIN` — Sine
- `SPACE` — Gets space available on the current file’s device
- `SQR` — Square root
- `STD` — Standard deviation
- `STOP` — Stops the running program
- `STYLE` — Sets the text window character style
- `SUM` — Sums a list of numeric items

## `SCI$` — Converts a number to scientific format

Usage: `s$=SCI$(x,y%,z%)`

Returns a string representation of `x` in scientific format, to `y%` decimal places and up to `z%` characters wide.

Examples:

        SCI$(123456,2,8)="1.23E+05"
        SCI$(1,2,8)="1.00E+00"
        SCI$(1234567,1,-8)=" 1.2E+06"

If the number does not fit in the width specified then the returned string contains asterisks.

If `z%` is negative then the string is right-justified.

See also `FIX$`, `GEN$`, `NUM$`.

## `SCREEN` — Changes the size of the text window

Usage: `SCREEN width%,height%
`or `SCREEN width%,height%,x%,y%`

Changes the size of the window in which text is displayed. `x%,y%` specify the character position of the top left corner; if they are not given, the text window is centred in the screen.

An OPL program can initially display text to the whole screen.

See `SCREENINFO`.

## `SCREENINFO` — Gets information about the text screen

Usage: `SCREENINFO var info%()`

Gets information on the text screen (as used by `PRINT`, `SCREEN` etc.)

This keyword allows you to mix text and graphics. It is required because while the default window is the same size as the physical screen, the text screen is slightly smaller and is centred in the default window. The few pixels gaps around the text screen, referred to as the left and top margins, depend on the font in use.

On return, `info%()` contains the information. `info%()` must have at least 10 elements. The information is returned at the following indices in `info%()`.

`KSinfoALeft%` | 1 | Left margin in pixels.
`KSinfoATop%` | 2 | Top margin in pixels.
`KSinfoAScrW%` | 3 | Text screen width in character units.
`KSinfoAScrH%` | 4 | Text screen height in character units.
`KSinfoAReserved1%` | 5 | Reserved (window server id for default window).
`KSinfoAFont%` | 6 | Unused (font ID for older systems).
`KSinfoAPixW%` | 7 | Pixel width of text window character cell.
`KSinfoAPixH%` | 8 | Pixel height of text window character cell.
`KSinfoAReserved2%` | 9 | Least significant 16 bits of the font ID.
`KSinfoAReserved3%` | 10 | Most significant 16 bits of the font ID.

These constants are supplied in Const.oph.

The font ID is a 32-bit integer under EPOC, and therefore would not fit into a single element of `info%()`. Hence, the least significant 16 bits of the font ID are returned to `info%(9)` and the most significant 16 bits to `info%(10)`.

Initially `SCREENINFO` returns the values for the initial text screen. Subsequently any keyword which changes the size of the text screen font, such as `FONT` or `SCREEN`, will change some of these values and `SCREENINFO` should therefore be called again.

See also `FONT`, `SCREEN`.

## `SECOND` — Gets the current time in seconds

Usage: `s%=SECOND`

Returns the current time in seconds from the system clock (0 to 59).

E.g. at 6:00:33 `SECOND` returns `33`.

## `SECSTODATE` — Converts seconds to date

Usage: `SECSTODATE s&,var yr%,var mo%,var dy%,var hr%,var mn%, var sc%,var yrday%`

Sets the variables passed by reference to the date corresponding to `s&`, the number of seconds since 00:00 on 1/1/1970. `yrday%` is set to the day in the year (1-366).

`s&` is an unsigned long integer. To use values greater than +2147483647, subtract 4294967296 from the value.

See also `DATETOSECS`, `HOUR`, `MINUTE`, `SECOND`, `dDATE`, `DAYS`.

## `SETDOC` — Sets a file to be a document

Usage: `SETDOC file$`

Sets the file `file$` to be a document. This command should be called immediately before the creation of `file$` if it is to be recognised as a document. `SETDOC` may be used with the commands `CREATE`, `gSAVEBIT` and `IOOPEN`.

The string passed to `SETDOC` must be identical to the name passed to the following `CREATE` or `gSAVEBIT` otherwise a non-document file will be created. Example of document creation:

        SETDOC "myfile"
        CREATE "myfile",a,a$,b$

`SETDOC` should also be called after successfully opening a document to allow the System screen to display the correct document name in its task list.

`SETDOC` also adds the current document name to the `Recent files` list on the System screen. Selecting a document from the `Recent files` list will cause the EPOC to launch the document just as if it had been started from the system screen with a tap-while-selected. Applications which already use SETDOC require no code changes or re-translations to use this new feature.

In case of failure in creating or opening the required file, you should take the following action:

- Creating — try to re-open the last file and if this fails display an appropriate error dialog and exit. On reopening, call `SETDOC` back to the original file so the Task list is correct.
- Opening — as for creating, but calling `SETDOC` again is not strictly required.

Database documents, created using `CREATE`, and multi-bitmap documents, created using `gSAVEBIT`, will automatically contain your application UID in the file header. For binary and text file documents created using `IOOPEN` and `LOPEN`, it is the programmer’s responsibility to save the appropriate header in the file. This is a fairly straight-forward process and the following suggests one way of finding out what the header should be:

1. Create a database or bitmap document in a test run of you application using `SETDOC` as shown above
2. Use a hex editor or hex dump program to find the 1st 16 bytes, or run the program below which reads the four long integer UIDs from the test document.
3. Write these four long integers to the start of the file you create using `IOOPEN`.

        INCLUDE "Const.oph"
        DECLARE EXTERNAL
        EXTERNAL readUids:(file$)

        PROC main:
              LOCAL f$(255)
              WHILE 1
                    dINIT "Show UIDs in document header"
                    dPOSITION 1,0
                    dFILE f$,"Document,Folder,Drive",0
                    IF DIALOG=0
                          RETURN
                    ENDIF
                    readUids:(f$)
              ENDWH
        ENDP

        PROC readUids:(f$)
              LOCAL ret%,h%
              LOCAL uid&(4),i%
              ret%=IOOPEN(h%,f$,KIoOpenModeOpen% OR KIoOpenFormatBinary%)
              IF ret%>=0
                    ret%=IOREAD(h%,ADDR(uid&()),16)
                    PRINT "Reading ";f$
                    IF ret%=16
                          WHILE i%<4
                                i%=i%+1
                                PRINT "  Uid"+num$(i%,1)+"=",hex$(uid&(i%))
                          ENDWH
                    ELSE
                          PRINT "  Error reading: ";
                          IF ret%<0
                                PRINT err$(ret%)
                          ELSE
                                PRINT "Read ";ret%;" bytes only ";
                                PRINT "(4 long integers required)"
                          ENDIF
                    ENDIF
                    IOCLOSE(h%)
              ELSE
                    PRINT "Error opening: ";ERR$(ret%)
              ENDIF
        ENDP

Creating text file documents using `IOOPEN` or `LOPEN` has two special requirements:

- You will need to save the required header as the first text record. This will insert the standard text file line delimiters CR LF (hex 0D 0A) at the end of the record.
- The specific 16 bytes required for your application may itself however contain CR LF. Since you should know when this is the case, you will need to read records until you have reached byte 16 in the document. This is clearly not a desirable state of affairs but is inescapable given that text files were not designed to have headers. It is recommended that you request a new UID for your application if it contains CR LF.

See also `GETDOC$` and OPL applications.

## `SETFLAGS` — Sets an application’s flags

Usage: `SETFLAGS flags&`

Sets flags to produce various effects when running programs. Use `CLEARFLAGS` to clear any flags which have been set. `flags&` is formed by adding one or more of the following values.

`KRestrictTo64K&` | 1 | restricts the memory available to your application to 64K, emulating an older 16-bit machine. This setting should be used at the beginning of your program only, if required. Changing this setting repeatedly will have unpredictable effects.
`KAutoCompact&` | 2 | enables auto-compaction on closing databases. This can be slow, but it is advisable to use this setting when lots of changes have been made to a database.
`KTwoDigitExponent&` | 4 | enables raising of overflow errors when floating-point values are greater than or equal to 1.0E+100 in magnitude, instead or allowing 3-digit exponents (for backwards compatibility)
`KSendSwitchOnMessage&` | $10000 | enables `GETEVENT`, `GETEVENT32` and `GETEVENT32A` to return the event code $403 to `ev&(1)` when the machine switches on

These constants are supplied in Const.oph.

By default these flags are cleared.

See Advanced Topics and Database File Handling.

See also `GETEVENT32`, `CLEARFLAGS`.

## `SETPATH` — Sets the path for file access

Usage: `SETPATH name$`

Sets the current path for file access for example,

        SETPATH "C:\Documents\".

`SETPATH` needs the final backslash to be passed otherwise it ignores everything beyond the last backslash. `LOADM` continues to use the path of the initial program, but all other file access will use the new path.

## `SIN` — Sine

Usage: `s=SIN(angle)`

Returns the sine of `angle`, an angle expressed in radians.

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

## `SPACE` — Gets space available on the current file’s device

Usage: `s&=SPACE`

Returns the number of free bytes on the device on which the current (open) data file is held.

## `SQR` — Square root

Usage: `s=SQR(x)`

Returns the square root of `x`.

## `STD` — Standard deviation

Usage: `s=STD(list)`
or `s=STD(array(),element)`

Returns the standard deviation of a list of numeric items.

The list can be either:

- A list of variables, values and expressions, separated by commas

or

- The elements of a floating-point array.

When operating on an array, the first argument must be the array name followed by `()`. The second argument, separated from the first by a comma, is the number of array elements you wish to operate on for example `m=STD(arr(),3)` would return the standard deviation of elements `arr(1)`, `arr(2)` and `arr(3)`.

This function gives the sample standard deviation, using the formula:

To convert to population standard deviation, multiply the result by `SQR((n-1)/n).`

## `STOP` — Stops the running program

Usage: `STOP`

Ends the running program.

Note that `STOP` may not be used during an OPX callback and will raise the error ‘`STOP used in callback`’ if it is. See Callbacks from OPX procedures.

## `STYLE` — Sets the text window character style

Usage: `STYLE style%`

Sets the text window character style. `style%` can be 2 for underlined, or 4 for inverse.

See The text and graphics windows for more details.

## `SUM` — Sums a list of numeric items

Usage: `s=SUM(list)
`or `s=SUM(array(),element)`

Returns the sum of a list of numeric items.

The list can be either:

- A list of variables, values and expressions, separated by commas

or

- The elements of a floating-point array.

When operating on an array, the first argument must be the array name followed by `()`. The second argument, separated from the first by a comma, is the number of array elements you wish to operate on for example `m=SUM(arr(),3)` would return the sum of elements `arr(1)`, `arr(2)` and `arr(3)`.