Home Page Up one Level Site Map Send us mail
Overview:
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:
NONE
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 bycdi_flen. If the second example of this file was instead named "myfile2.txt", it would be found correctly bycdi_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:
4:/nvr:
1:/cd:
20:/term:
20:/t1:
20:/t2:
40:/d0:
40:/d0h:
40:/d0hd:
60:/pcd0:
60:/pcd0h:
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.txtthe 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, becauseOS9_HDis 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.
Example:
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.
init.scr (signal manager is
started)
00:00 Call_bg /h0/SUBROUT/cdi_sgmn
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
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
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
killfile.scr
00:00 Call /ho/SUBROUT/cdi_flac DELETE,newfile DOS_HD (delete
newfile)
01:00 Br_always_nr /h0/SCRIPTS/search.scr
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