REXX Libraries -- Extending the REXX Function Set

Presented by Gary Granat

Introduction and Overview:
- Welcome
- About the Presentation:
  - About the REXX Language
  - A Review of REXX Functions
  - Extending REXX -- The REXXUtil Library
  - Extending REXX -- REXXLib
  - Extending REXX -- REXX SuperSet/2
  - Reference
About the REXX Language:
- REXX was developed by Mike Cowlishaw of IBM between 1979 and 1982.
- REXX was designed to be an easy-to-read, easy-to-use, personal programming language. As the same time, it was designed not to sacrifice power to ease-of-use.
- REXX is available on numerous platforms:
  - VM/CMS (1983)
  - PC/DOS (Personal REXX, 1983)
  - ARexx (Commodore Amiga, 1987)
  - OS/2 (Personal REXX, 1989; IBM implementation on OS/2 1.2, 1990)
  - MVS/TSO (early 1990's)
    and REXX implementations have appeared for these platforms:
  - OS/400
  - AIX
  - UNIX
  - Tandem
  - Windows/Windows95/WindowsNT
- The American National Standards Institute (ANSI) issued standard X3.274-1996 in 1996 for Programming Language -- REXX.
A Review of REXX Functions:
What is a Function?
- A function is a programming language construct that is designed to provide some sort of service
- A function is called (sometimes) with an argument
- A function always returns some value to the caller
Thus, in: today = date() the value of "today" is "19 Sep 1998" today = date("M") the value of "today" is "September" today = date("U") the value of "today" is "09/19/98" "Built-In" Functions in REXX:
- REXX is replete with a number of "built-in" functions; this is one of the major strengths of the language
- A complete implementation of the standard provides between sixty-four and sixty-seven functions (depends on the I/O model adopted);
- Individual implementations may include additional functions, if needed
- The "built-in" REXX functions provide these services:
  
  I/O and File-Related Services:
  These functions tend to be specific to the implementation for a particular operating system.
  - The official I/O model uses the charin/charout/linein/lineout functions
  - The "unofficial" I/O model, developed by IBM for its operating system (which do not support character or line input and output) uses the execio function
    Some of the OS/2 REXX functions in this class are:
  - System Services:
    These functions return information about the state of some element of the system or preserve/restore information about state. A few of the OS/2 REXX functions in this class are:
    ADDRESS() -- returns the name of the current environment to which "host" commands are submitted (do not confuse with the ADDRESS keyword) BEEP(frequency, duration) -- sounds the system speaker at "frequency" (range is 37-32,767) for "duration" (range is 1-60,000)
  - Data Conversion and Numeric Services:
    REXX has a single datatype -- the string. It has, however, a powerful set of conversion and numeric functions used to transform the numeric presentation of data. Some of the OS/2 REXX functions in this class are:
    ABS(number) -- returns the absolute value of "number" as an unsigned value in the format specified by the NUMERIC keyword. B2X(binary_string) -- returns the hexadecimal value of "binary_string" (which must contain only "0"'s and "1"'s) C2X(string) -- returns the hexadecimal value of "string" FORMAT(number[, [before][, [after][, expp][, expt]]]]) -- returns "number" rounded and formatted; the integer is "before" and the fraction "after" characters in length; "expp" defines the number of places in the exponent and "expt" when an exponent is triggered TRUNC(number[, n}) -- returns the integer part of "number" and "n" decimal places; "number" is rounded, as needed before truncation occurs
  - String Manipulation Services:
    Most of the built-in functions support a variety of string manipulation services. A few of the ones in OS/2 REXX are:
    CENTER(string, length[, pad]) -- returns "string" centered in "length" and padded with the "pad" character(s), if specified (defaults to blank) COMPARE(string1, string2[, pad]) -- returns "0" if "string1" and "string2" are identical; otherwise, returns the position of the first character that does not match COPIES(string, n) -- returns "n" copies of "string" DATATYPE(string[, type]) -- if only "string" is specified, returns either "NUM" ("string" is a valid REXX number) or "CHAR"; when "type" is specified, returns "1" if "string" is of that type or "0" if it is not (there are 11 possible "type" values) DATE([option]) -- returns the current date in the format specified by "option"; if "option" is omitted, returns "dd Mon yyyy" LEFT(string, length[, pad]) -- returns the left portion of "string" to "length" size; "string" is truncated to "length" if necessary, or padded with the "pad" character LENGTH(string) -- returns the length of "string" RIGHT(string, length[, pad]) -- returns the right portion of "string" to "length" size; "string" is truncated to "length" if necessary or padded with the "pad" character SPACE(string[, [n][, pad]]) -- returns "string" formatted with "n" "pad" characters between each word STRIP(string[, [option][, char]]) -- returns a copy of "string" with leading, trailing or both leading and trailing "char" characters removed; "char" defaults to a blank; "option" defaults to both SUBSTR(string, n[, [length][, pad]]) -- returns a substring of "string" beginning at character "n" and "length" characters long; the returned string is padded with "pad" if necessary SUBWORD(string, n[, length]) -- returns a substring of "string" beginning at word "n" and up to "length" words long TIME([option]) -- returns the local time as HH:MM:SS or in the format specified by "option"; "option" can be one of eight values TRANSLATE(string[, [table_out][, [table_in][, pad]]]) -- returns "string" with the characters in "string" specified in "table_in" translated to the corresponding characters (by position) in "table_out"; "table_out" is padded with the "pad" character as needed WORD(string, n) -- returns the "n"th blank-delimited word in "string" WORDPOS(phrase, string) -- returns the word number of the first occurrence of "phrase" in "string" WORDS(string) -- returns the number of words in "string"; returns "0" if "string" is nil or consists only of spaces
  - Error Handling Services:
    These are the most common functions associated with error handling:
    CONDITION([option]) -- returns the condition information associated with the current trapped condition; several options control the information element(s) returned ERRORTEXT(n) -- returns the error text associated with a REXX error number; "n" is in the range 0 <= n <= 99
Extending REXX:
- The REXX language is designed to be extended through additional functions -- written either in REXX or in another programming language; when the functions are written in another language, they are collected into function libraries
- An external REXX library must be registered before the contained functions can be used; this is the general syntax needed to register a library:
- The balance of this presentation consists of an overview of three REXX function libraries (however, these are, by no means the only REXX extension libraries in existence)
Extending REXX -- The REXXUtil Library (IBM)
- This function library is integrated into the OS/2 delivery package; it was originally delivered as a part of Version 2.0 and has been regularly updated with each major release since then
- The current version of the REXXUtil library contains seventy-one functions that fall, generally, into three operational areas:
  - OS/2 System Services: These functions perform system activities such as copying and deleting objects. A few of these are: SysBootDrive() -- returns the drive used to boot OS/2; for example, "C" SysCopyObject(nameofObject, nameofDestination) -- returns "1" if the named object is successfully copied to the destination, or "0" if the copy was unsuccessful; "nameofObject" can be either an object ID or a fully-specified filename SysDestroyObject(name) -- returns "1" if the named object is successfully destroyed, or "0" if the operation failed; "name" can be either an object ID or a fully-specified filename SysSleep(n) -- returns "0" when the REXX program has paused for the number of seconds specified by "n"
  - Text/Screen I/O: These functions manage various screen activities. Some examples are:
    SysCls() -- returns a "0" when the screen has been successfully cleared SysTextScreenSize() -- returns two values indicating the size of the screen in rows and columns SysTextScreenRead(row, col[, length]) -- returns the text string read from the screen starting at "row" row and "col" column for the length specified by "length"; if "len" is omitted, the read continues to the end of the screen
  - OS/2 .INI File I/O: A single function manages elements of an .INI file:
    SysIni([inifile], app|'ALL:', key|'ALL:'|'DELETE:', value|stemname) -- this function has six different modes; the value returned depends on the function mode; sets, queries, and deletes elements of the .INI file specified by "inifile"
Extending REXX -- REXXLib (Quercus Systems)
- The REXXLib functions (which includes an additional function library called RXWINDOW) were originally published as a part of Personal REXX, Version 3
- REXXLib is the stand-alone version of the Personal REXX function library (the Personal REXX version requires the use of Personal REXX)
- Because it was released before REXXUtil, some of the REXXLib functions duplicate those in REXXUtil
- REXXLib consists of about 150 functions that support array manipulation operations; a very complete set of system operations; screen read and write operations; system hardware and software information operations; macrospace operations; named pipe operations; event semaphore operations; and mathematical, including trigonometric operation
- These are some of the functions in some of these categories:
  - Array Manipulation: REXX "arrays" consist of data in stem variables, also called compound variables. REXXLib provides functions to add to, delete from, sort and otherwise manage the data in arrays. A few function are: ARRAYCOPY(fromstem, tostem, [from], [to], [count]) -- copies "count" elements in the integrally-indexed array "fromstem" to "tostem" beginning at "from" and ending at "to" CVCOPY(fromstem, tostem) -- copies all the values in "fromstem" to "tostem"; "fromstem" and "tostem" can be arbitrarily-indexed arrays ARRAYSORT(stem, [first], [n], [[start], [length], [order], [type],...]) -- sorts the integrally-indexed REXX compound variable "stem" starting with the "first" element for "n" elements based on one or more fields in the array of values; a field in an element is "length" characters wide beginning at the "start" position; "order" defines the type of sort (ascending or descending); "type" defines how the content of a field is interpreted (case-sensitive, case-insensitive, or numeric)
  - System Operations: REXXLib provides 47 functions to manage the file system and various aspects of process execution. A few of these are: DOSCOPY(sourcename, [targetname], [mode], [options]) -- copies the contents of "sourcename" to "targetname"; "mode" ("R" - replace, "A" - append, "N" - no action) defines how to handle "targetname" if it already exists; "options" controls content verification DOSFDATE(filename, [newdate], [newtime]) -- changes the last write date and time of "filename" to "newdate" and "newtime" DOSMKDIR(pathname) -- makes the "pathname" directory; fails if "pathname" includes intermediate directory names that do not exist -DOSMAKEDIR(pathname) -- make the "pathname" directory; creates any intermediate directories specified in "pathname" if they do not already exist
  - System Hardware Information: These functions return information about various aspects of the system hardware. A few of these are: PCMODEL() -- returns the system model value contained in the BIOS PCRAM() -- returns the number of 1024-byte memory blocks installed in the system PCVIDEOMODE() -- returns four space-delimited numbers indicating, respectively, the success of the function call, the number of bits used to display color information for each pixel, the horizontal resolution in pixels, and the vertical resolution in pixels
Extending REXX -- REXX SuperSet/2 (SofTouch Systems)
- REXX SuperSet/2 delivers 370 functions in eight classes
- REXX SuperSet/2 has a strong orientation on communications activities
- Each function category class of a separate DLL, allowing registration of those functions needed
- The REXX SuperSet/2 overlaps both REXXUtil and REXXLib
- These are some of the functions provided in each category:
  - Communications Manager/2 CPIC Functions: These functions are useful to those who are programming in a Communications Manager/2-supported environment (generally either a 3270 or 5250 host-connected terminal environment. Use requires an understanding of the "C" language CPIC APIs.
    - No examples
  - EHLLAPI Interface Functions: These functions provide an interface to Communications Manager emulator sessions. Access to all EHLLAPI services excepting asynchronous services.
    - No examples
  - "Host" Functions:
    These four functions provide services that are available on most MVS and VM/CMS operating systems. EXECIO is an example of this class. It has several forms:
    - EXECIO rcdcnt DISKW filename ([STEM varname] [FINIS] -- writes "rcdcnt" records to "filename" from data contained in the compound variable "varname"; if "FINIS" is included with the instruction (or is the only argument) "filename" is closed when the write is finished
    - EXECIO rcdcnt DISKR filename startrcdnum ([FINIS] [FIFO|LIFO|SKIP] -- reads "rcdcnt" records from "filename" starting with record number "startrcdnum"; records are read into the current REXX queue in the order specified ("FIFO", "LIFO", "SKIP"); if "FINIS" is included "filename" is closed when the read concludes
    - EXECIO rcdcnt DISKR filename startrcdnum ([STEM varname] [FINIS] -- reads "rcdcnt" records from "filename" starting with record number "startrcdnum"; records are read into the compound variable "varname"; if "FINIS" is included, "filename" is closed when the read concludes
  - LAN Server Interface Functions: Provides an interface to the IBM LAN Server and Warp Server APIs. Many of these functions may also be usable for IBM Peer Services.
    - No examples
  - NetBIOS Interface Functions: Provides a single function name to be use with any of eighteen parameters to perform NetBIOS services.
    - No examples
  - TCP/IP Interface Functions: Provides an interface to the TCP/IP Sockets and FTP APIs. Examples are:
    - GrxFtpPwd(host, id, pwd, acct, 'hostdesc') -- returns a description of the remote FTP host "host" in the variable "hostdesc"; "id", "pwd", and "acct" are the values used to log on to the remote host
    - GrxTcpPing(host, len) -- resolves the host name "host" and sends a ping packet of length "len" to determine if "host" is responding; "host" contains an internet address in standard dot notation
  - User Profile Management Functions: Provides an interface to User Profile Management services. Supports administration activities in a LAN Server environment.
    - No examples
  - General OS/2 Utility Functions: Provides an interface to many low-level and high-level services for the OS/2 environment. Eight operational categories of service are supported:
    - Date Manipulation Functions:
      Two functions are provided. They convert a standard date to a REXX "base" date and convert a "base" date to a standard date.
      - GrxDateToBase(datestr, [fmtstr]) -- returns standard REXX basedate data type for the formatted string "datestr"; "fmtstr", which may be any of "L", "N", or "S", controls the format of the returned value; an incorrectly formatted value in "datestr" causes an error to be returned
      - GrxBaseToDate(datestr, [fmtstr]) -- returns the formatted REXX date for the standard REXX basedate value "datestr"; "fmtstr", which may be any of "L", "N", or "S", controls the format of the returned value; an incorrectly formatted value in "datestr" causes an error to be returned
    - File and System Functions: Twenty-two functions are provided. They access a wide variety of file and system services. One example, which is unique to REXX SuperSet/2 is:
      - GrxShutdown -- does not return a value to the calling REXX program; accesses the system shutdown API, terminating the current process
    - Math Functions: Extends the mathematical capabilities available in REXX through the addition of twenty-on functions. These functions are derived from the equivalent IBM C Set++ functions and do not obey the current REXX NUMERIC setting.
      - No examples
    - Named Pipe Functions: Eight functions are provided to control named pipe services.
      - No examples
    - Process Functions: Manipulate and return information about system processes.
      - GrxGetPID([option]) -- returns the ID of the process identified by "option"; "option" may be either "C" (current) or "P" (parent); if "option" is omitted, defaults to "C"
      - GrxKillProcess(pid, [option]) -- returns a value indicating the degree of success terminating the "pid" process; "pid" is a string containing the process ID; "option", if present is either "P" (current process only) or "T" (current process and all child processes); if "option" is omitted, defaults to "P"
    - REXX Macrospace Manipulation Functions: Seven functions support management of the contents of the REXX macrospace.
      - No examples
    - Semaphore Functions: Twenty functions provide services to manage and manipulate OS/2 semaphores.
      - No examples
    - VIO (Character-Mode) Functions: Twenty-two functions provide services to manipulate and manage character-mode screens and their contents.
      - No examples
Reference
- REXXLIB available from Quercus Systems
- REXX SuperSet/2 from SofTouch Systems
- See also Hobbes REXX Directory and Hobbes Object REXX Directory
The Southern California OS/2 User Group
www.scoug.com
P.O. Box 26904
Santa Ana, CA 92799-6904, USA
Copyright 1998 the Southern California OS/2 User Group. ALL RIGHTS RESERVED.
OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.

REXX Libraries -- Extending the REXX Function Set

Introduction and Overview:

About the REXX Language:

A Review of REXX Functions:

Extending REXX:

Extending REXX -- The REXXUtil Library (IBM)

Extending REXX -- REXXLib (Quercus Systems)

Extending REXX -- REXX SuperSet/2 (SofTouch Systems)

Reference