Updated: July 20, 2003
Whenever an user need any information, he/she can use functions which are in the below Function Summary table.
In order to write a new strategy, do first
1) Change structure Strategy
in Strategy.h so that it can hold parameters which are necessary for your
new strategy.
2) Change Strategy_init()
so that the function can set initial values of parameters for your strategy.
3) Change specifyStrategy()
so that it can properly process commandline arguments.
4) Modify printStrategy().
Then you can write your strategy in updateAgentOrder.
Contains information about a client who is connected to pxs, which includes present value, shares, cash, agent number, etc.
Contains basic information about current market(pxs), which includes currnet market price, volume, the number of orders, etc..
Contains some statistical information for traders, which
includes quartile values, etc. There may be 2 different MarketStatistics.
One is computed based on ISLAND queues, the other is computed based on pxs(simulator)
queues.
Contains parameters for an user's own strategy.
This summarizes all functions which users can call or whose content users should
provide.
int  getAgentNumber
(ClientState
*cState)
Returns agent number of this agent. 
float  getIslLastPrice
(MarketState
*mState)
Returns current Island market price. 
float  getSimLastPrice
(MarketState
*mState)
Returns current Simulator market price. 
float  getVolume
(MarketState
*mState)
Returns how many shares have been traded since the market opens today. 
int  getOrders
(MarketState
*mState)
Returns how many orders have been placed since the market opens today. 
float  getBuyQuartile
(MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in buy side queue. 
float  getSellQuartile
(MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in sell side queue. 
float  getIslandBuyQuartile
(MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in buy side queue. 
float  getIslandSellQuartile
(MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in sell side queue. 
int  getTotalBuyVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in buy queue . 
int  getTotalSellVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in sell queue. 
int  getTotalVolume
(MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in both buy and sell queues. 
int  getMatchBuyVolumeOfAllAgents
(MarketState
*mState)
Returns how many volumes of buy orders placed by all agents matched. 
int  getMatchSellVolumeOfAllAgents
(MarketState
*mState)
Returns how many volumes of sell orders placed by all agents matched. 
int  getTotalMatchVolumeOfAllAgents
(MatketState
*mState)
Returns how many volumes placed by all agents matched. 
float  MarketStatistics_getWeightedMarketAverage (const
MatketState
*mState, MarketStatistics
*stat)
Returns the weighted market average price for the corresponding market statistics of the current market. 
int  getCurrentShare
(ClientState
*cState)
Returns how many shares this agent holds currently. Negative shares are allowed. 
float  getCurrentCash
(ClientState
*cState)
Returns cash amount which this agent holds currently. Negative cash is allowed. 
float  getIslPresentValue
(ClientState
*cState)
Returns Island present value(i.e. profit and loss) of fund which this agent manages. 
float  getSimPresentValue
(ClientState
*cState)
Returns Simulator present value(i.e. profit and loss) of fund which this agent manages. 
int  updateAgentOrder
(ClientState
*cState, MarketState
*mState, MarketStatistics
*pxsStat, MarketStatistics
*iStat, Strategy
*myStrategy)
Is the function where users should put their own strategies. 
int  getNumOfElementsInBuyQueue
(MarketState
*mState)
Returns how many orders exists in buy side queue. 
int  getNumOfElementsInSellQueue
(MarketState
*mState)
Returns how many orders exist in sell side queue. 
float *  getOrderPricesInBuyQueue
(int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in buy side queue. 
float *  getOrderPricesInSellQueue
(int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in sell side queue. 
int *  getOrderSharesInBuyQueue
(int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in buy side queue. 
int *  getOrderSharesInSellQueue
(int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in sell side queue. 
int  buyOrder
(float price, int share, ClientState
*cState, MarketState
*mState)
Places a buy order. 
int  sellOrder
(float price, int share, ClientState
*cState, MarketState
*mState)
Places a sell order. 
int  withdraw
(int type, int ref_no, ClientState
*cState, MarketState
*mState)
Request withdrawal of an order. 
simTime_t  simTime (const MarketState
*mState, simTime_t *t)
Returns the value of simulator time in seconds since "midnight". 
double  simDiffTime
(simTime_t time1, simTime_t time0)
Returns the number of seconds elapsed between time time1 and time time0. 
int *  getRefNosOfMyBuyOrders
(ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference number of buy orders of this agent. 
int *  getRefNosOfMySellOrders
(ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference number of sell orders of this agent. 
float  getPriceOfThisBuyOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this buy order. 
float  getPriceOfThisSellOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this sell order. 
int  getShareOfThisBuyOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this buy order. 
int  getShareOfThisSellOrder
(int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this sell order. 
int  getNumOfMyBuyOrders
(ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in buy queue. 
int  getNumOfMySellOrders
(ClientState
*cState, MarketState
*mState)
Returns the number of orders ot this agent in sell queue. 
void  specifyStrategy
(int argc, char **argv, Strategy
*myStrategy)
Sets parameters for user's strategy by processing commandline arguments. 
void  Strategy_init
(Strategy
*myStrategy)
Initialize parameters for user's strategy. 
void  printUsage
(void)
Prints usage. If an user made any change in structure Strategy, it should be modified so that it can print correct usage. 
void  printStrategy
(Strategy
*myStrategy)
Prints summarized strategy before mytrader starts running. 
int getAgentNumber (ClientState
*cState)
Returns agent number of this agent.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
agent number of this agent.
float getIslLastPrice (MarketState
*mState)
Returns current Island market price.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current Island market price.
float getSimLastPrice (MarketState
*mState)
Returns current Simulator market price.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current Simulator market price.
float getVolume (MarketState
*mState)
Returns how many shares have been traded since the market opens today.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
current market volume.
int getOrders (MarketState
*mState)
Returns how many orders have been placed since the market opens today.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders placed today.
float getBuyQuartile (MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in buy side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat  pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
index  1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), or 4(for
100% quartile).
Returns:
a buy quartile value of real and virtual orders.
float getSellQuartile (MarketState
*mState, MarketStatistics
*pxsStat, int index)
Returns a quartile value which is computed over all orders in sell side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat  pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
index  1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a sell quartile value of real and virtual orders.
float getIslandBuyQuartile (MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in buy side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
iStat  pointer to MarketStatistics
which is passed as 4th argument of updateAgentOrder.
index  1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a buy quartile value of real orders.
float getIslandSellQuartile (MarketState
*mState, MarketStatistics
*iStat, int index)
Returns the specified quartile value for only REAL orders in sell side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
iStat  pointer to MarketStatistics
which is passed as 4th argument of updateAgentOrder.
index  1(for 25% quartile), 2(for 50% quartile), 3(for 75% quartile), 4(for
100% quartile).
Returns:
a buy quartile value of real orders.
int getTotalBuyVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in buy queue.
Parameters:
mState
 pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat  pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in buy queue.
int getTotalSellVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in sell queue.
Parameters:
mState
 pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat  pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in sell queue.
int getTotalVolume (MarketState
*mState, MarketStatistics
*pxsStat)
Returns total volume of all orders in both buy and sell queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
pxsStat  pointer to MarketStatistics
which is passed as 3rd argument of updateAgentOrder.
Returns:
total volume of all orders in both buy and sell queue.
int getMatchBuyVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of buy orders placed by all agents matched.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of buy side shares which were placed by all agents and matched.
int getMatchSellVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of sell orders placed by all agents matched.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of sell side shares which were placed by all agents and matched.
int getTotalMatchVolumeOfAllAgents (MarketState
*mState)
Returns how many shares of all orders placed by all agents matched.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of all shares which were placed by all agents and matched.
int MarketStatistics_getWeightedMarketAverage (const MatketState
*mState, MarketStatistics
*stat)
Returns the weighted market average price for the corresponding market statistics of the current market.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
stat  pointer to MarketStatistics which is either the 3rd or the 4th argument of updateAgentOrder. The value will be computed based on the PXS queues if the 3rd argument of updateAgentOrder is passed, or based on the Island queues if the 4th argument of updateAgentOrder is passed.
Returns:
the weighted market
average price for the corresponding market statistics of the current market.
int getCurrentShare (ClientState
*cState)
Returns how many shares this agent holds currently. Return value may be negative.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
the number of current holding shares of this agent.
float getCurrentCash (ClientState
*cState)
Returns cash amount which this agent holds currently. Return value maybe negative.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
cash amount which this agent holds.
float getIslPresentValue (ClientState
*cState)
Returns Island present value of fund which this agent manages. The value is calculated based on the Island last price.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
present Island value of the fund which this agent manages.
float getSimPresentValue (ClientState
*cState)
Returns Simulator present value of fund which this agent manages. The value is calculated based on the Simulator last price.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
Returns:
present Simulator value of the fund which this agent manages.
int updateAgentOrder (ClientState
*cState, MarketState
*mState, MarketStatistics
*pxsStat, MarketStatistics
*iStat, Strategy
*myStrategy)
Is the function where users should put their own strategies.
Parameters:
cState  pointer to ClientState
which contains information about this agent.
mState  pointer to MarketState
which contains basic information about current market(on pxs).
pxsStat  pointer to MarketStatistics
which contains statistical information computed from pxs order book.
iState  pointer to MarketStatistics
which contains statistical information computed from ISLAND order book.
myStrategy  pointer to Strategy
which conatains parameters for user's strategy.
Returns:
1 if any order is placed, otherwise 0.
int getNumOfElementsInBuyQueue (MarketState
*mState)
Returns how many orders exists in buy side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders in current buy queue.
int getNumOfElementsInSellQueue (MarketState
*mState)
Returns how many orders exists in sell side queue.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders in current sell queue.
float *getOrderPricesInBuyQueue (int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in buy side queue.
Parameters:
number  the number of order prices a user wants to get from the top of the buy
queue. This cannot be greater than the return value of getNumOfElementsInBuyQueue.
If the return value of getNumOfElementsInBuyQueue
is used for number, the return value of this function can access prices of all
orders in the buy queue.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains price information of each order in buy side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
float *p_arr;
:
p_arr = getOrderPricesInBuyQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
float *getOrderPricesInSellQueue (int number, MarketState
*mState)
Returns pointer to array which contains price information of each order in sell side queue.
Parameters:
number  the number of order prices a user wants to get from the top of the
sell queue. This cannot be greater than the return value of getNumOfElementsInSellQueue.
If the return value of getNumOfElementsInSellQueue
is used for number, the return value of this function can access prices of all
orders in the sell queue.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains price information of each order in sell side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
float *p_arr;
:
p_arr = getOrderPricesInSellQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getOrderSharesInBuyQueue (int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in buy side queue.
Parameters:
number  the number of order shares an user wants to get from the top of the buy
queue. This cannot be greater than the return value of getNumOfElementsInBuyQueue.
If the return value of getNumOfElementsInBuyQueue
is used for number, the return value of this function can access shares of all
orders in the buy queue.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains share information of each order in buy side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getOrderSharesInBuyQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getOrderSharesInSellQueue (int number, MarketState
*mState)
Returns pointer to array which contains share information of each order in sell side queue.
Parameters:
number  the number of order shares an user wants to get from the top of the
sell queue. This cannot be greater than the return value of getNumOfElementsInSellQueue.
If the return value of getNumOfElementsInSellQueue
is used for number, the return value of this function can access shares of all
orders in the sell queue.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains share information of each order in sell side
queue.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getOrderSharesInSellQueue
(number, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int buyOrder (float price, int share, ClientState
*cState, MarketState
*mState)
Places a buy order.
Parameters:
price  price at which an user wants to buy.
share  share amount an user wants to buy.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
reference number of this order.
int sellOrder (float price, int share, ClientState
*cState, MarketState
*mState)
Places a sell order.
Parameters:
price  price at which an user wants to sell.
share  share amount an user wants to sell.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
reference number of this order.
int withdraw (int type, int ref_no, ClientState
*cState, MarketState
*mState)
Request withdrawal of an order.
If the owner of the order isn't identical to the person who requests this
withdrawal, or the order doesn't exist in proper queue, it will
be rejected. And even though
the requeust is accepted, it means just it'll be processed. Note that
partial cancellation of an order is not allowed yet.
Parameters:
type  should be "BUY" or "SELL"
ref_no  reference number of the order which the agent wants to withdraw.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
1 if the request is accepted. It may be rejected later.
0 if the request is rejected.
simTime_t simTime (const MarketState
*mState, simTime_t *t)
Returns the time in seconds since "midnight," where "midnight" is defined relative to the simulator execution. If t is nonNULL, the return value is also stored in the memory pointed to by t. "simTime.h" needs to be included for using this function.
Parameters:
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
t  if nonNULL, the return value is also stored in the memory pointed to by this pointer.
Returns:
the value of simulator time in seconds since "midnight".
double simDiffTime (simTime_t time1, simTime_t time0)
Returns the number of seconds elapsed between time time1 and time time0. "simTime.h" needs to be included for using this function.
Parameters:
time1  later timestamp.
time0  earlier timestamp.
Returns:
the number of seconds elapsed between time time1 and time time0.
int *getRefNosOfMyBuyOrders (ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference numbers of buy orders of this agent.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains reference numbers of buy orders of this
agent.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getRefNosOfMyBuyOrders
(cState, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
int *getRefNosOfMySellOrders (ClientState
*cState, MarketState
*mState)
Returns pointer to array which contains reference numbers of sell orders of this agent.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
pointer to array which contains reference number of sell orders of this
agent.
Warning:
If an user calls this function, he/she MUST call a function free in order to
free memory in updateAgentOrder
or another subroutine.
Usage for free should be as follows.
int *p_arr;
:
p_arr = getRefNosOfMySellOrders
(cState, mState);
:
free (p_arr); // p_arr MUST be the initial value (the return value of this
function)
float getPriceOfThisBuyOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this buy order.
Parameters:
ref_no  reference number of the order which this agent wants to get its price.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the price of this buy order.
float getPriceOfThisSellOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the price of this sell order.
Parameters:
ref_no  reference number of the order which this agent wants to get its price.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the price of this sell order.
int getShareOfThisBuyOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this buy order.
Parameters:
ref_no  reference number of the order which this agent wants to get its price.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the share of this buy order.
int getShareOfThisSellOrder (int ref_no, ClientState
*cState, MarketState
*mState)
Returns the share of this sell order.
Parameters:
ref_no  reference number of the order which this agent wants to get its price.
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the share of this sell order.
int getNumOfMyBuyOrders (ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in buy queue.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders of this agent in buy queue.
int getNumOfMySellOrders (ClientState
*cState, MarketState
*mState)
Returns the number of orders of this agent in sell queue.
Parameters:
cState  pointer to ClientState
which is passed as 1st argument of updateAgentOrder.
mState  pointer to MarketState
which is passed as 2nd argument of updateAgentOrder.
Returns:
the number of orders of this agent in sell queue.
void specifyStrategy (int argc, char **argv, Strategy
*myStrategy)
Sets parameters for user's strategy by processing commandline arguments.
Parameters:
argc  the number of commandline arguments.
argv  poiter to pointer to commandline arguments.
myStrategy  pointer to Strategy
which is passed as 5th argument of updateAgentOrder.
void Strategy_init (Strategy
*myStrategy)
Initialize parameter for user's strategy.
Parameters:
myStrategy  pointer to Strategy
which is passed as 5th argument of updateAgentOrder.
void printUsage (void)
Prints usage of mytrader program
which an user makes changes corresponding to his/her strategy.
Prints summarized strategy before
mytrader starts running.
This summarizes all deprecated functions which appear in the previous
versions of API. They are kept for backwards compatibility. Users are highly
recommended to use their corresponding updated version.


float  getLastPrice (MarketState
*mState)
Returns current Island market price. Replaced by getIslLastPrice (MarketState *mState). 
float  getPresentValue
(ClientState
*cState)
Returns Island present value(i.e. profit and loss) of fund which this agent manages. Replaced by getIslPresentValue (ClientState *cState). 