A real-time component interface is available for PC-SPAN version 4. With this additional software module, you can develop programs which interface to PC-SPAN in real-time.
For example, suppose a customer requests an order. Using the component interface, your program can call PC-SPAN, specify the updated position that will result from the order, request that the performance bond be calculated, and receive back the updated performance bond requirement -- all with extremely rapid execution times.
The SPAN Risk Manager software also has a real-time component interface. With this software module, in addition to everything you can do with the component interface to PC-SPAN, you can develop programs which execute the functions of the SPAN Risk Manager in real-time.
For example, you could programmatically update market prices for futures and physicals, and then recalculate volatilities, theoretical prices and risk arrays, with extremely fast.
This document provides a technical reference to the real-time component interfaces for PC-SPAN and for the SPAN Risk Manager.
Below is an example of calling the component interface from Visual C++ code.
#include <stdio.h>
int main(int argc, char* argv[])
{
if(FAILED(::CoInitialize(NULL))) return 1;
ISpanCom* pSpanCom;
if(SUCCEEDED(::CoCreateInstance(CLSID_SpanCom, NULL, CLSCTX_LOCAL_SERVER,
__uuidof(ISpanCom), (LPVOID*)
&pSpanCom)))
{
printf( "Success\n");
// pSpanCom->Load("C:\\cme0216s.par",1,0);
pSpanCom->Release();
}
else printf("Fail\n");
::CoUninitialize();
return 0;
}
short Load(BSTR fileName, boolean replaceExc, boolean useExtLayout);
Loads into the PC-SPAN any file, specified by fileName. replaceExc parameter specifies whether PC-SPAN should replace already loaded exchange complexes with the ones from the file (true) or leave them intact (false). All position files (*.txt and .pos) require corresponding risk parameter files to be already loaded. Positions are loaded into the currently selected point in time. If point in time is not selected positions are loaded into the point in time specified in the position file. If this point in time is not present positions are loaded into the first available point in time. useExtLayout parameter specifies whether PC-SPAN should use extended file layout when loading positions. It is only used for loading old format position files (*.txt). Return value can be 0 (success) or non-zero (failure).
short Save(BSTR fileName);
Saves all the information from PC-SPAN into the file, specified by fileName. Information is saved in the XML format. Return value can be 0 (success) or non-zero (failure).
short SelectPIT(BSTR busDate, short isSettle, short isFinal, BSTR busTime, BSTR description);
Selects specified point in time as current. busDate has following format: YYYYMMDD. isSettle and isFinal can have following values:
-1– ignore
0– false
1– true.
busTime has format: HHMM. If busDate is empty the rest of the parameters are ignored and first available point in time is selected. If either isSettle or isFinal is set to –1 this parameter and all parameters following it are ignored. If busTime or description is empty it is ignored. Return value can be 0 (success) or non-zero (failure).
short SelectPortfolio(BSTR firmCode, BSTR acctCode, BSTR segType);
Selects specified portfolio as current. This method searches for the specified portfolio in the currently selected point in time. If point in time is not selected it fails. If firmCode is empty the rest of the parameters are ignored and first available portfolio is selected. If either acctCode or segType is empty this parameter and all parameters following it are ignored. Return value can be 0 (success) or non-zero (failure).
void ResetPIT();
Sets currently selected point in time to NULL (removes selection). Also resets portfolio selection.
void ResetPortfolio();
Sets currently selected portfolio to NULL (removes selection).
short Calculate();
Performs SPAN requirements calculations for the currently selected object. If portfolio selection is not NULL it does calculations only for the selected portfolio. If it is NULL and point in time selection is not NULL it does calculations for all portfolios in the selected point in time. If both selected portfolio and selected point in time are NULL it does calculations for all points in time and portfolios loaded into PC-SPAN. Return value can be 0 (success) or non-zero (failure).
double GetPortfLongFutValue();
Returns long futures value calculated for the selected portfolio. If portfolio is not selected (NULL) it returns 0.
double GetPortfShortFutValue();
Returns short futures value calculated for the selected portfolio. If portfolio is not selected (NULL) it returns 0.
double GetPortfLongOptValue();
Returns long options value calculated for the selected portfolio. If portfolio is not selected (NULL) it returns 0.
double GetPortfShortOptValue();
Returns short options value calculated for the selected portfolio. If portfolio is not selected (NULL) it returns 0.
double GetPortfSpanReq(short pbClass, boolean isInitial);
Returns SPAN requirement calculated for the selected portfolio. pbClass can be 1(CORE) or 2(RESERVE). isInitial indicates maintenance or initial requirement. If portfolio is not selected (NULL) it returns 0.
double GetPortfTotalReq(short pbClass, boolean isInitial);
Returns SPAN requirement calculated for the selected portfolio. pbClass can be 1(CORE) or 2(RESERVE). isInitial indicates maintenance or initial requirement. If portfolio is not selected (NULL) it returns 0.
void Delete();
Deletes currently selected object from PC-SPAN. If portfolio selection is not NULL it deletes only the selected portfolio. If it is NULL and point in time selection is not NULL it deletes selected point in time. If both selected portfolio and selected point in time are NULL whole contents of the PC-SPAN is deleted.
void SetLogLevel(short processId, short priorityId);
Use this method to specify logging level for PC-SPAN. processLimit - upper limit for process id of the log message source. priorityLimit - lower limit for the log message priority. Possible values for parameters are:
For processId:
PROC_ID_LOAD_RISK = 10;
PROC_ID_LOAD_POS = 20;
PROC_ID_LOAD_XML = 30;
PROC_ID_OMNIBUS = 40;
PROC_ID_CALC_START = 51;
PROC_ID_CALC_PBOND = 60;
PROC_ID_CALC_SPREAD = 70;
PROC_ID_CALC_LIQ_RISK = 80;
PROC_ID_CALC_DETAIL_START = 101;
PROC_ID_CALC_SPREAD_DETAIL = 110;
PROC_ID_CALC_LIQ_RISK_DETAIL = 120;
PROC_ID_CALC_POS_DETAIL = 130;
PROC_ID_UPPER = -1;
For priorityId:
PRIORITY_ID_LOW = -1;
PRIORITY_ID_NORMAL = 10;
PRIORITY_ID_WARNING = 20;
PRIORITY_ID_ERROR = 30;
Default values are 0 and 30 (only errors are logged).
void LogSave(BSTR fileName);
Saves PC-SPAN log into the file specified by fileName.
short CreatePortfolio(BSTR firmCode, BSTR acctCode, BSTR segType);
Creates a new portfolio with specified parameters in the selected point in time and selects it as current. Fails if point in time is not selected. If portfolio with given parameters already exist selects the existing portfolio as current (does not create a duplicate one). If segType is empty “N/A” segment type is assumed. Returns 0 (success) or non-zero (failure).
short SetPortfAcctType(BSTR acctType, boolean isClearing);
Sets account type for the selected portfolio. If portfolio is not selected – fails. If method does not find specified account type in the organization master database it also fails. If selected portfolio already has some positions defined method fails. Following values are currently defined for the acctType:
N - normal
M - member
H - hedge
S - speculator
O - omnibus (speculator)
Q - omnibus (hedge).
isClearing specifies whether account is customer or clearing. Returns 0 (success) or non-zero (failure).
short SetPortfParent(BSTR firmCode, BSTR acctCode, BSTR segType);
Sets parent portfolio for the selected portfolio. Used only for omnibus accounts. Only omnibus account can be a parent of another portfolio. Only one level of parents is supported. Fails if portfolio is not selected, parent portfolio can not be found or omnibus rules are violated. Returns 0 (success) or non-zero (failure).
short SetPortfCurrency(BSTR currencyCode);
Sets currency for the selected portfolio. currencyCode is a three-letter ISO code for the currency (USD, EUR, GBP etc.). Fails if portfolio is not selected or currency is not defined in the organization master database. Returns 0 (success) or non-zero (failure).
BSTR GetPortfCurrency();
Returns a three-letter ISO code for the currency of the selected portfolio. If portfolio is not selected or currency for it is not specified method returns an empty string.
short SetPortfLedgerBalance(double value);
Sets ledger balance for the selected portfolio. Fails if portfolio is not selected. Returns 0 (success) or non-zero (failure).
double GetPortfLedgerBalance();
Returns ledger balance for the selected portfolio. If portfolio is not selected returns 0.
short SetPortfOpenTradeEquity(double value);
Sets open trade equity for the selected portfolio. Fails if portfolio is not selected. Returns 0 (success) or non-zero (failure).
double GetPortfOpenTradeEquity();
Returns open trade equity for the selected portfolio. If portfolio is not selected returns 0.
short SetPortfSecurityOnDeposit(double value);
Sets security on deposit for the selected portfolio. Fails if portfolio is not selected. Returns 0 (success) or non-zero (failure).
double GetPortfSecurityOnDeposit();
Returns security on deposit for the selected portfolio. If portfolio is not selected returns 0.
short SetPortfPosition(BSTR exchCmplxAcro, BSTR exchAcro, BSTR pfCode, short pfType, BSTR futPeriod, BSTR optPeriod, boolean isPut, double strike, long totalLong, long totalShort, long intraLong, long intraShort, long interLong, long interShort);
Sets positions in the selected portfolio in the specified contract. If portfolio is not selected or contract can not be found method fails. Parameters:
exchCmplxAcro - exchange complex acronym (“CME”, “BOTCC”)
exchAcro - exchange acronym (“CME”, “CBT”)
pfCode - product family code (“SP”, “BP”)
pfType - product family type:
1 - physical
2 - debt
3 - stock
11 - future
12 - equivalence debt
21 - option on physical
22 - option on future
23 - option on equity
31 - combination
41 - option on combination
futPeriod - period code for future contract (period code for the underlying contract for options). Format is usually YYYYMM, there are special cases like weeklies and flexes when some characters are added to this format (for example “200002W3”). For physicals, equity and options on physicals/equity this parameter should be set to “000000”.
optPeriod - period code for option contract. This parameter and following contract identification parameters are ignored for non-option contracts. Same format as futPeriod.
isPut - put/call flag for options. True means put.
strike - strike price for options.
totalLong - new value for total long positions. If portfolio is net based this value will be used for calculating net positions (Net = totalLong – totalShort)
totalShort - new value for total short positions. If portfolio is net based this value will be used for calculating net positions (Net = totalLong – totalShort)
intraLong - new value for intra long positions. If portfolio is net based this value is ignored. It is used for calculating number of naked positions (NakedLong = totalLong – intraLong - interLong)
intraShort - new value for intra short positions. If portfolio is net based this value is ignored. It is used for calculating number of naked positions (NakedShort = totalShort – intraShort - interShort)
interLong - new value for inter long positions. If portfolio is net based this value is ignored. It is used for calculating number of naked positions (NakedLong = totalLong – intraLong - interLong)
interShort - new value for inter short positions. If portfolio is net based this value is ignored. It is used for calculating number of naked positions (NakedShort = totalShort – intraShort - interShort)
If number of positions specified is inconsistent totalLong < intraLong + intraShort or totalShort < intraShort + interShort method fails. Returns 0 (success) or non-zero (failure).
short ChangePortfPosition(BSTR exchCmplxAcro, BSTR exchAcro, BSTR pfCode, short pfType, BSTR futPeriod, BSTR optPeriod, boolean isPut, double strike, long totalLong, long totalShort, long intraLong, long intraShort, long interLong, long interShort);
Modifies positions in the selected portfolio in the specified contract. If portfolio is not selected or contract can not be found method fails. Parameters:
exchCmplxAcro - exchange complex acronym (“CME”, “BOTCC”)
exchAcro - exchange acronym (“CME”, “CBT”)
pfCode - product family code (“SP”, “BP”)
pfType - product family type:
1 - physical
2 - debt
3 - stock
11 - future
12 - equivalence debt
21 - option on physical
22 - option on future
23 - option on equity
31 - combination
41 - option on combination
futPeriod - period code for future contract (period code for the underlying contract for options). Format is usually YYYYMM, there are special cases like weeklies and flexes when some characters are added to this format (for example “200002W3”). For physicals, equity and options on physicals/equity this parameter should be set to “000000”.
optPeriod - period code for option contract. This parameter and following contract identification parameters are ignored for non-option contracts. Same format as futPeriod.
isPut - put/call flag for options. True means put.
strike - strike price for options.
totalLong - change in total long positions. If portfolio is net based this value will be used for calculating change in net positions (NetChange = totalLong – totalShort)
totalShort - change in total short positions. If portfolio is net based this value will be used for calculating change in net positions (NetChange = totalLong – totalShort)
intraLong - change in intra long positions. If portfolio is net based this value is ignored. It is used for calculating change in number of naked positions (NakedLongChange = totalLong – intraLong - interLong)
intraShort - change in intra short positions. If portfolio is net based this value is ignored. It is used for calculating change in number of naked positions (NakedShortChange = totalShort – intraShort - interShort)
interLong - change in inter long positions. If portfolio is net based this value is ignored. It is used for calculating change in number of naked positions (NakedLongChange = totalLong – intraLong - interLong)
interShort - change in inter short positions. If portfolio is net based this value is ignored. It is used for calculating change in number of naked positions (NakedShortChange = totalShort – intraShort - interShort)
If number of positions specified is inconsistent totalLong < intraLong + intraShort or totalShort < intraShort + interShort method fails. Returns 0 (success) or non-zero (failure).
short SavePositions(BSTR fileName);
Saves positions for the selected object into the file, specified by fileName. If selected portfolio is not NULL saves only positions for selected portfolio. If selected portfolio is NULL, but selected point in time is not saves positions for all portfolios in the selected point in time. If both selected portfolio and selected point in time are NULL method fails. Returns 0 (success) or non-zero (failure).
short SelectExchangeComplex(BSTR excAcro);
Selects specified exchange complex as current. excAcro is an acronym used to identify exchange complex. Point In Time should be already selected prior to calling this method. Call to this method automatically resets BFCC and product family selection. Return value can be 0 (success) or non-zero (failure).
short SelectBFCC(BSTR ccCode);
Selects specified BFCC as current. ccCode is a combined commodity code. Exchange Complex should be already selected prior to calling this method. Call to this method automatically resets product family selection. Return value can be 0 (success) or non-zero (failure).
short SelectProductFamily(BSTR exchCode, BSTR pfCode, short pfType);
Selects specified product family as current. Parameters:
exchAcro- exchange acronym (“CME”, “CBT”)
pfCode- product family code (“SP”, “BP”)
pfType- product family type:
1- physical
2- debt
3- stock
11- future
12- equivalence debt
21- option on physical
22- option on future
23- option on equity
31- combination
41- option on combination
BFCC should be already selected prior to calling this method. Return value can be 0 (success) or non-zero (failure).
void ResetExchangeComplex();
Sets currently selected exchange complex to NULL (removes selection). Also resets BFCC and Product Family selection.
void ResetBFCC();
Sets currently selected BFCC to NULL (removes selection). Also resets Product Family selection.
void ResetProductFamily();
Sets currently selected product family to NULL (removes selection).
short CalcImpliedVolatility();
Calculates Implied Volatilities for selected object. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time.
Returns 0 if successful, non-zero – otherwise.
short CalcCallPutAverage(boolean outMoney, boolean acceptZero);
Does Call/Put Averaging for selected object. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time.
outMoney - true means use out-of-money volatility, false means do averaging
acceptZero - true means accept zero volatility as valid, false is the opposite
Returns 0 if successful, non-zero – otherwise.
short CalcSeriesVolatility(boolean useZero, double minExpTime, int maxIn, int maxOut, int minAccept);
Calculates Series Level Volatilities for selected object. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time.
useZero - true means do not filter out zero implied volatilities during calculations, false - filter them out.
minExpTime- minimum time to expiration in years. Standard value used by most algorithms is 0.0273973 (10 business days).
maxIn- number of closest in the money options which volatilities will be used in calculations (1 is standard).
maxOut- number of closest out of the money options which volatilities will be used in calculations (3 is standard).
minAccept- minimum sufficient number of around the money volatilities (5 is standard).
Returns 0 if successful, non-zero – otherwise.
short CalcPrice(short meth, boolean resetAll);
Calculates Theoretical Prices for selected object. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time.
meth- calculation method code:
1- use option/series level volatility
2- use option level volatility only
3- use series level volatility only
resetAll - true means reset prices for all contracts, false means reset prices only for contracts with undefined price
Returns 0 if successful, non-zero – otherwise.
short CalcRiskArray(short meth, boolean limitAtOptValue);
Calculates Risk Arrays for selected object. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. Parameters:
meth- calculation method code:
1- use option/series level volatility
2- use option level volatility only
3- use series level volatility only
limitAtOptValue - true means limit risk array values at the value of the option, false means do not limit risk array values
Returns 0 if successful, non-zero – otherwise.
void UpdatePrice(double value, short meth);
Use this method to Update Prices. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdateVolatility(double value, short meth);
Use this method to Update Volatilities. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdatePriceScan(double value, short meth);
Use this method to Update Price Scans. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdateVolScan(double value, short meth);
Use this method to Update Volatility Scans. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdateRiskFreeRate(double value, short meth);
Use this method to Update Risk-Free Rates. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdateDividendYield(double value, short meth);
Use this method to Update Dividend Yields. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
void UpdateTimeToExpiration(double value, short meth);
Use this method to Update Times to Expiration. It works on the lowest level object already selected (product family, bfcc, exchange complex, point in time). If point in time is not selected it will work on all loaded points in time. It will update price scans using value and one of the following methods:
Possible values for meth:
SET - set price scan to value
CHG - change price scan by value
PCNT - change price scan by value %
SET is the default method
short CopyPIT(BSTR description, BSTR busDate, short isSettle, short isFinal, BSTR busTime);
Use this method to copy Point In Time. This method creates new Point In Time object exactly matching the selected Point In Time. Attributes of the newly created Point In Time will be changed using parameters specified for the method. If Point In Time with these attributes already exists an error will be generated. Point In Time should be selected prior to using this method. If no Point In Time is selected an error will be generated. This method does not affect selected Point In Time.
Parameters:
description-description string, can be blank
busDate-has following format: YYYYMMDD (blank –
ignore)
isSettle and isFinal can have following values:
-1– ignore
0– false
1– true.
busTime-has format: HHMM (blank – ignore)
Return value can be 0 (success) or non-zero (failure).
Use this method to apply what-if scenario stored in the XML file fileName to the selected Point In Time. If Point In Time is not selected or file is not found, has incorrect format or is empty an error will be generated. Typical sequence of actions before using this command would include creation of a copy of a particular Point In Time. What-if scenario is applied to this copy:
SelectPIT
CopyPIT
SelectPIT
ApplyWhatIf
If doCalc flag is set to true following actions are performed on the selected PointInTime after applying what-if scenario:
CalcPrice
CalcRiskArray
Calculate
Parameters:
fileName fully specified path name of the what-if scenario XML file (required)
doCalc true or false
Return value can be 0 (success) or non-zero (failure).