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)

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

• Copy the RXMMUTL.DLL somewhere in your LIBPATH.
• Be sure to have the EMX runtime library, EMX.DLL (preferably version 0.9d) somewhere in your LIBPATH.
• Register the DLL's functions once from your REXX scripts:

  CALL RxFuncAdd 'MMLoadFuncs', 'RXMMUTL', 'MMLoadFuncs'
  CALL MMLoadFuncs

• Copy REXX functions from rxmmutl.cmd as you need them.

Download

ZIP file with source and this guide: Version 0.31

RXMMUTL.CMD Reference (REXX-Functions)

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)

• Added ToGmTime(time) to rxmmutl.cmd
• Added MMIniQuery(profile,application,key) and MMIniWrite(profile,application,key,value) to rxmmutl.dll

Version 0.3 (May 31, 2003)

• Added MMFileIn(filename) to rxmmutl.dll
• Added MMIniOpen(profile) and MMIniClose(profile) to rxmmutl.dll

• Added MMHash(data, hashtype) to rxmmutl.dll, uses Crypto++ by Wei Dai.

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:-): 

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