APL Wiki|
Size: 4676
Comment:
|
Size: 3224
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 9: | Line 9: |
| {{{ServiceState}}} is a class that offers an interface between the Windows SCM (Service Control Manager) and a Dyalog APL application running as a service. | {{{ServiceState}}} is a namespace script that offers an interface between the Windows SCM (Service Control Manager) and a Dyalog APL application running as a service. |
| Line 11: | Line 11: |
| In you application workspace you need to have a function on `⎕LX` like this: | In you application workspace you need to have a function on `⎕LX` similar to this: |
| Line 14: | Line 14: |
| Start [1] #.WinFile.PolishCurrentDir [2] rideFlag←0 [3] timeout←3 [4] #.myServiceState←⎕NEW #.ServiceState rideFlag timeout [5] '#'⎕WS'Event' #.myServiceState.Event_QuitDQ 1 [6] :If myServiceState.IsRunningAsService [7] {}myServiceState.EstablishServiceCallback ⍬ ⍝ This does not work! [8] {#.TestService.Run ⍵}&⍬ [9] ⎕DQ'.' [10] #.TestService.Off [11] :Else [12] #.TestService.Run ⍬ [13] :EndIf |
Start;ps [1] ps←#.ServiceState.CreateParmSpace [2] ps.ride←1 [3] #.ServiceState.Init ps [4] :If #.ServiceState.IsRunningAsService [5] {#.TestService.Run ⍵}&⍬ [6] ⎕DQ'.' [7] #.TestService.Off [8] :Else [9] #.TestService.Run ⍬ [10] :EndIf |
| Line 30: | Line 27: |
| Note that this example focuses just on getting the application running as a service. | Note that this example focuses on getting the application running as a service. For the purpose of demonstrating how to overwrite defaults (no RIDE) it shows how to create a parameter space with default settings (line [1]) and then overwrite a setting (line [2]). If you are happy with the defaults (which you can check by executing `#.ServiceState.CreateParmSpace.∆List`) then you can specify `⍬` as the right argument of `#.ServiceState.Init` in line [3]. |
| Line 34: | Line 33: |
| '''[1]''': This makes sure that if the workspace carries a path the work (or current) directory is set accordingly. | '''[4]''': Checks whether the application is actually running as a Windows Service. This allows to execute the application in its own thread in case its running as a service but not otherwise - that makes debugging the application significantly easier. |
| Line 36: | Line 35: |
| '''[2]''': Flags that indicates whether the service is expected to connect to Ride or not. | '''[5]''': Here we start the real application. Note that this '''must''' run in its own thread because otherwise the application might well become unresponsive. |
| Line 38: | Line 37: |
| '''[3]''': Timeout: this defines how long the `ServiceState` class will wait for the application to conform a requested state change. | '''[6]''': We need to execute `⎕DQ '.'` in order to make sure that the interpreter processes all events. |
| Line 40: | Line 39: |
| '''[4]''': This instantiates the `ServiceState` class. '''[5]''': `#.myServiceState.Event_QuitDQ` is a variable carrying an (any) integer. The application is supposed to send the same integer to `#` (when it wants to stop) in order to quit the `⎕DQ` on line 9. '''[6]''': Checks whether the application is actually running as a Windows Service. '''[7]''': This establishes `#.ServiceState.EstablishServiceCallback` as a callback that will handle all messages send by the Windows SCM. Well, it should. At the time of writing an instance methods that is associated with an event cause a NONCE ERROR, so we must circumvent thus Dyalog bug for the time being with something like this: {{{ '.'⎕WS'Event' 'ServiceNotification' '#.OnServiceHandler' }}} The `#.OnServiceHandler` function in turn calls the instance method: {{{ OnServiceHandler←{ #.myServiceState.OnServiceHandler ⍵ } }}} That works. '''[8]''': Here we start the real application. Note that this '''must''' run in its own thread because otherwise the application might well become unresponsive. '''[9]''': We need to execute `⎕DQ '.'` in order to make sure that the interpreter processes all events. '''[10]''': At this stage we need to execute `⎕OFF`; that's what `#.TestService.Off` is doing. |
'''[7]''': At this stage we need to execute `⎕OFF`; that's what `#.TestService.Off` is doing. |
| Line 70: | Line 43: |
| The application must make sure that it checks whether a state change was requested. This can be done by calling certain helpers as shown in this example: | The application must make sure in its main loop that it checks for state changes, and act accordingly. This is all done by the Operator `#.ServiceState.CheckServiceMessages` which takes the name of a logging function as operand: |
| Line 73: | Line 46: |
| MainLoop dummmy;buffer;data;event;obj;rc;r;msg;cs [1] Log 'Server got started' [2] :While 1 [3] ⎕DL 1 [4] :If #.myServiceState.ShallServicePause [5] {}#.myServiceState.ConfirmStateChange ⍬ [6] Log'The service is pausing' [7] {}#.myServiceState.WaitForContinue ⍬ [9] {}#.myServiceState.ConfirmStateChange ⍬ [10] Log'The service is no longer pausing' [11] :EndIf [12] :If #.myServiceState.ShallServiceQuit [13] {}#.myServiceState.ConfirmStateChange ⍬ [14] Log'The service is in the process of shutting down...' [15] :Leave [16] :EndIf [17] :EndWhile [18] ⎕NQ'#'#.ServiceState.Events.QuitDQ |
MainLoop dummmy;buffer;data;event;obj;rc;r;msg;cs [1] :Repeat [2] ⎕DL 1 ⍝ What is reasonable here depends on the application [3] :If (Log #.ServiceState.CheckServiceMessages)#.ServiceState.IsRunningAsService [4] Log'The service is in the process of shutting down...' [5] :Leave [6] :EndIf [7] :Until 0 |
| Line 95: | Line 58: |
| '''[14]''': This makes sure that the `⎕DQ` in `Start[7]` quits. Apart from `ShallServicePause` and `ShallServiceQuit` there is also a function `ShallServiceContinue` but this is called by this function: {{{ {r}←WaitForContinue dummy [1] ⍝ Returns always ⍬. [2] ⍝ Consider calling this in case ShallServicePause has returned a 1 and you don't _ [3] ⍝ have to do any particular gymnastics but just want to wait for a state change. [4] ⍝ It just waits until the status changes, although not necessarily to "continue". [5] r←⍬ [6] :While 0=ShallServiceContinue [7] ⎕DL 1 [8] :EndWhile }}} |
Line '''[3]''' checks for any changes signalled from the Service Control Manager (SCM). If a "Pause" is detected, then the function loops until either a "Continue" or a "Stop" is detected. The explicit result is 1 in case a "Stop" is detected and 0 otherwise. |
ServiceState: interface between SCM and APL
Contents
ServiceState is part of the CategoryAplTree project.
Overview
ServiceState is a namespace script that offers an interface between the Windows SCM (Service Control Manager) and a Dyalog APL application running as a service.
In you application workspace you need to have a function on ⎕LX similar to this:
Start;ps
[1] ps←#.ServiceState.CreateParmSpace
[2] ps.ride←1
[3] #.ServiceState.Init ps
[4] :If #.ServiceState.IsRunningAsService
[5] {#.TestService.Run ⍵}&⍬
[6] ⎕DQ'.'
[7] #.TestService.Off
[8] :Else
[9] #.TestService.Run ⍬
[10] :EndIfNote that this example focuses on getting the application running as a service. For the purpose of demonstrating how to overwrite defaults (no RIDE) it shows how to create a parameter space with default settings (line [1]) and then overwrite a setting (line [2]).
If you are happy with the defaults (which you can check by executing #.ServiceState.CreateParmSpace.∆List) then you can specify ⍬ as the right argument of #.ServiceState.Init in line [3].
Remarks:
[4]: Checks whether the application is actually running as a Windows Service. This allows to execute the application in its own thread in case its running as a service but not otherwise - that makes debugging the application significantly easier.
[5]: Here we start the real application. Note that this must run in its own thread because otherwise the application might well become unresponsive.
[6]: We need to execute ⎕DQ '.' in order to make sure that the interpreter processes all events.
[7]: At this stage we need to execute ⎕OFF; that's what #.TestService.Off is doing.
The application
The application must make sure in its main loop that it checks for state changes, and act accordingly. This is all done by the Operator #.ServiceState.CheckServiceMessages which takes the name of a logging function as operand:
MainLoop dummmy;buffer;data;event;obj;rc;r;msg;cs [1] :Repeat [2] ⎕DL 1 ⍝ What is reasonable here depends on the application [3] :If (Log #.ServiceState.CheckServiceMessages)#.ServiceState.IsRunningAsService [4] Log'The service is in the process of shutting down...' [5] :Leave [6] :EndIf [7] :Until 0
Remarks:
Line [3] checks for any changes signalled from the Service Control Manager (SCM). If a "Pause" is detected, then the function loops until either a "Continue" or a "Stop" is detected. The explicit result is 1 in case a "Stop" is detected and 0 otherwise.
Project Page
For bug reports, future enhancements and a full version history see ServiceState/ProjectPage
Version Information
Original author: |
|
Responsible: |
|
Email: |