M Tutorial

(Part 1)

By

Chris Bonnici

This section of MWM is a tutorial on M. You may have already read how efficient and fast it is; well why not try it out for yourself. It's as easy as they say. This tutorial assumes no knowledge of programming whatsoever. If you missed out the previous issues, you will find them listed in the index. As from this issue we have renamed this page. Previously it was called Teach You, Teach Me. If you look our back issues, please look for this tutorial under its old name.

Our tutorial is based on the Student version of Micronetics Standard M (MSM/Student). For more information about this company jump over to their web page. Micronetics is listed in our Thank You page. Drop them an e-mail to let them know that you appreciate their contribution. In order to download a copy of this program check out Chris Bonnici's Download M section. Before you leave this page be sure to bookmark it so that you can find your way back with ease. For a free subscription to MWM click the Subscribe button on top.

If you have any comments or questions we are here to help. Your input could be in the form of general comments giving us the green light, hitting the expand-topic button and even taking us back a step or two.

No two people will generate the same solution to a problem. We welcome any code you send in, be it different approaches to what we present here or other code of your choice. All accepted submissions will be prominently displayed in MWM.

Last time we delved into procedures (or as they are also called routines). In this issue we will be looking at their close cousins, functions.

Click here to download this issue's routines

What is a Function?

A procedure can normally be defined as a doer. When your program calls up a procedure, the called procedure does something. When it finishes control returns to the calling module. A function has the same characteristics of a procedure plus the added capability of returning a value to the calling module. For those who might be familiar with OOP, one can look at a function as an object whose parent is a procedure. The function has all the characteristics of a procedure plus that added extra.

FUNC001Þ;Program demonstrates function calls - June 1997
Þ;M Web Magazine @ http://www.geocities.com/SiliconValley/7041/mwm.html
Þ;You are using this program at your own risk
Þ;
ÞW #
ÞW /CUP(2,10),"*** Procedure Call"
ÞD GETPNME
ÞW /CUP(5,1),PNAME
ÞW /CUP(12,10),"*** Function Call"
ÞS FNAME=$$GETFNME
ÞW /CUP(15,1),FNAME
ÞQ
Þ;*** EOR ***
GETPNMEÞR /CUP(3,1),"Enter Name: ",PNAME
ÞQUIT
Þ;*** EOR ***
GETFNME()ÞN NAME
ÞR /CUP(13,1),"Enter Name: ",NAME
ÞQUIT NAME

In FUNC001 we demonstrate the difference between a function and a procedure. From the top module, procedure GETPNME is invoked using a DO. Within the body of the procedure we get a name which we store in PNAME. Since PNAME is not encapsulated in the procedure it will also be available in the calling module (from where we output this variable.

On closer inspection, we will observe that the function GETFNME is invoked differently from a procedure call; it is handled as if it were a normal variable. This defines the characteristic mark of a function; its ability to return a value to the calling module. Observe that the function name must be proceeded by a $$. This allows MSM to evaluate that it will be dealing with a function (and not a variable). Also observe that the function label must be followed by brackets (). How does the function return a value? Rather than exit the called module with a solo QUIT, the function’s QUIT must be followed by the value to be returned. In out example this is the QUIT NAME.

You will notice how nicely the function is designed to return a value. The procedure is very clumsy in this respect. Support for this claim can be seen in FUNT002.

FUNC002Þ;Program demonstrates function calls - June 1997
Þ;M Web Magazine @ http://www.geocities.com/SiliconValley/7041/mwm.html
Þ;You are using this program at your own risk
Þ;
ÞW #,/CUP(1,$$MIDCOL^IOLIB("Add 'em Up")),"Add 'em Up"
ÞS TOTAL=$$^ADD2NUMS
ÞW /CUP(7,5),"Total :",TOTAL
ÞQ

In this program you can observe how well the function integrates into the WRITE instruction on top. While this might look more compound (and therefore more complex), it is quite simple. It might help if you extracted each component out of the bracket pairs, always remembering that the leftmost open bracket -(- will have it’s companion -)- at the rightmost position on the line.

In FUNC002 we are also using the top WRITE to show you how one would call a function held within a library. In effect it is quite similar to what we said when we talked about procedures last time.

The line S TOTAL=$$^ADD2NUMS will store the value returned by the function in the variable TOTAL. (Cool isn’t it). Since this function is stored in a separate file, we must let MSM know and thus (as we did in the case of procedures), precede the name by the claret (^) symbol. Note that the ^ goes before the function name and not before the $$.

Function ADD2NUMS is listed here.

ADD2NUMS()Þ;Prompts the user for two numbers and returns to the calling module their addition - ACB - May 1997
Þ;M Web Magazine @ http://www.geocities.com/SiliconValley/7041/mwm.html
Þ;You are using this program at your own risk
Þ;
ÞN NUM1,NUM2
ÞR /CUP(3,5),"Enter the first number: ",NUM1
ÞR /CUP(4,5),"Enter the second number: ",NUM2
ÞD SHOWMSG^IOLIB("Thank You")
ÞQ NUM1+NUM2

In MWM003, we created the library routine IOLIB. Today we added a new function called MIDCOL that return the column position so as to center the phrase passed as a parameter. Last time we claimed that one of the benefits of having libraries is that when we update (improve) them all programs that call upon them will automatically reflect this improvement. This is being demonstrated here. We’ve taken IOLIB and made some alterations to SHOWMSG (it now calls $$MIDCOL for the center point). Try running the programs that were distributed with MWM003. You should notice no difference in their operation even though the underlying code is now different.

IOLIBÞ;Input / Output Library Routines
Þ;M Web Magazine @ http://www.geocities.com/SiliconValley/7041/mwm.html
Þ;You are using this program at your own risk
Þ;
Þ;Displays a message in the middle of line 23. Waits for user input, Clears the line and exits - ACB - May 1997
Þ;The centering is being handled by function MIDCOL - ACB - June 1997
SHOWMSG(MESSAGE)Þ N ERR
ÞW /BEL,/CUP(23,$$MIDCOL(MESSAGE)),MESSAGE
ÞR *ERR
ÞW /CUP(23,1),/EL(2)
ÞQ
Þ;*** EOR ***
HELPLINE(MESSAGE)Þ;Animates the Line Display - ACB - May 1997
ÞF I=1:1:79 W /CUP(24,79-I),/EL(2),$E(MESSAGE,1,I) H:I#40=0 1
ÞQ
Þ;*** EOR ***
Þ;Returns the column position that will cause MESSAGE to be centered on an 80 column screen - ACB - June 1997
MIDCOL(MESSAGE)ÞQ (80-$L(MESSAGE))\2

Alter FUNC002 so that it works exclusively with procedures.

Try writing other functions that will subtract, multiply and divide two numbers.

Write a new program that will prompt the user for the math operator. Depending on the operator entered the appropriate function will be called to return a value.

In FUNC002 could we have changed the two lines
ÞS TOTAL=$$^ADD2NUMS
ÞW /CUP(7,5),"Total :",TOTAL
into the single statement
ÞW /CUP(7,5),"Total :",$$^ADD2NUMS
and the answer would have come out the same? Try altering this program. What is the problem?

From the Try It example above, you should get a fairly good understanding of how M works when it executes a line which contains a function. By the way, other programming languages also muck up in a practically similar manner when confronted with such a problem.

E&OE