The uni-REXX Sample Library provides a variety of sample applications that illustrate a number of possible uses of Rexx in the UNIX environment. Many of the samples may be used immediately, exactly as they appear in the sample directories. They may also be adapted to your specific needs. Others illustrate the use of certain features of the language or provide electronic versions of examples included in the uni-REXX Reference Manual. The sample library is located in the directory samples.rx in the directory where uni-REXX is installed at your site (default: /usr/local/rexx). Within samples.rx the various types of samples are organized into the following directories:

You may download the files directly from these pages using "Save As". Or you may download a compressed tar file that contains all the samples .

functions

useful functions which may be called from any uni-REXX program; also includes a math function package that may be added to your interpreter

filters

useful filters that accept input from STDIN or from a pipe and send output to STDOUT, which may be redirected to a file or piped to another command or program

utilities

general-purpose programs which may be used alone or called from other programs; includes a system administration tool for AIX/3, a program to perform the equivalent of the UNIX 'which' command, a program to replace a line in an existing fi le, and many more

api.samples

all the examples from the reference manual chapter on Application Programming Interfaces (APIs), and a program to build the examples on your system

extensions.samples

the example applications from the reference manual chapter on UNIX-Specific Extensions and programs to build them on your system

The sections that follow document each of these sample types. For those samples that require you to generate a particular application, instructions for running the automated build procedures are also included.

Functions

The files in this directory that end with the extension ".rex" are uni-REXX functions that may be useful in your applications. Each of these functions is described briefly below. Comments in the source programs provide additional informati on.

fn.rex

converts a system-independent file specification into a local filename

grepper.rex

a specialized string search facility

remove@.rex

converts email addresses from the form "person@place" to the form "place!person"

Also included in this directory is a math function package that provides trigonometric functions, square- and cube-root functions, exponential function, and natural logarithm. The function package is written in C and may be added to the uni-REXX interpreter. This also illustrates the process of extending uni-REXX by adding your own functions written in C or another compiled language. The components of the package are

math.c

C language source file containing function package

mathbld

a Rexx program to compile math.c and generate a new interpreter

testmath

a Rexx program illustrating the use of the math functions

The syntax of mathbld is

       mathbld [ -h]

The -h option displays help on how to run mathbld. When is omitted, mathbld generates a new interpreter, named rxxm, that includes the math functions. Note: HP-UX sites should read the comments in math.c and make a required change before running mathbld. To run testmath, type

        rxxm testmath 

The uni-REXX math function package is distributed on an as-is basis. It merely exposes the C library functions to Rexx programs. In some cases, this does return exact answers. We hope that this package will be of use for some applicatio ns but urge you to verify your results the first time you use it for a specific application.

Filters

Filters accept input from STDIN or a pipe and send output to STDOUT, which may be redirected to a pipe or a file. This directory contains some useful Rexx filter programs. Each of these filters is described briefly below. Comments in the source programs provide additional details.

backspace

remove embedded backspace characters from a file

box

replace characters used to simulate boxes with actual line-drawing characters for boxes

mult

outputs all lines from input that contain one or more specified strings

upcase

converts all alphabetic characters in a file to uppercase

vptrim

removes Ventura Publisher markup strings from a word processing file

Utilities

Utility programs are general purpose programs that may be executed alone or called by other Rexx programs. This directory contains some useful utilities, each of which is described briefly below. Comments in the source programs provide add itional details.

dbxw

invokes dbx on a program in a different window

fi

cover for the UNIX "find" command

fldfit

formats a number to fit a field of a specified length

make_user

automates creation of new userids for AIX

rlp

print on a remote host

sieve

finds all prime numbers within a specified range

tree

prints visual depiction of directory structure

whichdir

identifies first occurrence of specified filename in directories included in the PATH environment variable; similar to the UNIX "which" command, which may not be present in all UNIX implementations

write

replaces a specific line in a file with new data

API Samples

Samples in this directory illustrate each of the uni-REXX Application Programming Interfaces (APIs) documented in Chapter 7 of the uni-REXX Reference Manual. They are the same examples as those presented in the manual. You may download a compressed tar file that contains all the API samples .

The uni-REXX program "apibld" presents a menu from which you may

• select a specific example to build
• build all examples
• clean up the directory by removing any binaries that have been created

You may invoke apibld in any of the following ways:

       apibld [ -h]
              [option]
              [program]

Without operands, apibld displays a menu for selecting which sample to build. -h provides help on the syntax and use of apibld. option is any valid option number from the main menu. program is the name of one of the sample programs as shown on the main menu

To execute the sample you have built, type the name shown in the rightmost column of the apibld menu.

UNIX-Specific Extensions

Samples in this directory illustrate the following UNIX-specific extensions to uni-REXX:

• UNIX-specific functions, illustrated in a client/server application that processes modem requests for an entire network

• creating your own programs/commands with the uni-REXX interprocess communication library

In both cases, the samples provided are the same as the ones shown in the uni-REXX Reference Manual.

Running the Network Modem Manager This application uses the following files:

mods

the modem server daemon

modc

the modem allocation request client

sendbuf

package and transmit a message between client and server

recvbuf

receive and unpack a message

modem.list

configuration file of available modems

The programs are configured to allow you to easily test this client/server application on a single workstation. If you want to test it across multiple workstations, you must modify line 27 the program modc. Comments in modc tell you exac tly what to do. Both the server program (mods) and the client program (modc) have as their first line an implicit execution string that points to the rxx interpreter in /usr/local/rexx. If you do not have uni-REXX installed in this location or if your platform does not support implicit invocation strings, you must change or delete this line.

To start the server, type

       mods

The server runs as a daemon on the workstation where you started it. It displays a message giving you the process-id of the server so that you can easily kill the daemon when you have finished testing.

The client may be used to request a modem or to free an assigned modem. The syntax is

       modc get  n
            free hostname device

Use get to request a modem allocation. n is the desired baud-rate of the modem you wish to have assigned. The modem assigned will be the first free modem that has a baud rate greater than or equal to the requested spee d. The reply message, assigning a modem, is in the form

 hostname device modem_initialization_string

Use free to release an assigned modem after your use is complete. hostname and device are the names previously assigned in response to the "get" request. This sample modem management service is very rudimentary and intended only to illustrate what can be done with some of the UNIX-specific functions in uni-REXX. It may be used as a model for developing your own client/server applications in uni-REXX. Building Programs/Commands with the uni-REXX Interprocess Communication Library Chapter 7 of the uni-REXX Reference Manual includes a section describing interprocess communication with uni-REXX. The example in that section and in this directory is "rxqueue", modeled after the OS/2 feature of the same name. It copies its standard output to the uni-REXX program stack. Files associated with this sample are

rxqueue.c

source code for rxqueue

mkrxq

make file to build the binary

rxqbld

uni-REXX program that prompts you for the location of required files and runs the make

testrxq

test file that demonstrates how rxqueue works

To build rxqueue for your system, type

       rxqbld

For help with rxqbld, type

       rxqbld -h

To test rxqueue, type

       testrxq