IBM Object REXX for Linux(tm) on Intel(tm) Readme

(c) Copyright International Business Machines Corporation 1998, 2002
All Rights Reserved

CONTENTS

1.0 ABOUT THIS README FILE
1.1 Agreement Text
2.0 INSTALLATION INFORMATION
2.1 System Requirements
2.2 Installation of the 'tgz' Package
2.3 Installation/Removal of the 'rpm' Package
3.0 DOCUMENTATION
4.0 PROGRAMMING EXAMPLES
5.0 REXX TCP/IP SOCKETS SUPPORT
6.0 REXX FTP SUPPORT
7.0 HINTS AND TIPS
7.1 REXX Invocation
7.2 Case sensitivity of commands
7.3 Case sensitivity of library names
7.4 Precautions using RexxShutDownAPI
7.5 External queue limits
7.6 Shared data limits
7.7 Semaphore limits
7.8 Name length limits
8.0 PROBLEM FIXING
8.1 Known problems
9.0 IMPORTANT: SHARED MEMORY USAGE
10.0 FIXES AND ADDITIONS
11.0 DESCRIPTION OF NEW FUNCTIONS
11.1 SysGetErrortext
11.2 SysQueryProcess
11.3 SysCreatePipe
11.4 SysFork
11.5 SysWait
11.6 FtpGetResume
11.7 USERID
11.8 The MutableBuffer Class
12.0 LIST OF REXX UTILITY FUNCTIONS
13.0 CONTACTS


1.0 ABOUT THIS README FILE

This is the installation package of:

   IBM Object REXX for LINUX V2.3.3.0 on i386

It is provided on an as-is basis.

The installation of this package is at your own risk (see the
agreement text). Do not install this package if you do not agree
to the conditions.


1.1 Agreement Text

   LICENSE AGREEMENT FOR OBJECT REXX FOR LINUX(tm)
   BEFORE INSTALLING THE PROGRAM, YOU SHOULD CAREFULLY READ
   THE FOLLOWING TERMS AND CONDITIONS.  INSTALLING THE PROGRAM
   INDICATES YOUR ACCEPTANCE OF THE TERMS AND CONDITIONS.  IF
   YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT
   INSTALL THE PROGRAM.

   GRANT OF LICENSE:  The Program, Object REXX for Linux, is
   owned by International Business Machines Corporation or one
   of its subsidiaries (IBM) and is copyrighted and licensed,
   not sold.  IBM grants you a non-transferable, non-exclusive
   license to use the Program.  As this Program is an
   application development tool, you may distribute
   applications created using the Program.

   You may not reverse assemble, reverse compile, otherwise
   translate or discover the source code of the Program, except
   as permitted by law without the possibility of contractual
   waiver.  In addition, unless otherwise specified, you may
   not rent , lease, sub-license, assign or distribute the
   Program to any third party.  You agree that any information
   or feedback you may provide to IBM in reference to the
   Program or this Agreement is non-confidential and you grant
   IBM a worldwide, fully paid up and irrevocable license to
   use this information/feedback for IBM business activities.

   CHARGE:  IBM is offering the Program to you at no charge
   under this Agreement.

   TERM AND TERMINATION:  You may terminate your license at any
   time by destroying all your copies of the Program.  IBM may
   terminate your license if you fail to comply with the terms
   of this Agreement.

   DISCLAIMER OF WARRANTY AND SUPPORT:  IBM will not provide
   any service or support for the Program whatsoever.

   THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND
   EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
   IMPLIED WARRANTY OF MERCHANTABILITY AND FITNESS FOR A
   PARTICULAR PURPOSE.  THE ENTIRE RISK ARISING OUT OF THE USE
   OR PERFORMANCE OF THIS PROGRAM AND DOCUMENTATION REMAINS
   WITH YOU.  IN NO EVENT WILL IBM BE LIABLE FOR ANY LOST
   PROFITS, LOST SAVINGS, INCIDENTAL OR INDIRECT DAMAGES OR
   OTHER ECONOMIC CONSEQUENTIAL DAMAGES, EVEN IF IBM OR ITS
   AUTHORIZED SUPPLIER HAS BEEN ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGES.  IN ADDITION IBM AND ITS SUPPLIERS WILL NOT BE
   LIABLE FOR ANY DAMAGES CLAIMED BY YOU BASED ON ANY THIRD
   PARTY CLAIM.

   Some jurisdictions do not allow the exclusion of implied
   warranties, or the limitation for consequential damages, so
   the above may not apply to you.

   Note to U.S. Government Users - Documentation related to
   Restricted Rights-Use, duplication, or disclosure is subject
   to restrictions set forth in GSA ADP Schedule Contract with
   IBM Corporation.

   This Agreement is entered into in the State of New York,
   U.S.A. and governed by the laws of the State of New York
   without regard to conflict of law principles.  Regardless
   of where you access this Program from, you agree to comply
   with all applicable United States laws including those
   regarding the export of data.



2.0 INSTALLATION INFORMATION

IBM Object REXX comes in two different packages. If you want to
install the 'tgz' package, you must at least have "tar" and "gzip"
on your system.  If you want to install the 'rpm' package, you
must have installed the Red Hat Package Manager (RPM), which is
part of most distribution packages.

IMPORTANT: If you already have an earlier version of Object REXX
for Linux installed on your system, you must remove it before
starting with the installation of this package.
 
Ignore the warnings during installation via "RPM", because the
image for installation was not built by the root user.


2.1 System Requirements

You need about 11 MB free disk space for the installation of
Object REXX for Linux, including all documentation.

You need an ELF system (i386) and your kernel must support
System V IPC. Object REXX must run with Linux kernel version 2.2.14
or higher, libc.so.6.1.1 or higher, and ld.so.1.9.5-13 or higher.

Object REXX was tested on the following versions of Linux,
but it should also run on others:

     - SuSE 6.4 7.1


2.2 Installation of the 'tgz' Package

If you have the package maintenance tool 'pkgtool' on your system,
you can use it to install or deinstall Object REXX via a graphical
tool. Start pkgtool as 'root' and install the 'orexx-2.3.0.0-0.i386.tgz'
package. All files will be copied to the directory '/opt/orexx/' and
its subdirectories.

If 'pkgtool' is not available, you can install Object REXX by copying the
orexx-2.3.n.0-n.i386.tgz file to the root directory ( / ) and decompress
the package with the following command:

  tar zxvf orexx-2.3.n.0-n.i386.tgz

If Object REXX for Linux does not run on your machine, you must
set some environment variables.  The easiest way to do this is
to use one of the shell scripts you will find in the directory
'/opt/orexx/etc', namely:

  - rexx.sh
     type: '. /opt/orexx/etc/rexx.sh' if you use the bourne- or
     korn-shell (also bash)

  - rexx.csh
     type: 'source /opt/orexx/etc/rexx.csh' if you use the c-shell

If necessary, add the appropriate script to your login-script to
make Object REXX generally available.  If other users also want
to use Object REXX, they must have access to the script and the
directories where Object REXX is installed.

You must add the following links:

ln -s -f /opt/orexx/lib/librexx.so.2.3       /usr/lib/librexx.so.2.3
ln -s -f /opt/orexx/lib/librexx.so.2.3       /usr/lib/librexx.so.2
ln -s -f /opt/orexx/lib/librexx.so.2.3       /usr/lib/librexx.so
ln -s -f /opt/orexx/lib/librexxapi.so.2.3    /usr/lib/librexxapi.so.2.3
ln -s -f /opt/orexx/lib/librexxapi.so.2.3    /usr/lib/librexxapi.so.2
ln -s -f /opt/orexx/lib/librexxapi.so.2.3    /usr/lib/librexxapi.so
ln -s -f /opt/orexx/lib/librexxutil.so.2.3   /usr/lib/librexxutil.so.2.3
ln -s -f /opt/orexx/lib/librexxutil.so.2.3   /usr/lib/librexxutil.so.2
ln -s -f /opt/orexx/lib/librexxutil.so.2.3   /usr/lib/librexxutil.so
ln -s -f /opt/orexx/lib/librxsock.so.2.3     /usr/lib/librxsock.so.2.3
ln -s -f /opt/orexx/lib/librxsock.so.2.3     /usr/lib/librxsock.so.2
ln -s -f /opt/orexx/lib/librxsock.so.2.3     /usr/lib/librxsock.so
ln -s -f /opt/orexx/lib/librxftp.so.2.3      /usr/lib/librxftp.so.2.3
ln -s -f /opt/orexx/lib/librxftp.so.2.3      /usr/lib/librxftp.so.2
ln -s -f /opt/orexx/lib/librxftp.so.2.3      /usr/lib/librxftp.so
ln -s -f /opt/orexx/lib/librxmath.so.2.3      /usr/lib/librxmath.so.2.3
ln -s -f /opt/orexx/lib/librxmath.so.2.3      /usr/lib/librxmath.so.2
ln -s -f /opt/orexx/lib/librxmath.so.2.3      /usr/lib/librxmath.so
ln -s -f /opt/orexx/lib/librxregexp.so.2.3      /usr/lib/librxregexp.so.2.3
ln -s -f /opt/orexx/lib/librxregexp.so.2.3      /usr/lib/librxregexp.so.2
ln -s -f /opt/orexx/lib/librxregexp.so.2.3      /usr/lib/librxregexp.so
#
ln -s -f /opt/orexx/bin/rexx                 /usr/bin/rexx
ln -s -f /opt/orexx/bin/rexx.img             /usr/bin/rexx.img
ln -s -f /opt/orexx/bin/rexxc                /usr/bin/rexxc
ln -s -f /opt/orexx/bin/rexxc                /usr/bin/REXXC
ln -s -f /opt/orexx/bin/rxqueue              /usr/bin/rxqueue
ln -s -f /opt/orexx/bin/rxqueue              /usr/bin/RXQUEUE
ln -s -f /opt/orexx/bin/rxsubcom             /usr/bin/rxsubcom
ln -s -f /opt/orexx/bin/rxsubcom             /usr/bin/RXSUBCOM
ln -s -f /opt/orexx/bin/rexxtry              /usr/bin/rexxtry
ln -s -f /opt/orexx/bin/rxdelipc             /usr/bin/rxdelipc



2.3 Installation/Removal of the 'rpm' Package

To install the 'rpm' package, use your rpm-package-manager. Select
the 'orexx-2.3.n.0-n.i386.rpm' package for the installation. Refer
to your package manager for further information. The package manager
adds orexx to your local rpm-database. The command with the command
line rpm-package-manager is:

   rpm -i orexx-2.3.n.0-n.i386.rpm

Object REXX is installed in the directory /opt/orexx.

If Object REXX for Linux does not run on your machine, you must set some
environment variables. The easiest way to do this is to use one of the
shell scripts you will find in the directory '/opt/orexx/etc', namely:

  - rexx.sh
     type: '. /opt/orexx/etc/rexx.sh' if you use the bourne- or
     korn-shell (also bash)

  - rexx.csh
     type: 'source /opt/orexx/etc/rexx.csh' if you use the c-shell

If necessary, add the appropriate script to your login script to make
Object REXX generally available.  If other users also want to use
Object REXX, they must have access to the script and the directories
where Object REXX is installed.

The command 'rpm' can also be used to remove the package from the database
if it is entered at the command line:

   rpm -e orexx-n.n.n.n-n

Note that RPM removes the entire Object REXX directory tree /opt/orexx.


3.0 DOCUMENTATION

The following documentation is provided in the directory
   /opt/orexx/doc/

"Object REXX Reference"               - file:  rexxref.pdf
"Object REXX Programming Guide"       - file:   rexxpg.pdf
"Object REXX Mathematical Functions"  - file:   rxmath.pdf  NEW!
"RxSock Reference"                    - file:   rxsock.pdf
"RxFtp Reference"                     - file:    rxftp.pdf
"Object REXX Regular Expression"      - file: rxregexp.doc  NEW!

If you need the Adobe Acrobat reader to read the PDF files,
download it from URL

     http://www.adobe.com/prodindex/acrobat/readstep.html

and install it on your Linux system. Provide the acroread link
in the /usr/bin directory.

Object REXX for Linux provides man-pages that can be
displayed by entering:

     man rexx     (if a link exists to /opt/orexx/man1/rexx.1.gz)

Use this command also to display initial usage and service
contacts information.



4.0 PROGRAMMING EXAMPLES

The following sample programs (with source code) are provided
in directory '/opt/orexx/samples/':

     - ccreply.cmd   Concurrent program using REPLY
     - complex.cmd   Complex number class
     - factor.cmd    Factorial program
     - greply.cmd    Concurrent program using WAIT and NOWAIT
     - guess.cmd     A guessing game
     - ktguard.cmd   Concurrent program using START and GUARD
     - month.cmd     Displays days of the month of January
     - pipe.cmd      A pipeline implementation
     - qdate.cmd     Date query program
     - qtime.cmd     Time query program
     - semcls.cmd    Semaphore class
     - stack.cmd     Program that uses a stack class
     - usecomp.cmd   Program that uses complex number class
     - usepipe.cmd   Program that uses pipeline implementation

The files have the extension '.cmd' to be compatible with the other
system environments Object REXX is running on. These programs are
executable without change on Windows 95/98, Windows NT, AIX,
Linux, SUN/Solaris and OS/2.

Additional programming samples are in subdirectories /macro and
/api. They demonstrate the use of the Object REXX macro facility
and the programming APIs. See the separate README files in the
subdirectories for more information.



5.0 REXX TCP/IP SOCKETS SUPPORT

Object REXX supports TCP/IP sockets through the REXX Sockets
interface "rxsock", which is implemented in the dynamic-load
library librxsock.so. A description of this interface is
in file rxsock.htm. Programming examples using TCP/IP sockets
are on the Object REXX home page:

     http://www.ibm.com/software/ad/obj-rexx/ibmrexx.html



6.0 REXX FTP SUPPORT

Object REXX supports TCP/IP FTP through the REXX FTP interface
"rxftp", which is implemented in the dynamic-load library
librxftp.so. A description of this interface is in file rxftp.pdf.
Programming examples using TCP/IP FTP are on the Object REXX
home page:

     http://www.ibm.com/software/ad/obj-rexx/ibmrexx.html



7.0 HINTS AND TIPS


7.1 REXX Invocation

To invoke REXX, enter:

     rexx [-v] filename [arguments]

If the first line is:

     #! /usr/bin/rexx

the REXX interpreter can be invoked directly by entering

         filename [arguments]

if the file is an executable.

NOTE: The first line is removed by the shell before the REXX
interpreter sees the contents of the command file.

On Unix based systems this first line must be changed to
the installation path of Object REXX  >>>#! /usr/bin/rexx<<<.

On Windows 95/98 and Windows NT with Object REXX version
1.0.3, this first line is recognized as a comment and the REXX
code runs without change if the latest update is installed.

On OS/2 Warp REXX code containing this type of shell prefix line
fails because OS/2 requires a comment to invoke the REXX
interpreter. To execute Object REXX code under OS/2, comment-out
the shell prefix line.


7.2 Case sensitivity of commands

If you submit a command to the system shell, or if you want
to call another external REXX program from REXX, put the
command in quotes. This causes the REXX interpreter to handle
the command as a case-sensitive string.  If the quotes are
omitted, the interpreter puts the string into upper case and
Linux does not recognize this command. This is important
if you want to run REXX programs that were developed under
non-Unix platforms.


7.3 Case sensitivity of library names

If you want to load a function from an external library,
remember that the library is case sensitive.  For example,
if the library name is 'librexxutil.so',  you must enter:

     rxfuncadd 'SysSleep','rexxutil','SysSleep'

If you instead enter:

     rxfuncadd 'SysSleep','Rexxutil','SysSleep'

the interpreter does not find the library.


7.4 Precautions using RexxShutDownAPI

The package contains an API called RexxShutDownAPI, which
deletes your process-shared data (shared memory). Use it only
if no other REXX program is running.

The binary "rxdelipc" provides the same function.


7.5 External queue limits

The number of external data queues is limited to 15 queues
per user (one SESSION queue per process included).


7.6 Shared data limits

Every process-shared data is user-specific. The limit is
16 MB for each of the following data:

  o  External data queues
  o  Macro space and registrations (external functions,
     subcommand handlers, system exits).


7.7 Semaphore limits

The number of semaphores accessible via the REXX utility
semaphore functions is limited to 32 per user.


7.8 Name length limits

The names of external functions, subcommand handlers,
system exits, external data queues, libraries, and
semaphores can be up to 127 characters long.



8.0 PROBLEM FIXING

If you encounter problems with Object REXX for Linux, report them
to the development team. The team tries to provide fixes, however,
this implies no obligation to do so.

8.1 Known problems
    - Shell (bash) does not executed commands if called in subthreads.
    - Only the first buffer is read by routed input, no problem if input
      is piped.
    - The option for "rexxc" is "-s", not "/s" as described in the
      documentation.
    - The library "librxftp.so" is not thread save.


9.0 IMPORTANT: SHARED MEMORY USAGE

Object REXX on Linux uses a shared memory for function
registration and data exchange between different REXX processes.
If a running REXX process must be interrupted (by using the command
"kill -9 pid"), the shared memory might be left in disorder.  In this
case, the interpreter tries to restore the shared memory. If this
fails, use the binary "rxdelipc" to delete the shared memory.



10.0 FIXES AND ADDITIONS

o  Problems with loops when rexx.cat cannot be found are fixed. The
   message catalog must reside in the directory /opt/orexx.

o  Problems with reload failure if a library could not be loaded are
   fixed.

o  Problems with hang if concurrent processes destroy the chain of
   session queues are fixed.

o  Signal blocking is now generally suppressed to avoid interference
   if REXX is used as subsystem.

o  REXX does no longer interpret CNTL_Z as end-of-file character.
   The end of file is determined by the physical file size.

o  Delayed and piped input from "stdin" (keyboard) is no longer
   ignored.

o  The libraries "librxftp.so" and "librxsock.so" can be loaded and
   used by one REXX script without interference of function calls.

o  The deletion of registered functions from a library is only carried
   out at the end of the REXX process.

o  Wrong number of arguments sent to REXX Mutable Buffer methods
   New and Append no longer causes memory faults.

o  The REXX Session Queue is no longer deleted if a subshell is called
   and closed during a REXX script procedure.

o  New Mathematical Function package added.

o  New Regular Expression package added.

o  New option "-h" (help) added to "rxdelipc".

o  Better performance of stem evaluation.

o  Better memory management to reduce possibilities of memory leaks.

o  The default path "/opt/orexx" is set for the REXX message catalogue.



11.0 DESCRIPTION OF NEW FUNCTIONS


11.1 SysGetErrortext

   >>-SysGetErrortext(errornumber)-------------------------><

Obtains a string describing the system error identified by the
error number.

Returns a string with the description of the error, or an empty
string if no description is available.

Example:

   err=SysMkDir("/home/NotKnown/temp")

   if err \= 0 then

   say "Error" err":"SysGetErrortext(err)


11.2 SysQueryProcess


                        .-PID------.
                        |          |
   >>-SysQueryProcess("-+----------+--")-------------------><
                        |          |
                        +-PPID-----+
                        |          |
                        +-PPRIO----+
                        |          |
                        +-PTIME----+
                        |          |
                        +-PMEM-----+
                        |          |
                        +-PSWAPS---+
                        |          |
                        '-PRCVDSIG-'

Retrieves information about the current process.

Parameter:

   PID
      Returns the process ID of the current process.

   PPID
      Returns the parent process ID of the current process.

   PPRIO
      Returns the priority number of the current process.

   PTIME
      Returns time information of the current process.

   PMEM
      Returns the maximum memory (RSS) used by the current
      process.

   PSWAPS
      Returns the number of times that the process has been swapped out of
      memory.

   PRCVDSIG
      Returns the number of signales that has been received by the process.

Return codes:

  o  For PID or PPID: an ID

  o  For PPRIO: a number from -20 to +20

  o  For PTIME: the summary and the duration that the process
     executed in kernel mode, and the duration that the process
     executed in user mode.


11.3 SysCreatePipe

                     .-Blocking----.
                     |             |
   >>-SysCreatePipe(-+-------------+-)---------------------><
                     |             |
                     '-Nonblocking-'

Creates an interprocess channel called an "unnamed pipe", opens
it, and returns two handle identifiers, separated by a blank.
The first handle is opened for reading, and second for writing.

Unnamed pipes are used to allow communication between different
processes. Anything that is written to the writing pipe can be
read from the reading pipe. The restriction is that unnamed pipes
can only be shared between the process that creates them and the
child processes of that process.

Once an unnamed pipe is created with SysCreatePipe, the read and
write handles can be used directly with the system I/O functions,
or they can be concatenated with the string "HANDLE:" to form
stream names that can be used like any other transient streams in
REXX programs. Because they are transient streams, changing the
read and write positions is not allowed, CHARS returns only 1 or 0
(See Chapter "Input and Output Streams" for a discussion of
REXX input and output).

The "Blocking" option, which is the default, causes input operations
to wait until data is available in the pipe, or until an end-of-file
indication is returned by the Unix operating system (which means
that no processes remain that have the pipe open for writing).
The end-of-file indication causes the NOTREADY condition to be
raised when the native REXX input functions are used. For system
input functions, the end-of-file indication is returned.

The "Nonblocking" option causes input operations to return immediately,
regardless of the availability of data. If no data is present, but there
are still processes that have the pipe open for writing, the input
operations simply return null strings (""). An end-of-file indication
still raises the NOTREADY condition if the native REXX input functions
are used. For system input functions, the end-of-file indication is
returned.

The handles returned by SysCreatePipe are numeric, and equal to the
handle numbers returned by the "pipe" of the Unix operating system
subroutine. You can to pass this information to any programs that you
call, so that they can make use of the pipes that you have created.

Examples:
   SysCreatePipe()       ->  "7 8"   /* maybe this */
   SysCreatePipe()       ->  "9 14"  /* maybe this */


11.4 SysFork

   >>-SysFork()---------------------------------------------><

Returns the process ID (pid) of the created child process to the
parent process, and always returns a value of 0 to the child
process.


11.5 SysWait

   >>-SysWait()---------------------------------------------><

Waits for a child process to stop or to terminate, then returns
with the exit code of the child process. If the child process that
has not been waited for has already stopped or terminated prior to
the call, SysWait returns without waiting.


11.6 FtpGetResume

New function in the RxFTP library for a file transfer restart.

The FtpGetResume() call copies a single file from a restart position
of a file on the remote FTP server to the local FTP client. The copy
and the file to be copied need not have the same name.

The RestartPosition parameter is optional:

     If it is omitted (or if RestartPosition = 0), and if the local
     file exists, data from the remote file, beginning at its restart
     position, is appended to the local file.

     If it is omitted (or if RestartPosition = 0), and if the local
     file does not exist, the restart position of the remote file
     is ignored, and the entire remote file is copied.

     If a restart position greater than "0" is specified, data from
     the remote file, beginning at the restart position, is copied
     to a new local file. An existing file is overwritten.

The transfer mode is always BINARY.

The remote host running the FTP server is specified with the
FtpSetUser() call.

Note: The FtpGetResume() function can only be used with an FTP
      server that supports the restart facility.

Syntax:

rc = FtpGetResume(localFile,remoteFile<,restartPosition>)

where:

localFile
     is the name of the file on the local host.

remoteFile
     is the name of the file to be copied from the remote FTP
     server.

RestartPosition
     is the offset from the beginning of the remote file
     (in number of bytes) where the restart must begin.

The return value is an FTP error code.


11.7 USERID

New built-in function of Object REXX.

Syntax:

user_id = UserID()

   >>-UserID()--------------------------------------------><

The return value is the active user identification.


11.8 The MutableBuffer Class

                    ,-----,-256------,
>>-INIT(-+--------+-+----------------+-)-------------------><
         '-string-' '-,-buffer size--'

Initialize the buffer, optionally assign a buffer content and
a starting buffer size. The default size is 256; the buffer
size increases if an overflow would occur if adding to the
buffer.


>>-APPEND(string)------------------------------------------><

Appends string string to the buffer content. The buffer size
is increased if necessary.


>>-DELETE(n---+---------+--)-------------------------------><
              '-,length-'

Deletes length characters from the buffer beginning at the
n'th character. If length is omitted, or if length is greater
than the number of characters from n to the end of the buffer,
the method deletes the remaining buffer contents (including
the n'th character). The length must be a positive integer
or zero. The n must be a positive integer. If n is greater than
the length of the buffer or zero, the method does not modify the
buffer content.


>>-GETBUFFERSIZE-------------------------------------------><

Retrieves the current buffer size.


>>-INSERT(new-+-----------------------------------------+--)><
              '-,--+---+--+--------------------------+--'
                   '-n-'  '-,--+--------+--+------+--'
                               '-length-'  '-,pad-'

Inserts the string new, padded or truncated to length length,
into the mutable buffer after the n'th character. The default
value for n is 0, which means insertion at the beginning of the
string. If specified, n and length must be positive integers
or zeros. If n is greater than the length of the buffer contents,
the string new is padded at the beginning. The default value for
length is the length of new. If length is less than the length of
string new, INSERT truncates new to length length. The default
pad character is a blank.


>>-LENGTH--------------------------------------------------><

Returns length of data in buffer.


>>-OVERLAY(new-+-----------------------------------------+--)--><
               '-,--+---+--+--------------------------+--'
                    '-n-'  '-,--+--------+--+------+--'
                                '-length-'  '-,pad-'

Modifies the buffer content by overlaying it, starting at the
n'th character, with the string new, padded or truncated to
length length. The overlay can extend beyond the end of the
buffer. In this case the buffer size will be increased. If
you specify length, it must be a positive integer or zero.
The default value for length is the length of new. If n is
greater than the length of the buffer content, padding is
added before the new string. The default pad character is a
blank, and the default value for n is 1. If you specify n,
it must be a positive integer.


>>-SETBUFFERSIZE(n)----------------------------------------><

Sets the buffer size. If n is less than the length of buffer
content, the content is truncated. If n is 0, the entire
contents is erased and the new buffer size is the value given
in the INIT method.


>>-STRING--------------------------------------------------><

Retrieves the content of the buffer (a string).


>>-SUBSTR(n-+--------------------------+--)----------------><
            '-,--+--------+--+------+--'
                 '-length-'  '-,pad-'

Returns a substring from the buffer content that begins at the
n'th character and is of length length, padded with pad if
necessary. The n must be a positive integer. If n is greater
than receiving_string~LENGTH, only pad characters are returned.
If you omit length, the remaininf buffer content is returned.
The default pad character is a blank.



12.0 LIST OF REXX UTILITY FUNCTIONS

=================================================================
 Function                 | Exists on platforms:  |
  Name:                   | OS/2 | Windows | UNIX | Remarks
--------------------------+------+---------+------+--------------
SysAddFileHandle          | YES  |   YES   | NO   |
SysAddRexxMacro           | YES  |   YES   | YES  |
SysBootDrive              | YES  |   YES   | NO   |
SysClearRexxMacroSpace    | YES  |   YES   | YES  |
SysCloseEventSem          | YES  |   YES   | YES  |
SysCloseMutexSem          | YES  |   YES   | YES  |
SysCls                    | YES  |   YES   | YES  |
SysCopyObject             | YES  |   NO    | NO   |
SysCreateEventSem         | YES  |   YES   | YES  |
SysCreateMutexSem         | YES  |   YES   | YES  |
SysCreateObject           | YES  |   NO    | NO   |
SysCreatePipe             | NO   |   NO    | YES  |
SysCreateShadow           | YES  |   NO    | NO   |
SysCurPos                 | YES  |   YES   | NO   |
SysCurState               | YES  |   YES   | NO   |
SysDeregisterObjectClass  | YES  |   NO    | NO   |
SysDestroyObject          | YES  |   NO    | NO   |
SysDriveInfo              | YES  |   YES   | NO   |
SysDriveMap               | YES  |   YES   | NO   |
SysDropFuncs              | YES  |   YES   | YES  |
SysDropLibrary            | YES  |   YES   | NO   |
SysDropRexxMacro          | YES  |   YES   | YES  |
SysDumpVariables          | YES  |   YES   | YES  |
SysElapsedTime            | YES  |   NO    | NO   |
SysFileDelete             | YES  |   YES   | YES  |
SysFileSearch             | YES  |   YES   | YES  |
SysFileSystemType         | YES  |   YES   | NO   |
SysFileTree               | YES  |   YES   | YES* |
SysFromUnicode            | NO   |   YES   | NO   |
SysToUnicode              | NO   |   YES   | NO   |
SysGetErrortext           | NO   |   YES   | YES**|
SysFork                   | NO   |   NO    | YES  |
SysGetCollate             | YES  |   YES   | NO   |
SysGetEA                  | YES  |   NO    | NO   |
SysGetFileDateTime        | YES  |   YES   | YES  |
SysGetKey                 | YES  |   YES   | YES  |
SysGetMessage             | NO   |   YES   | YES  |
SysGetMessageX            | NO   |   NO    | YES  |
SysGetpid                 | NO   |   NO    | YES+ | use SysQueryProcess instead;
SysIni                    | YES  |   YES   | NO   |
SysLoadFuncs              | YES  |   YES   | YES  |
SysLoadLibrary            | YES  |   YES   | NO   |
SysLoadRexxMacroSpace     | YES  |   YES   | YES  |
SysMapCase                | YES  |   YES   | NO   |
SysMkDir                  | YES  |   YES   | YES  |
SysMoveObject             | YES  |   NO    | NO   |
SysNationalLanguageCompare| YES  |   YES   | NO   |
SysOpenEventSem           | YES  |   YES   | YES  |
SysOpenMutexSem           | YES  |   YES   | YES  |
SysOpenObject             | YES  |   NO    | NO   |
SysPostEventSem           | YES  |   YES   | YES  |
SysProzessType            | YES  |   YES   | NO   |
SysPulseEventSem          | YES  |   YES   | NO   |
SysPutEA                  | YES  |   NO    | NO   |
SysQueryClassList         | YES  |   NO    | NO   |
SysQueryEAList            | YES  |   NO    | NO   |
SysQueryExtLIBPATH        | YES  |   NO    | NO   |
SysQueryProcess           | YES  |   YES   | YES* |
SysQueryProcessCodePage   | YES  |   YES   | NO   |
SysQueryRexxMacro         | YES  |   YES   | YES  |
SysQuerySwitchList        | YES  |   NO    | NO   |
SysRegisterObjectClass    | YES  |   NO    | NO   |
SysReleaseMutexSem        | YES  |   YES   | YES  |
SysReorderRexxMacro       | YES  |   YES   | YES  |
SysRequestMutexSem        | YES  |   YES   | YES  |
SysResetEventSem          | YES  |   YES   | YES  |
SysRmDir                  | YES  |   YES   | YES  |
SysSaveObject             | YES  |   NO    | NO   |
SysSaveRexxMacroSpace     | YES  |   YES   | YES  |
SysSearchPath             | YES  |   YES   | YES  |
SysSetExtLIBPATH          | YES  |   NO    | NO   |
SysSetFileDateTime        | YES  |   YES   | YES  |
SysSetFileHandle          | YES  |   NO    | NO   |
SysSetIcon                | YES  |   NO    | NO   |
SysSetObjectData          | YES  |   NO    | NO   |
SysSetPriority            | YES  |   YES   | NO   |
SysSetProcessCodePage     | YES  |   YES   | NO   |
SysShutDownSystem         | YES  |   YES   | NO   |
SysSleep                  | YES  |   YES   | YES  |
SysStemCopy               | YES  |   YES   | YES  |
SysStemDelete             | YES  |   YES   | YES  |
SysStemInsert             | YES  |   YES   | YES  |
SysStemSort               | YES  |   YES   | YES  |
SysSwitchSession          | YES  |   YES   | NO   |
SysSystemDirectory        | YES  |   NO    | NO   |
SysTempFileName           | YES  |   YES   | YES  |
SysTextScreenRead         | YES  |   YES   | NO   |
SysTextScreenSize         | YES  |   YES   | NO   |
SysUtilVersion            | YES  |   YES   | YES  |
SysVersion                | YES  |   YES   | YES  |
SysVolumeLabel            | YES  |   YES   | NO   |
SysWait                   | NO   |   NO    | YES  |
SysWaitEventSem           | YES  |   YES   | YES  |
SysWaitForShell           | YES  |   NO    | NO   |
SysWaitNamedPipe          | YES  |   YES   | NO   |
SysWinDecryptFile         | NO   |   YES   | NO   |
SysWinEncryptFile         | NO   |   YES   | NO   |
SysWildCard               | YES  |   YES   | NO   |
==========================+======+=========+======+==============
SysOS2Ver                 | YES  |   NO    | NO   | use SysVersion instead;
SysWinVer                 | NO   |   YES   | NO   | use SysVersion instead;
SysLinVer                 | NO   |   NO    | YES++| use SysVersion instead;
=================================================================
     Legend: *  <=> works differently;
             ** <=> new function;
             +  <=> AIX only.
             ++ <=> Linux only.
=================================================================


13.0 CONTACTS

Please address any comments and problem reports via our home
page's problem reporting facility:

     http://www.ibm.com/software/ad/obj-rexx

or by e-mail to:

     rexxhelp@vnet.ibm.com

or by mail to postal address:

   IBM Deutschland Entwicklung GmbH
   REXX Development, Department 7804
   Postbox 1380
   D-71003 Boeblingen
   Germany



12.0 NOTICES

This information was developed for products and services offered
in the U.S.A. IBM may not offer the products,services, or features
discussed in this document in other countries. Consult your local
IBM representative for information on the products and services
currently available in your area. Any reference to an IBM product,
program, or service is not intended to state or imply that only
that IBM product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any
IBM intellectual property right may be used instead. However, it is
the user's responsibility to evaluate and verify the operation of
any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject
matter described in this document. The furnishing of this document
does not give you any license to these patents. You can send license
inquiries, in writing, to:
  IBM Director of Licensing
  IBM Corporation
  North Castle Drive
  Armonk, NY 10504-1785
  U.S.A.

For license inquiries regarding double-byte (DBCS) information,
contact the IBM Intellectual Property Department in your country
or send inquiries, in writing, to:
  IBM World Trade Asia Corporation
  Licensing
  2-31 Roppongi 3-chome, Minato-ku
  Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any
other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION
"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not
allow disclaimer of express or implied warranties in certain transactions,
therefore, this statement may not apply to you.

This information could include technical inaccuracies or
typographical errors. Changes are periodically made to the information
herein; these changes will be incorporated in new editions of the
publication. IBM may make improvements and/or changes in the product(s)
and/or the program(s) described in this publication at any time without
notice.

Licensees of this program who wish to have information about it for
the purpose of enabling: (i) the exchange of information between
independently created programs and other programs (including this one)
and (ii) the mutual use of the information which has been exchanged,
should contact:

  IBM Deutschland
  Informationssysteme GmbH
  Department 3982
  Pascalstrasse 100
  70569 Stuttgart
  Germany

Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed
material available for it are provided by IBM under terms of the
IBM Customer Agreement, IBM International Program License Agreement
or any equivalent agreement between us.

COPYRIGHT LICENSE:

This information contains sample application programs in source
language, which illustrates programming techniques on various
operating platforms. You may copy, modify, and distribute these
sample programs in any form without payment to IBM, for the purposes
of developing, using, marketing or distributing application programs
conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples
have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of
these programs. You may copy, modify, and distribute these sample
programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs
conforming to IBM's application programming interfaces.

