Macro String Functionality in SmartCAM

Technote 158
Date: 06/97
Product: All Applications
Version: v10x and up

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

Note: There are additional string functions in more recent versions of SmartCAM, this technical bulletin lists the functions that should work in all versions from v10.x on up. For information on more recent string functions see the SmartCAM Customization Guide, Automating SmartCAM with macros; and Learning SmartCAM, Automating SmartCAM. Both are available from your application using Help - Online Manuals.

Procedures:

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, any key to continue."]
ENDIF

// Alternatively, using the string directly:
IF(STRLEN("teststring")<>20)
READOUT[TX="String is not the correct length, 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, any key to continue"]
ENDIF

IF(STREQUAL(#mysub,"string")=1)
READOUT[TX="Sub-string is ok, 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"]
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"]
ELSE
READOUT[TX="File does not exist"]
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.