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

(C) Copyright International Business Machines Corporation 1998, 2004.
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 FtpGetResume
11.4 USERID
11.5 The MutableBuffer Class
11.6 MakeString Method of array class
11.7 RexxAllocMem RexxFreeMem
11.8 ANSI Compliance for lines function and method
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.4.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. Object REXX for Linux is a 32Bit application.


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.


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.18
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.1 8.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.n.0-n.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
"RxSock Reference"                    - file:   rxsock.pdf
"RxFtp Reference"                     - file:    rxftp.pdf
"Object REXX Regular Expression"      - file: rxregexp.doc

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/awdtools/obj-rexx/



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/awdtools/obj-rexx/



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 (see: rxdelipc -h).


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

  o  For each user the REXX semaphores are limited under Linux to:
                    32 REXX semaphores for the utility functions
                    48 REXX semaphores for the REXX Queues


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

    - Only piped "|" input and no redirected "<" input can be evaluated
      by Object REXX under Unix.
    - 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.

o  The REXX utility function "SysFileSearch" now also counts lines
   that consist of only one new-line-character.

o  The REXX utility function "SysMkDir" now takes the permission of the
   "umask" setting for a directory to be created.

o  The pragma statements in the "rexx.h" file have been delete to allow the
   compilation of C and C++ programs using the Object REXX API.

o  The options of the "lines" method of the stream class and the
   "lines" function have changed (see chapter 11.8).

o  Instore scripts and scripts in the macrospace now accept
   '#!/usr/bin/rexx' at the first line.

o  REXX runs from a current working directory which belongs to a
   different user if the permission has been set for it.

o  Threads of a process can now find the functions registered by the main
   process.

o  The REXX utility function "SysSleep" now accepts a value of 3600.

o  The anchor point "..IBM_OREXX2.3.4.0_$USER" of the shared memory is
   unique for each user after a switch of user.


o  The Object REXX FTP API V2.7 and higher has got the additional transfer
   type "EBCDIC" for a file transfer to and from an EBCDIC system. The
   transfer type "EBCDIC" allows a restore of the data format for instance
   on z/VM.

   /* This REXX sample shows briefly how you can get a variable blocked */
   /* file from VM and put it back as fixed block 80:                   */

   /* Receive a file from VM -------------------------------------------*/
   say " FTPQUOTE "FtpQuote("type e", retstr )
   say "Message returned: "retstr
   say " FTPQUOTE "FtpQuote("mode b", retstr )
   say "Message returned: "retstr

   Say "Receiving a file via FtpGet ..."
   If FtpGet("local_ebcdic", "host_file1" ) = 0 Then
     Say " File transferred;"
   Else
     Call Terminate " *** No EBCDIC file received; Program ENDS."

   /* Send a file to VM ------------------------------------------------*/
   say " FTPQUOTE "FtpQuote("type e", retstr )
   say "Message returned: "retstr
   say " FTPQUOTE "FtpQuote("mode b", retstr )
   say "Message returned: "retstr
   say " FTPQUOTE "FtpQuote("site fix 80", retstr )
   say "Message returned: "retstr

   Say "Sending a file via FtpPut ... "
   If FtpPut("local_ebcdic", "most_file2" ) = 0 Then
     Say " File transferred;"
   Else
     Call Termination " *** No EBCDIC file sent; Program ENDS."
   /* ====================================================== */

   You must NOT define the transfer mode "EBCDIC" in the following
   REXX FTP API functions:
                          FtpSetBinary()
                          FtpAppend()
                          FtpGet()
                          FtpPut()
                          FtpPutUnique()
                          FtpProxy().





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 signals that have 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 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.4 USERID

New built-in function of Object REXX.

Syntax:

user_id = UserID()

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

The return value is the active user identification.


11.5 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 to the length of the string if the string does
not fit into 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 remaining buffer content is returned.
The default pad character is a blank.


11.6 The MakeString Method of the array Class

                 .-(LINE)--.
>>-MAKESTRING----+---------+------><
                 '-(CHAR)--'

Returns a stream that contains the data of an array (one to n dimensional).
The elements of the array are treated either in line or character format,
starting at the first element in the array. The line format is the default.

11.7  Dynamically allocating and de-allocating memory

For several functions of the Rexx-API it is necessary or possible to
dynamically allocate or free memory. Depending on the operating system,
compiler and REXX interpreter, the method for these allocations and de-
allocations vary. To write system independent code, Object REXX comes with
two new API function calls called RexxAllocateMemory() and RexxFreeMemory().
These functions are wrapper for the corresponding compiler or operating
system memory functions.

11.7.1 The RexxAllocateMemory() function

PVOID APIENTRY RexxAllocateMemory( ULONG size );

where:

size

  is the number of bytes of requested memory

Return Codes

  returns a pointer to the newly allocated block of memory, or NULL if no
  memory could be allocated.

11.7.2 The RexxFreeMemory() function

APIRET APIENTRY RexxFreeMemory( PVOID MemoryBlock );

where:

MemoryBlock

  is a void pointer to the block of memory allocated by the Object REXX
  interpreter, or allocated by a previous call to RexxAllocateMemory().

Return Codes:

  RexxFreeMemory() always returns 0.



11.8  ANSI Compliance for lines function and method


The ANSI Standard has extended this function to allow an option: "Count"

If this option is used, "lines" returns the actual number of complete
lines remaining in the stream, irrespective of how long this operation takes.

The option "Normal" returns 1 if there is at least one complete line
remaining in the file or 0 if no lines remain.


The following syntax diagram shows the new option of the lines function:


                        +-Normal-+
>>-LINES(--+------+-,---+--------+---)-------><
           +-name-+     +-Count--+

The default is "Normal".


The following syntax diagram shows the new option of the lines method:

            +-Count--+
>>~-LINES(--+--------+----)-------><
            +-Normal-+

The default is "Count".


The defaults of the lines method and function are different because of
compatibility reasons.


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* |
SysFork                   | NO   |   NO    | YES+ |
SysFromUnicode            | NO   |   YES   | NO   |
SysGetErrortext           | NO   |   YES   | 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   |
SysToUnicode              | NO   |   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/awdtools/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.

