Copyright: MERXUtil Copyright(c) 1994 Wm. Potvin II
Citation: MERXUtil Copyright(c) 1994 Wm. Potvin II


Contents
 MERXUtil Version 0.1.10 (Beta)

A function package for Quercus Systems Personal Rexx for Microsoft Windows NT

Introduction

Release Notes

Support

Summary Descriptions

Contact Information

Copyright

Licence

Warranty

Notices


Copyright
 The MERXUtil Function Package for Personal Rexx for Windows NT is Copyright 1994 William Potvin II.  All Rights Reserved.


Quercus
Quercus Systems

P.O. Box 2157

Saratoga, CA  95070

(408) 867-REXX

(408) 867-7489 [FAX]


Charles
Quercus Systems


Stawsh
Enterprise Alternatives


Notices
Trademark Notices

Personal REXX is a trademark of Quercus Systems.

Microsoft, MS, Windows, Win32 and Windows NT are trademarks of Microsoft Corporation.

IBM, MVS, OS/2, TSO and TSO/E are trademarks of International Business Machines Corporation.

OS/2 is a registered trademark licenced to Microsoft Corporation.

Unix is a registered trademark of Unix Systems Laboratories.

CompuServe is a registered trademark of CompuServe, Inc.


cwin

Contents

Introduction

Release Notes

Support

Descriptions

Contact Info

Copyright

Licence

Warranty

Notices


Licence
 MERXUtil License

This Beta software is Copyright  1994 William Potvin II. All Rights Reserved.

The author of this Beta software will, as revisions evolve, make those revisions available via the Compuserve Information Service in the Quercus section, (Library 11), of the PCVENA forum.

The user may not develop applications based upon this Beta version software and distribute those applications, except for evaluation purposes ;  this is Beta software and must not be used for any critical applications.  It is very likely that some functions, particularly the System Services functions, will be renamed as this Beta progresses as a standard naming convention is established.


Warranty
 MERXUtil Warranty

This Beta software is provided by the author "as is" without any warranty of any kind, either expressed or implied, including, but not limited to, the fitness of this Beta software for a particular purpose or merchantability.  The user holds all risk with respect to the quality and performance of this Beta software and the user assumes all costs relative to all necessary servicing, repair or correction.

Under no circumstances will the author of this Beta software be liable to the user for any damages whatsoever, including general, incidental or consequential damages resulting from the use, or from the inability to use this Beta software, including, but not limited to loss of data or business profits or business interruption or a failure of this Beta software to operate with any other programs or any other pecuniary loss sustained by you or third party users, even if the author has been advised of the possibility of such damages.

This is Beta software; please regard it as such.


Contact
 The author may be contacted via email on CompuServe at 70540,120 or via email over the Internet at INTERNET:70540.120@compuserve.com


 Introduction

This is a Beta version of a function package for Personal Rexx for Microsoft Windows NT.  The intention is to offer a function package with functionality comparable to that of the REXXLIB package for OS/2 v2.x which is offered by Quercus Systems.  The current Beta release, 0.1.10, contains 55 functions which extend the Rexx Language, as implemented by Quercus Systems' Personal Rexx, within the Windows NT processing environment.  The Beta versions of MERXUtil are debug builds and the Beta package now includes a symbols file.

The functions provided by the MERXUtil Function Package are organized into the following groups:  Windows NT System functions, Transcendental Mathematical Functions, Complex Mathematical Functions, Dialog Functions and Miscellaneous Functions.

When Mike Cowlishaw created the Rexx Language, his primary design goal was to develop a language that was easy to learn and use for both computer professionals and general users alike.  This has also been the primary design goal for the MERXUtil Function Package; every effort is being made to make the functions provided by MERXUtil as easy and simple to use as possible.  There are no functions with complicated or unintuitive parameters, and the naming convention used attempts to be as clear and concise as possible.  Since this package is in Beta test, input from testers is imperative in order to insure that functions and their implementation do not become too obscure or difficult to use.

Input from Beta testers is also sought for new functions.  The MERXUtil User's Guide, contained in the Beta distribution, describes those areas of functionality already targeted.  In particular, comments regarding the use of Rexx for batch processing are encouraged.  One of the demo EXECs which accompanies the MERXUtil distribution shows how the ParseLine MERXUtil function can be used in combination with the Rexx Parse function to scan and tokenize MVS JCL.

Personal Rexx is an implementation of the Rexx Language for MS-DOS, MS Windows, MS Windows NT and IBM OS/2 v2.x.  Since you've downloaded this package, you must already own a copy of Personal Rexx, but I'll risk "preaching to the converted" by stating that, in my opinion, Personal Rexx is the finest implementation of the Rexx Language that exists.  Charles Daney and Stan Murawski have done a magnificent job of making Rexx accessible to users of those platforms.  I encourage you to use Rexx in general and Personal Rexx in particular.  I would also encourage you to join the Rexx Language Association.  A description of the Association, along with an application for membership form is available in the file REXXLA.TXT from the Quercus section, (Library 11), of PCVENA on CompuServe.

I also must make it clear that this Beta software is in no way connected with Quercus Systems or Enterprise Alternatives;  Please DO NOT bother either Charles or Stan with questions regarding this Beta.


Release Notes
 Release Notes for Release 0.1.10

The following functions have been added to MERXUtil with Release 0.1.10:

Windows NT System Functions:

RxNTMemory	memory information

RxNTDiskInfo	disk information

RxNTDiskType	disk type

RxNTEnvKeys	environmental variable names

RxNTEnvSize	environment size

RxNTEnvStrs	environment strings

RxNTEnvVal	environment variable value

RxNTGetDisks	disk drives on the system

RxNTUpTime	milliseconds the system has been up

RxNTVolumeInfo	volume information

Dialog Functions:

RxKillStatus	destroy a status box

RxShowStatus	create a status box

RxUpdateStatus	update a status box


 Summary Descriptions

Windows NT System Functions

Mathematical Functions

Complex Number Functions

Miscellaneous Functions

Dialog Functions


Windows NT System Functions
 Windows NT System Functions:

GetPID	get the current process id

Kill	terminate the given pid

ps	enumerates top-level windows

RxComputerName  	the computer name

RxNTDiskInfo	disk information

RxNTDiskType	disk type

RxNTEnvKeys	environmental variable names

RxNTEnvSize	environment size

RxNTEnvStrs	environment strings

RxNTEnvVal	environment variable value

RxNTGetDisks	disk drives on the system

RxNTMemory	memory information

RxNTUpTime	the milliseconds the system has been up

RxNTVersion	the current Windows NT version

RxNTVolumeInfo	volume information

RxSleep	stop execution for specified time

RxSystemInfo	hardware info

RxUserName	the user name

Start	start a process


Mathematical Functions
 Mathematical Functions:

Note that this section is not yet complete, however, most of the functions are relatively self explanatory.  The descriptions will be completed with the next Beta release.

Acos()	return arccosine

Asin()	return arcsine

Atan()	return arctangent

Atan2()	return arctangent

Cbrt()	return cube root

Ceil()	return smallest integer >= given value

Cos()	return cosine

Cosh()	return hyperbolic cosine

Cot()	return cotangent

Csc()	return cosecant

d2r()	convert degrees to radians

Exp()	return e raised to the given power

Floor()	return largest integer <= given value

Hypot()	return hypotenuse given two sides

Log()	return natural logarithm

Log10()	return base 10 logarithm

r2d()	convert radians to degrees

Sec()	return secant

Sin()	return sine

Sinh()	return hyperbolic sine

Sqrt()	return square root

Tan()	return tangent

Tanh()	return hyperbolic tangent


Complex Number Functions
 Complex Number Functions:

CAbs	return modulus

CAdd	return sum

CDiv	return quotient

CMul	return product

CSub	return difference


Miscellaneous Functions
 Miscellaneous Functions:

About	display an "about" box

GetUsage	get number of processes using the MERXUtil dll

Load	registers all of the functions

ParseLine	strtok for EXECs

UnLoad	de-registers all of the functions


Dialog Functions
 Dialog Functions:

RxKillStatus	destroy a status box

RxShowStatus	create a status box

RxUpdateStatus	update a status box


 GetPID

The GetPID function returns the process identifier for the current process.

Parameters

This function has no parameters

Return Value

A hexidecimal value representing the process identifier of the current process

Comments

Use the GetPID function to retrieve a process identifier for any function that requires such an identifier.

Usage

my_pid = GetPID()

See Also

Kill, ps


Kill
 Kill( pid )

The Kill function terminates the given process identifier.

Parameters

pid

    Identifies the process to terminate.

Return Value

Either OK for success, or ERROR for failure.

Comments

The Kill function will terminate the current process, however it is recommended that the current process be terminated via an EXIT instruction.

This function uses the Win32 TerminateProcess API call to perform the process termination.  Consequently, the same usage cautions associated with the TerminateProcess call apply to the Kill function.  This function unconditionally  terminates a process and all of its associated threads.  It is very important to note that no DLLs which may be attached to the specified process are notified that the process is terminating.  As a result, any global data maintained by DLLs may be compromised by using the Kill function.

Use this function only as a last resort.

It is also important to note that Kill does not necessarily remove a process from the system.  The system will not delete the process until the last open handle to that process is closed.

Usage

ret_code = Kill( pid )

See Also

GetPID, ps


ps
 ps( stem. )

The ps function enumerates the top-level windows in the system and returns process information in the specified stem variable.  Information returned is in the form:

hwnd pid ttime ktime utime name

hwnd    	- window handle

pid     	- process id

ttime   	- total execution time, (ktime + utime)

ktime   	- kernel mode execution time

utime   	- user mode execution time

name    - window title bar text

Parameters

stem.

    A compound variable name to be filled with process information.

Return Value

Either OK for success, or ERROR for failure.

Comments

The returned compound variable is integer-based with stem.0 containing the count of items in the "array".

For simplicities sake, this function enumerates the top level windows on the system and returns information about them.  This function does NOT list every process on the system.  If the need arises, then an additional function will be included which, via the registry, will return information about all processes active on the system.  Such a function is, however, extremely resource intensive and consumes several seconds in order to retrieve the necessary information.

Usage

The following example illustrates the ps function:

ret_code = ps( ps_list. )

if ret_code = 'OK' then

    do i=1 to ps_list.0

        parse var ps_list.i hwnd pid ttime ktime utime pname

        say '>' hwnd pid ttime pname

    end

else

    say 'call to ps() failed.'

See Also

GetPID, Kill


 RxComputerName

The RxComputerName function returns the computer name of the current system as initialized via the registry at system startup.

Parameters

This function has no parameters.

Return Value

A string representing the computer name.

Comments

Use the RxComputerName function to retrieve a computer name for any function which requires such a name.

Usage

computer_name = RxComputerName()

See Also


RxNTDiskInfo
 RxNTDiskInfo( root_dir )

The RxNTDiskInfo function returns disk drive information in the following form:

root sec_cluster byte_sector f_cluster t_cluster

root	- root path name

sec_cluster	- sectors per cluster

byte_sector	- bytes per sector

f_cluster	- free clusters

t_cluster	- total clusters

Parameters

root_dir

    Optionally specifies the root directory of the desired disk drive.

Return Value

A string containing the disk drive information.

Comments

If no root_dir  is specified, then the current drive is used.

Usage

disk_info = RxNTDiskInfo()

See Also

RxNTDiskType, RxNTGetDisks, RxNTVolumeInfo


RxNTDiskType
 RxNTDiskType( root_dir )

The RxNTDiskType function returns disk type information.

Parameters

root_dir

    Optionally specifies the root directory of the desired disk drive.

Return Value

A string containing the disk type.

Comments

If no root_dir is specified, then the current drive is used. The returned string will contain one of the following values:

UNKNOWN

NOROOT

REMOVABLE

FIXED

REMOTE

CDROM

RAMDISK

Usage

disk_type = RxNTDiskType()

See Also

RxNTDiskInfo, RxNTGetDisks, RxNTVolumeInfo


 RxNTGetDisks

The RxNTGetDisks function returns a string containing drive strings for each disk drive on the system.  The string is in the form:

drive drive drive ...

Where drive could be a:\, b:\, c:\, etc.

Parameters

This function has no parameters.

Return Value

A string containing drive strings for each drive on the system.

Comments

Use this function to retrieve drive strings for any function which requires a drive string as an argument.

Usage

disks = RxNTGetDisks()

See Also

RxNTDiskInfo, RxNTDiskType, RxNTVolumeInfo


RxNTEnvKeys
 RxNTEnvKeys( stem. )

The RxNTEnvKeys function returns the specified stem variable filled with all of the environment string keys in the system for the current login.

Parameters

stem.

    Specifies the stem variable into which the keys should be written.

Return Value

Either OK for success, or ERROR for failure.

Comments

Use this function to obtain a list of all of the environment variable names.

Usage

ret_code = RxNTEnvKeys( env_keys. )

See Also

RxNTEnvSize, RxNTEnvStrs, RxNTEnvVal


  RxNTEnvSize

The RxNTEnvSize function returns the size, in decimal bytes, of the current user's environment.

Parameters

This function has no parameters.

Return Value

A string representing the size, in decimal bytes, of the current environment.

Comments

Use this function to obtain the size of the current environment.

Usage

ret_code = RxNTEnvSize()

See Also

RxNTEnvKeys, RxNTEnvStrs, RxNTEnvVal


RxNTEnvStrs
  RxNTEnvStrs( stem. )

The RxNTEnvStrs function returns the specified stem variable filled with all of the environment strings in the system for the current login.

Parameters

stem.

    Specifies the stem variable into which the strings should be written.

Return Value

Either OK for success, or ERROR for failure.

Comments

Use this function to obtain a list of all of the environment variables.

Usage

ret_code = RxNTEnvStrs( env_strings. )

See Also

RxNTEnvKeys, RxNTEnvSize, RxNTEnvVal


RxNTEnvVal
 RxNTEnvVal( env_var  )

The RxNTEnvVal function returns the value of the specified environment variable.

Parameters

env_var

    Specifies the environment variable for which to return a value.

Return Value

A string representing the value of the specified environment variable.

Comments

Use this function to obtain the value of a environment variable.

Usage

ret_code = RxNTEnvVal( COMSPEC )

See Also

RxNTEnvKeys, RxNTEnvSize, RxNTEnvStrs


 RxNTUpTime

The RxNTUpTime function returns the number of milliseconds that Windows NT has been running on the current system.

Parameters

This function has no parameters.

Return Value

A string representing the number of milliseconds the system has been running.

Comments

The internal counter wraps about every 49.7 days of continuous operation.

(REF: Win32 PR, vol 3, pg 714, "GetTickCount")

Usage

tick_count = RxNTUpTime()

See Also


 RxNTVersion

The RxNTVersion function returns the version of Windows that is currently running, as well as the operating system platform.  The returned string will be of the following form:

[WinNT | Win32s] version_major.version_minor

Parameters

This function has no parameters.

Return Value

A string containing the operating system platform and the Windows version number.

Comments

Use this function to obtain both platform and version information for Windows.  This function does not return MS-DOS version numbers.

Usage

version = RxNTVersion()

See Also


RxNTVolumeInfo
 RxNTVolumeInfo( root_dir )

The RxNTVolumeInfo function returns volume information in the following form:

root name volser fname_clen flags filesys_name

root	- root path name

name	- volume name

volser	- volume serial number

fname_clen	- file name component length

flags	- flags:  hexidecimal combination of the following,

  FS_CASE_SENSITIVE	0x00000001

  FS_CASE_IS_PRESERVED	0x00000002

  FS_UNICODE_STORED_ON_DISK	0x00000004

filesys_name	- file system name, i.e. FAT, NTFS or HPFS

Parameters

root_dir

    Optionally specifies the root directory of the desired disk drive.

Return Value

A string containing the volume information.

Comments

If no root_dir is specified, then the current drive is used.  The returned flag value is expressed in hexidecimal and is based upon the current release of the Win32 SDK and may likely change with future releases of Windows NT.

Usage

vol_info = RxNTVolumeInfo()

See Also

RxNTDiskInfo, RxNTDiskType, RxNTGetDisks


RxSleep
 RxSleep( msecs )

The RxSleep function suspends execution of the EXEC for the specified number of milliseconds.

Parameters

msecs

    The number of milliseconds to suspend execution of the EXEC.

Return Value

Either OK for success, or ERROR for failure.

Comments

This function is identical in functionality to the built-in Delay function, except that RxSleep allows the specification of time in milliseconds as opposed to seconds.

Usage

ret_code = RxSleep( 100 )

See Also


 RxSystemInfo

The RxSystemInfo function returns hardware information about the running system in the form:

oemid numpro typpro mskpro pagesize minappaddr maxappaddr

oemid	- OEM id

numpro	- Number of Processors

typpro	- Processor Type

mskpro	- Active Processor Mask

pagesize	- Page Size

minappaddr	- Minimum Application Address

maxappaddr	- Maximum Application Address

Parameters

This function has no parameters.

Return Value

A string containing the hardware information.

Comments

Use this function to obtain hardware information about the active system.

Usage

sysinfo = RxSystemInfo()

See Also


 RxUserName

The RxUserName function returns the logon name of the current user.

Parameters

This function has no parameters.

Return Value

A string representing the current user name.

Comments

This function uses the Win32 GetUserName API call.  If the current thread is impersonating another client, the user name returned is that of the impersonated client.

Usage

user = RxUserName()

See Also


Start
 Start( cmdline, title, show_option, wait_flag )

The Start function creates a new process.

Parameters

cmdline

    Specifies the command line, including arguments, to be used to create the new process.

title

    Optionally specifies a title to place on the title bar of the new processes window.

show_option

    Optionally specifies the initial state of the new processes window.  If specified, show_option must be one of the following:

[MINIMIZED | MAXIMIZED | NORMAL]

wait_flag

    Optionally specifies synchronous or asynchronous creation.  If specified, the wait_flag is indicated with:

WAIT

Return Value

The return value is the process identifier of the created process.

Comments

Calling the Start function with no arguments causes a command process to be started.  The title parameter is valid only with respect to console applications; for GUI apps, it is ignored.  The default show_option parameter is NORMAL.  The show_option parameters as well as the wait_flag parameter may be abbreviated to their first three characters.  If the wait_flag is specified, then the process identifier returned is no longer a valid process identifier since the process has terminated.  It is returned for informational purposes only.

Usage

Following are examples of the use of the Start function:

/* start a command processor. */

pid = Start()

/*

 * start a command processor and

 * wait util it terminates.

 */

pid = Start(,,,wait)

/*

 * start Personal Rexx in a maximized window, run

 * the test.rex EXEC and wait until it completes.

 */

pid = Start( 'prexxw test.rex',, MAX, WAIT )

/*

 * start the Personal Rexx command line version,

 * run the test.rex EXEC, apply the title "test run"

 * to the command window and return immediately.

 */

pid = Start( 'rexx test.rex', 'test run' )

/*

 * start a server application in a minimized

 * window.

 */

pid = Start( 'server',,MINIMIZED )

/*

 * start a client application and wait for it

 * to terminate.

 */

pid = Start( 'client',,,wai )

See Also

Kill, ps


Acos( n )

The Acos function returns the arccosine of the specified value.

Parameters

n

    Specifies the value, in the range -1 <= n < 1, for which to return the arccosine.

Return Value

A string representing the arccosine of the specified value.

Comments

If the specified value is not within the range -1 <= n < 1, this function returns "DOMAIN ERROR".  The value returned is in the range 0 <= return_val <= pi.

Usage

acos_val = Acos( .875 )

See Also

Asin, Atan, Atan2, Cos, Cosh, Sin, Sinh, Tan, Tanh


Asin( n )

The Asin function returns the arcsine of the specified value.

Parameters	n

    Specifies the value, in the range -1 <= n < 1, for which to return the arcsine.

Return Value	A string representing the arcsine of the specified value.

Comments	If the specified value is not within the range -1 <= n < 1, this function returns 	"DOMAIN ERROR".  The value returned is in the range -pi/2 <= return_val <= pi/2.

Usage	asin_val = Asin( .14392 )

See Also	Acos, Atan, Atan2, Cos, Cosh, Sin, Sinh, Tan, Tanh


Atan( n )

The Atan function returns the arctangent of the specified value.

Parameters	n

    Specifies the value for which to return the arctangent.

Return Value	A string representing the arctangent of the specified value.

Comments	The value returned is in the range -pi/2 <= return_val <= pi/2.

Usage	atan_val = Atan( 1.234 )

See Also	Acos, Asin, Atan2, Cos, Cosh, Sin, Sinh, Tan, Tanh


Atan2( x, y )

The Atan2 function returns the arctangent of x / y.

Parameters	x, y

    Real numbers specifying the value for which to return the arctangent.

Return Value	A string representing the arctangent of the x / y..

Comments	The value returned is in the range -pi <= return_val <= pi.

Usage	atan2_val = Atan2( x, y )

See Also	Acos, Asin, Atan, Cos, Cosh, Sin, Sinh, Tan, Tanh


Cbrt( n )

The Cbrt function returns the cube root of the specified value.

Parameters	n

    Specifies a real number for which to return the cube root.

Return Value	A string representing the cube root of the specified value.

Comments	The argument n  passed to this function must be in the range:

- 1.175494351e-38 <= n <= 3.402823466e+38

These are the values for FLT_MIN and FLT_MAX defined by Microsoft's

Standard C Library for Windows NT.  For values outside of this range, the

function returns DOMAIN ERROR.  The cube root is obtained by factoring

out powers of 2 from n  until the resulting value is less than 1.  The cube

root is then calculated for the new value using Newton's Method:

          f(xn)

xn+1 = xn

          f(xn)

over five iterations, with f(x) = x3n, with an initial starting point of 0.737

Usage	cbrt_val = cbrt( 125 )

See Also	sqrt


Ceil( n )

The Ceil function returns the smallest integer that is greater than or equal to

the specified value.

Parameters	n

    Specifies the value for which to calculate the ceiling.

Return Value	A string representing the smallest integer greater than or equal to n.

Comments

Usage	ceil_val = Ceil( 1.237 )

See Also	floor


Cos( n )

The Cos function returns the cosine of the specified value.

Parameters	n

    Specifies the value for which to calculate the cosine.

Return Value	A string representing the cosine of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	cos_val = Cos( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cosh, Sin, Sinh, Tan, Tanh


Cosh( n )

The Cosh function returns the hyperbolic cosine of the specified value.

Parameters	n

    Specifies the value for which to calculate the hyperbolic cosine.

Return Value	A string representing the hyperbolic cosine of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	cosh_val = Cosh( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cos, Sin, Sinh, Tan, Tanh


Cot( n )

The Cot function returns the cotangent of the specified value.

Parameters	n

    Specifies the value for which to calculate the cotangent.

Return Value	A string representing the cotangent of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	cot_val = Cot( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Csc, Sec


Csc( n )

The Csc function returns the cosecant of the specified value.

Parameters	n

    Specifies the value for which to calculate the cosecant.

Return Value	A string representing the cosecant of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	csc_val = Csc( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Cot, Sec


d2r( n )

The d2r function converts degrees to radians.

Parameters	n

    Specifies the value in degrees to convert.

Return Value	A string representing the radian equivalent of n.

Comments	The value returned is in standard floating point format.

Usage	rad = d2r( 30 )

See Also	r2d


Exp( n )

The Exp function raises e  to the specified power.

Parameters	n

    Specifies the power to which e is to be raised.

Return Value	A string representing en.

Comments	If n is too large, the function returns RANGE ERROR.

Usage	e_to_n = Exp( 3.14 )

See Also	Log, Log10


Floor( n )

The Floor function returns the largest integer less than or equal to the specified

value.

Parameters	n

    Specifes the value for which to find the floor.

Return Value	A string representing the largest integer less than or equal to n.

Comments

Usage	floor_val = Floor( 3.14 )

See Also	Ceil


Hypot( a, b )

The Hypot function returns the length of the hypotenuse of a triangle given the

lengths of the two sides.

Parameters	a

    Specifies the length of one side of the triangle

b

    Specifies the length of the second side of the triange.

Return Value	A string representing the length of the hypotenuse.

Comments	The function returns RANGE ERROR if an overflow results.  Calling this function

is equivalent to evaluating sqrt( (a**2)+(b**2) ).

Usage	c_side = Hypot( a_side, b_side )

See Also	Abs


Log( n )

The Log function returns the natural logarithm of the specified value.

Parameters	n

    Specifies the value for which to calculate the natural logarithm.

Return Value	A string representing the natural logarithm of the specified value.

Comments	If n is negative, then the function returns DOMAIN ERROR.  If n is

zero, then the function returns INFINITY.

Usage	log_val = Log( 3.14 )

See Also	Log10, Exp


Log10( n )

The Log10 function returns the base-10 logarithm of the specified value.

Parameters	n

    Specifies the value for which to calculate the base-10 logarithm.

Return Value	A string representing the base-10 logarithm of the specified value.

Comments	If n is negative, then the function returns DOMAIN ERROR.  If n is

zero, then the function returns INFINITY.

Usage	log10_val = Log10( 3.14 )

See Also	Log, Exp


r2d( n )

The r2d function converts radians to degrees.

Parameters	n

    Specifies the value in radians to convert.

Return Value	A string representing the degree equivalent of n.

Comments	The value returned is in standard floating point format.

Usage	deg = r2d( 1.57 )

See Also	d2r


Sec( n )

The Sec function returns the secant of the specified value.

Parameters	n

    Specifies the value for which to calculate the secant.

Return Value	A string representing the secant of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	sec_val = Sec( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Cot, Csc


Sin( n )

The Sin function returns the sine of the specified value.

Parameters	n

    Specifies the value for which to calculate the sine.

Return Value	A string representing the sine of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	sin_val = Sin( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cos, Cosh, Sinh, Tan, Tanh


Sinh( n )

The Sinh function returns the hyperbolic sine of the specified value.

Parameters	n

    Specifies the value for which to calculate the hyperbolic sine.

Return Value	A string representing the hyperbolic sine of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	sinh_val = Sinh( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cos, Cosh, Sin, Tan, Tanh


Sqrt( n )

The sqrt function returns the square root of the specified value.

Parameters	n

    Specifies the value for which to calculate the square root.

Return Value	A string representing the square root of the specified value.

Comments	if n is negative, the function returns DOMAIN ERROR.

Usage	sqrt_val = sqrt( 25 )

See Also	cbrt


Tan( n )

The Tan function returns the tangent of the specified value.

Parameters	n

    Specifies the value for which to calculate the tangent.

Return Value	A string representing the tangent of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	tan_val = Tan( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cos, Cosh, Sin, Sinh, Tanh


Tanh( n )

The Tanh function returns the hyperbolic tangent of the specified value.

Parameters	n

    Specifies the value for which to calculate the hyperbolic tangent.

Return Value	A string representing the hyperbolic tangent of the specified value.

Comments	If the n is so large that significance is lost, then RANGE ERROR is

returned.

Usage	tanh_val = Tanh( ( 3*3.1415927 )/2 )    /* 3pi/2 /

See Also	Acos, Asin, Atan, Cos, Cosh, Sin, Sinh, Tan


CAdd
 CAdd( i, j  )

The CAdd function adds two complex numbers.

Parameters

i, j

    Specifies the two complex numbers to add.

Return Value

A string representing the sum of the two specified complex numbers.

Comments

The value returned is a complex number of the form a+bi.

All of the complex number functions require that their arguments be quoted.  For example: '2-6i' or '7+2j', etc.

Usage

c_sum = CAdd( '1+2i', '3+4i' )

See Also

CSub, CMul, CDiv, CAbs


CSub
 CSub( i, j  )

The CSub function subtracts two complex numbers.

Parameters

i, j

    Specifies the two complex numbers to subtract.

Return Value

A string representing the difference between the two specified complex numbers.

Comments

The value returned is a complex number of the form a+bi.

All of the complex number functions require that their arguments be quoted.  For example: '2-6i' or '7+2j', etc.

Usage

c_sub = CSub( '1+2i', '3+4i' )

See Also

CAdd, CMul, CDiv, CAbs


CMul
 CMul( i, j  )

The CMul function forms the product of two complex numbers.

Parameters

i, j

    Specifies the two complex numbers to multiply.

Return Value

A string representing the product of the two specified complex numbers.

Comments

The value returned is a complex number of the form a+bi.

All of the complex number functions require that their arguments be quoted.  For example: '2-6i' or '7+2j', etc.

Usage

c_mul = CMul( '1+2i', '3+4i' )

See Also

CAdd, CSub, CDiv, CAbs


CDiv
 CDiv( i, j  )

The CDiv function divides two complex numbers.

Parameters

i, j

    Specifies the two complex numbers to divide.

Return Value

A string representing the quotient of the two specified complex numbers.

Comments

The value returned is a complex number of the form a+bi.

All of the complex number functions require that their arguments be quoted.  For example: '2-6i' or '7+2j', etc.

Usage

c_div = CDiv( '1+2i', '3+4i' )

See Also

CAdd, CSub, CMul, CAbs


CAbs
 CAbs( i  )

The CAbs function calculates the absolute value, or modulus, of the specified complex number.

Parameters

i

    Specifies the complex number for which to find the modulus.

Return Value

A string representing the modulus of the specified complex number.

Comments

The value returned is a complex number of the form a+bi.

All of the complex number functions require that their arguments be quoted.  For example: '2-6i' or '7+2j', etc.

Usage

c_abs = CAbs( '1+2i' )

See Also

CAdd, CSub, CMul, CDiv


RxKillStatus
 RxKillStatus( hwnd_status )

The RxKillStatus function destroys the Status Box identified by the specified window handle.

Parameters

hwnd_status

    Specifies the window handle of the Status Box to destroy.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

Usage

ret_code = RxKillStatus( status_hwnd )

See Also

RxShowStatus, RxUpdateStatus


RxShowStatus
 RxShowStatus( title, message )

The RxShowStatus function creates and displays a Status Box with the specified title and message.

Parameters

title

    Specifies the title for the Status Box, a maximum of 20 characters.

message

    Specifies the initial message to display in the Status Box, a maximum of 250 characters.

Return Value

The function returns a string representing the window handle of the Status Box created, or NULL if an error was encountered.

Comments

Usage

status_hwnd = RxShowStatus( 'Processing...', 'Please Wait!' )

See Also

RxKillStatus, RxUpdateStatus


RxUpdateStatus
 RxUpdateStatus( hwnd_status, message )

The RxUpdateStatus function updates the Status Box specified with the specified message.

Parameters

hwnd_status

    Specifies the window handle of the Status Box to update.

message

    Specifies the message to display in the Status Box, a maximum of 250 characters.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

Usage

ret_code = RxUpdateStatus( status_hwnd, new_msg )

See Also

RxKillStatus, RxShowStatus


About
 About( product_name, description, icon_flag )

The About function displays a standard "About" box, optionally specifying information about your Rexx application.

Parameters

product_name

    Optionally specifies a product name for your Rexx application.

description

    Optionally specifies a short description of your Rexx application.

icon_flag

    Specifies whether to use the Microsoft Windows default icon, or the MERXUtil default icon.  To specify the Microsoft Windows default icon, specify icon_flag  as:

STDICON

    Otherwise, for the MERXUtil default icon, leave icon_flag blank.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

If product_name is specified, then description must also be specified.

Usage

rc = About( 'MyProduct', 'MyDescription' )

rc = About( "", "", STDICON )

rc = About()

See Also


 GetUsage

The GetUsage function returns the number of processes currently using the MERXUtil Function Package.

Parameters

This function has no parameters.

Return Value

A string representing the number of processes using the DLL.

Comments

This function appears to be unuseful.  As a consequence, it will likely be removed for the General Release.  Please comment.

Usage

usage = GetUsage()

See Also


ParseLine
 ParseLine( input, "tokens", destination. )

The ParseLine function parses the specified string using the specified token delimiters and fills the specified stem variable with the results.

Parameters

input

    Specifies the input string.

"tokens"

    Specifies the tokens with which to delimit the string.

destination.

    Specifies the stem variable into which the results should be placed.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

The tokens argument must be enclosed in quotes.  The resulting tokens are placed into the destination stem variable with destination.0 holding the number of tokens

Usage

Given this code segment:

input = "start device,address=all,opt=force"

rc = ParseLine( input, " \t,=", tokens. )

if rc == 'OK' then do

    do i=0 to tokens.0

        say tokens.i

    end

end

The following output is produced:

6

start

device

address

all

opt

force

See Also


 Support

This software is developed in my "spare" time.  As a consequence, support for this Beta, as well as for any marketable product that may result from this Beta, is limited to electronic mail.  Telephone support is, unfortunately, out of the question at this time.  I may be reached via Compuserve mail in the following manner:

70540,120

or, via the Internet

70540.120@compuserve.com

In addition, I can frequently be found in the Quercus message area of PCVENA on Compuserve, however, I would prefer that any support questions be directed via email so as not to clutter up the Quercus forum.  As stated previously, this Beta software is in no way connected with either Quercus Systems or Enterprise Alternatives; DO NOT bother either Charles or Stan with questions about this software.

Finally, one of my biggest difficulties with this package is in deciding what features to implement.  Your feedback is crucial, both in terms of bug reports, as well as to suggest new features.  Many times I'll think on a feature and dismiss it because I couldn't think of a good use for it, but you may have a good use that I couldn't think of.  Additionally, please take a few seconds to review the evolution section of this document and consider the functionality described there.  Please note anything in that section that would not be useful and be liberal in your feedback; I look forward to hearing from all of you.


 RxNTMemory

The RxNTMemory function returns information about currently available physical and virtual memory.  The information returned is in the following form:

t_phys a_phys t_page a_page t_virt a_virt load

t_phys	- total physical memory

a_phys	- available physical memory

t_page	- total pagefile memory

a_page	- available pagefile memory

t_virt	- total virtual memory

a_virt	- available virtual memory

load	- memory load: [0..100]

0=not busy and 100=very busy

Parameters

This function has no parameters.

Return Value

A string containing the memory information.

Comments

The information retrieved by this function is updated continuously.  There is no guarantee that two successive calls will return the same information.

Usage

memory = RxNTMemory()

See Also


 Unload

The UnLoad function de-registers all of the MERXUtil functions with the Rexx Interpreter.

Parameters

This function has no parameters.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

Usage

ret_code = UnLoad()

See Also

Load


 Load

The Load function registers all of the MERXUtil functions with the Rexx Interpreter.

Parameters

This function has no parameters.

Return Value

The function returns OK for success, or ERROR if unsuccessful.

Comments

Usage

ret_code = Load()

See Also

Unload