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 MESS 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 MESS, 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 MESS 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 a well-known, 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.
You can start TIImageTool 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 image_file argument, TIImageTool will directly open the image on startup.
You can also start the serial bridge without launching the rest of the program by using the command line:
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. I have added a huge load of new features to the previous version of TIImageTool, certainly testing everything several times in different ways. But it's just impossible to ensure that everything works as expected.
So if you find something weird going on with TIImageTool, here are some suggestions:
In all cases, if you need help please contact me at ti99@mizapf.de. It is most helpful for me to find the cause of the problem if you provide me with a detailed description what you did before the error appeared. So if it seems to you as if there is a problem, first try to reproduce the problem, so my chances are better to quickly find it. In case of doubt, contact me, don't try to live with the problem.
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; then I was in need of a tool which allowed me to quickly check whether all images have been correctly copied. MESS offers a tool named imgtool, but it is a text-only command line tool, and its main usage seems to be to create new images. After I added the track dump format to the TI-99 emulation in MESS, I should have added that support to imgtool as well. imgtool is a good tool if you are working with many different emulations in MESS, but it cannot cover all features that one would like to have for one specific platform.
So 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.
The typical usage is to open one or more images using the open function in the file menu and to view, move, copy, or save files stored inside the images.
When an image is loaded its contents are displayed in an own tab in a format similar to the directory displays in 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. You can certainly do file operations (like moving or copying) across different tabs.
With the 2.0 release, you can detach tabs from the main window. When you close the detached windows, they become tabs of the main window again, unless you close the main window, which shuts down all open windows at once.
In general, we call a directory listing of an image a view. Thus, 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 use the context menu.
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 provided 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. Thus 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 well-known 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 of the most notable enhancements of release 2.0 is the Drag-and-Drop support (DnD). You can now 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 is the default operation in TIImageTool. This 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.
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.
You can copy 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.
We're not done yet. 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 indeed be handled as an export operation, and you can again handle one or more files or directories in one go. The exported files will appear as TIFILES files on the file system.
You can even drag files into TIImageTool from your file system. Simply try to pull a text file, or maybe a BASIC program? I guess it is better you just have a try before I continue with long explanations.
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. Its contents depend on the entry - BASIC files, for instance, cause the List BASIC feature to become active. The "free space" of the directory tab offers a own context menu which contains options to create new entries 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. MESS 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.
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.
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.
If you work with a small set of image files the "Open recent" feature considerably speeds up your work.
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 MESS just like floppy disk images, but they are usually much bigger due to their higher storage capacity.
MESS 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.
MESS 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).
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 versions
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.
TIImageTool supports versions 4 and 5 of CHD. MESS itself does not accept older formats, which means that every now and then you will have to upgrade the format of your CHD containers. TIImageTool allows you to change the version of the CHD container, even to downgrade, although this is only reasonable when you want to use the image with an earlier MESS release.
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 MESS tools or with TIImageTool without formatting, you must format it inside the emulation (e.g. with the Myarc Disk Manager). However, you will notice that the CHD will grown to its maximum size at once. The formatting tools in the emulation write a test pattern on the disk, and the CHD support in MESS cannot know that this is merely a test pattern. However, this can be "fixed" because TIImageTool 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 MESS 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 MESS about the geometry of the drive even when it is not formatted yet.
Also here, 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. MESS CHD v5 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 MESS at this time (0.159).
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 MDOS 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 MESS versions, only the HFDC controller is emulated. Later MESS 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.
We cannot access floppy drives directly from TIImageTool, as we cannot configure the PC floppy controller from within Java. However, if no reconfiguration is necessary, we can also access devices directly.
This is useful in two scenarios:
We can assume that the TI file system can be directly found on the "raw" device, as the TI does not make use of partitioning. Certainly, the PC operating system (whether it is Windows, MacOS, or Linux) does not recognize the TI file system, but we still have the option to directly access the drive. The SCSI or flash disk contents looks just like an image, and TIImageTool can open them.
Enter a file or drive specifier: You can open one image file by providing the complete path, but its primary intention is to open a device that does not have a PC-readable file system. Keep in mind that the changes are always directly committed to the file system.
Please make sure that you do not unintentionally select another drive in your PC; you have a good chance to break it. You need administrative privileges to open a device directly, so you have to start TIImageTool as root or Administrator.
Within Linux, a device file typically looks like /dev/sda or /dev/sdb (with no partition number). In Windows you can use the drive name like E: where the device is mounted.
Known issues:
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.
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 three 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 MESS 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)
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.
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.
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 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
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 MESS. 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 MESS, 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 MESS 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 MESS 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 three 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 only shows the contents of the log file at the point of opening. It is not a live view. If you want to see the output immediately, you should remove the file name in the Preferences, thus redirecting the output back to the standard output and error channels. You can see the output when you start TIImageTool in a console, not if you start it by mouse click.
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.
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 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 MESS 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.
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.