Rational Programming Patterns for System z

The Macro entity

The purpose of a Macro is to standardize functions that are common to several programs, or to several procedures of the same program. A called Macro is a complement to the generation possibilities of the system. A Macro is usually displayed in a program description as if its lines had been directly entered by a programmer.

A Macro is not a subprogram because, unlike a subprogram, a Macro can contain non-consecutive statements.

However, a Macro can call a subprogram.

Macro types

There are six basic types of Macros:
  • A 'general program outline type'. It gives a program a standard structure which takes into account all the development standard followed on your site. This type of Macro is also used to describe a body of technical (system-oriented) procedures that are linked to the use of a TP monitor or a DBMS;
  • A 'technical (system-oriented) function type' used to standardize specific commands, such as the input/output procedures of a DBMS (read, modify, delete, and so on);
  • A 'complex technical functions type'. It resolves all the complicated procedures involved in a DBMS, whether in an online environment, such as: validation management, the sequential read of a file, the technical procedures for database updates, the particular access path used in a database...

    This type is generally a combination of elementary technical functions that you must rewrite in order to minimize the task of connecting elementary Macros to one another;

  • A 'general function type'. It resolves certain procedures that are common to a set of applications, such as: date validation, date transformation, or standards for online error message handling. You must keep in mind that this type of Macro is independent of the operating system, the TP monitor, and the DBMS used;
  • A 'specific function type' used to 'harmonize' the development of programs that make up a system. For example, to standardize the presentation of certain reports or screens by using common procedures defined in a Macro.
  • A type used to create cross-references; for example, if a Macro calls a subprogram, you can automatically find out which programs use that subprogram.

Differences between Macros and subprograms

You must often decide whether to use a subprogram or a Macro to consolidate all the procedures that are common to several Programs.

In order to find the answer, you must ask several questions:
  • Are the common procedures consecutive?
  • Is the position of these procedures defined?
  • Are there many parameters?
  • Are these procedures executed generally?
Answers to these questions help you to determine which procedures must be executed in a subprogram and which must be executed in a Macro.
  • If they are not consecutive ⇒ Macro.
  • If the position is already defined ⇒ Macro.
  • If there are many parameters ⇒ subprogram.
  • If the procedures are not executed generally ⇒ subprogram.

Parameterizing the key of a specific code line

You can parameterize the key of specific code lines (function code, subfunction code, and the first two characters of the line number). As a recommendation, before writing a Macro, you must try to structure the procedure to be written. Try to minimize the number of parameters in the key, to:
  • Facilitate usage of the Macro,
  • Obtain Programs with a homogeneous structure,
  • Minimize the resolution time of a Macro.

As a rule, it is not recommended to use a Macro instead of one or two specific code lines. Using specific code is less time-consuming upon generation and limits the number of necessary Macro calls.

Consistency of parameters

A Program can call several Macros. You must check that the parameters are used consistently.
Example: If two Macros are called into the same program, and both use a Data Structure as a parameter, both Macros would ideally have that Data Structure in the same position.
This programming mode has a twofold advantage:
  • It is easier for the programmer,
  • The same type of information is presented in the same order in a Program
While this is not always possible, it would be wise to consider the placement of parameters in existing Macros before designing a Macro.

Documenting a Macro

Documenting a Macro is important. It gives the developer the information needed to use the Macro properly: the meaning of each parameter, which functions, subfunctions, or both, are used.

A Macro can be documented in two different ways:
  • In the same way as any program, in the -G Lines tab (-GC Lines),
  • On the Macro Comments tab.

Overriding a Macro line

Given the same key, the lines of a Macro are overridden by the lines of the calling program (Program or Screen entity). It is advised to design Macros so that as few lines as possible will be overridden by the calling programs. The maintenance is easier.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)