Conscriptus Files

CONSCRIPTUS
http://meetup.commandus.com/

Foreword
========

People tend to argue about what they are doing. To do this,
they use bulletin boards, create a page on the Internet,
maintain their blogs, participate in conferences.

Now you can do so using your cell phone.

Tell a little about yourself, and you get contacts from 
people who are interested in communicating with you. You 
can just tell about garage sales or car or real estate. 
If you like to do in their spare time to engage in fishing, 
software development or painted fences, just write about it.
You can also try to find new customers for your restaurant
or clinics. Look at the application just as an yellow pages,
in which your potential customers do not need to remember of
your phone numbers anymore, they simply will be looking
for your service on the keywords.

The most interesting thing is that the program offers a 
simplification of the process of appointing the time and place 
of meeting people. When a person finds your data and wants to 
use your service or simply meet, the program shows a time
when both he (she or even it) and you are free. 

You do not need to spend time and phoned to the appointment of 
mutually convenient time, the program will agree on the 
schedule of your working quickly and easily.

1. Scope
========

Cellphone application to assist persons assign a meeting at the suitable 
place and time according to their location and time sheet. Advertisers
can indicate their services. For instance, user can enter "Garage sale"
to inform their neighbors about event.

There is small example how two user can use this:
	- User of handset wants to find out service closest to him, for
		instance, user can enter "Taxi" or "Pizza"
	- Advertiser, for instance, a driver of taxi who placed information
		about services his company provides, get a notification
		about somebody at the indicated location on map wants to 
		pick-up.

This document describes purpose, typical application, required and recommended
operations of the User. Second part contains a reference of scripts useful
to integrate application into company's environment.

If you have Adobe Reader installed, please read 
http://meetup.commandus.com/doc/UsersGuide-en.pdf. This PDF document is much
easy to read. Other documents you can download from http://meetup.commandus.com/

Please note Section 7 describes test data which can be helful to test application,
you can also take a look at http://meetup.commandus.com/live/ - page show
list of pre-loaded data to play with.

2. What can you use the Conscriptus 
===================================

2.1 Background

The program is designed for use in mobile devices:
	1.telephones;
	2.hand-held computers
working on the Android platform.

2.2 Designation

The program is designed for
	1. Looking for people and objects on the following criteria:
		- services;
		- belonging to a group of professional, social activities, personal interests (hobbies);
		- submitting private advertisements;
	2. assign place and time of the meeting or obtain services;
	3. Grouping people and objects in separate ?slices?.

2.3 Variations of use

	1.Maintenance reception in clinics, workshops and field attendance
	2.Looking for proposals for the sale of vehicles and real estate, temporary work and garage sales (private ads)
	3.Group of people and objects to "slice":
		- bus route for traffic control on the map;
		- ATMs, restaurants, community facilities or businesses selling goods on machines'
		- professional people.

2.4 Basic concepts

The program uses the following concepts:
	1. keyword
	2. slice
	3. radius
	4. time slot
One or more keywords used in the search for people and objects. Radius is the distance from the initiator to the 
original search site (person or object). Objects that are too far away, usually drop. 

3 Build and Installation
========================

There are two version of server side software:
	- gcc/Autotools standalone server and client using gSOAP C/C++ library and Berkeley DB backend;
	- Perl CGI scripts: server and client using kSOAP Perl library, server script is not compatible with C/C++ Berkeley DB backend;
Also Dephi wrapper which can get access to the Berkeley DB database in monopoly mode is available.
Simple Android client is available too.
You can obtain latest release from http://meetup.commandus.com/download/ or http://meetup.sf.net/. Install meetup.apk file as described in instruction to the device or an emulator.

3.1 Unix compatible

./configure
make
make install

3.2 Mingw on Microsoft Windows

rename Makefile.mingw to Makefile and type make in cmd prompt.

3.3 Visual studio on Microsoft Windows

Not supported.

3.4 Perl

See README.perl

4 Setup
=======

When you first launch the program offers to enter the kind of activity, your name, keywords used in the search, the 
name of your location. It is not necessary to specify all the information you are limited in your choice of a nick name
(pseudonym) or real names.
Later you can change those names so as to ensure a flow of visitors, and prevent unwanted contacts.
The example shows how to fill in the data about you and your service more detail.

Complete the first form.
The first button serves to define working time, the second - lunch time.
Duration sets recommended time per visit. This duration will be offered people designating a meeting with you by
default.

Select menu "Edit my contacts"

Enter contact phones.

In the "Subject" specify the name of the meeting recommended for people who are appointing you meet. In the "Item" 
you can specify the name or identifier of goods or services.

Select menu "Service information"

Enter the name and title of the slice (layer) and telephone of company (service). Indicate whether the service 
rendered active. Later, you can quickly enable or disable service from the menu.

Select menu "Maintenance"

Select "Server host". 

If you do not install the server side applications that use the proposed address of the server. After the first time
client connect to the server, server will find other server nearest to you, so that the address can be changed by the
program.

Select menu "Refresh time". By default  MeetUp connecting to the server each 5 minutes and download updated list of 
new appointments.

Sometimes it is important to update your location more often. By default, your coordinates transmit to the server
every 30 minutes with an accuracy not exceeding 1 kilometer.

Close window. Check one more time your settings and press "Apply" button in the menu.

Please wait until server gives you a new identifier and password and your personal data stores to the server.

Setup completed. You can then edit, selecting from the menu "Profile".

5 Quick start
=============

Once the server has appointed a new account, you can start using the program. 
Select a meeting and press it, or in the menu select "Appointment".

It can be labeled in the planned meeting, to change the place or time.

Select "Find" in menu.

Enter keywords, or the full name of the desired object or person. In the example, we introduce the name of the place
where the man.

Click on "Search" button or select "Search" button in menu. Depending on the distance from your desired object or
person search may take considerable time.

Running a list of found objects or people. Select the most suitable person. At the top of the screen show: keywords,
layer (slice), the location name, company's name and the distance from you to the person or object in kilometers.

Click on the person or object harvested or select "Meeting" in menu. The list of the most suitable places and times
for meetings.
Available time slots (running time) that is free from the found person or object as well as you.
Select the desired time interval. The example chosen morning.

Because found person believed that 15 minutes is sufficient for communication, the meeting clarified. Choose a
suitable 15 minutes in the list.

User returning to the screen a list of scheduled meetings.

You can add to the list of activities without finding other people. The scheduled time now is not available.

To suspend the admission of people at the meeting, in the menu, click "Available" button.

Red color button means that the admission has left.

The menu "Maintenance" you can remove selected appointment or delete all the overdue meetings.

In menu button ?Profile? gives access to the properties of your account.

The button "Changing the date" in the menu   allows leafing case forward or backward.

To return to the current time, click on "Today" button.

In the "Time Window" menu user can expand searching by time shifting.

By default calendar showing people and objects found on the same day. If at this time there is no free (available)
time, it is possible to expand the search for the next day, week or month.

Geographically, the search can be expanded or restricted by the increase or decrease the radius of the search.

By default distance to the object or person is disregarded.

If option "at any time" turned off, a meeting may be imposed only for your kindness and human being harvested.

If option "at any time" turned on, the meeting may be appointed in overtime for you. This option can also help if
the people at the arrival in your time zone is not changed its time zone.

If necessary, the appointment of the meeting is useful to make a preliminary call to find out details

Following agreement on the phone could go on the appointment of the meeting.

6 Integration tools and scripts
===============================

Not all people use telephones. Nevertheless, often to work effectively often requires programs to the scheduling of 
the experts. Package includes part of the server, which performs the functions of planning time by which applications 
can be treated using SOAP. The specifications of functions listed in the file soapmeetup.wsdl, they can be easily 
imported into development environment such  Borland Delphi and Visual Studio and use them with any programming
languages, as with the "normal" functions.
The second way is likely to be interesting web programmers. Package includes a set of utilities, packaging, or that 
return data in text form or in the form of XML documents, or in a format JSON.
The text type can be used to create applications using the programming scripts for interpreters bsh, bash, ksh,
or perl.
The last two methods are often used in various AJAX framework known as Web2.0 technology. Available small example
using Adobe Spry framework.

6.1 Utilities

Utilities are Perl scripts and Perl scripts has .pl suffix in the file name.
It requires Perl interpreter versions 4-5, accessible on the path /usr/bin/perl. Before using scripts, you must have
permission to perform, for example, you need execute the command chmod a+x *. pl. For the convenience of scripts
files can be renamed, in particular, has been removed suffix ". pl" from the file names.
In the Windows are encouraged to call Perl interpreter clearly:

C:>perl getver.pl

You can set interpreter on call "file name extension" using the Registry Editor. For more information, see the
documentation Perl under "Windows specifics".
Scripts can be summoned as from the command line or through an interface CGI, in the latter case, the folder
containing the files scripts must have the appropriate permissions that are specific to a particular web server.

6.1.1 Parameters

All parameters consists of name and value, delimited by ?=? sign. If parameter value consist of spaces, value must
be enclosed in paired """. Using CGI, all parameters must be delimited by "&" sign.
Parameter fmt controls MIME type of produced document. By default JSON format is used. XML document is also available.

6.1.2 delrec

Purpose:	Delete user record 
Usage:		delrec.pl u=<user name> pwd=<password> [v=1] [fmt=plain|json|xml] [host=<host>] [p=<script path>]
Example:
./delrec.pl u=Corwin pwd=masterkey
CGI example:
http://localhost/cgi-bin/delrec.pl?u=Corwin&pwd=masterkey

6.1.3 distance

Purpose:	Calculate distance between two points in meters
Usage:		distance.pl l1=<latitude1> o1=<longitude1> a1=<altitude1> l2=<latitude2> o2=<longitude2> a2=<altitude2>
		[fmt=plain|json|xml] [host=<host>] [p=<script path>]
Example:
./distance.pl l1=60.0 o1=130.0 l2=59.9999 o2=130.0 
Example:
./distance.pl l1=11.01 o1=22.02 l2=11.0101 o2=22.0201
Result: 15m
CGI example:
http://localhost/cgi-bin/distance.pl?l1=60.0&o1=130.0&l2=59.9999&o2=130.0 

6.1.4 findrec

Purpose:	Find record by keyword(s)
Usage:		findrec.pl u=<user name> pwd=<user password> l=<latitude> o=<longitude> a=<altitude> k=<keys>
		r=<radius> s=<starts> e=<ends> c=<min capacity> sl=<slice> n=<nickname> ln=<location name>
		[help=1] [v=1] [host=host] [p=script]
Example:
./findrec.pl u=Corwin pwd=masterkey l=11.234 o=22.23 a=6 r=4000 k=queen
CGI example:
http://localhost/cgi-bin/findrec.pl?u=Corwin&pwd=masterkey&l=11.234&o=22.23&a=6&r=4000&k=queen

6.1.5 getappointments

Purpose:	Get time-sheet of specified user. This function works differently for user owns time-sheet an others.
		Return new appointments for owner, return appropriate time-slots for others. After each call ?new? flag is turned off.
Usage:		getappointments.pl t=<to-user> f=<from-user> w=<from password> ds=<starting date/time> de=<ending date/time> s=<starts>
		e=<ends> bs=<breakstarts> be=<breakends> [f=file] [fmt=json|plain|xml] [d=1] [myall=1] [help=1] [v=1]
		[host=host] [p=script]
Example:
./getappointments.pl t=Tmer f=Corwin w=masterkey s=8:00 e=17:00 bs=13:00 be=14:00 f=timesheet1.txt

6.1.6 getrec

Purpose:	Get record for user.
Usage:		getrec.pl u=<user name> [tz=<time zone offset number in hours>] [fmt=txt|json|xml] [host=<host>] [p=<script path>]
Example:
./getrec.pl u=Corwin fmt=plain

6.1.7 getuid

Purpose:	Get uid for a new user
Note:		getuid creates a new record in this version. Call setrec() immediately after getuid().
Usage:
getuid.pl l=<latitude> o=<longitude> a=<altitude> [help=1] [v=1] [fmt=plain|json|xml] [host=<host name>]
		[p=<script path>] 
Example:
./getuid.pl l=1.01 o=2.22

6.1.8 getver

Purpose:	Get script version
Usage:		getver.pl [help=1] [fmt=plain|json|xml] [host=<host name>] [p=<script path>] 
Example:
./getver

6.1.9 loaddata

Purpose:	Load data from tab-delimited text file
Usage:		loaddata.pl f=<tab-delimited file> [u=<user>] [n=1] [v=1] [help=1] [host=<host>] [p=<script path>]
Example:
./loaddata f=testdata.txt u=Corwin n=1
In this example, add Corwin record from the testdata.txt.
N=1 do not clear data before loading.
If option "f" is omitted, all records will be loaded.

6.1.10 ls

Purpose:	Get list of users. You can use regular expression e.g. .*win returns Corwin and Delwin.
Note:		host and p parameters is not used, only list from local host is available.
Usage:		ls.pl [filter=<user name regexp>] [a=<attr name>] [help=1] [fmt=plain|json|xml] [host=<host name>] [p=<script path>]
Attributes:
password, pre_zone, phone, xmpp, latitude, longitude, altitude, slice, keys, hash, attrs, photo, date, servicename, 
serviceon, starts, ends, breakstarts, breakends, flatitude, flongitude, faltitude, locationisfixed, locationname, 
capacity, needcoords, needconfirm, confirmationtype, needmoreinfo, flags, created, modified

Note:

If attribute ?password? is specified, no result returned. 

Example:
./ls.pl
In this example, all users will be shown.
Example:
./ls.pl a=slice
CGI Example:
./ls.pl?a=slice&fmt=xml
In this example, all slices will be shown.

6.1.11 meetupcgi

Purpose:	Common gateway interface
Usage:
Perl code sample:

	my $service = SOAP::Lite->uri(Meetup/Lite)-> proxy('http://localhost/cgi-bin/meetupcgi.pl);

This script give access to the Meetup::Lite package via SOAP.

6.1.12 setappointments

Purpose:	Set appointments of specified user.
Note:		First you need call getappointments.pl to get list of available time slots. Return true if appointments is assigned
Usage:		setappointments.pl t=<to-user> f=<from-user> w=<from password> su=<subject> ln=<locationname> l=<latitude> 
		o=<longitude> a=<altitude> s=<starts> e=<ends>  it=<items> op=<operation> [fmt=json|plain|xml]
		[d=1] [help=1] [v=1] [host=host] [p=script]
		where operation 1- delete appointment. Valid if to-user = from-user (owners can delete appointment only). 
Example:
./setappointments.pl t=Tmer f=Corwin w=masterkey ln="Bloody Andy" l=22 o=33 a=4 s=11:00 e=11:45 su="Yak yak"
Example
./setappointment.pl u=Corwin pwd=masterkey z=1 tel=5551256 xmpp=corwin l=11.234 o=22.23 a=6 sl=Amber k=prince:doctor 
	h=12368 sn="Cordell Farmacy" on=1 s=09:00 e=17:00 bs=12:00 be=13:00 fl=11.23 fo=22.23 fa=5 ln=Paris td=0:30
	it="visit" subj="Visit doctor"

6.1.13 setrec

Purpose:	Set record for user.
Usage:		setrec.pl u=<user name> pwd=<user password> tel=<phone> xmpp=<xmpp address> z=<pre_zone> l=<latitude> o=<longitude>
	a=<altitude> sl=<slice> k=<keys> h=<hash> sn=<service name> on=<on> s=<starts> e=<ends> bs=<breakstarts>
	be=<breakends> td=<time duration> fl=<fixed service latitude> fo=<longitude> fa=<altitude>
	lf=<location is fixed=1> ln=<location name> c=<capacity> nc=<need coords from client=1> nf=<need confirm>
	ct=<confirmation type> ni=<need more info=1> f=<flags> [ph=<photo file name>] [w=<link url>] [nn=<nickname>]
	[attrs=attrs] [td=<time duration>] [it=<items>] [subj=<subject>] [v=1] [host=host] [s=script]
Time can be assigned as decimal seconds since 1970 or in ?HH:MM? format. 
Example:
./setrec.pl u=Corwin pwd=masterkey z=1 tel=5551256 xmpp=corwin l=11.234 o=22.23 a=6 sl=Amber k=prince:doctor h=12368
	sn="Cordell Farmacy" on=1 s=09:00 e=17:00 bs=12:00 be=13:00 fl=11.23 fo=22.23 fa=5 ln=Paris

6.1.14 time2long

Purpose:	Get time as long integer since 1970 
Note:		Useful in log analysis.
Usage:		time2long.pl y=<year> m=<month> d=<day> hh=<hour> mm=<minute> z=<zone> [help=1] [fmt=json|plain|xml] 
Example:
./time2long.pl y=2008 m=4 d=1 hh=21 mm=55

6.2 Perl specific
-----------------

6.2.1 Testing SOAP call
-----------------------

perl SOAPsh.pl http://localhost/cgi-bin/meetupcgi.pl urn:Meetup/Lite

then enter function name: getver

6.2.2 Create perl stub using WSDL file
--------------------------------------

You can create stub with stubmaker script:

1. Copy soapmeetup.wsdl to the web server root directory
2. Call script:
        stubmaker http://localhost/soapmeetup.wsdl
or
        perl stubmaker.pl http://localhost/soapmeetup.wsdl

3. Validate end point:
        endpoint => 'http://localhost/cgi-bin/meetupcgi.pl',
perl "-Meetup qw(:all)" -le "print getver()"
You get
        12

Then you can use created meetup.pm:

use Meetup::Lite ':all';
print getver();


6.2.3 Time zones
----------------

All time stored are UTC.
In Javascript, getTimezoneOffset() returns value -9 for GMT+9 and 9 for GMT-9. In the scripts you must invert
time zone offset before pass it to "tz" parameters.

6.2.4 How data is stored
------------------------

User table:
Key             Value
----------------------
<user name>     serialized array of data (32 elements)


7 Test data
===========

7.1 Loading test data

Test data can be imported from a OpenDocument spreadsheet testdata.ods. In the File menu, select "Save as Text CSV". 
In the dialog, specify a field separator {Tab} and empty symbol as separator. Ask testdata.txt file.
Another way is select entire table and copy it into Notepad, save to a text file tesdata.txt.
Get the resulting file utility loaddata:
loaddata f=testdata.txt

7.2 Clean up database tables

One way is to re-load data with empty dataset:
loaddata f=testdata.txt u=NA
of just deleting files of database. Then package Meetup:: Lite will reconstruct all database files. Pay attention 
to the need have enough rights.

8 Some details about how it does implemented
============================================

8.1 How it works

The client program calls to the server in finding people and objects. Designated meeting are stored on the server,
serving the target person or object.

Client program raises function in one of the servers. Server can query another server. When another server responds,
the first server transmits the customer response.
Because the data are distributed in the space between the remote servers, each server computes the desired server,
where the necessary data can reside and request it.
One server has one or more zones. The zone is a rectangular area, asked polar coordinates two points. Each zone
has a unique number.

Potentially, it could lead to endless cycles. To combat this, server verify where a request was received. If another
server, then banned. If the client, then allowed. To that end servers must have lists of servers. Servers pass
parameters TTL for the prevention of endless cycles.
Lists of servers need to determine a responsible server.
Servers are divided into levels. Level 0 is responsible for updating the lists of servers lower levels. Level 1 Servers
are responsible for one or more zones and can respond to client needs. Server Level 2 did not meet any one area, but
responding to the requests of customers, directing them to the server level 1. Servers can Level 2 cache information.
In this realization server processes data locally without sending data to other servers.
For more information, please refer to the Developer's Guide.

9 Contacts
==========

This application is alpha and intended for Android contest. If you have any question, please contact me to
mailto:support@commandus.com, G-Talk jid:andrei.i.ivanov