REXX CGI Script Function Library for OS/2 Warp and eComStation.

Version 1.0 © October 2002 by Igor Pool [igor@igor.co.nz]

Getting Started

Installation

To install REXXWEB copy the file rexxweb.dll to a directory which is included in the path statment in your config.sys.

A typical directory would be x:\os2\dll [where x: is the boot drive]

To access the functions from the DLL you need to load the DLL. This is done by either adding the following lines to your rexx scripts or creating a rexx script called startup.cmd in the root directory of your boot drive which includes the following lines which is executed automatically when OS/2 or eComStation boots up.

       /********/
       call RxFuncAdd 'RexxwebLoadFuncs', 'REXXWEB', 'RexxwebLoadFuncs'
       call RexxwebLoadFuncs

You are now ready to use REXXWEB.

Deinstallation

To remove rexxweb.dll from your system stop all rexx scripts which call any of the functions then delete all copies of the DLL and reboot the machine. Any rexx scripts which use the functions contained in the DLL will cease to function until it is reloaded.

Applying Updates

Exit all rexx scripts or applications which call the rexxweb functions. Replace your existing copy of rexxweb.dll with the new version and run script calling the above function to reload the REXXWEB functions.

getFormData

Retrieves URL form data from either a GET or POST method and stores it in the rexx variable WWWFORMDATA.

This function must be called BEFORE any calls using getFieldData or getFieldNames can be made.

For CGI script debugging you can dump the contents of WWWFORMDATA to disk using the WriteToDisk function.

Function returns 0 if URL data retrieved successfully or 1 if not.

getFieldNames

Returns list of field names submitted by a form using either the GET or POST methods into stem variable rexxvar.

rexxvar.0 holds the total number of fields returned.

Forms using enctype multipart/form-data are not supported

getFieldData

This function extracts from WWWFORMDATA the data corresponding to form input field field name. The data is then truncated to length if nescessary and validated as type.

Note length is the maximum data to be returned. If set to 0 no length check is done

Field values such as those received by from Select box with the MULTIPLE attribute are returned separated by a CRLF. This only works for forms submitted with the default encoding type of APPLICATION/X-WWW-FORM-URLENCODED or TEXT/PLAIN.

Files uploaded by multipart/form-data are placed into field name. Two additional variables are created field name_name which holds the orginal file name and field name_size which holds the file size in bytes.

Data received can be returned in another rexx variable specified by rexxvar parameter.

URL2Ascii

Converts URL encoded characters in rexxvar to their ASCII equivalent. Characters such as Double and Single quotes, Line Feeds and Carriage Returns can be removed by specifying a dropout string with one of the following options:

• D - drops double quotes
• S - drops single quotes
• C - drops carriage returns
• L - drops line feeds

• P - Replaces Line Feeds with HTML Paragraph Tag
• B - Replaces Line Feeds with HTML Break Tag

Ascii2HTML

Converts any ASCII chars in rexxvar to their HTML eqvivalent.

Returns 0 if conversion successful or 1 if not.

Validate

Returns 0 after verifying the contents of rexxvar is of type and length. Function returns 1 if type validation fails or 2 if length check fails.

If length is set to 0 no length check is done.

Type	Result
T	Text. May contain a-z A-Z 0-9 . , / < > ? ; : [ ] \ { } | ` ~ ! @ # $ % ^ & * ( ) _ + - = SPACE
A	Alphanumerics. May contain a-z A-Z 0-9 . - SPACE
N	Numerics. May contain 0-9 . -
I	Integer. May contain 0-9 -
C	Currency to 2 decimal places. May contain 0-9 . $
E	E-mail using format user@domain. May contain a-z A-Z 0-9 . - _ @
P	Phone using format (area_code) number. May contain () 0-9 SPACE

DoubleQuoted

Alters the contents of rexxvar by adding an extra quote after each existing quote as required by most Database Systems. By default both extra single and double quotes are added. By specifying either 'S' or 'D' in option you can elect to double up on either single or double quotes. Returns 0 if successful or 1 if an error occured.

EncodeString

Return a hex encoded string double the length of the string supplied.

A8CAE6E840A6E8E4D2DCCE = EncodeString('Test String')

DecodeString

Return a hex encoded string double the length of the string supplied.

Test String = DecodeString('A8CAE6E840A6E8E4D2DCCE')

getTextString

Returns the string matching stringname from filename. If stringname is not found a 1 is returned. rexxvar allows you to specify an alternative REXX variable with which to return the string.

filename must include the full path to an ASCII file using the following format:

stringname: string

For example:

httpserver: http://www.igor.co.nz/
copyright: ©2000 www.igor.co.nz
email: igor@igor.co.nz
page: index.htm
page: contact.htm
page: about.htm

getAllTextStrings

Loads all text strings found in filename into individual REXX variables.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

getTextStringName

Returns the string name matching the first occurance of stringvalue. Check is not case-sensitive and any leading or trailing spaces in stringvalue are ignored.

stringvalue is limited to 256 bytes of data.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

getTextCollection

Returns the collection of strings matching stringname from filename in a stem of stringname. If stringname is not found a 1 is returned. rexxvar allows you to specify an alternative REXX stem variable with which to return the string.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

getAllTextCollection

Returns the collection of strings from filename in a stem of rexxvar.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

setTextString

Sets the string stringname in filename to the value of the rexx variable stringname. If stringname does not exist then it is created. If rexxvar is supplied then the value of the rexx variable rexxvar is used.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

setTextCollection

Writes the stem variable stringname to filename. Any existing occurances of stringname are replaced. rexxvar allows you to specify an alternative rexx stem variable to source values from for stringname.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

addTextString

Adds the value of the rexx variable stringname to filename. If rexxvar is supplied then the value of the rexx variable rexxvar is used.

filename must point to an ASCII file as per getTextString function.

Long file names supported under HPFS.

getTextFile

Returns the contents of a text file in rexxvar after substituting place holders identified by #name# for the value of their rexx variable equivalent. Place holders which do not have an equivalent rexx variable are removed.

Place holders in the text file may include optional justification commands which specify either left or right and a length e.g.

Customer Name: #L20:customer_name# Amount Overdue: #R10:amount#

will become:

Customer Name: Igor Pool            Amount Overdue:     100.00

If filename is not found a return code of 1 is returned.

filename must include the full path to an ASCII file.

File size is limited to available system memory. Long file names supported under HPFS.

WriteToFile

Writes the contents of the rexx variable rexxvar to filename. If filename already exists it is deleted. No additional carriage return or linefeed characters are added to the file and the file is closed.

Returns 0 is successful and 1 if not.

Long file names supported under HPFS.

RenameFile

Renames oldfilename to newfilename returning 0 if successful and 1 if not.

Long file names supported under HPFS.

DeleteFile

Deletes filename returning 0 if successful and 1 if not.

Long file names supported under HPFS.

ReplaceString

Scans the rexx variable rexxvar replacing each occurance of StringOut with StringIn.

option can be used to specify either MIXED case or EXACT case.

Returns 0 is successful and 1 if not.

StringIn and StringOut are both limited to 256 characters.

CapitaliseString

Coverts the contents of the rexx variable rexxvar to lowercase then capitalises the first letter of each word. option can be used to specify either only the FIRST word, ALL words (default) or the first letter of the first word in each SENTENCE.

Returns 0 is successful and 1 if not.

StringCase

Coverts the contents of the rexx variable rexxvar to either lowercase or uppercase. option can be used to specify either LOWER or UPPER. Both 7bit and 8bit characters are converted.

Returns 0 is successful and 1 if not.

CGIScriptError

Returns a complete HTML page and terminates the script. The default output is:

If redirectURL is provided then a blank page with optional backgroundcolor is returned that redirects the browser to redirectURL.

getImageSize

If successful function returns a string containing 3 words identifying the image type (GIF, BMP or JPG) and width and height in pixels.

If the image is larger than the optional maxwidth or maxheight the aspect ratio is calculated and the returned width and height adjusted accordingly.

Supported formats are GIF87a, GIF89a, BMP (Windows and OS/2), JPG.

Long file names supported under HPFS.

getDirectoryUsage

If successful function returns total disk space used in the directory specified. An invalid directory path results in an empty string being returned.

BuildHTMLGraph

This function will construct the HTML graph based on data supplied in two stems and put the graph into graphvar. Returns 0 if graph build successful or 1 if not.

Setup. contains the layout and configuration controls as follows.

• graphtitle: Graph Title
• xlabel: X-axis label
• imageurl: URL to single pixel gif images for graph bars and layout
• positivebarcolour: Bar colour for positive values (refers to single pixel gif image filename).
• negativebarcolour: Bar colour for negative values (refers to single pixel gif image filename).
• backgroundcolour: Background colour for graph.
• graphwidth: Width in pixels (don't make it too small! 500 is good).
• graphheight: Height in pixels (don't make it too small! 200 is good).

Setup.0 must be set to the appropriate number of setup elements.

Data. contains the graph bar data in the form:

label : value : colour : url <- Use : [colon] to seprate parts

Where:

• label: Bar Label
• value: Value of bar
• colour: Bar colour
• url: Provides optional URL link to bar. Do not include http://. This can be used to provide a drill down effect.

Data.0 must be set to the appropriate number of data elements.

BuildHTMLCalendar

This function will construct an HTML based calendar for the month and year supplied and put the HTML code into calendarvar. Returns 0 if calendar build is successful or 1 if not.

The options stem variable allows you to change the appearance of the calendar as follows.

• width: Sets width of calendar table. If width is not evenly disvisable by 7 then width will be adjusted but will not exceed what was specified. There is a minimum width of 200.
• border: ON/OFF Controls calendar bordering.
• weekstart: Sunday/Monday [default Sunday]
• headertextcolour: Sets text colour for calendar header [default White]
• headercolour: Sets background colour for calendar header [defaut Black]
• calendarcolour: Sets background cell colour for overall calendar [default White]
• datetextcolour: Sets text colour for calendar [default Black]
• showtoday: Hightlight current day cell [default YES]
• todaycolour: Sets background cell colour for current day [default Red]
• blankdaycolour: Sets background cell colour for blank cells [default White]
• dayformat: Use SHORT [Mo..Su] or LONG [Monday..Sunday] day format.
• datelinktarget: Specify the name of target window or frame for date link.

February 2001
Su	Mo	Tu	We	Th	Fr	Sa
				1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28

BuildHTMLList

This function will construct an HTML List using the CRLF sequence found in rexxvar to identify new list items. Returns 0 if list build successful or 1 if not.

BuildPDF

Converts the contents of rexxvar into text only Adobe PDF format. Once converted the contents of rexxvar can be sent as an attachment via sendSMTP or written to disk with WritetoFile.

Optional parameters title, subject and author can be used to describe the document.

• The Font is set to Courier 12.
• Page size is 8.5 x 11 inches.
• A page consists of 60 rows by 70 cols. Any line which exceeds this is automatically wrapped.
• Preceeding spaces at the begining of a line are not stripped. This allows for text formating using getTextFile as the courier font is monospaced.
• Commands to control layout and graphics. Commands must start at the begining of a line and begin with a colon. Remaining data on the line is ignored.
  • Graphics commands with coordinates 0,0 located in the top left-hand corner. All parameters must be supplied - those in square [] brakets are optional.
    • :LINE x1 y1 x2 y2 line_size
    • :RECT x y width height line_size [color]
      Colour is a RGB value represented in Hexadecimal form similar to that used in HTML. Some basic colors are Black = 000000, Orange = 007F00, Blue = 0000FF, red = FF0000, green = 00FF00
    • :LABEL font fontsize x y; data
      Valid fonts are Courier, Courier-Bold, Helvetica and Helvetica-Bold. Fontsize must be an integer greater than zero. LABEL data can also contain %PAGE, %DATE and %TIME markers for substitution with appropriate values.
  • :NEWPAGE will start a new page.
  • :DIVISION [Y]
    Y specifies new starting value in pixels where all further text and graphic functions will be relative to. If Y is not specified the new division starts at the current line position.

To help minimise file sizes group any graphical commands at the top of each page by command. This ensures minimal overhead within the resulting PDF to describe the page.

BuildPDF returns 0 if PDF successfully created and 1 if not.

sendSMTP

Send an e-mail via SMTP to the mail server specified in server. If the mail server is on a port other than port 25 use server:port.

recipient can either be a standard rexx variable or a rexx stem variable if more than one recipient is required. A maximum of 100 recipients in a stem variable is permitted.

attachment can either reference a single file or a rexx stem variable if more than one attachment is required. Contents of Rexx variables can also be included as a attachment if rexxvar is prefixed by VAR:variable. The file name for the attachment can be added by including NAME:attachment name e.g.

VAR:disclaim NAME:disclaimer.txt

Rexx variable contents limited to printable ASCII. A maximum of 100 attachments per e-mail is permitted. Files are encoded using base64.

encoding can be used to specify encoding of the message as either Plain (no encoding) or Quoted-Printable (Default). Valid values are either P or Q.

When the function has a return code greater than 0 the e-mail addresses specified in the REXX stem variable recipient which failed are returned in the same stem variable. recipient.0 is set to the appropriate value. A common reason for this is that the mail server is not able to relay mail to other domains or the address is invalid.

POP3Mail

Connects to the POP3 server specified in server using user and password. If the POP3 server is on a port other than port 110 use server:port.

Password is transmitted as plain text.

The default is for all messages to be returned although a single message can be requested by supplying message-index.

getHTTPDocument

Retrieves the document specified by httpURL from an HTTP web server and returns the document in the REXX variable rexxvar.

getHTTPDocument will follow through on redirects which is common for a number of web sites. The maximum number of redirects permitted is 5.

Optional parameter modified-since can be used to specified a date (format dd-mm-yyyy) which will return the requested document if it has been modified since. Not all web servers have support for this function and usually html files and CGI scripts can not be date checked as they may contain either server side includes or be generated on demand. This parameter is ignored if the cgidata parameter is specified.

browser-type can be used to specify a browser type other than the default Rexxweb.dll for OS/2, for example:

Mozilla/4.0 (compatible; MSIE 5.0; Windows 95; DigExt)
Mozilla/4.61 [en] (OS/2; U)
Mozilla/5.0 (OS/2; U; Warp 4.5; en-US; rv:0.9.4) Gecko/20020328

cgidata can be used to specifiy a rexx variable containing URL encoded formdata which can be passed throught to the server. Documents are requested using the GET method. The request method changed by prefixing the URL encoded formdata with either POST: or GET:

Using the GET method cgidata is restricted to 256 bytes.

name=Igor+Pool&country=New+Zealand

GET:name=Igor+Pool&country=New+Zealand

POST:name=Igor+Pool&country=New+Zealand

returnByHTTP

This function allow you to control downloads of specific files to the browser. Actual file location maybe outside of HTTP Server directory so not to be seen by the browser.

save-as-filename can be used to give the returning file a different name. Alternatively if filename references a REXX variable (prefix filename with 'VAR:') then the contents of the REXX variable is returned.

The correct HTTP header is created based on browser type and platform and has been tested on MSIE (Mac and Windows), Netscape 4.0+ (Windows and OS/2).

Function returns 0 if successful and 1 if not.

NTPDateTime

This function returns 4 words describing the local date time and UTC date time from a NIST server. The TZ environment variable in the config.sys is used to convert UTC date time to local date time.

Daylight savings time is NOT yet supported. This function requires access to a NIST server using port 13.

Optional format-specifier as per DateAdjust function.

If not successful function returns an empty string.

System date and time can be set using OS/2 DATE and TIME commands.

A list of worldwide NTP servers can be found at http://www.eecis.udel.edu/~mills/ntp/servers.htm

DateAdjust

Adjusts the date by the specified number of days using the Julian Calendar for days prior to 1582 and the Gregorian Calendar for dates after.

Default date format: dd-mm-yyyy can be change with a format-specifier. Current system date can be referenced by passing keyword 'TODAY' as date.

DateDifference

Returns the number of days (either positive or negative) between 2 dates. Both dates must be greater than 01-01-0000 and less than 31-12-3000. If either date is invalid or outside the allowable date range then an empty string is returned.

DateDifference uses the Julian Calendar for days prior to 1582 and the Gregorian Calendar for dates after.

Optional format-specifier as per DateAdjust function. Note: Both dates must be in the same format.

Current system date can be referenced by passing keyword 'TODAY' as basedate and/or date.

DateWeekday

Returns the full weekday for any given day from 01-01-0001 to 31-12-3000.

DateDifference uses the Julian Calendar for days prior to 1582 and the Gregorian Calendar for dates after.

Optional format-specifier as per DateAdjust function. Option can be used to specify the return weekday in LONG format (Monday), SHORT format (Mon), or as an index value INDEX with Monday = 1

Current system date can be referenced by passing keyword 'TODAY' as date.

DateVerify

Verifies a date is valid using the Julian Calendar for days prior to 1582 and the Gregorian Calendar for dates after.

Optional format-specifier as per DateAdjust function.

Function returns 0 if date supplied is valid and 1 if not.