#!/usr/bin/perl
#############################################################################
#
# fxtp_commands.cgi -- FXTP command API documentation.
#
# $License:
#
# Copyright (C) Kenneth A. Kittlitz, All Rights Reserved.
# 
# Unless explicitly acquired and licensed from Licensor under a
# separate arrangement, the contents of this file are subject to the 
# Idea Futures Public License ("IFPL") Version 1.0, or subsequent
# versions as allowed by the IFPL, and You may not copy or use this file
# in either source code or executable form, except in compliance with the
# terms and conditions of the IFPL.
# 
# The IFPL V1.0 is identical to the Reciprocal Public License V1.1 as
# published at <http://www.opensource.org/licenses/rpl.php>, with the
# following two changes to term 13.8:
# 
# [start of changes]
# Change 1) Replace:
#    "This License shall be governed by Colorado law provisions..." 
# with:
#    "This License shall be governed by Alberta law provisions...".
# 
# Change 2) Replace:
#    "You further agree that Adams County, Colorado USA is proper venue..."
# with:
#    "You further agree that Alberta, Canada is proper venue...".
# [end of changes]
# 
# All software distributed under the License is provided strictly on
# an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
# IMPLIED, AND KENNETH A. KITTLITZ HEREBY DISCLAIMS ALL SUCH
# WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT,
# OR NON-INFRINGEMENT. See the License for specific language
# governing rights and limitations under the License.
#
# :License$
#
#############################################################################

use strict;
use CGI;
require "Common.pl";

my (@content,$data);
my $query = new CGI;
print $query->header;

my $title = "FXTP Command Set";
my $header = "FXTP Commands";
$data = <<EOT;
<UL>
<LI><A HREF="#fxtp">FXTP Commands<a></LI>
<UL>
<LI><A HREF="#Introduction">Introduction</A></LI>
<LI><A HREF="#Overview">Overview of Usage</A></LI>
<LI><A HREF="#HD_NM_5">FXTP Servers</A></LI>
<LI><A HREF="#Types of Commands">Types of Commands</A></LI>
<LI><A HREF="#HD_NM_9">Command Descriptions</A></LI>
<LI><A HREF="#HD_NM_16">Other Topics</A></LI>
</UL>
</UL>
<P></P>
<P>COPYRIGHT: this document may be freely redistributed in its entirety, including this copyright notice. Redistribution of parts of this  document requires the consent of the editor, Ken Kittlitz (kittlitz AT ideosphere DOT com). All other rights reserved.</P>
<H1><A NAME="fxtp">FXTP Command Set</A></H1>
<H2><A NAME="Introduction">Introduction</A></H2>
<P>This document describes the <A HREF="/\L${FXTP::T_ACRONYM}\E/index.html">Foresight Exchange</A> Transport Protocol (FXTP) command set. FXTP is the protocol by which clients (web, telnet email, etc.) communicate with the FXTP server. The  <A HREF="fxtp.html">FXTP Overview</A> describes the overall server structure and rationale behind FXTP; complete documentation on <A HREF="index.html">how to play</A> the Foresight Exchange is also available.</P>
<H2><A NAME="Overview">Overview of Usage</A></H2>
<H3><A NAME="Connecting">Connecting to the FXTP Server</A></H3>
<P>To use the Foresight Exchange, you send FXTP commands to the server via one of several ways:</P>
<UL>
<LI>using the <A HREF="/\L${FXTP::T_ACRONYM}\E/index.html">webface</A>. In this case, the FXTP commands are embedded in the CGI scripts that make up the pages, and you don't need to know the actual FXTP syntax. This option will suffice for many players.</LI>
<LI>using the <A HREF="#Connection Server">connection server</A>. This is the "raw" FXTP server, suitable for use by automated agents, Java applets, ActiveX controls etc.</LI>
<LI>using the <A HREF="#Telnet Server">telnet</A> or <A HREF="#Email Server">email</A> servers. Both provide handy shortcuts for FXTP commands, and format the output of some commands. These servers are intended for direct use by people, as opposed to programs.</LI>
</UL>
<P></P>
<P>This document focuses on the connection and telnet/email servers.</P>
<H3><A NAME="HD_NM_4">Basic Command Structure</A></H3>
<!-- help:command_structure-->
<P>FXTP commands are all of the form:</P>
<PRE>
<code>name argument1,argument2,...</code>
</PRE>
<P>where <I>name</I> is the name of command and <I>argument1, argument2</I> etc. are its arguments. All "raw" FXTP commands as supported by the <A HREF="#Connection Server">connection server</A> are terminated by a newline character (ASCII value 10); that is, no command can span multiple lines. The <A HREF="#Telnet Server">telnet</A> and <A HREF="#Email Server">email</A> servers allow more humane ways of entering some commands.</P>
<P>An example of an FXTP command is:</P>
<P><code>claim_info Foobar,short,judge</code></P>
<P>which would return the short description and the judge of claim "Foobar".  Exactly how the information is returned depends on the <A HREF="#HD_NM_5">server</A> being used.</P>
<H2><A NAME="HD_NM_5">FXTP Servers</A></H2>
<P>FXTP servers allow you to send FXTP commands to the main database server. Other than the <A HREF="/\L${FXTP::T_ACRONYM}\E/index.html">webface</A>, which takes care of the FXTP commands for you, you have the choice of sending/receiving raw FXTP commands via the <I>connection server</I>, or formatted commands via the <I>telnet</I> or <I>email</I> servers.</P>
<H3><A NAME="Connection Server">Connection Server</A></H3>
<!-- help:connection_server-->
<P>The connection server runs on port 7001 of ideosphere.com It accepts "raw" FXTP <A HREF="#Types of Commands">commands</A>, meaning that each command is terminated by a new-line, and returns raw output. The format of the output varies from command to command, however:</P>
<UL>
<LI>the status of the command is always returned as the first output line. The status line begins with a number: "2nn" indicates success; anything else indicates failure.</LI>
<LI>output  is guaranteed to be terminated by a '.' character on a line by itself. </LI>
</UL>
<P>Note that each line of output is terminated by a newline character (ASCII value 10), <I>not</I> by a carriage return/newline combination.</P>
<P>For example, sending the  FXTP command:</P>
<P><code>claim_info Foobar short,date_due</code></P>
<P>to the connection server might result in output like:</P>
<PRE>
200 command OK, output follows...
<code>This is the short description of claim "Foobar"...</code>
<code>1995/01/01</code>
<code>.</code>
</PRE>
<P>In other words, the claim status is the first line of output, the short description of the claim is returned as the second line, the claim's due date returned as the third line, and the terminating '.' as the third line.</P>
<P>To exit a connection server session, send the command <code>bye.</code></P>
<P>The connection server is designed for use by programs such as automated agents and Java applets.</P>
<H3><A NAME="Telnet Server">Telnet Server</A></H3>
<!-- help:telnet_server-->
<P>The telnet server runs on <A HREF="telnet://ideosphere.com:7002/">port 7002 of ideosphere.com</A>, and is designed to be used by people rather than programs. Like the connection server, it accepts FXTP <A HREF="#Types of Commands">commands</A> as input; most are simple enough to be specified on one line, but it supports <A HREF="#Telnet and Email Server Extensions">extensions</A> for more complex commands, including alternate syntax, shortcuts, and. formatting of command output so that it is easier to interpret: for successful commands, the status line is not returned; for all command the terminating '.' line is stripped. Each line of output is terminated by a carriage return/newline pair (ASCII 10 + ASCII 12).You can identify the end of a command's output because the server displays the following prompt when it is ready to receive more input:</P>
<P><code>FXTP-telnet:</code></P>
<P>To exit a telnet server session, enter the command <code>bye.</code></P>
<H3><A NAME="Email Server">Email Server</A></H3>
<!-- help:email_server-->
<P>The email server is available at <A HREF="mailto://\L${FXTP::T_ACRONYM}\E\@ideosphere.com">fx\@ideosphere.com</A>, and is designed to be used by people rather than programs (though nothing prevents you from writing a program that uses it). Like the connection server, it accepts FXTP <A HREF="#Types of Commands">commands</A> as input; most are simple enough to be specified on one line, but for more complex commands it supports <A HREF="#Telnet and Email Server Extensions">extensions</A> such as alternate syntax, shortcuts and formatting of command output so that it is easier to interpret.. For all command output, the server strips off the terminating '.'; in its response message, it indicates which output is associated with which command request.</P>
<P>If the server was unable to recognise any commands in the message, it will return the output for the <A HREF="#commands:help">help</A> command.</P>
<H3><A NAME="Telnet and Email Server Extensions">Telnet and Email Server Extensions</A></H3>
<P>Because the telnet and email servers are designed primarily for use by people rather than programs, they use some variations on the raw FXTP syntax. These fall into three categories: <I>shortcuts, alternate syntax </I>and <I>output formatting.</I></P>
<H4><A NAME="Shortcuts">Shortcuts</A></H4>
<!-- help:server_shortcuts-->
<P>The only shortcut currently supported is <I>login,</I> which has the following syntax:</P>
<P><code>login uid,password</code></P>
<P>When this command is entered (either in a telnet server session, or as a line in a message to the mail server), subsequent commands that require a uid and/or a password can be typed in abbreviated form. For example, the person with uid 107 and password 'haha' would normally place <A HREF="#commands:orders">orders</A> command like this:</P>
<P><code>orders 107,haha,new Foobar B10\@30</code></P>
<P>But using the <I>login</I> shortcut, he/she can send commands like:</P>
<P><code>login 107,haha</code></P>
<P><code>orders ,,new Foobar B10\@30</code></P>
<P>Note that the commas that delimit the uid and password fields still have to be included. So, for example, the shortcut for the same user's <A HREF="#commands:account">account</A> command:</P>
<P><code>account 107,-1</code></P>
<P>would be:</P>
<P><code>account ,-1</code></P>
<P>Commands that can be abbreviated using the <I>login</I> shortcut are: <A HREF="#commands:account">account</A>, <A HREF="#commands:approve">approve</A>, <A HREF="#commands:claim">claim</A>, <A HREF="#commands:orders">orders</A>, <A HREF="#commands:set_email">set_email</A>, <A HREF="#commands:profile">profile</A>, <A HREF="#commands:set_password">set_password</A>, <A HREF="#commands:set_profile">set_profile</A> and <A HREF="#commands:user_info">user_info</A></P>
<H4><A NAME="Alternate Syntax">Alternate Syntax</A></H4>
<!-- help:alternate_syntax-->
<P>For ease of use, the telnet and email servers use alternate syntax for the following commands: <A HREF="#commands:claim">claim</A>.</P>
<H4><A NAME="Output Formatting">Output Formatting</A></H4>
<!-- help:output_formatting-->
<P>For ease of use, the telnet and email servers format the raw output of the following commands: <A HREF="#commands:account">account</A>, <A HREF="#commands:claim">claim</A>, <A HREF="#commands:claim_info">claim_info</A>.</P>
<H2><A NAME="Types of Commands">Types of Commands</A></H2>
<P>FXTP commands can be broken down into several categories (some commands appear in more than category).</P>
<H3><A NAME="HD_NM_15">Registration/Administration Commands</A></H3>
<!-- help:registration/admin_commands-->
<P>The following commands are used to create or maintain your FX registration:</P>
<UL>
<LI><A HREF="#commands:register">register</A>: the first command you send, used to create a new account.</LI>
<LI><A HREF="#commands:activate">activate</A>: confirms your registration</LI>
<LI><A HREF="#commands:resend_id">resend_id</A>: resends the FX uid and password associated with your email address</LI>
<LI><A HREF="#commands:set_email">set_email</A>: changes the email address associated with your account.</LI>
<LI><A HREF="#commands:set_password">set_password</A>: changes your account's password</LI>
<LI><A HREF="#commands:set_profile">set_profile</A>: sets one of your user profiles</LI>
</UL>
<!-- info:For more information on a specific command, use "help <command>".-->
<P></P>
<H3><A NAME="Trading Commands">Trading Commands</A></H3>
<!-- help:trading_commands-->
<P>The major trading commands are:</P>
<UL>
<LI><A HREF="#commands:orders">orders</A>: places orders on claims</LI>
<LI><A HREF="#commands:account">account</A>: retrieves your portfolio</LI>
<LI><A HREF="#commands:ticker">ticker</A>: retrieves the trading history of a claim or user</LI>
<LI><A HREF="#commands:volume">volume</A>: retrieves the trading volume of claims for a specified trading period.</LI>
<LI><A HREF="#commands:plot">plot</A>: plots the price of a claim for a specified trading period.</LI>
</UL>
<!-- info:For more information on a specific command, use "help <command>".-->
<P></P>
<H3><A NAME="HD_NM_12">User Information Commnands</A></H3>
<!-- help:user_info_commands-->
<P>Commands that return information about users are:</P>
<UL>
<LI><A HREF="#commands:list_uids">list_uids</A>: retrieves the set of user Ids (uids)</LI>
<LI><A HREF="#commands:user_info">user_info</A>: retrieves attributes of a specified user</LI>
<LI><A HREF="#commands:ticker">ticker</A>: retrieves a user's trading history</LI>
<LI><A HREF="#commands:profile">profile</A>: retrieves a trading profile for a specific user.</LI>
</UL>
<!-- info:For more information on a specific command, use "help <command>".-->
<P></P>
<H3><A NAME="HD_NM_13">Claim Information/Editing Comm</A>ands</H3>
<!-- help:claim_commands-->
<P>Commands that create, modify, or return information about a claim are:</P>
<UL>
<LI><A HREF="#commands:change_claim_state">change_claim_state</A>: allows a judge to close a claim</LI>
<LI><A HREF="#commands:claim">claim</A>: creates or modifies a claim.</LI>
<LI><A HREF="#commands:list_claims">list_claims</A>: retrieves the  list of claim symbols</LI>
<LI><A HREF="#commands:claim_list">claim_list</A>: retrieves the list of claims associated with a specified <A HREF="#keywords">keyword</A>.</LI>
<LI><A HREF="#commands:list_keyword">list_keyword</A>: retrieves the list of possible claim keywords.</LI>
<LI><A HREF="#commands:claim_info">claim_info</A>: retrieves attributes of a specified claim</LI>
<LI><A HREF="#commands:ticker">ticker</A>: retrieves a claim's trading history</LI>
<LI><A HREF="#commands:volume">volume</A>: retrieves the trading volume of claims for a specified trading period.</LI>
<LI><A HREF="#commands:plot">plot</A>: plots the price of a claim for a specified trading period.</LI>
<LI><A HREF="#commands:approve">approve</A>: allows a player to signify that he/she is willing to be the judge of a claim.</LI>
</UL>
<P>Additionally, help is available for the <A HREF="#regexp">regular expression syntax</A> used to specify claims.</P>
<!-- info:For more information on a specific command, use "help <command>".-->
<!-- info:For more information on claim symbol regular expressions , use "help regexp".-->
<P></P>
<H3><A NAME="HD_NM_14">Miscellaneous Commands</A></H3>
<!-- help:misc_commands-->
<UL>
<LI><A HREF="#commands:help">help</A>: returns FXTP help information.</LI>
<LI><A HREF="#commands:time">time</A>: returns the current server time.</LI>
<LI><A HREF="#commands:bye">bye</A>: terminates a connection or telnet server session.</LI>
</UL>
<!-- info:For more information on a specific command, use "help <command>".-->
<P></P>
<H2><A NAME="HD_NM_9">Command Descriptions</A></H2>
<P>This section describes the FXTP commands in detail; commands are listed alphabetically.</P>
<H3><A NAME="commands:account">Account</A></H3>
<!-- help:account-->
<P>Retrieves a user's portfolio, as specified by a <A HREF="#profiles">profile key</A> or <A HREF="#coommands:keywords">keyword</A> (both are values that selects a set of claims).</P>
<H4>Syntax</H4>
<PRE>
account uid,&lt;profile_key | keyword&gt;
</PRE>
<H4>Returns</H4>
<P>The system time, user's nym, cash, networth and score. For each keyword selected,  the keyword name. For each claim associated with the keyword, the claim symbol, user's holdings (0 if none), bid/ask/last price (on one line, separated by tabs), short description and user's booked orders (blank line if none).</P>
<P>The <A HREF="#Connection Server">connection server</A> returns the information one item per line; the <A HREF="#Telnet Server">telnet</A> and <A HREF="#Email Server">email</A> servers format the output.</P>
<H4>Connection Server Example</H4>
<PRE>
account 107,-1
200 command OK, output follows...
1996/09/24 14:19:52
Killer
 883.01
 972.31
0.972
Category: Booked Orders
\$vIF
1
68      70      70
Real \$ Ver. of IF (&lt;1.1.2000)
50Y\@53,100N\@10
BBQT
0
81      90      90
U.S. Abandons Net Censorship
50N\@5                 
.
</PRE>
<!-- info:See also: "help profile".-->
<PRE>

</PRE>
<H3><A NAME="commands:activate">Activate</A></H3>
<!-- help:activate-->
<P>Activates a newly-<A HREF="#commands:register">registered</A> account. </P>
<H4>Syntax</H4>
<PRE>
     activate email,password
</PRE>
<P>where:</P>
<UL>
<LI><I>email</I>: is your email address</LI>
<LI><I>password</I>: is the password returned by the register command.</LI>
</UL>
<H4>Returns</H4>
<P>The uid for your account. This information is also emailed to you.</P>
<H4>Connection Server Example</H4>
<PRE>
activate ken\@ideosphere.com,f2jK1v
200 command OK, output follows...
uid=107
.
</PRE>
<!-- info:See also: "help register".-->
<P></P>
<H3><A NAME="commands:approve">Approve</A></H3>
<!-- help:approve-->
<P>Allows a player who has been asked to be the judge of a proposed to agree to this role and, implicitly, approve the claim's wording, due date, etc. Once a new claim has been approved and passed the mandatory waiting period, it becomes active for trading.</P>
<H4>Syntax</H4>
<PRE>
     approve uid, password, claim
</PRE>
<P>where:</P>
<UL>
<LI><I>uid</I>: is the judge's uid</LI>
<LI><I>password</I>: is the judge's password</LI>
<LI><I>claim</I>: is the symbol of the claim to be approved</LI>
</UL>
<H4>Returns</H4>
<P>English sentence denoting success or failure of operation.</P>
<H4>Connection Server Example</H4>
<PRE>
approve 107,haha,Foobar
200 command OK, output follows...
Claim 'Foobar' changed to APPROVED state.
.
</PRE>
<H3><A NAME="commands:bye">Bye</A></H3>
<!-- help:bye-->
<P>Terminates a <A HREF="#Telnet Server">telnet server</A> or <A HREF="#Connection Server">connection server</A> session.</P>
<H4>Syntax</H4>
<PRE>
     bye
</PRE>
<H4>Connection Server Example</H4>
<PRE>
bye
205 over and out
Connection closed by foreign host.   

</PRE>
<H3><A NAME="commands:change_claim_state">Change_claim_state</A></H3>
<!-- help:change_claim_state-->
<P>Allows the judge of an active claim to close it (render judgement).</P>
<H4>Syntax</H4>
<PRE>
     change_claim_state password, claim, YES_payout
</PRE>
<P>where:</P>
<UL>
<LI><I>password</I>: is the judge's password</LI>
<LI><I>claim</I>: is the symbol of the claim to be judged</LI>
<LI>YES_payout: is a number between 0 and 100 inclusive, indicating how much each YES coupon is worth. For example, 100 means each YES coupon is paid out at 1 credibill (NO coupons pay 0), 65 means each YES coupon is paid out at 0.65 credibills (NO coupons pay 0.35) and 0 means each YES coupon is worthless (NO coupons pay 1 credibill).</LI>
</UL>
<H4>Returns</H4>
<P>English sentence denoting success or failure of operation.</P>
<H4>Connection Server Example</H4>
<PRE>
change_claim_state haha,Foobar,0
200 command OK, output follows...
Claim 'Foobar' changed to state RETIRED.
.

</PRE>
<H3><A NAME="commands:claim">Claim</A></H3>
<!-- help:claim-->
<P>Creates a new claim or edits an existing claim. To create a claim, you must have at least $50 in your account. </P>
<H4>Syntax</H4>
<PRE>
     claim uid, password, symbol, short, long, judge, due,
           newsgroup, scaled, keyword, keyword,...
</PRE>
<P>where:</P>
<UL>
<LI><I>uid</I>: the creator's/editor's uid</LI>
<LI><I>password</I>: the creator's/editor's password</LI>
<LI><I>symbol</I>: the trading symbol of the claim</LI>
<LI><I>short</I>: short description of claim</LI>
<LI><I>long</I>: long description of claim</LI>
<LI><I>judge</I>: UID of judge (i.e., must be registered player)</LI>
<LI><I>due</I>: YYYY/MM or 'TBD'.</LI>
<LI><I>newsgroup</I>: newsgroup for summary postings</LI>
<LI><I>scaled</I>: 1 if claim is scaled (coupons may pay other than $0 or $1). 0 otherwise.</LI>
<LI><I>keyword</I>: keywords (categories) that claim belongs to.</LI>
</UL>
<P>When creating a claim, optional fields (see <A HREF="#claim_usage">usage</A>), can be omitted (though you still need to include all commas).</P>
<H4><A NAME="claim_usage">Usage</A></H4>
<P>Not all arguments need to be given. If creating a new claim, arguments not given are set to appropriate default values. If editing an existing claim, empty arguments do not affect existing claim values. To reset a claim value to its default, pass in 'none' for it.</P>
<P>When creating a new claim, the following fields are mandatory:</P>
<UL>
<LI>trading symbol</LI>
<LI>short description</LI>
<LI>long description</LI>
</UL>
<P>When editing an existing claim, the following rules apply:</P>
<UL>
<UL>
<LI>nothing can be edited if the claim is retired.</LI>
</UL>
</UL>
<UL>
<LI>otherwise:</LI>
<UL>
<LI>keywords' and 'newsgroup' can always be edited.</LI>
<LI>due' can be edited if its value is 'TBD' or if claim state is PROPOSED.</LI>
<LI>'judge', 'long', 'short', 'scaled' can be edited if and only if. claim state is PROPOSED. </LI>
</UL>
</UL>
<H4>Alternate Syntax</H4>
<P>The raw FXTP syntax of <I>claim</I> (as supported by the <A HREF="#Connection Server">connection server</A>) is not human-friendly. The <A HREF="#Telnet Server">telnet</A> and <A HREF="#Email Server">email</A> servers use an alternate syntax of the form:</P>
<PRE>
     claim uid,password
     tag: value
     tag: value
     end
</PRE>
<P>where:</P>
<UL>
<LI><I>tag</I>: is the name of a claim attribute. Legal attributes are "symbol", "short", "long", judge", "due", "scaled", "newsgroup" and "keywords".</LI>
<LI><I>value</I>: is the value of a claim attributes. If the attribute can have more than one value, they may be separated with commas or newlines.</LI>
</UL>
<P>Optional fields may be omitted. Note that the long description may span multiple lines.</P>
<H4>Telnet/Email Server Example</H4>
<P>The following would create claim "Foobar" (assuming a claim with that symbol doesn't already exist).</P>
<PRE>
claim 107,haha
symbol: Foobar
short: This is the Foobar claim
long: This is the long
description of the Foobar claim.
judge: 110
due:  1995/01/01
keywords: News:World News
News:US News
end
</PRE>
<H3><A NAME="commands:claim_info">Claim_info</A></H3>
<!-- help:claim_info-->
<P>Returns information about the specified claim symbol <A HREF="#regexp">regular expression</A>.</P>
<H4>Syntax</H4>
<PRE>
     claim_info (claim_regexp),attribute,attribute...]
</PRE>
<P>where legal attributes are: <I>short, judge, date_created, date_due, date_closed, long, bid, ask, last, owner, newsgroup, scaled, price, book, status, keywords.</I></P>
<H4>Returns</H4>
<P>Attribute values are returned in the order the attributes were specified; each value is terminated by a newline character. Note that some attributes may not have values (e.g., "date_closed" for active claims). In such case, only a newline character is returned..</P>
<UL>
<LI><I>short: </I>claim short description.</LI>
<LI><I>judge, owner: </I> UIDs.</LI>
<LI><I>date_created: </I>in format YYYY/MM/DD</LI>
<LI><I>date_due: </I>in format YYYY/MM/DD</LI>
<LI><I>date_closed:</I> in format YYYY/MM/DD</LI>
<LI><I>long: </I>claim's long description</LI>
<LI><I>judge_statement: </I>Judge's statement about the claim</LI>
<LI><I>bid, ask, last:</I> range from 0 to 100</LI>
<LI><I>price</I>: returns bid, ask and last prices, separated by tabs</LI>
<LI><I>book:</I> returns booked orders separated by commas Booked orders are all of the form <I>uid symbol order</I> (e.g., 107 BC96 B10\@85).</LI>
<LI><I>status: </I>state of claim. Values 0 to 100 inclusive is YES coupon payout (claim is closed); -1 indicates claim is proposed only; -2 indicates claim is active; -3 indicates claim is pending (past due date).</LI>
<LI><I>keywords:</I> separated by tabs.</LI>
</UL>
<P></P>
<P>The telnet and email server split output lines at about 70 characters.</P>
<H4>Connection Server Example</H4>
<PRE>
claim_info BC96,short,keywords,book
200 command OK, output follows...
Clinton re-elected in 96
Politics:US Politics
79 BC96 100\@89,157 BC96 65\@89,128 BC96 58\@89,286 BC96 
1\@89,199 BC96 106\@88,162 BC96 100\@88,157 BC96 79\@86
79 BC96 100N\@9,116 BC96 10N\@9,199 BC96 99N\@8
.
</PRE>
<H3><A NAME="commands:claim_list">Claim_list</A></H3>
<!-- help:claim_list-->
<P>Returns the symbols of claims having the <A HREF="#keywords">keywords</A> specified by a <A HREF="#regexp">regular expression</A></P>
<H4>Syntax</H4>
<PRE>
     claim_list keyword_regexp
</PRE>
<P>where:</P>
<UL>
<LI><I>keyword_regexp</I>: is a regular expression describing claim keywords.</LI>
</UL>
<H4>Returns</H4>
<P>The symbols of the claims that are associated with the keyword(s). Each symbol is terminated by a newline character.</P>
<H4>Connection Server Example (Extract)</H4>
<PRE>
claim_list News
200 command OK, output follows...
Cuba
SGAJ
seal
IrWh
16Jn
DKfg
OJvn
.
</PRE>
<!-- info:For information on regular expressions, use "help regexp".-->
<!-- Info:For information on keywords, use "help keywords".-->
<P></P>
<H3><A NAME="commands:help">Help</A></H3>
<!-- help:help-->
<P>Returns help information about the specified topic.</P>
<H4>Syntax</H4>
<PRE>
     help topic
</PRE>
<P>where:</P>
<UL>
<LI><I>topic</I>: is a recognised help topic.</LI>
</UL>
<P>Topics include individual FXTP commands and information on FXTP servers, regular expressions etc. "help topics" returns a list of available topics.</P>
<H3><A NAME="commands:list_claims">List_claims</A></H3>
<!-- help:list_claims-->
<P>Returns all claim symbols.</P>
<H4>Syntax</H4>
<PRE>
     list_claims
</PRE>
<H4>Returns</H4>
<P>All claim symbols, including those of proposed or retired claims, each terminated by a newline.</P>
<H3><A NAME="commands:list_keywords">List_keywords</A></H3>
<!-- help:list_keywords-->
<P>Returns all valid keywords (claim categories).</P>
<H4>Syntax</H4>
<PRE>
     list_keywords
</PRE>
<H4>Returns</H4>
<P>All possible claim keywords, each terminated by a newline..</P>
<P></P>
<H3><A NAME="commands:list_uids">List_uids</A></H3>
<!-- help:list_uids-->
<P>Returns the UIDs of all FX users..</P>
<H4>Syntax</H4>
<PRE>
     list_uids
</PRE>
<H4>Returns</H4>
<P>All FX user UIDs, each terminated by a newline..</P>
<P></P>
<H3><A NAME="commands:login">Login</A></H3>
<!-- help:login-->
<P>Registers player's UID and/or password with an email or telnet server session.</P>
<P><B>Note: this is a telnet/email server </B><A HREF="#Telnet and Email Server Extensions">extension</A><B>, not a true FXTP command.</B></P>
<H4>Syntax</H4>
<PRE>
     login [uid],[password]
</PRE>
<H4>Usage</H4>
<P>Once the <I>login</I> command has been used, FXTP commands that require the player's uid and/or password may be abbreviated by leaving out those field values. The commas that delimit the fields must still be included however..</P>
<H4>Telnet/Email Server Example (Extract)</H4>
<P>orders 107,haha,new Foobar S5\@40</P>
<PRE>
login 107,haha
orders ,,del Foobar S5\@40
</PRE>
<!-- info:For information on server extensions, use "help extensions".-->
<P></P>
<H3><A NAME="commands:orders">Orders</A></H3>
<!-- help:orders-->
<P>Places, modifies or deletes claim coupon orders.</P>
<H4>Syntax</H4>
<PRE>
     orders uid,password,order,[order,]...
</PRE>
<P>where each "order" is of the form:</P>
<PRE>
     &lt;new|del|inc|dec&gt; claim [B|S]quantity\@price
</PRE>
<P>and:</P>
<UL>
<LI><I>claim</I>: is a claim symbol</LI>
<LI><I>B</I>: indicates coupons are to be bought (default)</LI>
<LI><I>S</I>: indicates coupons are to be sold.</LI>
<LI><I>quantity</I>: is a number &gt; 0</LI>
<LI><I>price</I>: ranges from 1 to 99.</LI>
</UL>
<H4>Usage</H4>
<P>The <I>new</I> specifier adds a new order to the book. An error is returned if you already have an order at the same price.</P>
<P>The <I>del</I> specifier deletes an existing order. An error is returned if you do not have such an order on the book.</P>
<P>The <I>inc</I> specifier increments the existing order at the specified price by the specified quantity. An error is returned if you do not have an existing order at the specified  price.</P>
<P>The <I>dec</I> specifier decrements the existing order at the specified price by the specified quantity. An error is returned if you do not have an existing order at the specified  price.</P>
<H4>Returns</H4>
<P>English sentences describing the success or failure of the order(s). If successful, the orders may be added to the book or cause transactions to occur (if they match existing orders of the opposite type).</P>
<H4>Connection Server Example</H4>
<PRE>
orders 107,haha,new FooBar B10\@20
200 command OK, output follows...
order 'new FooBar 10\@20' added to book.
.
</PRE>
<H3><A NAME="commands:plot">Plot</A></H3>
<!-- help:plot-->
<P>Plots the price of a claim over a specified time period.</P>
<H4>Syntax</H4>
<PRE>
     plot claim,[start_date],[end_date],&lt;GIF|ASCII&gt;
</PRE>
<P>where:</P>
<UL>
<LI><I>claim</I>: is a claim symbol</LI>
<LI><I>start_date</I>: in form YYYY/MM/DD; default is claim's creation date</LI>
<LI><I>end_date</I>: in form YYYY/MM/DD; default is current date.</LI>
<LI><I>GIF</I>: indicates a GIF plot should be generated.</LI>
<LI><I>ASCII</I>: indicates an ASCII plot should be generated.</LI>
</UL>
<H4>Returns</H4>
<P>If an ASCII plot was requested, it will be returned in the output. If a GIF plot was requested, a URL will be returned.</P>
<H4>Connection Server Example</H4>
<PRE>
plot Foobar,,,GIF
200 command OK, output follows...
http://www.ideosphere.com/ideosphere/fx/plot/foobar.gif
.
</PRE>
<H3><A NAME="commands:profile">Profile</A></H3>
<!-- help:proifile-->
<P>Returns a specified user profile.</P>
<H4>Syntax</H4>
<PRE>
     profile uid,profile_key
</PRE>
<P>where:</P>
<UL>
<LI><I>profile_key</I>: is a number between 0 and 5</LI>
</UL>
<H4>Returns</H4>
<P>The associated <A HREF="#profiles">profile</A>.</P>
<H4>Connection Server Example</H4>
<PRE>
profile 107,1
200 command OK, output follows...
K+Arts &amp; Entertainment:Entertainment Technology K+Arts &amp; Entertainment:Movies
</PRE>
<P>.</P>
<!-- info:For information on profiles, use "help profiles".-->
<P></P>
<H3><A NAME="commands:register">Register</A></H3>
<!-- help:register-->
<P>Registers a new user.</P>
<H4>Syntax</H4>
<PRE>
     register email,nym,privacy
</PRE>
<P>where:</P>
<UL>
<LI><I>email</I>: is the user's email address</LI>
<LI><I>nym</I>: will be the user's "game name"</LI>
<LI><I>privacy</I>: either 0 or 1. If 1 (set) the user's email address will not be visible to other players (though his/her nym will be).</LI>
</UL>
<H4>Returns</H4>
<P>If the email address appears valid, and neither the email address nor nym is in use by another player, an email message is sent containing an initial password. The password can then be used to <A HREF="#commands:activate">activate</A> the account.</P>
<H4>Connection Server Example</H4>
<PRE>
register ken\@ideosphere.com,Killer,0
200 command OK, output follows...
Password has been sent to ken\@ideosphere.com by email.
</PRE>
<P>.</P>
<!-- info:For information on the activate command, use "help activate".-->
<P></P>
<H3><A NAME="commands:resend_id">Resend_id</A></H3>
<!-- help:resend_id-->
<P>Mails the FX UID and password associated with the specified email address to that email address. This is useful for people who have forgotten their passwords..</P>
<H4>Syntax</H4>
<PRE>
     resend_id email
</PRE>
<P>where:</P>
<UL>
<LI><I>email</I>: is the email address of an FX player.</LI>
</UL>
<H4>Returns</H4>
<P>If the email address is associated with an FX account, the UID and password will be mailed to the address.</P>
<H3><A NAME="commands:set_email">Set_email</A></H3>
<!-- help:set_email-->
<P>Changes the email address of a registered user.</P>
<H4>Syntax</H4>
<PRE>
     set_email uid,password,new_email
where:
</PRE>
<UL>
<LI><I>new_email</I>: is the new email address of the user.</LI>
</UL>
<H3><A NAME="commands:set_password">Set_password</A></H3>
<!-- help:set_password-->
<P>Changes the password of a registered user.</P>
<H4>Syntax</H4>
<PRE>
     set_password uid,old_password,new_password
</PRE>
<H3><A NAME="commands:set_profile">Set_profile</A></H3>
<!-- help:set_profile-->
<P>Sets the specified user profile.</P>
<H4>Syntax</H4>
<PRE>
     set_profile uid,password,profile_key,profile
</PRE>
<P>where:</P>
<UL>
<LI><I>profile_key</I>: is a number between 1 and 5</LI>
<LI><I>profile</I>: is the new profile</LI>
</UL>
<H4>Returns</H4>
<P>The associated <A HREF="#profiles">profile</A>.</P>
<p>Note: profile 0 can also be set, but represents the
player's timezeone offset from GMT. As such, its value
is numeric rather than a category string.
<H4>Connection Server Example</H4>
<PRE>
set_profile 107,password,1,K+News:World News
200 command OK, output follows...
Profile 1 set for user 107.
</PRE>
<P>.</P>
<!-- info:For information on profiles, use "help profiles".-->
<P></P>
<H3><A NAME="commands:ticker">Ticker</A></H3>
<!-- help:ticker-->
<P>Returns most recent ticker entries for the specified user or claim for the specified number of days.</P>
<H4>Syntax</H4>
<PRE>
     ticker uid,claim[,days]
</PRE>
<P>where:</P>
<UL>
<LI><I>uid</I>: UID of FX user (omitted if claim is specified)</LI>
<LI><I>claim</I>: claim symbol (omitted if uid is given)</LI>
<LI><I>days</I>: number of days for which ticker entries should be extracted. Default is all relevant entries.</LI>
</UL>
<H4>Returns</H4>
<P>Ticker lines of the form:</P>
<PRE>
     claim quantity price date/time pairs people buyer seller
</PRE>
<P>where:</P>
<UL>
<LI><I>claim</I>: claim symbol</LI>
<LI><I>quantity</I>: quantity of coupons traded</LI>
<LI>price: price of trade</LI>
<LI><I>date/time</I>: time of trade</LI>
<LI><I>pairs</I>: coupon pairs in circulation after the trade people: number of people who hold coupons after the trade.</LI>
<LI><I>buyer</I>: UID of buyer</LI>
<LI><I>seller</I>: UID of seller</LI>
</UL>
<P>All items are separated by tab characters.</P>
<H4>Connection Server Example</H4>
<P>The following would retrieve the ticker entries for claim "BC96" that have occurred within the last day:</P>
<PRE>
ticker ,BC96,1
200 command OK, output follows...
BC96  100  88  1996/09/25 14:04:36  5034  51  162  305
BC96  106  88  1996/09/25 14:04:36  5034  51  199  305
BC96  1  89  1996/09/25 14:02:53  5034  52  286  305
.
</PRE>
<H3><A NAME="commands:time">Time</A></H3>
<!-- help:time-->
<P>Returns the current FX server time (GMT).</P>
<H4>Syntax</H4>
<PRE>
     time
</PRE>
<H4>Returns</H4>
<P>The FX server time (GMT), in format YYYY/MM/DD HH:MM:SS</P>
<H3><A NAME="commands:user_info">User_info</A></H3>
<!-- help:user_info-->
<P>Returns information about the specified user</P>
<H4>Syntax</H4>
<PRE>
     user_info uid,attribute,attribute...]

</PRE>
<P>where legal attributes are: nym, email, privacy, cash, networth, score, fees_in, fees_out, holdings, book, gid, allowance, date_signup, date_last_on</P>
<H4>Returns</H4>
<P>Attribute values are returned in the order the attributes were specified; each value is terminated by a newline character. Note that some attributes may not have values; in such case, only a newline character is returned..</P>
<UL>
<LI><I>allowance</I>:<I> </I>total credibills user has received from allowance payments.</LI>
<LI><I>book:</I> returns user's booked orders separated by commas Booked orders are all of the form <I>uid symbol order</I> (e.g., 107 BC96 B10\@85).</LI>
<LI><I>cash: </I>user's cash balance.</LI>
<LI><I>date_last_on: </I>date user last performed an operation that required his/her password. In format YYYY/MM/DD</LI>
<LI><I>date_signup: </I>in format YYYY/MM/DD</LI>
<LI><I>email:</I> user's email address; only available if <I>privacy </I>is set to 0..</LI>
<LI><I>fees_in</I>: income from other than trading profits and allowance (e.g., claim judging fee).</LI>
<LI><I>fees_out</I>: credibills expended other than in trading (e.g., claim creation).</LI>
<LI><I>gid</I>: currently unused.</LI>
<LI><I>holdings</I>: in form <I>claim:coupons</I> separated by tab characters.</LI>
<LI><I>networth</I>: consists of cash balance and current value of holdings.</LI>
<LI><I>nym: </I>user's "game name".</LI>
<LI><I>privacy:</I> flag, either 0 (or blank) or 1.</LI>
<LI><I>score: </I>indicator of user's trading performance. Higher values are better.</LI>
</UL>
<P></P>
<H4>Connection Server Example</H4>
<PRE>
user_info 107,email,cash,score,holdings
200 command OK, output follows...
Ken\@lucifer.com
 883.01
0.963
\$vIF:1  Immo:50 Cuba:50 Ches:20 BC96:-100       APPL:10 TWAC:50
.
</PRE>
<H3><A NAME="commands:volume">Volume</A></H3>
<!-- help:volume-->
<P>Returns the number of coupons traded within the most recent N days, where N is specified by the command argument. Trading volume is summarised by claim.</P>
<H4>Syntax</H4>
<PRE>
     volume [days]
</PRE>
<P>where:</P>
<UL>
<LI><I>days</I>: number of (most recent) days for which trading volume is to computed. Default is 14.</LI>
</UL>
<H4>Returns</H4>
<P>For each claim that had activity during the requested time period, its symbol and number of coupons traded, separated by a space character and terminated by a newline character.</P>
<H4>Connection Server Example</H4>
<PRE>
volume 1
200 command OK, output follows...
TWAC 343
BC96 531
Ms.P 81
CLan 133
Cash 50
Ches 66
DLan 1
.
</PRE>
<H2><A NAME="HD_NM_16">Other Topics</A></H2>
<H3><A NAME="keywords">Keywords</A></H3>
<!-- help:keywords-->
<P>Keywords (also knows as categories) are used to categorise FX claims. Each keyword describes a category (e.g., "Science &amp; Technology:Space", "News:World News"), and each claim is associated with one or more keywords. Classifying claims by keywords helps users zero in on the types of claims that interest them; in particular, they can set up <A HREF="#profiles">profiles</A> containing specific keywords.</P>
<P>Commands that use or manipulate keywords are:</P>
<UL>
<LI><A HREF="#commands:account">account</A>: may take a keyword as its second argument</LI>
<LI><A HREF="#commands:claim_list">claim_list</A>: lists the claims associated with a particular keyword</LI>
<LI><A HREF="#commands:list_keywords">list_keyword</A>: lists possible keywords</LI>
<LI><A HREF="#commands:set_profile">set_profile</A>: sets a user profile</LI>
</UL>
<!-- info:For information on a command, use "help command".-->
<!-- info:For information on profiles, use "help profiles".-->
<P></P>
<H3><A NAME="profiles">Profiles</A></H3>
<!-- help:profiles-->
<P>Profiles allow users to select claims or categories of claims that they are interested in. Once defined, a profile can be used with the <A HREF="#commands:account">account</A> command.</P>
<P>Profiles are specified by numeric <I>keys;</I> the following keys are supported:</P>
<UL>
<LI>-1: claims user has booked orders on</LI>
<LI>-2: claims user has holdings in</LI>
<LI>-3: claims for which user has holdings or booked orders</LI>
<LI> 0: user information (currently, only contains timezone offset from GMT).</LI>
<LI>1 to 5: user-defined.</LI>
</UL>
<H4>User-Defined Profiles</H4>
<P>Profile keys 1 through 5 may be defined by the user via the <A HREF="#commands:set_profile">set_profile</A> command, which takes a key as its first argument and a value as its second argument. Profile values consist of tab-separated items of the form:</P>
<PRE>
     K+keyword
     K-keyword
     C+claim
     C-claim
</PRE>
<P>where:</P>
<UL>
<LI><I>K+keyword</I>: will select the claims associated with the specified <A HREF="#keywords">keyword</A></LI>
<LI><I>K-keyword:</I> will omit the claims associated with the specified <A HREF="#keywords">keyword</A>.</LI>
<LI><I>C+claim: </I> will select the claim with the specified symbol</LI>
<LI><I>C-claim:</I> will omit the claim with the specified symbol.</LI>
</UL>
<P>Any number of such items can be specified in a profile.</P>
<!-- info:For information on a particular FXTP command, use "help command"-->
<!-- info:For information on keywords, use "help keywords-->
<P></P>
<H3><A NAME="regexp">Regular Expressions</A></H3>
<!-- help:regexp-->
<P>Certain FXTP commands take <A HREF="http://www.perl.com/perl/index.html">Perl</A> regular expressions for one or more of their arguments. A complete discussion of such expressions is beyond the scope of this document, but some of their features are:</P>
<UL>
<LI>the regular expression "abc" will match strings such as "abc"<I>, </I>"12abcde"<I>, </I>etc. This is the most common use of regular expressions in FX. For example, "News" used as a keyword regular expression would match both "News:US News" and "News:World News".</LI>
<LI>the '^' character can be used to anchor matches to the beginnings of strings. For example, "^abc" would match "abcde" but not "12abc".</LI>
<LI>the '\$' character can be used to anchor matches to the ends of strings.</LI>
<LI>'.' matches any character in the string.</LI>
<LI>'*' matches 0 or more occurrences of the previous character.</LI>
<LI>other special characters include '/', '|' '+' and '?'.</LI>
<LI>'\\' can be used to remove the special meaning of a character. For example, "\\^abc" will match "12^abc".</LI>
</UL>
<P>Claim symbols or <A HREF="#keywords">keywords</A> containing characters such as '*' or '^' must be handled carefully. For example, since <A HREF="#commands:claim_info">claim_info</A> takes a regular expression as its first argument, special characters in claim symbols such as "\$vIF" must be protected with '\' characters:</P>
<PRE>
     claim_info \\\$vIF,short
</PRE>
<P>Commands that use regular expressions are:</P>
<UL>
<LI><A HREF="#commands:account">account</A>: second argument can be keyword regular expression</LI>
<LI><A HREF="#commands:claim_info">claim_info</A><I>:</I> first argument is claim symbol regular expression.</LI>
<LI><A HREF="#commands:claim_list">claim_list</A>: first argument is keyword regular expression.</LI>
</UL>
<P></P>
<!-- Info:For help on a particular command, use "help command".-->
<!-- help:end-->
<P></P>
<I>This page is maintained by <A HREF="http://www.ideosphere.com">Ken Kittlitz</A> (kittlitz AT ideosphere DOT com). Last modified on 11/09/2003.</I>
<P>
</P>
EOT
push(@content,$data);
&showHtml(8,$title,$header,undef,undef,@content);