Q-TRANS by Dilwyn Jones

Introduction

Q-Trans is a pointer driven dual window file transfer package originally developed as part of the Launchpad QL Desktop program, but released for standalone use.

Credits

Q-Trans was written by Dilwyn Jones, using the Easyptr 3 programming utility from Albin Hessler, and compiled with the QLiberator compiler from Liberation Software. The package also uses the DJToolkit from Norman Dunbar and the Display Code extensions from QL Today. Q-Trans is a freeware package which may be freely copied for all QLers. Q-Trans is copyright (C) 2002 Dilwyn Jones.

System Requirements

The software requires pointer environment, Toolkit 2 and expanded memory to be present.

Backup

Use your favourite backup program to make a copy of the Q-Trans disk, or use the Toolkit 2 WCOPY command to make a copy.

Configuring The Software

Q-Trans has a standard level 1 configuration block built in, so the program may be configured with the usual Config or MenuConfig programs supplied with most pointer driven QL software.

To configure the program, tell Config or MenuConfig to load QTRANS_OBJ and work through all the options one by one to set the program defaults listed below.

1. Sound Prompts Off Or On.

The program issues some beeps to accompany any error messages. If you'd prefer silent running, this can be set to OFF.

2. Default Left Pane Drive/Directory.

The program has two filename listing windows. Both have an associated drive and directory name, from where filenames are listed. This entry specifies the default name used for the left hand window (or "left pane") when the program starts. Normally this would be a drive name such as FLP1_ or WIN1_. You can also specify a directory if required, e.g. WIN1_GENERAL_. If this drive/directory is not found when the program starts, an error message will be issued and the file list window will be empty until another drive/directory is specified. If the name is specified as a single underscore character, this will be converted to the DATA_USE default setting when the program starts up.

3. Default Right Pane Drive/Directory.

Default drive/directory name for the right hand file listing window. Settings as for the left window described above.

4. Specify Printer Output Device.

This is used for printing files lists or hard copy of files. This will

normally be SER1, SER2 or PAR, though you can enter a filename or

network printer name if required.

5. Print Formfeed After Printouts.

This allows you to eject the last page after printing has finished. Normally used for laser printers or inkjet printers which may not release the last page if it is not a full page of text. I normally have this set to YES.

6. Pause Between Files Printed.

If you'd rather that the program paused between hardcopy of each fle selected for printing (e.g. so that you can check the previous printout was OK before proceeding and escape befor eprinting the next one if the printout is not satisfactory for some reason), set this to YES. If you just want the program to print selected files continuously (e.g. the computer is left unattended for the printing) set this to NO.

7. Specify Initial Display Height.

The program can be configured to start in one of 7 preset display sizes, to suit the most common QL display heights. If you start the computer in a smaller display height than that specified here, the program wll search for the nearest suitable smaller size and attempt to start the program to suit that size of screen. If all else fails, the program will start in QL screen (512x256). The available sizes are as follows, the number indicating the maximum number of visible filenames per window:

11 lines (about half QL screen size)

21 lines (QL screen)

23 lines (Extended mode 4)

30 lines (EGA screen)

43 lines (VGA screen)

55 lines (SVGA screen)

72 lines (1024x768 screen)

If you like, set this to the largest possible size and Q-Trans will always try to start with the largest display it can manage.

8. Drive/directory name for Trash can

Up to 10 characters may be specified as a path name for the Trash can. It is suggested that this be a single character directory name on a hard disk using an uncommon directory name (e.g. win1_*_), although the limit would allow a single character directory name over a single digit network station number if required (e.g. N1_WIN1_*_). If a blank entry is given, the Trash can facility is disabled - if the system does not have reasonable capacity drives such as hard disks or high capacity disks, there is little point trying to use the Trash facility.

9. Trash can mode of operation

The Trash can stores details of the original path name for a file (i.e. where it was Trashed from) in a small file with a name ending with '_t'. One of these files is created for each file Trashed using Q-Trans. If there are a lot of files in the Trash can, these will effectively double the length of the list of files. If you don't need to see the all of_the files you can reduce the length of the list of

files in the Trash can by opting to 'hide' these files by setting the 'Hide Trash can _t files' option to Yes.

Starting Q-Trans.

Simply execute the program with the EXEC or EX command or similar commands from commonly available toolkits.

EXEC FLP1_QTRANS_OBJ

The program can also be launched from most QL desktop programs and program launchers. It has been tested with Launchpad, Qascade and DEV Manager and will no doubt work with anything that will launch QLiberator compiled programs. The program will work in high colour modes, but always uses the original QL colour scheme for maximum compatibility. The program is designed to work on both QDOS and SMSQ/E systems equipped with pointer environment.

If you pass an option command parameter to the program (a string after the EX command) you can specify the default drive names of both windows, which will override the configured default drives. The first drive name should be separated from the second one by a single space character. This facility is useful for QL desktop programs like Launchpad where you can use Q-Trans as a form of file menu and pass a parameter to it to specify which drive(s).

EX FLP1_QTRANS_OBJ;"FLP1_ WIN1_"

This will start Q-Trans with the left pane listing filenames from FLP1_ and the right window pane listing files on WIN1_. If you just wish to specify the left hand pane drive, simply specify that:

EX FLP1_QTRANS_OBJ;'FLP1_'

If you wish to specify just the right hand pane drive, omit the first drive name, and put in a single space before the drive/directory anme of the right hand files window:

EX FLP1_QTRANS_OBJ;' RAM1_'

Mouse Terminology

HIT - press the left mouse button, or SPACE bar on the keyboard while over an icon.

DO - press the right mouse button, or ENTER on the keyboard while over an icon.

Note: users of certain other computers, HIT may be more familiar to you as 'left click' on a mouse, while DO may be more familiar as a right mouse click.

ESC - usually a press of the ESCAPE key on the keyboard. Some mouse systems for thee QL allow the middle button on the mouse to be configured to mimic the ESC key.

The Program Layout

I hope you like red, black and white, because that's the only colour scheme. Although the program works under the GD2 "colour drivers" it only ever uses the standard QL 4 colour mode colours.

The two large black areas bottom left and right are the two file listing windows. These show the filenames on the drive specified in the white strip above each window. The top line contains the main program command icons, while the second and third lines contain icons helping you to specify the drive names and numbers.

+--------------------------------------------------------------------+

| [MOVE] [RESIZE] [SLEEP]   [commands]   [REFRESH] [COPYRIGHT] [ESC] |

|                                                                    |

| [DRIVE NAMES LEFT PANE]            [DRIVE NAMES RIGHT PANE]        |

| [12345678][<-][DATA$][PROG$][T]    [12345678][<-][DATA$][PROG$][T] |

| [DRIVE/DIRECTORY NAME         ]    [DRIVE/DIRECTORY NAME         ] |

|                                                                    |

| +-----------------------------+    +-----------------------------+ |

| |                             |    |                             | |

| |                             |    |                             | |

| |                             | <- |                             | |

| | Left Pane                   |    |                  Right Pane | |

| |                             | -> |                             | |

| |                             |    |                             | |

| |                             |    |                             | |

| +-----------------------------+    +-----------------------------+ |

+--------------------------------------------------------------------+

The above diagram should help explain things a little. Let us start with the six red icons at the top. These are fairly standard pointer environment program control icons.

[MOVE] is the standard pointer environment window move icon - click on the corner to corner box symbol and an icon will appear - move this to where you want the program positioned and click again to 'drop' the program there on screen.

[RESIZE] lets you alter the amount of screen taken up by Q-Trans. It can occupy from about half a standard QL screen up to the height of a 768 pixel high screen. The bigger the display, the more filenames visible, the smaller the display, the less intrusive is Q-Trans. Each time you click on this icon, Q-Trans gets a bit bigger, until it can't make itself any larger so it goes back to minimum size. Alternatively, DO or right click on this icon to pick a size from the menu shown.

[SLEEP] or [Zzz] puts the program to sleep in the QPAC2 button frame if present. You'll see a small button with the name 'QTRANS' in it. To re-awaken this minimised form of the program, just move the on-screen pointer onto the button and DO (right click) on it. This will wake the program ready for use once again.

[REFRESH] The little red and white 'lightning' symbol will redraw the program display if it has been corrupted by another program for example. It will also, where possible, cause a refreshed listing of the files in the drive associated with both windows.

[©] The Copyright symbol icon simply displays a short copyright notice or 'about' screen. Brings up a short screen with author contact details and program version number (the program version number can also be seen when configuring the program).

[X] This is the Exit icon, use this to quit from the program. A short confirmation dialogue box appears, click on Yes or No to indicate your choice of actions.

In between these red and white icons, there's a row of white icons with names prefixed by function key names F1 to F10. Some QL systems only have function keys F1 to F5, in this case F6 is accessed by SHIFT F1, F7 as SHIFT F2 and so on.

F1 - Refresh left pane list of files.

F2 - Select (highlight) all filenames in the left pane.

F3 - Deselect (remove highlight from) all filenames in left pane.

F4 - Sort filenames list in left pane into alphabetical order

F5 - Commands, access the "commands" or "context" menu.

F6 - F10 same as F1 to F5, but apply to right hand pane.

The COMMANDS menu is explained in more detail below. If you have used F4 or F9 to sort a list of files into alphabetical order, the list may be "unsorted" simply by reading the drive again, e.g. by using F1 or F6.

The next line contains a list of the directory device names on your system. The program scans the directory devices list and presents shortcuts for up to 10 directory devices found. On my system, this gives me the list: SUB DOS DEV FLP WIN and RAM. Standard QLs will also have MDV of course. The device names are restricted to 3 characters as is normal QL practice. If longer device names are found, these are truncated to 3 characters for display. A HIT or a DO on one of these drive name icons will drop that device name into the wide white strip below and the program will look for files on this new device.

SUB DOS DEV FLP WIN RAM

1 2 3 4 5 6 7 8   <-   DATA$   PROG$  [Trash icon]

You will notice that the first letter of a drive name is underlined. This keystroke nominally selects that drive name as an alternative to using the mouse, but you may find that having device names starting with the same letter restricts this a little - how is the program meant to know that when you press D that you mean DOS device or do you mean DEV device? In such cases, the first instance of a device name starting with that letter is selected, any other device names starting with the same letter have to be selected with a HIT or a DO using the pointer. Similarly, the icons for the right hand pane may well have to be selected with the mouse, as they duplicate the names for the other window.

Under the device names are icons for drive numbers 1 to 8. These are a quick way of selecting drive number, e.g. changing from FLP1_ to FLP2. Press 1 to 8 to apply these to the left hand pane, or SHIFT 1 to SHIFT 8 for the right hand pane.

In the case of network filenames, a name is assumed (from v0.08 of the program) to be a network name if it starts with a single letter device name, e.g. N32_ or S1_ (S is the Sernet device), in which case the device name shortcuts are handled a little differently. Suppose the window is displaying a list of files on WIN1_. Then you select the N device to access the QL network, and it changes from WIN1_ to N1_WIN1_ and you can press the icons for 1 to 8 to select network station number, say station 6. So it becomes N6_WIN1_. If you then select the FLP device, since it's a network name the FLP is not inserted at the start of the name, it goes after the separator between the network station and drive name, so N6_WIN1_ changes to N6_FLP1_. It sounds difficult, but you should quickly get used to it.

HITting a network filename will stuff the filename into the stuffer buffer, including the network device name and drive name.

(Note: I am not an expert on the QL network, Sernet and Midinet, so I hope I have implemented the network name handling correctly).

The <- symbol is used to go back down a directory level. For example, if the window was listing files on WIN1_EXEC_ and you clicked on the <- symbol, it would go back down to WIN1_, rather like the use of the Toolkit 2 command DUP.

A Hit or Do on the DATA$ icon will cause the window to list files on the DATA default drive, i.e. that set with DATA_USE. You can check the current DATA default setting with the DATAD$ function from BASIC. Likewise, a Hit or Do on the PROG$ icon does the same from the PROG or program default, as set with PROG_USE in BASIC and checked with the PROGD$ function.

A Hit or Do on the little dustbin or trashcan symbol to the right of these displays the content of the Trash directory, useful if you realise you need to restore a file - simply highlight a filename in the Trash directory and use the Untrash command to transfer the file back out of Trash.

A Hit or a Do on the wide white strip containing the drive/directory name will let you edit the name directly. Edit and type in the new name in the normal way and press ENTER. Pressing the '9' key will let you edit the left hand pane's drive/directory name, while '0' will let you do the same for the right hand pane.

The files list windows themselves follow the format of a two letter column at the left showing the file type, followed by the filename itself. An executable (file type 1) program is flagged with the letter E before it, while a directory (file type 255) is indicated by a > symbol before it. S-ROFF (type 2) files are indicated by a letter R. If there are more files than will fit in the black window space, scroll bars will appear, which take the form of a thin bar of green arrows above and below the list of files. Click on these bars to "steer" the list in that direction to see the hidden files. A red box appears to the right of the list, showing where the visible section is relative to the complete list of files, useful for large lists to help you see where you are. With large lists of files, it can sometimes be useful to split the list of files into sections which can be scrolled independently, allowing you to be able to see the start of a long list of files above the end of a long list of files for example. To split the list, DO on the very right of the window in the thin area used by the red scroll box. A further pair of strips of green arrows will appear. To get rid of this, DO on the little white strip which appears alongside the new scroll arrows. They will also disappear if the menu is redrawn, or a if you enter a new directory.

A HIT or a left click on a filename will "highlight" or "select" that filename. Files selected in this way are the ones that the COMMANDS menu will act upon, e.g. highlighted files are the only ones copied from a list. A DO or right click on a filename will both select it and bring up the "commands" or "context" menu, offering you commands to copy, rename, view etc files. The exception to this is when you DO on a directory name (one preceded by a > symbol). This is interpreted as a command to enter that directory, e.g. if the file list contains:

BOOT

E QUILL

> DOCS

A right click on BOOT or QUILL will bring up the commands menu, but a right click on DOCS would cause Q-Trans to try to enter that directory and list the files contained within it.

If a few files are highlighted in a window, clicking on the red left or right arrows between the two panes will cause Q-Trans to try to copy the files between the drives indicated. For example, if the left hand pane is listing files in FLP1_ and the right hand pane is listing files in RAM1_, clicking on the right facing arrow (the bottom one of the two) will cause Q-Trans to copy any highlighted file from FLP1_ to RAM1_. Clicking on the left facing red arrow (the top one of the two) will cause Q-Trans to try to copy any highlighted files from RAM1_ to FLP1_.

When such copying is complete, the program will try to update the files list for both drives.

Each time you HIT a filename (i.e. press SPACE or left mouse button click while the pointer is over a filename), the filename (not the file!) is copied into the Stuffer Buffer. If you then CTRL C to BASIC or to another program and press ALT SPACE (hold down the ALT key and tap the space bar) that filename is "typed into" the other program. Even older programs like Quill can accept filenames passed via the stuffer buffer in this way! This allows Q-Trans to be used as a simple form of pointer driven file selection utility for non-pointered programs, for example.

Note that the filenames listed generally do not include directory names in versions of this program after v0.05, this makes it easier to reliably move or copy files between directories.

Note also that although you can highlight and then copy a directory (e.g. Hit on > DOCS then use the Copy command in the Commands menu to copy it) this is unlikely to be useful as the directory 'file' itself is copied rather than creating the directory on the destination drive. This may be of some use to programmers wishing to copy a directory to examine its content but that's about all. If there is interest and the code can handle it, I may update this in future versions to create a directory on the destination drive. It is not currently possible to highlight a directory and copy all the files contained within it.

Commands Menu

This sub-menu contains a list of commands designed to act on selected files in the appropriate window. It includes the following commands:

+-------------------------------------+

| [MOVE]         ACTION         [ESC] |

+-------------------------------------+

|   Copy        Locate     Trash files|

|  Delete   Make directory  Trashcan  |

|Drive info      Move       Untrash   |

| Execute       Print         View    |

|Files list     Rename     Swap drives|

|  Format     Statistics      Exit    |

+-------------------------------------+

The red icons at the top are the usual double box MOVE symbol to move the menu around if required, and the [X] symbol to exit from this menu. You can also use the Exit command to quit in versions supporting this command.

Copy

This command copies files in exactly the same way as the little red arrow symbols between the two file list windows. A Copy dialogue box appears which gives you a choice of the usual Yes/No/All/Esc options (All causes the program to try to copy all of the files without further input from you unless an error occurs such as a file already exists in which case it will ask for confirmation of whether or not to overwrite it). No will skip the filename shown and go on to the next filename. Yes copies the filename shown. ESC or the [X] icon stops copying and returns to the main program display.

+----------------------------------------------+

| [MOVE]                COPY               [X] |

+----------------------------------------------+

| Copy FLP1_BOOT                       No  Esc |

| To   RAM1_BOOT                       Yes All |

+----------------------------------------------+

The white strip to the right of the word TO specifies the name to which this file will be copied. If you click on this box or press T you can alter the filename if required. This can be useful when you wish to make a duplicate of a file on the same drive, for example, as you might with the equivalent COPY FLP1_FILE1 TO FLP1_FILE1_backup command in BASIC for example.

Please note that although versions of Q-Trans later than v0.05 attempt to take directory names into account when copying or moving files between sub-directories, this may not work very well on substitution or alias directory devices such as DEV or SUB where you may need to manually rename files if Q-Trans becomes confused about "hidden" directory names (e.g. if you are in the habit of, say, setting DEV1_ to be equivalent to WIN1_QUILL_ for example in order to get floppy based software to run from directories on hard disks).

A suggestion to improve reliability when using DEV or SUB or other similar devices is to watch out in case part of the substituted names appear in the F2 or F3 directory window. For example, if DEV1_ is set to be WIN1_QUILL_ but the F2 window shows DEV1_QUILL_, you may get problems because DEV1_QUILL_ is really DEV1_QUILL_QUILL_ ! You can tie yourself up with complex DEV and SUB definitions, so try to use the 'real' names whenever possible. A hint on how to work around this is to navigate back to the 'root', i.e. if the above exaple shows DEV1_QUILL_, use the <- button to go back down to DEV1_ then wade back through the directories. If you start from the 'root' of a DEV or SUB definition and work your way up the directories you may well find it does sometimes work. While writing this program, I anticipated problems handling DEV and SUB names. It is best to expect them to fail in a Q-Trans context, but they do sometimes work rather better than I had originally thought even though it takes a bit of getting used to what Q-Trans can handle and can't handle.

Delete

This command deletes selected files from the drive specified. A 4 choice menu appears, as king if you want to delete the named file. You have four choices - the usual Yes, No, All or Esc.

+---------------------------------+

| [MOVE]        DELETE        [X] |

+---------------------------------+

| Delete ram1_BOOT                |

|                                 |

| [Yes]    [No]    [All]    [ESC] |

+---------------------------------+

Drive information

+-----------------------------------------------+

| [MOVE]        DRIVE INFORMATION        [MOVE] |

+-----------------------------------------------+

|                                               |

| +-------------------------------------------+ |

| |Drive   :FLP1_                             | |

| |Name    :test_disk QDOS HD                 | |

| |Capacity:528/2880                          | |

| |Files   :90                                | |

| +-------------------------------------------+ |

|                                               |

|                    [  OK  ]                   |

+-----------------------------------------------+

Shows how many files are on a drive, along with the medium name and capacity figures, like a DIR command. If a DV3 filing system (able to read MSDOS disks) it may also show if the disk is QDOS or MSDOS format.

Execute

Start an executable program or job. There are several options you can specify, such as sending an option command string to the program, and the usual Psion, Guardian, Unlock, Freeze and Impure options. Multiple programs can be executed if selected. If you have File Info II installed on your system, you can even execute files such as text files, since File Info II allows you to associate programs with certain types of files, meaning that if the text file is executed, the program associated with it is started and loads the file in question. The normal situation of course is that a single program is executed with none of these options enabled.

+--------------------------------------------------+

| [MOVE]            EXECUTE OPTIONS            [X] |

+--------------------------------------------------+

| Program:                                         |

| ram1_sample_txt                                  |

|                                                  |

| Command string:                                  |

| [                                              ] |

|                                                  |

| Control options:                                 |

| [Psion KB] [Guardian] [Unlock] [Freeze] [Impure] |

|--------------------------------------------------|

| [Yes,execute this file] [  No, skip this file  ] |

+--------------------------------------------------+

The Command String is passed to the program executed. Some programs use this command string to load a file as they start up or to specify some default settings for example. I use the S_Edit program as a general text editor and frequently pass the filename of a text file to be edited in this way from BASIC:

EX WIN1_S_Edit_obj;"FLP1_README_TXT"

The command string is in effect the same as such a command from BASIC.

The other options are similar to those you would use in hotkey or EXEP commands from BASIC.

The Psion KB option is for use with programs like Quill which tend to grab all available memory for themselves when they start up. This option lets you specify how many kilobytes of memory they are to be allowed when starting. For Quill, 32KB will suffice for small files, while larger amounts of memory may be needed for large documents.

The Guardian option sets up a guardian screen around the windows of a program which tends to cause chaos for the pointer environment by altering the size of its own windows frequently. Using a Guardian window will ensure that a consistent area of the display (usually the whole display) is saved to prevent the endless chaos caused by partly overwritten displays and so on.

Unlock is an option to allow programs to continue writing to the screen even if you CTRL C out of them or bury their windows with another program. A good example might be one of those little clock programs which needs to write the time and date to the screen even if it overwrites part of the display of another program. Using Unlock will allow that program to continue working.

The Freeze option is useful in exactly the opposite circumstances. If you have a program which writes direct to the display and does not stop when you CTRL C out of it or bury it with the display of another program, this option can be used to force freeze a program when necessary.

Impure. This specifies that a program is Impure, i.e. its code may modify itself. Since you cannot run several instances of a program written in self modifying code (old Turbo compiled programs may be an example of this), this option will help the QL to organise things accordingly.

The bottom two buttons are simply to let you say Yes-I really do want to execute this program now, or simply No it was all a mistake, don't execute this program. Once you have specified any options for the program to execute, you would normally click on Yes to execute the program shown.

Files List

This command lets you print a list of files on the drive/directory specified. One filename per line, with optional form feed after the last filename to ensure that the last page is ejected.

+------------------------------------------+

| [MOVE]           FILES LIST          [X] |

+------------------------------------------+

| List files to   : PAR                    |

| Form feed at end: Yes                    |

|                                          |

|               [  OK  ]                   |

+------------------------------------------+

Press F or click on the 'Form feed' box to alter this option - it will simply toggle between Yes and No.

Press L or click on the 'List files to' box to change where to print to - normally you would enter SER1, SER2 or PAR here, depending on which port your printer is connected to.

Finally, click on 'OK' to start printing the list. Note that only filenames selected or highlighted are actually printed.

Format

This command formats a disk or ramdisk. All you need to do is to enter the medium name then click on the 'OK' button to start the formatting operation.

+-----------------------------------------+

| [MOVE]            FORMAT            [X] |

+-----------------------------------------+

|   Enter medium name to format below,    |

| then [OK] to format, or ESC to abandon. |

|                                         |

| NAME: [                               ] |

|                                         |

|                   [ OK ]                |

+-----------------------------------------+

The name entered should include the drive name and any extra parameters required with the name. For floppy disks, *D, *H and *E are allowed to specify disk density to format if supported by your disk interface. For ramdisks, a number after the drive will indicate the number of sectors to formata static ramdisk. In essence, the name entered is just like the name you'd specify in a FORMAT command in BASIC. Note that as far as hard disk systems are concerned, you may need extra commands entered from BASIC, e.g. WIN_DRIVE or other specialised hard disk control commands.

Locate

Locate is a command which allows you to search for test within either the body of a file or within a filename. It pauses each time you have found a matching file, to give you the opportunity to view the file (since it's likely that most files searched will be test files).

+---------------------------------------------------------+

| [MOVE]                    LOCATE                    [X] |

+---------------------------------------------------------+

|                                                         |

| Search location:     [                                ] |

| Filenames containing:[                                ] |

| Containing text:     [                                ] |

| Searching in:                                           |

| Found in:            [                                ] |

|                                                         |

|                                                         |

| [    Locate    ]  [   View file   ]  [Use File Info 2]  |

+---------------------------------------------------------+

The search location is always the drive name specified for the window from which the command was activated. This cannot be altered in the Locate command itself.

Beneath the Search Location are two boxes into which you can enter the text to be searched for. If you know part of the filename, you can enter a vague filename in the 'Filenames containing' box. If one of the selected filenames contains this text in the filename, it will be shown in the 'Found in' box. A simple example: you know that the filename had a letter Z in it, so if you enter the Z into the 'Filenames containing' box, any filename containing a letter Z will be listed. The search is not case sensitive - Z or z will be found.

If you knew that the file itself contained the word "sprite" somewhere in the text, you could enter this word into the 'Containing text' box. Q-Trans will then scan through the selected files searching for this text. Any file found containing this text will have its filename shown in the 'Found in' box.

Note: the files are loaded into memory for searching if there is enough free memory. If not, short parts of the file are loaded at a time and scanned for the text. This makes searches a bit slower if free memory is in short supply.

Once a file has been located, you have the option to view it. If the file is a plain text file the internal file viewer may prove adequate. For more advanced users who have File Info 2 installed, an additional viewing option is available to use the file association facility to launch a suitable viewer as configured in File Info 2. For example, with File Info 2, it is possible to configure it to launch Quill to view DOC files and so on. This may also be useful for graphics files.

If you do not have File Info 2 installed on your system, this item will not be selectable.

Make Directory

This command is equivalent to the MAKE_DIR command in BASIC. On level 2 and higher filing systems it allows you to create a directory with a given name.

+------------------------------------------+

| [MOVE]        MAKE DIRECTORY         [X] |

+------------------------------------------+

|                                          |

| In this location:                        |

| [FLP1_                                 ] |

|                                          |

| Create a directory called:               |

| [                                      ] |

|                                          |

+------------------------------------------+

The menu contains the usual Move and Exit icons at the top. The next box down lets you specify the drive/directory in which to create the new directory. This box defaults to the current drive/directory for the window pane from which the command was activated. Simply HIT or DO on this box or press the "i" key to edit what is shown here.

HIT or DO on the bottom box, or press the "C" key to enter a new directory name. When you press ENTER, Q-Trans tries to create that directory name. If it already exists, or there is any other error, an error message is displayed - click on OK in this error message window and you return to the directory creation screen to try again. There is no overwrite option when creating directories.

Move

This command lets you move a file from one drive/directory to another. It is very similar to copying, but the original file is removed. In other words, it's like a COPY with an option to change the filename and followed by a DELETE. The main difference between this and a RENAME is that RENAME can only change the name of a file, it cannot send the file from one location to another. By default, the source and destination drives for the Move operation are determined by the drive/directory settings for the two panes.

+-------------------------------------------------+

| [MOVE]               MOVE                   [X] |

+-------------------------------------------------+

|                                                 |

| MOVE  [FLP1_README_doc           ]  [No ] [Esc] |

|                                                 |

| To    [RAM1_README_doc           ]  [Yes] [All] |

|                                                 |

+-------------------------------------------------+

As with Copy, you have the usual No/Yes/All/Esc options to specify whether to just move the file shown or to move all remaining selected files automatically without further input from you. Press ESC or E to stop at this point.

Click on the white To box to modify the destination filename if required.

Note: the same cautions concerning the renaming of files or moving files between sub-directories applies as with the Copy command described above.

Print

Lets you print a hard copy of the file. Only supports plain text files. The files selected in the window from which the command was activated are printed.

+------------------------------------------------+

| [MOVE]                PRINT                [X] |

+------------------------------------------------+

| Print files to  : [SER1                      ] |

| Form feed at end: [Yes]                        |

| Pause in between: [Yes]                        |

|                                                |

|                    [  OK  ]                    |

+------------------------------------------------+

You can specify where to print the file to (normally a printer on the PAR or SER1 ports). Just click on the white box holding the name and edit it in the usual way.

The Form Feed At End option ensures that the last page is ejected when each file has been printed - this helps to ensure that all files are on separate pages for example. If required, you can tell the program to pause between each file printed, e.g. if you want to be able to load different paper for some files.

Rename

Allows you to change the name of a file. All you have to do is to enter the new name of the file - multiple files can be renamed, just select or highlight as many filenames as need be renamed and step through them one at a time.

+-----------------------------------------------+

| Rename  FLP1_README_ASC                       |

| To     [FLP1_README_TXT                     ] |

+-----------------------------------------------+

Just type the new name into the bottom box and press ENTER. If you wish to abort the rename you can press ESC. If the name in the bottom box is the same as the one in the top box there is obviously no need to rename and to prevent an error none is attempted.

Statistics

This command allows the display of rudimentary file statistics for selected files. It brings up a small menu with filename, file type, dataspace, file length, update date, backup date and file extra information (as you'd get with the FXTRA extension of Toolkit 2 for example.

+-----------------------------------------------+

| [Move]         [FILE STATISTICS]        [Esc] |

+-----------------------------------------------+

| +-------------------------------------------+ |

| | Filename       :WIN1_MyBoot               | |

| | File type      :Data                      | |

| | Dataspace      :0                         | |

| | File length    :285                       | |

| | Update date    :2003 Jan 04 17:35:25      | |

| | Backup date    :1961 Jan 01 00:00:00      | |

| | File extra info:0                         | |

| +-------------------------------------------+ |

|      [Previous]               [  Next  ]      |

+-----------------------------------------------+

The 'Previous' and 'Next' icons let you step through the selected files one at a time.

Swap drives

This command simply swaps the lists of files in both windows over. Someone asked for this to be added to v1.01, I'm not sure why!

Trash

From version 0.10, Q-Trans includes a rudimentary Trash can facility, which allows a degree of restorable deletion of files. It is not a true 'undelete' or 'recycle' facility as found on other computer systems and facilities are limited. Basically, a special folder is created on your hard disk and, using the Trash command, files are selectively moved into this folder rather than being deleted as such. If you later realise you have made an error in deleting a file and wish to restore it, simply enter the Trash directory and copy the file back out. If the Trash starts to take up too much space, you can of course remove any number of files to free up space, but files erased from the Trash cannot of course be recovered later. It is best to give the Trash directory a short and uncommon name such as WIN1_*_ to reduce problems with filenames exceeding the QL filename length limit and being truncated. A single Trash directory serves all devices, so anything Trashed from floppy, ramdisk, over the network or from the hard disk will all end up in the same place, there is no support for separate Trash facilities on each device. Since files from all devices can end up in the Trash can, it may become hard to know where the files came from, so there is the facility to create short 'info' files in the Trash can to store the details of where the file came from. These info files are called '_t' files, so-called because their names are derived ffrom the source filename by adding _t to that filename, truncating if necessary to staywithin the QL filing system name length limits. So if the Trash is WIN1_*_ and you delete FLP1_letter_doc, it goes in the Trash can as WIN1_*_letter_doc, and a small file called WIN1_*_letter_doc_t is created, which stores the original path name 'FLP1_letter_doc'. QL filename length limits mean that files moved into Trash may get their names truncated to within QDOS/SMSQ filename length limits.

To Trash a file, simply highlight the file to be Trashed, then from the commands menu, select the Trash command, which works in the same way as the Delete equivalent.

Trash can

If the window from which the command is chosen is displaying the content of the Trash can, this Trash can options menu is available. From this you can see how many files are in the Trash can and their total lengths. There are 4 options for deleting files from the Trash can, to free up space on the drive concerned. When the menu is first shown, Q-Trans checks the total size of files in the Trash can, so if there are a large number of files in the Trash can, it might display a "please wait" message while it reads the details.

+-----------------------------------------------------+

| [Move]               [TRASHCAN]               [Esc] |

+-----------------------------------------------------+

| +-------------------------------------------------+ |

| |Trash can directory is      : WIN1_*_            | |

| |Number of files in Trash    : 486                | |

| |Total size of Trashed files : 1.507302E6         | |

| +-------------------------------------------------+ |

|            [  Empty entire Trash can  ]           | |

| Remove files older than [     ] days from Trash can |

|   Delete files Trashed [     ] or more days ago     |

|   Erase files larger than [     ] KB in Trash can   |

+-----------------------------------------------------+

The first command is easy enough, clicking on [Empty entire Trash can] simply erases all files from the Trash can. If you have just a backup of your entire hard disk, for example, or it is some time since you last deleted anything and feel that nothing could possibly need to be undeleted or untrashed, or quite simply you are running out of space on that drive, you may find this command useful, if drastic.

The other three commands are selective deletes for the Trash can content. They zap files which are older than a given number of days, or zap files trashed more than a given number of days ago, or simply remove larger files (size more than a stated number of kilobytes in length). Simply click on the box to enter the number of days or kilobytes, press ENTER and the selective delete will begin. Afterwards it will show how many files were deleted. Selective deletes from the Trash can are slower than normal deletes.

Please note the differences between the second and third options. The first is that files OLDER THAN x days are deleted, while files trashed x OR MORE days ago are deleted. A fuller description of the Trash can mechanism is given below.

Untrash

With this command, files which have already been Trashed can be restored to their original selves, provided they were (a) placed in the Trash can rather than deleted as such, and (b) they have not already been removed from the Trash can. Untrashing a file removes both the file and its associated _t file from the Trash can, so once Untrashed, you cannot Untrash again unless the file is Trashed again. In fact, there is no magic status to the Trash can, you could COPY or MOVE a file to the Trash can directory using BASIC or another file handling program, just that if no _t file is created, the program does not have the necessary information about where the file came from.

+-----------------------------------------+

| [Move]          UNTRASH           [Esc] |

+-----------------------------------------+

|           Trash is WIN1_*_              |

| Untrash selected files to current path  |

| Untrash selected files to original path |

+-----------------------------------------+

The first option simply untrashes files to the location shown in the other window of Q-Trans and ignores the information about where the file originally came from. The second uses the path restore information, so that if the file Trashed was called LETTER_DOC and it came from a directory called WIN1_QUILL_ it would offer to restore the file as WIN1_QUILL_LETTER_DOC. If it cannot find the path restore information (there is no matching _t file or it has been accidentally deleted from the Trash can) the program will offer to Untrash to the current DATA default instead, although you can manually edit filenames when untrashing anyway. So if you ask to untrash a file called LETTER_DOC and its LETTER_DOC_T file is not present for some reason, it will offer to Untrash LETTER_DOC To LETTER_DOC instead, and you can add the drive/directory name yourself if you wish.

View

This command lets you view a file or selected files on screen. For plain text files, the internal text viewer will probably suffice, while for other files it is possible to start the file via its associated File Info 2 program setting, when File Info 2 is installed and available.

+------------------------+

| [MOVE]  VIEW WITH  [X] |

+------------------------+

|    Internal viewer     |

|    via File Info 2     |

+------------------------+

HIT or DO on the option you require. If you select the File Info 2 option, Q-Trans tries to call the associated program for the file in question. For example, most File Info 2 users have it set up to load Quill to load DOC files. Be careful if using File Info 2 and several files have been selected - you might end up with on-screen chaos if several associated programs have to be started one after the other!

The internal viewer is a simple to use file viewer which lets you scroll up and down through a file and step back and forward between the files selected.

+--------------------------------------------------------------------+

|[MOVE][TOP][UP][PAGE UP][<<]  VIEW  [>>][PAGE DOWN][DOWN][BOTTOM][X]|

+--------------------------------------------------------------------+

| Text is displayed                                               |  |

| in this window                                                  |  |

| as many lines of text                                           |  |

| as will fit!                                                    |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

|                                                                 |  |

+--------------------------------------------------------------------+

The MOVE icon is the usual one allowing the window to be moved anywhere within the Q-Trans outline. the X icon quits and returns you to the main screen.

The Top icon (a vertical arrow with a bar across it) takes you to the start of the file. The Bottom icon (downward arrow with bar beneath it) takes you to the bottom of the file. The up and down arrows scroll up or down one line at a time. The double arrows scroll up or down by a screenful at a time. The double left and right arrows take you to the previous file selected if there is one, or to the next file selected.

The narrow window on the right is a position indicator. It shows how far through the file you currently are. You can click on this to move to a given point if you wish - the full length of the window indicates the complete file, while the red box or bar in the window indicates the visible section - this is a bit imprecise for small files.

If you click on the text in the viewing window itself, various actions are possible depending on whether it was a Hit or Do, and whether it was in the top half or bottom half of the window.

Hit in top half - text scrolls up one line

Hit in bottom half - text scrolls down one line

Do in top half - text scrolls up by one screenful

Do in bottom half - text scrolls down by one screenful.

If you hold your finger on a mouse button while the pointer is in this window, the text will continue scrolling. Indeed, if you move the pointer up and down past the mid-point, the text can be made to 'rock and roll' up and down. This may prove useful for browsing if scanning through a file for certain text.

Exit

Quit from the program.

NOTES ON THE TRASH CAN

The following notes are included in case anyone else would like to implement a compatible system for 'Trashing' files in their own programs.

The Trash can is a normal QL directory. It is a 'one for all' solution, the same Trash can is used for all drives. There is no separate Trash can for each drive.

When a file is Trashed, the following actions take place:

1. The file is copied into the Trash directory.

2. The update date of the original file is read and copied into the header of the file in the Trash can. Thus the file in the Trash can retains the same update date as the original file. This is stored at offset 52 (decimal) in the file header.

3. The date at which the file was Trashed is stored in the BACKUP long word in the file header (decimal offset 60).

4. A file called 'filename'&'_t' is created (name limited to 39 characters if required to stay within the limit of 5 character drive name and 36 character filename) and always has '_t' appended. This contains the full drive+directory+filename of the original file.

5. The original file is finally deleted.

The system is pretty rudimentary but has served me reasonably well since I first implemented it. It does mean the programmer has to handle filename length limitations and the special cases such as when the _t file is missing or a file has been manually copied into the Trash can directory (BEWARE of using the selective delete from Trashcan if you suspect files may have been placed there by another program as the dates stored in the file header may not be as expected!)

VERSION HISTORY

0.04

- First Beta test release.

0.05

- Second Beta test release, November 2002, contained more bugs than the first, especially when copying files between sub-directories.

0.06

- 20th December 2002. Improved copying and moving of files between sub-directories, if this version is stable it might become the first non-Beta release. Added my new email address. Filenames displayed in the files list panes are now 'pure' filenames, not including directory names where possible. This makes it easier to handle cases where files are being moved or copied between directories and even allows a degree of operation with DEV AND SUB.

0.07

- 11th January 2003. Colour scheme now changed to be consistent with Launchpad. Some colour inconsistencies under GD2 ironed out (green becoming cyan, etc). MOVE a file, menu used to say 'Copy' filename to, QTrans now says 'Move' filename to... Directory name problems with DOS device on QPC2 up to v3.03 tackled with limited improvement (FNAME$ on open directory channel gives different results with DOS device compared to other devices) - QPC2's author says this will be addressed in a future release of QPC2 (possibly QPC2 v3.04). Under older versions of QPC2, an access to a DOS device immediately goes to a root directory - in v0.06 changing from say WIN1_QUILL_ to DOS1_QUILL_ may have resulted in errors with name lengths due to the different way in which FNAME$ worked.

Different appearance in QL screen sized menu of directory devices list if less than 10 devices now fixed.

Viewing just last file in a list of files via File Info 2 association no longer causes attempts at multiple viewing of same file until an error occurs.

0.08

- 15th January 2003. Filename placed in stuffer buffer now corrected (directory name missing in v0.07)

Network timeout error message if issued at all (e.g. by Sernet) should now appear in F2 or F3 window as appropriate, no longer randomly overwriting the menu.

Attempt at better handling of network names in F2+F3 windows, after request by Jon Dent.

Change made to RENAME command to address possible problems on non-SMSQ/E systems.

Small change to DOS device handling to help Windows 98SE users.

0.09

- 18th January 2003. Parameter coercion problem in MITEM statement affecting RENAME command fixed.

0.10

- 19th January 2003. Trash can facility added.

Configuration block updated for Trashcan.

No need to configure maximum number of files per list any more, as Q-Trans now does a two pass read of files to generate a dynamic list. Especially useful when dealing with Trash can.

1.00

- 8th February 2003. Trash can upgraded to allow Untrash and date dependent operations, better handling of 'restore original path' untrashing thanks to use of _t files, files can now be restored with original update dates, Trashcan options menu now shows number of Trashed files and total size of those files.

File statistics facility added. Configuration block updated for new facilities.

1.01

- 13th February 2003. Drive Information command added to Commands menu. Swap Drives command added to Commands menu. Layout of commands menu changed to 3 columns to accommodate new commands in smallest possible Q-Trans display height.

Incorrect colours for messages during formatting now fixed.

Move menu heading now centered like Copy.

Esc option when prompted to overwrite during Copy, Move or Untrash fixed - did not work on some systems before.

1.02

- 16th February 2003. Status of [OK] loose item after formatting a medium now reset correctly.

1.03

- 20th February 2003. Corruption occurred in configuration block if string items were configured to become longer than as supplied. Now fixed.

1.04

- 13th November 2003. Switching from a sub-directory on WIN1_ to non-existent directory on DOS1_ by using the 'DOS' device icon causes name length errors, due to differetn way in which SBASIC FNAME$ works with DOS device on QPC2. Now, to work around this, Q-Trans always goes to the root of DOS1_ to avoid getting trapped in a non-existent directory.

Author: Dilwyn Jones

Email : dilwyn.jones@tesco.net

Table of Contents

Introduction

Credits

System Requirements

Backup

Configuring The Software

1. Sound Prompts Off Or On.

2. Default Left Pane Drive/Directory.

3. Default Right Pane Drive/Directory.

4. Specify Printer Output Device.

5. Print Formfeed After Printouts.

6. Pause Between Files Printed.

7. Specify Initial Display Height.

8. Drive/directory name for Trash can

9. Trash can mode of operation

Starting Q-Trans.

Mouse Terminology

The Program Layout

Commands Menu

Copy

Delete

Drive information

Execute

Files List

Format

Locate

Make Directory

Move

Print

Rename

Statistics

Swap drives

Trash

Trash can

Untrash

View

Exit

NOTES ON THE TRASH CAN

VERSION HISTORY