A rich selection of functions is an integral part of the REXX language. We will break the major functions into four groups: Data Conversion, Input/Output, Math, and String.

Novice REXX programmers should concentrate their study on the bold functions below. Note that there are a few more functions that we will ignore in this basic course.

There are two types of general Input and Output:

• Sequential (often called "Serial" or "Record") I/O such as a magnetic tape, where one record follows another and one must read all previous records and write all subsequent records before or after dealing with any given record.

• Direct Access I/O such as a magnetic disk or CDROM where the access mechanism can move directly to a particular data element.

REXX will support both types, however we will not cover direct access here.

Your bread and butter Input functions will be:

LINEIN( filename, input_line, [, count ] )

filename -- usually an input file name. Files are implicitly opend with the first call to LINEIN.

input_line -- a string variable to accept the line

count -- if present, must be zero or one. Basic users should omit this parameter.

CHARIN( [ filename ] [, start ] [, length ] )

filename -- usually an input file name. Files are implicitly opend with the first call to CHARIN.

start -- optional offset from the beginning of the file. (default = 1)

length -- optional maximum length. (default = 1)

Typical use:

/* Copy a file line by line */

Input_File_Name = "USER_FILE.TXT"

Output_File_Name = "COPIED_FILE.TXT"

DO WHILE ( LINES( Input_File_Name ) > 0 )

     rc = LINEIN( Input_File_Name, Data_Line )

     rc = LINEOUT( Output_File_Name )

END

rc = LINEOUT( Output_File_Name )

rc = LINEOUT( Input_File_Name )

- - - - - - - - -

/* Copy a file character by character */

Input_File_Name = "USER_FILE.TXT"

Output_File_Name = "COPIED_FILE.TXT"

DO WHILE ( CHARS( Input_File_Name ) > 0 )

     This_char = CHARIN( Input_File_Name )

     rc = CHAROUT( Output_File_Name, This_char )

END

rc = CHAROUT( Output_File_Name )

rc = CHAROUT( Input_File_Name )

While these programs will certainly do the job, a more robust program would check the returned value "rc" to see if the operation was successful.

It is considered good technique to close a file when you are finished with it.. This can be done by calling LINEOUT or CHAROUT without specifying any data to be written. REXX will usually close all open files when the program ends, but we've learned that obscure, intermittent problems can be prevented by explicitly closing all files.

REXX string functions contain the usual compliment of string functions that programmers expect:

SUBSTR( string, n, length , pad )

string -- input string.

length -- maximum number of characters to be returned. n = 1 is the first character.

pad -- Enough pad characters will be added such that the output string will be length characters.

POS( needle, haystack, start )

needle -- String we are searching for.

haystack -- String to be searched.

start -- the starting position of the search.

Returns the first position satisfying the search or zero if the needle is not found.

LEFT( string, length, pad )

string -- input string.

length -- maximum number of characters to be returned.

pad -- pad character.

Returns the first length characters of the string, If necessary, pad characters will be added to the right end of the string to satisfy length.

RIGHT( string, length, pad )

string -- input string.

length -- maximum number of characters to be returned.

pad -- pad character.

Returns the last length characters of the string, If necessary, pad characters will be added to left end of the string to satisfy length.

LENGTH( string )

Returns the length of string.

REXX also defines some not so standard string functions.

ABBREV( string, test_string, length )

COMPARE( strinng1, string2, pad )

COPIES( string, n )

DELSTR( string, n, length )

DELWORD( string, n, length )

FILESPEC( option, filespec )

option --

D: return the drive letter [ C: ]

P: return the file path [ \OS2\DRIVERS\ ]

N: returns the file name [ FD8XX.EXE ]

INSERT( new, target, n, length, pad )

LASTPOS( needle, haystack, start )

OVERLAY( new, target, n, length, pad )

REVERSE( string )

SPACE( string, n, pad )

STRIP( string, option, char )

SUBWORD( string, n, length )

TRANSLATE( string, out_map, in_map, pad )

string -- input string to be searched

out_map -- table of output characters

in_map -- table of input characters

pad -- out_table will be padded with pad characters to match length of in_table

Scans through string, character for character, searching for a matching entry in in_map. If found, the corresponding entry in out_map replaces the input character in the returned output string. If out_map is shorter than in_map, out_map will be padded with pad.

VERIFY( string, characters, option, start )

WORD( string, n )

WORDINDEX( string, n )

WORDLENGTH( string, n )

WORDPOS( phrase, string )

WORDS( string )

PARSE

PARSE is one of the more unusual functions provided by REXX.

As REXX programmers we are oftenfaced with the task of breaking down a string of text into its elements. There is an endless list of such strings, below are a few examples:

"First name","Last name","Address 1","Address 2","City","State","Zip"

First Second third forth FIFTH

A=1 B=2 C=3 E=4

/F:config.sys /D:3-26-2001 /t:3:32

Breaking down such strings, while straight forward, is tedious and error prone. PARSE provides an easy to use facility to solve this sort of problem.

Technically, PARSE is not a REXX function, it is a keyword that has several forms:

PARSE [UPPER] ARG [template]

PARSE [UPPER] LINEIN [template]

PARSE [UPPER] PULL [template]

PARSE [UPPER] SOURCE [template]

PARSE [UPPER] VALUE [expression] WITH [template]

PARSE [UPPER] VAR name [template]

PARSE [UPPER] VERSION [template]

PARSE is one of the most difficult to master REXX facilities, but your time will be well spent. Here is an example of the power of PARSE:

    /* example */

    person = '"First name","Last name","Address 1","Address 2","City","State","Zip"'

    D = '","'

    PARSE VAR person '"' First (D) Last (D) Addr_1 (D) Addr_2 (D) City (D) State (D) Zip '"'

    say First
    say Last
    say Addr_1
    say Addr_2
    say City
    say State
    say Zip

This is a bit easier than writing a routine to pick through a data record character by character.

Be careful, there is a subtle trap in the PARSE Keyword -- If anything is left over at the end of the scan, it will be assigned to the last variable, if any. That's why we have the final trailing double quote after the Zip entry. (Check your reference and think about that for a while!)

Unfortunately, REXX does not provide any Date or Time calculation functions. DATE() and TIME() return the current system date and time, in various formats.

DATE( option )

TIME( option )

---

About these pages Content updated: 07-09-2005 09:40am

Page building by:

Content updated 07-09-2005 09:40am