• ServiceState

ServiceState

(Show (Hide table-of-contents) table-of-contents)

ServiceState is part of the CategoryAplTree project.

Overview

ServiceState is a namespace 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 like this:

      Start
[1]   #.WinFile.PolishCurrentDir
[2]   {}#.ServiceState.Init 1 3
[3]   '#'⎕WS'Event'#.ServiceState.Events.QuitDQ 
[4]  :If #.ServiceState.IsRunningAsService
[5]       {}#.ServiceState.EstablishServiceCallback ⍬
[6]       {#.TestService.Run ⍵}&⍬
[7]       ⎕DQ'.'
[8]      #.TestService.Off
[9]  :Else
[10]     #.TestService.Run ⍬
[11] :EndIf

Note that this example focuses just on getting the application running as a service.

Remarks:

[1]: This makes sure that if the workspace carries a path the work (or current) directory is set accordingly.

[2]: This initializes the ServiceState interface. There are two arguments:

1. is a boolean that indicates whether the service shall connect to Ride (1) or not (0).

2. is a positive integer specifying the number of seconds until ServiceState gives up waiting for the application to confirm a state change requested by the SCM (timeout).

Note that the two values are considered as constants; they are therefore established as niladic functions. For example, after having executed line [2] of the aforementioned Start function you can say:

      #.ServiceState.States.ride
1
      #.ServiceState.States.timeout
3

[3]: #.ServiceState.Events.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 7.

[4]: Checks whether the application is actually running as a Windows Service.

[5]: This establishes #.ServiceState.EstablishServiceCallback as a callback that will handle all messages send by the Windows SCM.

[6]: Here we start the real application. Note that this must run in its own thread because otherwise the application might well become unresponsive.

[7]: We need to execute ⎕DQ '.' in order to make sure that the interpreter processes all events.

[8]: At this stage we need to execute ⎕OFF; that's what #.TestService.Off is doing.

The application

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:

      MainLoop dummmy;buffer;data;event;obj;rc;r;msg;cs
[1]  Log INI.CONFIG.appshortname,' server started'
[2]  :While 1
[3]      ⎕DL 1
[4]      :If #.ServiceState.ShallServicePause
[5]          Log'The service is pausing'
[6]          {}#.ServiceState.WaitForContinue ⍬
[7]          Log'The service is resuming'
[8]      :EndIf
[9]      :If #.ServiceState.ShallServiceQuit
[10]         Log'The service is in the process of shutting down...'
[11]         :Leave
[12]     :EndIf
[13] :EndWhile
[14]  ⎕NQ'#'#.ServiceState.Events.QuitDQ

Remarks:

[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

Project Page

For bug reports, future enhancements and a full version history see ServiceState/ProjectPage

Version Information

CategoryAplTree CategoryAPLTreeProject