IBM Object REXX for Linux(tm) on S/390(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 Install/Remove 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 LIST OF 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 on S/390

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

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.  The Red Hat Package Manager (RPM), which is part of most
distribution packages, must be installed if you want to use the
'rpm' package.

IMPORTANT:
If you already have an earlier version of Object REXX for LINUX
installed on your system, you MUST REMOVE this version before
starting with the installation of this package.


2.1 System Requirements

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

You need an ELF system (S/390) and your kernel must support System V IPC.
Object REXX must run with Linux kernel version 2.2.16 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 7.0


2.2 Installation of the 'tgz' Package

If you have the package maintenance tool 'pkgtool' on your system, you can
use this to install or deinstall Object REXX via a graphical tool. Start
pkgtool as 'root' and install the orexx-2.3.2.0-4.s390.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.s390.tgz file to the root directory ( / ) and decompress
the package with the following command:

  tar zxvf orexx-2.3.n.0-n.s390.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 there are other users who
want to improve their work by using 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/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 Install/Remove the 'rpm' Package

To install the rpm-package, use your rpm-package-manager. Select the
orexx-2.3.n.0-n.s390.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.s390.rpm

Object REXX is installed in the directory /opt/orexx.  All required
files are placed there.

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 there are other users who want
to improve their work by using 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 whole 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 as instructed. 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 the 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 which uses a stack class
     - usecomp.cmd   program which uses complex number class
     - usepipe.cmd   program which 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 any change on Windows 95/98, Windows NT, AIX,
LINUX, SUN/Solaris and OS/2.

Additional programming samples in the subdirectories /macro and
/api  demonstrate the use of the Object REXX macro facility and
the programming APIs. See the separate README files in the sub-
directories for a description.


5.0 REXX TCP/IP SOCKETS SUPPORT

Object REXX supports TCP/IP sockets through the REXX Sockets
interface "rxsock", which is implemented by the dynamic-load
library librxsock.so. A description of the REXX Sockets interface
is provided in the file rxsock.htm. Programming examples using
TCP/IP sockets are provided 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 by the dynamic-load library
librxftp.so. A description of the REXX FTP interface is provided
in the file rxftp.pdf. Programming examples using TCP/IP FTP
are provided 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 in use 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 the 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 will run without a change if the latest update is installed.

On OS/2 Warp REXX code containing this type of shell prefix line
will fail 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

When 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 OS/2,
Windows95/98/NT, or other 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 called "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 any problems, you are encouraged to report them
to the development team of Object REXX for LINUX. The team
provides fixes to known problems as soon as they become available.
However, this implies no obligation to do so.

8.1 Known problems
    - Shell (bash) does not executed commands, if called in subthreads.
    - Only first buffer read by routed input, no problem if piped.
    - The option for the "rexxc" is "-s" and NOT "/s". This is wrong 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 LIST OF FIXES AND ADDITIONS

o  Fix of looping if rexx.cat cannot be found. The message catalog
   must reside in the directory /opt/orexx.

o  Fix of reload failure if a library could not be loaded.

o  Fix of hang when concurrent processes destroy the chain of
   session queues.

o  REXX Mathematical Function package is added.

o  Signal blocking is suppressed, because REXX must not interfere
   signaling if used as subsystem.

o  REXX Regular Expression package is added.

o  The call of the binary "rxdelipc" with option "-h" shows help text.

o  The performance of the stem evaluation.

o  The memory management of REXX causing memory leaks.

o  CNTL_Z character for end-of-file is ignored by REXX now.

o  Delayed and piped input from "stdin" (keyboard) is recognized.

o  The libraries "librxftp.so" and "librxsock.so" can be loaded
   and used from one REXX script.

o  Default PATH "/opt/orexx" set for the REXX message catalogue.

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



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:

   info
      The kind of information requested:

   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 on the current process.

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

   PSWAPS
      Returns the number of memory which has been swapped out.

   PRCVDSIG
      Returns the number of memory which has been swapped out.

Return codes:

  o  For PID or PPID: an ID

  o  For PPRIO: a number between -20 and +20

  o  For PTIME: the summary and the amount of time that the
     process executed in kernel mode, and the amount of time
     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 returned is opened for reading, and the second is
opened 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 for "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 will cause 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, on the other hand, 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 will simply return null
strings (""). An end-of-file indication will still raise 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 might want 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 copy on the local host.

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

RestartPosition
     is the number of bytes from where the restart of the remote file 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 content and starting size
for the buffer size. The default is 256; the buffer size will be
increased if an overflow would occur when adding to the buffer.


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

This modifies the buffer's contents by appending the string string
at the end of the buffer's data. The buffer size will be extended
if necessary.



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

Modifies the buffer's contents by deleting the length characters
beginning at the nth character. If you omit length, or if length is
greater than the number of characters from n to the end of the buffer,
the method deletes the rest of the buffer's contents (including the
nth character). The length must be a positive whole number or zero.
The n must be a positive whole number. If n is greater than the length
of the buffer or zero, the method does not modify the contents of the
buffer.


>>-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 nth 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 whole numbers or zero. If n is greater than
the length of the buffer's 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 the string new, then 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's contents by overlaying them, starting at the nth
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 extended as appropriate. If you specify length, it
must be a positive whole number or zero. The default value for length
is the length of new. If n is greater than the length of the buffer's
contents, 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 whole number.


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

Sets the buffer size. If n is smaller than the length of the content
of the buffer, the contents are truncated. If n is 0 all contents will
be erased and the new buffer size will be the value given in the INIT
method.


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

Retrieves the content of the buffer (a string).


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

Returns a substring of the buffer's contents that begins at the nth
character and is of length length, padded with pad if necessary. The
n must be a positive whole number.   If  n  is greater than
receiving_string~LENGTH, only pad characters are returned. If you omit
length, the rest of the buffer's contents are returned. The default pad
character is a blank.



12.0 LIST OF REXX UTILITY FUNCTIONS

=================================================================
    This is the list of the Object REXX system utilities.
      They may differ or do not exist on all platforms.
=================================================================
 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 different;
             ** <=> 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.
