SmartCAM Technical Bulletin: 236
Announcing

Topic: Macro functions in SmartCAM

Technote 236
Date: December 2008
Product:All SmartCAM Applications
Version: v15.x and up

This is an updated version of technote 158. The previous technote is in the archives and still available, but if you are using versions 15.x and up, this is the appropriate technote.

  • Logic AND/OR functions
  • Testing for string length
  • Display of multi-line string in Pause window
  • Extracting sub-strings from existing strings
  • Compare string contents to a known value
  • Concatenating several strings together into one
  • AND/OR functions

    In the past these operators required the use of ',AND' or ',OR'. For those familiar with many standard programming languages these are the symbols '&&' or '||'. The older method is still available, but the new, more common method is also.

    // Consider the following IF statement.
     IF(#V1=1 ,AND #V2=1)

    // The following is equvalent.
     IF(#V1=1 && #V2=1)

    // And same for the OR operator.
     IF(#V1=1 || #V2=1)

    Testing for String Length

    You can obtain the length of a string and assign it to a variable or use it as a testing tool. The string can be directly used, or can be accessed by using the variable name it has been assigned to, as in the following examples:

    // All string variables need to be defined as such at the beginning of 
    // the macro. And assign a string value to the variable #mystr:
    STRING: #mystr = "teststring"
    
    // This string has a length of 10 characters.
    // You can evaluate this length and assign the number to another variable using the STRLEN 
    // function in two ways: use the original string or use the variable name:
    #strlength = STRLEN(#mystr)
    #strlength = STRLEN("teststring")
    
    // Either way, the variable #strlength now has a value of 10.
    
    // Also, you can use the string length directly - without evaluating it to another variable - 
    // for testing. In this case: if the length of the string stored in #mystr is not equal to 
    // 20 characters, then display the following message in the readout line:
    IF(STRLEN(#mystr)<>20)
      READOUT[TX="String is not the correct length - hit any key to continue."]
    ENDIF
    
    // Alternatively, using the string directly:
    IF(STRLEN("teststring")<>20)
       READOUT[TX="String is not the correct length - hit any key to continue"]
    ENDIF

    Display of Multi-line String in Pause Window

    You can include line feed characters within the string itself, and have those line feeds become active when the string is output in a pause window command. The following examples illustrate this behavior:

    // Define the string variable:
    STRING: #mystr
    
    // Assign a string value to the variable #mystr: 
    // Note that the '\n' is seen as one character - the line feed character.
    #mystr = "This is a test\n
    of the multi-line\n
    string output function."
    PAUSE[TX=STRTMP("%mystr")]
    
    // This also works using the string directly, with no variable assignments:
    PAUSE[TX="This is a test\n
    of the multi-line\n
    string output function."]
    
    // Starting with SmartCAM v14.5, you do not need to split up the multi-line
    // strings by ending each line with the \n character. You can embed the
    // newline in the string
    PAUSE[TX="This is a test\nof the multi-line\nstring output function."]

    Extracting Sub-Strings from Existing Strings

    Version 10.0 allows you to extract a sub-string of any length and starting with any character within an existing string. The syntax follows the form of naming the original string, naming the starting character number of the partial string to be extracted, then giving a length of the string to be extracted. The following text provides working examples of this function:

    // Define the string variables:
    STRING: #mystr = "Original string"
    STRING: #mysub
    
    // Extract a sub-string starting with the tenth character and having a
    // length of six characters:
    #mysub = MID(#mystr,10,6)
    READOUT[TX=#mysub]
    
    // This returns the value of #mysub in the readout line - here it would
    // be "string"
    // since the tenth character in #mystr is the 's' and the six character length,
    // which includes this starting character would take the sub-string to the 'g'.
    
    // Note that if you were to extract a sub-string starting with the tenth
    // character and having a length of ten characters (past the end of the original 
    // string), the resulting sub-string would consist of only as many characters as 
    // the original string had to fill it. Here, the value of #mysub would be the 
    // same. The next lines illustrate another example of this:
    #mystr = "A short String"
    #mysub = MID(#mystr,10,26)
    READOUT[TX=#mysub]
    
    // This returns a value of "tring" to the readout line.
    
    // These functions are also available using the actual string itself, without
    // any variable assignments.
    #mysub = MID("Original string",10,6)
    READOUT[TX=#mysub]

    Compare String Contents to a Known Value

    You can compare the value of a string variable to that of a known or existing string. This is useful for testing the contents of a string and performing other operations based on that result. The following illustrates this function:

    // Define the string variables:
    STRING: #mystr = "Original string"
    STRING: #mysub
    
    // Extract a sub-string starting with the tenth character and having a
    // length of six characters:
    #mysub = MID(#mystr,10,6)
    
    // Test the contents of the sub-string against what we would like it to be:
    IF(STREQUAL(#mysub,"string")<1)
       READOUT[TX="Sub-string does not check out - press any key to continue"]
    ENDIF
    
    IF(STREQUAL(#mysub,"string")=1)
       READOUT[TX="Sub-string is ok - press any key to continue"]
    ENDIF
    
    // Test the contents of the sub-string against what we know it shouldn't be.
    
    // Note the capital 'S' in the string to compare the variable to:
    IF(STREQUAL(#mysub,"String")<1)
       READOUT[TX="Sub-string does not check out - press any key to continue"]
    ENDIF
    
    // The STREQUAL function is a true/false test. If the strings are identical, the 
    // function will return a value of 1. For any other condition where the strings
    // are not identical, it will return a value of 0.

    Concatenating Several Strings Together into One

    Version 10.0 allows you to put several strings together and assign them as a single entity to a string variable using the STRTMP command. The following examples show how to use this function:

    // Define the string variables:
    STRING: #mystr = "String Number One"
    STRING: #mystr2 = "The SeCoNd string.I wrote."
    STRING: #result
    
    // Add the contents of #mystr and #mystr2 and assign the solution to #result:
    #result = #mystr + #mystr2
    READOUT[TX=#result]

    Information about this, and much more is available on the Learning SmartCAM webpage. In your SmartCAM application select Help - Online Manuals.