Rexx/EEC
Version 1.4
Copyright (C) 2017 Mark Hessling <mark@rexx.org>

TABLE OF CONTENTS

1. RexxEEC/Introduction [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

Rexx/EEC is an external function package that provides functions for Encrypting, Encoding and Compressing Rexx strings. The opposite functionality; Decrypting, Decoding and Decompressing is also provided by this function package.

USAGE

To make the external functions available add the following lines before: the first call to one of the functions in the package:

Call RxFuncAdd 'EECLoadFuncs', 'rexxeec', 'EECLoadFuncs'
Call EECLoadFuncs

TODO

BUGS

PORTABILITY

Rexx/EEC runs on Windows 9x/Me/NT/2k/XP, OS/2 3.0+ and on any Un*x platform

SEE ALSO

Rexx/EEC lives at http://rexxeec.sf.net

COPYRIGHT

Rexx/EEC is Copyright(C) 2008 Mark Hessling <mark@rexx.org>
The compression code in the "zlib" directory is Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler.
The encryption code in the "des" directory is Copyright (C) 1995-1997 Eric Young .
The encryption code in the "blowfish" directory is Copyright (C) 1997 Paul Kocher .

2. RexxEEC/Constants [ Modules ]

[ Top ] [ Modules ]

NAME

Package Constants

DESCRIPTION

The following "constants" are defined when RexxEEC starts. By default, all constants are stored in an array with the stem preset to !REXXEEC.! This can be changed by using the 'CONSTANTPREFIX' value of EECvariable(). If you use "Procedure" on your labels, you MUST "EXPOSE !REXXEEC." or the stem you set with EECvariable() will not be visible. To reference the constants defined below, you must prefix them. So the "constant" ENCRYPT_TYPES would be, by default, referenced in your code as !REXXEEC.!ENCRYPT_TYPES.

SEE ALSO

EECvariable

ATTRIBUTES

3. Functions/Encode-Decode [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

The following functions encode and decode a string to and from an encoded format. Encoding generally converts 8 bit characters into printable characters for electronic transmission. As a result the encoded string is longer than the raw string.

USAGE

EECencode and EECdecode are symmetrical. ie: EECdecode( EECencode( str ) ) == str

NOTES

For UUencoding the length of the original string must be stored with the encoded string as the decoding mechanism has no way of knowing the original length of the string. Rexx/EEC prepends 4 bytes to the beginning of the returned encoded string which contains the original length of the string.

3.1. Encode-Decode/EECencode [ Functions ]

[ Top ] [ Encode-Decode ] [ Functions ]

NAME

EECencode

SYNOPSIS

encstr = EECencode( Str[, Type] )

FUNCTION

Encodes Str to one of:

ARGUMENTS

RESULT

Str encoded or blank if an error.

SEE ALSO

EECdecode, !REXXEEC.!INTERRM

SOURCE

...
str = 'This is my string.'
encstr = eecencode( str )
Say 'UUencoded string is: encstr

3.2. Encode-Decode/EECdecode [ Functions ]

[ Top ] [ Encode-Decode ] [ Functions ]

NAME

EECdecode

SYNOPSIS

str = EECdecode( EncStr[, Type] )

FUNCTION

Decodes EncStr from a UU or BASE64 string.

ARGUMENTS

RESULT

EncStr decoded or blank if an error.

SEE ALSO

EECencode, !REXXEEC.!INTERRM

SOURCE

...
str = 'This is my string.'
encstr = eecencode( str, 'BASE64' )
samestr = eecdecode( encstr, 'BASE64' )
If samestr \== str Then Say 'error encoding/decoding'

4. Functions/Encrypt-Decrypt [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

The following functions encrypt and decrypt a string using a specified algorithm and key. They provide symmetrical encryption functionality.

USAGE

Provided the same algorithm and key are used: EECdecrypt( EECencrypt( str, 'mykey', 'DES' ), 'mykey', 'DES' ) == str

NOTES

All encryption algorithm encrypt data in chunks of various sizes. Any string not an exact multiple will have spaces appended before the encryption takes place. As a result of this behaviour it is not possible to decrypt a string to its original value without the appended spaces. To overcome this problem, the encryption mechanism in Rexx/EEC prepends 4 bytes to the beginning of the returned encrypted string which contains the original length of the string. This is used by the decryption function to return the exact length of the original string that was encrypted. The builtin DES encryption algorithm does not work on 64bit machines.

4.1. Encrypt-Decrypt/EECencrypt [ Functions ]

[ Top ] [ Encrypt-Decrypt ] [ Functions ]

NAME

EECencrypt

SYNOPSIS

encstr = EECencrypt( Str, Key[, Type] )

FUNCTION

Encrypts a Rexx string using the specified Key and encryption Type.

ARGUMENTS

RESULT

The encrypted string. If an error occurs during encryption, the return value will be blank and an error available in the variable !REXXEEC.!ERRMSG.

SEE ALSO

EECdecrypt

SOURCE

...
encstr = eecencrypt( 'my secret data', 'mykey, 'DES' )
If encstr = '' Then Say 'Error encrypting' !REXXEEC.!INTERRM

4.2. Encrypt-Decrypt/EECdecrypt [ Functions ]

[ Top ] [ Encrypt-Decrypt ] [ Functions ]

NAME

EECdecrypt

SYNOPSIS

str = EECdecrypt( EncStr, Key[, Type] )

FUNCTION

Decrypts a Rexx string using the specified Key and encryption Type.

ARGUMENTS

RESULT

The decrypted string. If an error occurs during decryption, the return value will be blank.

SEE ALSO

EECencrypt

SOURCE

...
str = eecdecrypt( '^^#((@#(', 'mykey' )
If str = '' Then Say 'Error decrypting' !REXXEEC.!INTERRM

5. Functions/Compress-Decompress [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

The following functions compress and decompress a string using the specified algorithm.

USAGE

Provided the same algorithm is used: EECdecompress( EECdecompress( str ) ) == str

NOTES

For types prefixed vy "I-", the length of the original string must be stored with the compressed string as the decompression mechanism has no way of knowing the original length of the string. Rexx/EEC prepends 4 bytes to the beginning of the returned compressed string which contains the original length of the string. Types prefixed by "I-" are intended to be used by Rexx/EEC only. Strings compressed by type I-ZLIB or I-GZIP can only be decompressed by Rexx/EEC unless the 4 bytes prepending the compressed data is removed. Display the internal Rexx variable !REXXEEC.!COMPRESS_TYPES for the list of supported compression algorithms supported.

5.1. Compress-Decompress/EECcompress [ Functions ]

[ Top ] [ Compress-Decompress ] [ Functions ]

NAME

EECcompress

SYNOPSIS

cmpstr = EECcompress( Str[, Type] )

FUNCTION

Compresses Str with the algorithm specified by Type.

ARGUMENTS

RESULT

The compressed string.

SEE ALSO

EECdecompress

SOURCE

...
cmpstr = eeccompress( 'my big, fat data' )
If cmpstr = '' Then Say 'Error compressing' !REXXEEC.!INTERRM

5.2. Compress-Decompress/EECdecompress [ Functions ]

[ Top ] [ Compress-Decompress ] [ Functions ]

NAME

EECdecompress

SYNOPSIS

str = EECdecompress( CmpStr[, Type] )

FUNCTION

Decompresses CmpStr with the algorith specified by Type.

ARGUMENTS

RESULT

The decompressed string.

SEE ALSO

EECcompress

SOURCE

...
str = eecdecompress( '*#*@', 'ZLIB' )
If str = '' Then Say 'Error decompressing' !REXXEEC.!INTERRM

6. Functions/General [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

The following functions are single direction algorithms that calculate various values.

6.1. General/EECcrc [ Functions ]

[ Top ] [ General ] [ Functions ]

NAME

EECcrc

SYNOPSIS

num = EECcrc( InStr[, Type[,Source]] )

FUNCTION

Calculates the CRC for the supplied string or file specified by Type

ARGUMENTS

NOTES

RESULT

The calculated CRC.

SOURCE

...
num = eeccrc( '*#*@', 16 )
Say 'CRC value is:' num

6.2. General/EECmd [ Functions ]

[ Top ] [ General ] [ Functions ]

NAME

EECmd

SYNOPSIS

num = EECmd( InStr, Type[, Source] )

FUNCTION

Calculates the Message Digest (MD) checksum for the supplied string or file

ARGUMENTS

RESULT

The calculated MD.

SOURCE

...
str = '*#*@'
hash = eecmd( str, 5 )
Say 'MD value of string' str 'is:' hash
...
filename = 'RexxEEC.tar.gz'
hash = eecmd( filename, 5, 'File' )
Say 'MD value of file' filename 'is:' hash

6.3. General/EEChtdigest [ Functions ]

[ Top ] [ General ] [ Functions ]

NAME

EEChtdigest

SYNOPSIS

num = EEChtdigest( Action, Filename, Username, Realm[, Password] )

FUNCTION

Provides similar functionality to the Apache htdigest command to manage passwords in a .htdigest file

ARGUMENTS

RESULT

0 on success, any other value an error

SEE ALSO

RFC2617

SOURCE

...
rcode = eechtdigest( 'Add', '.htdigest', 'mark', 'rexx.org' )
-- user will be prompted to enter password using keyboard
rcode = eechtdigest( 'Add', '.htdigest', 'mark', 'rexx.org', 'mypass' )
...
rcode = eechtdigest( 'C', '.htdigest', 'mark', 'rexx.org', 'newpass' )
...

6.4. General/EECsha [ Functions ]

[ Top ] [ General ] [ Functions ]

NAME

EECsha

SYNOPSIS

num = EECsha( InStr[, Type[, Source]] )

FUNCTION

Calculates the SHA1 hash for the supplied string or file

ARGUMENTS

RESULT

The calculated SHA1 or SHA256 hash as a hex value. To get the "real" hash value call x2c() on the result from EECsha.

SOURCE

...
str = '*#*@'
hash = eecsha( str )
Say 'SHA1 value (in hex) of string' str 'is:' hash
...
filename = 'RexxEEC.tar.gz'
hash = eecsha( filename, 1, 'File' )
Say 'SHA1 value (in hex) of file' filename 'is:' hash

7. Functions/PackageManagement [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

These functions are common to most Rexx external function packages.

7.1. PackageManagement/EECLoadFuncs [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

EECloadfuncs

SYNOPSIS

rcode = EECloadfuncs()

FUNCTION

Loads all other RexxEEC external functions

ARGUMENTS

None

RESULT

0 in all cases

SEE ALSO

EECdropfuncs

7.2. PackageManagement/EECdropfuncs [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

EECdropfuncs

SYNOPSIS

rcode = EECdropfuncs(["UNLOAD"])

FUNCTION

Cleans up RexxEEC environment and optionally will drop the external functions.

ARGUMENTS

RESULT

0 in all cases

SEE ALSO

EECloadfuncs

7.3. PackageManagement/EECvariable [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

EECvariable

SYNOPSIS

rcode = EECvariable(Variable [,NewValue])

FUNCTION

Get or set an internal RexxEEC variable.

ARGUMENTS

RESULT

When setting a variable, then 0 if success, any other value is an error When getting a variable, then the value of the variable is returned.

NOTES

The "Variable" argument can be one of:

      DEBUG (settable)
         0 - no debugging
         1 - all Rexx variables set by RexxEEC are displayed as they are set
         2 - all RexxEEC functions are traced on entry with argument values and
             on exit with the return value
         4 - all internal RexxEEC functions are traced with their arguments
             (really only useful for developers)
         The values can be added together for a combination of the above details.
      DEBUGFILE (settable)
         Where any debugging output is written. By default this goes to
         the system's error stream; usually 'stderr'.
      CONSTANTPREFIX (settable)
         The variable name prefix for all RexxEEC constants. By default this is
         '!REXXEEC.!'. If you change this, it is useful to make the prefix result
         in stemmed variables; this makes it far easier to EXPOSE these constants.
      VERSION (readonly)
         The full version details of RexxEEC in the format:
         package version version_date
         Where:
            package      - the string 'rexxeec'
            version      - package version in n.n format; eg 1.0
            version_date - date package was released in DATE('N') format

SOURCE

...
Say 'We are running at debug level:' EECvariable( 'DEBUG' )

7.4. PackageManagement/EECQueryFunction [ Functions ]

[ Top ] [ PackageManagement ] [ Functions ]

NAME

EECQueryFunction

SYNOPSIS

rcode = EECqueryfunction(FunctionName|ResultArray[, Option])

FUNCTION

Populates an array of all functions supplied by this package depending on Option

ARGUMENTS

RESULT

0 if successful or 1 if the FunctionName is not found

NOTES

To determine if a FunctionName can be executed in your code, pass the function name as the first argument, and 'R' as the second. If the function can be called the function returns 0, otherwise it returns 1