It is currently Mon Apr 22, 2019 1:42 pm

All times are UTC - 8 hours [ DST ]

Post new topic Reply to topic  [ 1 post ] 
Author Message
 Post subject: Unit 2 - Lesson 6: Expressions - Symbol Names
PostPosted: Sat Jun 18, 2011 7:32 am 
User avatar

Joined: Wed Nov 17, 2010 8:37 am
Posts: 136
Real Name: Terry L. Wiechmann
Began Programming in MUMPS: 0- 0-1971
This lesson covers Symbol Names. As stated, Symbol Names (or variables) provide a way to symbolically access data in a MUMPS system. There are five types listed in the guide. They are:
  • Local Variables
  • Global Variables
  • Special Variables
  • Extrinsic Variables
  • Structured Special Variable Names
Three variable types are covered in this lesson: (Simple) Local Variables, Special Variables and Structured Special Variables.

The Local and Global Variables are elaborated upon in the next lesson. They are identical in structure. They are implemented as sparse arrays with string subscripts. The difference is that local variables reside in the process space and live as long as the process does. Global Variables reside persistently on disk and live until killed. Arrays provide a structuring mechanism for organizing data strings. They form the MUMPS database and are considered to be the one defining feature of MUMPS.

Extrinsic Variables contain two types.
  1. Those written by the application programmer using the MUMPS language ($$ prefix) and
  2. those written by the MUMPS implementer at the system level($& prefix).

Note: We haven't covered Functions yet, however, it is important to point out the difference between a function and special variable. Functions have parameters that are passed into its context and Special Variables do not. They both pass a value back to the caller. It's as simple as that.

An Extrinsic Variable with the $& prefix is a namespace reserved for MUMPS implementers to implement a specialized variable (or function). Traditionally, older MUMPS systems used the prefix ā€œZā€ on names to namespace implementation specific functions and special variables. However, the $& prefix now permits the implementer to access external functionality in a more well defined way.

Note: MUMPSV1 makes use of this mechanism rather than using the traditional Z prefix. Check out the list at Are there any Extrinsic Variables in the list?

Review the list of Special Variables outlined in the student guide. You will learn these variables by using them. It is important that you know what is available at this point.

Exercise 1

Use the implementation specific programming guide and the direct mode WRITE command to display and become familiar with the remaining Special Variables. Note that they contain information that may be important for error processing covered below. Review all implementation specific Special Variables (Z prefix) if they exist for the system you are using. Additionally, look at all Structured Special Variable Names (SSVN).

Note: Do not try the transaction processing Special Variables. They are part of a larger mechanism.

Error Processing

Some of the more important Special Variables are for error processing. Error processing is an extremely important part of application programming. They are:
  • $ECODE
  • $ETRAP
  • $STACK
Also, the $STACK function is important.

The $ECODE Special Variable is used to invoke an error trap and to pass error information back to the previous call level. It can be set by the MUMPS system when it encounters an error condition or the application programmer to process a condition.

When set by the system, it will contain one or more error codes. They may begin with an M or Z. M codes are standard and are listed in section 6.4.3 of the Pocket Guide. Z codes are implementation specific and are listed in the implementation specific manuals.

Often, the application program will run into an error condition that necessitates some action. Codes that begin with U are for that purpose. These codes are typically well defined by your organization for consistency across all applications. As the application programmer you can set the $ECODE variable to invoke error trapping.
Note that it is the act of setting the $ECODE variable with some non-null value that triggers the trap.

$ETRAP variable is used to define a line of code to be executed in the event that $ECODE contains a non-null value. Every time you execution a DO or XECUTE command, it creates an entry on the interpreter stack. You can push the current value of $ETRAP to the stack using the NEW command and then set $ETRAP to a line of code to be executed at the new level. So once $ECODE contains a non-null value, the code defined at the last level is executed. Once the code hits an explicit or implied QUIT, the next level is executed.

Often your organization will have predefined error processing code for you to use. Additionally, the MUMPS vendor often supplies a utility that can be used. For example, Cache and MUMPSV1 provide the %ET routine. Take a look at it.

IMHO, writing Error Processing programs (or using and existing set) is a first priority for an application programmer. It should be the first thing you do.

Exercise 2

Create a new routine that looks like this:

xxxETRAP ;
   ;Example Error Processing Routine
   New $ETRAP
   Set $ECODE=""
   Set $ETRAP="Do Error"
   Do Level1
Level1 ;
   New $ETRAP
   Set $ETRAP="Do Error1"
   Do Level2
Level2 ;
   New $ETRAP
   Set $ETRAP="Do Error2"
   ;Cause error here
   Set $ECODE="U2"
Error ;
   Write !,"Error Level 0 (entry level)"
   Write !,$ECODE,!
Error1 ;
   Write !,"Error Level 1"
   Write !,$ECODE
Error2 ;
   Write !,"Error Level 2"
   Write !,$ECODE

This is a shell routine that you can use to demonstrate how error trapping works. Replace the code at Level2+4 to demonstrate different errors. The goal is to show how errors can be processed at each stack level. Use the WRITE command to write $ESTACK and $STACK variable contents out within the appropriate error subroutine. Play with it.

Terry L. Wiechmann

Offline Profile  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 1 post ] 

All times are UTC - 8 hours [ DST ]

Who is online

Users browsing this forum: No registered users and 1 guest

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
Theme created