OS/2 Shareware BBS: 6 File/06-File.zip/DHRGCD.ZIP/DHRGCD.TUT

Text File | 1992-07-01 | 16KB | 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