Buf0-7 String Storage

Each macro array Buf0-7 is a collection of 1024 elements. Each element normally holds a 64-bit numerical value, but that same 64 bit element can instead hold up to 8 ASCII text characters. Elements can be accessed individually or in groups of 2, 4, 8, 16, 32, 64, 128, or 256 to provide string arrays of up to 8, 16, 32, 64, 128, 256, 512, 1024, or 2048 characters per entry.

For example, Buf0[100]#a="Label #1" stores the string "Label #1" at Buf0 index 100.

Note that you must always use an index, even if it is [0].

Buf0[100]#a2="Longer Label #1" uses index 101 as well as 100 to hold the 15-character string. (A null is entered as the 16th character.)

Similarly, use #a4 and #a8 to specify 4-element (32-character) or 8-element (64-character) strings. 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

Any unused characters in an element are padded with nulls, which will be ignored when the string is used.

If an attempt is made to enter a string that is longer than the specified size, the extra characters will be ignored.

A string may include any standard ASCII character that can be typed into a macro definition, such as alphanumerics or symbols, as well as any string expression options such as n to start a new line, or t to insert the current time.

Strings may be copied from String Arrays Str0-Str7, Notes, Labels, or Fields. For example, Buf0[100]#a2=Field1 will copy the contents of Field1, which may hold up to 15 characters.

Similarly, Buf0[0]#aE=Str0 will copy the entire contents of Str0 up to its full capacity of 2048 characters, and still have room for 3 more String Arrays at Buf0[256], Buf0[512], and Buf0[768].

Conversely, Str0#A=Buf0[0](aE) will copy the first 2048 bytes from Buf0[0] into Str0, including nulls.

Note that with string expressions you must choose the string size specifier (#a through #aE) for the longest string expression output. For example, if you want to store the long-form channel name (such as "Left In") of the channel number previously specified via the Channel Select variable Ch, using Buf0[100]#a=Ch(c) will store only "Right Ou" if Ch = 3. Instead, use the longer Buf0[100]#a2=Ch(c)

Alternatively, you could use Buf0[100]#a=Ch(C) (note uppercase 'C') to specify short-form channel names, which are all exactly 4 characters like "R.O.".

To use Buf0-7 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[100](a2).

You may also read a single character from a string. For example, Buf0?5[123] will return character 5 of element [123] in Buf0. The character number after the '?' may range from 0 to 7 to read any of the 8 characters stored in the given element. One use for this is to provide different macro actions depending on a part number, test series, or subject code specified in a Field by the operator. You would first copy the Field to an array element, such as Buf0[123]#a=Field1, then test for certain characters with IF.Buf0?0[123]="A" to see if the first character in Field1 is 'A'.

A string assignment to an array element may include other string array elements, including itself. For example:

    Buf0[100]#a="ABCD"
    Buf0[100]#a=Buf0[100](a) + "EFGH"

This will leave the element holding "ABCDEFGH".

An array can mix these formats in any combination, including conventional numerical values.

Buf0-7 arrays containing strings (plus anything else) can be saved to .BUF files using Buf0="<Save:MyFile", but not with Buf0="<SaveTXT:MyFile" or any other explicit Save format. Those will save numerical data, but not strings. (SaveTXT saves numerical data as strings, but it won't save arbitrary strings directly.)

There are two options for loading arrays with strings (or any arbitrary bytes): The first approach is Buf0="<Load:MyFile". The file must have a .BUF extension for this to work.

A more versatile approach is to use Buf0#W=64 followed by Buf0="<LoadDAT:MyFile". This allows use of any file extension by specifying it explicitly, as in Buf0="<LoadDAT:MyFile.TXT", or letting the user specify it in the File Open dialog.

A buffer containing text can be mapped (not copied) to a string array such as Str0 via Str0#B=n, where n is 0-7 to specify Buf0-Buf7. This allows easy reading of all 8192 bytes using versatile string array commands including string searches. This mapping is read only; you can't write to the string that is mapped until it is released via Str0#B=-1.

Since the Buf0-7 arrays can each hold up to 1024 strings of 8 characters each, a single .BUF file can normally hold up to 8192 characters. But you can save 2 or 4 adjacent arrays as "multi-channel" files that will likewise be loaded to adjacent arrays. So in principle you could save up to 32768 characters to a single file. (See "Saving Buffers To Files" and "Loading Buffers From Files" under Macro Array File Operations.)

Whether saving or loading a file, no recognition is given to the format or organization; it's all "just bytes". You can organize and mix formats any way you choose. In particular, you can load raw continuous text (not parsed into 8, 16, 32, 64, ...2048-byte strings) and parse it as desired.

The Multiple Meters mini-app employs mixed array usage with Buf6, which holds various parameters, plus voltage, dB, and frequency values for each channel, along with strings to label custom controls and meters with the selected measurement mode (like "RMS" or "Peak-to-Peak").

For example, when the main Multi_Meters macro starts, it loads the strings into Buf6[900]#a2 through Buf6[920]#a2 via:

    Buf6[900]#a2="RMS"
    Buf6[902]#a2="Peak-to-Peak"
    Buf6[904]#a2="Positive Peak"
    Buf6[906]#a2="Negative Peak"
    Buf6[908]#a2="Absolute Peak"
    Buf6[910]#a2="dB  Re: 1V Sine"
    Buf6[912]#a2="dB  Re: FS Sine"
    Buf6[914]#a2="Crest Factor"
    Buf6[916]#a2="Crest dB"
    Buf6[918]#a2="Frequency"
    Buf6[920]#a2="Off"

Later, when the user clicks Custom Controls Btn0 to select a channel for adjustment, or Btn2 to select a new measurement mode for the selected channel, the _Multi_Mtr_Ctrls macro calls _Multi_Mtr_Mode.

_Multi_Mtr_Mode sets the current channel Ch from the Btn0 value (0-3) and sets UC to the measurement mode number (0-10) for that channel which is stored in Buf6[800] to Buf6[803] via UC=Buf6[800 + Btn0]. It then sets UI as an index variable to find the proper string for that channel and measurement mode. It labels Btn2 with the measurement mode via Btn2="" + Buf6[UI](a2), and labels the meter for that channel with the channel name and the measurement mode via MtrV="<<" + Ch(c) + " - " + Buf6[UI](a2)

Ch=Btn0                        ;Set channel to Btn0 state 0-3
UC=Buf6[800 + Btn0]            ;Get meter mode for this channel
UI=900 + 2 * UC                ;Index for mode text for this chan
Btn2="" + Buf6[UI](a2)         ;Label button with mode for this chan
MtrV="<<" + Ch(c) + " - " + Buf6[UI](a2)   ;Chan and mode to Mtr title

Without the use of Buf0-7 string arrays, this same section of _Multi_Mtr_Mode code would require 11 separate IF statements, one for each possible measurement mode:

Ch=Btn0
IF.Buf6[800 + Btn0]=0
    Btn2="RMS"
    MtrV="<<" + Ch(c) + " - RMS"
ENDIF.
IF.Buf6[Btn0]=1
    Btn2="Peak-to-Peak"
    MtrV="<<" + Ch(c) + " - Peak-to-Peak"
ENDIF.
IF.Buf6[Btn0]=2
    Btn2="Positive Peak"
    MtrV="<<" + Ch(c) + " - Positive Peak"
ENDIF.
IF.Buf6[Btn0]=3
    Btn2="Negative Peak"
    MtrV="<<" + Ch(c) + " - Negative Peak"
ENDIF.
IF.Buf6[Btn0]=4
    Btn2="Absolute Peak"
    MtrV="<<" + Ch(c) + " - Absolute Peak"
ENDIF.
IF.Buf6[Btn0]=5
    Btn2="dB  Re: 1V Sine"
    MtrV="<<" + Ch(c) + " - dB  Re: 1V Sine"
ENDIF.
IF.Buf6[Btn0]=6
    Btn2="dB  Re: FS Sine"
    MtrV="<<" + Ch(c) + " - dB  Re: FS Sine"
ENDIF.
IF.Buf6[Btn0]=7
    Btn2="Crest Factor"
    MtrV="<<" + Ch(c) + " - Crest Factor"
ENDIF.
IF.Buf6[Btn0]=8
    Btn2="Crest dB"
    MtrV="<<" + Ch(c) + " - Crest dB"
ENDIF.
IF.Buf6[Btn0]=9
    Btn2="Frequency"
    MtrV="<<" + Ch(c) + " Frequency"
ENDIF.
IF.Buf6[Btn0]=10
    Btn2="Off"
    MtrV="<<" + Ch(c) + " - Off"
ENDIF.

Note that the same indexed array approach can be used with String Arrays Str0-7. See the "Multiple Substrings" subtopic for details.

See also Macro Overview, Macro Arrays Buf0-Buf7