OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / fileutil / dhrgcd / dhrgcd.tut < prev next >

Wrap

Text File | 1992-07-01 | 16.0 KB | 309 lines

DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description 06/22/92 This document will attempt to explain some of the how and why of the programming logic in DHRGCD.CMD. REXX was chosen as the programming language because it is easy to use and is included free with OS/2 2.0. The version supplied with OS/2 is highly integrated with OS/2 and supports all features of the DOS style batch language including the essential ability to permanently change disks and directories from within a REXX command file The DHRGCD program was written to provide a way to jump from directory to directory without requiring the full path name. This functionality is provided in DOS by the Norton Utilities' program NCD. The additional ability to jump between disks was included because the size of OS/2 and developmental software had required me to purchase multiple disk drives. When the new configuration was complete, I was left with 7 logical disks on 2 physical drives to manage. For program development (and most other tasks), I prefer to use multiple full screen command line sessions rather than have multiple small windows open on the work place shell. Since I do mainframe programming (IBM VM and MVS) as well as DOS and OS/2 programming, my general editor of choice is Mansfield Software's KEDIT (for OS/2 and DOS) which is very similar to XEDIT on VM (which I prefer over SPF on MVS). Throughout the file are comments labeled /* Reference #x */. I will refer to those in the following explanation. The exec begins with the required REXX comment line, the content of which re- flects the operating system where I first learned REXX - IBM's VM/CMS where REXX files were required to have a file type of 'EXEC' (where in OS/2 the file type is 'CMD'). The first execut- able instruction is 'trace'. This is used primarily during devel- opment by adding the option 'r' to display what is happening within the REXX program during execution. It is left here to maintain the same line number count during normal operations and testing. The OS/2 environment variable RXTRACE may also be used to display program flow. The PARSE source extracts the full name of the CMD including path information. The filespec function and following PARSE is used to extract just the name. The name will be used in displays from the program. The command '@ECHO OFF' turns off displays of commands sent to OS/2 exactly the same as in a BAT file. The signal statement here identifies the name of a REXX subrou- tine that will be executed if control break or control C is entered. The routine at Reference #13 will first delete the index file if the program is in the process of building it then display a termination message and exit. 1 DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description 06/22/92 Following Reference #2 are options to control how the REXX pro- gram will operate. They were placed here in a group to allow easy modification. The variable use_current_disk_index when set to 'Y' will place the index on the disk where the command is executed. If not set to 'Y', the variable use_boot_disk_index when set to 'Y' will place the index on the boot disk. If use_current_disk_index is not 'Y' and use_boot_disk_index is also not 'Y', the index will be placed on the first local hard disk. The REXX variable use_ansi_colors determines if ANSI control strings will be used to change colors when displaying messages from the program. The variable use_all_disks controls if only local drives or all drives known to OS/2 will be used when creat- ing an index file. The first task is to extract information from the command line. The PARSE instruction is used to separate the command line into sections - destination subdirectory name and execution option. Options in DOS and OS/2 follow the UNIX tradition of a '/' or '-' followed by a sometimes cryptic letter or combination of letters that means something to the executing program. The options may precede or follow a parameter such as a file name. Options in the IBM VM/CMS world are generally meaningful names that always follow a '(' that may follow a parameter such as a file name. OS/2 -> GCD /l sub1 OS/2 -> GCD sub1 /l VM/CMS -> GCD sub1 (l The OS/2 High Performance File System allows a dash ('-') to be a leading character in a file or subdirectory name so the use of the '-' as an option flag will not be supported in this REXX program. (This is not to say it cannot be done, it can be done in this program due to the limited number of options but could not be done if more options were available.) GCD -h -l - which is the directory and which is the option? The lines following Reference #3 extracts two items from the command line that have been entered in either the DOS-OS/2 format or the VM/CMS format. There are three PARSE instructions all extracting from the same command string but using different patterns to match different types of input. Much of the logic here is to handle either format of parameters. The PARSE option 'upper' will convert both subdirectory name and option to upper- case. If a question mark was entered, it will be placed in the option field even though a slash was not entered. The HPFS allows directory and file names to contain spaces. The REXX PARSE gener- ally uses spaces as a delimiter. The first PARSE statement speci- fies a delimiter of '/' which prevents the removal of spaces from the directory name, although the primary purpose is to identify the option string. The STRIP function without options removes beginning and trailing spaces. To allow entry of a directory name 2 DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description 06/22/92 that contains a leading space, the program provides for entry of a directory surrounded by double quotes with another PARSE state- ment. Note that quotes are only required if the directory name begins with a space. Trailing spaces are never stored by the HPFS. Any trailing spaces are removed by a STRIP call with the 'T' option. Lines following Reference #4 check for options that can be han- dled immediately and combinations of entries that are invalid. This is placed here to minimize the amount of processing for these types of entries. If help was not requested and the options appear valid, lines following Reference #5 initialize variables that are used later. Based on a variable set following Reference #2, the ansi_ variables are set to ANSI escape sequences to control display color or to null. The REXXUTIL DLL will be used in multiple places, so here it is tested to see if it was pre- viously loaded by another CMD file. If not, it is loaded here. If the variable use_boot_disk_index was set to 'Y', lines follow- ing Reference #6 determine the boot disk. The custom DHRRU100 DLL will be used to extract the boot drive number. The RxFuncAdd call will load the custom DLL that contains the REXX function DHRSys- Info that will be used to determine the logical disk that was used to boot the system. As I described before, having 7 logical disks is a perfect oppor- tunity for the OS/2 Boot Manager. Drive C is a bootable primary dual boot DOS 5 and OS/2 1.3 FAT partition. Drive D is a bootable logical OS/2 2.0 PM FAT partition. Drive E is a bootable logical OS/2 2.0 non PM FAT partition (to do corrective CHKDSK on the D drive when required). Drive F, G, and H are FAT logical parti- tions. Drive I is a bootable logical OS/2 2.0 PM HPFS partition. The desire to segregate system files to a specific boot disk led to the development of a simple REXX callable DLL written in C which would return the contents of the OS/2 control program function QuerySysInfo which contains, among other things, the boot disk number. After the call to DHRSysInfo the REXX variable OS2info.5 contains the boot disk number. The DLL will normally only be used by this REXX program, so it is released by the RxFuncDrop. Lines following Reference #7 determine if the index is present based on a variable set at the top of the program. If the use_boot_disk_index is set to 'Y' and the boot_disk variable contains a value, the index_disk will be set to the boot_disk. The following lines may be uncommented to test the boot disk for the presence of the index and force all disks to be searched if the index is not found on the boot disk. The next IF-END will search for the index disk on any local disk if it has not been 3 DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description 06/22/92 identified. Lines following Reference #8 are executed if the disk containing the index file has not been determined which means it does not currently exist. By the time we get to Reference #9, there are four possible options - 'R', 'RQ', 'L', or NULL. The option 'RQ' is an exten- sion of the 'R' option so they are handled together. The 'L' option is a modification of the normal look up so is handled in the second half of the IF statement. The 'R' or 'RQ' option builds or rebuilds the directory index. With these options the target string may become a string of disks to be searched for indexing. The '@ECHO OFF' at the beginning of the program turned off the normal echoing of command execution to the console, but the 'DEL' command will produce an error message when a file to be deleted is not found. The redirection ' 2> NUL' discards information written to file handle 2 (STDERR) which is where the 'not found' error message is displayed. The DO WHILE sequence takes an entered string of disks to be indexed and expands the string by adding a colon and space to the end of each letter. The PARSE instruction in the next DO WHILE loop will separate each disk delimited by a space. The call to the REXXUTIL entry SysFileTree should work but there is a problem in the internal code of OS/2 (to be fixed in the future) so SysFileTree does not return subdirectories that begin with a space. The DIR command does so the next line calls a REXX subrou- tine to return the same information but in more lines of code. The code following Reference #14 redirects the output of the DIR command to the default REXX queue with the OS/2 RXQUEUE program. The DO loop places the queued information into a REXX stem vari- able called 'dirstem' which is exactly where the information would have appeared had the SysFileTree function been executed. The subdirectory names are output to the index file with a call to a REXX subroutine write_dir. The second half of the IF ELSE test implements the subdirectory look up. The REXXUTIL function SysFileSearch following Reference #10 is used to search the directory index for all names that contain the target string. An error is displayed if no matches are returned. The returned values are further reviewed in the following DO loop. If the /l option was included, all returned values that do not exist on the current disk are skipped. If the returned value does not include the target directory as part of the last qualifier, it is also rejected. The REXX stem variable match_val. will contain all valid matches. An attempt is made to 4 DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description DHRGCD.CMD Version 1.01 Detailed Description 06/22/92 provide a best match hint for later display. If there was only one match, the directory is switched by the call to the REXX function directory. If there was more than one choice, they are displayed and the user is prompted for a selec- tion in the lines following Reference #11. The REXXUTIL function SysTextScreenSize is used to determine how many lines are avail- able for the display. If there are more choices then there are display lines, the list will be divided into two columns. If there is a best match, item number will be displayed along with the prompt. A best match value allows the use of just the enter key for acceptance. The local function get_ans, located following Reference #15, reads one or more keys based on the expected maxi- mum length of the reply. The call to CHROUT is used to prevent the automatic CR/LF output of the SAY instruction. Non-numeric keys are rejected, the ESC key may be used to return without a value, and the enter key will return with whatever has been entered. The string entered is returned to the caller. If a valid value was entered, the call to the directory function will switch to the new directory. The common exit code following Reference #12 is required to restore the screen colors to a white on black display. The label exit_gcd: is used by the signal following the call to get_ans to immediately exit if either the ESC key was pressed or 0 was entered. If the default screen color is not white on black, the variable ansi_white should be changed to the correct color defined at the start of the program. The subroutine write_dir at Reference #16 was included here rather than placed inline at the single calling location to allow future expansion. Two help displays are available, caused by a ? or /h. The /h provides the OS/2 full screen VIEW display of the DHRGCD.INF file. Unfortunately, the return code is always zero. The enter of a ? will produce the short text display of help information. 5