REXX

REXX is a high-level language designed to support personal programming, 
operating system command files, application program macros, and prototyping. It 
is IBM's SAA (Systems Applications Architecture) Procedures Language, and is 
available on a wide variety of operating systems and platforms. REXX is a 
standard part of OS/2 release 1.3 and up.

REXX support in 1-2-3 for OS/2 Release 1.1 exploits the external programming 
interfaces of 1-2-3, and allows you to execute 1-2-3 @functions and macro 
commands that have been written in the REXX programming language. @Functions 
and macro commands written in REXX offer the following advantages:

		More powerful than the native 1-2-3 macro language.

		Easier to maintain than those written in the native 1-2-3 macro language.

		Easy access to the system facilities of OS/2 and to other application programs.

Note-This chapter assumes you are familiar with REXX.

	Insert the Custom Applications Sample Disk in drive A and close the door.

	Type copy A:\rexxlink\rexxlink.dll c:\123g and press ENTER. 

If you placed the disk in a drive other than A, substitute the appropriate 
drive letter for A:. If c:\123g is not the path and name of your 1-2-3 program 
directory, substitute the appropriate path and name.

	Type copy a:\rexxlink\*.wg2 c:\123g\work and press ENTER.

	Type copy a:\rexxlink\*.cmd c:\123g\work and press ENTER. 

The installation procedure copies the following files to your 1-2-3 directories:





Files and Contents

REXXLINK.DLL

REXX executable code.

REXXLINK.WG2

Sample worksheet.

REXXABRV.CMD

Sample REXX procedure that returns an abbreviation of a word in a range.

REXXADD.CMD

Sample REXX procedure that adds `value' to each of the cells in `range'.

REXXARGS.CMD

Sample REXX procedure that returns the number of arguments passed to it.

REXXDIAG.CMD

Sample REXX procedure that moves the values of the cells on the top left to the 
bottom right, across the horizontal axis, of a range to the diagonal, across 
the horizontal axis.

REXXDISK.CMD

Sample REXX procedure that returns the most free space available among disks.

REXXEMSG.CMD

Sample REXX procedure that displays a 1-2-3 macro error message with `value' as 
the text.

REXXMATH.CMD

Sample REXX procedure that returns the arithmetic result of applying `operator` 
to `op1' and `op2'. The operator must be one of the REXX binary operators.

REXXPRSE.CMD

Sample REXX procedure that parses a column of strings from range1 into a range 
of cells, range2.



Caution-The sample REXX procedures provided on the disk have not been 
thoroughly tested. Lotus recommends you do not use them in your application 
code without first testing them.

After you copy these files to your 1-2-3 program directory, you can start 1-2-3 
and attach and use REXX. You can of course delete the sample files from your 
disk at any time.

You can also load the source code on your hard disk by typing copy 
a:\rexxlink\source\*.* c:\source and pressing ENTER. If you placed the disk in 
a drive other than A, substitute the appropriate drive letter for A:. If 
c:\source is not the path and name of your C source directory, substitute the 
appropriate path and name.

To attach and invoke REXX, invoke the LIBRARY ATTACH macro command:

{library-attach rexxlink}

This loads the REXXLINK Dynamic Link Library (DLL) file into memory and makes 
it available to 1-2-3. Any @functions written in REXX that are part of 
currently open worksheets are evaluated.

If errors are encountered while attempting to execute an @function or macro 
written in REXX, an error message is displayed in a popup dialog box, 
indicating the REXX error number. These error numbers are described in the IBM[ 
OS/2 Procedures Language/2 REXX Reference. Some of the most common errors are 
listed in the following table.





Error numbers and Explanation

-3

The REXX program could not be read from disk. You may have misspelled it, or it 
is not located in a directory named in your PATH environment variable.

-4

The system interrupted execution of the REXX program. You may have pressed the 
Break key during its execution.

-5

Machine resources are exhausted. You have run out of memory, and out of disk 
space for the SWAPPER.DAT file. Remove some programs from memory or some files 
from your disk.



1-2-3 provides two @function names, @REXX and @REXXD. These @functions can in 
turn call REXX procedures of any name.



@REXX("rexx_procedure [log_file]",[arg...])
@REXXD("rexx_procedure [log_file]",[arg...])

rexx_procedure is the name and extension of the file containing the REXX 
procedure to be invoked. The file must be in the 1-2-3 working directory, in 
the OS/2 search path or be preceded by a fully-qualified path. Any extension 
(not just CMD) is valid.

log_file is the (optional path), name and extension of a file to which the 
output of REXX SAY and TRACE instructions will be written, to facilitate 
debugging.

arg is an argument to be passed to the REXX procedure. Up to 20 arguments may 
be supplied, separated by commas. Standard 1-2-3 rules for @function and macro 
command arguments apply.

All @REXX and @REXXD @functions are called when the REXXLINK.DLL is attached 
via the {LIBRARY-ATTACH} macro command, and whenever a cell containing it is 
recalculated. The @REXXD @function is always -dirty". It is called whenever a 
recalculation is done. 

Note-@NOW is an example of an "always dirty" @function. 1-2-3 @functions cannot 
modify their arguments; they can only return a value.

If the argument is a range, the cells of the range are available to the REXX 
procedure as shared compound variables whose values are set when the procedure 
begins execution. The stem names used to hold the values of range cells are 
always RANGE1., RANGE2., and so on. The value of the cells of each range are in 
RANGE1.1, RANGE1.2, ..., RANGE2.1, RANGE2.2, and so on. The variables RANGE1.0, 
RANGE2.0 and so on, have the total number of cells in the range as their 
values.

Note-A REXX procedure invoked as an @function cannot determine the address or 
dimensions of the ranges passed to it.

If the return value from the REXX procedure can be interpreted as a number, it 
is returned to 1-2-3 as a number; otherwise it is returned as a string. The 
standard 1-2-3 string prefixes (', ", ^) can be used 
to control justification of the returned string. If the numeric value returned 
does not fit into a 64 bit floating point number or a 32 bit integer number, 
data is truncated without warning. See the 
sample REXX procedures REXXABRV.CMD, REXXARGS.CMD, REXXDISK.CMD, and 
REXXMATH.CMD for examples of these funtions.

1-2-3 provides three macro names, {REXXV}, {REXXR}, and {REXXRV}. These macro 
commands can in turn call REXX procedures of any name. 



{REXXV "rexx_procedure [log_file]", value [, value]}
{REXXR "rexx_procedure [log_file]", range [, range]}


rexx_procedure is the name and extension of the file containing the REXX 
procedure to be invoked. The file must be in the 1-2-3 working directory, in 
the OS/2 search path or be preceded by a fully-qualified path. Any extension 
(not just CMD) is valid.

value is the (optional path), name and extension of a file to which the output 
of REXX SAY and TRACE instructions are written, to facilitate debugging.

value is a value argument to be passed to the REXX procedure. It 
may be a string, number or special value (NA or ERR).

range is a range (not a collection) to be passed to the REXX 
procedure.

Macro commands must have their operands defined at the time the external 
library is attached. REXXV takes 1 or 2 values as arguments. REXXR takes 1 or 2 
ranges as arguments. REXXRV takes a range and optional value as an argument.

The cells of range arguments are available to the REXX procedure as shared 
compound variables whose values are set when the procedure begins execution. 
The stem names used to hold the values of range cells are always RANGE1., 
RANGE2., and so on. The value of the cells of each range are in RANGE1.1, 
RANGE1.2, ..., RANGE2.1, RANGE2.2, and so on. The variables RANGE1.0, RANGE2.0 
and so on have as their values the total number of cells in the range, the 
number of sheets in the range, the number of columns in the range, and the 
number of rows in the range, each of these values separated by a blank.

REXX procedures called as 1-2-3 macro commands can modify the values of cells 
in ranges that are passed as arguments. They can modify the value of any cell 
that is below, to the right of, or behind the top left hand front corner of the 
range. Passing the range A:A1..A:A1 as a range gives the REXX procedure access 
to every cell on every sheet in the worksheet. See the sample REXX procedures 
REXXABRV.CMD, REXXARGS.CMD, REXXDISK.CMD, and 
REXXMATH.CMD for examples of these funtions.

The following external functions are available to REXX procedures called from 
1-2-3 as macro commands.

Display123Error(string)

Displays string as an error message in a popup window and 
returns 0.

Get123Cell(range, sheet, column, row)

Returns the value of the cell at address sheet, column, row. The address is 
relative to the upper left hand front corner of range, which must be the name 
of a range that was passed to the REXX procedure as an argument (e.g., RANGE1, 
RANGE2, and so on).

Set123Cell(range, sheet, column, row, type, value)

Sets the value of the cell at address sheet, column, row to value. The address 
is relative to the upper left hand front corner of range, which must be the 
name of a range that was passed to the REXX procedure as an argument. The 
argument type must be one of the arguments listed in the following table.





Argument and Description

EMPTY

An empty cell. Value is ignored and may be omitted.

ERR

The special value ERR. Value is ignored and may be omitted.

NA

The special value NA. Value is ignored and may be omitted.

NUMBER

A numeric value. If the value contains a decimal point, the cell is set as a 
floating point number; if the value does not contain a decimal point, the cell 
is set as an integer number. Note that if the numeric value passed by the REXX 
procedure does not fit into a 64 bit floating point number or a 32 bit integer 
number, the number is truncated without a warning; possibly resulting in data 
loss.

STRING

A string.



Set123Cell returns 0 if the cell's value was set, 1 otherwise.

The special values NA and ERR are passed from 1-2-3 to the REXX procedure as 
null strings, and are indistinguishable from empty cells. This is true for both 
arguments and the values of cells in ranges.

The REXX procedure cannot do console I/O (no SAY or TRACE instructions), except 
to the log file, described above. You can use the REXX TRACE instruction in 
conjunction with the log_file argument described above, and then view the 
resulting log file from a text editor, such as the OS/2 System Editor, while 
1-2-3 is still active, as the file is closed when the REXX procedure completes 
execution. 
File I/O works just fine.

When you are first writing a REXX procedure to be invoked by 1-2-3, it is 
useful to first invoke the REXX procedure from the OS/2 prompt to have the REXX 
interpreter check it for syntax errors.

Tip-Consider executing your REXX procedures from a VDISK for improved 
performance.

Tip-Once your REXX procedure is running properly, remove the log_file argument 
to improve performance.

This support was compiled using the Microsoft C 6.0A compiler. The makefile is 
for the NMAKE utility. There should be few if any compatibility problems with 
current version of the IBM C/2 compiler.

You can detach an application by using the LIBRARY-DETACH macro command. To 
remove REXX support for 1-2-3, use the following command:

{library-detach rexxink}

If you have a worksheet open, @functions written in REXX are reevaluated and 
return ERR.

