REXX Algorithms
=============================================================

Table of Contents
-----------------

1.     Disclaimer.
2.     Copyright.
3.     Current version
4.     REXX Algorithms.
4.1.     Searching and sorting. 
4.1.1.     Binary search.
4.1.2.     Bubble sort.
4.1.3.     Insertion sort.
4.1.4.     Quick sort
4.1.5.     Shell sort.
4.2.     Date and time.
4.2.1.     Translate Gregorian date to Julian date.
4.2.2.     Julian date to Gregorian date.
4.2.3.     Date with century
4.3.     Strings.
4.3.1.     Translate umlauts to lower case.
4.3.2.     Recursive string formatting.
4.3.3.     Replace a substring by an another.
4.3.4.     Remove umlaut characters.
4.4.     Mathematical functions.  
4.4.1.     Square root evaluation.
4.4.2.     Cube root evolution
4.4.3.     Greatest common divisor
4.5.     File system.  
4.5.1.     Recursive creating directory path.
4.5.2.     Delete directory path.
4.6.     Multimedia.  
4.6.1.     Digital Audio Player (mciRexx)
4.7.     Miscellaneous. 
4.7.1.     Exclude multiple items from a stem.
5.     Author.


=============================================================

1. Disclaimer.
--------------

This package is provided as is, without any guarantees or
warrantees whatsoever. The author is not liable or responsible 
for any loss or damage of any kind whatsoever, including, but
not limited to, losses of a financial, physical, emotional,
marital, social, or mental nature that may result from the
use or the purported use of anything in this package, for any
purpose whatsoever. 

Thanks to Michael Shillingford for this wording.

=============================================================

2. Copyright.
-------------

(C) Copyright Janosch R. Kowalczyk, 1996, 1997. All rights reserved. 

You may distribute this document and software in the original format to any one.

You can use this document and software for all non-commercial purposes only.
Commercial users must obtain the permission of the author first. 

You aren't allowed to distribute this document and software in printed form 
without the written permission of the author.

All the routines described in this document are implemented in Rexx by the 
author and they are free of charge. 

=============================================================

3. Current version.
-------------------

The current version of Rexx Algorithms is 1.31.
The current source files are:

- RXALG131.CMD
- RXALG131.FNC (for Greed - OS/2 only)

Last revision date: July 2, 1997

=============================================================

4. REXX Algorithms.
-------------------

I work as a systems programmer for MVS security systems and I work
quite often under both TSO and OS/2 systems (environments). That's
why I'm so happy to have Rexx - I must write my programs only once
and they work on these two systems.

I've written already a lot of Rexx programs. Doing this I wrote 
many simple but rather useful Rexx subroutines. They are both 
common well-known algorithms and my own solutions for Rexx specific
problems.
 
RexxAlgo is a collection of various REXX source code (sub)routines.
I think that many Rexx programmers can use these subroutines to solve 
their problems and they do not have to develop these things once again.

These algorithms are at the Release 1.30 subdivided in the following 
thematical groups:  

1. Searching and sorting.  
   - Binary search                       BiSearch
   - Bubble sort                         BubSort
   - Insertion sort                      InsSort
   - Quick sort                          QSort
   - Shell sort                          ShlSort

2. Date and time.  
   - Gregorian date to Julian date       G2J
   - Julian date to Gregorian date       J2G
   - Date with century                   Date2000

3. Strings.  
   - Translate umlauts to lower case     ToLower
   - Recursive formatting                Combine 
   - Replace a string                    ReplaceString
   - Remove umlaut characters            NoUmlaut
     This is a sample for using ReplaceString.

4. Mathematical functions.  
   - Square root evaluation              SqrRoot
   - Cube root evaluation                CubeRoot
   - Greatest common divisor             EuclidGCD

5. File system.  
   - Recursive creating directory path   MakePath
   - Delete directory path               ErasePath

6. Multimedia.  
   - Digital Audio Player (mciRexx)      PlayFile

7. Miscellaneous. 
   - Exclude multiple items              NoMult
 
All these code templates are written as internal subroutines.

I have placed the same subroutines into two files:
- first, as plain text into the Rexx command file named RXALGxxx.CMD
- secondly, as code templates in the function file for GREED's Templates
  Controller, named RXALGxxx.FNC (INI format).

Note: The abbreviation xxx is the current version number i.e. 131 for the
      version 1.31 

GREED - General Rexx Extended Editor - is a small PM developing
environment to write, store and control of code templates. It can
be used to control the code sections for all programing languages.
You can find it in the CompuServe forum OS2USER (library: Open forum)
under the name GREED.ZIP.


4.1. Searching and sorting.
---------------------------  
4.1.1. Binary search.

       Function name: BiSearch
       Syntax.......: foundIndex = BiSearch( value )
       Function.....: Binary search a stem variable for a value
       Call param...: Searched value
       Returns......: index of the found value,
                      0 if nothing found

       Notes........: The elements to search for must be saved
                      in the stem named so as the stem in this
                      procedure (default name "STEM.")
                      stem.0 must contain the number of elements
                      in stem.
                      The stem-variable must be in the sorted order.

       Sample call..:
                      foundIndex = BiSearch(value) 
                      If foundIndex = 0 Then
                        Say 'Value' value 'not found!'
                      Else
                        Say stem.foundIndex 

4.1.2. Bubble sort.

       Function name: BubSort
       Syntax.......: Call BubSort
       Function.....: Sort of a stem variable using the Bubble sort
                      algorithm.
       Call parm....: No 
       Returns......: nothing (NULL string)

       Notes........: The elements to sort for must be saved in the
                      stem named so as the stem in this procedure 
                      (in this case "STEM.").
                      stem.0 must contain the number of elements in
                      stem.

4.1.3. Insertion sort.

       Function name: InsSort
       Syntax.......: Call InsSort
       Function.....: Sort of a stem variable using the Insertion sort
                      algorithm.
       Call parm....: No 
       Returns......: nothing (NULL string)

       Notes........: The elements to sort for must be saved in the
                      stem named so as the stem in this procedure 
                      (in this case "STEM.").
                      stem.0 must contain the number of elements in
                      stem.

4.1.4. Quick sort

       Function name: QSort
       Syntax.......: Call QSort
       Function.....: Sort of a stem variable using the Quick sort
                      algorithm.
       Call parm....: No 
       Returns......: Left-Right span

       Notes........: The elements to sort for must be saved in the
                      stem named so as the stem in this procedure 
                      (in this case "STEM.").
                      stem.0 must contain the number of elements in
                      stem.

4.1.5. Shell sort.

       Function name: ShlSort
       Syntax.......: Call ShlSort
       Function.....: Sort of a stem variable using the Shell sort
                      algorithm.
       Call parm....: No 
       Returns......: nothing (NULL string)

       Notes........: The elements to sort for must be saved in the
                      stem named so as the stem in this procedure 
                      (in this case "STEM.").
                      stem.0 must contain the number of elements in
                      stem.


4.2. Date and time.
-------------------  
4.2.1. Translate Gregorian date to Julian date.

       Function name: G2J
       Syntax.......: julDate = G2J( yyyy.mm.dd )
       Function.....: Translates Gregorian date to the Julian date
       Call param...: Gregorian date in format yyyy.mm.dd
       Returns......: Julian date in format yyyy.ddd

4.2.2. Julian date to Gregorian date.

       Function name: J2G
       Syntax.......: gregDate = J2G( yyyy.ddd )
       Function.....: Translates Julian date to the Gregorian date
       Call param...: Julian date in format yyyy.ddd
       Returns......: Gregorian date in format yyyy.mm.dd

4.2.3. Date with century

       Function name: Date2000
       Syntax.......: Date = Date2000(Option)
       Call option..:   Returns dd Mmm yyyy
                      B Returns dddddd days since 01.01.0001
                      D Returns ddd - days in the current year
                      E Returns dd/mm/yyyy
                      J Returns yyyy.ddd - Julian date
                      L Returns dd Month yyyy
                      M Returns Month
                      N Returns dd Mmm yyyy
                      O Returns yyyy/mm/dd
                      S Returns yyyymmdd
                      U Returns mm/dd/yyyy
                      W Returns Weekday
       Function.....: Same output as the Rexx built-in function Date() but
                      includes the century with the year. Has also an additional 
                      option, J.


4.3. Strings.
------------- 
4.3.1. Translate umlauts to lower case.

       Function name: ToLower
       Syntax.......: lowString = ToLower(upperString)
       Function.....: Translate entired string to lower case
       Call param...: String to translate
       Returns......: Translated string

       Notes........: Simply change variable 'Lowers' and 'Uppers'
                      to get the function ToUpper

4.3.2. Recursive string formatting.

       Function name: Combine 
       Syntax.......: formStr = Combine( _combStr, _combLen, [_combTooth], [_combRep] )
       Function.....: Recursive formatting of a string with a constant
                      interval.
       Call param...: _combStr   - string to be formated,
                      _combLen   - string's length,
                      _combTooth - new format string (optional),
                      _combRep   - format interval (optional)
       Returns......: formated string 

       Notes........: Default value for _combTooth is a blank
                      Default value for _combRep is 1
                      _combTooth will be inserted into the _combStr at
                      the position computed as follows:
                      _combLen = _combLen - _combRep

       Sample.......: formStr = Combine( '10000000000', 11, ',', 3 )
                      Input string  = '10000000000'
                      String length = 11
                      Format string = ','
                      Interval      = 3
                      Output string = '10,000,000,000'

4.3.3. Replace a substring by an another.

       Function name: ReplaceString
       Syntax.......:    tranStr = ReplaceString( _string, _origin, _replStr )
       Function.....: Replace in the input-string all found substrings
                      by the another (so as built-in functions Overlay and
                      Insert together).
       Call param...: _string  - input string,
                      _origin  - substring to be replaced,
                      _replStr - replace substring
       Returns......: translated string

       Note.........: This function is called from NoUmlaut

4.3.4. Remove umlaut characters.

       Function name: NoUmlaut
       Function.....: Replace umlaut characters with double character
                      strings ( -> ae,  -> oe,  -> ue,  -> ss)
       Call param...: _string - string with umlauts,
                      _upper  - upper case return string (optional)
       Returns......: translated string
       Syntax.......: tranStr = NoUmlaut( uString,['U'] )

       Notes........: This function calls the function ReplaceString.


4.4. Mathematical functions.  
----------------------------
4.4.1. Square root evaluation.

       Function name: SqrRoot
       Syntax.......: sqrt = SqrRoot(number, [precision])
       Function.....: Square root evolution for the called parameter.
       Call params..: evolution number,
                      precision (optional)
       Returns......: Square root of the called parameter
       Notes........: precision is the highest possible error for the
                      evaluation.
                      Default Value of the precision is 0.00001
                      You are responsible for the valid number values

4.4.2. Cube root evaluation.

       Function name: CubeRoot
       Syntax.......: gcd = CubeRoot(_digit, _precision)
       Function.....: Cube root evolution.
       Call params..: Call parameters are two digits. The first one is the digit 
                      for which you want to compute the cube root, the second is 
                      the precision of the calculation. The precision is a 
                      decimal fraction number e.g. : 0.00000001.

       Returns......: cube root of the called parameter.
       Notes........: You are responsible for the valid number values 

4.4.3. Greatest common divisor

       Function name: EuclidGCD
       Syntax.......: gcd = EuclidGCD(_counter, _denominator)
       Function.....: Euclid's algorithm to obtain the greatest common divisor.
       Call params..: Call parameters are two digits, for which the function 
                      computes the greatest common divisor.

       Returns......: greatest common divisor.
       Notes........: You are responsible for the valid number values

4.5. File system.  
-----------------
4.5.1. Recursive creating directory path (OS/2 only).

       Function name: MakePath
       Syntax.......: _destPath = MakePath( _destPath )
       Function.....: Recursive creating of the directory path
       Call parm....: _destPath  - directory path
       Returns......: directory path

4.5.2. Delete directory path (OS/2 only).

       Function name: ErasePath
       Syntax.......: _erasePath = MakePath( _erasePath )
       Function.....: Delete fully directory path
       Call parm....: _erasePath - directory path to be deleted
       Returns......: formated string
       Note.........: Only empty directories will be deleted.


4.6. Multimedia.  
----------------
4.6.1. Digital Audio Player (mciRexx)

       Function name: PlayFile
       Syntax.......: rc = PlayFile( audio_file_name )
       Function.....: Play digital WAV/MID file
       Call params..: File name to play
       Returns......: RC from the last mciRexx function


4.7. Miscellaneous. 
-------------------
4.7.1. Exclude multiple items from a stem.

       Function name: NoMult
       Syntax.......: Call NoMult
       Function.....: Excludes multiple items from a sorted stem variable                         */
       Call param...: no
       Returns......: 0
       Notes........: The elements to exclude must be saved in the stem
                      named so as the stem in this Procedure (in this
                      case "STEM.")
                      stem.0 must contain the number of elements in stem.
                      The stem variable must be previously sorted.

=============================================================

5. Author.
----------

If you have any questions or suggestions, you can reach me under
the following address:

  Janosch R. Kowalczyk
  Oberwaldstr. 42
  63538 Grosskrotzenburg / Germany
  Tel: +49 (0)6186 201676
  Compuserve: 101572,2160
  Internet: 101572.2160@compuserve.com
 
=============================================================

Enjoy!

Janosch
