Zen and the Art of Macro Writing: Creating Global Programs That Can Be Accessed From Anywhere

1. Zen and the Art of Macro Writing:Creating Global Programs That Can Be Accessed From Anywhere Presented by Brian Schmit July 27, 2010

2. What are Prefixes? Part I Meditech's programming language, MAGIC, uses 10 different characters to connect to databases, printers, terminals, etc. These 10 characters are called Prefixes. They are: $ % # ! / \ & : ? *

3. What are Prefixes? Part II Meditech's NPR Procedures have a general convention for the use of their Prefixes: $ Utility Directory % Current Directory (LIVE.MIS, TEST.5.5.MIS, etc) # Current terminal ! Output device (Printer, Screen, etc) / Private Memory-based temp \ MIS Dictionaries & Current Application Dictionaries : Current Application Data ? Current Application Data * Current Application Data

4. What are Prefixes? Part III The last 3 Prefixes, :, ?, and *, certainly seem redundant since they all appear to open to the same database. However, they are used differently for each Application. You can look to the Procedure Logic for the NPR Procedure APPL.TOOL.BOX.open.prefixes to see the code Meditech uses to open those three Prefixes for each Application (replace APPL with the mnemonic of the Application. For instance, see PHA.TOOL.BOX.open.prefixes to see how those 3 Prefixes are used for the PHA Application) If you plan on using MAGIC code to change Prefix connections, it is recommended that you do NOT use $, %, #, !, /, or \.

5. What are Prefixes? Part IV O is the MAGIC command used to Open a Prefix to a database. C is the MAGIC command used to Close a Prefix connection. C/S is slightly different in their use of Prefixes. Meditech's C/S Programming Language is able to include an Argument with their Prefixes, so they are able to maintain more than 10 Prefix connections at once. For instance, not only is / connected to a Private Memory-based temp, but so are /(.S) and /(.U).

6. What is Z.link? Part I Z.link is a utility program available to Meditech MAGIC Customers. It is designed to accept arguments that will open a specific prefix to a specific database. Meditech NPR Application Databases are broken into two: Data and Dictionaries. They are referred to: %.APPL.data (Data) %.APPL.dic (Dictionaries) You can replace APPL with the mnemonic of any NPR Application, except for NPR. There is only one Application Database for the NPR Application: %.NPR

7. What is Z.link? Part II Here is a sample of how Z.link would be used to connect to your LAB Database: %Z.link("?","LAB","%.LAB.data","LAB.DB")^OLD In this example, the Prefix we specified is "?". The second argument is "LAB" which is the Application mnemonic. The third argument is "%.LAB.data". We use this since we want to connect to the LAB Data, not the LAB Dictionaries. The fourth argument is the mnemonic of the LAB Application Database. This is usually unique to each site.

8. What is Z.link? Part III %Z.link("?","LAB","%.LAB.data","LAB.DB")^OLD This particular use of Z.link will not only connect the "?" Prefix to the LAB Data, but it will also return the previous connection for "?" and store it in a Local Variable called OLD. A Local Variable is just a temporary holding place for a value. It is important to note that Z.link only connects a single Prefix to the database specified, so that database will be available via that Prefix. The Application NPR Procedures are not necessarily available. They would only be available if that Application Database is on your current Segment, or if your current Segment also has your NPR Application.

9. What is Z.link? Part IV Z.switch.appl, which we will go over later, opens all of the necessarily Prefixes to a specific Application, and it also makes all of that Application's NPR Procedures available. When using Z.link within an NPR Report Writer Macro, programmers often make use of the @Chg.prefix and @Res.prefix NPR Programming Macros.

10. What is @Chg.prefix? Part I If you look at the Online Data Definitions on the Meditech website, you will find a column called Offset/Local/VAL. For instance, select the LAB Application, then the LAB.L.SPEC DPM, then the lab.l.specimen.file Segment, and look to the Field called number. You will find the Offset/Local/VAL column to show ?SLS[sls]|0. What this means is that Meditech has set up their LAB.L.SPEC DPM to assume the Prefix ? is connected to the LAB Data.

11. What is @Chg.prefix? Part II Let's suppose we are writing an NPR Report from another Application, such as PHA. The ? Prefix would now be connected to the PHA Data. We can use Z.link to connect a Prefix to the LAB Data. For the sake of this example, let's also assume that we want to use a specific Prefix, such as "*". %Z.link("*","LAB","%.LAB.data","LAB.DB")^OLD, @Chg.prefix(LAB.L.SPEC,?,*), .... ....

12. What is @Chg.prefix? Part III Since our Z.link Procedure uses "*" in this case, we must instruct the rest of our NPR Report Writer Macro to use * in place of ? for any reference to the LAB.L.SPEC DPM.

13. What is @Res.prefix? Part I Once a Prefix is connected to a Database that it is not set up to use, according to the Meditech Data Definitions, then @Chg.prefix can be used to instruct the NPR Report Writer Macro to use a different Prefix. @Res.prefix can be used to instruct the NPR Report Writer Macro to again use the standard Prefix.

14. What is @Res.prefix? Part II @LAB.L.SPEC.number, (now using the Prefix ?) %Z.link("*","LAB","%.LAB.data","LAB.DB")^OLD, @Chg.prefix(LAB.L.SPEC,?,*), @LAB.L.SPEC.number, (now using the Prefix *) @Res.prefix(LAB.L.SPEC,?), @LAB.L.SPEC.number, (once again using the Prefix ?)

15. What is Z.switch.appl? Part I Z.switch.appl will not only connect ALL of the necessary Prefixes to a specific Application's Databases, but it will also make all of that Application's NPR Procedures available for use. %Z.switch.appl("APPL") is all that is necessary to switch from the current Application to the one used the argument in this NPR Procedure. However, it is important to note that the current Application's Data, Dictionaries, and NPR Procedures will not be available after Z.switch.appl is executed.

16. What is Z.switch.appl? Part II %Z.switch.appl("") will switch back to the prior Application, and once again the original Application's Data, Dictionaries, and NPR Procedures will be available again. Here is a simple example of how this can be used: %Z.switch.appl("LAB"), .... %Z.switch.appl("")

17. What is Z.switch.appl? Part III If you have more than one Application Database for LAB, you can instead specify a specific Application Database: %Z.switch.appl("LAB","","","LAB.DB"), .... %Z.switch.appl("")

18. What is Z.link.db? Part I Z.link.db is the C/S equivalent of Z.link, except that it connects all of the necessary Prefixes, instead of just a single one. This will open the Prefixes: %Z.link.db({"APPL.DB"},{"O","B",1}) This will close the Prefixes: %Z.link.db({"APPL.DB"},{"C","",1})

19. What is a DO Loop? Part I A DO Loop is similar to an IF statement, except that a DO Loop repeats itself again and again until the Condition returns a value of nil. Typical format: DO{CONDITION STATEMENT} If the CONDITION returns a non-nil value, then the STATEMENT is executed. Then the CONDITION is checked again for a non=nil value. If it is non-nil, then the STATEMENT is repeated. This process is executed again and again until the CONDITION results in a nil value. If CONDITION never results in a nil value, then the DO Loop will never end. This is known as an Infinite Loop.

20. What is a DO Loop? Part II Here is some simple code that increments a Local Variable called NUMBER by 1. The Loop continues as long as the value of NUMBER is less than 10: 0^NUMBER, DO{@Add(1,NUMBER)<10 I(NUMBER)N^#} Code: 0^NUMBER, Explanation: The value of 0 is assigned to the Local Variable NUMBER.

21. What is a DO Loop? Part III Code: @Add(1,NUMBER) Explanation: @Add is an NPR Programming Macro that increments Argument B by the value of Argument A. In this case, the Local Variable NUMBER is incremented by 1.

22. What is a DO Loop? Part IV Code: @Add(1,NUMBER)<10 Explanation: < is the MAGIC "Less Than" Relational Operator. It requires two Arguments and the Format is: A<B If the value of Argument A is Less Than the value of Argument B, then the value of Argument A is returned. This is our CONDITION. As long as the value of NUMBER is Less Than 10, then this will result in the value of NUMBER which is a non-nil value. When the value of NUMBER is no longer Less Than 10, then a nil will be returned by our CONDITION.

23. What is a DO Loop? Part V Code: I(NUMBER)N^# Explanation: This is our STATEMENT. It is executed as long as the CONDITION returns a non-nil value. I is the Interpreter MAGIC Programming function. It is used in this case to print the value of NUMBER and then append the New Line MAGIC Programming function, N. This code is then assigned to # which is the Prefix connected to your Terminal.

24. What is a DO Loop? Part VI So this code would result in the following being sent to your Terminal screen: 1 2 3 4 5 6 7 8 9

25. What is an MV Array? Part I An MV Array is a table that can be populated with whatever data you like. It is typically used when needing to print out multiple values in user-defined fields. It involves using several different features in the NPR Report Writer. Specifically, we will make use of a Line Attribute, a Footnote to execute a Macro, a Macro, and a user-defined field. Let's suppose we want to simply have our report print out the number (1 through 9) on their lines, as we did in our previous example. Of course we could simply type these numbers out manually on their own lines on the Report Picture. But for the sake of this example, let's do this using an MV Array.

26. What is an MV Array? Part II Step 1: Create a user-defined Field: xx.numbers DAT=PINT LEN=10 VAL="� The code used for our VAL Attribute DOES NOT matter. The actual value printed for our user-defined field will be determined by the values in our MV Array.

27. What is an MV Array? Part III Now let's place this Field on a Detail Region line: D xx.numbers But since we want to print out Multiple values, we must treat this user-defined Field as we would any Mutliple Field from a Child Segment: D xx.numbers D xx.numbers

28. What is an MV Array? Part IV If we were to File our report right now, we would get a message that the report would crash because we would be using a Multiple that doesn't come from a Child Segment. This is true, so far, because our user-defined Field doesn't come from any Child Segment. So, we have to add a Line Attribute to the Detail Region line that has the first xx.numbers. This Line Attribute will appear like this: MV=D For this example, I have chosen the value of D. I can in fact use any value I like, I simply need to make note of it. Some users often simply use the Region that the MV Array will print in. In this case, that is the Detail Region, so let's use MV=D.

29. What is an MV Array? Part V Next, we need to use a Footnote to execute a Report Writer Macro. AL is a Footnote that stands for Algorithm. It is typically used to execute a Macro. We will use the following format: AL D d AL is the Footnote, D is the Region that the Macro should execute immediately before, and d is the Macro name. You can name your Macros whatever you like. They are always lowercase and we typically use periods to separate words. In this case, I am naming the Macro after the Region D.

30. What is an MV Array? Part VI We can now File and Translate our Report. Nothing will print for that user-defined Field since we have not written our Macro yet. Before we do that, though, we must go back to our Report Picture and see what the Field Number is for our user-defined Field. You can find the Field Number to the left of the Field name in the Fields section of your Picture Page/Tab. Let's just suppose it is Field Number 3. Make sure to make note of that. So, we know the value of our Line Attribute (D), the name of our Macro (d), and our Field Number (3).

31. What is an MV Array? Part VII Now we can write our Macro: 0^NUMBER, DO{@Add(1,NUMBER)<10 NUMBER^/MV["D",NUMBER,3]} This code is fairly similar to the code we used in our DO Loop example but there are a few differences. The value of NUMBER is assigned to our MV Array. In MAGIC, the Array is referred to as /MV but in C/S, it is /R.MV.

32. What is an MV Array? Part VIII The Subscripts of the MV Array are within the square brackets. The First Subscript, "D", is the value of our Line Attribute in quotes. The Second Subcript, NUMBER, is a unique value. It must be unique or else one line will be over-written by another. The Third Subscript, 3, is our Field Number. You can then File and Translate this Macro.

33. What is an MV Array? Part IX Whenever you execute a Macro via the Footnote AL in this manner, you must retranslate your report anytime you translate the Macro. You can leave yourself a helpful reminder by adding this line of code to the end of your Macro: @Translate.message("***RETRANSLATE YOUR REPORT***")

34. What is an MV Array? Part X When your report runs, the macro creates an MV Array, and the Line Attribute MV=D instructs the report to put these Values in the place of Field Number 3: Subscripts Value ["D",1,3] 1 ["D",2,3] 2 ["D",3,3] 3 ["D",4,3] 4 ["D",5,3] 5 ["D",6,3] 6 ["D",7,3] 7 ["D",8,3] 8 ["D",9,3] 9

35. Sample Report Part I Let�s write an NPR Report starting from ADM.PAT that includes data from PHA, LAB and OE:

36. Sample Report Part II No changes necessary on Page 1 to include an MV Array:

37. Sample Report Part III No changes necessary on Page 2 to include an MV Array:

38. Sample Report Part IV We will create six user-defined fields: RX #, Med, LAB Test, Result, OE Order #, Procedure:

39. Sample Report Part V Remember, the VAL Attribute can simply equal nil since the values from the MV Array determine what prints. We add the Line Attribute MV=D to the top of the two Detail Region lines: We also add a Footnote to execute our Macro called d:

40. Sample Report Part VI We then File and Translate our report. We go back into our report, to our Fields, and we record the Field Numbers (in this example, they are 3, 4, 5, 6, 7, 8). We now create our macro called d. We need to know how to link ADM.PAT to PHA.RX, LAB.L.SPEC, and OE.ORD.

41. Sample Report Part VII Go to www.meditech.com, click on Customers, Products and Resources Home Pages, NPR Report Writer, Application Specific Info, select Application ADM, Fragment Links.

42. Sample Report Part VIII You will see a list of ADM.PAT Fields that link to other DPMs. ADM.PAT.urn links to PHA.RX.patient, LAB.L.SPEC.patient, and OE.ORD.patient.

43. Sample Report Part IX So, those the are the Fields that we will use to link from ADM.PAT to PHA.RX, LAB.L.SPEC, and OE.ORD. Let�s start our Macro called d: Here is the main body of our Macro: Our first line of code assigns the value of ADM.PAT.urn to the Fields PHA.RX.patient, LAB.L.SPEC.patient, and OE.ORD.patient. We use three Local Macros to run DO Loops that create the MV Arrays.

44. Sample Report Part X A Local Macro is a set of commands that perform a particular function. In this case, we are grouping all of the commands that get the PHA data into a Local Macro called GET.PHA.DATA The Local Macros are separated from the main body of the Macro and other Local Macros by a blank line. Local Macros begin with the title of the Local Macro (in uppercase letters, words separated by periods, and no comma at the end of the line) A Local Macro is executed by preceeding the name of the Local Macro with an @ symbol. The last line of a Local Macro does not end with either a semi-colon or a comma.

45. Sample Report Part XI Z.link connects the Prefix ? to the PHA database. PHA.RX.med uses Prefix ? but Index File pha.rx.patient.index uses Prefix : so we instruct our Macro to use ? in place of with @Chg.prefix.

46. Sample Report Part XII To get the Field PHA.RX.med, we need the Subscript for Segment pha.rx.file, urn. We have the ADM.PAT.urn Field which is linked to PHA.RX.patient. But we need to get PHA.RX.urn. The Index File pha.rx.patient.index has two subscripts: patient and number and a value of urn. We have patient but need urn. The Data Definitions show that another name for pha.rx.patient.index is patient.x.

47. Sample Report Part XIII The NPR Programming Macro @Next will return the Next value of a Subscript from either a Detail Segment or an Index File. @Add(1,COUNT) increments Local Variable COUNT. We then assign the values we want to the MV Array. We reconnect Prefix ? back to its previous connection via the line: ZZ%O(?,OLD)

48. Sample Report Part XIV We now create a Local Macro called GET.LAB.DATA: Z.link connects the Prefix ? to the LAB database. LAB.L.SPEC.result uses Prefix ? but Index File lab.spec.l.patient.index uses Prefix : so we instruct our Macro to use ? in place of with @Chg.prefix.

49. Sample Report Part XV To get the Field LAB.L.SPEC.result, we will need the Subscripts for Segment lab.l.spec.result.tests, urn and test. We have ADM.PAT.urn, which is linked to LAB.L.SPEC.patient Field. But we need LAB.L.SPEC.urn. Index File lab.spec.l.patient.index has five subscripts: patient, collection.date, collection.time, prefix, number.part and a value of urn. We have patient but need urn. The Data Definitions shows that another name for lab.spec.l.patient.index is patient.x.

50. Sample Report Part XVI The NPR Programming Macro @Next will return the Next value of a Subscript from either a Detail Segment or an Index File. @Add(1,COUNT) increments Local Variable COUNT. We then assign the values we want to the MV Array. We reconnect Prefix ? back to its previous connection via the line: ZZ%O(?,OLD)

51. Sample Report Part XVII We now create a Local Macro called GET.OE.DATA: Z.link connects the Prefix ? to the OE database. Z.link connects the Prefix & to the OE dictionaries. OE.ORD.order.num uses Prefix : so we instruct our Macro to use ? in place of with @Chg.prefix.

52. Sample Report Part XVIII To get the Field OE.ORD.order.num, we will need the Subscripts for Segment oe.order, urn. We have ADM.PAT.urn, which is linked to OE.ORD.patient Field. But we need OE.ORD.urn. Index File oe.ords.by.pat.and.ord.date.x has three subscripts: patient, order.date, and urn. We have patient but need urn. The Data Definitions shows that another name for oe.ords.by.pat.and.ord.date.x is order.x.

53. Sample Report Part XIX The NPR Programming Macro @Next will return the Next value of a Subscript from either a Detail Segment or an Index File. @Add(1,COUNT) increments Local Variable COUNT. We then assign the values we want to the MV Array. We reconnect Prefixes ? And & back to their previous connections via the line: ZZ%O(?,OLD1,&,OLD2)

54. Sample Report Part XXX We can the File and Translate our Macro, and then retranslate our report. So, the report runs as it normally would, and the Macro d will be executed each time before the D Region prints. The Macro puts the values from PHA.RX, LAB.L.SPEC, and OE.ORD into an MV Array. And the Line Attribute instructs the report to print the values from the MV Array in the user-defined fields.