Easily manage TI-99 floppy and hard disk images
Also see www.ninerpedia.org for more technical details.
The objective of this tool is to simplify working with disk images for TI-99 systems. Disk images are, simply speaking, floppy disks or hard disks that have been saved as a file. These images are used in some emulators like MAME instead of using a real floppy drive or hard drive, mainly because the PC hardware does not directly support the device operations coming from the emulated TI. Instead, the emulator only works with a disk image, and the emulator "believes" to see a real disk.
Disk images can be created with most emulators, also with MAME, but apart from creating them, only little support for changing the image contents is available. Certainly, images change while we work with the emulator, because the emulated system performs write operations, and so we can copy files on the image, delete them, and also read them. But multi-system emulators like MAME simply cannot implement all the handling for every single system.
TIImageTool is a program which allows you to create and modify TI disk images in an intuitive way, including common file management features that we know from PC systems. Disk images can be created with different sizes, files can be copied from one disk to another, files can be imported and exported, and file systems can be checked for errors.
In the following sections I will go through each feature of the program and explain its usage.
For using TIImageTool you only need a Java Runtime Environment version 6 and higher. If you are reading this text from the help menu you obviously already have a working Java environment on your computer. Remember to install a Java Runtime on each system where you intend to use TIImageTool.
One specific feature of TIImageTool is the Serial bridge. This allows you to transfer files to and from another computer system via XModem file exchange. The other computer system may be a real TI or Geneve, so you can easily exchange your files between the PC and the TI. In order to use the serial bridge you need the serial interface support for Java. TIImageTool uses the RXTX serial library, so you have to install this library if you want to use the bridge. If you do not install it, you can use all features of TIImageTool without limitations except for the serial connection which will then be unavailable.
If you want to work with Compact Flash cards that are used with the CF7 expansion system (or the nanoPEB), you also need a program to read directly from a storage device. This program is called dd, and it is already part of every Linux distribution or MacOS, but not of a normal Windows installation. You have to download the DD for Windows program; it is simply one EXE file that you should store at a location that you easily remember. You can set the path to DD.EXE in the preferences.
TIImageTool is started by double-clicking the JAR file (if the JAR file type is associated to the Java Runtime Environment). Alternatively, you can start the program on the command line
If you provide the optional imageFile argument, TIImageTool will directly open the image on startup. In case you simply want to use the serial bridge feature without all the other things, you can pass the BRIDGE argument in the command line like this:
Please see below (serial bridge) for more details.
Image files that can be used with TIImageTool may have one of the following formats:
All these formats can be used directly, including reading and writing operations. Files and directories may be moved or copied between images of different formats. The different formats are only visible to some lower layer of TIImageTool and are not visible to the user. There are no constraints beyond those that are specific for the device (e.g. you cannot create more than three directories on a floppy disk).
Usage of TIImageTool is subject to the GPLv3 license. The terms of the license can be found inside the distribution package file that contained this JAR file. The package also contains the source code as required by the GPL license. The GPL license text can also be downloaded from www.gnu.org. In essence, you can redistribute or change the software to your needs, but only if you put your modifications under the same GPLv3 license. In doubt, contact the above E-Mail address, also for dual licensing considerations.
Although everyone does his or her best, to err remains human. Every new release of TIImageTool has added a set of new features, everything certainly tested several times in different ways. But it is just impossible to ensure that everything works as expected.
So if you find something weird going on with TIImageTool, here are some suggestions:
In any case, if you need help please contact me at ti99@mizapf.de. The more detailed your problem description is, the easier it is for me to track the source of the issue. Tell me exactly what you did when the problem occured, or even better, try to reproduce the problem. Just do not try to silently get along with it.
Suggestions are always welcome. Also tell me if some program behavior is obviously correct as described but feels surprising, awkward, or not useful for you. I cannot promise to consider all of your inputs but if your point convinces me there is a good chance you'll get in the next version.
TIImageTool has been created by myself without rigorous testing and without verification against any formal tests or test suites. The program may contain errors which may prevent it from functioning in a promised or expected way. Even worse, as the core features of the program comprise file management, any malfunction may render image files useless after using this tool. As I am using this tool by myself, you can feel reassured that I do not plan to purposefully break the images, as my own ones would also be lost.
Although care has been taken to ensure a safe working with images, you should always keep backup copies of your media. As long as you only read files with this tool your images remain unchanged.
My motivation for writing TIImageTool emerged when I managed to copy all of my old TI floppy disks to PC image files in order to use them in MESS (today MAME). At that point I was in need of a tool which allowed me to quickly check whether all images have been correctly copied. MAME offers a tool named imgtool, but it is a text-only command line tool, and its main use case seems the creation of new images. After I added the track dump format to the TI-99 emulation in MAME, I should have added that support to imgtool as well. imgtool is a good tool if you are working with many different emulations in MAME, but it cannot cover all features that one would like to have for one specific platform.
I started with TIImageTool in 2010, first as a pure command line tool. Later I added a graphical user interface. During the following years I added more and more features, like multi-disk support and cut-copy-paste capabilities, hard disk operations, and archive support.
TIImageTool is a single-person project, done in my free time. I wrote it completely in Java using the jEdit editor as my favorite programming environment (small, fast, useful). The background image was created by using GIMP, based on a screenshot of the Master Title Screen.
As the most typical use case, you open one or more image files by the open function in the file menu and view, move, copy, or save files stored inside those images.
When an image is loaded, its contents are displayed in an own tab in a format similar to the directory displays known from the TI or Geneve. You can open more than one image, and each image gets its own tab. You can also open an image more than once for a comfortable file transfer on the same image. File operations may involve a single tab, but also another tab, when you copy or move files from one image to another. You can open an image more than once, hence getting multiple tabs for the same image.
Tabs may be detached from the main window, which means they are shown as separate windows. When you close the detached windows, they again become tabs of the main window, unless you close the main window, which shuts down all open windows at once. Using different windows makes it easy to copy or move files, using the drag-and-drop feature. In general, we call a directory listing of an image a view. Using this terminology we can say that views can appear as tabs of the main window, or as separate windows.
Within the directory content display you can open files by double-clicking the left mouse button over the entry. TIImageTool will choose a suitable display format (text for DIS/VAR 80 files, program listing for BASIC). In order to step into a subdirectory, double-click its name in the display; to get back, double-click the parent directory entry ("..").
All file operations require that you select one or more files. Selection is done in the usual way by moving the mouse pointer over an entry and by left-clicking on it (marking it). If you want to do single file operations you do not need to mark the file first; you can immediately double-click it or click the right mouse button to let the context menu show up.
Selection of multiple files or directories is done by left-clicking while pressing the Shift or Ctrl key on the keyboard. The Shift key allows you to select a range (starting at the last selected entry) while Ctrl is used for separate selections.
Available operations depend on the selected entries. For instance, if you select multiple text files you can open each one of them in one go. If you select a BASIC file and a text file together, however, there are less options because you cannot list a text file. The program determines which options may be reasonable to use for the current selection.
According to the available operations, menu items become selectable or become deactivated. For instance, the close menu option is only available if an image has been opened.
Many operations are available via the context menu. This menu is shown when you right-click a directory entry (right mouse button) or when you right-click on a free space on the directory tab. All this is done in a way which should be quite familiar for people using modern operating systems like Linux, MacOS, or Windows.
All operations are performed immediately on the image. There is no undo feature in TIImageTool yet. One exception is the sector editor where all changes are kept in memory until they are explicitly copied to disk.
With the Drag-and-Drop support (DnD) you can easily move or copy files between images, between directories, or even between an image and the PC file system and vice versa. The DnD support is based on the DnD implementation in Java Swing. It implements all common gestures, but has some few limitations that you should be aware of.
In most cases, DnD is simply done by clicking on a file, holding the mouse button while moving the pointer to a target area, and then releasing the button.
Moving means that after the operation, the file is added to the target image (where you released the mouse button), and it is removed from the image from where you dragged the file away. Press and hold the Shift key while moving the file to the destination.
Copying is what you may want to do in almost the same number of times. You can specify that the DnD gesture means copying by pressing and holding the Ctrl button on the keyboard when you drop the file. In this case, the file will not be removed from its origin.
If you do not press Shift or Ctrl, the program may pop up a small dialog window to ask whether you intend to move or copy the files or directories. This feature can be enabled or disabled in the Preferences. On MacOS the Drag and Drop support of Java seems to have some issues here; obviously the Shift and Ctrl keys are not checked during the drag, so there will always be a dialog window, even when you press Shift or Ctrl. In that case you may choose to disable this dialog completely; when no key is pressed, moving will be assumed automatically.
You can copy or move single files, but also a set of files from a single view. For this purpose you must mark the files as already described above (left-clicking, together with Shift or Ctrl keys) and then drag them to the target view.
You can also copy directories; they behave in the same way as your files. One exception though, you cannot drag a directory into another directory on a floppy disk, since the floppy disk file system does not support nested directories.
Finally, what happens when you pull your file out of TIImageTool? - This will be handled as an export operation, and also here, you can select multiple files or directories and export them in one go. The exported files will appear as TIFILES files in the PC file system.
The opposite direction means importing, and you can achieve it using DnD by dragging a file from the PC file system into TIImageTool. If the file to be imported is a TIFILES file, all file metadata are retrieved and automatically set for the newly imported file. If the file is a plain binary file or a text file, you will be asked for the missing information. Maybe you should just try it before I try to explain it with a lot of words.
One limitation of the export feature is that you can only copy files and directories from the image file to the external file system; moving is not possible even though your file explorer will offer you the option to move. This is a limitation of the Java DnD support.
You find more details about import and export below.
The context menu pops up when you click the right mouse button over an entry of the directory. The set of active selections depends on the selection: For instance, when you click on a BASIC file, the option to List BASIC becomes active.
You can also click in the free space below the last file; this will open a context menu for the volume itself, which contains items to create new files or directories, or to paste copied files into this directory.
Floppy disk images represent real floppy disks and contain files just as their real counterparts. Floppy images are stored in a specific format. MAME and TIImageTool support two formats known as the Sector Dump Format and the Track Dump Format; other names are v9t9 and pc99 format, according to the name of the emulators which first used them.
With the introduction of the HFDC controller, the floppy file system was enhanced by directories, but we can only have 3 directories at root level. Also, directories cannot be nested.
TIImageTool does not allow for creating disk images from a real floppy disk at this time. This requires a low-level access to the floppy controller on the PC board. You can, however, transfer files using XModem.
Disk images can be created with or without a file system within TIImageTool.
Allows you to create new floppy disk images. You can decide between pre-formatted and blank image files.
Floppy image files may be created as sector images (v9t9), track images (pc99), or HFE images (Lotharek).
You have to choose a file name for the new image. If you create a sector dump format image (SDF), the file suffix "dsk" is appended (unless you provided it already). Track dump format files get a "dtk" suffix; HFE files get a "hfe" suffix.
Formatted images are automatically opened after creation.
The most often used format is 360 KiB (double-sided, double density, 40 tracks). While high and ultra density disks are supported by the HFDC DSR, the real HFDC card cannot reliably deal with the higher data rates. You may find descriptions on the Web how to upgrade the hardware to work with these formats.
The Sector Dump Format is recommended for common use.
This feature allows you to open an image and display its contents in a new tab in the program window. As stated in the formats section, floppy disk images in SDF and TDF format are supported. Also, hard disk images in RAW and CHD format may be used. It is not required to extract the CHD contents before using in TIImageTool, and modifications to the image are properly written into the CHD file.
Unlike prior releases of TIImageTool, you can open an image more than once. Any change you commit to one of the copies is reflected in all others immediately.
The "Open recent" feature considerably speeds up your work when you usually use a limited set of different images.
In the Open recent file menu item you can find the most recent 10 image file names in a list.
You can close the currently selected image in several ways.
This option closes the currently selected view (or all views). Remember that changes to the image have already been performed when you operated on the image, hence closing is not necessary to commit previous changes. You can also close tabs using the close button on the tab (and I bet you'll use that one).
Hard disks images can be used in MAME just like floppy disk images, but they are usually much bigger due to their higher storage capacity.
MAME uses a special container for hard disk images called CHD (Compressed Hunks of Data). TIImageTool allows for working with plain contents as well as with these CHD containers. You can find all kinds of operations like creating, extracting, or modifying the CHD container within the menu functions.
Also, two file systems are supported: the HFDC and the SCSI file system. The difference between both is that the SCSI file system does not contain information about cylinders, heads, and sectors per track, because SCSI drives provide a linear block addressing.
Raw images are simply sector dump images as found with the floppy disks; they consist of a sequence of sector contents, starting with sector 0 and going up to the last sector. Raw images do not contain information about the drive parameters (how may cylinders, heads, and sectors per track are used) except for the information in sector 0 after the hard disk has been properly formatted.
MAME cannot handle raw images because it must be able to determine the drive parameters from unformatted drives as well. These parameters are available in the CHD format.
When you attach your TI or Geneve SCSI hard disk to a SCSI adapter in a PC, you can read the raw data and produce a raw image, even though the PC does not know anything about the TI file systems. In Linux you can use the dd command:
dd if=/dev/sdX of=imagefile.raw bs=4096
You must, of course, use the appropriate device name (not sdX) which is assigned to that drive. In Linux you can use this "raw" device (e.g. sda, sdb, ...) when you want to access the device outside of any disk partitioning. The bs parameter declares the block size in bytes, which may be set to 256 as the real sector size, but using a higher value speeds up the copy process (multiple sectors will be read in one go).
You can read more about working with external devices in the section Compact Flash handling.
CHD means Compressed Hunks of Data which implies one of its original uses: to allow to pack contents of mass storage media in a comparably small container. CHD is not only intended for hard disk images, but also for CD-ROMs, tapes, and others. The CHD container not only allows for compressing the contents, but also for checking their integrity with CRC and SHA1 hash values.
For working hard disks, neither compression nor hash values can be used, because their contents are changing over time; only if a hard disk contains a fixed content these properties are useful. Apart from that, the CHD container adds important information about the drive geometry (cylinders, heads, sectors per track).
CHD has evolved along many versions; the current version is 5. It introduced a very useful feature: The size of the image can be minimized even without compressing. All tracks that are completely filled with 0 are not stored. There is a map at the beginning of the container, and when the system looks up the pointer to a desired track and gets a 0, it automatically creates an empty track image filled with zeros.
You can also extract the contents of a CHD container into a raw image; you will need this when you want to write contents back to your real TI/Geneve hard drive. Vice versa, you can import raw contents and create a new CHD container. On this occasion, you can specify whether you want unallocated space to be filled with zeros. As said above, this may greatly reduce the size of your image.
When you create a blank hard disk with MAME tools or with TIImageTool without formatting, you must format it inside the emulation (e.g. with the Myarc Disk Manager). However, after formatting the CHD container will have grown to the maximum size, so the CHD format may not utilize its space-saving feature. The reason is that the Disk Manager writes test patterns on the hard disk which the CHD does not know about, so it assumes that these patterns are user data. This can be "fixed" by TIImageTool which can convert this test pattern to zeros if the respective sectors on the hard disks are not allocated for files.
There are two groups of parameters for hard disk usage: the geometry, and technical parameters.
Geometry
SCSI drives do not expose these geometric data to the outside world, other than MFM drives which were used with the HFDC controller. SCSI drives only define a number of sectors and care for locating them inside their own control logic. Accordingly, we have a variation of the hard disk file system on the TI/Geneve which we call SCSI file system; it only differs in the first sector where the geometry data and technical parameters are left blank.
Advanced options
All these technical parameters may be safely left with their defaults. The only thing that you have to consider is that the size of the hard disk matches the declared parameters in the file system (in sector 0). You cannot use hard disks beyond the size of 248 MiB because of the size of the allocation table in the file system which has a size of 31 sectors.
Allows you to create new hard disk images. You have to define the geometry of the disk and you can decide between pre-formatted and blank image files.
Note that when you let TIImageTool format the hard disk image, the CHD container can be minimized in size, as the free space is filled with zeros. Thus, the formatted image is much smaller if you use this format option, compared to the fully expanded size which you will find after formatting with Myarc Disk Manager within the emulation.
You can use this function to upgrade your old CHD image from 4 to 5. You can also downgrade the container, although this is only recommended when you use it with an old MAME version.
Convert to version: Specify the new CHD version. The default is 5. If you downgrade (from 5 to 4) you will get a warning notice.
You can always cancel the operation before any change takes place.
If you leave the version as is, no operation will be performed. If you intend to optimize the size of the v5 container you should extract and re-import the contents again.
Extracting is pretty simple, as the target format (the sector contents) does not need any parameters. Note that CHD containers may be much smaller than the size they represent. The extracted content will expand to the full size. Make sure you have enough space on your file system.
Extraction will not be done on the currently open image, but you have to choose an image file from your file system.
Importing requires some information that is not contained in the raw contents. This information (the metadata) inform MAME about the geometry of the drive even when it is not formatted yet. As above, you do not operate on the currently open images.
The new CHD container is stored on the PC drive, but it is not automatically opened. You can open it as usual.
The CHD container may be much smaller than you expected. CHD containers do not store tracks which are filled with zeros. However, if you format the drive within the emulation, test patterns will make the CHD expand to its full size.
When you import raw data into a new CHD, TIImageTool fetches the geometry values from sector 0. If the raw image has a SCSI file system, we need to guess proper geometry values. This should not cause any problems, as there are no checks for known geometries. However, keep in mind that you cannot use SCSI images in MAME at this time (version 0.179).
You can change the file system from SCSI to HFDC and back. You will lose the geometry and technical parameters when you convert it to SCSI, and you have to define them when you convert to HFDC.
Changing the file system is possible with raw images, but not with CHD images. The reason is that when you change the parameters, the CHD information may become inconsistent. You have two ways to handle this:
Convert to HFDC
The volume information block (VIB) of a hard disk image differs between HFDC and SCSI systems: For the HFDC, the VIB contains cylinder/head/sector information (the disk geometry); SCSI file systems use a linear block addressing and therefore do not define a geometry. Converting to HFDC means that you have to supply the geometry data by yourself.
The suggestions are a guess from the program which would result in a hard disk of the size of the raw data.
TIImageTool tries to guess reasonable values for the drive geometry from the size of the image. SCSI drives, however, usually reserve a set of sectors for replacing defect sectors, so the number of sectors is less than should be expected from calculating the number by multiplying cylinders, heads, and sectors per track. We assume that we have 32 sectors per track and round up to the next multiple of 512 sectors. This allows us to cleanly divide the total sector number into the geometry values. If you know different values you can change them manually.
This function also checks for invalid MaxAU values. These invalid values are caused by a bug of a formatter in earlier GeneveOS versions. When found, the program will replace all of these values by the correct maximum value.
Converting to HFDC is required only if you want to use a SCSI image with the HFDC. For current MAME versions, only the HFDC controller is emulated. Later MAME versions may include a SCSI emulation so that this conversion may become obsolete.
Convert to SCSI
This is the inverse process to the conversion to HFDC. Here the geometry data are discarded. This may be necessary when you want to write an image back to a SCSI drive and continue to use it by a real SCSI controller (ASCSI or WHTech) attached to your TI or Geneve.
The conversion completes silently, and you will notice the effect when you see that the heading contains the line Directory of SCS1.
Compact Flash cards offer a high storage capacity in a small casing, at least compared to conventional hard disk drives and floppy disks. Nowadays, CF cards are getting rarer because SD cards have become superior in capacity, performance, and handling.
CF cards are nevertheless interesting for TI users, since there is a peripheral device that has gained much popularity, the nanoPEB. It makes use of a CF card to emulate a floppy drive (or even several of them) by defining a set of volumes that can be mounted as desired and which appears as a floppy disk for the TI system.
CF cards come in various sizes - from 128 MiB, to 512 MiB, 1 or several GiB. However, only in rare cases the CF cards provide the amount of memory printed on their casing. This is because a certain portion of the memory is retained for replacing defect sectors. This has some ugly consequences. If we have 256 MiB image file, it is not certain whether it can be written on a 256 MiB card. This also means that we may fail to copy a 256 MiB card to another one of the (seemingly) same size.
For this reason, the typical approach for creating new images is not recommended here. For instance, if we create a 256 MiB image to be later written on a CF card, we may find out that it won't fit. Instead, we set up a different way:
Linux does not allow a normal user to directly access the CF card device. In order to get the required privileges, Linux systems must run the dd command as root, and this can be achieved by a special command before. In a shell this command is known as sudo, but we need the corresponding command for the graphical desktop:
MacOS offers a similar concept by the command osascript (thanks to Henrik Wedekind for donating these lines to TIImageTool). After copying the CF contents to the local filesystem, we have to change the ownership of the file, as it still belongs to root. That is, a chown command is executed at last.
In Windows, no privilege escalation is required, so there is nothing like kdesu, gksu, osascript, or chown that you have to deal with.
The paths for all of these commands can be set in the Preferences.
If everything worked correctly, you should have got a file with the complete contents of the CF card. Note that we did not yet talk about the CF7 format - the contents of the CF card are plainly copied, so they may have any format or just none. If this image represents a CF7 card, you can now open this file with the usual open operation. The same is true for a HFDC or SCSI backup. If the contents are not recognized, you have to format one or more CF7 volumes to make use of them.
After working on the file, you should write it back on the CF card so that the card can be used in the nanoPEB. Writing is done again with the dd command, so be sure you entered the correct drive letter of your CF card. Double-check the drive letter! If you accidentally use a drive letter that is assigned to one of your hard disk drives, you will erase its contents and possibly destroy your PC installation.
Although CF cards usually offer far too much space to be used for a TI file system, we can make use of them as cheap and handy backup media. Maybe you also have a way to connect a CF card to your TI system by some expansion card.
In this situation, you just need to copy the CF contents to an image file. For example, your CF card is accessible as drive e: in Windows (your situation may be different) or as a device /dev/sdc in Linux, and the target image file should be cfcopy.raw in your PC file system. After reading, you can open the cfcopy.raw file in TIImageTool with open and perform all desired operations.
When you are done with editing, you just need to write the image file (here cfcopy.raw) back to the CF card.
CF7-formatted CF cards consist of a sequence of volumes, each representing a virtual floppy disk with 400 KiB size (1600 sectors). The nanoPEB allows the user to mount one volume per virtual disk drive, where the volumes are enumerated from 1 to a maximum number, determined by the size of the card. That is, volume 1 occupies the first 400 KiB, volume 2 occupies the next 400 KiB, and so on until the space is exhausted.
Volumes must be formatted before they can be used, similar to the other media like floppy disks and hard disks. It is not necessary to format all volumes on the card, however. Since all volumes are 400 KiB in size, there is no reason why we would have to format all preceding volumes to be able to open the next one.
There is one exception. For TIImageTool to be able to determine the format, volume 1 must be formatted. If not, you cannot open the CF7 image; this can be easily fixed by formatting the first volume.
Volumes may be stored as separate dsk files, and as such they share their format with the sector dumps of floppy disks, with the exception that they have 1600 sectors. Apart from that, they just behave like a floppy disk image, but you cannot create directories on them.
Separate volumes are not really needed when you work with TIImageTool: You can always open a volume inside a CF7 card without having to extract it to a file. However, the nanoPEB device provides two utility programs to handle such separate volumes: cf2dsk.exe copies a volume to a separate file, while dsk2cf.exe imports a volume from a separate file into a CF card. So if you have a CF7 device like the nanoPEB, you may have those separate volumes, and you should be able to work with them with TIImageTool.
Another advantage of separate volumes is that you can easily send them to other users by E-mail or upload them to a server - without the need to send your complete CF7 image.
Allows you to create a new, separate CF7 volume.
Formatted volumes are automatically opened after creation. Please keep in mind that at this point, a separate volume does not belong to a CF7 image yet. There is no particular function to import a volume into a CF7 image, but it is quite easy to achieve this with the common TIImageTool operations: Just open the separate volume and the target CF7 image, and copy and paste all files from one to another.
You may be surprised by this one:
Does not allow you to create a new CF7 image. Instead, you should use the functions that are available in the Utility menu.
For an explanation see the section on general considerations.
Concerning CF7 cards, there are two situations to be distinguished. When you attempt to open a CF7 volume, it is opened just like any other floppy image. When you attempt to open a CF7 image which represents the whole CF card, you have to specify which volume you are interested in. A dialog window is displayed which shows the available, formatted volumes in this image.
(CF7 volume) Opens a separate CF7 volume in a new tab.
(CF7 image) Presents a list of defined, formatted volumes of this image file, then opens the volume that you select by single click and Return, or by double click.
For each open operation you can only select one volume to be opened, since there is no multi-item selection capability in this dialog. You can, however, repeat the open action and open one more volume each time.
File management in TIImageTool is widely done in the same way as you know it from working with PC file systems. Files can be moved (removed from the original location and put at the new one), copied (created at the new location without deleting it at the origin), deleted (removed, no way to undo the operation), or renamed (staying at the same location).
One important thing to know is how to determine on which files the operation shall be applied. To specify you must select the files by a single click.
You can select a single file by moving the mouse pointer over the entry in the directory list and clicking the left mouse button. Pressing Shift while clicking the left mouse button, you can select a range of entries, while the Ctrl key allows you to add a file to the current selection. You can deselect files by clicking on them a second time (holding the Ctrl key). If you left-click on any item without holding one of these keys, the current selection will be canceled.
You can work with directories in the same way - directories can be selected to be moved, renamed, and so on.
Sometimes you may need to select all files; you can do this my selecting the first entry at the top and selecting the last one at the bottom, pushing Shift this time. Or you use this menu function. You can also select the whole contents using the Ctrl-A key combination.
These functions allow you to modify the image contents by moving, copying, and deleting entries of the directories. They work pretty much like the well-known functions which are available in many other programs.
These functions are established ways to operate on files in directories. You can select one or multiple files or directories, or both.
You can use the well-known shortcuts: Ctrl-C for copy, Ctrl-V for paste, Ctrl-X for cut, Del for delete.
Moving files on the same image does not move the file contents. It only moves the file into another directory. Moving to another image, instead, first copies the file, then deletes the file on the original image. When you copy or move a file or directory to a directory where there is already a file or directory of the same name, you will be asked to choose another name.
Moving or copying directories applies to the complete subtree of this directory. This means that when you copy a directory to another image, the complete contents will be copied as well.
Files and directories can be renamed.
If you select multiple files or directories, this function is iteratively performed for each one.
New name: Provide a valid name. There is no auto-renaming scheme. The input is checked for validity and whether the name is already used.
You will notice that after renaming the contents will appear re-sorted. The TI file systems use sorted lists of files and directories, so it is an error if the list is not displayed as sorted.
Volumes can also be renamed.
You can rename the currently open volume. This is also the recommended way to change the volume names of CF7 volumes inside a CF7 image.
New name: Provide a valid name. There is no auto-renaming scheme. The input is checked for validity.
After the rename operation you should immediate notice that the volume name has changed above the directory listing.
Hard disks and also floppy disks may have directories to structure their content. Floppy disks are constrained to have at most three directories, and they must reside in the root directory of the file system. This means you cannot create a directory inside another directory when you are working with floppy images. On hard disks, these restrictions do not apply. You can have up to 114 subdirectories in a directory.
Directory name: Provide a valid name. The input is checked for validity and whether the name is not already used. The new directory is created in the currently shown directory.
The menu function and the context menu function are deactivated when you are not allowed to create a new directory at this point.
Barry Boone's Archiver is the standard tool for packing files on a TI or Geneve. Archiver works similar to the tar program; it concatenates all file contents in a single file, including the metadata of the files (file names, types, and other information). Archiver offers the option to compress the whole package using LZW compression. Archiver does not allow for storing directories and can only pack files from a single directory. It does not store path information.
Uncompressed archive files have file type DIS/FIX 128, while compressed archives can be recognized by their INT/FIX 128 file type.
TIImageTool supports Archiver archive files in both compressed and uncompressed mode, and it provides a transparent integration. In fact, archive files are treated like directories, so when you double-click an archive file, TIImageTool will act as if you entered a subdirectory.
Within this kind of "directory" you have all features of TIImageTool at your control: You can view files, copy, delete, rename files, or even create new archives within. Indeed - you can step into nested archives at any level. This is a useful feature which you will enjoy when you encounter archive files that contain archives themselves: You need not unpack everything first but simply follow the path through all nested archives. Unpacking or packing files is simply done by opening the archive and doing the usual file operations.
The only operation you are not allowed to do in archives is to create a subdirectory, as the Archiver format does not implement this feature. However, using nested archives you can get a similar effect, although it has a noticeably worse performance: Any change you apply to a nested archive will imply a re-packing of its parent and recursively of all its ancestors.
This function creates an empty archive. Although TIImageTool can cope with empty archives, you should not try to open it with the Archiver or other tools on the TI or Geneve, as those tools may not have been designed to handle empty archives.
Empty archives are like empty directories, and you can carry on by copying files into the archive.
You can archive files in two ways:
After copying into the archive, the archive file is instantly recreated. If there is not enough space on the image, an error message is issued, and the archive file remains unchanged.
Writing a set of files into an archive is a noticeably complex process because the archive is recreated for each single file. This will hopefully be fixed in a later release. So please be patient when you insert twenty or so files into an archive.
Archives are treated like directories. This means that by double-clicking on them you enter the archive just like a directory. You can unpack the files in this archive simply by copying them elsewhere. For instance, to unpack the archive in the same directory, enter the archive, select all files, choose copy, enter the parent directory (which is the directory where the archive file is located), and paste the files.
Each file may have a specific method to view its contents. In the context menu you can find a choice of applicable ways. The standard way to look at the file is used when you double-click on the file.
You can also select multiple files. In that case, viewing will be restricted to the ways that are supported by all files in the set, and all selected files will be shown in individual frames.
This feature is particularly interesting when the file entries seem to have errors. You can have a look at the FIB as found on the image.
You can inspect each file in its plain dump format as a hex dump, including text files or BASIC programs. You can use this to find out more about the format of the file or when other options do not deliver the desired result.
All files with DIS/VAR 80 format are assumed to be text files. Double-clicking on them will open the text viewer. You can then save the text to a file on your PC file system, or copy it into the clipboard. Editing is not yet possible, although you can achive this by creating a new file with text content, and copying the contents into the editor frame.
TIImageTool recognizes four image formats:
Viewing a UTIL/GK dump is almost the same as viewing the plain dump, with the exception that the UTIL or GK header is analyzed and the addresses are automatically set according to this information. In this version the header can only be used for the ROM portions of a GK dump, so this option does not show up for the GROM parts.
This option is not available when the program does not recognize the first bytes of the file as a valid UTIL or GK header.
When TTImageTool concludes that the selected file is a BASIC program, it offers the option to list the BASIC program, and double-clicking will open this listing as well. BASIC programs are recognized in three formats:
By default, programs are displayed in the style as used by Extended Basic. In particular, this means that several subsequent colons are displayed with spaces in between so that they are not interpreted as the statement separator (double colon). This behaviour can be changed in the Preferences.
In text files, all bytes are supposed to be visible in the viewer frame. However, there may be unprintable characters, used as control characters for formatting, or used in BASIC programs for defining graphics. You can tell TIImageTool to replace these unprintable characters by a single character, or by an escape sequence. This can be configured in the Preferences.
There are essentially two option so far:
TIImageTool allows to view the source code for two low-level languages. You can disassemble GPL programs in memory image format (PROGRAM type) and native machine language programs (TMS99xx) in memory image format (PROGRAM) or tagged object code format (DIS/FIX 80).
Disassembling is the reverse operation of converting assembly language programs into an executable format. That means, disassembling allows you to retrieve the human-readable source code from the executable code.
Not all original information can be restored, however. Unlike BASIC programs, machine language programs do not store comments. Also, data words, bytes, or texts cannot easily be distinguished from machine commands. When we encounter a sequence of bytes in memory, these bytes may have been assembled from a DATA line, but possibly also from a command line.
In TIImageTool, you can give the disassembler some hints how the bytes should be disassembled. In particular, you can specify regions in the code which have to be interpreted as data.
Assembler programs that are written for the TMS99xx platform are also called native code programs. Native code is stored in two variants:
Although tagged object code seems to be much more comfortable, loading is much slower. This is the reason why programmers ultimately try to bind the object code to a program file.
Depending on your selection, the TIImageTool disassembler presents a specific dialog for parameters. Program image files need the precise memory location where they are intended to be loaded. If the file contains a header, the header contents are filled as defaults into the dialog. Otherwise you have a chance to adjust these values. You can also start to disassemble the file somewhere in the middle.
When you disassemble tagged object code, you cannot specify a loading address, since the address is usually defined as relocatable.
Disassembling tagged object code yields results that may be re-assembled again. Indeed, TIImageTool tries very hard to create syntactically correct source code. Try it with some small examples to get an idea how well the original source code can be reproduced.
Decades before Java showed up on the scene, Texas Instruments invented a virtual machine inside the TI console. This virtual machine has an own machine language called GPL - Graphics Programming Language. GPL is a complex instruction set 8-bit language. It is specifically tailored for use inside the TI computer, introducing more addressing modes with all available memory spaces (CPU, VDP, GROM, CRU) for source and target addressing. The TI BASIC interpreter is completely written in GPL. And now you know why it is so slow.
TIImageTool contains a GPL disassembler. GPL code is only available in memory image format, and it cannot be loaded in the TI system, as GPL is only intended for use in GROMs, which can be found in the console or in cartridges. But even when you do not intend to write own GPL programs, you may be interested in finding out how some cartridges are programmed.
When you work with MAME you can try to have a look at the GROM contents of the console: Unpack the ti99_4x.zip file, and import the file with the GROM contents into a disk image. Once it is on the disk image you can start the disassembler to get the source code.
There are different variants of the GPL source code format, which is due to the fact that TI did not release a specification to the public. Compared to the code as seen in the popular TI Intern book, there are some differences:
As already mentioned the disassembler cannot know whether the bytes it finds in the file were created from instructions or from data or text lines. You can give the disassembler some hints how to interpret the data appropriately. Several hints can be written one after another, separated by spaces, commas, or newlines.
The good thing: The disassembler hints are stored in the settings file. Actually, TIImageTool uses the contents of the file to compute a key to look up the values, so you can rename the file on the image, and the values are still correctly found.
The hints make use of memory location specifications. We make use of the term location as a generalized form of an address.
There are several kinds of hints:
Data region
Format: data(from,to)
Tells the disassembler to create DATA lines for the given memory region. In the memory image formats of the native language or GPL language, the addresses are specified as 4-digit hexadecimal (absolute) addresses. For tagged image code, addresses are specified as locations.
Example: data(R0100,R017F) - declares the region of relocatable addresses 0100 to 017F as a data area.
Text region
Format: text(from,to)
Tells the disassembler to create TEXT lines for the given memory region. If the bytes are not within the range of displayable characters, BYTE lines are created instead.
Example: text(X6100,X6277) - declares the region of absolute addresses 6100 to 6277 as a text area.
Format: btext(from,to)
Only available for GPL. Similar to text(,), but the characters in the region are shifted by 96 positions. This is the case in TI BASIC. Using this hint, the disassembler can create useful (readable) representations of the region.
Referenced line
Format: ref(location)
Only available for tagged object code. The contents at the specified location are referenced by another line, for instance, as a jump or branch target or by source or target memory access. This means that the contents are very likely not suitable as arguments of another command. With this feature you can prevent the disassembler to falsely consume the bytes at this location when it tries to disassemble an assumed command in the predecessing location.
Example: ref(R0204) - the word at the relocatable location 0204 is referenced from somewhere else.
Call parameters
Format: param(branchTarget,count)
Specifies that a BL / BLWP call (in GPL a CALL operation) is followed by a fixed number of data parameters. In the native machine language, you can only specify a number of 16-bit data words. In GPL, the count refers to the number of 8-bit bytes.
You can specify the branchTarget by the location of the subprogram, or by its label. Labels must be enclosed in quotes.
The number of following data lines must be constant for each branch target, as the disassembler cannot find out how many data lines are required at run time. If you are serious, you don't really want to write your programs this way.
Example: param("XMLLNK",1) defines that calls to XMLLNK are always followed by one DATA line.
FMT inhibit
Format: nofmt(from,to)
Only available for GPL. Prevents the disassembler to disassemble FMT commands in the specified area. This is useful in order to prevent a false disassembly of data items as FMT. The specific problem with FMT is that it can be used to build nested formatting structures, and in that role, each FMT must be terminated by a matching END directive. If the disassembler runs into plain data areas, this constraint is not fulfilled, and the rest of the area will end up in a phantom FMT block. An error message will be printed at the end which informs about the location of the unmatched FMT command.
Example
These are the hints to be used for disassembling GROM 0 and the first 512 bytes of GROM 1. Use 0000 for offset and start address, and 2200 for length.
data(0000,000F),data(0045,0049),data(004C,0051),data(044F,048F), text(0490,04BB),data(04BC,094C),text(094D,094F),data(0950,099F), data(0FDB,117A),data(1267,12A9),text(12AA,12BF),data(12C0,130F), data(1310,1314),text(1315,1317),data(1318,131C),text(131D,131F), data(1320,1325),param(14A9,1),param(149F,1),param(14FE,1),data(15A0,17FF), data(2000,200F),btext(2022,214C),data(214D,2151), text(2152,2159),data(215C,216E)
Viewing a directory is simply done by double-clicking on its name, or by selecting Enter in the context menu. Note that directories are always listed at the beginning of the contents, and that they are shown in blue colored text, like the archive files. To close the view, you can either completely close the tab, or you enter the parent directory "..". The root directory has no parent.
As long as they are not open, archive files are treated just like files - you can view their contents as a plain dump. However, you can open them by double-clicking or by selecting Enter in the context menu, and just as with a directory, the current tab displays the contents of the archive. Watch the path information in the heading showing an "(Archive)" notice.
You can create an empty archive and copy files into that archive as you do with a directory, or you can create an archive from selected files. The archive name is suggested by taking the first 6 characters from the first file name and adding "_ARK". You can change this suggestion if there are already files in the directory with that name.
Find more about this feature in the Archive support section.
Sometimes you may want to send a file to someone else by E-mail, or you are using an emulation that makes use of external files (like Classic99). In this situation you have to export a file from a disk image to the host file system.
Exporting and importing are simple ways to exchange files with a real TI system via a serial connection. The standard external format TIFILES was defined long ago just with the requirements of uploading and downloading TI files to or from a file server.
TIFILES files are files on a non-TI file system (e.g. on a PC) which contain information about the contents and about the file format which would otherwise be lost in a PC file system. Essentially, the file from the TI is put inside this format with the relevant entries from its File Information Block and with the contents of the sectors it occupied.
TIImageTool will analyze the information at the head of the file and rebuild the file within the currently open directory. That is, you can import the file at any location in the image.
The file name is specified in the head of the file as well, but earlier versions of the TIFILES format did not require a file name in the header, so it will not be found during import. In this case, TIImageTool offers two possibilities:
You get this dialog window only when the file to be imported lacks a file name in the TIFILES header
Guessing the name is particularly useful when you want to import a larger set of files and you really do not want to define every single name. The importer takes the PC file name and creates a valid TI file system name by stripping off the suffix (".tfi", ".tifile", ".tifiles") if there is one, converting all letters to uppercase, replacing "." by an underscore, and truncating the name to 10 characters. This turns "telco.ark.tfi" into "TELCO_ARK".
You can find the rules by which the name conversion takes place in the Preferences dialog.
You can also import files which do not have a TIFILES header. These files may have been created by some communication tools that spared this header to lower the communication overhead. In that case you will get a dialog window where you can specify all missing data, from file name to file type, record length, and more. The dialog window fields are initially filled with a suggested DIS/FIX 128 format.
It is recommended to use the ".tfi" suffix so that the file dialog can filter away all other files in the directory. If the file has another suffix you must switch to "all files" in the file filter.
You get the following dialog window when the file has a TIFILES header, but the name is not valid. This is a somewhat exceptional situation, so the auto-repeat is not offered here.
In this release, you can define your own preferences for handling file names during import and export. For instance, you can specify that the file name of the file on the PC file system shall be used as a file name within the TI file system, or, shortly, to ignore the file name in the TIFILES header. When there is no suitable file name you can tell the program to use the external file name so it will not ask you to provide a name. The external file name will, however, be checked for characters that are not allowed in the TI file system, and they will be replaced appropriately.
If the file on the PC file system is a plain text file, you can import that file as a DIS/VAR 80 file. This also means that the PC-typical file structure with lines, separated by CRLF or LF, has to be converted to a sequence of variable records with length byte. This is automatically done in this function.
TIImageTool tries to figure out whether the file is a text file or not, and offers you a dialog window where you can ultimately decide. If it detects other non-printable characters, it will present you the dialog as mentioned above (for files without TIFILES header). Sometimes, text files also contain control characters like ASCII 12 (form feed); instead of catching each of these exceptions, the programs leaves the decision up to you.
Also new to this release, TIImageTool will try to find out whether the imported file is a BASIC program. For this purpose it looks at the first ten lines (or less) and tries to parse them for TI BASIC and then for Extended Basic. When successful, it offers you a modified import dialog.
This is actually a counterpart of the export feature explained below. You can recreate the whole directory structure (if possible; mind that floppy disks only allow a single layer of directories). The information about the directory name is stored in a file called meta.inf.
This feature is mainly useful when you want to add a new text file into your disk image. Suppose you want to program some application in assembly language, but you prefer to use your editor on the PC. In that case you can simply paste the text contents from the clipboard into the open window and save it.
Alternatively, you can also use the file import function.
Here as well, TIImageTool tries to figure out whether this can be interpreted as a BASIC file, and if that is the case, it will provide you with the options listed above.
The TAB and special characters entry is only shown if such characters were found. For instance, the umlaut characters are usually mapped to {, |, and } in the German versions of TI Writer.
Usually you should always have a proper TIFILES header when importing. However, you may probably want to import a plain binary file (for instance, a dump from a cartridge).
You can try to read your TI floppy disks with the PC floppy drive (this is perfectly possible, since TI used standard formats, but you must have access to the low-level functions of the controller to configure the parameters), connect your SCSI drive to a SCSI adapter, or you transfer the files via a serial connection.
Using this menu item you can utilize the XModem support in TIImageTool, and by this way you can send files from the TI where you have to run a suitable terminal program like TELCO or PORT.
See more on that in the section on serial connections.
The HFDC (Hard and Floppy Disk Controller) from Myarc allows for mounting a file on the hard disk as a floppy disk; the file must be an image of that disk like the sector dumps that we have on the PC file system. This is useful for situations where a program expects all data to be on the disk in drive DSK1. This was not an issue before the hard disks showed up, but proved to be a nuisance because you could store all your floppy disks on the hard disk, but you could not use them because they still searched files on the physical DSK1 drive.
TIImageTool offers this feature to create an emulate file on the hard disk image. These files are indicated by the Emulate type in the directory view. You can import any floppy disk image to the currently open hard disk directory view.
You can certainly have more than one emulate file on your hard disk; the one that is marked as active will then take the role of the DSK1 drive. If you want to get access to the physical drive, you have to deactivate the emulate file again.
You can select multiple files to be imported as emulate files. In order to activate one of them you have to use the Toggle emulate flag function in the context menu. Also, in order to save the emulate file as a disk image again, you can use the context menu on that file and select the Save as DSK image function.
The export function is closely related to the Save as TIFILE option in the context menu. Unlike that one, however, it acts as if the root directory of the currently selected image has been selected.
The TIFILES format has been established as an external format for files stored in TI file system. This external format preserves all file meta-information beside the file contents. TIFILES files may be easily imported into TI disk images. Also, terminal emulator programs like TELCO or PORT make use of the TIFILES format when sending or receiving TI files. Sometimes the TIFILES format is also called the XModem format as the data transmitted by XModem is stored in this format on the remote computer side. The format itself has nothing to do with the actual XModem protocol.
The complete image will be exported, including all subdirectories. The volume of the currently open and selected directory is exported to a directory on the PC file system that you select in the file chooser.
The export feature suggests a scheme for creating file names for the TIFILES files.
For each directory on the TI image a directories is created in the target folder. To preserve the original name, a file called meta.inf is put into each directory, containing meta-information about this directory. At this time, the inf file only contains the actual directory name.
As a result you get:
You can save a single file or a set of marked files to your PC's file system in TIFILES format. All information is stored inside the file header so that you will be able to import these files comfortably, without specifying anything but the target directory.
If the file you want to export is a text file, you should better open a text view and save it from there.
The only thing that you have to specify here is what PC file name shall be used. If you create a single file you have to provide the name directly. For a set of files, you will be supported by a file name creator which guesses suitable names.
The Export image feature is similar, but it always exports the whole image. This also includes all contained directories. As a result you will find a directory structure on your PC drive with the respective exported files in it, and each directory contains a special file which tells the importer what name to assign to the newly created directory.
This option saves the contents of the file as a raw dump. With a hex editor you can see the same contents as if you were viewing the file as a plain dump.
This is the counterpart to the remote import from above. You can transmit a file to a remote system, usually another TI or Geneve running a suitable application, using XModem. In this version you can only send a single file, not a list of files.
Find more on remote communication in the serial section
An emulate file can be used as a target for redirecting all DSK1 accesses to the physical drive. It is a sector dump of the contents of a floppy drive. Since there may be more than one emulate file, one of them must be marked as active. If no emulate file is active, the real floppy drive becomes visible again. You can use this option to toggle the flag on a single emulate file, or to remove the flag from another emulate file in order to set it on the currently selected file.
The reverse operation from importing as an emulate file is to save the emulate file as a disk image again. You have to choose the target directory and file name. The result will be a sector dump image.
For all serial operations in TIImageTool you need the RXTX library which provides an access to the system's serial adaptors. If TIImageTool does not find the RXTX library it will disable all these features.
For some more information on setting up RXTX and on working with the serial connection please see www.ninerpedia.org.
TIImageTool utilizes the serial connection for two purposes.
XModem transfer is a traditional way of transmitting files over a serial connection, between directly connected computers or using a modem connection.
You have to start suitable applications at both ends of the connection; one side is the sender, the other the receiver. Using Send to remote you configure TIImageTool to be the sender. You can choose TELCO, PORT, MYTERM or other tools on the TI/Geneve side to provide the receiver. The same programs will also serve as sender.
For setting up the connection you have to specify some parameters:
The receiver must define the same parameters. One exception is the transfer protocol option which is negotiated between both sides. During the transfer you can watch the progress of the file transfer. When receiving, TIImageTool will place the file into the currently open directory.
The serial bridge is a special feature used in conjunction with the serial emulation in MAME. It is used to establish a serial connection with another computer, in particular with a real TI or Geneve. The serial bridge consists of a server socket which communicates with MAME, and the serial library using RXTX which operates a local serial interface.
If you get an error message "No serial ports found" then either you actually do not have a serial port, or all serial ports are already used.
Assuming that the bridge uses port 10000 on the same computer where MAME is running, you have to specify this as follows:
mess ti99_4a -peb:slot6 tirs232 -serl1 socket.localhost:10000
You can also launch the serial bridge without bringing up the TIImageTool GUI by starting it with the parameter BRIDGE:
java -jar tiimagetool.jar BRIDGE /dev/ttyS0 10000
Other than in the XModem scenario, you cannot set parameters of the serial bridge. These are actually set by the connected MAME emulator, or, more precisely, by the application running inside the emulator.
With this bridge running, you can let the emulated TI/Geneve communicate with a real TI/Geneve or you can attach a modem. Concerning the XModem communication, you can now run TELCO on both sides (emulated and real) and use it to move files between them.
The serial bridge menu item is always available, unless you have already opened it; you can only run a single bridge with TIImageTool. Please make sure you have prepared everything for the creation of the serial connection; check with the manuals of RXTX. In particular, you must be eligible to access the serial interface of your PC, and you must have permission to create a lock file in /var/lock (when using Linux).
Many of the features have been explained above; here are the remaining points.
When you select this function, the log file is opened and shown in a new window. Note that each start of TIImageTool adds a separator line (=====) but does not clear the log file. You can clear the file by the menu selection Clear content in the File menu of the log output window.
The window shows the contents of the log file at the point of opening and is updated when new entries are added. If you prefer to see the output in the console from where you launched TIImageTool, you must remove the file name in the Preferences, thus redirecting the output back to the standard output and error channels. Of course, you do not see any output when you start TIImageTool by double-clicking its symbol on the desktop; in this case you should enter a log file name.
Using this function we can check the integrity of the file system. This is a multi-stage test which checks the following properties:
As for the "broken sectors" check, formatting procedures usually fill all sectors with values like E5E5 or D7A5. Some copying tools fill sectors with the value DEAD if the sector was not successfully copies. Although it may happen that such values indeed appear purposefully within the file, in most cases this is an indication that something is wrong. You should then check by yourself what might be the problem with this file.
One of the problems you first encounter when you start up a Geneve (whether real or emulated) is that you will get an error message if no disk is inserted in drive one, containing the operating system.
TIImageTool contains in its JAR file a freely distributable release of the operating system called Geneve Operating System (formerly called MDOS). The main operating system file is called SYSTEM/SYS; another file is required when the HFDC controller is used, called LOAD/SYS. Finally, similar to known operating systems on the PC, a text file named AUTOEXEC contains commands that are executed after booting is complete.
For bootable floppy disks, all three files are put into the root directory of the floppy disk that is currently selected.
For bootable hard disks, the LOAD/SYS file is put into a directory that is located at root level; the other two files are put into the root directory.
Unless there was an error (maybe because the disk was already full), you can directly boot the Geneve with this disk mounted as floppy disk 1, or with a hard disk as hard disk 1.
Have you ever desperately looked for a file? No idea what disk it was stored on? - The search function in TIImageTool provides you with a flexible tool to find your files.
Besides looking for file names, you can even search for content. For this search process, a copy of the file contents is searched, where all non-printable characters have been replaced by space characters. The original file is not affected. Searching for content takes more time, but it may be the only way if you don't even remember the file name.
Third, you can search for the creation or update date of files. Usually, you would use a regular expression at this point, like "2016-.*", which refers to all dates that start with 2016. When there is no update time, the creation time is used for comparison. If neither exists, "none" is used as the date string.
During the search process, a progress window pops up that allows you to interrupt the process. It also informs you what image file is currently checked, and how many hits have been found at this time.
Finally, a result window is displayed. When you click on a result, the image containing the match will be opened in the main window. The file may be contained in a subdirectory; you will have to navigate there manually.
In section Compact Flash handling we already learned about the considerations concerning the access to a compact flash card, be it a CF7 card or an ordinary card that contains a copy of a TI hard disk file system.
With this function the contents of a flash card are read to a file on the PC file system. This resulting image file can then be modified and written back to a CF card.
The Read function does not care about the data structure on the CF card, it simply creates a copy of the contents, so you can use it both for working with CF7 or non-CF7 formats.
In Unix-like systems there is no editable field for the dd command here. You can set it in the preferences. The reason for not offering a field here is that the command is usually installed as a system tool, so the position is determined by your operating system, and it is not in the user's responsibility.
In section Compact Flash handling we already learned about the considerations concerning the access to a compact flash card, be it a CF7 card or an ordinary card that contains a copy of a TI hard disk file system.
With this function the contents of a file are written to a CF card. The file may be a hard disk image file or a CF7 image. Usually the file has been copied from the same CF card and edited with TIImageTool.
The Write function does not care about the data structure of the file, it simply copies its contents to the CF card. You can use it both for working with CF7 or non-CF7 formats.
Please keep in mind that writing to a CF card is a critical operation. If you select the wrong drive letter or path, you will overwrite the selected drive which may, in the worst case, be your system drive. You would then lose all data on the drive and make it necessary to reinstall your computer system from scratch.
In order to use the CF card as a CF7 image, you must create volumes on this image. Note that we are not working on the CF card itself but on its copy. After formatting you must write the image back to the CF card.
Volumes are addressed by numbers. The first volume on the CF7 card has number 1; it must be formatted so that TIImageTool is able to recognize it as a CF7 image. This can be done by this function.
Every volume is exactly 400 KiB long. When you want to open a volume from this image, you will be presented its number and volume name in a list of formatted volumes.
Unlike the read and write CF functions, the format CF7 function does not require the DD tool. However, when you want to copy the results to a CF card, you will need the DD tool.
If your disk images are created and updated correctly, everything you possibly want to do is already covered by the previous functions. But what if your image is broken? A similar situation occurs when you discover that there is a flaw in the file information block of a file, and you know you just have to change a few values to make it work again.
As a 1337 h4xx0r (leetspeak for "elite hacker", go look it up, I won't explain everything) you certainly know what to do. You use your favorite hex editor and change those bad values. On the TI there are some good programs for that, and on the PC you could, for example, use ghex.
This will work, but only for the simple cases of DSK images. The reason is that not all images contain the sector contents in a simple, direct way. Remember that the DSK files (sector dump) are just a concatenation of sector contents from the first to the last sector. The DTK format (track dumps) are a bit trickier: You have to locate the sector first, then change the value, then remember to fix the CRC value of the sector, or you will get CRC errors. And for the HFE format, none of that will work, because this format just contains MFM level changes. Good luck with finding out the MFM encoding of your changes...
Accordingly, the sector editor of TIImageTool works on top of the image format; this means you can actually edit the sector bytes, but the format implementation will take care of writing the appropriate changes to the image.
You cannot edit the sectors of an open image. No, you wouldn't like it, really. Just close it before you try to edit it, which means all tabs for that image.
When the image has been successfully opened, the contents of the first sector (sector 0) are displayed. On the left side there is the hex byte representation, while on the right side you should see an ASCII byte display. Only characters are shown that are printable; all others are shown as periods. That means, generally you will see a lot of periods on the right side.
There are four input widgets at the top:
When you click into the hex or ASCII display, a yellow cursor will appear. You can now change the values of one byte or of several successive bytes. Watch how the other display is immediately updated when you change values. Pressing Return in the editor windows lets you advance to the next byte. Pressing ESC leaves the editing mode, and the cursor disappears.
Changes are not committed to the image file until you select Save changes to image. If you close the window before saving, you are warned that there are unsaved changes. If you feel like having done something stupid, you can always revert the original contents of the sector, but only when the edits have not been saved yet. You find this feature in the menu as well.
Finally, you can save the sector contents to a file as a textual hexdump.
This may be particularly interesting for Linux people. You can start TIImageTool without windows - just on the command line, or within a script file.
When launching TIImageTool you simply add the parameter CommandShell and the respective command.
At this time, there are three features you can invoke this way:Some examples:
This is the manual that you're reading at the moment. You can get it quickly by pressing F1.
You may have noticed that TIImageTool is getting more and more bloated, and it already takes quite a long time to read through this manual. For this reason I added a feature that I paradoxically never liked in other programs.
On startup, a short message will be shown that presents some of the important capabilities and properties of TIImageTool to you. The good thing is that you can stop that by selecting Don't show me hints on startup.
Well, you should not do that too quickly. These messages do have some sense, and while I know well what is inside my program, you very likely do not. Just let me have a short word on that, and then you can continue. If you know my hint, you can block it from further bothering you by selecting I know that one already.
You can use the preferences in the File menu (also see below) to turn on or off the automatic hints on program start. If you feel like getting a hint during runtime, just select the menu point in the Help menu, or press the F3 key.
This function opens a small message window which tells you the release number of this program. This is important when you experience problems and you want to get some help from other people.
Some settings may be done in this function. The settings are saved to disk so that they will be available on the next program start. At this time you can choose the font of the content display.
You can set properties which are saved to disk and loaded the next time you start TIImageTool. The preferences are divided into categories.
General
Paths
CF card
Output
Importing
Exporting
The settings are saved to a file called tiimagetool.prop on Windows systems (located in the home folder of the user). On other systems like Linux the file is called .tiimagetoolrc and is located in the user's home directory. Opening the file in an editor reveals some more settings which the program saves for itself during usage. You can change the contents of this file as long as you keep its structure (name=value pairs).
Terminates the program. Changes to image file are always committed immediately, so there is no need to explicitly exit the program by this option. However, preferences are saved on exit. Closing the main window is equivalent to this menu function.
CHD format is a container format used by the MAME emulator. It is used to store contents of mass storage devices like hard disks, CD-ROMs, Laserdisks, and more. The CHD format (short for "Compressed Hunks of Data") allows for compressing the contents and for checking the integrity using checksums and digests. For hard disk images the CHD container must stay uncompressed because the contents are likely to change during usage (unlike CD-ROMs which remain unchanged).
DSR is short for Device service routine and would be called a device driver (or firmware) in the PC world.
LONG format is used by Extended Basic when a program does not fit into the free space of video memory. Although it may reside in the memory expansion, the BASIC code must be copied into the video memory to be saved in PROGRAM format. If this is not possible the program is stored in a record structure file instead of in a program file.
RXTX is a free implementation of the java.comm API. TIImageTool links to these classes, so you must use RXTX and no alternative implementation. Please visit the RXTX homepage and download the binary package. Installation of RXTX is very simple; you only have to put the RXTXcomm.jar and the librxtxSerial.so (Unix) or rxtxSerial.dll (Windows) into your Java installation. For Windows, search the folders ext (for the jar file) and bin (for the dll) in your Java installation (in Program Files) and copy the files into them. Restart TIImageTool, and the XModem options should be available.
SDF images are in sector dump format, which means that the image consists of consecutive sector contents. This format is also known as v9t9 format, named after the v9t9 emulator which used this format first. SDF image files should use the suffix .dsk. SDF images are always assumed to have a size of a multiple of 256. There is a known extension of the SDF format with a map of bad sectors (768 bytes) at the end; this is detected and ignored, allowing to work with this image.
TDF images are in track dump format, which means that the image consists of whole track dumps including data outside of sectors. This format uses more space that the SDF format, but is more accurate to the structure of the real medium. This format is also known as PC99 format, named after the PC99 emulator. TDF image files should use the suffix .dtk. In everyday usage, the SDF format should be preferred as it is more common among the different emulators, and it is also much less overhead during processing, which could be important if you run the emulator on a weaker PC. Note that the TDF format differs from the PC99 formats for single-sided disks. If you intend to create disk images for the PC99 emulator, only use double-sided formats.
HFE images are images that represent the flux changes on the disk medium. They are used in the Lotharek Floppy Disk Emulator.
TIFILES is a format for the external storage of TI-99 file system files on PCs. TIFILES files contain the file contents and meta-information about the file, like the file type and the file structure. This information is required for restoring the file in a TI-99 file system. TIFILES files are therefore well suited to be stored on file servers, and the Classic99 emulator uses TIFILES directly. TIFILES files should use the suffix .tifiles, .tifile, or .tfi.