Home Page Up one Level Site Map Send us mail

Supplement for: File Access


File Access provides a method for reading, writing, creating, and deleting text files while playing a CD-i title. Additionally, files may be copied and simple string searches may be made of file contents. The files accessed by the plug-in can be in non-volatile RAM, on a PC or OS-9 floppy diskette, on a PC or OS-9 hard disk, or on a CD-i disc.

NOTE: The File Access Plug-In works only with text files.

Plug-ins required for operation:

cdi_flen - The "File Engine" plug-in. It does the actual work of the File Access Plug-in
cdi_flac - The "File Access" plug-in. It provides the method for sending commands to cdi_flen.
cdi_flcp - The "File Copy" plug-in. It allows files to be copied.
cdi_flss - The "String Search" plug-in. It allows simple string searches of a files' contents.
cdi_sgmn - The "Signal Manager" plug-in. It provides communication between the other plug-ins.

MediaMogul utilities required to prepare assets:


Assets to create before using the plug-in:

None required, but depending on the application, text files may need to be prepared. If so, text files are ASCII files and can be created with any text or most word processors.

Special preparations:

No additional required.

How the plug-in works:

· You must start up the signal manager plug-in, cdi_sgmn, first. Then start the file engine, cdi_flen. This creates a data module , cdi_file_data, in memory. This data module is used to store the names, locations, and attributes of open files. In cdi_flen you need to specify the maximum number of open files, e.g. the files open at any one time, not the total number of files to be used. There is a limit of 32 files open at one time, and there is no warning if a number larger than 32 is specified. If memory usage in your title is a concern, the maximum size of cdi_file_data is 4464 bytes.

· You send most commands to the file engine via the file access, cdi_flac, plug-in. The order of this is to open the file in the appropriate mode, perform the operation(s) on the file, and then close the file. You must specify the filename and device when you open a file. A file can only be accessed when it has been opened in the appropriate mode, e.g. you cannot write to a file opened in Read mode.

· In order to read from or write to a file, you must open the file in the correct mode first. This is done via cdi_flac. There are three modes in which a file may be opened: Read (OPEN_R) which allows a file to be read from; Write (OPEN_W) which opens a new file for writing; Append (OPEN_A) which opens an existing file for writing additional information to the end of the file. Opening a file that does not exist in Write mode creates that file. Opening an existing file in Write mode opens it with a size of 0 bytes, essentially erasing its contents. To open an existing file for writing, and retain information already present in the file, open the file in Append mode.

· Reads and Writes are done a line at a time. Each subsequent read or write of an already open file reads from/writes to the next line of the file. If you need to read from the beginning of a file that is already open, close the file and open it again in Read mode.

· Once a file has been opened, its pathname, location, and attributes are stored in the data module created by cdi_flen. Because of this, the location need not be specified again as long as the file is open. However, each file is referenced by its filename only, which means that no two files with the same name should be opened simultaneously, even if they are in different directories or on different devices.

A representation of how the file information is stored in cdi_file_data would be:

Reference Pathname Device (location) Attributes
myfile.txt myfile.txt NVR (non-volatile RAM) read, write
oldfile.txt /YELLOW/oldfile.txt CD (CD-i disc) read (file on locked media)
myfile.txt /TEXTFILES/myfile.txt OS9_FD (OS-9 diskette) read, write

NOTE: The second file named "myfile.txt" would not be read from or written to, since the first file "myfile.txt" would always be found first by cdi_flen. If the second example of this file was instead named "myfile2.txt", it would be found correctly by cdi_flen.

· Copying a file requires that 2 files be open, the original and the copy. Make sure that you have specified at least 2 files to be open in cdi_flen if you need to copy a file. Again, the files must have different names, otherwise an error is returned as cdi_flen opens the first file with the specified name in Read mode, and then tries to open in Write mode the file that already is open.

· In order to open a file, the device it is on must be in the csd. The csd is a file in non-volatile RAM that contains information about devices and other hardware descriptors used by the player. It is created by every CD-i player when the player starts up. SCSI hard drives, however, are not listed in the csd, so the csd must be edited to include the descriptor for a PC or OS-9 SCSI drive if you want to access files on these devices. The entry for a PC drive is "70:/hpc" and the entry for an OS-9 drive is "50:/h0". These can be added to the csd by opening it via the File Access plug-in in Append mode and writing the entry. The csd should then be closed before attempting to access a file on an attached SCSI device.

An shortened example of a csd from a 605T looks like this:


NOTE: The exact string to write to the csd for a PC SCSI drive is "70:|hpc:\n" and for an OS-9 drive it is "50:|h0:\n". The "|" is used instead of the "/" because the "/" may not be used as part of a string, the second ":" is used because each entry in the csd should end in a colon, and the "\n" is a carriage return, which is required for the last line of the csd.

· After every call to any of the File Access Plug-ins you should check the value of the Z variable for errors. See the File Access Plug-In manual for a complete list of errors.

· Files do not have to be at the root level of a device in order to be accessed. If a file is in a directory, the path can be included as part of the filename. Remember, the "/" character cannot be used in a string, so the "|" character should be used instead.

Example: To access a file /h0/TEXTFILES/myfile.txt the name would be entered as "TEXTFILES|myfile.txt" The rest of the path is implied by the device entered as a parameter. In this case /h0/ is implied, because OS9_HD is the device entered for a file located on drive /h0, and the second delimeter, "/" in this case, is implied as part of any device.

· Placing the file(s) to be accessed on a CD-i disc requires editing of the master script or include files. You should run script2disc and build a disc image. This disc image may be discarded. Then edit the master script, mast_s, or the include files _master0, _master1, and _master2, to include the file(s) in the disc image. Once the edits are made, master should be run to create the disc image, which now will include the text files. These can be read by file access. Remember, files on a disc cannot be written to or deleted.


In the following example, the csd is edited to include the description for a PC hard drive. A file is created on the PC drive. This file is written to, and then closed. The file is copied and the original deleted. Finally, the copy is searched for a text string.

00:00 Call_bg /h0/SUBROUT/cdi_sgmn
(signal manager is started)
00:20 Call_bg /h0/SUBROUT/cdi_flen 2 (file engine is started)
01:10 Call /h0/SUBROUT/cdi_flac OPEN_A,csd NVR
(csd is opened in append mode)
02:00 Call /h0/SUBROUT/cdi_flac WRITE,csd 70:|hpc:\n
(the descriptor for the PC SCSI drive is written to the csd)
03:00 Call /h0/SUBROUT/cdi_flac CLOSE,csd (the csd is closed)
03:00 Br_always_nr /h0/SCRIPTS/newfile.scr

00:00 Call /h0/SUBROUT/cdi_flac OPEN_W,newfile DOS_HD
(the file "newfile" is opened in Write mode on the PC hard drive.
This creates the file.)
01:00 Call /h0/SUBROUT/cdi_flac WRITE,newfile first line (write to file)
02:00 Call /h0/SUBROUT/cdi_flac WRITE,newfile second line (write to file)
03:00 Call /h0/SUBROUT/cdi_flac WRITE,newfile third line (write to file)
04:00 Call /h0/SUBROUT/cdi_flac CLOSE,newfile (the file is closed)
04:20 Br_always_nr /h0/SCRIPTS/copyfile.scr

00:00 Call /h0/SUBROUT/cdi_flcp DOS_HD,newfile DOS_hd,copyfile
(copy newfile to copyfile)
02:00 Br_always_nr /h0/SCRIPTS/killfile.scr

00:00 Call /ho/SUBROUT/cdi_flac DELETE,newfile DOS_HD (delete newfile)
01:00 Br_always_nr /h0/SCRIPTS/search.scr

00:00 Call /h0/SUBROUT/cdi_flac OPEN_R,copyfile DOS_HD
(open copyfile for reading)
01:00 Call /h0/SUBROUT/cdi_flss second copyfile
(search copyfile for "second")
02:00 Br_ifeq_nr /h0/SCRIPTS/notfound.scr Z 0
(branch to notfound.scr if string not found)
02:00 Br_ifeq_nr /h0/SCRIPTS/found.scr Z 1
(branch to found.scr if the string was found)

NOTE: Times in the above example are approximate.

Home Page Up one Level Site Map Send us mail