REXX utilities beyond REXXUTIL for OS/2

This is a (growing) collection of miscellaneous REXX utility functions and code fragments. Some of them are coded in REXX others in C.

Version: 0.31 (Jan. 6th, 2006)

→ Quick guide → Download → Reference (REXX) → Reference (C DLL) → History → Contact

This font indicates things you can type in.
Italic in addition indicates parameters, which have to be replaced by meaningful values.
Parameters in [braces] are optional.


Quick guide


Download

This utility functions are freeware.

ZIP file with source and this guide: Version 0.31


RXMMUTL.CMD Reference (REXX-Functions)

All of the following functions are part of the script RXMMUTL.CMD. You may copy them into your own REXX scripts.

ToUnixTime ToGmTime UnixTime StringMatchQ StringReplace QSort

Parse command line

This code fragment will split a command line string into arguments, properly handling and removing quotes (").
params = STRIP(ARG(1))
DO WHILE params \= ''
IF LEFT(params,1) = '"' THEN DO
PARSE VAR params '"'param'"'params
params = STRIP(params, 'L')
END
ELSE
PARSE VAR params param params
/* param is the next parameter to process ... */
IF (LEFT(param, 1) = '/') | (LEFT(param, 1) = '-') THEN
SELECT
/* parsing options ... */

OTHERWISE
SAY "illegal option '"param"'"
END

ELSE DO
/* any other arg ... */

END
END

ToUnixTime(year, mon, day, hour, min, sec)

Convert time to Unix format (seconds since Jan. 01, 1970 0:00).
year
Year (4 digits ! E.g. 1997)
mon
Month (1-12)
day
Day of month (1-31)
hour
Hours (0-23)
min
Minutes (0-59)
sec
Seconds (0-59)
Return value
Unix time
Notes:
  1. Be sure to set NUMERIC DIGITS at least to 10. The default of 9 overflowed on 9. Sep. 2001 1:46:40 (AM).
  2. Be careful with the function arguments as there are no consistency checks at all.
  3. This function will fail on 1st Mar. 2100 and later because the century exception for the gap day 29th Feb. is not implemented.
  4. This function will ignore time zones. It will only work correctly if the time is GMT.

ToGmTime(time)

Convert Unix time to time structure. Similar to the C runtime function gmtime().
time
Unix time stamp in seconds since Jan. 01, 1970 0:00.
Return value
Structure with the following space delimited values:
word name description
1 sec seconds after the minute [0-59]
2 min minutes after the hour [0-59]
3 hour hours since midnight [0-23]
4 mday day of the month [1-31]
5 mon months since January [0-11] - note the zero based offset like in the C structure tm!
6 year years since 1900
7 wday days since Sunday [0-6]
8 yday days since January 1 [0-365]
Notes:
  1. Be sure to set NUMERIC DIGITS at least to 10. The default of 9 overflowed on 9. Sep. 2001 1:46:40 (AM).
  2. This function will fail on 1st Mar. 2100 and later because the century exception for the non leap year 2100 is not implemented.
  3. This function will ignore time zones. It will always assume GMT.

UnixTime

Get current time in Unix time format (seconds since Jan. 01, 1970 0:00).
Parameter
None
Return value
Current time (Unix format)
This is similar to the C function time(NULL). However, the result is localtime rather than GMT.

StringMatchQ(string, template)

Check if string matches a template string containing wildcard characters (*,?).
string
String to check
template
Template string
? represents any character.
* represents any sequence of zero or more characters.
Return value
1 (true) string matched
0 (false) string does not match

StringReplace(string, find, replace[, find, replace[,...])

Replace substrings.
string
String to modify
find
Find find and ...
replace
... replace with replace
Return value
Modified string
This is the same than the Object REXX function CHANGESTR(find, string, replace), if you specify only one replacement rule and if you have Object REXX.

CALL Qsort stem[, first][, last]

Sort a stemmed variable.
stem
Name of the stemmed variable.
first
First item in the stemmed variable to sort. By default 0.
last
Last item in the stemmed variable to sort. By default stem.0.
The function destroys the variable STEM in the callers scope.

RXMMUTL.DLL Reference (external C Functions)

MMTranslateCp MMUpper MMTime MMSetFileSize MMFileMove MMFileIn MMHash MMIniOpen MMIniClose MMIniQuery MMIniWrite

MMLoadFuncs

Register any function in rxmmutl.dll (except for MMLoadFuncs, of course).
Parameter
None
Return value
Empty string
Note: You usually want to register this function first:
IF RxFuncAdd("MMLoadFuncs", "RxMMutl", "MMLoadFuncs") = 0 THEN
CALL MMLoadFuncs

MMDropFuncs

Deregister all functions from rxmmutl.dll.
Parameter
None
Return value
Empty string

MMTranslateCp(string, [sourceCP], [destinationCP], [substitutionchar])

Translate string from one code page to another.
The source and destination code page is not restricted to the ones prepared in the CONFIG.SYS with the CODEPAGE statement. See description of WinCpTranslateChar for a list of supported code pages.
string
String to translate
sourceCP
Source code page
If omitted the current active code page is used.
destinationCP
Destination code page
If committed the current active code page is used.
substitutionchar
Substitution character for untranslatable characters.
This argument must be at most one character in length. By default D2C(255) is used. The null string, '', has a special meaning: it suppresses the conversion of untranslatable characters at all. You should be careful with this option, because it usually results in bogus characters in the destination code page. However, it may have useful side effects.
Return value
Translated string

MMUpper(string, [codepage], [country])

Translate string to uppercase.
In comparison to TRANSLATE(string) this takes care of special characters like umlauts.
string
String to translate
codepage
code page
If committed the current active code page is used.
country
Country code
If committed the current country code defined in the CONFIG.SYS is used. I don't really know the influence of this parameter. Normally you can drop it.
Return value
Uppercase string
Note: This function is similar to the in Classic REXX undocumented REXXUTIL function SysMapCase.

MMTime

Return time in UNIX time format (seconds since 01.01.1970 0:00). This is the return value of the C library function time(NULL).
Parameter
None
Return value
UNIX time

MMSetFileSize(filename, newsize)

Modify size of file. The file can be truncated or extended.
filename
Name of the file to modify
newsize
New size of the file in bytes
Return value
0 - file size changed successfully
otherwise - OS/2 error code

MMFileMove(oldname, newname)

Move and/or rename a file or directory.
oldname
Current name of the file or directory to move/rename
newname
New path and/or name of the file or directory (The drive letter must be omitted or the same as before)
Return value
0 - file moved/renamed successfully
otherwise - OS/2 error code

MMFileIn(filename)

Read an entire file into a symbol.
filename
Name of the file to read.
Return value
File content or an empty string in case of an error.
This is roughly the same action as the REXX instructions:
CALL STREAM filename, 'c', 'open read'
result = CHARIN(filename, , STREAM(filename, 'c', 'query size'))
CALL STREAM filename, 'c', 'close'
But in contrast to the above instructions there is no memory leak!
There is no way to distinguish between an empty file and an error. Furthermore you cannot get any details about the error occurred.

MMHash(data, hashtype)

Create a hash value from data.
data
Input data
hashtype
One of: Adler32, CRC32, HAVAL, MD2, MD4, MD5, RIPEMD160, SHA, SHA256, SHA384, SHA512, Tiger
Return value
Hash value
The length of the hash value depends on the hash type.

Profile functions

The profile functions provided by RXMMUTL are significantly superior to SysIni from REXXUTIL. The main advantage is the speed when accessing user defined profiles that are not open by another application. This is because SysIni always opens and closes the profile on each call. Furthermore there are no reserved strings like 'DELETE:' that may be interpreted in an unexpected way.

MMIniOpen(profile)

Open an OS/2 profile like SysIni does, but in contrast to the latter one the profile is kept open until you call MMIniClose or your REXX application terminates. This is significantly faster than SysIni if you access the profile multiple times.
profiledata
profile name
Return value
OS/2 PM error code or 0 in case of success.
Remark: this function is even useful when the REXXUTIL function SysIni is used in the application, because once, the profile is opened by MMIniOpen SysIni is faster by a factor.

MMIniClose(profile)

Close an OS/2 profile. This will never affect handles from another REXX application even if they are related to the same file.
profile
profile name
Return value
OS/2 PM error code or 0 in case of success.

MMIniQuery(profile, [application, [key]])

Read data from an OS/2 profile. If the profile is not already opened MMIniQuery opens the profile like MMIniOpen has been executed before. The Profile is not closed after execution. The profile will be automatically closed when your Application (REXX instance) terminates. Use MMIniClose to forcibly close the profile.
profile
profile name
application
Name of the application section in the profile. If this (and the next) parameter is omitted a list of all existing applications in the profile is returned.
key
Name of the key to query. If this parameter is omitted a list of all existing keys for the application is returned.
Return value
Value of the requested property or list of values (depending on application and key). The items in the list are separated by NULL characters. If an error occurred or the requested property does not exist the function returns an empty string. There is no way to distinguish between an error and an empty value or an empty item collection respectively.

MMIniWrite(profile, application, [key, [value]])

Write data into an OS/2 profile. If the profile is not already opened MMIniWrite opens the profile like MMIniOpen has been executed before. The Profile is not closed after execution. The profile will be automatically closed when your Application (REXX instance) terminates. Use MMIniClose to forcibly close the profile.
profile
profile name
application
Name of the application section in the profile.
key
Name of the key to query. If this parameter is omitted all keys for the application are deleted.
value
Value of the key to set. If this parameter is omitted the specified key is deleted. Note that an empty string will not delete the key.
Return value
OS/2 PM error code or 0 in case of success.
E.g. 267012 = X2D(41304), i.e. severity (high order word) = 4 = warning and error (low order word) = X2D(1304) = not found (while deleting a key).

History

Version 0.31 (Jan. 6, 2006)

Version 0.3 (May 31, 2003)

Version 0.2 (Aug 4, 2002) Version 0.1 (first release)

Build instructions

Use the included Makefile to build RXMMUTL.DLL. I used GCC 3.2.2 for EMX OS/2. However, it should work with other C++ compilers too. There should be no GCC specific elements in the code. In contrast, the makefile contains GCC specific parameters.

Since version 0.2 you must have libcryptopp, which is not included in this package. However, if you don't want to include this bulky library simply remove the compile time option -DHAVE_CRYPTLIB. (See the comment in the makefile.) Of course, the relating functions will not work in this case. (currently only MMHash)


Contact

Suggestions, help, complaints (but not too much:-): Mail address: mueller-at-maazl-dot-de

Original homepage: http://www.maazl.de/project/rxmmutl/index.html