| # 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. Predefined variables 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. Macros 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. The available macros:
    (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)
UPDATE VALUE
             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. Return value 0 OK <0 Error UPDATE.NORM
                 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. Return value
    0   OK
    <0  Error
UPDATE.MIN
              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. Return value 0 OK <0 Error UPDATE.MAX
              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. Return value 0 OK <0 Error UPDATE.ADJ.NORM
              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. Return value 0 OK <0 Error UPDATE.BENCH
              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. Return value
    0   OK
    <0  Error
WRITE.LINE
              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. Return value 0 OK <0 Error BLANK.LINE
     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. Return value 0 OK <0 Error UPDATE.TEXT
              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(). Return value 0 OK <0 OK GET.VALUE
              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. GET.NORM
              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. GET.ADJ.NORM
              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. GET.MIN
              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. GET.MAX
              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. GET.BENCH
              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. GET.PERIOD.OF.DATE
              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! Return value 0 OK <0 Error GET.DATES.OF.PERIOD
           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. Return value 0 OK <0 Error OPEN.PI.LOG
           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. Return value 0 OK <0 Error MSG.PI.LOG
          	 long MSG.PI.LOG(string(132))
The argument string is written to the earlier opened log file. Return value 0 OK <0 Error ERROR.PI.LOG
          	 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. Return value 0 OK <0 Error CLOSE.PI.LOG
          	 long CLOSE.PI.LOG()
The earlier opened log file is closed. Return value 0 OK <0 Error Overview of predefined variables
     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)