Daqarta
Data AcQuisition And Real-Time Analysis
Scope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
The following is from the Daqarta Help system:

Features:

Oscilloscope

Spectrum Analyzer

8-Channel
Signal Generator

(Absolutely FREE!)

Spectrogram

Pitch Tracker

Pitch-to-MIDI

DaqMusiq Generator
(Free Music... Forever!)

Engine Simulator

LCR Meter

Remote Operation

DC Measurements

True RMS Voltmeter

Sound Level Meter

Frequency Counter
    Period
    Event
    Spectral Event

    Temperature
    Pressure
    MHz Frequencies

Data Logger

Waveform Averager

Histogram

Post-Stimulus Time
Histogram (PSTH)

THD Meter

IMD Meter

Precision Phase Meter

Pulse Meter

Macro System

Multi-Trace Arrays

Trigger Controls

Auto-Calibration

Spectral Peak Track

Spectrum Limit Testing

Direct-to-Disk Recording

Accessibility

Applications:

Frequency response

Distortion measurement

Speech and music

Microphone calibration

Loudspeaker test

Auditory phenomena

Musical instrument tuning

Animal sound

Evoked potentials

Rotating machinery

Automotive

Product test

Contact us about
your application!

String Variables and Expressions

Introduction:

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.)


Usage:

String expressions may be used by the following commands:

    File Names
    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 Buf0[123](a2)
    Numeric variables like VarA, A, or Buf0[123]
    Main Daqarta numeric control variables like TrigLevel
    On/Off toggle controls like Gen (0 or 1)

Besides control variables, you can use any read-only variable that normally returns a value or string, such as Freq, SPL, Volts, Frames, or DeltY.

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:

    d   Local Date.
    uD  UTC Date.
    t   Local Time.
    uT  UTC Time.

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".

There are certain limitations when string variables are used to set file names, as with SaveDQA or SaveTXT. Time variables t and uT are not allowed because they produce strings that include colons, which can't be used in file names.

Date variables d and uD may be used in file names, applying 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) when the macro runs. You may want to eliminate the separator entirely (the nnnnnn option), in which case leading zeros are automatically used to avoid ambiguity.


Decimal Display Format:

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 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.


Hexadecimal Display Format:

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.


Binary Display Format:

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:

11111111 10011000

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.)


Exponential Display Format:

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.


Scientific Notation Format:

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.


Time Display Format:

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 0 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, however, get the current time in seconds via X=Time?s (local) or X=Time?S (UTC), and then use X(T.0), etc, to control decimal places without changing the main Time Format preference.


Alphanumeric Format:

You can also specify that the value be shown as text. The integer part of the value is treated as four ASCII bytes, with the right-most character as the lowest byte. If Var0 = 0x50415353 then Field1="Test" + Var0(A) would show as TestPASS.

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 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[123]="FAIL" can be displayed with the (A) alphanumeric format option, such as via Mtr0=Buf0[123](A).

(The String Array Format, below, discusses how to save and use 8, 16, 32, or 64-character strings in macro arrays.)

Note that when assigning 4-character (or less) strings to an intermediate variable like UA above, 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 String Array assignment such Buf0[123]#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.


String Array Format:

This format applies only to strings that have been saved to string arrays in macro array buffers Buf0 to Buf7.

Each string can use 1, 2, 4, or 8 indexed elements of a buffer. Each buffer element can hold up to 8 characters, so strings can be up to 8, 16, 32, or 64 characters.

Strings are saved via commands like:

Buf0[99]#a="Test1234"
Buf0[100]#a2="Testing 12345678"
Buf0[102]#a4=t + "  " + d
Buf0[106]#a8=t + "  " + d + "  Testing 12345678"

To use array strings in a string expression, you use the same a through a8 specifiers (without the #) in place of the alphanumeric format A, as in Msg=Buf0[100](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[100](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 [101] via Mtr0=Buf0?2[101](a).

Array string expressions can be assigned to other array strings, including themselves, such as Buf0[100]#a2=Buf0[100](a2) + "5678"

See the Macro String Arrays topic for more information, including a discussion of how the Multiple Meters mini-app uses them to simplify macro code.


Logical State Format:

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.


Channel Name Format:

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.


When a numeric variable (either a main control like ToneFreq or a macro variable like VarA) 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 the 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

GO:

Questions? Comments? Contact us!

We respond to ALL inquiries, typically within 24 hrs.
INTERSTELLAR RESEARCH:
Over 30 Years of Innovative Instrumentation
© Copyright 2007 - 2017 by Interstellar Research
All rights reserved