Arcom MERLIN (ROM-DOS/Sockets) User manual

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 1
MERLIN
Embedded Industrial
Internet Appliance
Library Technical Manual
Product Information
Full information about other Arcom products is available by contacting our Website at:
www.arcomcontrols.com
Useful Contact Information
Customer Support Europe Customer Support US
Tel: [phone]
Fax: [phone]
E-mail:suppor[email protected]
Tel: [phone]
Fax: [phone]
E-mail: [e-mail]
Sales offices Sales hotlines
United Kingdom:
Arcom Control Systems Ltd
Clifton Road
Cambridge CB1 7EA, UK
Tel: [phone]
Fax: [phone]
E-mail:
[email protected]
United States:
Arcom Control Systems Inc
13510 South Oak Street
Kansas City MO 64145 USA
Tel: [phone]
Fax: [phone]
E-mail:
[email protected]
Belgium:
Groen Nummer:
Tel: [phone]
Fax: [phone]
France:
Numero Vert
Tel: [phone]
Fax: [phone]
Germany:
Kostenlose Infoline:
Tel: [phone]
Fax:[phone]
Netherlands:
Gratis Nummer:
Tel: [phone]
Fax: [phone]
Italy:
Numero Verde:
Tel: [phone]
Fax: [phone]
Whilst Arcom’s sales team is always available to assist you in making your decision, the final
choice of boards or systems is solely and wholly the responsibility of the buyer. Arcom’s entire
liability in respect of the boards or systems is as set out in Arcom’s standard terms and
conditions of sale.
If you intend to write your own low level software, you can start with the source code on the
disk, which is supplied. This is example code only to illustrate use on Arcom’s products. It has
not been commercially tested. No warranty is made in respect of this code and Arcom shall
incur no liability whatsoever or howsoever arising from any use made of the code.
© 2000 Arcom Control Systems Ltd
All trademarks recognised.
Arcom Control Systems Ltd
operate a company-wide quality
management system which has
been certified by the British
Standards Institution (BSI) as
compliant with ISO9001:1994

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 2
Contents
Contents........................................................................................................................................2
Revision History............................................................................................................................3
Preface...........................................................................................................................................3
Software Library............................................................................................................................4
TSR (“Terminate and Stay Resident”) Support.............................................................................4
SSI (“Server Side Include”) Support.............................................................................................4
CGI (“Common Gateway Interface”) Support...............................................................................4
Data Types.....................................................................................................................................5
Logic............................................................................................................................................5
Include Files.................................................................................................................................5
TSR (“Terminate and Stay Resident”) Support...........................................................................6
Issues Pertaining to Stack Size....................................................................................................7
Coreleft() Function.......................................................................................................................8
SMALL Model Executable Example.............................................................................................9
Choice of wSPTop Parameter (when loading a TSR)...................................................................9
Choice of wSPTop Parameter (when registering CGI handler or SSI file) ..................................10
TSR Example.............................................................................................................................11
SSI (“Server Side Includes”) Support........................................................................................12
An Example SSI Implementation................................................................................................15
Dynamic SSI Variable Update....................................................................................................17
CGI (“Common Gateway Interface”) Support ...........................................................................18
Common Gateway Interface Demonstration Applications...........................................................28
Stack Overflow Example............................................................................................................29
Embedded LAN Connections.....................................................................................................30
TCP/IP Servers ............................................................................................................................30
FTP............................................................................................................................................30
HTTP.........................................................................................................................................30
NETBIOS/SMB Support...............................................................................................................30
Configuring the MERLIN to access a remote Windows 9x drive over Ethernet...........................30
NETBIOS / SMB Troubleshooter................................................................................................31
Connecting the MERLIN to a Modem.........................................................................................31
Configuring the MERLIN for Modem Operation..........................................................................31
Host Configuration.....................................................................................................................32
Connecting to an NT RAS server............................................................................................32
Connecting to a Windows 9x system......................................................................................33
Modem Connectivity Troubleshooter ......................................................................................35
Direct RS232 Cable Connection.................................................................................................35
MERLIN Configuration...............................................................................................................35
Host Configuration.....................................................................................................................36
Connection to a Windows NT system.....................................................................................36
Connecting from a Windows 9x system..................................................................................37
Direct Cable Connectivity Troubleshooter...............................................................................37
Glossary ......................................................................................................................................38

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 3
Revision History
Manual Date Comments
Issue A
Issue B
Issue C
080201
150301
260601
First release of manual
[ECO 2957] Embedded LAN Connections section added
[ECO 2985] Changes to sections discussing stack sizes
Preface
The Arcom MERLIN (ROM-DOS/Sockets) Development Kit enables you to build full Ethernet and
PSTN dial-up network support (modem required) into your target systems.
This includes:
• TCP/IP API with TCP, UDP and ICMP
• Support for BOOTP, DHCP, or static I.P. addressing
• FTP and HTTP servers and clients with extension API’s.
• CGI and SSI extensions to the HTTP server and API’s.
• NETBIOS, SMB support (drive redirection to Windows shares)
• SMTP and POP3 support for sending and receiving e-mails
This manual is in two parts. The first part details the MERLIN EIIA software library functions and
support. The second part explains how to make various network connections between the
MERLIN and other networks via the Ethernet or the COM3 serial port (directly to another PC or via
a modem).

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 4
Software Library
The MERLIN EIIA software library enhances and extends the Datalight Sockets TCP/IP stack.
The library is supplied as a set of binaries pre-built for use with the Borland C++ 4.52 compiler. A
number of examples are provided which demonstrate use of the library functionalities. If Borland
C++ 4.52 is required, a copy may be obtained from Arcom Control Systems.
At this time the library comprises the following components:
TSR (“Terminate and Stay Resident”) Support
Allows loading of a program in the background. The program code and data will remain in memory,
until unloaded. This facilitates use of ‘callbacks’ (see later)
SSI (“Server Side Include”) Support
Allows creation of HTML template files. These files may contain variables, defined using a certain
HTML tag. When a client requests the template file it is parsed and the variable is replaced with an
application definable string. This replacement string may be defined or redefined by the application
at any time.
This allows dynamic content to be generated simply and without the requirement to modify HTML
source files.
CGI (“Common Gateway Interface”) Support
Allows the execution of user application code when specified URL requests are received from
clients. Additionally supports the parsing of data received from these clients. Returned data may be
in the form of dynamic HTML or other depending on application requirements.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 5
Data Types
The .\include directory contains the ARTYPES.H include file. This include file defines a
number of Arcom standard data types
#define UCHAR unsigned char 8-bit
#define SCHAR signed char 8-bit
#define BYTE unsigned char 8-bit
#define UINT16 unsigned int 16-bit
#define SINT16 signed int 16-bit
#define WORD unsigned int 16-bit
#define UINT32 unsigned long 32-bit
#define SINT32 signed long 32-bit
#define ULONG unsigned long 32-bit
#define FLAG unsigned char 8-bit (1/0)
Logic
A number of logical definitions are also made here:
#define TRUE 1
#define FALSE 0
#define SUCCESS 0
#define ERR_HW -1
#define ERR_HTTPD -2
#define ERR_FILE -10
#define ERR_PARAM -20
#define ERR_UNKNOWN -2
#define ERR_NORXDAT -3
#define ERR_NOKEY ERR_NORXDAT
Include Files
The .\include directory contains the ARAPI.H include file. This include file declares the
publicised API to the Arcom E.I.I.A. library.
The demonstration board API may be found in the ARDEMO.H include file.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 6
TSR (“Terminate and Stay Resident”) Support
Allows loading of a program in the background. The program code and data will remain in
memory, until unloaded. This facilitates use of ‘callbacks’ (see later)
Function FLAG fArFindTSR( UCHAR *sID )
Description Check if a program corresponding to string sID is installed as a TSR
Parameters UCHAR *sID
If NULL then use this program’s ID
(i.e. the executable filename without the .EXE)
Returns TRUE - TSR found
FALSE- TSR not found
Notes None
Function FLAG fArLoadTSR( SINT16 wSPTop )
Description Install the currently loaded executable program as a TSR.
Parameters SINT16 wSPTop
Top of stack for any call-backs. If (wSPTop == 0) then the default
behaviour is to use the current stack pointer plus 50 bytes, which is
likely to result in approximately 64KBytes of memory being reserved
for the data, heap and stack of the TSR if the TSR was compiled
using the small memory model (with default heap and stack sizes).
For efficient memory allocation when loading TSR functions, set
wSPTop to equal the maximum estimated stack (+ heap + allocated
data) size required by the TSR (+ a small safety margin).
Returns This function DOES NOT RETURN if it works as the program has, by
definition, finished execution but remains in memory.
FALSE- TSR Error Installing TSR
Notes The program name (i.e. the filename without the .EXE extension) is
used as the TSR name. Any files open at the time the call is made
remain open.
For details on the correct use of wSPTOP see “Issues Pertaining to
Stack Size” at the end of this sub-section.
TSR code should be < 64Kb in size and should be compiled in
SMALL model ideally. The entire executable program remains within
memory. There is no concept of a transient loader component being
discarded

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 7
Function FLAG *fArUnloadTSR( UCHAR *sID )
Description Uninstall an installed TSR program
Parameters UCHAR *sID
If non-NULL then unload the TSR corresponding to the sID string
which is in memory. Alternatively unload the TSR in memory with a
name corresponding to the program name of this executable (i.e.
without the .EXE extension)
Returns TRUE - TSR Uninstalled
FALSE - Error Uninstalling TSR
Notes Anything registered within the TSR will not be unregistered
This is an extremely important point – if a TSR registers against a
URL then callbacks will be generated into that body of code. If the
TSR is unloaded from memory without unregistering from the URL
then callbacks will continue to be made into the original code area
which will, in all probability, cause a system failure. As such it is
recommended that the TSR unloading facility should be used only in
a development environment.
Issues Pertaining to Stack Size
DOS applications may be compiled and linked in a number of different “memory models”. A
memory model defines a set of pointer constraints for compiled code.
e.g.
An application compiled in TINY model must have a total size of less than 64Kb
(CODE size + DATA size + STACK size < 64Kb)
An application compiled in SMALL model must have a total code size of less than 64Kb. The size
of the data combined with the stack must be less than 64Kb also.
(CODE size < 64Kb, [DATA + STACK] < 64Kb)
There are similar constraints for the MEDIUM, COMPACT, LARGE and HUGE models. For further
details please refer to your compiler reference manual.
If we consider the memory map of an executable in isolation it appears something like the
following:

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 8
TOP OF AVAILABLE APPLICATION MEMORY (TOP OF STACK)
Top of stack
|
Bottom of stack
The stack expands downwards as the
running program makes calls to functions
and/or creates ‘local’ variables.
Function calls cause parameters and a
return address to be placed on the stack.
Local variables are also placed on the
stack.
The stack contracts as called functions
make returns, and as this causes local
variables to be discarded.
Free space
The stack expands into this free space
from above. The heap (also known as
the allocated data) expands into this free
space from below.
If we run out of free space then our stack
can become corrupt and/or our data can
become corrupt. This will usually cause
a system failure
Top of allocated data
|
Bottom of allocated data
The allocated data contains all global
application data. Additionally, if the
application dynamically allocates near
data blocks then the top of the allocated
data area can grow upward into the free
space.
As dynamically allocated data blocks are
freed the top of the allocated data area
may contract (although this is dependent
on issues of contiguity)
Top of program code
|
Bottom of program code
The program code occupies a given
amount of memory and this will not
change during the lifetime of any normal
DOS executable.
BOTTOM OF APPLICATION MEMORY
As can be seen from the above, if the stack extends down too far or the allocated data increases
too much then the stack and heap areas may overlap – causing corruption and a probable system
failure.
Coreleft() Function
There is a Borland C++ function available which returns the amount of space between the heap
and the stack during program execution. See the Borland documentation for details of coreleft()
and farcoreleft() functions.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 9
SMALL Model Executable Example
For a SMALL model executable we have one area for code (the code ‘segment’) and another area
for both the data and stack (data/stack segment). The maximum size of both of these segments is
64Kb.
When the executable is loaded into memory the top of the stack (TOS - which also corresponds to
the top of this application) is set to the top of the data/stack segement.
This gives us the maximum possible space of 64Kb for data and stack. Now ordinarily this would
be the best arrangement. However, when loading TSRs we must conserve as much memory as
possible. The standard TOS results in a minimum requirement of 64Kb TSR memory allocation
which could increase to a maximum of 128Kb with the code segment.
Our stack size (as a rule of thumb) will be 4Kb or 8Kb unless we require:
• Large local (stack) data structures
• Recursive functions
• Floating Point Arithmetic
In the above cases the required stack size can be expected to increase.
Choice of wSPTop Parameter (when loading a TSR)
The above discussion illustrates that it is useful to be able to restrict the size of the stack, which
has the effect of reducing the memory requirement for a TSR.
Once a TSR has been installed using fArLoadTSR() code in that TSR will only be executed as a
result of a “callback” from either the TCP/IP stack or the HTTP server.
The HTTP server uses it’s own internal stack. When it generates a callback to a user supplied
function (see later) it switches the stack to that of the user supplied function. This new stack will be
the stack in use when the function was registered (e.g. that of the executable which was shortly to
become a TSR, or the user program that was running when the CGI handler was registered). At
the end of the callback the stack is reset to that of the HTTP server.
Given that for most TSR’s we do not require the full 64Kb segment for data and stack (in small
model) we can reduce the value of the top of the stack, which is the top of the available application
memory, when the callback is made.
If for example, a program (which has a compiled size of say 8KBytes) is loaded using
fArLoadTSR() and wSPTop is set to 0, the TSR will take up 8KBytes of memory for the program
code and allocated data PLUS approximately 64KBytes (less the program’s allocated data size) for
the heap and stack. For fArLoadTSR(), the wSPTop parameter directly specifies where the top of
the stack should begin (in bytes above the end of the program code). Thus if we know that the
stack, heap and allocated data will always take up less than 10KBytes, we could set wSPTop to
10*1024.
Our stack is now ‘lower down’ and so we have less free space. It is critical to ensure that the
stack will not grow down into the allocated data space at any time.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 10
A suggested methodology is to first use either the TDUMP program or your application .MAP file to
see how much application data your program uses.
For details on TDUMP or mapfiles see the relevant compiler reference manual.
If you use dynamic memory allocation in your application – this is not recommended for TSRs –
then you should calculate how this will increase your data area usage (heap usage). Remember to
take into account data fragmentation.
Finally, select a value of wSPTop:
wSPTop = (Total Data Usage)
+ (Worst case estimated stack usage)
+ (Safety margin)
If you find that your TSR application is exhibiting strange behaviours try increasing the size of
wSPTop.
Choice of wSPTop Parameter (when registering CGI handler or SSI file)
The wSPTop parameter in the wArSSIAddFile() and wArCGIRegister() functions is handled slightly
differently from the fArLoadTSR() function discussed above. When a TSR is loaded, it has its own
stack, used only by the TSR. However, a CGI handler for example, will use the same memory
segment for its stack as the user program that executed the wArCGIRegister() function uses for its
stack. This size of the user program stack will be dynamic and its maximum size cannot always be
exactly determined, only estimated.
The point in memory that the CGI handler will use as the top of its stack is determined at the
moment that it is registered, not at the time of a callback. Thus at the moment a handler is
registered, an estimate must be made regarding the maximum size that the user program stack
might reach before a callback is made. If wSPTop is set to 0, the default top of the handler stack is
set to 1000 bytes below the current user program stack pointer.
This 1000 byte safety margin will work in most circumstances unless the user program has large
local variable arrays or recursive functions. If a much smaller safety margin was used, there is a
danger that the callback stack will be placed over existing user program stack variables, causing
corruption of the user program’s local variables and/or other stack data. If a much larger safety
margin was used, there might be a danger of the callback stack reaching down into the user
program’s allocated memory area and corrupting that data (e.g. global variables).
To increase the safety margin to 2000 bytes, for example, wSPTop should be set to “_SP - 2000”
(where _SP is the current stack pointer). Alternatively, if it is easier to estimate the maximum size
required of the CGI handler stack (+ the user program allocated data and heap size), then wSPTop
could be set directly to that total value (+ a safety margin). Obviously the safety margin used here
must be small enough to ensure that the callback stack still begins below the stack of the user
program.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 11
TSR Example
The .\library\examples\chktsr directory contains a Borland C++ 4.52 project which can be used to
build the TSR example application.
The project builds a number of executables. These are the same source code but built in the small,
medium, compact, large and huge models. It is suggested that all user TSRs are developed in
small model.
See CHKTSR.C for the main example code. Also see ARAPI.H, or this documentation, for details
on the library APIs available.
If the CHKTSRx.EXE application is run from the command line it will terminate and the code/data
will stay resident in memory. This can be verified by running the DOS ‘MEM’ command with the ‘/C’
option.
If the CHKTSRx.EXE is run again it will fail as there is already a TSR of the same name in
memory.
If the CHKTSRx.EXE is run with the ‘/u’ argument the TSR which was originally loaded into
memory will now be unloaded. This can be verified using the ‘MEM’ command.
NOTE: Due to the fact that any registered resources are not deregistered when the TSR is
unloaded it is suggested that this facility is used only during development

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 12
SSI (“Server Side Includes”) Support
Allows creation of HTML template files. These files may contain variables, defined using a certain
HTML tag. When a client requests the template file it is parsed and the variable is replaced with an
application definable string. This replacement string may be defined or redefined by the application
at any time.
This allows dynamic content to be generated simply and without the requirement to modify HTML
source files.
Function SINT16 wArSSIAddFile( UCHAR *pszSSIFilePath,
SINT16 (far *wfpCallback)( void )
SINT16 wSPTop )
Description Registers an HTML template file for the SSI adapter to parse
Parameters UCHAR *pszSSIFilePath
Filepath to register e.g. if the parameter points to a string “ssidemo”
then a client browser should request ‘http://w.x.y.z/ssidemo’ where w,
x, y, z form the I.P. address of the E.I.I.A. system.
SINT16 (far *wfpCallback)( void )
If this parameter is non-NULL then the specified function will be
called whenever a new connection is received for the registered file-
path. This allows updating of any SSI variables before the HTML
template file is parsed.
If this parameter is NULL then no callback is made upon receipt of a
new client connection to the registered filepath
SINT16wSPTop
Top of stack for callback entry. For details see Terminate and Stay
Resident Support – Issues Pertaining to Stack Size.
If this parameter is 0 then the default behaviour of the SSI adapter is
to set the top of stack to the current top of stack minus 1000 bytes at
callback time.
Returns 0 - Success
< 0 - Error condition
Notes Only the last call to one of wArSSIAddFile() or wArCGIRegister() will
affect the top of stack. Prior call settings will be discarded.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 13
Function SINT16 wArSSIAddVar( UCHAR *pszName,
UCHAR *pszValue )
Description Adds an SSI variable for HTML template parsing. When the HTML
template is requested any occurrences of the variable (pszName) will
be replaced with the string corresponding to (pszValue).
Parameters UCHAR *pszName
Pointer to parameter string (e.g. “PARAM1”)
UCHAR *pszValue
Pointer to new value string (e.g. “VALUE1”)
Returns 0 - Success
<0 - Error
Notes The HTML template may or may not contain one or more SSI
parameters. All of the registered SSI parameters will be replaced with
the associated value string.
The tag format for an SSI variable in an HTML template file is:
<!--#echo var=PARAM-->
The replacement value string may be an arbitrarily complex HTML
string e.g.
<img src=\"image.gif\">
This would result in a specific image being linked into the HTML
document on the client. The application can then modify the value
string to point to a different image (say) depending on real-world I/O
or other constraints.
See the CHKSSI example for further details

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 14
Function SINT16 wArSSIUpdateVar( UCHAR *pszName,
UCHAR *pszValue )
Description Updates an SSI variable for HTML template parsing – replaces the
existing value string with the new pszValue string. When the HTML
template is requested any occurrences of the variable (pszName) will
be replaced with the string corresponding to (pszValue).
Parameters UCHAR *pszName
Pointer to parameter string (e.g. “PARAM1”)
UCHAR *pszValue
Pointer to value string (e.g. “VALUE1”)
Returns 0 - Success
<0 - Error
Notes The HTML template may or may not contain one or more SSI
parameters. All of the registered SSI parameters will be replaced with
the associated value string.
The tag format for an SSI variable in an HTML template file is:
<!--#echo var=PARAM-->
The replacement value string may be an arbitrarily complex HTML
string e.g.
<img src=\"image.gif\">
This would result in a specific image being linked into the HTML
document on the client. The application can then modify the value
string to point to a different image (say) depending on real-world I/O
or other constraints.
See the CHKSSI example for further details.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 15
Function const UCHAR *psArSSIReadVar(UCHAR *pszName)
Description Returns a pointer to the value string associated with a given
parameter string.
Parameters UCHAR *pszName
SSI variable name
Returns NULL - Error or NULL value
!= NULL - Pointer to value string
Notes The value string should not be modified directly.
Use wArSSIUpdateVar() instead.
Function void vArSSIShutdown(void)
Description Shuts down SSI adaptor: unhooks HTTP server
Parameters None
Returns Nothing
Notes This must be called before the application is unloaded from memory
An Example SSI Implementation
Server side includes are about the simplest way to insert dynamic content into HTML files which
are then served to one or more clients.
The application developer decides upon a number of variables which may, for example, describe
the state of various system components.
e.g. We might decide to use four variables to describe the state of four LEDs.
Each of these variables must be given a name – the “Parameter string”
e,g, LED1, LED2, LED3, LED4
A minimal HTML template file must now be generated, using any text editor.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 16
The simplest case would be something like the following:
<HTML>
<BODY>
LED1 = <!--#echo var=”LED1”-->
</BODY>
</HTML>
Note the very specific tag containing the LED1 parameter. This is the standard SSI variable
replacement format.
Having created the HTML template and stored this on the server, the next step is to “register” this
template file with the SSI adaptor.
An example program is given in the .\examples\chkssi directory. The part of the code which
registers the HTML file is:
if(wArSSIAddFile("ssitest1.sht", wArUpdateVars,
SP_TOP) < 0)
{
printf("Error: Adding SSI file: %s\n",
"ssitest1.sht");
return(-1);
}
NOTE :The HTTP server (HTTPD) must be resident for this registration to succeed
Now, whenever a client requests a URL of the form http://w.x.y.z/ssitest1.sht the SSI adaptor will
parse the ssitest1.sht file on the filesystem and replace any registered variables before transmitting
the file to the client.
The application developer must ensure that the variables are also registered:
if(wArSSIAddVar(“LED1”,”ON”) < 0)
{
printf("Error: Adding SSI variable: %s\n",
“LED1”);
return(-1);
}
With both the HTML template file and the appropriate variables registered a request for the
http://w.x.y.z/ssitest1.sht file will result in the following being sent to the client:
<HTML>
<BODY>
LED1 = ON
</BODY>
</HTML>

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 17
Dynamic SSI Variable Update
Looking back at the wArSSIAddFile() code snippet we see that there is a function referenced,
wArUpdateVars(). This function will be called whenever a client connects to the HTTP server and
requests the registered file. The application developer may choose to implement this function to
update all SSI variables before the HTML template file is parsed. Alternatively a NULL may be
passed here in which case no callback is made.
NOTE: For details on the correct choice of the SP_TOP parameter see:
TSR (“Terminate and Stay Resident”) Support -> Choice of wSPTop Parameter

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 18
CGI (“Common Gateway Interface”) Support
Allows the execution of user application code when specified URL requests are received from
clients. Additionally supports the parsing of data received from these clients. Returned data may be
in the form of dynamic HTML or other depending on application requirements.
Function SINT16 wArCGIRegister( UCHAR *pszFilePath,
CGI_HANDLERS far *pCgi,
SINT16 wSPTop )
Description Registers a partial URL path to the CGI adapter
Parameters UCHAR *pszFilePath
URL portion to register with HTTP server
e.g. “cgidemo”. A client would then query http://w.x.y.z/cgidemo
CGI_HANDLERS far *pCgi
Pointer to a CGI_HANDLERS structure. This structure defines all
possible user callbacks during a client connection. See the
CGI_HANDLERS structure below for details.
SINT16 wSPTop
Top of stack for callback entry. For details see Terminate and Stay
Resident Support – Issues Pertaining to Stack Size.
If this parameter is 0 then the default behaviour of the CGI adapter is
to set the top of stack to the current top of stack minus 1000 bytes at
callback time.
Returns 0 - Success
< 0 - Error condition
Notes Only the last call to one of wArSSIAddFile() or wArCGIRegister() will
affect the top of stack. Prior call settings will be discarded

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 19
Function SINT16 wArCGIUnregister(UCHAR far *pszFilePath)
Description Deregisters a partial URL path from the CGI adapter
Parameters UCHAR *pszFilePath
URL portion to unregister from HTTP server
Returns 0 - Success
< 0 - Error condition
Notes This must be called before the application exits or is unloaded from
memory. Otherwise a system failure will result
Function SINT16 wArCGITxData( SINT16 wHandle ,
UCHAR far *pData,
SINT16 wCount)
Description This function may be used to transmit data to the client
(< 2^16 -1 bytes)
Parameters SINT16 wHandle
Connection handle for Tx/Rx to client
UCHAR far *pData
Pointer to a byte array of data to transmit
SINT16 wCount
Number of bytes to transmit
Returns > 0 - Number of bytes actually transmitted
< 0 - Error
Notes It is possible, even likely, that the number of bytes transmitted in a
given call to this function will be less than the total number of bytes to
transmit. In this even the caller function should return and await
another callback at which time a call to wArCGITxData() should be
made again to transmit the rest of the data.

CONTROL SYSTEMS
J640 2192-10850-000-000
Page 20
Function SINT16 wArCGIRxData( SINT16 wHandle ,
UCHAR far *pData,
SINT16wSize)
Description This function may be used to receive data from the client
(< 2^16 -1 bytes) e.g. sent via a POST function
Parameters SINT16 wHandle
Connection handle for Tx/Rx from client
UCHAR far *pData
Pointer to a byte array of data to hold received data
SINT16 wCount
Size of buffer
Returns > 0 - Number of bytes actually received
< 0 - Error
Notes It is possible, even likely, that the number of bytes received in a given
call to this function will be less than the total number of bytes
expected from the client. In this even the caller function should
return and await another callback at which time a call to
wArCGIRxData() should be made again to receive more data.