The Page Separator program allows you to have large block letters for
spooled separator pages (either job or file). Up to 3 values of 10
characters each may be written as large block letters. Each block
letter is 10 x 10 in space with the character taking up 8 x 10.
Options exist to tailor the values that print as block letters such
as job, user name, system, user data, etc.
Optional distribution information may exist if you add a simple user
exit program to supply the distribution information. A working
sample is provided.
See the section on 'Further customization' for how to substitute your
required fields from the spooled file attributes for the standard
supplied fields.
The system Print Exit Program for a Customized Separator Page is
used. The system calls the TAA supplied program with a standard
parameter list.
Getting started
---------------
To use the Page Separator program, you must specify the name of the
TAATOOL program on each printer device description where you want the
function. Two programs are provided so that you may vary the page
separator per printer - See the later discussion.
You cannot change a printer device description unless the device is
varied off. Therefore, the following steps would normally be
performed:
** Use WRKWTR and check if any writers are started to the printer
device you want to change. If so, end the writer.
** Use VRYCFG to vary off the device:
VRYCFG CFGOBJ(xxx) CFGTYPE(*DEV) STATUS(*OFF)
** Use CHGDEVPRT to specify the TAA Tool separator program:
CHGDEVPRT DEVD(xxx) SEPPGM(TAATOOL/TAASPMDR)
** Use VRYCFG to vary on the device:
VRYCFG CFGOBJ(xxx) CFGTYPE(*DEV) STATUS(*ON)
To change either the number of job separators or file separators or
both, do the following:
** The number of job separators is specified on the CHGOUTQ
command with the JOBSEP parameter. The default is 0. The
OUTQ must not be allocated to a print writer if you intend to
change the value.
** The number of file separators is specified on the CRT/CHGPRTF
or OVRPRTF commands with the FILESEP keyword. You may also
specify a value on the STRPRTWTR or CHGWTR commands FILESEP
keyword.
Options for block text
----------------------
The system level options used by the Tool exist in the TAAPAGSEP1
application value (a user space) in TAASECURE. You may choose what
data should print for each of the 3 values that allow block letters
for both job and file separators. You may choose from:
- *JOB - Job name
- *USER - User who owns the spooled file
- *JOBNBR - Job number
- *SPLF - Spooled file name
- *USRDTA - User data (from a command like OVRPRTF)
- *ORGSYS - Originating system
- *ORGUSER - Originating user
- *DST1 - Distribution info 1 (see later discussion)
- *DST2 - Distribution info 2 (see later discussion)
You may also choose whether to overprint the block letters. See the
next section.
An *ALLOBJ user may change the values. Enter the command:
EDTAPPVAL APPVAL(TAASECURE/TAAPAGSEP1)
Change the default values to meet your requirements.
Block letters and the overprint option
--------------------------------------
By default, the large block letters are made up of the character to
be printed. Each character takes up 10 positions in width (including
two blanks two the right) and 10 lines of printing. For example, the
letter A appears as:
AAAAAAAA
AAAAAAAAAA
AA AA
AA AA
AAAAAAAAAA
AAAAAAAAAA
AA AA
AA AA
AA AA
AA AA
An option exists in the TAAPAGSEP1 application value to allow
overprinting of the large block letters (the detail information at
the bottom of the page is not overprinted). Use the EDTAPPVAL
command previously described for the 'Overprint block letters'
option.
Depending on your printer, overprinting can make the large block
letters darker or it may have little effect.
You may also consider the overprint option to print a 'blob'
character by using the *BLOB option. This is caused by printing the
letter N and overprinting with the letter E. For example, instead of
seeing many letter A's to form the block letter A as in the previous
example, you would see the letter A formed out of blob characters.
In general, the blob character will produce a much darker image to
help identify the separator page and who it belongs to.
You may try the options at any time. When a change occurs to the
Application Value, it will be considered when the next separator page
is produced.
Detail information at the bottom of the separator page
------------------------------------------------------
At the bottom of each separator page is detail information which will
contain all of the values that may be specified in the Application
Value plus some additional spooled file information for file
separators. These appear as standard size printed output rather than
block letters.
The *DSTn values (described later) will only print if a non-blank
value exists. It is possible to fill the *DSTn values for the detail
information without using the *DSTn data for block letters.
The constants (such as 'Job name') can be translated. See the later
discussion.
Supplying distribution information
----------------------------------
You may want to add distribution information to the separator page to
assist in distributing the hard copy output.
For example, you may want a separator page such as:
JONES
Dept 132
or
SMITH
002 - 001R
By supplying an exit program and specifying the name of the program
in the TAAPAGSEP1 application value, you can add distribution
information to the separator page.
A sample exit program is supplied by the program TAASPMDC2. This
program could be used 'as is'.
The TAASPMDC2 program assumes that you have changed the text
descriptions of your user profiles so that the last 10 bytes contain
the distribution information (See the later discussion of the
CHGOBJD3 TAA Tool for a simple solution). The TAASPMDC2 program
extracts the last 10 bytes of the text description of the user
profile object that is the owner of the spooled file and places it in
the &DST1 return parameter.
If you change your user profiles, you could use the TAASPMDC2
program. The TAA Tool CHGOBJD3 will let you do this easily. You
would enter the command:
CHGOBJD3 OBJ(USER1) OBJTYPE(*USRPRF)
An interactive display is presented with the current text description
of the user profile. A ruler is shown to identify positions 1 - 50.
Enter the distribution information beginning at position 41.
If you have similar distribution information in a data base file and
want to access it with your own program do the following:
Copy out the source with the command:
CPYTAA TAAARCMBR(TAASPMDC2) TOSRCFILE(xxx)
This CL source should be used as a model to write your own version.
It is important to note the following when using a program to supply
distribution information:
** The program must be written to receive 3 parameters:
- User *CHAR 10 - The name of the spooled file owner.
- Dst1 *CHAR 10 - The value you want returned for *DST1.
- Dst2 *CHAR 10 - The value you want returned for *DST2.
It is not required that any value be placed in the
Distribution 2 return variable. You can use just the
Distribution 1 variable.
** The page separator program TAASPMDR is specified on the
CHGDEVPRT command as described earlier (do not specify the
program you are creating to supply the distribution
information).
When the spool writer runs, it operates under the QSPLJOB user
profile. This profile has no special authority. The sample
program (TAASPMDC2) uses RTVOBJD to access a user profile
object. Most user profiles are created without any public
authority to allow access. Consequently, the sample program
is owned by QSECOFR and is created with OWNER(*USRPRF). This
adopts the QSECOFR profile to ensure access.
Depending on what your program is accessing, you may need to
create the program with OWNER(*USRPRF).
** When the spool writer starts, the QSPLPRTW job description is
used. This job description uses *SYSVAL as the library list.
If you describe user objects in the exit program, you may need
to library qualify their use such as with an OVRDBF command or
a qualified user command.
** The TAAPAGSEP1 application value must be changed to name the
program you create. As a user with *ALLOBJ authority, edit
the application value with the command:
EDTAPPVAL APPVAL(TAASECURE/TAAPAGSEP1)
Enter your program and library name for the values:
- User program to provide *DSTn
- User pgm lib to provide *DSTn
You are now ready to specify the *DST1 and/or *DST2 value for
the Job or File Separator values in TAAPAGSEP1.
Debugging the exit programs
---------------------------
The function provided by the system for the SEPPGM parameter on
CHGDEVPRT assumes that if the user exit program fails, the normal
system separator page will be produced. The spool writer job log
will contain any error messages sent to the exit program.
Consequently, if you are experiencing problems, use WRKWTR and end
the writer with OPTION(*IMMED). Use WRKSPLF QSPLJOB to display the
job logs owned by QSPLJOB. Find the job log for the specific
printer. You should be able to determine from the messages what
error occurred to cause the the normal system separator page.
The system retains pointers to the sub programs in some cases. If
you see a message that indicates a program no longer exists, try
ending the writer and starting again.
Further customization
---------------------
In some cases you may want to print a field from the spooled file
attributes that is not in the standard list (such as the job name or
user) supplied by the tool.
You can achieve this by first going thru the previous steps to name
the SEPPGM as TAASPMDR. Then change the TAASPMDR program and
substitute the value you want for one of the supplied values.
Begin by:
CPYTAA TAAARCMBR(TAASPMDR)
By default, the source will be placed in the TAASPMDR member of
QATTRPG in TAATOOL. You could specify your own member and source
file.
Scan the source for *CUSTOM. It describes how to do a move from one
of the fields in the SPLDS data structure to one of the fields to be
printed such as SPJOB (job name) or SPUSER (user name). Pick one
that you don't need to be printed.
If you don't find the field you want in the SPLDS data structure,
look at format SPLA0200 of the QUSRSPLA API. Add your field to the
SPLDS data structure (remember that fields are offset so you must add
one to the starting and ending location).
Delete the existing program:
DLTPGM PGM(TAATOOL/TAASPMDR)
And recreate it (if you used a different source file and member name,
substitute yours):
CRTRPGPGM PGM(TAATOOL/TAASPMDR)
SRCFILE(TAATOOL/QATTRPG)
SRCMBR(TAASPMDR)
Assume you picked SPUSER as the field to contain your value. You
then need to update the TAAPAGSEP1 Application Value and describe
that you want to print *USER.
EDTAPPVAL APPVAL(TAASECURE/TAAPAGSEP1)
The default is to print *USER (the user information) as the first set
of block letters.
Multiple devices
----------------
You may specify the TAASPMDR program for all or specific print
devices.
If you have certain print devices where you want to vary the contents
of the separator pages, you may use the second version of the
TAASPMDR program and the TAAPAGSEP1 application value that are
shipped with the product. To use the second version, specify:
CHGDEVPRT DEVD(xxx) SEPPGM(TAATOOL/TAASPMDR2)
This version of the program works with the TAAPAGSEP2 Application
Value (user space object). Edit the values with the command:
EDTAPPVAL APPVAL(TAASECURE/TAAPAGSEP2)
If you need more than 2 versions, the following describes how to
create a 3rd version. Create as many version as needed, by just
changing the last character from 3, to 4, 5, etc.
Use CPYTAA to copy out the source for TAASPMDR to a source file in
your own library.
Edit the source for the TAASPMDR program. Scan for the letters
USRSPC. You should see the value 'PAGSEP1' being moved to the
parameter for USRSPC. For the 3rd variation, change this to PAGSEP3.
Create the program in your own library.
Change the device description for the desired printer file for the
program you created.
The TAASPMDC program is standard and does not need to be changed.
Use CRTDUPOBJ to duplicate the TAAPAGSEP1 user space (*USRSPC) in
TAASECURE to TAAPAGSEP3 in TAASECURE.
Use EDTAPPVAL on the new user space and specify the required values.
Translating the constants for the detail information
----------------------------------------------------
The detail information that appears at the bottom of each separator
page is supplied from constants and the TAASPMDR program. The
majority of constants should be automatically changed by the system
to your native language by the use of message IDs CPX070A and CPX0703
in QCPFMSG.
A few constants are stored in the PAGSEP data area in TAASECURE. Use
the command:
EDTDTAARA2 DTAARA(TAASECURE/PAGSEP)
and key over the top for your native language. The text to the right
'Limit of nn' describes the maximum length of each constant.
When the next release of the TAA Productivity Tools is installed, the
contents of any existing information will not be changed.
Command parameters *CMD
------------------
No command exists.
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
APPVAL Application value
Implementation
--------------
You must make the changes as described in the 'Getting started'
section.
You may optionally change the values that appear in the block letters
as described previously and/or add an exit program to provide
distribution information.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
TAASPMDC *PGM CLP TAASPMDC QATTCL
TAASPMDC2 *PGM CLP TAASPMDC2 QATTCL
TAASPMDR *PGM RPG TAASPMDR QATTRPG
TAASPMDR2 *PGM RPG TAASPMDR2 QATTRPG
TAAPAGSEP1 *USRSPC
TAAPAGSEP2 *USRSPC
PAGSEP *DTAARA
Both the TAAPAGSEP1 and TAAPAGSEP2 user spaces and the PAGSEP data
area exist in the TAASECURE library.
TAASPMDC2 is the sample exit program to access the distribution
information from the user profile.
TAASPMDR2 is the second version of the page separator program that
works with the TAAPAGSEP2 user space.
The PAGSEP data area contains the constants used for the Distribution
text that may be translated.
|
