Rexx/EEC
Version 1.0
Copyright (C) 2008 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 UUencoded format. UUencoding is a mechanism to convert 8 bit characters into 7 bit characters. As a result the encoded string is longer than the raw string.

USAGE

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

NOTES

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 )

FUNCTION

Encodes Str to a 7-bit string.

ARGUMENTS

RESULT

Str uuencoded or blank if an error.

SEE ALSO

EECdecode, !REXXEEC.!INTERRM

SOURCE

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

3.2. Encode-Decode/EECdecode [ Functions ]

[ Top ] [ Encode-Decode ] [ Functions ]

NAME

EECdecode

SYNOPSIS

str = EECdecode( EncStr )

FUNCTION

Decodes EncStr to an 8-bit string.

ARGUMENTS

RESULT

EncStr uudecoded or blank if an error.

SEE ALSO

EECencode, !REXXEEC.!INTERRM

SOURCE

...
str = 'This is my string.'
encstr = eecencode( str )
samestr = eecdecode( encstr )
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

The DES encryption algorithm encrypts data in chunks of 8 bytes. Any string not exactly a multiple of 8 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 DES 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 DES 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 a specified algorithm.

USAGE

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

NOTES

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. ZLIB compression is builtin. Other compression mechanisms may be availabe depending on the support offered by your platform. See !REXXEEC.!COMPRESS_TYPES.

5.1. Compress-Decompress/EECcompress [ Functions ]

[ Top ] [ Compress-Decompress ] [ Functions ]

NAME

EECcompress

SYNOPSIS

cmpstr = EECcompress( Str[, Type] )

FUNCTION

Compresses Str with the algorith 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/PackageManagement [ Modules ]

[ Top ] [ Modules ]

DESCRIPTION

These functions are common to most Rexx external function packages.

6.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

6.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

6.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' )

6.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