home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Dr. CD ROM (Annual Premium Edition)
/
premium.zip
/
premium
/
IBMOS2_2
/
DHRGCD.ZIP
/
DHRGCD.TUT
< prev
next >
Wrap
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