File handling

Introduction

In the teletext script, there is a "user I/O file" which may be opened, written to, and then closed. You can only have the one file open at a time, however there is nothing to stop you from creating multiple files, one after the other. There is no concept of 'file handle', as the write commands write to the open file.

When we talk of frame and page, there are some complications with this terminology, hence:

• Page - a teletext page, i.e. p102 which may consist of multiple frames.
• Frame - a single teletext frame. This can often be used interchangeably for 'page' in cases where there are no subframes, and most of the time we would use the terminology 'frame' as the script interpreter works one frame at a time.
• Subframe - specifically refers to an individual frame in a page that consists of many frames. All subframes are frames, but not all frames are subframes. For example the news on BBC World (and possibly BBC analogue services) presents each item of news in a single frame. That frame is a page, but it isn't considered a subframe. On the other hand, Sky News and EuroNews teletext services present their news articles on two or three pages. The group (i.e. p107) is the page, which consists of two or three frames, which are subframes.

Opening and closing files

Creating a new file is performed using the filewrite() command. It will open the output file, which is empty, and set the output pointer to the beginning of the file. If the file specified already exists, it will be erased and a new version created.

filewrite("#TEMP#\tempfile.txt")

Appending to an existing file is performed using the fileupdate() command. It will open the output file, which may already contain data, and set the output pointer to the end of the file so anything you now add will be written after previous content.

fileupdate("#PAGES#\currencylog.txt")

Closing the output file is the same in either case, you use the fileclose() command.

fileclose()

Please note that there is a difference between path specifiers on RISC OS, where the following would be quite valid:

filewrite("<Teletext$Pages>.mypage")

filewrite("#PAGES#\mypage.ttx")

As just mentioned, while Windows file 'types' are self-contained in the file extension (i.e. ".txt", etc), RISC OS requires a metadata setting. This should be performed once the output file has been closed, using the filetype() command.

filetype("<Teletext$Pages>.mypage", &FAF)

General notes:

• Under RISC OS, untyped files are given type &FFD (datafile). Attempts to run the file will usually result in an error message saying that there is no program capable of opening that sort of file; so be sure to use an appropriate filetype.
• Under RISC OS, there are few controls over the type of file that may be created and what these files may be called; it is valid to attempt to create something like <OvationPro$Dir>.OvnPro, and I'm sure you can guess the result of that. It is wise to check over scripts from unknown sources to be sure that there is nothing malicious.
• Under Windows, there are stricter controls. You are blocked from creating files with extensions such as .exe and .dll, you cannot create files within the Windows directory, etc etc. [there is special handling for if #TEMP# is within Windows]
• Under Windows, the filetype() command works but accepts a strict few types, and its use is strongly discouraged as it is better to apply a correct file extension in the beginning.
• Under Windows, there is no oscall(); getting a file to load itself is performed using execfile() which takes no parameter, it will use the name of the last user file accessed. You cannot run arbitrary files or perform arbitrary commands under Windows.
• Opening a file with no path specifier may leave the file in an undefined location. Under Windows, this is likely to be the WinTTX application directory; under RISC OS it is likely to be the root of the default drive (your CSD, which is totally different to where the application 'lives').
• In either case, attempting to write to a file with no write permission, no write access, a read-only media, or insufficient user privileges to write is all classed as an "undefined" error and how the interpreter handles this situation is not explicitly specified.
• Creating a file and outputting multiple teletext format frames to this file will create an invalid file which will not be able to be loaded properly.

Tidying up teletext frames

The removal of unwanted mosaic codes is performed using the smartclear() command. This is because only the creation of teletext files is able to preserve the mosaic characters. They cannot be represented in text.
You can smartclear() individual lines, or you can under Windows pass the line number -1 to smartclear the entire frame.

The removal of blank lines is more useful. With the exception of teletext files, the output methods permit the complete omission of lines marked as 'blank', so you can only output the content you want and the rest will be discarded. This is acheived with the omitline() command.
Note that you must omit the header (line 1) for any other omissions to take effect. If the header is present, omitted lines will be retained, and this might have some odd side effects under Windows - namely lots of "OMITTHIS" markers!

You can also read characters from the frame using set <var> to char(<x>, <y>) and write characters to the frame using setchar().

When a frame has been modified, you must push it back to the cache, as attempts to write the frame to file will cause the frame to be loaded from the cache, and hence the older cached version would overwrite the one you just amended. Don't worry if that sounds confusing, just be sure to call storeframe() after any alteration to the frame's content.

Writing to files - different options

To output entire frames (with optional omission of unwanted lines), you can use appendframe() or appendframes(); the difference being that the former will write the frame specified and the latter will write all the integral subframes of the page specified.

To write individual bytes to the file, you would use filewritebyte(). This is perhaps most useful for outputting newlines.

You can write string literals (that is a fixed string that you specify in the script) using filewritestring(). You cannot copy strings from teletext frames, this can be achieved using a roundabout method (described below).

Floating point values (either literal or from a variable) may be written using filewritefloat(), and variables (either integer or float) may be written using filewritevar().
It may seem as if when we are speaking of a float variable, that filewritefloat() and filewritevar() may do much the same thing. This is mostly correct, however there are slight differences in the control of output style.

Writing to files - different formats

OvationPro DDL output hints

filewrite("<filename>")  ; "filename.dpd" under Windows
filewriteovnhead()       ; must be the FIRST thing you output

; output the frames, ie:
;  appendframe(x, 3)
; in a loop, or whatever

filewriteovntail()       ; must be the LAST thing you output
fileclose()

filetype("<path>", &B25) ; only under RISC OS

The filewriteovnhead command outputs (with small modifications depending on platform):

// minimal OvationPro DDL script created by Teletext (1.49)
 
COL_00={colour "Ttx Black" {rgb 0x0 0x0 0x0}}
COL_01={colour "Ttx Red" {rgb 0x10000 0x0 0x0}}
COL_02={colour "Ttx Green" {rgb 0x0 0x10000 0x0}}
COL_03={colour "Ttx Yellow" {rgb 0x10000 0x10000 0x0}}
COL_04={colour "Ttx Blue" {rgb 0x0 0x0 0x10000}}
COL_05={colour "Ttx Magenta" {rgb 0x10000 0x0 0x10000}}
COL_06={colour "Ttx Cyan" {rgb 0x0 0x10000 0x10000}}
COL_07={colour "Ttx White" {rgb 0x10000 0x10000 0x10000}}
 
STORY_001={story

You can replace this with your own header if you wish, however you must define the colours as above, because the output frames will expect them to be present.

The append[given]frame[s] commands, with type 3 output, write the frames exactly as for the OvationPro DDL output from the Save dialogue. Please refer to any saved file for an example.

The filewriteovntail command outputs:

{endoftext}
}

This tells OvationPro that the DDL file has finished. The minimum you can get away with is a single '}' character, but you might as well call this function and end properly...

A suggestion is to 'centre' the output. For this, you should:

filewrite("<filename>")
filewriteovnhead()
filewritestring("{align 1}")

; output follows...

The alignment types are:

left	0
centre	1
right	2
justified	3

You might like to output headings before each group of pages. The example below shows outputting a heading, and then outputting the pages 101 to 110.

; NEWS
filewritestring("{newpara}{textsize 16000}{bold 1}{underline 1}")
filewritebyte(34)
filewritestring("Headlines")
filewritebyte(34)
filewritestring("{bold 0}{underline 0}{textsize 12000}")
filewritebyte(34)
filewritestring(" (from CNN)")
filewritebyte(34)
filewritebyte(10)   ; or you can output <13><10> under Windows
filewritestring("{textsize}{bold}{underline}{newpara}")

set A to 101
.writenews
  appendframe(A, 3)
  A++
  if (A [ 110) go("writenews")

You have various commands at your disposal. A command with no parameter will restore the option to the default for the current style (which will probably be Trinity.Medium, 12pt, left aligned, no bold/italic/underline).

{align #}	Sets the alignment to that specified (0-left, 1-centre, 2-right, 3-justified).
{bold #}	Use {bold 1} to switch bold on, and {bold 0} to switch it off.
{italic #}	Use {italic 1} to switch italics on, and {italic 0} to switch it off.
{newpara}	If you want a line break, use {newpara}.
{textsize #}	The text size is 'pointsize * 1000', so 12000 is 12pt, and 24000 is 24pt...
{underline #}	Use {underline 1} to switch underline on, {underline 0} for off...

All text must be enclosed in "quotes", including spaces between items. The following is valid:

{bold 1} "this text is in bold" {bold 0}

Even the following would work:

{bold 1}
"this "
"text "
"is "
"in "
"bold"
{bold 0}

This, however, won't work:

{bold 1} this text is in bold {bold 0}

If you need to include the characters '{', '\', or '"' in the DDL, you will need to escape them, as shown:

For:	Use:
{	\{
\	\\
"	\"

There are all sorts of nifty things possible, such as tab-aligned results from a calculation, but these things require a deeper knowledge of the OvationPro DDL script, and that is outside of the scope of this document.

Remember, you can always 'fake' what you'd like to see in OvationPro, then save the document in DDL format to an editor such as !Edit (Notepad in Windows). This will allow you to see how something was achieved, and thus allow you to use it in your own generated output.

A useful suggestion is to save a number of 'desired' frames to a directory, and then load them in using the cache_loaddirectory() command. This will save you waiting for each frame fetch while testing and tweaking your teletext script to produce exactly the DDL script that you want.
(this command has not been implemented under Windows, however you can use the cache_loadfile() command to load files individually to acheive the same result.

And for HTML?

filewrite("<filename>")  ; "filename.html" under Windows
filewritehtmlhead()      ; must be the FIRST thing you output

; output the frames, ie:
;  appendframe(x, 4)
; in a loop, or whatever

filewritehtmltail()      ; must be the LAST thing you output
fileclose()

filetype("<path>", &FAF) ; only under RISC OS

All of the remaining comments are much the same as already given for the OvationPro output. If you know HTML mark-up, you can patch in a lot of custom HTML.

Copying strings from a teletext page

filewritestring("                  Sky  = ")
set A to 30
.reportloop
  set B to char(A, 17)
  filewritebyte(B)
  A++
  if (A [ 40) go("reportloop")
filewritebyte(13)
filewritebyte(10)