TAA Tools
PRTPAGOF       PRINT PAGE OF                           TAASPPE

The Print Page Of  command allows you to re-print a  spooled file where
you have printed  'Page n' and change the value to 'Page  n of n'.  You
must  identify where the units  position of the page  number is and the
line it is  to print on.   An option exists to  shift part of the  line
to allow room  for the ' of n' value.   After re-printing, the original
spooled file is deleted by default.

The PRTPAGOF command typically follows a print program such as:

             CALL       myprtpgm
             PRTPAGOF   PRTLIN(1) PAGNBRPOS(nn)

PRTPAGOF  uses CPYSPLF to create a temporary  data base file, reads the
file and determines how many pages  exist in total.  It then  re-prints
the file  and changes  the line  with the  page number  to include  the
total  number of pages.   A RTVSPLFA  command is used  for the original
file and most  of the values  are used  on an OVRPRTF  command for  the
new file.  This means  that the new spooled file will have  most of the
attributes  of the  original  file  such as  USRDTA,  FORMTYPE, COPIES,
etc.  The original spooled file is then deleted by default.

If  the page number  is reset during printing,  PRTPAGOF will print the
total for  each group.    For example,  if you  are printing  invoices,
each  invoice  would  normally start  with  'Page  1'.   If  the  first
invoice had  3 pages, the output of the first  page would be 'Page 1 of
3'.

It is not necessary that your  spooled file have the word 'Page'.   You
may  have used  a  different  text value  (such  as  a native  language
version of  'Page' or no text  value and just printed  the page number.
In the following  discussions, it  is assumed  that you  are using  the
word 'Page', but it is not required.

Shifting the print line containing the Page number
--------------------------------------------------

The Page  information can  also be  shifted to the  left by  describing
the first  position to shift  from (usually the  'P' in 'Page'  and the
position to shift it to.

You  must have sufficient  room to print  the 'Page n  of n' value plus
the length defined  for PAGNBRLEN (default  is 4).   If not, an  escape
message is sent describing the minimum position that can be used.

For example,  most system  output places the  'Page' text  beginning in
position  121 and the page number ending  in 130.  Without shifting the
value there  would not  be enough  room to  print 'Page  n of  n'.   By
shifting the value, you can print it properly such as:

             PRTPAGOF  PRTLIN(1) PAGNBRPOS(130)
                         SHIFT(121 114)

The first SHIFT  value is where the  'P' starts in 'Page'.   The second
value  is where  you  want it  to start.   There  must  sufficient room
after the shift start value to print the 'Page n of n' value.

In most cases you must shift at  least 7 positions to the left, but  it
can vary (such  as the length  of the PRTTXT value).   If there  is not
sufficient  room, an  escape  message  is sent  describing  the minimum
position that can can be used.

System  output (such as using WRKSYSSTS  *PRINT or a job log) typically
starts the  'Page' text in  121 and  places the  page number ending  in
130 (so it may  be seen with DSPSPLF).  Note that  this only allows for
a  max  of 999  pages.   PRTPAGOF  allows for  a  2-6 byte  page number
(default is 4).   To use  PRTPAGOF,the typical shift  value for  system
output is SHIFT(121 114).

Some  system output  does not  allow for  a  simple shift  of just  the
'Page' text  because data exists to the left  that would be overlaid or
more difficult  to read.   For  example, the  CRTCLPGM command  creates
output with  the page number ending  in 132.   You could keep  the page
number on the DSPSPLF display (ending in 130) by shifting as follows:

             PRTPAGOF  PRTLIN(1) PAGNBRPOS(132)
                         SHIFT(124 116)

While  this would  be allowed, there  would only  be one  space between
the  end of  the time  value and  the word  'Page'.   Better formatting
could be achieved by  shifting a large portion  of the first line  such
as:

             PRTPAGOF  PRTLIN(1) PAGNBRPOS(132)
                         SHIFT(42 33)

The CRTRPGPGM command  creates output with the page  number in 130, but
you  must begin the shift in position  74 (qualified library name) to a
position such as 67.

             PRTPAGOF  PRTLIN(1) PAGNBRPOS(130)
                         SHIFT(74 67)

It may take some testing  to determine the specific shifting  positions
to be used.

Testing PRTPAGOF
----------------

You can use  a normal program that  creates a spooled file  in your own
job  and then determine the  print line and units  position of the page
number.  Then enter the values on PRTPAGOF.

To try it on a production spooled  file, use a command such as  DUPSPLF
to duplicate the spooled  file to your own job.   After determining the
line  and  units position  of  the  page number,  try  PRTPAGOF on  the
duplicate.

If  you need  to use the  SHIFT parameter, it  may take a  few tries to
get what you want.

The  default  on  PRTPAGOF   is  to  delete  the  spooled   file  after
re-printing with  the parameter DLTSPLF  (default is *YES).   Using *NO
can be helpful when testing to compare the two spooled files.

Comments and restrictions
-------------------------

  **   The  spooled file to  be re-printed must  exist in  the same job
       as PRTPAGOF.

  **   The spooled  file must  be  capable of  being read  by  CPYSPLF.
       This allows  for SCS spooled  output, but disallows  other types
       such as AFP.

  **   The  line containing  the page  number  must be  in the  first 5
       printed lines on a page.   Only printed lines (not blank  lines)
       count.   Note that  the first  printed line is  usually not  the
       first  possible line  1 of  each page  but rather  line 6  or so
       with the first 5 lines blank.

  **   The  default is to print  something like 'Page 1  of 7', but the
       'of' text is  only the  default.  A  20 byte  value may be  used
       such as 'of  total', 'Total pages =', or  a language translation
       of 'of'.

  **   The  units position  where the  page number  exists on  the page
       must be identified.   It must be  at least n  bytes to the  left
       of the  page width  to allow  for the length  of the  PRTTXT and
       the total  pages to be printed.  The  'n' value is determined by
       adding the units position, plus  the length of the PRTTXT,  plus
       2 blanks,  plus room for  the number  of positions described  by
       PAGNBRLEN.

       You cannot  have the page number  on one line and the  'of n' on
       a different line.

       The  total pages value will be  left adjusted.  Thus the default
       PRTTXT of 'of'  will require 8  bytes to the  right of the  page
       number for ' of nnnn'.

       If data  exists to the  right of the  units position, it  may be
       overlaid.   Only  the specific  length required is  changed (not
       the full 20 bytes allowed for PRTTXT.

       Note that  most spooled  files created  by the  system (such  as
       job logs)  place the units position  of the page number  in byte
       130 or 132 thus requiring the use of the SHIFT parameter.

  **   The maximum  amount that may be  shifted (the difference between
       PAGNBRPOS and the shift start position is 120.

  **   A resetting of the Page number  may occur such as when  printing
       invoices  and  the  first   page  of  each  is  Page   1.    The
       identification  of   a  reset  is  determined   by  finding  one
       position  prior to  the units  position of  the Page  number and
       checking for ' 1'.

  **   There is  no special support  for overstriking  a line (such  as
       to  make  bold printing).    It  is  assumed your  testing  will
       determine whether PRTPAGOF can be used properly.

  **   The  spooled   file  attributes  that  are  retrieved  from  the
       original spooled file  and used  on an OVRPRTF  command for  the
       new  file  are  SPLFNAME,  FORMTYPE,  OUTPTY,  COPIES,  FILESEP,
       SCHEDULE,  HOLD, SAVE, USRDTA, ACGCDE,  PAGLEN, PAGWTH, LPI, and
       CPI.   The other  values  default to  the TAAPRT1  printer  file
       values.

  **   Only one printing of ' of nnnn' may exist for a page.

  **   The maximum  number of  total pages  that may  exist depends  on
       the PAGNBRLEN parameter value.  The default is 9,999.

  **   The  maximum printer  width is  378 bytes  (same maximum  as any
       spooled file).

  **   A  new page is  identified by a  skip to a  line number which is
       less than  the current  line number.   Therefore,  spacing to  a
       new page will not be recognized.

PRTPAGOF escape messages you can monitor for
---------------------------------------------

None.  Escape messages from based on functions will be re-sent.

PRTPAGOF Command parameters                           *CMD
---------------------------

   PRTLIN        The  print line  where  the page  number  exists.   It
                 must  be a value of 1 -  5.  Only actual printed lines
                 (not  blank  lines)  are  counted  by  PRTPAGOF.     A
                 typical form of  output starts with 5  blank lines and
                 then  a heading  which includes the  page number.   If
                 the first  printed  line  on each  page  includes  the
                 page number, use PRTLIN(1).

   PAGNBRPOS     The units position  where the page number  is printed.
                 If  the RPG  PAGE special  name is  used, this  is the
                 same print position as specified in RPG.

                 The value must be between 4 and 378.

   PRTTXT        The  print  text that  is to  appear before  the total
                 number of  pages.   The default  is  'of'.   Up to  20
                 bytes  may  be  entered.    There will  be  one  space
                 before  the  PRTTXT  value, one  after,  and  then the
                 total number of pages.   The value is left  justified.

   SHIFT         A two  part parameter  that allows  you to  shift part
                 of  the data  on the line  containing the  Page number
                 to the left  to allow  room for 'Page  n of  n'.   The
                 default for  both parts is  *NONE meaning  no shifting
                 will  occur.  Use  the default  when there is  room on
                 the  print line after the  PAGNBRPOS position to print
                 the PRTTXT  and the total  number of pages  (typically
                 8 bytes).

                 The first  part of the parameter  identifies the first
                 position  to be  shifted.  If  there is  room to shift
                 the word  'Page' without  overlaying any  data to  the
                 left,  the position  to use  would  normally be  where
                 the 'P' in 'Page' is.

                 If  shifting left  will overlay  data  to the  left of
                 the 'Page'  identification, you  may have  to  specify
                 an earlier  position such  as in  a series of  blanks.
                 See  the previous  discussion of  'Shifting  the print
                 line containing the page number'.

                 The  second  part  of  the  parameter  identifies  the
                 first position to be  shifted to.  Normally, you  need
                 about  8 positions  less  than the  position to  start
                 the  shift.  An  error message will occur  if there is
                 insufficient  room  and  the  minimum  value  will  be
                 described.

   SPLF          The spooled file  name to be re-printed.   The default
                 is  *ANY  for  any spooled  file  meaning  the spooled
                 file is  identified  by  the  SPLNBR  parameter  which
                 defaults   to  *LAST.     The   typical   use  is   to
                 immediately follow  the command which  creates spooled
                 output with PRTPAGOF.

                 If *ANY is used, SPLNBR(*LAST) must be specified.

                 A specific spooled file name may be specified.

   SPLNBR        The  spooled file number  to be used.   The default is
                 *LAST.    A  specific  spooled  file   number  may  be
                 entered with  or without a  specific name in  the SPLF
                 parameter.

                 If  *LAST  cannot be  used  and  you do  not  know the
                 spooled file number,  consider the RTVSPLFID  command.

   DLTSPLF       A *YES/*NO  value for whether  to delete  the original
                 spooled file.

                 *YES  is the default  as you would  normally want only
                 the modified spooled file.

                 *NO may be  specified to retain  the original  spooled
                 file.   This can be  helpful when  testing to allow  a
                 comparison   of   what    changed.      If   you   are
                 experimenting  with different  SHIFT values,  you need
                 only delete  the latest spooled  file version  created
                 by by PRTPAGOF and try different SHIFT values.

   PAGNBRLEN     The length of  the page number.  The  default is 4 for
                 a  4 digit page number.  The  value must be in a range
                 of 2-6.


Restrictions
------------

See the section on 'Comments and restrictions'.

Prerequisites
-------------

The following TAA Tools must be on your system:

     EDTVAR          Edit variable
     RMVMSGKEY       Remove message key
     RSNLSTMSG       Resend last message
     RTVSPLFA        Retrieve spooled file attributes
     RTVSPLFID2      Retrieve spooled file ID 2
     RTVVALA         Retrieve value attributes
     SNDCOMPMSG      Send completion message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   PRTPAGOF      *CMD                   TAASPPE       QATTCMD
   TAASPPEC      *PGM       CLP         TAASPPEC      QATTCL
   TAASPPER      *PGM       RPG         TAASPPER      QATTRPG
					

Added to TAA Productivity tools July 15, 2011


Home Page Up to Top