Data AcQuisition And Real-Time AnalysisScope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
Contact us about
String Variables and Expressions
Certain Macro commands can accept string expressions that contain multiple terms. The items in the string must be separated by plus (+) signs. Ordinary text must be surrounded by quotes. Spaces between items are optional. For example:
LogTxt=n + "Time: " + t + " Test" + VarA(3) + " PASSED"
This would start a new line (n) in the log file, with the text:
Time: 09:52:21.859 Test074 PASSED
The time is given according to the Time Format in Date/Time Preferences in the Edit Menu. The value of VarA in this example is 74, shown with a 3-digit integer format (3) to get a standardized output. If the (3) wasn't used, the default format would show the minimum number of integer digits, plus 3 decimal places... Test74.000. (See Decimal Display Format and following, below, for more format options.)
String expressions may be used by the following commands:
File name commands like Open or SaveDQA Notes Labels Fields Generator Title Custom Meters Mtr0-Mtr3 Message text WaitMsg and Msg Message titles WaitMsgTitle and MsgTitle Event Wait prompt message WaitAvg Log File macros LogTxt and LogName
The terms that can be used in string expressions include:
Quoted strings String variables like Notes, Labels, and Fields String Array entries like Str0 or Str0[100,123] String Storage entries like Buf0(a2) Numeric variables like VarA, A, or Buf0 Main Daqarta numeric control variables like TrigLevel On/Off toggle controls like Gen (0 or 1)
String expressions simply substitute the string representation for each variable. The '+' signs that separate the terms only indicate concatenation; you can't use any sort of math expressions or math functions on the variables within the string expression. Instead, you must perform any calculations first, and set the results to variables whose values can then be displayed.
String expressions may be continued over multiple lines by ending each unfinished line with an underscore, and starting the continued line with a '+'.
Note that you can't use constants pi or e directly. Instead of Msg=pi, set a variable like A=pi then use Msg=A.
As shown in the initial example, string expressions can use special date and time variables:
In addition, if a string expression is being used to set Notes, Mtr0-3, WaitMsg, Msg, WaitAvg, or LogTxt you can control the format via:
b Insert one space (blank). b123 Insert 123 spaces. b(UA) Insert UA spaces. c Insert comma plus one space. c123 Insert comma plus 123 spaces. c(UA) Insert comma plus UA spaces. q Insert a quote character. n Start a new line. p123 Position next string output at column 123. p(UA) Position at column UA. f*123 Fill with '*' from current column to 123. f*(UA) Fill to column UA.
123 in the above examples may be replaced with any immediate value from 0 to 999. (UA) can be replaced with any expression; the value will be limited to 0-999 after evaluation.
The position (p) and fill (f) options can only advance from the current position, otherwise they have no effect. Column numbers are 0-based. The current position is maintained separately for Notes and LogTxt across separate commands during a Daqarta session. (The first command of a session always starts a new line.)
The fill character (* in the above examples) can be any displayable standard ASCII character except a space. (The p position commands fill with spaces.)
Notes, Field, and Label strings can include themselves, to allow appending or prepending to an existing string. For example, Notes=Notes + "Tail" will append "Tail" to any existing Notes string, while Notes="Head" + Notes will prepend "Head".
When a numeric variable is used in a string expression, the default is to show the entire integer portion, plus 3 decimal places. A=pi followed by Msg=A would display 3.142.
You can specify a different format by including it in parentheses. The format consists of a 0-9 integer digit count followed by a decimal point and a 0-9 decimal place count. For example, A(4.3) specifies 4 integer digits and 3 decimal places.
If you use only a single digit in parentheses, such as A(4), it is assumed to specify integer digits, with decimal places set to 0.
The integer digit count is the minimum number of digits to be shown, with leading zeros added as needed. If the integer part of the variable value requires more digits, they are always shown. If it requires less, it is padded with leading zeros. If you set the integer digit count to zero and there are no integer digits to be shown, a single zero will nevertheless be shown before the decimal point.
Alternatively, you can use an underscore in place of the decimal when specifying the format, as in A(4_3). That will cause spaces to be used instead of leading zeros. However, if there are no integer digits a single zero will still be shown before the decimal point.
The decimal place count is the maximum number of decimal places shown. Less-significant digits are removed by rounding, not truncation.
Thus, if Var0 is equal to 12.345, then with the default format Field1="Test" + Var0 would set Field1 to Test12.345. Var0(3.0) or Var0(3) would result in Test012, while Var0(0.2) would result in Test12.35 due to rounding.
You will probably want to use leading zero padding for test or file names, as in the above Test012 example. For general display you can usually just specify zero integer digits to let the actual amount needed be shown, plus the specified number of decimal places.
However, sometimes you may want to keep numbers aligned, such as columns of values in Log files, multi-line messages, or Custom Meters. In fact, even for a single-line custom meter you may want to use a fixed number of integer spaces so that the display doesn't jump around as the size of the value increases and decreases. You will need to set the integer digit count to handle the largest value that will be shown, and you will probably want to use an underscore to specify spaces instead of leading zeros.
Alternatively, you can specify a hexadecimal string via (h) or (H). The (h) option truncates any fractional part and shows only the 32-bit integer part as an 8-character string, so Var0(h) in the above example would show as Test0000000C.
The (H) option shows the full 32-bit integer and 32-bit fraction parts as two 8-character strings separated by a decimal point. Var0(H) in the above example would give Test0000000C.5851EB85.
You can specify that an integer value be displayed in binary format as a string of 1s and 0s. Use (b) to display a single 8-bit byte (0-255), or the low 8 bits of a larger value. For example, if UX holds the decimal value 123, Msg=UX(b) will display 01111011.
Use (b2) to display a 16-bit (2 byte) value in the decimal range of 0-65535, or the low 16 bits of a larger value.
Use (b4) to display a 32-bit (4 byte) value in the decimal range of 0 to 4294967295 (2^32-1).
If any value has a fractional part, it is ignored.
Note that no separators are provided in the (b2) or (b4) options, so (for example) 65432 is shown as 1111111110011000. To make this easier to read, you may wish to parse the value into bytes. If X holds the value, the high byte can be obtained by UH=int(X >> 8) and the low byte by UL=X & 255. You can then use Msg=UH(b) + " " + UL(b) to get:
You can use the same strategy to break larger values into separate bytes for better legibility.
(Note that you need the int() for finding UH because the underlying math for the >> right-shift operation returns a floating-point result with automatic rounding of the fraction, which in this case would be to zero. See the Caution note at the end of "Arithmetic Operators" under Macro Expressions and Operators.)
The above decimal and hexadecimal format options only support 32-bit integer plus 32-bit fraction display (0-9 digits each). However, floating-point variables A-Z can hold much larger or smaller values, from about 10^4932 down to 10^-4932, with 64-bit resolution (about 19 digits).
To show these you can use exponential format by prepending 'e' before the integer digit, as in Msg=A(e1.9). Then if A = pi * 10^123 this would show it as 3.141592653e+123.
If you just use Msg=A(e) with no digits specified, the default is the same as A(e1.3). If you only supply a single digit after the 'e', it is assumed to be the integer digit count.
If you use 'E' instead of 'e', then Msg=A(E1.9) will show 3.141592653E+123.
Note that with exponential notation, the integer digit count is always the actual number of digits to be shown. So in the above example, A(3.3) would show 314.159e+121. Note how the exponent has been decreased by the same amount the integer digits have been increased. Exponential notation only allows up to 9 decimal places, but if you need more resolution you can increase the number of integer digits, up to a maximum of A(e9.9).
You can also use exponential notation with fixed-point variables Var0-Z and main Daqarta control variables, not just A-Z floats. However, the fixed-point values will be converted to floats for formatting; there will be no real increase in resolution.
This is very similar to the above exponential format. If A = pi * 10^123 then:
Msg=A(S1.9) shows 3.141592653 * 10^+123 Msg=A(s1.9) shows 3.141592653*10^+123.
(Note that small 's' means smaller spacing.)
As with exponential format, if this is used with fixed-point variables they will be converted to floats, but they will still have the same overall resolution.
A numeric value can be shown as time in H:M:S.nnn format, assuming that the value is in seconds. For example, if X = 12345.6789, Msg=X(T) will show it as 3:25:45.679 using a default of 3 decimal places. You can specify more or less places by appending a decimal and a digit from 0 to 9 after the 'T', so that Msg=X(T.0) will show 3:25:46 and Msg=X(T.5) will show 3:25:45.76890. Large values will be shown with hours greater than 24 as needed. Small values will have zeros as needed in hours and minutes, such that 12.345 will be shown as 0:00:12.345.
Please note that this is for display of numerical values in a time format; it does not apply to display of the current time using the 't' or 'uT' options. Those use the current Time Format set via the TimeFmt command, or manually via the Date/Time Preferences menu.
You can also specify that the value be shown as text, using the (A) option as in Msg=X(A). The value is treated as a string of ASCII bytes with the left-most character as the highest byte in use. The number of characters that can be stored depends on the variable type.
Floating-point variables A-Z and 64-bit fixed-point variables Var0-VarZ can hold up to 8 characters.
Integer MIDI variables U0-UZ and Q0-QZ can hold up to 4 characters.
Small fixed-point MIDI variables Ua-Uz and Qa-Qz can only hold 2 characters.
For example, if you set X="12345678" you can use Msg=X(H) to see the stored value 31323334.35363738 in hexadecimal, while Msg=X(A) will show the original 12345678.
If you set UA="PASS" it will be stored as 50415353 in hex. It could have been entered as UA=h50415353 or in decimal as the equivalent UA=1346458451, but will be shown by Msg=UA(A) as PASS.
You can thus use variables in string expressions, such as Field1="Test: " + UA(A)", which for the above UA value would result in Field 1 showing Test: PASS.
ASCII characters below 0x20 (space) or above 0x7E (tilde) are skipped during conversion to text. 0x41884243 would be shown as ABC, ignoring the 0x88 in the second byte.
The alphanumeric display format is most useful with numeric macro variables that have been set directly using a string. For example, you can use V="NumA". If you later increment V by one, it will be shown as 'NumB' using the V(A) option.
Most macro variables can be set with quoted text like this, as well as indexed elements of macro arrays Buf0-Buf7. For example, Buf0="FAIL" can be displayed with the (A) alphanumeric format option, such as via Mtr0=Buf0(A).
(The Buf0-7 String Array Format, below, discusses how to save and use 8, 16, 32, 64, ... up to 2048-character strings in macro arrays.)
As noted previously, when assigned to most numeric variables the characters are stored in the same left-to-right significance as written, such that UA="1234" would be stored as hex 31323334. This is the opposite of what happens with a Buf0-7 string storage assignment such Buf0#a="1234", which stores string characters starting at the least-significant fraction end of the 8-byte array element (lowest in memory on Windows systems.) This would result in 00000000.34333231 if displayed with the (H) hexadecimal display option. Instead of the (A) option you should thus use one of the Buf0-7 string storage formats discussed below.
Each string can use 1, 2, 4, 8, 16, 32, 64, 128, or 256 indexed elements of a buffer. Each buffer element can hold up to 8 characters, so strings can be up to 8, 16, 32, 64, 128, 256, 512, 1024, or 2048 characters.
The table below shows each format, the number of array elements it uses, the maximum number of characters in the string, and the number of such strings that can fit into each Buf0-7 array:
Format Elements Characters Capacity a 1 8 1024 a2 2 16 512 a4 4 32 256 a8 8 64 128 aA 16 128 64 aB 32 256 32 aC 64 512 16 aD 128 1024 8 aE 256 2048 4
Strings are saved via commands like:
Buf0#a="Test1234" Buf0#a2="Testing 12345678" Buf0#a4=t + " " + d Buf0#a8=t + " " + d + " Testing 12345678"
To use array strings in a string expression, you use the same a through aE specifiers (without the #) in place of the alphanumeric format A, as in Msg=Buf0(a2).
You can also use individual characters from each element of the array. Each element holds up to 8 characters, numbered 0-7, and a single character can appear in a string expression like Mtr0=Buf0?5(a). This inserts character number 5, which would be the "g" from "Testing 12345678" in the above example. Note that this single-character form must always use the (a) format specifier, even though the original string was assigned with #a2. To display the "3" from the second half of this string you'd use the next element index  via Mtr0=Buf0?2(a).
Array string expressions can be assigned to other array strings, including themselves, such as Buf0#a2=Buf0(a2) + "5678"
Variables that are used to hold binary states of 1 or 0 can be shown as more-meaningful text. For example, the (L.t) format option will show 1 as 'True' and 0 as 'False'.
(L.t) = True / False (L.y) = Yes / No (L.o) = On / Off (L.p) = Pass / Fail
If you use an uppercase letter the resulting text will be all upper case. For example, with Msg=Var0(L.T) you will get 'TRUE' or 'FALSE'.
Any value whose integer portion is above zero will be treated as 1, while any whose integer portion is 0 or negative will be treated as 0.
If a variable holds a value from 0 to 3 that corresponds to an input or output channel number, it can be shown via the (C) (short form) or (c) (full text) options. The text for each channel number is:
0 = L.I. or Left In 1 = R.I. or Right In 2 = L.O. or Left Out 3 = R.O. or Right Out
If the value is outside this range it shows as 'Bad Chan'.
The Channel format allows Custom Meters, for example, to display values that are labeled with the channels they are obtained from. For example, you can read the current Channel Select value Ch and display it via Mtr0=V(0.3) + " " + Ch(c) to show something like '123.456 Left In'. (The same channel names can also be used to label Custom Controls via the CtrlN="<<"+ Ch(c) and BtnN="" + Ch(c) options discussed in the Custom Controls Command Summary.)
Note that by default the Freq, Volts, and SPL meter readout macros return strings that may include units, like '123.456 mV'. You can control the decimal places with the Plcs controls in each meter (FcountPlcs, VoltPlcs, or SPLplcs), but those affect the meter itself as well as the macro usage. However, if you use one of the above format options like Msg=Volts(0.6) you would get '0.123456' instead; the format automatically uses whole volts, not mV.
There are certain limitations when string variables are used to set file names, as with Open, SaveDQA, SaveTXT, or various macro array file operations. Time variables t and uT produce strings that include colons, which can't be used in file names. If a macro uses these in a file name, or even explicitly uses colons, Daqarta will replace the colons with percent signs.
Similarly, date variables apply the current settings of the Date/Time Preferences Menu. However, a slash as date separator (the nn/nn/nn option) will be replaced with a dash (nn-nn-nn) in the file name. You may want to eliminate the separator entirely (the nnnnnn option), in which case leading zeros are automatically used to avoid ambiguity.
See the Filename Forbidden Characters section under the ASCII Character Table topic for other forbidden characters and their automatic replacement alternates.
When a numeric variable (either a main control like ToneFreq or a macro variable like A, VarA, or UA) is used in a file name, the default is to show no decimal places instead of the usual default of 3 places. (The value is rounded, not truncated, to remove any fraction.) This prevents extra decimals in file names, such as Freq123.456.TXT. Such names are perfectly legal under Windows, but if you want them you need to specify an explicit format such as SaveTXT="Freq" + L.0.ToneFreq(3.3).
See also Macro Overview
Questions? Comments? Contact us!We respond to ALL inquiries, typically within 24 hrs.
Over 30 Years of Innovative Instrumentation
© Copyright 2007 - 2017 by Interstellar Research
All rights reserved