Davin, these are good questions!
For the benefit of others who may be reading this thread, I have provided some background and expanded detail.
APLWeb services is designed to provide 'waiting and ready' server-side application system 'instances' of APL+Win functions to service the transaction requests of web clients. The number of, and resources associated with, each instance of a server-side application system is determined by the 'load balancing' needs of the organization providing the web service. Where necessary additional servers, essentially identical to the portal server can be deployed to handle larger numbers of web client requests using 'busyid' property of the APL WebServices workspace configuration section.
Generally web services applications provide for two modes of operation, that can apply to web client / web server interaction in which the web client is either a human responding to a browser-based GUI or a another web server.
State-less operation occurs when the web client makes a complete request in one transaction to the next available instance of the server-side application and that server side application instance responds back to the web client as part of the same transaction. Immediately after responding to the web client, that instance of the server-side application is available to service another web client.
Assuming it is permitted by the web service, state-ful operation occurs when the web clienlt makes a persistant connection to the next available instance of the server-side application and maintains that connection throughout a series of transactions between client and server. When the interaction is completed, the web client terminates the 1:1 connection and the server-side instance of the application is now available to service another web client. During the interval of 1:1 client / server interaction the server-side instance of the application is not available to serve any other web client. The maximum duration of the 1:1 state-ful operation may have a time out established by the server-side application.
When a web client needs to maintain a state-ful connection to a particular instance of APL+Win running behind APL WebServices, the 1:1 relationship must be established, by returning the 1:1 flag (=1) via a function call from the client to the server. This function, typically named "START_SINGLE_SESSION", will be in the virtual server path for the APL+Win application being supported by APL WebServices.
Interspersed between the start of a 1:1 connection and the end of a 1:1 connection, the web client can perform any transactions (effectively calling server-side APL+Win functions) supported by the particular web service and be assured that the data manipulations affected by the prior interspersed transaction will still be resident in the server-side APL+Win workspace.
Similarly when that 1:1 relationship is no longer required by that web client, it should be terminated byt the web client, by returning the 1:1 flag (=0) via an analogous function, typically named "END_SINGLE_SESSION', in the virtual server path for the APL+Win application being supported by APL WebServices.
The APL WebServices configuration file for doing this would include a section analogous to the following xml. The APL+Win functions "START_SINGLE_SESSION" and "END_SINGLE_SESSION" would exist in the server-side APL+Win workspace. The APL WebServices configuration file is easily maintained using the APL WebServices configuration GUI. The 'MESSAGE_TO_CLIENT" function result is merely a cosmetic element of the implementation.
<virtualpath name="/my_webapp_name/start_single_session">
<access />
<wsid>MyWsName</wsid>
<function>START_SINGLE_SESSION</function>
<result type="document">MESSAGE_TO_CLIENT</result>
<result type="one-to-one">SINGLE_SESSION_FLAG</result>
</virtualpath>
<virtualpath name="/my_webapp_name/end_single_session">
<access />
<wsid>MyWsName</wsid>
<function>END_SINGLE_SESSION</function>
<result type="document">MESSAGE_TO_CLIENT</result>
<result type="one-to-one">SINGLE_SESSION_FLAG</result>
</virtualpath>
Of course the virtual path names in the APL WebServices configuration need not be the same as the actual names of the APL+Win functions in the server-side APL+Win workspace, but it helps to keep them so to avoid confusion.
Now to the answers to your questions:
The APL+Win workspace does not maintain the 1:1 relationship. It knows nothing about web traffic. The APL+Win workspace is a 'slave' COM application instantiated by APL WebServices. Barring un-anticipated errors from within the application system functions in the APL+Win workspace, an instance of the APL+Win workspace, created as a COM client of APL WebServices, lives or dies under the control of the APL WebServices server which is a Microsoft .Net application.
The APL WebServices .Net application:
Instantiates the instance of the APL+Win workspace(s) as COM clients either when APL WebServices is started based on the programmer-created APL WebServices configuration file settings for number of instances or on demand by a request of a web client. Note that the intialization of instances of the APL+Win application at start-up of APL WebServices is one reason for the excellent performance of the APL WebServices / APL+Win ensemble. When a request arrives from a web client, APL+Win is already started-up and ready to go.
The APL WebServices .Net application instantiates each instance of APL+Win as an independent thread, because .Net is multi-threaded. The Windows operating system automatically allocates threads to multiple processors unless barred from doing so by the machine's administrator. This means that APL WebServices provides multi-threading and multi-processor support to APL+Win.
Thie .Net application converts the 1/0 return value from the APL+Win START_SINGLE_SESSION/END_SINGLE_SESSION functions value that can be received by the web client to indicate the start/end of the state-ful session.
The .Net application also keeps the state-ful session open until the server-side-controlled timeout occurs or the web client ends the 1:1 session.
There are three 'time-out's in the APL WebServices configuration file:
<server><connection-timeout>...
and
<workspace><timeout>...
and
<server>
<enable-content-expiration>...
<expire-content>...
The 1:1 relationship timeout is controlled by the <workspace><timeout>... tag in the APL WebServices configuration file, which is in units of milliseconds, but can be set to high values. For debugging purposes, I often set this value quite high, so that I can examine what is happening on the server-side APL+WIn. Note however, that implementing a web service application permitting state-ful operation which lasts more than a short while means that significant server-side resources are being tied up by the web client as they ponder the screen. In many cases it is possible to split the presentation to the web client of the GUI and the submission of the filled GUI into two web services transactions supported by different server-side APL+Win functions.
Assuming that the server-side APL+Win functions handling the transaction ensemble are properly configured to refresh global variables in the workspace whenever a new ensemble of transactions is processed, the only 'clean-up' necessary would be to have the web client call 'END_SINGLE_SESSION'.
The information necessary to maintain this 1:1 relationship between the web client and the particular instance of APL+Win running on the server is contained in a 'cookie'.
If by 'shut-down' you mean an un-anticipated error on the server side, then this is handled by having the web client listen for exceptions from the server in addition to expecting the anticipated results of the transaction call from the web client to the web server. Such exceptions on the server side may require transaction recovery methodology in the server-side APL+Win functions. For example, if the server-side APL+Win application is manipulating data in an SQL Server database, then those manipulations should be encapsulated into an SQL Server database 'transaction' so that partial manipulations are reversed and the SQL Server database data remains consistent.
A 'shut-down' caused by an anticipated error on the server side, e.g. validation of invalid web client input, should be handled by the anticipated return result of the transaction rather than by an exception thrown by the server-side application.
For server-to-server communication, the APL+Win 'Notifiy' method can be used to inform the server communicating with APL WebServices of exceptions. The []elx of the APL+Win application can be set to create/capture the appropriate error message and then transmit it as an exception to the other server and, if desired, shut-down the current instance of APL+Win. Syntactically: '#' []wi 'Notify' ('<aplresult><aplmethod>kill2aplcom</aplmethod><apldata>',x,'</apldata></aplresult>'), where x is any (string) data result to be sent back to the calling server.
What other 'program control over the situation' would you need or like to have?
Actually APL WebServices is not that mysterious. It is based upon the Microsoft IIS (Internet Information Services) model, which itself is based upon the multi-vendor-endorsed
www.w3.org standards for web services. The pre-existing APL+Win ActiveX/Com interface does the work on 'translating' between the data types of APL+Win and Win32 datatypes of COM. APL WebServices uses the .Net Framework to translate between the COM data types and the .Net datatypes and finally the
www.w3.org web services structures which are all string-based.