Introduction to the Use of Macros

Unit 2 - Macros 1

Macros

Unit 2

MEDITECH Level Two - NPR Report Writer Workshop Unit 2 – Macros 2

The Report Writer allows you to insert user-defined macros into your custom report code. Macros provide the ability to perform functions that standard report code cannot do. In this way macros are much like a computed field, however macros provide the ability to incorporate unlimited lines of code into a report.

A macro will most often be used when the code you are creating will not fit into the space allowed in field or line attributes (256 translated characters). However, the additional functionality of the macro editor makes it appropriate to create a macro for even less complicated computations.

MEDITECH Level Two - NPR Report Writer Workshop Unit 2 - Macros 3

The naming convention for a macro is the same as used for a report. Only lower-case alpha characters, numeric characters, and periods (.) may be used when naming a macro.

To enter a macro, select the Enter/Edit Macro routine from the Process Reports menu. An existing report must be identified prior to accessing this routine. Once entered, the macro becomes permanently attached to the report.

Below is displayed a sample of a macro as it would be defined in the macro editor. The code in this macro could easily have been created within the limited space of a computed field, however it has instead been moved to a macro. The macro editor allows code to be created that can be more easily read by other users. This includes the ability to place comment lines in the macro to document the functionality of its code. The conventions used in the macro will be covered in this manual.

Functions of the Macro Editor

The following are the functions and syntax used while creating and editing macros.

When writing any type of programming code it is good practice to comment the code that you write. This will assist in identifying to other users, or even yourself at a later time, the purpose of your code. To create comment lines in the macro editor, simply begin the line with a semi-colon (;). This informs the macro translator that all other information on the line should be ignored.

As previously mentioned, a macro is a grouping of MAGIC expressions. Each MAGIC expression must be separated by a comma (,) within the macro editor. After any comma ending a MAGIC expression, it is appropriate to create a new line of macro code. This provides the ability to break up sections of code into multiple lines, making your code cleaner and easier to read. In addition, it assists in insuring that the maximum of 255 translated characters per line is not reached.

At times, it is also appropriate for a semi-colon to end a line of macro code. However, this is only appropriate if the line is contained within a MAGIC control structure (i.e. IF or DO statement), and the semi-colon is being used as the else portion of the statement. The diagram on the next page illustrates this capability within the macro editor.

A feature of the macro editor, that makes this tool much more functional and powerful than a computed field, is the fact that there is no limit to the number of lines that a macro can contain. This allows for the complexity of macro code to range from that of a simple computed field to complex programming code.

See the diagram on the next page of a macro for an example of each of these rules.

The first 5 lines of this macro are defined as comment lines, as they begin with a semi-colon. The first 7 lines of the IF statement are ended with a semi-colon, signifying the else clause within this structure. The only other scenario in which a semi-colon can end a macro line is as the last character of a macro (as shown above). The proper way to end a macro is discussed in more detail later in this Unit. The eighth line of the IF statement is appropriately ended with a comma, as it ends a MAGIC expression.

Formatting

Format Code: SHIFT + F1

This function will format the code to provide proper indenting and will also provide a warning of any syntax errors in the code. You will always want to format the macro before filing.

Left Justify Code: CTRL + F1

Will left justify the code.

Join Code: SHIFT + F4

This will join two lines together.

Note: The syntax checker only checks for illegal references, it does not check for incorrect MAGIC syntax.

Other Functions

Data Element Lookup: F9

This function will allow a lookup to find a certain field, DPM, Segment, or lookup the Segment Hi- erarchy.

D\ : DPM Lookup

By typing D\ and then F9 we will get a lookup of all DPM's. We can also do a partial lookup. So, we could type D\ADM then F9 to get a lookup of all DPM's within ADM.

S\: Segment Lookup

The S\ will provide a lookup of the segments within the DPM we are writing in. In the example above the report is written in ADM.PAT, so we get a lookup in the segments of ADM.PAT. If I wanted to see segments of a different DPM, for example BAR.PAT, I could type S\BAR.PAT and then F9 to see the segments within BAR.PAT.

X\: Segment Hierarchy

By typing X\ we will get a lookup to the segment hierarchy of the DPM we are writing in. Again, in the example above we are writing in ADM.PAT and can see the segment hierarchy for this DPM. If I wanted to see the segment hierarchy for a different DPM, like BAR.PAT, I would simply type X\BAR.PAT.

Search and Replace

The search and replace functions will allow us to set a certain value to search for within the macro. We can also set a replace value so that when the value is found we replace it with the value specified.

F2: Set Search

By pressing the F2 key we are prompted with a box to enter a value to search for and what to replace this value with. The prompt box of A=a? defaults to "Y" and means that the search will not be case sensitive. By placing an "N" in this box the search will be case sensitive. Also, the prompt Verify? is defaulted to "Y". This means that before any occurrences are replaced it will allow the user to verify the replacement. If an "N" is placed in this box when we hit F12 it will automatically replace any occurrences.

F3: Search

If a "Y" was left in the Verify prompt we will then need to use the F3 key to search for the value specified. Once a value has been found the search will pause and highlight the occurrence.

F4: Replace

Once the search pauses and highlights a string we will need to type F4 to verify and replace the field with the replacement value specified in the search and replace. If there is a value we do not want to replace we would press the F3 key again to continue searching through the macro.

Cut and Paste Functions

Cut: CTRL + X OR

Copy: CTRL + C OR

Paste: CTRL + V OR

Get Function

F5: Get Function

This function will allow you to access code from other macros in both custom and standard reports.

By selecting the F5 key, we get the box above, prompting for the DPM. It will automatically default in the DPM we are writing in but can be changed if needed. A F9 lookup into the DPM's is also available here. Once the correct DPM is selected we will hit enter:

Once we press enter we will be prompted for the procedure. This is where we will put in the report name that we want to access. In order to get a prompt for the macro we will first need to type a M and then enter our report name. Again, a F9 lookup is available to see the report names. After selecting a report we will again hit enter:

After selecting our report we will then be prompted for the program/macro name. We can either type in the name of the macro or do an F9 lookup to see the macros in the report. Once we have our macro name and press enter we will then be in the macro editor for that macro and will have access to the code.

Local Macros

Local macros are subroutines within a macro. They provide the ability to define a macro first in general terms and then expand the details within each general area. Local macros are useful to perform repetitive functions as they only need to be defined once and can then be called multiples times.

Local Macro Rules:

 Only accessible from within the macro they are defined  Use at least 3 uppercase alphanumeric characters for naming convention  Last line should not end with a comma or semicolon  A local macro is separated from the rest of the macro logic by one blank line.

Local Macro References

A macro may contain references to other sections of MAGIC code, referred to in other programming languages as subroutines or functions. These references are preceded by an at sign (@). The corresponding MAGIC code is called a Local Macro.

For example: @GET.COUNT

This syntax will execute the code defined within the GET.COUNT local macro. GET.COUNT must be defined within the same macro it is being referenced from.

Local Macro Definition

The definition of a local macro consists of two parts: a single line containing only the local macro name, and one or more expression lines composing the body of the macro.

For example: GET.COUNT 1+CNT^CNT

In this example when @GET.COUNT is referenced within the body of the macro, the MAGIC code associated with this local macro, as seen above, will be executed.

In the following screen shot, we have taken the macro on the previous page and added two local macros LOCATION and COUNT. This code will count the patients that have visited one of the 8 lo- cations. The functionality of this macro is the same as the one in the preceding diagram; in fact their object code will be identical. @LOCATION and @COUNT will execute the code defined within the local macros.

The use of local macros with meaningful naming conventions can improve the readability of macro code.

Notice that neither of the above local macros end with a comma or semi-colon. When the object code is created for this macro a comma will automatically be placed at the end of the local macro’s code.

Syntax Checker

The Report Writer has a syntax checker that is invoked after filing a macro. The purpose of the syntax checker is to protect the integrity of your application data. This is done by only allowing assignments to the slash prefix and local variables, while disallowing specific MAGIC programming functions. The syntax checker prohibits the following character sequences (displayed as error messages):

Macro Translator

After filing a macro it must then be translated. The translation process creates the object code of the macro from its source code. Error messages will be generated if data fields have been referenced incorrectly.

Incorporating Macros

 As a footnote

The KEYWORD specifies the point in the object code in which the macro will be inserted. The macro.name is the name of the macro as defined within the Enter/Edit Macro routine.

If the macro is associated with the same report macro can be referenced with just the macro name as follows:

AL START macroname

If the macro referenced is from a different report than where it is being called from the complete name is needed:

AL D DPM.zcus.reportname.M.macroname

For example:

Report Name: BAR.PAT.zcus.status.rpt Macro Name: get.info Complete Macro Name: BAR.PAT.zcus.status.rpt.M.get.info

When a macro is called via an AL footnote, the Report Writer inserts the macro’s object code directly into the report’s object code and it places a comma at the end of the code. For this reason, when using the AL footnote to call a macro, be sure the last line of the macro does not end with a comma or semi-colon.

NOTE: The Report Writer incorporates the macro’s object code into the report’s object code at translation time. Therefore, each time you edit a macro, you must retranslate all reports which call that macro.

Although multiple footnotes may be defined within the Footnote editor, each KEYWORD may only be referenced once. If a single KEYWORD is utilized multiple times in the same report, only the logic for the last of these footnotes will be executed.

Benefits of Calling Macro Via Footnote

 Local variables established within the NPR Report are accessible within the macro  Local variables established within the macro are accessible within the NPR Report

Demo Report for Macro Called as Footnote: ADM.PAT.zcus.zadv.demo2.incorp.macros

Workshop - Part A:

 We currently have an ABS.PAT report that is printing out certain patient information(name, acct.number, etc...). The user has asked that this report include a computed field to return a certain string depending on the drg. The criteria for what should be returned looks as follows:

DRG Range String to be Returned 100 – 200 "Cardiac Care, Medical"

250 – 300 "Newborn”

115 – 118 "Neurological, Surgical"

514 - 518 "Psychiatry"

521 – 527 "Trauma, Medical"

301 - 400 "Substance Abuse"

Not in a range above “Other”

Copy the report: ABS.PAT.zcus.zlevel2.day1.workshopa.

** Do Not Edit the Above Report **

 Call a macro as a footnote to check the drg ranges above and return the correct string to a computed field.

Incorporating Macros

 As a program

We have now been asked to edit the report to exclude records that have a string of “Other” printing in our computed field.

 Can we select on the computed field as it is currently setup? o Since detail happens after selection we do not have the value  Can a different footnote be used? o There are no other footnotes that will get the correct values

In order to select on the value from the macro, we must remove the footnote call and call the macro as a program from the computed field.

Calling Macros as a Program

A macro must be called as a program when accessed from a line attribute, field attribute, or within the macro editor.

The above slides illustrate a macro being called as a stand-alone program. Local variables established by the report are not accessible within the macro. Therefore, in order for the macro to access data fields properly, it becomes necessary to pass arguments (field values) from the report to the macro. This is exactly the same a passing arguments to a Z program. Most often you will be passing the subscripts of your detail segment, to enable you to access data from this segment. If you don't require that arguments be passed to your macro, the nil value must be entered as an argument (""). This process is performed during the initial program call.

Once within the macro, the arguments that are passed from the report are accessible by the variables: A, B, C etc. As shown in the above slide, the first argument passed to the macro is stored in the variable A, the second variable is stored in the variable B, etc..

These variables can then be passed back into the standard field's local variable (if one should exist) or can be utilized simply as a variable in the macro.

Referring to the above slide, the variable A has been assigned the value of urn. Within the macro this variable can now be utilized in one of two ways: 1) As a subscript to access a data field (i.e. @discharge.date[A])

2) Assign the value of A back to the field’s local variable (i.e. A^urn,@discharge.date). This method will allow you to access any field from the main segment without having to enter the variable A as a subscript.

When called as a program the object code of the macro is separated from that of the report. The object code of the report contains only a program call to the macro. Because of this, it is necessary to end your macro with a semi-colon (;), the same character used to end all MAGIC program.

A symbol table is a local structure that stores all of the local symbols (variables) used by a particular program. When a NPR report invokes a macro (as a program), a new symbol table is created. This new symbol table is completely separate from the symbol table of the NPR report. Because both symbol tables are separate, any local variables established within the macro cannot be accessed by the NPR report (and vice-versa).

Slash variables, unlike local variables, are not stored in the local symbol table of a program, therefore a slash variable established within a macro is accessible by the NPR report (and vice- versa).

When called as a program, the value returned to the report is the value of the last expression within the macro. Take for example the following macro logic:

A^urn, @discharge.date;

If the patient has a discharge date, the value passed back to the report will be the patient's discharge date, otherwise the value will be nil.

Demo Report for Macro Called as Program: ADM.PAT.zcus.zadv.demo2.incorp.macros

Workshop - Part B:

 Edit your report from Part A to now call the macro as a program.  You will want to edit the report so records that return the string “Other” are excluded

MEDITECH Level Two - NPR Report Writer Workshop