_Get_String Macro Subroutine

The _Get_String macro subroutine is one of the Macro Examples and Mini-Apps included with Daqarta. It allows the calling macro to request a string from the user, such as a numerical value. For example, the DaquinOscope macro mini-app uses it to ask the user for the Arduino pin number to be used as an oscillator output.

To use this subroutine, you must first specify one of the Macro String Arrays Str0-Str7 via the Ch Channel Select command, then set it with the desired prompt text before calling _Get_String via the @ prefix:

    Ch=6
    StrV="Pin Number: "
    @_Get_String

Note that the return is a selected portion of a string of text in StrV, between indexes Posn?3-1 and Posn?5-2. These Miscellaneous Position macro values are used here to avoid other common macro variables, to make it easier to add _Get_String to a large macro with many variables. To convert this substring to an integer in Q1, use

    Q1=StrV?E[Posn?3-1,Posn?5-2]

The caller is responsible for validating the value. In the case of DaquinOscope, that includes rejecting pins that are not available for general use on the Arduino, such as pins 0 and 1 which are used for serial port access. It also rejects pins that are already in use by another of the 4 oscillators available.

_Get_String Macro Subroutine Listing:

;<Help=H4923
;On entry, StrV holds string like "Enter value:"
;Ch is set to 0-7 to specify the 'V' in StrV
;Returns with entered text in StrV[Posn?3-1,Posn?5-2]
;Convert to value X via X=StrV?E[Posn?3-1,Posn?5-2]

Posn#3=StrV?N          ;Get length of prompt string
IF.StrV[Posn?3-1]=!"_"         ;Is last character an underscore?
    StrV=StrV + "_"                ;Add as position cursor if not
    Posn#3=Posn?3 + 1              ;Count it
ENDIF.
MsgStyle=TCx               ;Prevent [X] cancel during wait
Msg=StrV                       ;Show the prompt string
Posn#4=0                       ;Entered char
WHILE.Posn?4=!h0D          ;Wait for Enter char
    WaitKey=128                ;Wait for any character
    Posn#4=Key?#                   ;Get entered char
    Posn#5=StrV?N                  ;Size of current string
    IF.Posn?4=8                    ;Backspace key?
        IF.Posn?5=>Posn?3              ;Room to go back?
            StrV[Posn?5-2]=                ;Remove last character
            StrV=StrV + "_"                ;Update cursor posn
        ENDIF.
    ELSE.
        IF.Posn?4=!h0D                 ;Anything but Enter key?
            StrV[Posn?5-1]#1=Posn?4        ;Update entered string
            StrV[Posn?5]="_"               ;Update cursor posn
        ENDIF.
    ENDIF.
    Msg=StrV                       ;Show the new string
WEND.                          ;Wait for Enter key
MsgStyle=TC                    ;Restore [X] to future Msg titles
Msg=                           ;Remove this Msg box and return

See also Macro Overview, Macro String Arrays Str0-Str7