Working with strings in ZPL Macros

Also available in 日本語

This article describes how to use strings and the string related capabilities of ZPL.

Authored By Andrew Locke

Introduction

The Zemax Programming Language (ZPL) is a versatile scripting language that can be used to greatly enhance the built-in capabilities of OpticStudio. One of the many things it supports is the use of string variables, which have the ability to:

• Work with non-numeric surface data such as glasses, coatings and comments
• Change the name of a file
• Determine the lens units being used in a file
• Reduce repetitive text entry in a macro
• Customize labels for data analysis summaries and plots
• And more

This article will introduce you to ZPL string variables, string operations, string logical operators and string functions.

String variables

String variables are similar in concept to numeric variables in ZPL. The primary difference is the numeric variables are used to store numeric data while string variables are used to store alphanumeric text data (alphabetical characters and/or numbers). All ASCII symbol characters (except double quotation marks) can be stored in string variables as well. Each string variable can hold up to 260 characters.

String variables can be declared just like numeric variables except for one important difference. All string variables must have a $ (dollar sign) character at the end of the string variable name.

For example, imagine that you wanted to assign the text “The optimized spot size at surface 9” to a string variable. The corresponding macro command would be:

A$ = "The optimized spot size at surface 9"

Note that a literal string must be surrounded by double quotation marks when assigning the string to a string variable.

String operations and the PRINT keyword

Multiple strings can be concatenated (combined) together using the + (plus) operator. This operator can be used to combine multiple string variables, multiple literal strings or a mixture of string variables and literal strings together. Remember, literal strings must be surrounded by double quotation marks.

Here is an example of a string variable and a literal string concatenated together into another string variable:

units$ = "millimeters"
B$ = "The optimized spot size at surface 9 in " + units$

A PRINT keyword can then be added to output the concatenated string. The following macro code:

units$ = "millimeters"
B$ = "The optimized spot size at surface 9 in " + units$
PRINT B$

will output:

String variables and literals can also be combined directly by the PRINT keyword. Strings to concatenate in the PRINT command are separated by , (commas), you can’t use the “+” operator when concatenating directly in PRINT statements. For example:

units$ = "millimeters"
PRINT "The optimized spot size at surface 9 in ", units$

will also output:

String logical operators

ZPL can be used to evaluate string variables in many of the same ways that numeric variables can be evaluated. This includes applying logical operators to compare strings.

Note: All string logical operators begin with a $ (dollar sign) character.

The available types of logical operations that can be used are:

• A$ $== B$ (returns 1 (true) if the A$ and B$ strings are identical)
• A$ $> B$ (returns 1 if A$ is greater than B$)
• A$ $< B$ (returns 1 if A$ is less than B$)
• A$ $>= B$ (returns 1 if A$ is greater than or identical to B$)
• A$ $<= B$ (returns 1 if A$ is less than or identical to B$)
• A$ $!= B$ (returns 1 if A$ is not identical to B$)

The process of comparing whether two strings are identical or not is straightforward. For example, imagine that you have two strings, one is the text “ABC” and the other is the text “DEF”. Obviously, these strings are not equivalent as the following macro shows:

A$ = "abc"
B$ = "def"
PRINT "A = ", A$
PRINT "B = ", B$
IF (A$ $== B$) THEN PRINT "A is identical to B"
IF (A$ $!= B$) THEN PRINT "A is not identical to B"

and the resulting output is:

On the other hand, if the two strings to compare are the same:

A$ = "abc"
B$ = "abc"
PRINT "A = ", A$
PRINT "B = ", B$
IF (A$ $== B$) THEN PRINT "A is identical to B"
IF (A$ $!= B$) THEN PRINT "A is not identical to B"

then the resulting output is:

For the greater than and less than based string logical operators, the rule of comparison that is applied is effectively ASCII order.  "A" is less than "Z" which is less than "a" which is less than "z" and so on, as this macro shows:

A$ = "z"
B$ = "a"
PRINT "A = ", A$
PRINT "B = ", B$
IF (A$ $<= B$) THEN PRINT "A is less than or identical to B"
IF (A$ $>= B$) THEN PRINT "A is greater than or identical to B"

and the resulting output is:

Again, it is the alphabetic order in which the two strings would be listed that matters, not the number of characters as this macro shows:

A$ = "D"
B$ = "AAAAAAA"
PRINT "A = ", A$
PRINT "B = ", B$
IF (A$ $<= B$) THEN PRINT "A is less than or identical to B"
IF (A$ $>= B$) THEN PRINT "A is greater than or identical to B"

which produces:

String functions

String functions are similar to numeric functions in OpticStudio. Both types of functions return data. The fundamental difference is that numeric functions return numeric data while string functions return alphanumeric data. Like numeric functions, the name of each string function must be followed by an open then closed parenthesis. In the case of some string functions, one or more arguments will be required between the two parentheses.

Note: All string functions begin with a $ (dollar sign) character.

Many string functions are used to return information about the currently loaded lens file. There are also string functions which can be used to parse string variables stored in the same macro that the string function is called. A list of all the string functions available in ZPL is in the “String functions” section of the OpticStudio help file located here: “The Programming Tab...About the ZPL...String Functions”

An example of a string function that returns information about the currently loaded lens file is the $GLASS(i)function. This function returns the glass name of the i^th surface.

If this macro:

A$ = $GLASS(3)
PRINT "The glass on surface 3 is ", A$, "."

is run with the OpticStudio sample file {Zemax}\Samples\Sequential\Objectives\Cooke 40 degree field.zmx loaded, the resulting output would be:

which corresponds to what can be seen in the Lens Data Editor:

The LEFTSTRING(A,n) is a good example of a string function which can be used to parse string variable data. This function will return the n leftmost characters in a string. (Similarly, there is also a RIGHTSTRING(A,n) which returns the n rightmost characters in a string.) For example, the macro:

A$ = "programming"
B$ = $LEFTSTRING(A$,4)
PRINT A$, " becomes ", B$

will output: