<?xml version="1.0" encoding="utf-8"?>
<ManualTopic ID="/baanerp/tg/onlinemanual/000023" xml:lang="en">
   <Header>
      <Title>Macros for performance-indicator scripts</Title>
      <Keyword type="header" order="d1e2286502">
         <Level1>Performance indicator script</Level1>
         <Level2>macros</Level2>
      </Keyword>
   </Header>
   <GeneralSection>
      <Paragraph>When writing <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link> 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.</Paragraph>
      <GeneralSection>
         <SectionTitle>Predefined variables</SectionTitle>
         <Paragraph>At compile time a few variables are added automatically to the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link> script. These variables retrieve
their value when the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link> object is
executed by the batchprogram in the Calculate Performance Indicators (tgeis0214m000) session. These
variables can also be used in the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link> script.</Paragraph>
      </GeneralSection>
      <GeneralSection>
         <SectionTitle>Macros</SectionTitle>
         <Paragraph>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.</Paragraph>
         <Paragraph>There are macros for updating and retrieving data, for text handling
within output files of the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>, and
for date conversions.</Paragraph>
         <Paragraph>All macros use the calendar, which is linked to the specific <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indictor</Link> for writing and reading data from
the table. This means that all <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicators</Link> used in a script must have the same <Link href="/baanerp/tg/glossary/glossary#000159" role="glossary">calendar code</Link> linked, otherwise results cannot be aggregated, copied, or used for
other PIs due to a different time base. Before compiling the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>- script the system will check on
this.</Paragraph>
      </GeneralSection>
      <GeneralSection>
         <SectionTitle>The available macros:</SectionTitle>
         <Formula space-and-orientation="indented-estimated">
            <Paragraph>(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)</Paragraph>
         </Formula>
         <GeneralSection ID="A">
            <SectionTitle>UPDATE VALUE</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
         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
   </Paragraph>
            </Formula>
            <Paragraph>The calculated pi.value is written to the Calculated Value field for
the specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending on the
specified update.mode, the value is added to an existing value or it
overwrites an present value.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="B">
            <SectionTitle>UPDATE.NORM</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
             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
   </Paragraph>
            </Formula>
            <Paragraph>The calculated norm.value is written to the Norm Value field for the
specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending on the
update.mode an existing value is overwritten or the given norm.value is
added.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Formula space-and-orientation="indented-estimated">
                  <Paragraph>

0   OK
&lt;0  Error
</Paragraph>
               </Formula>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="C">
            <SectionTitle>UPDATE.MIN</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          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
</Paragraph>
            </Formula>
            <Paragraph>The calculated norm.value is written to the Minimum Value field for the
specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending the
update.mode an existing value is overwritten or the given norm.value is
added.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="D">
            <SectionTitle>UPDATE.MAX</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          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
</Paragraph>
            </Formula>
            <Paragraph>The calculated norm.value is written to the Maximum Value field for the
specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending the
update.mode an existing value is overwritten or the given norm.value is
added.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="E">
            <SectionTitle>UPDATE.ADJ.NORM</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          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
</Paragraph>
            </Formula>
            <Paragraph>The calculated norm.value is written to the Adjusted Norm Value field
for the specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending the
update.mode an existing value is overwritten or the given norm.value is
added.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="F">
            <SectionTitle>UPDATE.BENCH</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          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
</Paragraph>
            </Formula>
            <Paragraph>The calculated norm.value is written to the Benchmarking Value field
for the specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. Depending the
update.mode an existing value is overwritten or the given norm.value is
added.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Formula space-and-orientation="indented-estimated">
                  <Paragraph>
0   OK
&lt;0  Error
</Paragraph>
               </Formula>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="G">
            <SectionTitle>WRITE.LINE</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          long WRITE.LINE(string(132) text.line,
   long tabposition )</Paragraph>
            </Formula>
            <Paragraph>The string text.line is written/added to the text file. It starts at
the given tabposition.</Paragraph>
            <Paragraph>Caution: the text file is not written to table yet, that is done with
macro UPDATE.TEXT.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="H">
            <SectionTitle>BLANK.LINE</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph> long BLANK.LINE( long nr.rows )</Paragraph>
            </Formula>
            <Paragraph>This macro causes nr.rows blank lines in the text file.</Paragraph>
            <Paragraph>Caution: the text file is not written to table yet, that is done with
macro UPDATE.TEXT.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="I">
            <SectionTitle>UPDATE.TEXT</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          long UPDATE.TEXT(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>Writes the generated text file to tgeis012 for the specified <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>.</Paragraph>
            <Paragraph>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.</Paragraph>
            <Paragraph>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.</Paragraph>
            <Paragraph>After use of this macro the generated text file will be cleared, and a
new text file can be generated with WRITE.LINE().</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  OK</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="J">
            <SectionTitle>GET.VALUE</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.VALUE(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Calculated Value field, or, if filled, the User-Defined Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. If these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="K">
            <SectionTitle>GET.NORM</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.NORM(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Norm Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. When these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="L">
            <SectionTitle>GET.ADJ.NORM</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.ADJ.NORM(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Adjusted Norm Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. If these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="M">
            <SectionTitle>GET.MIN</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.MIN(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Minimum Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. If these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="N">
            <SectionTitle>GET.MAX</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.MAX( domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Maximum Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. If these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="O">
            <SectionTitle>GET.BENCH</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          domain tgeis.valu GET.BENCH(domain tgeis.pind perf.ind,
   [ domain tcyrno year,
   domain tgeis.yrpt year_part,
   domain tgeis.pern period ])
   </Paragraph>
            </Formula>
            <Paragraph>This macro returns the contents of the Benchmarking Value field.</Paragraph>
            <Paragraph>Year, year part, and period are optional. If these values are not
filled, the current period is read (according to the calendar).</Paragraph>
            <Paragraph>This macro can only be used to read data of PI with a
Processing Sequence Number lower then the sequence number of the current <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>. This to avoid reading data which
have not been calculated yet.</Paragraph>
         </GeneralSection>
         <GeneralSection ID="P">
            <SectionTitle>GET.PERIOD.OF.DATE</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
          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)
   </Paragraph>
            </Formula>
            <Paragraph>This macro calculates the year, year part, and period belonging to the given check.date.</Paragraph>
            <Paragraph>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.</Paragraph>
            <Paragraph>Caution: If the check.date is before the first defined period of the
calendar the 3 ref fields contain value 0.</Paragraph>
            <Paragraph>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!</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="Q">
            <SectionTitle>GET.DATES.OF.PERIOD</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
       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)
   </Paragraph>
            </Formula>
            <Paragraph>This macro calculates the start and end date of the given period. It uses the calendar code of the <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link> (to which the script belongs) and stores the result in the two ref
variables.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="R">
            <SectionTitle>OPEN.PI.LOG</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
       long OPEN.PI.LOG(domain tgeis.pind perf.ind
   [ , domain tcyrno year,
   domain tgeis.yrpt yrpt,
   domain tgeis.pern pern ])
   </Paragraph>
            </Formula>
            <Paragraph>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 <Link href="/baanerp/tg/glossary/glossary#000090" role="glossary">performance indicator</Link>- code extended with the time period.</Paragraph>
            <Paragraph>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.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="S">
            <SectionTitle>MSG.PI.LOG</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
      	 long MSG.PI.LOG(string(132))
      	 </Paragraph>
            </Formula>
            <Paragraph>The argument string is written to the earlier opened log file.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="T">
            <SectionTitle>ERROR.PI.LOG</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
      	 long ERROR.PI.LOG(string(132))
      	 </Paragraph>
            </Formula>
            <Paragraph>The argument string is written to the earlier opened log file. A prefix "Error: " is added to the string.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="U">
            <SectionTitle>CLOSE.PI.LOG</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph>
      	 long CLOSE.PI.LOG()
      	 </Paragraph>
            </Formula>
            <Paragraph>The earlier opened log file is closed.</Paragraph>
            <GeneralSection>
               <SectionTitle>Return value</SectionTitle>
               <Paragraph>0   OK
&lt;0  Error</Paragraph>
            </GeneralSection>
         </GeneralSection>
         <GeneralSection ID="V">
            <SectionTitle>Overview of predefined variables</SectionTitle>
            <Formula space-and-orientation="indented-estimated">
               <Paragraph> 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)

      	 </Paragraph>
            </Formula>
         </GeneralSection>
      </GeneralSection>
   </GeneralSection>
</ManualTopic>