Topic: Macro String Functionality in SmartCAM

Technote 158 Date: June 1997 Product:All SmartCAM Applications Version: v10.x and up
Previous versions of SmartCAM have had very limited string manipulation capabilities within the macro language. The v10.0 release of SmartCAM includes several new options and functions for using strings. Procedure: The new functions can be broken down as follows:

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

Access to long file names and JOS text information

These new macro words and their corresponding syntax formats are also available in the v8.21 Edit Plus that ships with the v10.0 release of SmartCAM. You can find them under Options - Template on the main menu. Once the Template dialog is displayed, set the Type field to MCL Commands and scroll down through the list of template words until you see the string functions.

Testing for String Length
Version 10.0 allows you to 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.
  STRING: #mystr
  // Assign a string value to the variable #mystr:
  #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
Version 10.0 allows you to 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."]

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
  STRING: #mysub
  // Assign a value to the variable:
  #mystr = "Original string"
  // Extract a sub-string starting with the tenth character and having a length of six characters:
  #mysub = STRSUB(#mystr,10,6)
  READOUT[TX=STRTMP("%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 = STRSUB(#mystr,10,26)
  READOUT[TX=STRTMP("%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 = STRSUB("Original string",10,6)
  READOUT[TX=STRTMP("%mysub")]
  #mysub = STRSUB("A short String",10,26)
  READOUT[TX=STRTMP("%mysub")]

Compare String Contents to a Known Value
Version 10.0 allows you to 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
  STRING: #mysub
  // Assign a value to the variable:
  #mystr = "Original string"
  // Extract a sub-string starting with the tenth character and having a length of six characters:
  #mysub = STRSUB(#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: #mystr2
  STRING: #result
  // Assign values to the variables:
  #mystr = "String Number One"
  #mystr2 = "The SeCoNd string.I wrote."
  // Add the contents of #mystr and #mystr2 and assign the solution to #result:
  #result = STRTMP(%mystr%mystr2)
  READOUT[TX=STRTMP("%result")]
  // You can also add literal text to the string variables called in the STRTMP function:
  // Note that spaces entered within the STRTMP command are not retained upon
  // creation of the result string unless they are within double quotes.
  #result = STRTMP("Some literal text and %mystr %mystr %mystr2")
  READOUT[TX=STRTMP("%result")]

Access to Long File Names and JOS Information
The string functions in v10.0 can be used to access and manipulate "outside" information such as long file names on the system or information from JOS planner input fields. The first example assumes that you have created a file in the \sm9\shared\sysmcl\ directory named 'long filename test.mcl' and uses this file with the F_EXIST command to test for file's existance. You could also use this type of logic to store any path and file name information to be used elsewhere as string data.

  // Define the string variables:
  STRING: #lfname
  // Set the anticipated case variable - the F_EXIST function is a true/false test that
  // will return a 1 if the file by the given name exists and return a 0 if no file by that
  // name exists. In this case, we assume that the file to be tested for does exist
  // and set the anticipated case to a 'true' value:
  #case1 = 1
  // set the string variable to the name of the file we are testing for. This data could be a
  // constant file name, or come from a JOS input field:
  #lfname = "long filename test.mcl"
  // test for the existence of a file by that name:
  #case2 = F_EXIST(STRTMP("c:\sm9\shared\sysmcl\%lfname"))
  // Output an appropriate message based on this test:
  IF(#case2=#case1)
  READOUT[TX="File exists - press any key to continue"]
  ELSE
  READOUT[TX="File does not exist - press any key to continue"]
  ENDIF

The second example shows how to access and manipulate a text string obtained from the planner. Any JOS information can be accessed this way, including job notes, tool notes, step notes, etc. The following example takes the job notes field from the current .jof file and outputs the contents in reverse order. This isn't really a practical example, but it does show the possibilities of the new string manipulation functions. It combines accessing JOS data, concatenating strings, and extracting sub-strings as discussed above.

  // Define the string variables:
  STRING: #part
  STRING: #temp
  STRING: #reverse
  STRING: #notes
  // Clear out the value of #reverse by setting it equal to an empty string:
  #reverse = ""
  // Retrieve the job notes from the JOS system as a string:
  JOS_CONTEXT_OPEN[BASEITEM=16,USERNAME=""]
  #notes = JOS_STR(job_note)
  JOS_CONTEXT_CLOSE[]
  // Echo the original job notes to the screen in a pause window:
  PAUSE[TX=STRTMP("%notes"), SR=15]
  // Establish the length of the job notes string #notes:
  #count = STRLEN(#notes)
  // Echo the length of the string to the readout line
  READOUT[TX=STRTMP("%count")]
  // Increment backwards through the job notes string, extracting each character as a
  // sub-string, then reassemble these characters in reverse order into a temporary
  // string variable named #temp:
  WHILE(#count>0)
  #part = STRSUB(#notes,#count,1)
  #temp = STRTMP(%reverse%part)
  #reverse = #temp
  #count = #count-1
  ENDW
  // Echo the result of the reordering to the screen in a pause window:
  PAUSE[TX=STRTMP("%reverse"), SR=15]
  // This will output the job notes of the current job file in exact reverse order.

More examples of all these functions can be found within the \tech_supp directoy on your v10.0 / v11.x CD in the Custom Macro section. The examples provided on this technote are meant as basic introductions to the new string functions in SmartCAM version 10.0. The macro file referenced in the above link provides some more in-depth uses and combinations of these functions, and should be used as a reference for more advanced string evaluations.