Macros for performance-indicator scripts

When writing performance indicator scripts all functionality present in tools development kit is available. This means that a script is written in the same way as a report script, an exchange scheme, or a program script.

At compile time a few variables are added automatically to the performance indicator script. These variables retrieve their value when the performance indicator object is executed by the batchprogram in the Calculate Performance Indicators (tgeis0214m000) session. These variables can also be used in the performance indicator script.

For reading tables and calculating results, the standard tools can be used. To write those results and texts to EIS-tables a lot of macros have been defined.

There are macros for updating and retrieving data, for text handling within output files of the performance indicator, and for date conversions.

All macros use the calendar, which is linked to the specific performance indictor for writing and reading data from the table. This means that all performance indicators used in a script must have the same calendar code linked, otherwise results cannot be aggregated, copied, or used for other PIs due to a different time base. Before compiling the performance indicator- script the system will check on this.

(1,UPDATE.VALUE)          - UPDATE.CUM.VALUE(2,UPDATE.NORM)           - UPDATE.CUM.NORM(3,UPDATE.MIN)            - UPDATE.CUM.MIN(4,UPDATE.MAX)            - UPDATE.CUM.MAX(5,UPDATE.ADJ.NORM)       - UPDATE.CUM.ADJ.NORM(6,UPDATE.BENCH)          - UPDATE.CUM.BENCH(7,WRITE.LINE)(8,BLANK.LINE)(9,UPDATE.TEXT)(10,GET.VALUE)             - GET.CUM.VALUE(11,GET.NORM)              - GET.CUM.NORM(12,GET.ADJ.NORM)          - GET.CUM.ADJ.NORM(13,GET.MIN)               - GET.CUM.MIN(14,GET.MAX)               - GET.CUM.MAX(15,GET.BENCH)             - GET.CUM.BENCH(16,GET.PERIOD.OF.DATE)(17,GET.DATES.OF.PERIOD)(18,OPEN.PI.LOG)(19,MSG.PI.LOGG)(21,ERROR.PI.LOG)(22,CLOSE.PI.LOG)

         long UPDATE.VALUE(domain tgeis.pind perf.ind,
   domain tgeis.valu pi.value,
   long update.mode,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])

   Update mode: 0=overwrite, 1=add
   

The calculated pi.value is written to the Calculated Value field for the specified performance indicator. Depending on the specified update.mode, the value is added to an existing value or it overwrites an present value.

Year, year part, and period are optional. If you do not specify these values, the program determines the periods itself, using the last calculation date. If year, year part, and period are given, the system will write data to that specified period. So, you can update another PI as the current and also store data for other periods than the current.

0 OK <0 Error

             long UPDATE.NORM(domain tgeis.pind perf.ind,
   domain tgeis.valu norm.value,
   long update.mode,
   [ domain  tcyrno year,
   domain tgeis.yrpt  year_part,
   domain tgeis.pern period ])

Update mode: 0=overwrite, 1=add
   

The calculated norm.value is written to the Norm Value field for the specified performance indicator. Depending on the update.mode an existing value is overwritten or the given norm.value is added.

Year, year part, and period are optional. If these values given, the system will write to the specified period. If these values are not given, the system will determine the period to use itself, using the last calculation date. So, you can update another PI as the current and also store data for other periods than the current.

0   OK
<0  Error

          long UPDATE.MIN(domain tgeis.pind perf.ind,
   domain tgeis.valu min.value,
   long update.mode,
   [ domain tcyrnoyear,
   domain tgeis.yrpt year_part,
   domain tgeis.pern  period ])

Update mode: 0=overwrite, 1=add

The calculated norm.value is written to the Minimum Value field for the specified performance indicator. Depending the update.mode an existing value is overwritten or the given norm.value is added.

Year, year part, and period are optional. If these values are given, the system will write to the specified period. If these values are not given, the system will determine the period to use itself, using the last calculation date. So, you can update another PI as the current and also store data for other periods than the current.

0 OK <0 Error

          long UPDATE.MAX(domain tgeis.pind perf.ind,
   domain tgeis.valu max.value,
   long update.mode,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])

Update mode: 0=overwrite, 1=add

The calculated norm.value is written to the Maximum Value field for the specified performance indicator. Depending the update.mode an existing value is overwritten or the given norm.value is added.

Year, year part, and period are optional. If these values are given, the system will write to the specified period. If these are not given, the system will determine the period to use itself, using the last calculation date. So, you can update another PI as the current and also store data for other periods than the current.

0 OK <0 Error

          long UPDATE.ADJ.NORM(domain tgeis.pind perf.ind,
   domain tgeis.valu adj.norm.value,
   long update.mode,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])

Update mode: 0=overwrite, 1=add

The calculated norm.value is written to the Adjusted Norm Value field for the specified performance indicator. Depending the update.mode an existing value is overwritten or the given norm.value is added.

Year, year part, and period are optional. If these values are given, the system will write to the specified period. If these values are not given, the system will determine the period to use itself, using the last calculation date. So, you can update another PI as the current and also store data for other periods than the current.

0 OK <0 Error

          long UPDATE.BENCH(domain tgeis.pind perf.ind,
   domain tgeis.valu bench.value,
   long update.mode,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])

Update mode: 0=overwrite, 1=add

The calculated norm.value is written to the Benchmarking Value field for the specified performance indicator. Depending the update.mode an existing value is overwritten or the given norm.value is added.

Year, year part, and period are optional. If these values are given, the system will write to the specified period. If these values are not given, the system will determine the period to use itself, using the last calculation date. So, you can update another PI as the current and also store data for other periods than the current.

0   OK
<0  Error

          long WRITE.LINE(string(132) text.line,
   long tabposition )

The string text.line is written/added to the text file. It starts at the given tabposition.

Caution: the text file is not written to table yet, that is done with macro UPDATE.TEXT.

0 OK <0 Error

 long BLANK.LINE( long nr.rows )

This macro causes nr.rows blank lines in the text file.

Caution: the text file is not written to table yet, that is done with macro UPDATE.TEXT.

0 OK <0 Error

          long UPDATE.TEXT(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

Writes the generated text file to tgeis012 for the specified performance indicator.

Year, year part, and period are optional. If these values are given, the system will write to the specified period. If these values are not given, the system will determine the period to use itself, using the last calculation date.

If this macro is not used, text files generated with WRITE.LINE and BLANK.LINE will not be stored in database and thus, not be present in enterprise modeler.

After use of this macro the generated text file will be cleared, and a new text file can be generated with WRITE.LINE().

0 OK <0 OK

          domain tgeis.valu GET.VALUE(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Calculated Value field, or, if filled, the User-Defined Value field.

Year, year part, and period are optional. If these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          domain tgeis.valu GET.NORM(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Norm Value field.

Year, year part, and period are optional. When these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          domain tgeis.valu GET.ADJ.NORM(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Adjusted Norm Value field.

Year, year part, and period are optional. If these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          domain tgeis.valu GET.MIN(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Minimum Value field.

Year, year part, and period are optional. If these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          domain tgeis.valu GET.MAX( domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Maximum Value field.

Year, year part, and period are optional. If these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          domain tgeis.valu GET.BENCH(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   

This macro returns the contents of the Benchmarking Value field.

Year, year part, and period are optional. If these values are not filled, the current period is read (according to the calendar).

This macro can only be used to read data of PI with a Processing Sequence Number lower then the sequence number of the current performance indicator. This to avoid reading data which have not been calculated yet.

          long GET.PERIOD.OF.DATE(domain tgeis.pind
   perf.ind,domain tcdate check.date,
   ref domain tcyrno year,
   ref domain tgeis.yrpt yrpt,
   ref domain tgeis.pern pern)
   

This macro calculates the year, year part, and period belonging to the given check.date.

The macro uses the calendar code of the period indicator (the PI to which the script belongs) and stores the values in the 3 ref fields.

Caution: If the check.date is before the first defined period of the calendar the 3 ref fields contain value 0.

If check.date is later then the last defined period, the ref fields contain the last defined period. So, take care that calendars of all years are filled!

0 OK <0 Error

       long GET.DATES.OF.PERIOD(domain tgeis.pind perf.ind,
   domain tcyrno year,
   domain tgeis.yrpt yrpt,
   domain tgeis.pern pern,
   ref domain tcdate start.date,
   ref domain tcdate end.date)
   

This macro calculates the start and end date of the given period. It uses the calendar code of the performance indicator (to which the script belongs) and stores the result in the two ref variables.

0 OK <0 Error

       long OPEN.PI.LOG(domain tgeis.pind perf.ind
   [ , domain tcyrno year,
   domain tgeis.yrpt yrpt,
   domain tgeis.pern pern ])
   

This macro creates/opens a log file in directory $BSE/log/eis.### (where ### is the current company number). The name of the log file is the performance indicator- code extended with the time period.

Messages can be written to this log file with use of the macros MSG.PI.LO and ERROR.PI.LOG. Finally the log file should be closed with CLOSE.PI.LOG.

0 OK <0 Error

      	 long MSG.PI.LOG(string(132))
      	 

The argument string is written to the earlier opened log file.

0 OK <0 Error

      	 long ERROR.PI.LOG(string(132))
      	 

The argument string is written to the earlier opened log file. A prefix "Error: " is added to the string.

0 OK <0 Error

      	 long CLOSE.PI.LOG()
      	 

The earlier opened log file is closed.

0 OK <0 Error

 perf.ind        = PI code of the current PI
(string12) yrno.to.process = the year number currently being processed
(long) yrpt.to.process = the year part currently being processed
(long) pern.to.process = the period number currently being processed
(long)