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

Version 1.0 © May 2009 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. The startup.cmd file is automatically executed 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 and close any OS/2 windows which can called these scripts. Delete all copies of the DLL and reboot the machine. Any rexx scripts which use the functions contained in the REXXWEB DLL will cease to function until it is reloaded.

Applying Updates

Exit all rexx scripts or applications which call the rexxweb functions. Close any OS/2 windows which had called these scripts. 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 WriteToFile function.

If option is specified and set to OS2ENVIRONMENT then the following rexx variables are created and populated:

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.

validation can be used to specify if the field is Mandatory or should be Validated. The value containted in label is used to word the error messages which is stored in the REXX variable message.

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.

exclude can hold the value 'CR' to exclude the carriage return from being converted to the HTML paragraph <P> tag.

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	Option	Result
T	-	Text. May contain ASCII codes 32 and above, TAB, CR, LF
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	D	Domestic Phone using format (area_code) number. May contain () 0-9 SPACE
P	I	International Phone using format +country_code area_code number. May contain 0-9 + SPACE
D	I	International Date using format dd-mm-yyyy. May contain 0-9 -
D	A	American Date using format mm-dd-yyyy. May contain 0-9 -
D	S	Sorted Date using format yyymmdd. May contain 0-9

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 or if option SHOW is included then the placeholders are left.

You can also specifiy an alternative variable marker from the default # (hash) by setting marker to a single character.

If prefix is present then only placeholders starting with prefix will be populated.

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.

getFile

Returns the contents of a file in rexxvar. The file is loaded as is and no variable subsitution occurs.

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

filename must include the full path to a 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.

CopyFile

Copies sourcefilename to destinationfilename returning 0 if successful and 1 if not.

File creation date and attributes copied. Extended Attributes not copied.
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.

DeleteDirectory

Deletes directory including any files and subdirectories contained within directoryname.

If option is set to FORCE then any files/directories set as Read-Only are deleted.

Long file names supported under HPFS.

CreateDirectory

Creates directoryname including any parent directories which do not exist. Function returns 0 if successful and 1 if not.

Long file names supported under HPFS.

CopyDirectory

Copies the contents of the sourcedirectory including any child directories to the destinationdirectory. Function returns 0 if successful and appripriate DOS error code of 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.

StemSearch

Scans the rexx stem variable haystack. counting each instance of needle.

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

The optional returnstem. can specify the name of a stem variable the matching results are returned in. results can be used to specify to return either the matching DATA or the INDEX of data in stem.

Returns the number of matched found or -1 if an error occured.

needle is 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.

CharCount

Counts and returns occurences of search-char in the rexx variable rexxvar. If no occurences found or rexxvar or search-char are invalid then 0 is returned.

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.

BuildHTMLCSSGraph

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.

Cascading style sheet options can be used to control the font elements of the graph. Entries for the following classes should exist in your style sheet (.css file).

• graph-title
• graph-x-data
• graph-y-data
• graph-x-label

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).
• groupsize: Number of bars data items to be grouped under a single heading. (Default = 1).

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 | to seprate parts

Where:

• label: Bar Label
• value: Value of bar
• colour: Bar colour
• url: Provides optional URL link to bar. 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.

E-mail recipients can receive either a carbon copy (CC) or blind carbon copy (BCC) by prefixing their email address with a 'CC:' or 'BCC:' (excluding quotes). This option is only available when a rexx stem variable is used.

recipient.0 = 5
recipient.1 = 'igor@igor.co.nz'
recipient.2 = 'to:dave@igor.co.nz'
recipient.3 = 'cc:lisa@igor.co.nz'
recipient.4 = 'cc:roger@igor.co.nz'
recipient.5 = 'bcc:matt@igor.co.nz'

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.

If the message tracking parameter is set to NOTIFYONREAD then mail servers that support this function such as Microsoft Exchange Server will send a reply when the client has read the e-mail - if this functionality is available.

Outside of the above parameters the default charset can be changed by populating the REXX variable SENDSMTP_CHARSET with the desired charset string. The default value for this is "us_ascii".

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

RebootPC

This function effects a clean shutdown then performs a warm/soft reboot of the machine.

It uses an undocumented/unsupported call to DOS.SYS to accomplish this, althought the call is now widely used by a number of OS/2 applications.

CallRexx

Use this function to call another rexx file (rexxfile) and pass a set of parameters. The called rexx file can return a value in returnvar.

Up to 250 parameters can be passed. returnvar is used to specify the rexx variable in which any results are returned. There is a 2GB limit on the size of the returned data.

The function itself returns 0 if completed OK, 1 if the file specified in rexxfile could not be found or 2 if an error occured.

DateAdjust

Adjusts the base 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. Instead of specifying the number of days to adjust you can also use keywords STARTOFMONTH, ENDOFMONTH and LASTBUSINESSDAY to adjust the base date to.

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.

DateWithinRange

Returns the 0 if the query-date is within the date range specified by start-date, end-date otherwise 1 is returned. If any date is invalid an empty string is returned.

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

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

Current system date can be referenced by passing keyword 'TODAY' as any of the 3 date parameters.

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.

D2T

Returns the string representation of an integer time value. option can be used to specify either a standard 12 hour clock (default) or a 24 hour clock.

T2D

Returns the decimal representation of a time value. Valid formats for time include hh:mm:ss, hh:mm AM/PM or hh:mm (24 hour format).

D2M

Returns the string representation of a integer month value. option can be used to specify the returning month be LONG format (January) or SHORT format (Jan).

M2D

Returns the integer value representing the specified month-string. month-string can be either in LONG format (January) or SHORT format (Jan).

gmtTimeStamp

Returns a string containing a full time stamp formatted in GMT. Options for the timestamp inlude the current vdate time, RESET to use 01-Jan 1970 or NOW to use the current timestamp.

timezone can be specified as offset hh:mm:ss with a minimum of offset hh. If TZ is specifed the the value returned by the environment variable TZ will be used.

Adjust can specify the number seconds the time stamp is to be adjusted - useful for calculating expiry times for sessions or cookies.

httpCookie

Returns the string containing a http cookie.

DISCLAIMER REXXWEB is provided "AS IS" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. In no event shall the author be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if the author advises or has been advised of the possibility of such damages. USE AT YOUR OWN RISK!!