SQL variables

You are here
SQL variables

Overview

The data stored in the MCS database from tests being run can be used in various ways. The mechanism for referencing the data is what we call a dollar ($) variable. It allows the user to extract test results for use in things like emails and a web page.

The tutorial will detail the available variables by type and, when applicable, how to use them.

Global - Variables like date, session ID, and connection type
Name Units Data Type Description Variable
IP varchar(128 bit) The IP address of the client '%IP%'
Time varchar(256 bit) The date/time as a GMT String '%TIME%'
Time Int bigint(20) The date/time as a number (eg: 20180725140500 for 14:05 on 25-Jul-2018) %TIMEINT%
Time ms ms bigint(20) The time in milliseconds from 1970 (eg: 1668193538367 for Fri Nov 11 2022 19:05:38 UTC 00:00). %TIMEMS%
Date/Time varchar(256 bit) The date/time that adheres to the SQL DATETIME standard. '%DATETIME%'
Session ID varchar(256 bit) The session ID is a custom identifier used to help identify results '%SID%'
DNS Name varchar(256 bit) Client's DNS Name '%DNSNAME%'
Test To varchar(32 bit) Server test-to address as seen by the client '%TESTTO%'
Country Code varchar(3 bit) Country code '%CC%'
ISP varchar(128 bit) Client’s ISP name '%ISP%'
Detail Link varchar(256 bit) The URL for the detail report '%DETAILLINK%'
Test ID int The ID number for a particular group of tests (not unique) %TESTID%
Record ID int Record ID # for an individual test (not unique) %RECORDID%
Connection Type varchar(16 bit) The type of connection the test was run on (WiFi/Ethernet) '%CONTYPE%'
Proxy State varchar(1) If a proxy was detected or not '%VIAPROXY%'
Account ID int The ID of the account that ran the test, this will be 0 for public users. '%ACCID%'
Wifi Signal varchar(8) The wifi signal strength, if applicable '%WIFISIG%'
Wifi Quality varchar(1) The quality of a wifi connection, if applicable '%WIFIQ%'

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[speed] INSERT INTO global (recordid, testid, timeint, time, datetime, sid, ip, isp, dns, testto, cc, detaillink, contype, proxy) VALUES (%RECORDID%, %TESTID%, %TIMEINT%, %TIME%, '%DATETIME%', '%SID%', '%IP%', '%ISP%', '%DNSNAME%', '%TESTTO%', '%CC%', '%DETAILLINK%', '%CONTYPE%', '%VIAPROXY%');
Speed - Variables related to throughput tests, like download and upload speed
Name Units Data Type Description Variable
Download Speed bps Integer (64 bit) Download speed in bits per second %ACT.DSPEED%
Upload Speed bps Integer (64 bit) Upload speed in bits per second %ACT.USPEED%
Download Bandwidth Kbps Integer (32 bit) Download Bandwidth in bits per second %ACT.DPCTKBPS%
Upload Bandwidth Kbps Integer (32 bit) Upload Bandwidth in bits per second %ACT.UPCTKBPS%
Download Percentile % Integer (8 bit) %ACT.DPCTILE%
Upload Percentile % Integer (8 bit) %ACT.UPCTILE%
QOS % Integer (8 bit) Download Quality/Consistency of Service %ACT.QOS%
Upload QOS % Integer (8 bit) Upload Quality/Consistency of Service %ACT.UQOS%
Min RTT ms Integer (8 bit) The minimum round trip time %ACT.RTT%
Max RTT % Integer (8 bit) The maximum round trip time %ACT.RTTMAX%
Average RTT % Integer (8 bit) The average round trip time %ACT.RTTAVG%
Max Pause ms Integer (8 bit) The max delay for the connection test %ACT.MAXPAUSE%
Up Max Pause Ms Integer (8 bit) Upload Max Pause %ACT.UMAXPAUSE%
Max Route Speed bps Integer (64 bit) The maximum achievable speed for the route based on the minimm round trp time %ACT.MAXROUTESPEED%
Up Max Route Speed bps Integer (64 bit) The maximum achievable speed for the route based on the minimm round trp time %ACT.UMAXROUTESPEED%
Effective Speed bps Integer (64 bit) The maximum effective speed %ACT.MAXLINESPEED%
Up Effective Speed Ms Integer (64 bit) Upload Maximum Effective Speed %ACT.UMAXLINESPEED%
Max TCP Connections Float The maximum amount of TCP connections given the result of the test %ACT.CONCURRENTTCP%
MUp ax TCP Connections Decimal (32 bit) Max TCP Connections %ACT.UCONCURRENTTCP%
TCP forced Idle % Float TCP Forced Idle %ACT.TCPFORCEDIDLE%
Up TCP Forced Idle % Float Upload TCP Forced Idle %ACT.UTCPFORCEDIDLE%
TCP MTU Integer (8 bit) Maximum Transmission Unit %ACT.TCPMTU%
Packets not in order Integer (16 bit) The number of packets that didn't arrive in order %ACT.TCPRXPOOO%
Bytes not in order Integer (16 bit) The number of bytes that didn't arrive in order %ACT.TCPRXBOOO%
Packets not in window Integer (16 bit) Packets that arrived outside of the window %ACT.TCPRXPOW%
Bytes not in window Integer (16 bit) Bytest that arrived outside of the window %ACT.TCPRXBOW%
Duplicated packets Integer (16 bit) Packets that were duplicated %ACT.TCPRXDOP%
Duplicated bytes Integer (16 bit) Bytes that were duplicated %ACT.TCPRXDOB%
Part duplicated packets Integer (16 bit) Packets that were partially duplicated %ACT.TCPRXPDP%
Part duplicated bytes Integer (16 bit) Bytes that were partially duplicated %ACT.TCPRXPDB%
CRC Packet Errors Integer (16 bit) CRC Packet Errors %ACT.TCPRXCRCERR%
Bad Packet Offset Integer (16 bit) Bad packet offsets %ACT.TCPRXBOFF%
Packets too short Integer (16 bit) Packets too short %ACT.TCPRXTS%
Window probes received Integer (16 bit) Window probes received %ACT.TCPRXPROBE%
Zero window updates sent Integer (16 bit) Zero window updates sent %ACT.TCPRXWINZEROUP%
Bytes lost Integer (16 bit) Bytes lost %ACT.TCPBYTESLOST%
Retransmit Timeouts Integer (16 bit) Retransmit Timeouts %ACT.TCPTXRTXTMO%
Fast Retransmits Integer (16 bit) Fast Retransmits %ACT.TCPTXRTXFAST%
Packets Retransmitted Integer (16 bit) Packets Retransmitted %ACT.TCPTXPRETX%
Bytes Retransmitted Integer (16 bit) Bytes Retransmitted %ACT.TCPTXBRETX%
Send Window Closed Integer (16 bit) Send Window Closed %ACT.TCPTXSNDWINCLOSE%
Pure Window Update Integer (16 bit) Pure Window Update %ACT.TCPTXRCVWINUPD%
Ack Too Much Integer (16 bit) Acknowledgements for unset packets %ACT.TCPTXRCVACKTOOMUCH%
Duplicate Acknowledgements Integer (16 bit) Duplicate Acknowledgements %ACT.TCPTXRCVDUPACK%
Send Probe Integer (16 bit) Window Probes Sent %ACT.TCPTXSNDPROBE%
Persist Timeouts Integer (16 bit) Persist Timeouts %ACT.TCPTXPERSISTTIMEO%
XL Frames Integer (32 bit) XL Frames %ACT.ETHRXFTL%
NA Frames Integer (32 bit) NA Frames %ACT.ETHRXNOAL%
Short Frames Integer (32 bit) Short Frames %ACT.ETHRXSF%
CRC Errors Integer (32 bit) CRC Errors %ACT.ETHRXCRCERR%
Overruns Integer (32 bit) Overruns %ACT.ETHRXOVR%
Cut Frames Integer (32 bit) Cut Frames %ACT.ETHRXTRUNC%
Download Test Type Text Download Test Type %ACT.DTESTTYPE%
Upload Test Type Text Upload Test Type %ACT.UTESTTYPE%
Network Downtime Sec Integer (32 bit) Network Downtime %ACT.NETDOWNSEC%
Network Uptime Sec Integer (32 bit) Network Uptime %ACT.NETUPSEC%
PC Network Downtime % Decimal (32 bit) PC Network Downtime %ACT.NETDOWNPC%
HTTP 3xx Sec Integer (32 bit) HTTP 3xx %ACT.HTTP3XXSEC%
HTTP 4xx Sec Integer (32 bit) HTTP 4xx %ACT.HTTP4XXSEC%
HTTP 5xx Sec Integer (32 bit) HTTP 5xx %ACT.HTTP5XXSEC%
HTTP ?xx Sec Integer (32 bit) HTTP ?xx %ACT.HTTPQXXSEC%
Firmware Version Text Firmware Version %ACT.VERSION%
CPU Up Time Sec Integer (64 bit) CPU Up Time %ACT.RUNTIME%
FreeQ Integer (32 bit) FreeQ %ACT.FREEQ%
Interface Text Ethernet Interface Type (100FD, 100HD etc) %ACT.INTERFACE%

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[act] INSERT INTO quality (recordid, testid, dspeed, uspeed, qos, rtt, rttmax, rttavg, maxpause, maxroutespeed, maxlinespeed, concurrenttcp, tcpmtu, tcpforcedidle, pooo, booo, pow, bow, dop, dob, pdp, pdb, crcerr, boff, ts, probe, winzeroup, byteslost, rtxtmo, rtxfast, pretx, bretx, sendclose, rcvwinup, acktoomuch, duppack, sndprobe, presisttmo, interface, uqos, umaxpause, umaxlinespeed, uconcurrenttcp, utcpforcedidle, ftl, noal, sf, ethrxcrcerr, ovr, trunc, dtesttype, utesttype, netdown, netup, downpc, http3, http4, http5, httpq, version, runtime, freeq) VALUES (%RECORDID%, %TESTID%, %ACT.DSPEED%, %ACT.USPEED%, %ACT.QOS%, %ACT.RTT%, %ACT.RTTMAX%, %ACT.RTTAVG%, %ACT.MAXPAUSE%, %ACT.MAXROUTESPEED%, %ACT.MAXLINESPEED%, %ACT.CONCURRENTTCP%, %ACT.TCPMTU%, %ACT.TCPFORCEDIDLE%, %ACT.TCPRXPOOO%, %ACT.TCPRXBOOO%, %ACT.TCPRXPOW%, %ACT.TCPRXBOW%, %ACT.TCPRXDOP%, %ACT.TCPRXDOB%, %ACT.TCPRXPDP%, %ACT.TCPRXPDB%, %ACT.TCPRXCRCERR%, %ACT.TCPRXBOFF%, %ACT.TCPRXTS%, %ACT.TCPRXPROBE%, %ACT.TCPRXWINZEROUP%, %ACT.TCPBYTESLOST%, %ACT.TCPTXRTXTMO%, %ACT.TCPTXRTXFAST%, %ACT.TCPTXPRETX%, %ACT.TCPTXBRETX%, %ACT.TCPTXSNDWINCLOSE%, %ACT.TCPTXRCVWINUPD%, %ACT.TCPTXRCVACKTOOMUCH%, %ACT.TCPTXRCVDUPACK%, %ACT.TCPTXSNDPROBE%, %ACT.TCPTXPERSISTTIMEO%, '%ACT.INTERFACE%', %ACT.UQOS%, %ACT.UMAXPAUSE%, %ACT.UMAXLINESPEED%, %ACT.UCONCURRENTTCP%, %ACT.UTCPFORCEDIDLE%, %ACT.ETHRXFTL%, %ACT.ETHRXNOAL%, %ACT.ETHRXSF%, %ACT.ETHRXCRCERR%, %ACT.ETHRXOVR%, %ACT.ETHRXTRUNC%, '%ACT.DTESTTYPE%', '%ACT.UTESTTYPE%', %ACT.NETDOWNSEC%, %ACT.NETUPSEC%, %ACT.NETDOWNPC%, %ACT.HTTP3XXSEC%, %ACT.HTTP4XXSEC%, %ACT.HTTP5XXSEC%, %ACT.HTTPQXXSEC%, '%ACT.VERSION%', %ACT.RUNTIME%, %ACT.FREEQ%);

Below is the CREATE TABLE statement for MySQL.

CREATE TABLE accessct (recordid bigint, testid bigint, dspeed bigint, uspeed bigint, qos int, rtt int, rttmax int, rttavg int, maxpause int, maxroutespeed bigint, maxlinespeed bigint, concurrenttcp float, tcpmtu int, tcpforcedidle float, pooo int, booo int, pow int, bow int, dop int, dob int, pdp int, pdb int, crcerr int, boff int, ts int, probe int, winzeroup int, byteslost int, rtxtmo int, rtxfast int, pretx int, bretx int, sendclose int, rcvwinup int, acktoomuch int, duppack int, sndprobe int, presisttmo int, interface varchar(128), uqos int, umaxpause int, umaxlinespeed bigint, uconcurrenttcp float, utcpforcedidle float, ftl int, noal int, sf int, ethrxcrcerr int, ovr int, trunc int, dtesttype varchar(6), utesttype varchar(6), netdown int, netup int, downpc int, http3 int, http4 int, http5 int, httpq int, version varchar(128), runtime int, freeq int, PRIMARY KEY (recordid));
VoIP - Variables related to VoIP tests, like jitter and packet loss
Name Units Data Type Description Variable
Up Jitter ms Float Jitter result for the upstream %VOIP.JITTER%
Up Loss % Float Packet loss for the upstream %VOIP.LOSS%
Down Jitter ms Float Jitter for the downstream %VOIP.DJITTER%
Down Loss % Float Packet loss for the downstream %VOIP.DLOSS%
Discards % Float Prcentage of packets discarded by protocol %VOIP.DISCARDS%
Order % Float Ordering percentage (metric showing how well ordered the packets were) %VOIP.ORDER%
RTT Minimum ms Int (8 bit) Minimum RTT (Round trip time) %VOIP.RTTMIN%
RTT Average ms Int (8 bit) Average RTT (Round trip time) %VOIP.RTTAVG%
RTT Maximum ms Int (8 bit) Maximum RTT (Round trip time) %VOIP.RTTMAX%
RTT Consistency % Float RTT (Round trip time) consistency %VOIP.RTTCONSISTENCY%
SIP Register ms Int (8 bit) Time taken to perform SIP REGISTER %VOIP.REGISTER%
SIP Invite ms Int (8 bit) Time taken to perform SIP INVITE %VOIP.INVITE%
SIP Bye ms Int (8 bit) Time taken to perform SIP BYE %VOIP.BYE%
SIP ALG String Varchar (8 bit) SIP Application Layer Gateway detected %VOIP.SIPALGFW%
Up Distribution Loss % Float Upstream distribution loss %VOIP.UPDISTLOSS%
Down Distribution Loss % Float Upstream distribution loss %VOIP.DOWNDISTLOSS%
Up Max Jitter ms Float Maximum recorded jitter during the upstream %VOIP.MAXJITTER%
Down Max Jitter ms Float Maximum recorded jitter during the downstream %VOIP.DMAXJITTER%
Up MOS - Float MOS score for the upstream %VOIP.MOS%
Down MOS - Float MOS score for the downstream %VOIP.DMOS%
Lines - Int Number of lines simulated for the test %VOIP.LINES%

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[voip] INSERT INTO myvoip (recordid, testid, jitter, loss, djitter, dloss, discards, pktorder, rttmin, rttavg, rttmax, rttcon, reg, inv, bye, sipalg, updist, downdist, maxjit, dmaxjit, mos, dmos, simlines) VALUES (%RECORDID%, %TESTID%, %VOIP.JITTER%, %VOIP.LOSS%, %VOIP.DJITTER%, %VOIP.DLOSS%, %VOIP.DISCARDS%, %VOIP.ORDER%, %VOIP.RTTMIN%, %VOIP.RTTAVG%, %VOIP.RTTMAX%, %VOIP.RTTCONSISTENCY%, %VOIP.REGISTER%, %VOIP.INVITE%, %VOIP.BYE%, '%VOIP.SIPALGFW%', %VOIP.UPDISTLOSS%, %VOIP.DOWNDISTLOSS%, %VOIP.MAXJITTER%, %VOIP.DMAXJITTER%, %VOIP.MOS%, %VOIP.DMOS%, %VOIP.LINES%);

Below is the CREATE TABLE statement for MySQL.

CREATE TABLE myvoip (recordid int, testid int, jitter float, loss float, djitter float, dloss float, discards float, pktorder float, rttmin int, rttavg int, rttmax int, rttcon float, reg int, inv int, bye int, sipalg varchar(8), updist float, downdist float, maxjit float, dmaxjit float, mos float, dmos float, simlines int);
Route - Variables related to route tests, like hops and ISP
Name Units Data Type Description Variable
Max Route Response
(client to server)
ms SMALLINT Maximum response time for the route %ROUTE.MAXMS%
Max Route Response
(server to client)
ms SMALLINT Maximum response time for the route %ROUTE.MAXMS%
Target Packet Loss
(client to server)
% TINYINT Packet loss to target %ROUTE.ENDLOSS%
Target Packet Loss
(server to client)
% TINYINT Packet loss to target %ROUTE.ENDLOSS%
Target Average Response
(client to server)
ms SMALLINT Average response time to target %ROUTE.ENDMS%
Target Average Response
(server to client)
ms SMALLINT Average response time to target %ROUTE.ENDMS%
Target IP
(client to server)
Varchar(128) The target IP address %ROUTE.IPTO%
Target IP
(server to client)
Varchar(128) The target IP address %ROUTE.IPTO%
Hops to target
(client to server)
SMALLINT Total number of hops in route %ROUTE.HOPS%
Hops to target
(server to client)
SMALLINT Total number of hops in route %ROUTE.HOPS%
Source IP
(client to server)
Varchar(128) The IP address the route originated from %ROUTE.IPFROM%
Source IP
(server to client)
Varchar(128) The IP address the route originated from %ROUTE.IPFROM%
Route target name Varchar(128) The name of the trace route target %ROUTE.ENTEREDNAME%
DNS Response ms SMALLINT The DNS response time for the target %ROUTE.DNSTIME%
Max Route Loss % TINYINT Maximum loss recorded for all hops over the route %ROUTE.MAXLOSS%

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[route] INSERT INTO myroute (recordid, testid, traceto, totalhops, targetms, maxms, targetloss, maxloss, dnstime, targetip, tracefrom) VALUES (%RECORDID%, %TESTID%, '%ROUTE.ENTEREDNAME%', %ROUTE.HOPS%, %ROUTE.ENDMS%, %ROUTE.MAXMS%, %ROUTE.ENDLOSS%, %ROUTE.MAXLOSS%, %ROUTE.DNSTIME%, '%ROUTE.IPTO%', '%ROUTE.IPFROM%');

Below is the CREATE TABLE statement for MySQL.

CREATE TABLE myroute (recordid int, testid int, traceto varchar(128), totalhops tinyint, targetms smallint, maxms smallint, targetloss smallint, maxloss smallint, dnstime smallint, targetip varchar(128), tracefrom varchar(128));

When running a bi-directional route test MCS will export one record for each direction. So, in the SQL table there will be a row for client-to-server and a row for server-to-client.

Capacity - Variables related to capacity tests, like download and upload capacity
Name Units Data Type Description Variable
Downstream Capacity bits BIGINT The download capacity result %CAPACITY.DCAPACITY%
Upstream Capacity bits BIGINT The upload capacity result %CAPACITY.UCAPACITY%
Downstream Packets bits INT The packet rate achieved for the download result %CAPACITY.DPACKETS%
Upstream Packets bits INT The packet rate achieved for the upload result %CAPACITY.UCPACKETS%
Downstream Limit bits BIGINT The upper limit that was configured for the test %CAPACITY.DMAXBANDWIDTH%
Upstream Limit bits BIGINT The upper limit that was configured for the test %CAPACITY.UMAXBANDWIDTH%
Packet Size Bytes INT The packet size used for the test %CAPACITY.PACKETSIZE%
Consistency of Service % TINYINT The consistency of service percentage %CAPACITY.QOS%

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[capacity] INSERT INTO capacity (recordid, testid, dcap, ucap, dlimit, ulimit, dpkt, upkt, pktsize, cos) VALUES (%RECORDID%, %TESTID%, %CAPACITY.DCAPACITY%, %CAPACITY.UCAPACITY%, %CAPACITY.DMAXBANDWIDTH%, %CAPACITY.UMAXBANDWIDTH%, %CAPACITY.DPACKETS%, %CAPACITY.UPACKETS%, %CAPACITY.PACKETSIZE%, %CAPACITY.QOS%);

Below is the CREATE TABLE statement for MySQL.

CREATE TABLE capacity (recordid int, testid int, dcap bigint, ucap bigint, dlimit bigint, ulimit bigint, dpkt int, upkt int, pktsize int, cos tinyint);
Firewall - Variables related to firewall tests, like ports open and closed
Name Units Data Type Description Variable
Firewall Record Id - - A delimitted string of the record IDs for each port/port group. See Global (above)
Ports tested - - An array of the port/port groups that were tested. %FIREWALL.PORTS%
Port protocol - - An array of the protocol for the tested ports (UDP, TCP) %FIREWALL.PROTOCOL%
Average response ms Float The average response time for testing the port availability %FIREWALL.AVGRESPONSE%
Minimum response ms SMALLINT The minimum response time for testing the port availability %FIREWALL.MINRESPONSE%
Maximum response ms SMALLINT The maximum response time for testing the port availability %FIREWALL.MAXRESPONSE%
Open ports - INT A count of how many ports were open. %FIREWALL.POPEN%
Blocked ports - INT A count of how many ports were blocked. %FIREWALL.PBLOCK%
Total open ports - INT A count of how many ports were open for the entire test. %FIREWALL.TPOPEN%
Total blocked ports - INT A count of how many ports were blocked for the entire test. %FIREWALL.TPBLOCK%

SQL Example

To use the SQL variables above create an SQL profile as shown below.

The SQL statment shown below must match the SQL table. The column types are shown above.

[firewall] INSERT INTO myfirewall (recordid, testid, avgres, minres, maxres, port, protocol, popen, pblock, tpopen, tpblock) VALUES (%RECORDID%, %TESTID%, %FIREWALL.AVGRESPONSE%, %FIREWALL.MINRESPONSE%, %FIREWALL.MAXRESPONSE%, '%FIREWALL.PORTS%', '%FIREWALL.PROTOCOL%', %FIREWALL.POPEN%, %FIREWALL.PBLOCK%, %FIREWALL.TPOPEN%, %FIREWALL.TPBLOCK%);

Below is the CREATE TABLE statement for MySQL.

CREATE TABLE myfirewall (recordid int, testid int, avgres float, minres smallint, maxres smallint, port varchar(16), protocol varchar(8), popen int, pblock int, tpopen int, tpblock int);