Download (ftp://ftp.itk.ru/pub/sm)

1. Brief description.

State Machine (further is SM) was developed to overcome the main, in our opinion, obstacle arising with the development of complex web-applications, namely the absence of a user context available all the time (at least for the period of a session). As a result:

• it is impossible to create a program in a form of a usual (for programmers and users) tree of calls of "procedure call - return" (or, from user's point of view, for example, "dialog window appearence - return");
• or it's necessary that the execution context should be "handed over" from a form to another and so on; all this is awful when being realized and results in disturbance of secrecy and integrity of the application;
• it's necessary to save the execution context in some format in server (e.g. in database) and to restore it during the next all.

Actually, SM realizes the last variant, but does it in a way which is"clear" to the application. In other words, cgi application sees no control SM directives. It's seen from its name, that SM is intended for controlling states of the application. State implies a set of cgi process environment vaiables, which is associated with its name (by run) and arguments. SM is located between web-server and cgi program, and it directs server stream and environment variable to the program and filtrates output stream of cgi program (only for Content-type: text/html). In case of detecting directive variables (forSM), SM executes certain actions on controlling states (saving and subsequent recovery, generation of new states, and return to parent ones), and also replace a part of URL in output stream, modifying them for further use. Thus, SM forms a tree of states, which, in fact, create an integral application of separate cgi programs.

Now, SM has been realized in a form of two programs - smconn and sm. Web server always calls smconn and gives it the rest of the path.

For example, application input point can be in the form:

http://localhost/cgi-bin/mail/smconn/init,

and "inside" the application it will something like:

http://localhost/cgi-bin/mail/smconn/state&41234123

In its turn, smconn is connected via Unix-domain-socket, "at the other end" of which sm proper is "located". In case of a call detected, sm runs sepatate thread for serving this call, and then necessary cgi program is started in sm.

Thus, at least two processes are started for processing of each call: smconn and cgi program proper. Although smconn is quite small and practically doesn't consumes system resourses, its run can be avoided, if module to web-server, performing its functions, is used.

As it's seen, the given scheme isn't quite simple, and the question arises: why couldn't SM function be realized directly in module of web- server? Unfortunately, in it's impossible. In its semantics, a SINGLE sm must process ALL calls to a specific application. Standard web-servers - for example, apache - create a set of copies of themselves to optimize processing calls, and, though this process can be controled within some limits, there's no full control.

The first version of SM was based on of knon protocol - FastCGI, but it turned out, that "reproduction" of server processes "reproducts" executors, which is inadmissible. Besides, FastCGI realization (free), that we have, has proved to be rather complex and unstable...

All control directives recognized by SM are described in a form of HTML tags, or rather in a form of HTML-comments. This, to some extent, makes SM extension easier - unrecognized directives will not litter user interface.
Also, when describing directives, parts enclosed in square brackets [ ] are not obligatory.

call	statename	global	bind	print
fcall	local	form	expire	quit
scall	private	img	clearquery
return	public	limg	option

2.1. Call directive call.

When used out of forms, call tag is replaced for <a href=state&34234234>, new (empty) space being created, i.e. some blank of state, containing only cgi-program name and its arguments.

For example, if in input stream there's:
<!#fcall program="help.sh main_context">Help</a>
then user will have something like
<a href="state&4234234&call">Help</a>

and, with the activation of this reference,SM activates corresponding state as a child state in relation to current one and will run help.sh program c with the argument of main_context command line. It should be noted that standard semantics of cgi-calls doesn't allow to transfer command line arguments, and this is quite inconvenient sometimes.

Return attribute defines the name of environment variable in which the result will put (see <!#return>).

If prefix attribute is, its value is added before href value. Sometimes this is necessary for manual control of states - to replace, for example, a current (relative to webserver) directory, or to change acess or recoding rights.

When used in forms, <!#call ...>directive is replaced for <input type=submit ...> or, if src attrbute has been transferred, for <input type=image ...>, url_srcattribute is source URL of image.

For example,
<!#form>
...
<!#call program="forward.sh" value="forward" size=20>
...
</form>

call directive will be replaced for
<input type=hidden name=_C_1 value="_N_1">
<input type=submit name="_N_1" value="forward" size="20">

or, with use of src:
attribute <!#form>
...
<!#call program="forward.sh" value="forward" size=20 src="forward.gif">
...
</form>
call directive will be replaced for
<input type=hidden name=_C_1 value="_N_1">
<input type=image name="_N_1" value="forward" size="20" src="/images/imail/forward.gif">

src attribute <input type=image ...>tag takes the valie of imagedir attribute of SM cinfiguration file plus плюс the value of src attribute of <!#call ...> control directive.

imagedir directive of SMconfiguration file (sm.cfg) in this example takes /images/imailvalue. See also <!#form> and directives of SMconfiguration file (sm.cfg) imagedir

2.2. scalldirective.

Directive is used in JavaScriptprograms to create states.
Foe example:
<script language="JavaScript">
...
window.open(, ...); ...
</script>
in output stream will be:
<script language="JavaScript">
...
window.open("state&121212&scall", ...); ...
</script>,
where 121212 is sttae number.

2.3. returnreturn.

return in input stream is replaced for a reference returning to parent state; for example, if the parent state has number 1234, then <!#return>back</a>
will be replaced for
<a href="state&1234&return">back </a>.

return attribute sets the value returned in parent state. This value will be assigned to environment variable indicated in calldirective.
For example,
main.sh ...
<!#call program="file.sh" return="asdf">
...
file.sh:
...
<!#return return="0">
...
asdf environment value, after executing cgii program - file.sh, will be assigned with 0value. If statenameattribute has been set, then the retun is performed to the state having "state_name" name (see <!#statename>).

If hrefattribute is set, its value is added (after # ) to resulting URL (i.e. as a reference inside a page). queryvalue is added to resulting URL after "?". prefix is used in the same may as in <! #call ...>. With the return to any state, all child states are destroyed automatically.

2.4. State name setting statename

Any newly created state is automatiacally assigned with a unique name. statenamedirective allows the state to be assigned with some_namename.
Later, this name can be used to return to the state from child states.
For example,
mine.sh
...
<!#statename "my_state">
...
<!#call program="file.sh">

file.sh
...
<!#return statename="my_state">
...
(см. <!#return>).

2.5. Creating variables.

Program executed underSM can determine for itself (and for child states) environment variables and assign variables to them. Variables can have localvisibility scope - public, private and global, and they are created by control directive in the form of :

<!#local   name1=value1 ... nameN=valueN>
<!#private name1=value1 ... nameN=valueN>
<!#public  name1=value1 ... nameN=valueN>
<!#global  name1=value1 ... nameN=valueN>

local variables belong only to the state in which they have been created.

private variables belong to the state in which they have been created, but are transferred to child states. A child state can change privatevariable of a partent, as private will create a new variable shadowing a parent variable.

public variables are inherited by child states. Thus, if the child state assigns a value to public variable, then publicparent variable changes as well.

global are publicvariables belongning to the highest (root) state. If several variables have one and the same name, the priory is given to local, then to private and to public.

Remark: environment variables common to the whole application may be можно determined by envar directive of SMconfiguration file sm.cfg.

2.6. Creation of forms form

<!#form ... > understands the same attributes as <form>standard tag does.
For example, if in input stream there is:
<!#form target="asdf">...</form>,
then user receives something like
<form action=state&12345&form target="asdf">,
where 12345 is current state number. In form, to create submit buttons, calldirective may be used. In this case, control will be given to cgi-program set by programattribute of <!#call ...> directive. But use of standard tags isn't prohibited:

<input type=submit ...> и <input type=image ...>.
In the last case, controll will be given into the same form.

2.7. Creating images.

Directives understand attributes which are standard for <img>tag. In output stream we have:
<img src="dir_for_image/url_src">
or
<img src="dir_for_image/kod_language/url_src"> for <!#limg ...> directive.
url_src - URL of image.
dir_for_image is set by sm.cfg imagedirconfiguration fale directive
kod_language is a two-letter abraviation of language used by browser to display of page contents. This language is set by browser preferences.

2.8. Directive bind.