From pro-carolina!delton@cbbs.scsn.net Tue Feb 3 14:41:01 1998 Date: Tue, 3 Feb 98 06:20:31 EST From: pro-carolina!delton@cbbs.scsn.net To: delton@cbbs.scsn.net Subject: "ecp8.doc.shack" file _______________________________________________________________________________ Documentation for ECP8 modifications by Randy Shackelford - June 12, 1989 This program is very well documented by the ECP8 User's Guide and the Technical Reference Manual. None of that information is repeated here, except as pertains to modifications made. Major modifications The most apparent modification is seen as soon as the program is run. Instead of displaying the program title, version number, and copyright notice, the screen is clear except for the prompt and the cursor. Instead of a colon, the prompt consists of the last directory name in the prefix path, followed by a space and a percent sign. So, for example, if the prefix is /RAM5, the prompt will look like this: RAM5 % or, if the prefix is /VOL/DIR/ECP8, the prompt will look like this: ECP8 % The prompt is changed automatically each time the prefix is changed so that the last directory name in the prefix is the name shown. A null prefix causes the prompt to consist only of a space and a percent sign. When the display is forty columns, the name does not appear in the prompt. This is for the sake of saving screen space. A flag located at $2038 determines whether the name is displayed in the prompt. If the value of $2038 is less than 128, the path is displayed; if the value is 128 or higher it is not. The included SET batch program may be used to manipulate this flag. The prefix is always set to ECP8's root directory upon program entry or when ctrl-reset is pressed. Formerly, the full prefix path was displayed when the prefix is changed by the \ or * commands or by typing a new path. This is rendered superfluous by the new prompt, so this feature was taken out. The PREFIX command may be used to display the full prefix path. Several routines were completely rewritten. Here is a list of these routines, along with the improvements or new features introduced: CATALOG: This routine was rewritten entirely from scratch. Instead of display- ing a plus sign if a file's backup bit is set, along with an asterisk if the file is locked, the routine displays the file's access attri- butes with the letters DNBWR, respectively representing the file's delete, rename, backup bit, write, and read status. This is the format used in the ORCA/M shell catalog command. The file length and aux type columns have been switched in the display. Sample 80 column directory display: /VOL/DIR Name Type Blocks Access Modified Length Aux FILE1 BAS 3 DNBWR 10-JUN-89 00:00 $00025B $0801 FILE2 SYS 1 B R 04-FEB-88 13:05 $00008E $2000 Blocks free: 5 Blocks used: 275 Total blocks: 280 A 40 column display is the same, except the modified date, length, aux type, and total blocks are not shown. The routine also supports invisible files - a user-modifiable flag located at $2039 determines how the routine treats these files. If the location contains 0, invisible files are not displayed. If the location contains 1, the routine displays the files, and displays an I along with the other access attributes. The flag location should only contain 0 or 1; any other value will cause the catalog display to mess up. The flag may be manipulated with the included SET batch program, and the default flag setting can be changed using the PATCH transient command. Files may have their invisible bits set or cleared using the built in ENABLE and DISABLE commands, discussed later. The original catalog routine used a file read to read the first directory block, then used block reads for subsequent blocks. The new routine, on the other hand, uses the latest Apple-approved method for listing a directory. That is, it uses only file reads, and ignores the file count in the directory header, reading the directory until the end is reached. This SHOULD make the routine completely network-friendly, but it has not been tested. The routine uses the value at $2037 to determine which file type to display. If this location contains zero, all types are displayed. A nonzero value will cause the routine to display files whose type matches the value at this location. LOCK/UNLOCK: for the sake of compatibility with existing transient programs, there are still MLI calls to lock and unlock a file. These com- mands are no longer available from the keyboard, however. Instead, there are two new commands, called ENABLE and DISABLE, which may be used to manipulate any or all of a file's access bits. Example: ENABLE |D|N|B|W|R|I| files As with most commands, more than one filename can be given to the command. Each file has the specified access bits enabled. There is a complementary DISABLE command for disabling access bits. Its syntax is identical to that of the ENABLE command. Unlike similar commands, e.g. the disable command in the ORCA/M shell, this command will disable the backup bit. Others will ac- cept a DISABLE B command, but it has no effect. These commands are not available in the MLI. BUZZ: This is the routine which is called when ctrl-g is output, instead of the routine which beeps the speaker. The former version of this routine would make a buzz sound on a 1 mhz machine and on a IIgs at normal speed and a bip sound on a IIgs at fast speed. The new routine makes the same sound on a IIgs regardless of the speed setting. ONLINE: This routine was completely rewritten. The most important change is that the routine no longer goes through the device list twice. Formerly, each device was accessed to see if it contains a ProDOS volume, then every device with a volume was accessed to get the create date, kilobytes free, and kilobytes used. The new routine accesses each device, and if a ProDOS volume is found, this information is read and displayed before the routine checks the next device. Thus, these two operations appear as one access to each device. The syntax for this command has been revised. The old routine would take slot and drive parameters in the following way: online s6 d1 This would display the information for the volume in the specified device. A slot could be specified without a drive with the following syntax: online s6 But this would display info for the same device as the previous example. In the new routine, if slot and drive arguments are given for the command, that device is checked. If only a slot is specified, both devices in that slot are polled and displayed. Of course, it is possible for a slot to contain only one device; in that instance, only the valid device is displayed. For instance, if there is a RAM disk in slot 3, drive 2 and slot 3 is specified, no drive 1 device will be displayed. If a slot containing no devices is specified, nothing will be displayed. The s and d may be omitted from arguments. This means that online s6 d1 and online 6 1 are equivalent. On a 40 column display, only the volume names and their locations are shown by this command. Lesser enhancements CLEAR: There is now a built-in command to clear the screen. This command causes a jump to the firmware routine at $FC58. HELP: This command is no longer built in. For those who wish to have a help command, a transient command has been supplied. COPY: This command can now take a DIR file as the second argument. This means that the destination path can be a path for the file or it can specify a directory into which to copy the file. For instance, copy /vol1/dir/file /vol2/dir and copy /vol1/dir/file /vol2/dir/file do the same thing. One anomalous feature was removed from the command. The former version allowed the first path to be a directory. This allowed the following to be acceptable: copy /vol1 /vol2/dirfile This would copy the volume directory of vol1 to a DIR file on vol2. The new routine prevents this by not allowing the first path to be a directory. OUTPUT: This command no longer requires a full path. This renders feasible the following small yet powerful batch program: output &3 ctrlp &1 &2 ctrlp If this program is placed in a file called FILE, then, for instance, it is possible to do a hex/ascii dump of one file into another file with the following: file xdump infile outfile Or, one can convert an AWP file to a text file with the following: file view awpfile txtfile MON: When the MON command is used to pass a command to the system monitor, a carriage return is output after the monitor command has finished executing. QUIT: The 16 bit operating systems on the IIgs add a special provision to the ProDOS 8 quit call. When the 16 bit quit dispatcher is active, a ProDOS 8 quit call may specify a path to quit to. If this path is provided, the application corresponding to the path is executed when the application issuing the call quits. If this call is made with no path, the last application user id is pulled off a stack and control returns to that application. Formerly, ECP8 could accept a path to quit to and issue an extended quit call with that path. However, no provision was made to issue an extended quit call with no path - if QUIT is entered with no path, a standard quit call is made. The following command allows an extended quit call with a null path: QUIT ~ Since the extended quit call does not exist unless the 16 bit quit dispatcher is present, i.e. ProDOS 8 was launched from a 16 bit operating system, an extended quit call acts exactly as a standard quit call if the 16 bit quit dispatcher is unavailable. For this reason, QUIT ~ has the same effect as QUIT if the system was not booted with a 16 bit operating system. This syntax is ignored on 8 bit II's, on which the extended quit call is never available. When the user attempts to launch a IIgs application, ECP8 first checks the value of OS_BOOT ($E100BD). This location is set according to whether the IIgs was booted with ProDOS 8 or a 16 bit operating system. If the machine was booted with ProDOS 8, IIgs applications cannot be launched, and ECP8 returns BAD FILE TYPE, as it always does when a IIgs application is specified on an 8 bit machine. The cursor has been changed from an underline to a block style cursor. Formerly, the program title, version number, and copyright information appeared each time the program was started up, the display was changed from 40 to 80 columns or from 80 to 40 columns, or when reset was pressed, or when ctrl-y was used to return from the monitor. This is no longer the case; the only time this information is displayed is when a new built in command called VERSION is used. This command is not available in the MLI. _______________________________________________________________________________ Documentation for new ECP8 transient commands BLANK: This command is a screen blanker. It works only on an enhanced //e, a //c, or a IIgs. It works properly in all three of the text modes on these machines - 80 column, 40 column, and 40 column with the 80 column firmware active. The DA menu is inaccessible on the IIgs because interrupts are disabled while the screen is blank. This is done because if the DA menu is entered and exited while BLANK is running, the default screen colors will be restored, and it will appear that the machine is locked up while BLANK is waiting for a keypress. CLOCK: This command only works on the IIgs. It reads the machine's built in clock and displays the day of the week, the month, the day, the year, and the time in AM/PM format. Its display looks something like this: Friday, June 23, 1989 10:45:23 AM CHAUX: This command is an analogue to the CHTYPE command supplied with ECP8. As one might guess, its purpose is to change the aux type of files. Its syntax is similar to that of CHTYPE: chaux file xxxx File is the path of the file to change, and xxxx is a 4 digit hex number. If the type is not an acceptable 4 digit hex number, it is rejected. COMPARE: This command is used to compare the contents of files. It is invoked with two pathnames as arguments. The command opens and reads the files and does a byte by byte comparison of their data. If any bytes are different, the command reports that the files have different data. If the files match byte for byte, the command reports that the files are identical. By default, COMPARE only examines the data in the files. On the other hand, if the -I option is specified, COMPARE will examine the files' types, access bits, aux types, and modified dates. HELP: This transient command replaces the built in help command, which has been removed. Its syntax and operation are similar to the former command. The difference is that the directory in which the help files reside must be named HELP. (that's HELP with a dot.) This is because since help is no longer built in, if the prefix is the root directory and HELP is used, it will cause ECP8 to set the prefix to the HELP directory instead of invoking HELP. Placing a dot in the help directory file name gets around this problem. HELP only works in 80 columns. IIS: If you have 3.5" drives or a hard disk along with your 5.25" drives, and all your 5.25" drives do for you is grunt when programs poll every device, this command is for you. This command is used to disconnect these drives, and can reconnect them, too. To disconnect the 5.25's (or Disk II's, as they are referred to by the command), you issue this command: iis -d The following command will reconnect the Disk II's: iis -e If you forget whether they are connected or disconnected, use this command: iis -s If you forget what the options are, IIS has a built in help function, invoked by the following command: iis -h This command uses some sort-of unused space in the system global page. The memory it uses is at $bf40-$bf42, which normally contains part of the following ASCII string: (C)APPLE'83 This string is placed there during the ProDOS boot process; it is stored in positive ASCII. When the Disk II's are connected, this is the case. When the IIS command disconnects them, the following happens: 1. The Disk II unit numbers are removed from the device list. 2. The low byte of the Disk II driver vector is placed in the memory location where the "(" in the ASCII string is stored, and the high byte is stored in the location where the ")" in the string is stored. 3. The "C" in the ASCII string is changed to negative ASCII, and serves as a flag to denote that the Disk II's are disabled. 4. The address contained in the slot 0, drive 1 device driver vector, which always points to the NO DEVICE CONNECTED routine in ProDOS, is copied into the slot 6 driver vector locations. This command uses a feature present in ProDOS 8 versions 1.2 and up, and should not be used with previous versions. After disconnecting the drives, it does an online call to both devices. The object of this is to remove from the volume control block the volume names of any 5.25" disks previously online. This insures that no volume names which can no longer be accessed remain in the VCB, allowing all eight VCB entries to be used. When the Disk II's are reenabled, the reverse happens - the slot 6 driver vectors are restored, the ASCII string is changed back to its original state, and the Disk II unit numbers are placed in the device list. They are always placed in the list so that the Disk II's will be the last devices in volume search order. Thus, the Disk II's may be placed last in volume search order if they are not already by disconnecting and reconnecting them. WARNING: This command should NOT be used if slot 6 contains anything other than a 5.25 drive controller card. (At least 95% of II users have their 5.25's connected to this slot.) It cannot work with 5.25 drives in any other slot. INFO: This command is an alternative to the INFO command supplied with ECP8. It provides relevant information about specified files within the context of the type of file. If a normal file is specified, the command will return the file's type, aux type, length, blocks used, storage type, and the modified/created dates. If a directory file is specified, the length is not shown, and the directory's file count is shown instead. If a volume directory is specified, the aux type is replaced by the total number of blocks on the volume, there is no modified date displayed, and the volume's slot/drive location is displayed. LAUNCH: There are several program selectors available which require the user to provide a list of application specifications which consist of an application name, a path to the application's SYS file, a prefix to use when running the application, and a startup path if the system program supports it. When this list is set up, the selector does all the work when the application is selected. On the other hand, ECP8 requires the prefix to be set, then the SYS file must be specified along with the desired startup. The idea of this command is to bring the application list to ECP8. The list is placed in a file called LAUNCH.LIST and must be placed in the CMDS directory. The file contains ASCII text describing a list of application specifications, which must be in the following format: @Application name token /VOL/DIR/SYSFILE /VOL/DIR STARTUP The first line is the application name, which is displayed when the application list is displayed. It has no functional purpose other than identifying the application. The name may be up to 60 characters in length, and must have a '@' character as the first character. The next line specifies the token associated with the application. An application is launched by giving the token of the desired application as the argument to the LAUNCH command. Valid tokens may contain letters, numbers, periods, and underscores, and may be from 1 to 15 characters in length. Here are some examples of valid tokens: . 9 prog3 1application appleworks _program The next line specifies the path to the application's main SYS file. This is the file which is executed when the application is launched. It must be a fully qualified path, and it must be the path to a SYS file. The path is rejected if these two requirements are not met. The next line provides a prefix path for the application's use. Some applications do not fully support ProDOS protocol, and must have the prefix set to their own directory in order to run correctly. This allows the prefix to be set properly for these programs. If the application is properly written and does not require a specific prefix, placing a single slash character on the prefix line will cause LAUNCH to leave the prefix as is. The final line is used to specify a startup path for system programs which support the ProDOS startup protocol. Any characters other than spaces are legal on this line. If the system program does not support startups, this line is ignored. If the system program does not support startups, or if the program's default startup is to be used, a single slash character should be placed on this line to tell LAUNCH not to change the startup. After the last application specification, an asterisk should be placed on a line by itself. This is used to tell LAUNCH that it has reached the end of the list. Comment lines may be placed in the list by placing an exclamation point as the first character on the line. This causes the line to be ignored. Each line in the launch list file should end with a carriage return. The command places no size limit on the launch list - it can be as large as the available disk space, or as large as will fit in the text editor being used. Once the launch list is set up, it is used in the following manner: :launch token This command will cause the application associated with TOKEN to be launched. The following command is used to cause LAUNCH to display all of the application names and tokens in the launch list: :launch -l MORE: This command is an all-purpose file display utility. It can display interactively files line by line or screen by screen, a specified number of lines starting at the beginning of the file, or the entire file continuously. Its usage is the following: more { [-c] | [-h (#)] } file [file2...] If no dash argument is specified, the command displays the file in interactive mode. An entire screen of the file is displayed, then the command pauses for a keypress. Pressing SPACE displays the next screenful. Pressing RETURN enters step mode. While in step mode, the display pauses after each line and awaits a keypress. Pressing RETURN displays the next line and remains in step mode. SPACE cancels step mode and returns to page mode, displaying a full screen of text before pausing. Pressing ESC at any pause will terminate display of the current file. Keypresses other than SPACE, RETURN, or ESC are ignored. Invoking MORE with the -h argument causes the head of the file to be displayed, by default 15 lines. If -h is followed by a decimal number, the number of lines displayed is equal to the number specified. The number must be between 1 and 255. The -c argument causes all specified files to be displayed continuously, without pausing until the entire file has been displayed. This command supports TXT, SRC, and BAT files. NUKERAM: This command is handy if your machine contains a memory expansion card which is used as a RAM disk and the piddly 64K RAM disk is more of a nuisance than of real use. It is also handy when using 128k software that handles this device stupidly. (An example is the AppleLink PE software - it tends to reconnect the RAM disk in some format ProDOS does not recognize.) When nukeram is invoked, the /RAM unit number is removed from the device list, and the slot 3 drive 2 driver vector is set to NO DEVICE CONNECTED. This command only works on slot 3 drive 2 devices - if your machine has an aux slot type memory card which serves as a RAM disk and you use an intelligent software driver such as the one from prosel, which connects the RAM disk as a slot 3 drive 1 device, this command will not disturb it. Otherwise, it should not be used. This command uses the same feature of ProDOS 8 1.2 and newer that the IIS command uses to remove /RAM from the VCB, so it also should not be used with older versions. PURGE: The normal delete command implemented by most applications will delete a file from a volume, but leave the data intact on the disk. This command will remove a file's data from the disk as well as deleting it. It does this by first writing a 512 byte block of zeroes into the file a number of times equal to the number of data blocks in the file, then deleting the file. Note that in most cases, the number of blocks in a file is slightly more than the number of data blocks in the file, because the ProDOS file system uses some blocks in files for overhead. The command calculates the number of data blocks for files of all sizes. Purged files can be recovered, but their data is erased and is not recoverable. VERIFY: This command can accept a list of pathnames of files to verify and will attempt to read each file specified to check for errors. It will determine a file to be ok if no errors occur. The command will accept volume names as well as file names - if an argument is a volume name, the command will use block reads to verify every block on the disk, and will display the numbers of any blocks which caused errors. Escape may be pressed to abort this process. If the path is a file, it attempts to read the entire file with file reads. If an error occurs, the process halts and the file is reported to the user as having bad blocks. The command has an optional verbose flag. If verify -v is used to invoke the command, it tells the user what is happening at every step. If verbose mode is not in effect, it only informs the user when an operation is done. WIPE - This command is used to remove all data from a volume, in effect reformatting the volume. It does this by writing a blank volume directory and bit map onto the volume. Several options may be invoked via command line arguments. Command usage is the following: wipe [-z] [-d] [-r name] [-v] volume | -b volume | -p s d newname | -h The command line arguments are defined as follows: -z: Zero all data blocks on the volume (block 7 to the last block on the volume.) -d: Update the volume's creation date to the current date and time. This is intended mainly for users whose machines are equipped with a ProDOS clock. -r: This option causes the volume to be renamed to the name specified. -v: Set the minimum_version field in the volume directory header to 0 and set the version field to the version of the ProDOS kernel presently running. -b: Write the ProDOS boot code onto block zero of the volume, making the volume bootable. This option leaves all data on the volume undisturbed. -p: Pseudo-format disk in device specified by slot and drive arguments, and give the specified name to the new volume. Pseudo-formatting a disk does everything a normal format does, with the exception of the actual low level formatting of the disk media. That is, a new volume directory, bit map, and boot blocks are written onto the disk, and the volume is given the specified name. This means that any disk which is physically readable by a device may be turned into a ProDOS volume, without actually being formatted. Pseudo-formatted volumes are in every way like any other ProDOS format- ted volume, e.g. they are bootable once the proper system files are placed on them, etc. -h: Displays help information for the command. -p, -b, and -h are exclusive: if one of these is on a command line with any other dash argument, the entire command line is rejected. On the other hand, all other dash options can be used in any combination. They may also be specified in any order. None of the features of this command support the 64K RAM disk. With the exception of the -b option, this command is limited to volumes no larger than two megabytes, i.e. volumes with one bit map block. It will work with any size volume under this limit. _______________________________________________________________________________