Generated from ./backend.tcl with ROBODoc v4.0.18 on Mon Aug 18 22:39:20 2008

schtonk/backend.tcl

NAME

    backend.tcl - persistent workhorse doing actual processing work

DESCRIPTION

    This module backend.tcl is the backend processor that takes
    pre-formatted user query and produces back a html that g.html
    in turn will supply to browser. 

backend.tcl/db_username

NAME

    db_username - db connection username. 

DESCRIPTION

    value of this variable is the username that schtonk will try to
    use when connecting to database. 

backend.tcl/::default_dateformat

NAME

    ::default_dateformat - string schtonk uses to format dates to strings

DESCRIPTION

    "%d-%m-%Y %H:%M:%S" by default

backend.tcl/Schtonk_Server

NAME

    Schtonk_Server - starts listening to specified port

FUNCTION

    procedure that sets up to listen at port, when incoming
    connection, causes a call procedure SchtonkAccept

INPUTS

    port    - is integer specifying the port where to listen

RESULT

    this procedure does not return

SEE ALSO

    backend.tcl/SchtonkAccept

backend.tcl/SchtonkAccept

NAME

    SchtonkAccept - conditionally calls "accept" for a socket

FUNCTION

    this procedure accepts (or rejects, based on addr)
    incoming connection and sets up a file-event that
    causes call to procedure Schtonk when socket becames
    readable. procedure Schtonk will then read the query
    from sock and start processing

INPUTS

    sock    - tcl socket identifier of incoming connection
    addr    - addr where connection is coming from
    prot    - tcp protocol from-port of the connection, we're
              always listening in port given to procedure
              Schtonk_Server

RESULT

    procedure returns no thing

SEE ALSO

    backend.tcl/Schtonk_Server backend.tcl/Schtonk

backend.tcl/Schtonk

NAME

    Schtonk - read request and start processing

FUNCTION

       This procedure is called when the server
       can read data from the client. This reads one line
       that is prepared in g.tcl, does some checks on database
       availability and calls method server_of_the_client
       that then does more work. This procedure is starting 
       point of request processing and is called by tcl
       due to file-event that is set up in procedure SchtonkAccept

INPUTS

       sock - The socket connection to the client

RESULT

       this does not return anything but this,as a side-effect
       causes the response of the query (or possible error message) to
       be written to sock. some error situations are here communicated
       to sock, in normal execution flow where no errors occur, 
       the resulting html will be written to sock by procedure
       server_of_the_client

SEE ALSO

    backend.tcl/SchtonkAccept backend.tcl/server_of_the_client

backend.tcl/server_of_the_client

NAME

    server_of_the_client - parse request and serve the result

FUNCTION

     this procedure server_of_the_client is called from proc 
     Schtonk when a line has been successfully read. this
     rather lengthy procedure calls various formatters or
     in most common case fetches the page from database, feeds
     it to tcl-evaluator,wiki-formatter, merges the css and 
     topmenu and writes the result back.

INPUTS

       client_expletion - contains the line that client sent. 
                          it is rather important to understand that
                          this line contains a tcl list that is supposed
                          to have following items in this order:
                           one letter command with meanings 
                             g - give page content
                             e - produce page containg editor for page
                             h - produce history listing if given page
                             s - save page from form given out with command "e"
                             d - print differences page of versions
                             a - attach a file, file content will read from sock
                             r - print out list of attachments so user can select one to be deleted
                             q - produce form asking for file to be attached  
                             b - send a binary attachment, like "g" but for attached files
                             f - delete attachment, result of "r"
                            pageid is an integer possibly followed by a 
                                   a string param in parentheses that is
                                   considered "page_param" later. The integer
                                   is reference to tables.sql/pages column
                                   named id.
                            lang   is language code, a 2-letter "fi" or "en"
                            version is version of page (specified by pageid) 
                                    that user wants.
                            contentlen if user posted a form, this
                                       contains length of the posted data
                            content_encoding contains encoding format of
                                             posted form. in practice it is
                                             application/x-www-form-urlencoded
                                             or multipart/form-data
                            remote_user is username as identified by
                                        httpd 
                          this line described above is produced by 
                          g.tcl and sent to sock as the very first
                          thing. it may be followed by posted form data
       sock - is the sock where to send the response back. 

RESULT

       this does not return anything but this,as a side-effect
       causes the response of the query (or possible error message) to
       be written to sock. 

SEE ALSO

    backend.tcl/Schtonk

backend.tcl/format_topmenu

NAME

    format_topmenu - returns topmenu contents

FUNCTION

    this takes topmenu content from global variable ::topmenu_content
    and replaces localizable strings inside the content

USED BY

     this is called from backend.tcl/server_of_the_client

INPUTS

       pageid - is number of the page being served
       lang   - is 2-characters long language code like "fi" or "en" 
                specifying the language

RESULT

       returns topmenu content. that is a html snippet. 

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/list_attachments_for_page

NAME

    list_attachments_for_page - queries db if there's any attachments for given pageid

FUNCTION

    proc that produces (possibly empty) listing of attachements
    for given page 

USED BY

     this is called from backend.tcl/server_of_the_client

INPUTS

       pageid     - is number of the page being served
       lang       - is 2-characters long language code like "fi" or "en" 
                    specifying the language
       page_param - part of pageid originally enclosed in parentheses after the
                    the integer-part of pageid 

RESULT

       returns list of attachments as html sniippet that backend.tcl/server_of_the_client
       will append at the end of the page being served. 

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/print_change

NAME

    print_change - proc that prints diff of 2 versions of a document

FUNCTION

    fetches 2 versions of a page from db and calls diff routine that 
    produces a diff in manner of tkdiff but only a lot uglier. 

USED BY

     this is called from backend.tcl/print_diff_page 

INPUTS

      pageid    - is pageid
      lang      - is lang
      leftside  - is version number of left side of compare
      rightside - is version number of left side of compare

RESULT

      a html snippet showing the differences

SEE ALSO

    backend.tcl/print_diff_page diff.tcl/diff2html

backend.tcl/print_diff_page

NAME

    print_diff_page - proc that takes page versions from posted 
                      form contents and calls backend.tcl/print_change

FUNCTION

    fetches page contents from db based on posted fields contents
    and calls a procedure that produces actual diff.

USED BY

     this is called from backend.tcl/server_of_the_client

INPUTS

     sock     - is the socket where to write back the response
     pageid   - is page of the page being diffed
     lang     - is language code

RESULT

     returns no thing but writes a whole html document to sock

SEE ALSO

    backend.tcl/print_change backend.tcl/server_of_the_client

backend.tcl/print_history_page

NAME

    print_history_page - procedure that produces a history listing html

FUNCTION

    fetches versions and dates from db and lists them in html format

USED BY

     this is called from backend.tcl/server_of_the_client

INPUTS

     sock       - is the socket where to write back the response
     pageid     - is page of the page being diffed
     lang       - is language code
     page_param - is page param extracted from original pageid

RESULT

     returns no thing but writes a whole html document to sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/print_attachment_query_page

NAME

    print_attachment_query_page - writes html that ask user to attach file

FUNCTION

    this procedure writes to sock a html document that offers user
    a form to select a file to be attached to given pageid. 

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name q.tcl

INPUTS

     sock       - is the socket where to write back the response
     pageid     - is page of the page being diffed
     lang       - is language code
     page_param - is page param extracted from original pageid

RESULT

     returns no thing but writes a whole html document to sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/print_attachment_removal_page

NAME

    print_attachment_removal_page - writes html that ask user to detach file

FUNCTION

    this lists attachments for a page, for each attachments it gives
    an URL that refers to g.tcl with name r.tcl and gives attachment
    id as pageid for f.tcl so when g.tcl is called with name f.tcl and
    having pageid of selected attachement, will finally g.tcl call
    server_of_the_client so that command is "f" "forget attachment" and 
    "pageid" is id of the attachment and so attachment will go away.  

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name r.tcl

INPUTS

     sock       - is the socket where to write back the response
     pageid     - is page of the page being diffed
     lang       - is language code
     page_param - is page param extracted from original pageid

RESULT

     returns no thing but writes a whole html document to sock

SEE ALSO

    backend.tcl/server_of_the_client backend.tcl/do_remove_attachment

backend.tcl/do_remove_attachment

NAME

    do_remove_attachment - deletes attachment from db

FUNCTION

    proc that does remove an attachment. returns number of the page
    where attachement was removed from. produces no thing in sock. 
    server_of_the_client will take the returned page and produce
    a "normal" rendition of the page where attachment was removed from

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name f.tcl

INPUTS

     sock       - is the socket where to write back the response
     pageid     - is page of the page being diffed
     lang       - is language code
     page_param - is page param extracted from original pageid

RESULT

     returns pageid of the page where the attachment did belong to

SEE ALSO

    backend.tcl/server_of_the_client backend.tcl/do_remove_attachment

backend.tcl/save_da_page

NAME

    save_da_page - saves a page to db

FUNCTION

   proc that reads a page and saves it to db. page is read from
   sock where it is available as posted form content. 
   normally produces no thing in sock. server_of_the_client
   will fetch the page contents and render it so user can
   see his foolishnes immeidately

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name s.tcl

INPUTS

     sock        - is the socket where to write back the response
     pageid      - is page of the page being diffed
     lang        - is language code
     remote_user - is userid as recognized by httpd 
     page_param  - is page param extracted from original pageid

RESULT

     returns no thing, produces no thing in sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/save_da_attachment

NAME

    save_da_attachment - saves an attachment to db

FUNCTION

    procedure that reads an attachment from global variable ::posted_fields
    and saves the content to db. before this is called the proceduer
    server_of_the_client must have called procedure
    encode_posted_content_into_variables or
    encode_multipart_content_into_variables so that there is something
    in variable ::posted_fields

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name a.tcl

INPUTS

     sock        - is the socket where to write back the response
     pageid      - is page of the page being diffed
     lang        - is language code
     remote_user - is userid as recognized by httpd 
     page_param  - is page param extracted from original pageid

RESULT

     returns no thing, produces no thing in sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/beam_an_attachment

NAME

    beam_an_attachment - procedure that sends attachment content to sock

FUNCTION

    this method queries attachment content from db and sends them
    to socket

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with name b.tcl

INPUTS

     sock        - is the socket where to write back the response
     pageid      - is actually id for database table attachments
                   specifying the attachment to send
     lang        - is page param extracted from original pageid

RESULT

     returns no thing, writes attachment to sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/encode_multipart_content_into_variables

NAME

    encode_multipart_content_into_variables - procedure for converting multipart/form data-encoded posted content into nice array of variables/values

FUNCTION

   proc that reads form posted as multipart/form data and 
   makes array out of that

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with content length bigger than zero.

INPUTS

     sock                    - is the socket where to write back the response
     posted_content_len      - length of posted content. this procedure will
                               try to read this many bytes from sock in 
                               order to acquire its inputs.

RESULT

     returns no thing, writes no thing to sock

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/::posted_fields

NAME

    ::posted_fields - array of posted fields

DESCRIPTION

   when user posts a form this array will contain field names and values

backend.tcl/html_encode

NAME

    html_encode - html character encoding conversion procedure

FUNCTION

    proc that decodes html encoding of posted form e.g. 
    "huijuutti+%26+%2B" -> "huijuutti & +"

USED BY

     this is called from backend.tcl/encode_posted_content_into_variables

INPUTS

     posted_val     - is html-encoded text 

RESULT

     posted_val formatted to unicode as tcl processes text

SEE ALSO

    backend.tcl/encode_posted_content_into_variables

backend.tcl/encode_posted_content_into_variables

NAME

    encode_posted_content_into_variables - procedure for converting application/x-www-form-urlencoded posted content into nice array of variables/values

FUNCTION

   proc that reads form posted as application/x-www-form-urlencoded data and 
   makes array out of that

USED BY

     this is called from backend.tcl/server_of_the_client when g.tcl is 
     called with content length bigger than zero.

INPUTS

     sock                    - is the socket where to write back the response
     posted_content_len      - length of posted content. this procedure will
                               try to read this many bytes from sock in 
                               order to acquire its inputs.

RESULT

     returns no thing, writes no thing to sock. as a side effect this
     will populate backend.tcl/::posted_fields.

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/somewhatmoinmoinsyntax

NAME

    somewhatmoinmoinsyntax - moinmoin wiki -> html formatter

FUNCTION

 procedure that converts wiki syntax to html. 

  MediaWiki syntax      Meaning                         Notes

  ''x''                 Italics
  '''x'''               Bold
  '''''x'''''           VeryStrong
  <sup>x</sup>          Superscript text
  <sub>x</sub>          Subscript text
  <small>x</small>      Small text
  <u>x</u>              Underline
  <tt>x</tt>            Preformatted embedded text
  <i>x</i>              Italics
  <b>x</b>              Bold
  &x;                   HTML entities
  <br>                  Breaking paragraphs

  ----                  Divider

  http://x              External Link
  [http://x]            External Link                   [5]
  [http://x y]          External Link with text

  [[x]]                 Link                            [1]
  [[x|y]]               Link with text                  [1]
  [[#Anchor]]           Setting an anchor in a page

  ==x==                 Header level 1
  ===x===               Header level 2
  ...
  * x                   Bullet list level 1
  ** x                  Bullet list level 2
  ...
  # x                   Numbered list level 1
  ## x                  Numbered list level 2
  ...
  *#*                   Mixed lists
  : x                   Indented paragraph level 1
  :: x                  Indented paragraph level 2
  ...
  ;x:y                  Definition level 1
  ;;x:y                 Definition level 2              [2]
  ...
  <pre>x</pre>          Preformatted uninterpreted text
  <nowiki>x</nowiki>    Uninterpreted text              [3]

  <!-- x -->            Comments                        [4]

  in addition from http://doc.jspwiki.org/2.4/wiki/WikiFormsExampleText
  lets steal FormOpen/Select/TextArea/Close so we don't need to 
  invent our own syntax
 
  in addition moinmoin understands ||cell 1||cell2||cell 3||
  that is utterly useful
 
  sucky as it is, this implements a subset of moinmoin and some extra
  and has about 2^9 bugs

USED BY

     this is called from backend.tcl/server_of_the_client almost always

INPUTS

     in       - is text in moinmoin syntax
     lang     - is language code, used when doing links to other wiki pages
     pageid   - is pageid integer of current page

RESULT

     returns contents of "in" but as html. 

SEE ALSO

    backend.tcl/server_of_the_client

backend.tcl/form_textarea_substituter

NAME

    form_textarea_substituter - digs textarea content from ::posted_fields and produces field

FUNCTION

    helper procedure called from somewhatmoinmoinsyntax that
    returns formatted <textarea> tag for form to use ; 
    reason for external proc is that we need to dig out
    possible textarea content somehow by conditioning on 
    textarea name

USED BY

     backend.tcl/somewhatmoinmoinsyntax

INPUTS

     areaname      - name of textarea in form
     rows          - textarea size in rows
     cols          - textarea size in columns

RESULT

     textarea-html snippet to be embedded into html form

SEE ALSO

    backend.tcl/somewhatmoinmoinsyntax

backend.tcl/form_textfield_substituter

NAME

    form_textfield_substituter - digs textfield content from ::posted_fields and produces field

FUNCTION

    helper procedure called from somewhatmoinmoinsyntax that
    returns formatted <textfield> tag for form to use ; 
    reason for external proc is that we need to dig out
    possible textarea content somehow by conditioning on 
    textarea name

USED BY

     backend.tcl/somewhatmoinmoinsyntax

INPUTS

     areaname      - name of textfield in form
     cols          - textfield size in columns

RESULT

     input type="text" -kind of snippet to be embedded into html form

SEE ALSO

    backend.tcl/somewhatmoinmoinsyntax backend.tcl/form_textarea_substituter

backend.tcl/form_selectfield_substituter

NAME

    form_selectfield_substituter - produces selector html snippet for form with content

FUNCTION

    same as form_text_area_substituter but will return a select
    list, thus invoked also from different kind of text input
 
    in fieldname, list of values
    out: 
    <SELECT NAME="Expl"><OPTION SELECTED>Blue#<OPTION>Red</SELECT>

    values is a list separated by semicolon, one may be prefixed with * to mark
    it as pre-selected

USED BY

     backend.tcl/somewhatmoinmoinsyntax

INPUTS

     fieldname      - name of selector item in form
     values         - selector values separated with semicolon

RESULT

    select-kind of html snippet to be embedded into html form

SEE ALSO

    backend.tcl/somewhatmoinmoinsyntax backend.tcl/form_textarea_substituter

backend.tcl/table_substituter

NAME

    table_substituter - formats one row of table

FUNCTION

    helper procedure called from somewhatmoinmoin that will
    take row content in form of a||b||c in and return
    <TR><TD>a</TD><TD>b</TD><TD>c</TD><TR>
    to format one line of a table

    limitations: bell \b is not an allowed character inside 
    a table

USED BY

     backend.tcl/somewhatmoinmoinsyntax

INPUTS

     tablerow_content - contents of the row. must have form || a || b ... ||

RESULT

    html snippet that belongs inside <table> tags

SEE ALSO

    backend.tcl/somewhatmoinmoinsyntax

backend.tcl/safe_mysqlsel

NAME

    safe_mysqlsel - procedure called from embed interp for performing db select

FUNCTION

    as our safe interperter in backend.tcl/tcl_evaluator has no access to
    database, lets have here a aliased procedure that it may call and it
    in turn does a database select and returns the stuff

USED BY

    backend.tcl/tcl_evaluator

INPUTS

    i    - not used for any purpose
    args - string containing valid select statement

RESULT

    select results as tcl array

SEE ALSO

    backend.tcl/tcl_evaluator

backend.tcl/safe_mysqlexec

NAME

    safe_mysqlexec - procedure called from embed interp for performing db update/insert/drop database

FUNCTION

    as our safe interperter in backend.tcl/tcl_evaluator has no access to
    database, lets have here a aliased procedure that it may call and it
    in turn does a database stuff other than select

USED BY

    backend.tcl/tcl_evaluator

INPUTS

    i    - not used for any purpose
    args - string containing valid "drop database and format root fs" statement

RESULT

    error code

SEE ALSO

    backend.tcl/tcl_evaluator

backend.tcl/safe_mysqlescape

NAME

    safe_mysqlescape - procedure called from embed interp for performing mysql string escape

FUNCTION

    as our safe interperter in backend.tcl/tcl_evaluator has no access to
    database, lets have here a aliased procedure that it may call and it
    in turn does a database string escape

USED BY

    backend.tcl/tcl_evaluator

INPUTS

    i    - not used for any purpose
    args - string to be escaped

RESULT

    strings from args but escaped

SEE ALSO

    backend.tcl/tcl_evaluator

backend.tcl/tcl_evaluator

NAME

    tcl_evaluator - procedure that evaluates embedded tcl in pages

FUNCTION

 proc that goes through content, finding tcl snippets and
 evaluating those ; replaces the code snippets in $content
 with the things that the tcl pieces return

USED BY

    backend.tcl/server_of_the_client

INPUTS

    content     - page content containing 0 or more TCL snippets 
                  marked with strings SCHTONK_TCL_CODE_BEGIN and
                  SCHTONK_TCL_CODE_END ; those strings will be
                  removed from $content and replaced with text
                  returned by tcl interpreter when code between
                  those markings is fed to interpreter. interpreter
                  may very well return empty. 
    pageid      - pageid integer from page request
    lang        - lang of current request
    remote_user - user as identified by httpd 
    page_param  - possible page param supplied after pageid integer in 
                  parentheses. 

RESULT

    content but with TCL removed and evaluated and string replaced

SEE ALSO

    backend.tcl/safe_mysqlsel backend.tcl/server_of_the_client

backend.tcl/add_klingon_translation

NAME

    add_klingon_translation - procedure for klingonization

FUNCTION

    produces klingon output from suitable input. 

USED BY

    backend.tcl/fill_string_arrays

INPUTS

    string

RESULT

    string

SEE ALSO

   backend.tcl/str_trans

backend.tcl/fill_string_arrays

NAME

    fill_string_arrays - one-time proc called at start for filling localized string arrays

FUNCTION

    performs single select for all localizable strings ; lets keep the strings
    in memory for better performance. 

USED BY

    backend.tcl

INPUTS

    none

RESULT

    none, but has a side effect of filling ::trans_tab_en, ::trans_tab_fi etc.

SEE ALSO

   backend.tcl/str_trans backend.tcl/add_klingon_translation

backend.tcl/str_trans

NAME

    str_trans - procedure for localizable string lookup table lookup

FUNCTION

    tries to find a localizable string from arrays filled in procedure
    backend.tcl/fill_string_arrays. this is called frequently from many 
    procedures inside schtonk

USED BY

    backend.tcl

INPUTS

    str  - name of string
    lang - selected language 

RESULT

    string in $lang

SEE ALSO

   backend.tcl/fill_string_arrays

backend.tcl/fetch_css_from_db

NAME

    fetch_css_from_db - proc called once at start for fetching css

FUNCTION

    for performance reason lets try to keep css in memory ; this procedure
    fetches it into global variable $::css_content

USED BY

    backend.tcl

INPUTS

    none

RESULT

    none but fills backend.tcl/::css_content

SEE ALSO

   backend.tcl/fill_string_arrays

backend.tcl/::css_content

NAME

    ::css_content - global variable for holding css content

DESCRIPTION

    used by about every procedure that needs to format whole html document in schtonk

backend.tcl/fetch_top_menu_from_db

NAME

    fetch_top_menu_from_db - proc called once at start for fetching top menu content

FUNCTION

    for performance reason lets try to keep top menu in memory ; this procedure
    fetches it into global variable $::topmenu_content

USED BY

    backend.tcl

INPUTS

    none

RESULT

    none but fills backend.tcl/::topmenu_content

SEE ALSO

   backend.tcl/fill_string_arrays

backend.tcl/::topmenu_content

NAME

    ::topmenu_content - global variable for holding topmenu content

DESCRIPTION

    used by about every procedure that needs to format whole html document in schtonk

backend.tcl/find_max_attachment_id

NAME

    find_max_attachment_id - does "select max(attachment_id)" ; used for unique numbering of attachments

FUNCTION

 procedure that gets biggest attachment id from db to be used
 later for future attachments

USED BY

    backend.tcl

INPUTS

    none

RESULT

    none but fills global variable backend.tcl/::max_attachment_id

SEE ALSO

   backend.tcl/save_da_attachment

backend.tcl/init_database_connection

NAME

    init_database_connection - initializes db handle

FUNCTION

    procedure that connects to mysql db

USED BY

    backend.tcl

INPUTS

    none

RESULT

    none but fills global variable backend.tcl/::mysli

SEE ALSO

   backend.tcl/save_da_attachment

backend.tcl/::mysli

NAME

    ::mysli - mysql database handle to be used with mysqltcl

DESCRIPTION

    used for all db stuff all around backend.tcl