Designing the Macro

This section outlines the development process of a macro, in broad strokes. Fundamentally, the programmer needs to determine what inputs are required for the macro to function, what outputs are expected, and what potential issues may arise; then create a high-level description of how the macro will operate.

Inputs

What information does the macro need to be successful? Since this macro will step through an open Process Model file, looking for Step geometry and summarizing the Step geometry lengths into an output file, we have two of the requirements described.

An open Process Model
If there is no open Process Model, this macro cannot do anything.
An output file Path and Filename
This is where the ASCII text report will be created.

Outputs

What outputs and feedback are needed by the macro?

Done message
A message indicating the macro has been completed.
ASCII Report File
This is the primary output: the ASCII text file with the summarized lengths.
Error messages
Will need error messages for any problems encountered during the macro's execution.

Issues

Consider the types of issues that may be encountered when running the macro. Figure out, ahead of time, how they will be handled.

No Step Geometry
In this case, there is an open Process Model. However, it only contains wireframe geometry.
Output File Problems
The given output filename may be invalid, incomplete, or write-protected.

Macro Design

Before starting to code, it is a good idea to have an understanding of how the macro will work. There are many ways to present and organize this information. This tutorial will use a process called Pseudocode.

Pseudocode is based on the terms pseudo and code, and it means fake code. It is a compact and informal high-level description of a program, using a similar structure to the final program but without adhering to all the syntax and semantic conventions of the language. It is a natural language description of the program flow.

Pseudocode allows the programmer to work through the macro solution before attempting to code it. If a programmer cannot describe the solution, they cannot effectively implement it. Additionally, once written, the programmer can envision how the macro will work in practice and test to ensure the design is correct and will function as intended.

For example, the following pseudocode:

IF counter is larger than the total number of elements in the database
   Display an error: Element counter exceeded
ELSE
   Add 1 to the counter
ENDIF

This pseudocode could be translated into the following actual MCL statements.

IF (#COUNTER > TOTEL())
   PAUSE[TX="Element counter exceeded."]
ELSE
   #COUNTER = #COUNTER + 1
ENDIF

The following pseudocode describes the macro to be developed. This is a high-level description of the solution. Many technical details need to be addressed, and they will be covered in the next topic, which is where the macro is written. Additionally, this is one of many possible methods that could be used to get the same result. This approach was chosen because it is conceptually straightforward to implement.

When creating the pseudocode for a macro, always refer to your list of Inputs, Outputs, and Issues. If these are not all addressed in the pseudocode, they likely won't be addressed in the macro itself.

// Check that a process model is loaded. If not error out
IF last element number is 0, no file is loaded
   Display error: Must have an open PM model with geometry
   Exit macro
ENDIF
			
// Make sure the output file path is valid and usable. Otherwise no point in continuing
IF outputfile can not be opened for Writing
   Display error: Output path invalid or read-only. Try another path
   Exit macro
ENDIF

// The main routine.
LOOP through entire database, starting at element 1
   Is current element a step?
	  IF Yes:
		 Get Step number and description
		 
		 // Don't check the same Step number more than once
		 Is Step number already checked?
		 IF No,
			Add Step and Description to list of checked steps
			
			// From the current Element position, check each remaining element and see if it is the
			// same step number as current
			LOOP from current element to End of Elements
			   Check each element
			   IF Layer
				  skip
			   ENDIF
			   IF Step
				  Get Step number
				  IF Step matches current Step
					 Get length and add to running total
				  ENDIF
			   ENDIF
			END LOOP
		 ELSE
			// Step is already checked, skip it and move to the next element
		 ENDIF
   ELSE If No
	  Nothing to do, move to next element
   ENDIF
END LOOP

// Output the results
OPEN the output file for writing
LOOP through the steps found
   Write the Step, Description, and accumulated length for step to output file
   Add Step accumulated length to total accumulated length
END LOOP
Write Total Accumulated length to output file
CLOSE the output file

// Macro finished
Display message: Macro complete.

The concept for this macro is simple. Starting at the first element in the database, check each element until the end of the database is reached. For each element, ignore it if it is a layer. If it is a Step, get the Step ID and Description. Keep a running list of Steps that have already been checked. If the newly found Step is in the list, skip it and move to the next element in the database.

If the Step has not already been checked, create an inner loop (a loop nested in the primary loop) that checks the database from the current position to the end of the file. For every element that uses the same Step, get the length and add to the total for that Step.

The following will help explain this algorithm. It is a simple representation of a small Process Model database.

El. 1 - Layer 1
El. 2 - Step 10
El. 3 - Step 10
El. 4 - Layer
El. 5 - Step 20
El. 6 - Step 20

The macro will create a main loop that checks each element from 1 to 6.

Element 1 is a layer and is skipped.
Element 2 is Step 10. Step 10 has not been checked yet. The length of Element 2 is collected and saved. A small loop will now check from Element 3 (Current element + 1) to Element 6.
Element 3 is Step 10, so its length is added to the running total for Step 10.
Elements 4 through 6 are not Step 10, so they are skipped. The small inner loop is complete.
The main loop increments to Element 3. It is Step 10; since Step 10 has already been checked, it is skipped.
Element 4 is a layer and is skipped.
Element 5 is Step 20. Step 20 has not been checked. So the length of Element 5 is added to the running total for Step 20. A small loop is set up to check from Element 6 (Current element + 1) to the end of the process model. In this case, a loop from 6 to 6, or one element.
Element 6 is checked. It is Step 20, so the length is added to the running total for Step 20. There are no other elements to check, so the small inner loop ends.
The main loop continues. The next element checked is Element 6. This is Step 20, which has already been checked, so it is skipped.

There are no other elements to check, so the main loop ends and the output is created.