The ESLWEB library provides an ESL Application the ability to Send and Receive data with a Web Server using standard internet protocols.
function HTTPGet (string : URL_SV,
boolean : Debug_BV,
boolean : StripTags_BV,
boolean : URLDecode_BV)
returns string
library "eslweb"
function HTTPPost (string : URL_SV,
string : EncodedFormData_SV,
boolean : Debug_BV,
boolean : StripTags_BV,
boolean : URLDecode_BV)
returns string
library "eslweb"
function HTTPPostWithHdr (string : URL_SV,
string : HTMLHeader_SV,
string : EncodedFormData_SV,
boolean : Debug_BV,
boolean : StripTags_BV,
boolean : URLDecode_BV)
returns string
library "eslweb"
The main input to the HTTPGet and Post functions is a URL string:
Host Address (e.g. "http://www.ESLSyndetic.com/Test_file_for_HTTPGet.htm")
Protocols:
The first section of the URL string must contain the protocol. Currently only the standard HTTP and HTTPS (Secure Socket Layer) protocols are support. Any other protocol will result in an error message in the error log and a null string being returned.
Other Parameters:
The URLDecode boolean, enables the output string to be decoded, using the URLDecode function detailed below without having to make an additional call to the URLDecode function from within the ESL code.
The StripTags boolean, enables the output strings to be filtered, removing all HTML tags.
Note that if the output string is encoded, then the URLDecode must be set to true, to enable the Strip Tags facility to work.
The Debug boolean will enable debugging of the conversation to be written to the errorlog.
The HTTPPost function, allows the ESL application to behave as an HTML Form by using the POST verb. The form data, is passed in the second agrument "EncodedFormData_SV", in the format name=value[&name2=value2]...
Each value passed in the Form Data must be encoded using the URLEncode function before being added to the Form Data string. (Do not Encode the Form Data string as a whole, otherwise the control symbols = and & will be lost!)
As the HTML header can vary, depending on the type of data being posted, the function "HTTPPostWithHdr" allows the ESL application to pass the required header data.
The output from all these functions is an ESL string containing the content of the returned "Web Page" or other data types transferred from the Web Server. As an ESL string is able to hold binary data, it is possible to handle any file type, for example, JPEG and GIF images.
The following two functions can be used to enhance the use of the functions above.
To improve the transport of data to and from the web server, we have included a MIME format called "x-www-form-urlencoded". The functions enable the ESL application to Encode and Decode the data.
function URLEncode (string : URL_SV)
returns string
library "eslweb"
function URLDecode (string : URL_SV)
returns string
library "eslweb"
The HTTPGet and the two functions above are demonstrated in example application: HTTPDemo.EAL. There is also a demonstration of transfering binary data in the WEBPICS.EAL application.
Although the ESL feature can transfer binary data directly, the introduction of XML messages used by the Simple Object Application Protocol (SOAP) has resulted in the need to convert binary data into a text string. The following two routines convert binary files into a Hex string and back:
function FileToHexString (string : FileName_SV)
returns string
library "eslweb"
subroutine HexStringToFile(string : FileName_SV,
string : HexString_SV)
library "eslweb"
The "FileToHexString" function can simply be embedded within a copy or append statement, that is being used to create the message to be passed to the Web Server, for example:
append
" <FIELD>\n"
" <NAME>IMAGE</NAME>\n"
" <TYPE>HEX</TYPE>\n"
" <VALUE>\n"
" " FileToHexString(File_LSV)"\n"
" </VALUE>\n"
" </FIELD>\n"
to XLM_SV
If there is an error when using "FileToHexString", for example the file does not exist, then a message will be recorded in the errorlog and a null string will be returned by the function.
To perform the reverse operation, the Hex string needs to be extracted from the message sent by the Web Server, this can be performed using the extract statement.
Once the Hex string has been extracted into a separate string variable, it can be written to a file using the "HexStringToFile" subroutine. For example:
extract from XLM_SV
skip by "<NAME>IMAGE</NAME>"
skip by "<VALUE>"
skip to word
take to "\n" Hex_SV
call HexStringToFile(File_LSV,
Hex_SV)
It is the developer responsibility to ensure the string passed only contains pairs of valid hex characters (i.e. 0 - 9 and A - F or a - f). Passing any other characters will stop the creation of the file.
As "HexStringToFile" is defined as an external subroutine, the application can use the built-in function "errorlevel" to check for errors. If there are no errors the "errorlevel" will be set to FTP_E_OK (i.e. zero). If the routine is unable to open the file to write the Hex string, the value will be FTP_E_CANTWRITE. If any character in the hex string is not a valid hex character, then the errorlevel will be set to FTP_E_BADHEX.
Note. These integer constants are defined in the ESLWEB include file.
In addition to the routine used with the HTTP protocol, ESL also provides the "File Transfer Protocol" commonly known as FTP. With release 12.10, there are 2 new routines that supersede the older FTPFile function, which is still supported, however; we would encourage to use either FTP_Get or FTP_Put as as they provide additional functionality:
subroutine FTP_Get (string : FTP_URL_SV,
string : FTP_RemoteFile_SV,
string : FTP_LocalFile_SV,
string : FTP_Userid_SV,
string : FTP_Password_SV,
boolean: FTP_OverWrite_BV,
boolean: FTP_Passive_BV)
library "eslweb"
subroutine FTP_Put (string : FTP_URL_SV,
string : FTP_LocalFile_SV,
string : FTP_RemoteFile_SV,
string : FTP_Userid_SV,
string : FTP_Password_SV,
boolean: FTP_OverWrite_BV,
boolean: FTP_Passive_BV)
library "eslweb"
The older FTPFile function allows files to be transferred between the local computer and another remote computer that supports FTP.
function FTPFile (string : FTP_SV,
integer: FTP_Action,
string : FTP_RemoteFile_SV,
string : FTP_LocalFile_SV,
string : FTP_Userid_SV,
string : FTP_Password_SV)
returns integer
library "eslweb"
The parameter passed to these routines and function are:
FTP_SV/FTP_URL_SV The URL of the Remote Computer
FTP_Action One of the following integer constants:
FTPGet - Upload a local file to the remote computer
FTPGetWithOverwrite - As FTPGet, but overwrite any existing file
FTPPut - Download a file from the remote computer
FTPPutWithOverwrite - As FTPPut, but overwrite any existing local file
FTP_RemoteFile_SV The filename, include path, of the file on the remote computer
FTP_LocalFile_SV The filename, include path if necessary, of the file on the local computer
FTP_Userid_SV The User Id, if not using anonymous login
FTP_Password_SV The password for the User Id, if not using anonymous login.
FTP_Overwrite_BV Set this to true, if any existing file is to be overwritten.
FTP_Passive_BV When set to true, the passive FTP mode is used.
By supporting the passive FTP mode, the routines FTP_Get and FTP_Put are able to transfer files through a Firewall, without the need to allow an exception for the Esl runtime, which could present a security issue. Whilst, the passive mode is more compatible with the Firewall, this mode has to be supported by the FTP Server.
The FTP_Get and FTP_Put sets the built-in "errorlevel", whilst the older "FTPFile" function returns an integer. All 3 facilities return FTP_E_ERRORFREE (i.e. zero) if the specified action has been successful. If there has been an error, the returned value will be non-zero. Please review the ESLWEB include file from a list of possible error values.
The use of the "FTP_Get" and "FTP_Put" routines are demonstrated in the application FTPDemo.
With release 12.10 we have introduced a function "Get_GUID" that returns a Globally Unique Identifier, which is needed within SOAP messages, when communicating with certain Web-Services.
As a number of Clients now use the facilities provided by the ESLWeb library, we now supply a complete set of documentation that includes a tutorial on Web-Services.
Please do let us have any feed-back regarding the functionality.
