	The REXX Column April, 1995 by Dick Goran	Index of articles
	Disclaimer: This material is reprinted here, as it was submitted to OS/2 Magazine, as a service to the OS/2 user community. Only minor editing has been done to accomodate the change to HTML format. Some of the information which was valid at the time the original column was written may now be obsolete. No assurance is implied as to its accuracy or completeness.

REXX Components

One of the more difficult tasks in learning a new programming language is trying to digest all of the facilities that the language provides. REXX has only 26 actual key-word instructions. Its power lies in the functions that accompany the instruction set. Tables 1 through 4 were compiled to provide the REXX programmer, particularly those who are new to the language, with a concise overview of these functions. Each table contains a logical grouping of the functions by what they do or the services they provide.

Table 1 contains a list of the 26 key-word instructions. Table 2, the largest of the four, contains a list of the built-in functions. Table 3 contains a list of the external commands provided with OS/2 REXX. Finally, Table 4 contains a list of the functions contained in the REXXUTIL application programming interface (API) which accompanies OS/2 REXX. At first glance, the limited number of key-word instructions might give the impression that REXX is limited in its scope. Quite the contrary. The small number of instructions and the large number of built in functions is one of the reasons that powerful REXX programs can be written so quickly and so easily.

Table 1 - Key-word instructions
ADDRESS	IF - ELSE	NUMERIC FUZZ	RETURN
ARG	INTERPRET	OPTIONS	SAY
CALL	ITERATE	PARSE	SELECT
DO	LEAVE	PROCEDURE	SIGNAL
DROP	NOP	PULL	TRACE
END	NUMERIC DIGITS	PUSH
EXIT	NUMERIC FORM	QUEUE

The built-in functions in Table 2 are divided into logical groups according to what they do. Most of the group names are self-explanatory. However, clarification is warranted on some. The conversion functions provide the capability of converting one type of field into another. The particular conversion is dictated by the key letters B, C, and X (both preceding and following the character 2 in the function name) representing binary, character, and hexadecimal. The Boolean functions permit individual bits to be used within strings. The Page Manager function is unique and allows REXX programs limited capability in producing graphical dialogue boxes with imbedded icons and push buttons.

Table 2 - Built-in functions

General Purpose
	DATE()
	TIME()

Numeric
	ABS()
	DIGITS()
	FORMAT()
	MAX()
	MIN()
	RANDOM()
	SIGN()

String
	ABBREV()
	CENTER()
	COMPARE()
	CONDITION()
	COPIES()
	DATATYPE()
	DELSTR()
	INSERT()
	LASTPOS()
	LEFT()

Words
	LENGTH()
	OVERLAY()
	POS()
	REVERSE()
	RIGHT()
	SPACE()
	STRIP()
	SUBSTR()
	TRANSLATE()
	VERIFY()
	XRANGE()

	DELWORD()
	SUBWORD()
	WORD()
	WORDINDEX()
	WORDLENGTH()
	WORDPOS()
	WORDS()

Conversion
	B2X()
	C2D()

Boolean
	C2X()
	D2C()
	D2X()
	X2B()
	X2C()
	X2D()

	BITAND()
	BITOR()
	BITXOR()

File System
	DIRECTORY()
	FILESPEC()

I/O
	CHARIN()
	CHAROUT()
	CHARS()
	LINEIN()
	LINEOUT()
	LINES()
	QUEUED()

System
	STREAM()

	ADDRESS()
	ARG()
	BEEP()
	ENDLOCAL()
	ERRORTEXT()
	FORM()
	FUZZ()
	RxFuncAdd()
	RxFuncDrop()
	RxFuncQuery()
	RXQUEUE()
	SETLOCAL()
	SOURCELINE()
	SYMBOL()
	TRACE()
	TRUNC()
	VALUE()

Page Manger
	RxMessageBox()

The System functions that appear in mixed case in Table 2 are unique to OS/2; whereas, all of the other built-in functions should be present in all of the other SAA REXX interpreters available from IBM.

Table 3 - External commands
RXQUEUE [option] [queue_name]
	Causes the data which follows it on STDIN (normally the keyboard, but can be the redirected output of a command) to be placed in queue_name or in the default REXX data queue SESSION if queue_name is omitted.
RXSUBCOM DROP env_name [dll_name] RXSUBCOM LOAD env_name [dll_name] RXSUBCOM QUERY env_name [dll_name] RXSUBCOM REGISTER env_name [dll_name]
	Drops, loads, queries or registers subroutines in env_name. Dll_name is the name of the Dynamic Link Library module name. Entry_point is the name of the function to be executed when called.

The REXXUTIL functions shown in Table 4 are what allow REXX to become so well integrated with OS/2 and the Workplace Shell. It is the object-related functions that permit REXX programs to create, manipulate, and alter WPS objects on an OS/2 system. The five functions identified with an asterisk (*) are new to OS/2 Warp Version 3.

Table 4 - REXXUTIL functions

Screen
	SysCls()
	SysCurPos()
	SysCurState()
	SysTextScreenRead()
	SysTextScreenSize()

File System
	SysDriveInfo()
	SysDriveMap()
	SysFileDelete()
	SysFileSearch()
	SysFileTree()
	SysMkDir()
	SysRmDir()

WPS Manipulation
	SysSearchPath()
	SysTempFileName()

	SysCopyObject() *
	SysCreateObject()
	SysCreateShadow() *
	SysDeregister ObjectClass()
	SysDestroyObject()
	SysMoveObject() *
	SysOpenObject() *
	SysQueryClassList()
	SysRegister ObjectClass()

Miscellaneous System Functions
	SysSaveObject() *
	SysSetIcon()
	SysSetObjectData()

	SysDropFuncs()
	SysGetEA()
	SysGetKey()
	SysGetMessage()
	SysIni()
	SysOS2Ver()
	SysPutEA()
	SysSleep()
	SysWaitNamedPipe()

Graphical User Interface (GUI), or Presentation Manager, programming is available with VX-REXX from WATCOM Systems, VISPRO REXX from Hockware, or Gpf REXX from Gpf Systems. There are also numerous APIs available as either freeware, shareware, or commercial products that further enhance REXX with OS/2. Quercus Systems produces the REXXLIB module and SoftNet distributes the GammaTech SuperSet/2 package both commercial offerings which provide a wide range of system-related functions, math routines, and file system functions. Also, the YDBAUTIL group of functions is available as rxu1a.zip.

Various other specialty APIs can be found on file repositories around the world. Some of the more popular function modules provide asynchronous communications, data base interfaces, high precision mathematical routines as well as some diverse specialty routines.

Using the Warp Internet Access Kit, you can "surf" the net looking for additional REXX APIs, many of which are free. As well as the other Internet addresses that have already been listed, the following are known to be REXX repositories: rexx.uwaterloo.ca/pub/freerexx, and ftp.cfsrexx.com/pub.

Correction

In last month's column, I published some wrong information about one of the five new REXXUTIL functions introduced in Warp. The error resulted from some ambiguous information released by IBM's Glendale Lab - the REXX development group.

The following is a corrected version of the definition of the SysSaveObject() function.

SysSaveObject( object_name, timing_flag )

Returns 1 if the WPS object object_name was successfully saved; otherwise, returns 0. File system objects (WPFileSystem) are saved in the file system's extended attributes and abstract objects are saved in the OS2.INI (user) file. Transient objects (WPTransient) cannot be saved.

Object_name can be a WPS object ID (the unique string preceded with a '<' and terminated with a '>') assigned to the object when it was created (e.g. ) or a fully qualified file name.

Timing_flag can be 0 (Boolean false - object is to be saved synchronously) or 1 (Boolean true - object is to saved asynchronously). If an asynchronous save is specified, the object will be saved on a separate thread ("lazy written"); this is the preferred method for saving. Otherwise, the object is saved on the user interface thread.

Warp / REXX Mystery Failures

There has been a "fix" in Warp Version 3 implemented by IBM that is subtly causing REXX programs, that ran with prior versions of OS/2, to fail. The culprit is the lack of file handles in the OS/2 session where the REXX program is running.

The default number of file handles, a resource required for each open file, is, and has been, twenty. Of the twenty, fifteen are available for user programs with five being reserved for system-related files. Prior to Warp Version 3.0, when multimedia support was installed it changed the default for the number of file handles from twenty to eighty. Apparently, this was being done without the knowledge of the kernel developers and they deemed it necessary to "correct" this problem.

The end result is that if you have a REXX program that inadvertently references file with any of the input/output (I/O) functions: CHARIN(), CHAROUT(), CHARS(), LINEIN(), LINEOUT(), or LINES() or uses any library functions that do not close all of their files (for example - the SysGetMessage() function); these programs may begin to fail. The only way to prevent this from happening is to increase the number of file handles available in the particular session where the program is running. This can be done with the GrowHandles() C function. Quercus Systems has implemented this capability in their latest version of REXXLIB, a commercial product that is available in a fully functional "demo" form from your favorite OS/2 BBS or repository. With the addition of rexxlib.dll, you can call the DOSFILEHANDLES() function and specify the number of file handles you want to be available for that session. Once the number of file handles has been increased, the larger number of file handles remain available to that session until the session is closed.

Return to index