Return to Wilcox Associates, Inc. Home Page

Created on: September 24, 2002
Last modified: July 16, 2008

Subroutines Examples

A subroutine is a very useful tool that allows you re-use code without having to write it each time in your program. Subroutines can either be internal or external to a part program. Consider these examples:

Construct a square slot using a subroutine.
Subroutine that parses a string.

Example 1: (Construct a square slot using a subroutine)

This example contains two part programs and uses a subroutine to construct a generic square slot feature. The first part program contains the subroutine calling statement, and the second part program contains the actual subroutine.

Note that the code provided in these examples provides several document (or programmer) comments detailing what's happening in both the calling part program and in the subroutine.

The Calling Part Program

Step 1: First we'll measure four lines that represent the four edges of the slot. Line one will start with one of the long sides, then line two will be a short side, line three will be the second long side, and line four will be the second short side.

$$ NO,These are the four lines to pass to the subroutine. They make up the sides of the slot. ,The first line, LIN1 should be one of the long sides of the slot, this is because PC-DMIS ,uses this feature's IJK for the slot's IJK. LIN1 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<55.337,16.758,-0.287>,<0.7071068,0.7071068,0> ACTL/<55.337,16.758,-0.287>,<0.7071068,0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<55.337,16.758,-0.287>,<0.7071068,-0.7071068,0>,<55.337,16.758,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<76.268,37.689,-0.287>,<0.7071068,-0.7071068,0>,<76.268,37.689,-0.287>,USE THEO=YES ENDMEAS/ LIN2 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<79.662,39.527,-0.287>,<0.7071068,-0.7071068,0> ACTL/<79.662,39.527,-0.287>,<0.7071068,-0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<79.662,39.527,-0.287>,<-0.7071068,-0.7071068,0>,<79.662,39.527,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<85.884,33.305,-0.287>,<-0.7071068,-0.7071068,0>,<85.884,33.305,-0.287>,USE THEO=YES ENDMEAS/ LIN3 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<84.046,29.911,-0.287>,<-0.7071068,-0.7071068,0> ACTL/<84.046,29.911,-0.287>,<-0.7071068,-0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<84.046,29.911,-0.287>,<-0.7071068,0.7071068,0>,<84.046,29.911,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<63.115,8.98,-0.287>,<-0.7071068,0.7071068,0>,<63.115,8.98,-0.287>,USE THEO=YES ENDMEAS/ LIN4 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<59.721,7.142,-0.287>,<-0.7071068,0.7071068,0> ACTL/<59.721,7.142,-0.287>,<-0.7071068,0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<59.721,7.142,-0.287>,<0.7071068,0.7071068,0>,<59.721,7.142,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<53.499,13.364,-0.287>,<0.7071068,0.7071068,0>,<53.499,13.364,-0.287>,USE THEO=YES ENDMEAS/

Step 2: Next we'll define eight variables, setting each to a value of 0. They will hold the data for the generic square slot that will be constructed.

Step 3: Call the subroutine with the CALLSUB statement:

$$ NO,You'll see the the CALLSUB statement below. ,The first parameter defines the subroutine name, so CONSTRUCT_SQUARE_SLOT ,The second parameter defines an external file path to the part program containing the subroutine. ,It also passes any parameters to the subroutine. ,Notice that the feature IDs must be passed within curly braces. CS1 =CALLSUB/CONSTRUCT_SQUARE_SLOT,D:\PARTPROGRAMS\MYSUBS.PRG:{LIN1},{LIN2},{LIN3},{LIN4},SLTX,SLTY,SLTZ,SLTR,SLTL,SLTI,$ SLTJ,SLTK,,

Things to Note:

The calling statement, CALLSUB, at least in our case here, takes four lines and eight variables and passes them to the subroutine "CONSTRUCT_SQUARE_SLOT".
The calling statement defines the path of the file where the subroutine resides: "D:\PARTPROGRAMS\MYSUBS.PRG:"
It passes all the needed information, into the subroutine as parameters. Note that features must be passed with curly braces {} surrounding the feature ID). Also, note that in order to get information back from a subroutine we must pass it variables within which it can store the data. The slot's XYZ (SLTX, SLTY, SLTZ), the slot's width (SLTW), the slot's length (SLTL), and the slot's IJK (SLTI, SLTJ, SLTK) are all being passed into the subroutine to store the data from the subroutine.

Step 4: Use the returned variables from the subroutine to construct the slot.

So here is our entire part program code:

PART NAME : v43SubroutineExample REV NUMBER : SER NUMBER : STATS COUNT : 1 STARTUP =ALIGNMENT/START,RECALL:,LIST=YES ALIGNMENT/END MODE/DCC FORMAT/TEXT,OPTIONS, ,HEADINGS,SYMBOLS, ;NOM,TOL,MEAS,DEV,OUTTOL, , LOADPROBE/PH9_V42 TIP/T1A0B0, SHANKIJK=0, 0, 1, ANGLE=0 $$ NO,These are the four lines to pass to the subroutine. They make up the sides of the slot. ,The first line, LIN1 should be one of the long sides of the slot, this is because PC-DMIS ,uses this feature's IJK for the slot's IJK. LIN1 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<55.337,16.758,-0.287>,<0.7071068,0.7071068,0> ACTL/<55.337,16.758,-0.287>,<0.7071068,0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<55.337,16.758,-0.287>,<0.7071068,-0.7071068,0>,<55.337,16.758,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<76.268,37.689,-0.287>,<0.7071068,-0.7071068,0>,<76.268,37.689,-0.287>,USE THEO=YES ENDMEAS/ LIN2 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<79.662,39.527,-0.287>,<0.7071068,-0.7071068,0> ACTL/<79.662,39.527,-0.287>,<0.7071068,-0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<79.662,39.527,-0.287>,<-0.7071068,-0.7071068,0>,<79.662,39.527,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<85.884,33.305,-0.287>,<-0.7071068,-0.7071068,0>,<85.884,33.305,-0.287>,USE THEO=YES ENDMEAS/ LIN3 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<84.046,29.911,-0.287>,<-0.7071068,-0.7071068,0> ACTL/<84.046,29.911,-0.287>,<-0.7071068,-0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<84.046,29.911,-0.287>,<-0.7071068,0.7071068,0>,<84.046,29.911,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<63.115,8.98,-0.287>,<-0.7071068,0.7071068,0>,<63.115,8.98,-0.287>,USE THEO=YES ENDMEAS/ LIN4 =FEAT/LINE,CARTESIAN,UNBOUNDED THEO/<59.721,7.142,-0.287>,<-0.7071068,0.7071068,0> ACTL/<59.721,7.142,-0.287>,<-0.7071068,0.7071068,0> MEAS/LINE,2,WORKPLANE HIT/BASIC,NORMAL,<59.721,7.142,-0.287>,<0.7071068,0.7071068,0>,<59.721,7.142,-0.287>,USE THEO=YES HIT/BASIC,NORMAL,<53.499,13.364,-0.287>,<0.7071068,0.7071068,0>,<53.499,13.364,-0.287>,USE THEO=YES ENDMEAS/ $$ NO,These emtpy variables represent the slot's XYZ, Width (R for radius), Length (L),and the IJK direction. ,They are passed empty to the subroutine but are later given values inside the subroutine which are then ,used to create the actual feature. ASSIGN/SLTX=0 ASSIGN/SLTY=0 ASSIGN/SLTZ=0 ASSIGN/SLTR=0 ASSIGN/SLTL=0 ASSIGN/SLTI=0 ASSIGN/SLTJ=0 ASSIGN/SLTK=0 $$ NO,You'll see the the CALLSUB statement below. ,The first parameter defines the subroutine name, so CONSTRUCT_SQUARE_SLOT ,The second parameter defines an external file path to the part program containing the subroutine. ,It also passes any parameters to the subroutine. ,Notice that the feature IDs must be passed within curly braces. CS1 =CALLSUB/CONSTRUCT_SQUARE_SLOT,D:\PARTPROGRAMS\MYSUBS.PRG:{LIN1},{LIN2},{LIN3},{LIN4},SLTX,SLTY,SLTZ,SLTR,SLTL,SLTI,$ SLTJ,SLTK,, $$ NO,==== THIS IS AFTER THE SUBROUTINE ==== $$ NO,Once the subroutine runs, these comments let us check if the values are properly set in the variables. COMMENT/OPER,NO,The Slot's Measured XYZ Values are: ,"X is: " + SLTX ,"Y is: " + SLTY ,"Z is: " + SLTZ COMMENT/OPER,NO,The Slot's IJK Values are: ,"I is: " + SLTI ,"J is: " + SLTJ ,"K is: " + SLTK $$ NO,This is the actual feature creation. $$ NO,GENERIC SQUARE SLOT F1 =GENERIC/SQUARE_SLOT,DEPENDENT,CARTESIAN,IN,$ NOM/XYZ,<SLTX,SLTY,SLTZ>,$ MEAS/XYZ,<SLTX,SLTY,SLTZ>,$ NOM/IJK,<0,0,1>,$ MEAS/IJK,<0,0,1>,$ NOM/IJK2,<SLTI,SLTJ,SLTK>,$ MEAS/IJK2,<SLTI,SLTJ,SLTK>,$ RADIUS/SLTR,SLTR,$ DISTANCE/SLTL,SLTL $$ NO,GREEN - GENERIC ROUND SLOT (VECTOR DOES ROTATE FEATURE) F3 =GENERIC/ROUND_SLOT,DEPENDENT,CARTESIAN,OUT,$ NOM/XYZ,<SLTX,SLTY,SLTZ>,$ MEAS/XYZ,<SLTX,SLTY,SLTZ>,$ NOM/IJK,<0,0,1>,$ MEAS/IJK,<0,0,1>,$ NOM/IJK2,<SLTI,SLTJ,SLTK>,$ MEAS/IJK2,<SLTI,SLTJ,SLTK>,$ RADIUS/0,SLTR,$ DISTANCE/0,SLTL

The Subroutine

In our case the subroutine is an external subroutine, because it resides outside of the calling part program inside a separate part program, called mysubs.prg.

The subroutine is named CONSTRUCT_SQUARE_SLOT. It takes the four line features and the eight variables and calculates the X, Y, Z, (the slot's center), the R (the slot's radius) and the L (the slot's length) of the square slot, as well as the IJK to use, and then it passes all this data back to the original calling part program.

Things to Note:

You must always have the line "SUBROUTINE/" containing the subroutine's name and any parameters. You will need a pathway to the part program containing the subroutine if the subroutine is external to the calling program. Passed in parameters are each seperated by a comma.
You must also always have the line "ENDSUB/" at the end of the subroutine. Any commands following an ENDSUB statement will be ignored.
Every feature, or variable that you pass into a subroutine that you want data back from must also have a unique ID inside the subroutine. They can be the same as the calling program, but that isn't necessary.
Everything that is possible inside a regular part program is also valid in a subroutine.

Here is our subroutine code, contained within the mysubs.prg part program.

$$ NO,This subroutine takes several values, 4 lines and 8 variables and assigns them to variables here. ,These variables must be in the same order as the passed in variables. SUBROUTINE/CONSTRUCT_SQUARE_SLOT, L1 = : PASSED LIN1 FEATURE, L2 = : PASSED LIN2 FEATURE, L3 = : PASSED LIN3 FEATURE, L4 = : PASSED LIN4 FEATURE, X = : PASSED SLTX VAR, Y = : PASSED SLTY VAR, Z = : PASSED SLTZ VAR, R = : PASSED SLTR VAR, L = : PASSED SLTL VAR, I = : PASSED SLTI VAR, J = : PASSED SLTJ VAR, K = : PASSED SLTK VAR, = $$ NO,This is just to show what parameter values are taken by the subroutine. COMMENT/OPER,NO,"PASSED VARIABLE VALUES:" ,L1 ,L2 ,L3 ,L4 ,X ,Y ,Z ,R ,L ,I ,J ,K $$ NO,This creates intersection points where the four lines intersect ,They are used to construct the XYZ center of the slot as well as ,calculate the the length and width (radius) of the slot. PNT1 =FEAT/POINT,CARTESIAN,NO THEO/<0,0,0>,<0,0,1> ACTL/<0,0,0>,<0,0,1> CONSTR/POINT,INT,L1,L2 PNT2 =FEAT/POINT,CARTESIAN,NO THEO/<0,0,0>,<0,0,1> ACTL/<0,0,0>,<0,0,1> CONSTR/POINT,INT,L2,L3 PNT3 =FEAT/POINT,CARTESIAN,NO THEO/<0,0,0>,<0,0,1> ACTL/<0,0,0>,<0,0,1> CONSTR/POINT,INT,L3,L4 PNT4 =FEAT/POINT,CARTESIAN,NO THEO/<0,0,0>,<0,0,1> ACTL/<0,0,0>,<0,0,1> CONSTR/POINT,INT,L4,L1 $$ NO,This gets the centroid (XYZ) of the slot from the entered points ASSIGN/X=(PNT1.X + PNT2.X + PNT3.X + PNT4.X)/4 ASSIGN/Y=(PNT1.Y + PNT2.Y + PNT3.Y + PNT4.Y)/4 ASSIGN/Z=(PNT1.Z + PNT2.Z + PNT3.Z + PNT4.Z)/4 $$ NO,This gets the IJK for LINE 1 and uses that IJK as the slot's IJK ASSIGN/I=L1.I ASSIGN/J=L1.J ASSIGN/K=L1.K $$ NO,This shows the calculated XYZ and IJK values. COMMENT/OPER,NO,"Inside Subroutine:" ,"X is: " + X ,"Y is: " + Y ,"Z is: " + Z ,"I is: " + I ,"J is: " + J ,"K is: " + K $$ NO,These dimensions get the distances between sides. They are used to calculate the Radius and the Length of the slot. ,The smaller distance (DIST1) and the larger distance (DIST2). DIM DIST1= 2D DISTANCE FROM POINT PNT4 TO POINT PNT3 (CENTER TO CENTER),NO_RADIUS UNITS=MM,$ GRAPH=OFF TEXT=OFF MULT=10.00 OUTPUT=BOTH AX NOMINAL +TOL -TOL MEAS DEV OUTTOL M 0.000 0.010 0.010 0.000 0.000 0.000 ---#---- DIM DIST2= 2D DISTANCE FROM POINT PNT4 TO POINT PNT2 (CENTER TO CENTER),NO_RADIUS UNITS=MM,$ GRAPH=OFF TEXT=OFF MULT=10.00 OUTPUT=BOTH AX NOMINAL +TOL -TOL MEAS DEV OUTTOL M 0.000 0.010 0.010 0.000 0.000 0.000 ---#---- $$ NO,These ASSIGN statements pull out the distances, the radius distance (R) and the slot's length (L). ASSIGN/R=DIST1.MEAS/2 ASSIGN/L=DIST2.MEAS COMMENT/OPER,NO,"Radius (R) is: " + R ,"Length (L) is: " + L ENDSUB/ $$ NO,The subroutine ends with the ENDSUB command and execution returns to the calling program. ,Any commands here in this program that follow this ENDSUB are ignored.

Example 2:(Subroutine that parses a string).

This subroutine takes a string and parses it at each "Comma" that the user places inside the string. An example of this would be the string: "80,2.0,0.1,0.1". The string has four numbers in it, each separated by a comma. The following subroutine will parse the string and place each number in its own variable that can then be used anyplace a variable can be used. The current displayed version of the subroutine will parse up to four values in the string, but it can be extended to parse as many values as needed.

The Calling Part Program

The call to the subroutine takes the string to be parsed, the number of items to parse out, and one variable ID for each item being parsed out. This particular example requests from the user the desired "Motion parameter" to be used during the execution of the program.

Step 1: Define four variables to be passed into the subroutine: MS for Move Speed. TS for Touch Speed. PH for Prehit Speed and RT for Retract Speed.

ASSIGN/MS=0 ASSIGN/TS=0 ASSIGN/PH=0 ASSIGN/RT=0

Step 2: Prompt the user with a comment for the needed information.

C1 =COMMENT/INPUT,NO,'Please enter the following "Motion Parameters" ,each value separated by a comma: ,MoveSpeed, TouchSpeed, Prehit, Retract ,(For example, 80,2,0.1,0.1)'

Step 3: Call the subroutine with the CALLSUB command, and send six parameters: the first is the C1.INPUT variable containing the user's string input, second is a number determining how many values are contained in the string input, and the remaining four parameters, are the defined variables which act as holding variables to collect the parsed values.

$$ NO,This calls the PARSE_COMMA_VALUES subroutine contained within the MYSUBS.PRG part program. ,It passes six parameters. CS2 =CALLSUB/PARSE_COMMA_VALUES,D:\PARTPROGRAMS\MYSUBS.PRG:C1.INPUT,4,MS,TS,PH,RT,,,,,$ ,

So, our complete calling code is here:

$$ NO,== Subroutine Example 2 == ,This example parses a string of inputed CSVs. ASSIGN/MS=0 ASSIGN/TS=0 ASSIGN/PH=0 ASSIGN/RT=0 C1 =COMMENT/INPUT,NO,'Please enter the following "Motion Parameters" ,each value separated by a comma: ,MoveSpeed, TouchSpeed, Prehit, Retract ,(For example, 80,2,0.1,0.1)' CS2 =CALLSUB/PARSE_COMMA_VALUES,D:\PARTPROGRAMS\MYSUBS.PRG:C1.INPUT,4,MS,TS,PH,RT,,,,,$ , MOVESPEED/ MS TOUCHSPEED/ TS PREHIT/ PH RETRACT/ RT

Step 4: Once the subroutine finishes parsing the values, we give the motion parameters the appropriate variable values.

The Subroutine

The subroutine receives the input string and all the other parameters, assigning them to local variables within the subroutine. It then enters a WHILE loop to parse out each value based on the location of each comma inside the string. It uses the ELEMENT expression to do this.

ELEMENT(<Integer>, <String1>, <String2>)

This expression returns the nth substring (element) from string2 using string1 as the delimiting text that divides the elements in string2.

The loop runs a total of four times and each time it assigns a value to one of the holding variables until all four contain values.

It then displays an Operator comment displaying all of the values.

Here is our complete subroutine code, contained within the mysubs.prg part program:

SUBROUTINE/PARSE_COMMA_VALUES, STR_INPUT = : THE ENTIRE STRING VALUE THAT WAS PASSED, TOTAL = : THE NUMBER OF VALUES TO LOOK FOR IN THE STRING, S_MS = : THE MS VAR, S_TS = : THE TS VAR, S_PH = : THE PH VAR, S_RT = : THE RT VAR, = ASSIGN/NUM=1 COMMENT/OPER,NO,"NUM is " + NUM ,"TOTAL is " + TOTAL $$ NO,This WHILE/END_WHILE code block loops a number of times equal to ,TOTAL to pull out each of the values inside the passed string. WHILE/(NUM <= TOTAL) COMMENT/OPER,NO,"Loop is now running " + NUM + " of " + TOTAL + " times." SELECT/NUM CASE/1 ASSIGN/S_MS=ELEMENT(NUM,",",STR_INPUT) ASSIGN/S_MS=INT(S_MS) COMMENT/OPER,NO,"CASE 1 Value: " + S_MS END_CASE/ CASE/2 ASSIGN/S_TS=ELEMENT(NUM,",",STR_INPUT) ASSIGN/S_TS=INT(S_TS) COMMENT/OPER,NO,"CASE 2 Value: " + S_TS END_CASE/ CASE/3 ASSIGN/S_PH=ELEMENT(NUM,",",STR_INPUT) ASSIGN/S_PH=DOUBLE(S_PH) COMMENT/OPER,NO,"CASE 3 Value: " + S_PH END_CASE/ CASE/4 ASSIGN/S_RT=ELEMENT(NUM,",",STR_INPUT) ASSIGN/S_RT=DOUBLE(S_RT) COMMENT/OPER,NO,"CASE 4 Value: " + S_RT END_CASE/ DEFAULT_CASE/ END_DEFAULTCASE/ END_SELECT/ ASSIGN/NUM=NUM+1 END_WHILE/ COMMENT/OPER,NO,"The values are:" ,"Move Speed:" + S_MS ,"Touch Speed:" + S_TS ,"PreHit Speed:" + S_PH ,"Retract Speed:" + S_RT ENDSUB/

Back to Hints