This document describes the Natural features supported by Natural Advanced Facilities and how these features can be used.
The DEFINE PRINTER statement is used to assign a
symbolic name to a report number and to control the allocation of a report to a
logical destination (printer).
Note:
The DEFINE
PRINTER statement is fully described in the Natural
Statements documentation. This
section only describes the clauses that apply for Natural Advanced
Facilities.
This section also covers information on Mixed Reports by using DEFINE PRINTER.
The DEFINE PRINTER statement syntax for NAF below is
different from the general DEFINE
PRINTER statement as not all of the keywords apply:
DEFINE
PRINTER |
([logical-printer-name =
]n ) |
||||
[OUTPUToperand1
] |
|||||
|
|
PROFILE operand2DISP operand3COPIESoperand3PRTYoperand4 |
|
|||
4 |
|||||
logical-printer-name is
the name which is to be allocated to printer n. This
is the name which will be used for the
rep notation in a DISPLAY
or WRITE statement. The value for
n may be in the range of
1-31.
The OUTPUT operand is the destination within the
online spooling system and is a logical printer (LPF). This logical printer
must be defined on the spool file (see Function 31.2), but need not be part of
the currently active user profile.
With the PROFILE clause, you specify as
operand2 the name of a printer control
characters table as defined in the NTCC macro or on the
spool file (see NTCC table, Function
31.8).
For the DISP clause, the possible values for
operand2 are DEL,
HOLD and KEEP. If the DISP clause is
omitted, the Disposition specified for the logical printer is used.
With the COPIES clause you specify the number of
copies to be printed. The possible values for
operand3 are 1-255. If the
COPIES clause is omitted, the number of copies specified for the
logical printer is used.
With the PRTY clause, you specify the priority for
spool-out. The possible values for
operand4 are 1-255 (where
1 is the lowest and 255 is the highest priority). If
the PRTY clause is omitted, the priority specified for the logical
printer is used.
In general, Natural Advanced Facilities uses the logical printer definitions in the physical main storage (not the ones on the spool file). One has to distinguish two different situations:
the requested logical printer is contained in the active user profile,
the requested logical printer is not contained in the active user profile.
If a DEFINE PRINTER statement for printer
n requests a logical printer which is
contained in the active user profile (see Example 1 below), logical printer
definitions in storage are not overwritten. A subsequent Natural
program will therefore encounter the same logical printer definitions. The
logical printer definitions will be valid until another DEFINE
PRINTER statement causes them to be overwritten.
If a DEFINE PRINTER statement for printer
n requests a logical printer which is
not contained in the active user profile (see Example 2 below), the
n-th logical printer definition in
storage will be overwritten by the requested one. A subsequent Natural program
will encounter altered logical printer definitions as established by the
previous DEFINE PRINTER statement (because it is assumed that the
altered logical printer definitions are also to be used by subsequent Natural
programs.)
The following examples demonstrate how the DEFINE
PRINTER statement works.
DEFINE PRINTER (2) OUTPUT 'LPF1' ... ... WRITE (2) 'text' ... WRITE (1) 'different text' ...
When the above Natural program is run, the output of the
WRITE (2) statement is spooled by using the definitions of
LPF1. The WRITE (1) statement uses LPF1
by default, since there is no DEFINE PRINTER (1) statement.
Therefore, both WRITE (1) and WRITE (2) statements
use the same logical printer.
If a subsequent Natural program executes a WRITE (2)
statement, and if the program does not contain a DEFINE PRINTER
(2) statement, the output is spooled by using the definitions of
LPF2.
If the OUTPUT operand of the DEFINE
PRINTER statement is not identical to one of the logical
printer names in the active user profile, the values for the printer profile
are overwritten with the new values specified in the OUTPUT
operand.
... DEFINE PRINTER (2) OUTPUT 'LPF9' ...
The OUTPUT operand of the above DEFINE
PRINTER statement causes the definitions of LPF2 to be
overwritten with the values assigned to LPF9, including the
logical printer name. The active user profile is changed to the following:
This definition remains in effect for the user profile until
another DEFINE PRINTER (2) statement is executed. Thus, the output
of all subsequent WRITE (2) statements within the same Natural
session is spooled by using the definitions of LPF9, if no other
DEFINE PRINTER (2) statement is executed.
Natural programs sometimes need to create different reports for
the same physical printer. In this case, attention has to be paid to the
OUTPUT operand of the DEFINE PRINTER statement.
If you use DEFINE PRINTER statements for different
logical printers but with the same OUTPUT operand (that
is, the same logical printer name), only one report is created. This
report contains the output of all WRITE, PRINT or
DISPLAY statements in a mixed sequence.
DEFINE PRINTER (1) OUTPUT 'LPF1' /* LPF same as in (0020) DEFINE PRINTER (2) OUTPUT 'LPF1' /* LPF same as in (0010) WRITE (1) 'This is for report 1' WRITE (2) 'This is for report 2' WRITE (1) 'This is for report 1' END
If you use DEFINE PRINTER statements for different logical printers and with different OUTPUT operands (that is, different logical printer names), multiple reports are created. To route these reports to the same physical printer, the same Destination/Form must be specified for the logical printers.
DEFINE PRINTER (1) OUTPUT 'LPF1' /* LPF different from (0020) DEFINE PRINTER (2) OUTPUT 'LPF2' /* LPF different from (0010) WRITE (1) 'This is for report 1' WRITE (2) 'This is for report 2' WRITE (1) 'This is for report 1' END
You can emphasize all or parts of printed reports by using Con-form instructions, for example, during a Con-nect session.
Support is provided for the following Con-form instructions:
| Instruction | Description |
|---|---|
.BF |
The text lines between two .BF
instructions are printed in boldface.
|
.BP |
Text contained on the next input line is printed in boldface. |
.US |
Text contained on the next input line is underscored. |
char B |
Backspace to super-impose one character over another. |
char U1...
char U0 |
Text within the symbols U1 and
U0 is underscored.
|
char M1...
char M0 |
Text within the symbols M1 and
M0 is printed in boldface.
|
char is any special
character which has been defined as the escape character by using the following
Con-form instruction:
.OP ESC=char
Note:
Text can only be printed in boldface if the Natural profile
parameter INTENS (see the
Natural Parameter Reference documentation) has been set to
a value greater than 1.
The Natural terminal command %H, when issued in
response to a prompt, produces output from Natural reports and communication
screen layouts on a printer. The output will be routed to the first
FREE physical printer allocated for the defined logical printer
for hardcopy (see Functions 12,
30.5,
31.1 and
33). The
%H command is effective for the current page and is
automatically disabled at the end of the program output.
If %H is used for a map created by an INPUT
statement, the complete contents of the page buffer is spooled to the output
device.
The same applies for the SET CONTROL 'H'
statement.
The NATSPOOL nucleus closes reports when Natural
returns to command mode. If a Natural application program uses a STACK
COMMAND statement to load another Natural program, command mode is
entered and reports created by the invoking program are closed and printed
according to their Disposition (provided that Natural is in ET status, that is,
no user END OF TRANSACTION statement is pending). However, if a
FETCH statement is used, command mode is not entered internally
and reports created by the invoking program are closed and printed only when
the invoked program ends. This allows more than one Natural program to be
involved in the creation of a single report.
* PGM-1 WRITE (1) 'output from PGM-1' STACK COMMAND 'PGM-2' END
* PGM-2 INPUT 'something' F1 (A8) (AD=MI) END
When Program PGM-1 is executed, the report created by the
WRITE (1) statement is closed and printed immediately.
* PGM-1 WRITE (1) 'output from PGM-1' FETCH 'PGM-2' END
* PGM-2 WRITE (1) 'output from PGM-2' INPUT 'something' F1 (A8) (AD=MI) END
When Program PGM-1 is executed, the report created by
the WRITE (1) statement is not printed immediately. When the
INPUT statement in Program PGM-2 is executed, the
report status is LOAD (the report is not yet closed). The report
is closed and printed only after PGM-2 ends. The output created by
PGM-2 is written to the same report as the output of
PGM-1.
The NATSPOOL nucleus attempts to issue an Adabas
ET command for a given report only when the close request is
executed. The close request is executed when Natural returns (internally) to
command mode or when a CLOSE PRINTER statement is executed. At
that time it is checked whether Natural is in ET status, that is,
if a user END OF TRANSACTION statement is pending. The
NATSPOOL nucleus issues an ET command
only if Natural is in ET status (if no user ET is
pending). This ensures that reports are stored completely on the spool file and
that no interference with user transaction logic occurs.
Special attention has to be paid to the order of the END OF
TRANSACTION and CLOSE PRINTER
(rep) statements, as shown in Examples 6 to 8
below.
When creating long reports on an Adabas spool file, the
transaction time limit for ET logic users (ADARUN
TT parameter) must be appropriately defined. When the
time limit is exceeded, the report is backed out from the spool file.
The hold queue size (ADARUN NH
parameter) must be large enough to prevent Response Code 145 (HOLD QUEUE
OVERFLOW) during creation of a report.
The data protection area (ADARUN
LP parameter) must be large enough to prevent Response
Code 9.
READ (1) PERSONNEL BY NAME
UPDATE ...
WRITE (1) 'string'
END OF TRANSACTION
END
The PERSONNEL file is updated, and the report is
printed. An ET is issued by Natural (not by
NATSPOOL).
READ (1) PERSONNEL BY NAME
UPDATE ...
WRITE (1) 'string-1'
END OF TRANSACTION
WRITE (1) 'string-2'
END
The PERSONNEL file is updated, and the report is
printed.
The END OF TRANSACTION statement forces Natural to
issue an ET. Once this ET
is executed, the PERSONNEL file is updated, the output
string-1 is stored on the spool file, and the report is
in status LOAD. Since Natural is now in ET status,
NATSPOOL issues another ET to store the
output string-2. The report status is set to
TOBE.
If an interruption occurs between the execution of the END
OF TRANSACTION and the subsequent ET of
NATSPOOL, the output string-2 will be backed
out from the spool file and the report will remain in status LOAD.
If the program above had no END OF TRANSACTION and the
CLEAR key were pressed, the entire report would be backed out. This
is because Natural issues a BT when the
CLEAR key is pressed.
The report can be recovered (that is, status TOBE can
be forced) by issuing the function code RC with
Function 10.
READ (1) PERSONNEL BY NAME UPDATE ... WRITE (1) 'string' END
The PERSONNEL file and the report are in
HOLD status. If the user presses the CLEAR key or
terminates the Natural session, the report is backed out from the spool
file.
No ET is issued, and the report can
neither be cancelled nor recovered by another user.
READ (1) PERSONNEL BY NAME UPDATE ... WRITE (1) 'string' BACKOUT TRANSACTION END
The update to the PERSONNEL file and the
report are backed out. No ET is issued.
READ (1) PERSONNEL BY NAME WRITE (1) 'string' END
The report is printed, and an ET is
issued by NATSPOOL (not by Natural).
READ (1) PERSONNEL BY NAME
UPDATE ...
WRITE (1) 'string'
END OF TRANSACTION
CLOSE PRINTER (1)
END
The PERSONNEL file is updated, and the report is
printed as soon as the CLOSE PRINTER statement is executed. An
ET is issued by Natural (not by
NATSPOOL).
READ (1) PERSONNEL BY NAME
UPDATE ...
WRITE (1) 'string'
CLOSE PRINTER (1)
END OF TRANSACTION /* issued too late
END
During close processing (forced by the CLOSE PRINTER
statement), the PERSONNEL file is still in hold. Since the start
of printing is triggered during close processing, the report is not printed,
but remains on the spool file in status TOLA (END OF
TRANSACTION issued too late). An ET is issued
by Natural (not by NATSPOOL).
READ (1) PERSONNEL BY NAME
UPDATE ...
WRITE (1) 'string'
CLOSE PRINTER (1)
END
During close processing (forced by the CLOSE PRINTER
statement), the PERSONNEL file is still on hold. Since the start
of printing is triggered during close processing, the report is not printed,
but remains on the spool file in status NOCL (not closed,
END OF TRANSACTION missing).
No ET is issued, and the report can
neither be canceled nor recovered by another user.
If the TP monitor terminates abnormally while
NATSPOOL is printing, the report is not lost. The report remains
on the spool file, with status ONPR.
After the TP monitor has been restarted, the report can be
recovered by issuing the function code RC with
Function 10. This forces the
report status TOBE. Thereafter, the printer can be restarted to
print the report.
These utility modules are provided to read the spool file and
print reports in batch mode. The modules are cataloged as
SPPBATPR, NSPOBAT, and SPPPRINT in the
Natural system library SYSPOOL.
Below is information on:
Reports printed with NSPOBAT are selected by their
Destination/Form identification, similar to Function 10 (Reports/Queues).
All reports selected with Disposition D,
K or H are printed as many times as requested when
creating the report. Reports with other Dispositions are not printed.
To delete all reports with Disposition D or
H from the spool file after the print job has terminated, specify
PURGE as the last parameter. Reports with other Dispositions are
not deleted.
Reports printed with SPPBATPR are selected by their
Destination/Form identification, similar to Function 10 (Reports/Queues).
All reports selected with Disposition D or
K are printed as many times as requested when creating the
report.
To delete all reports with Disposition D from the
spool file after the print job has terminated, specify PURGE as
the last parameter.
Reports printed with SPPPRINT are selected by their
Destination/Form, Disposition, user ID and by the number of days (age in days)
or the creation date.
Number of days determines that all reports are printed that exceed the number of days specified as storage limit for the spool file.
The creation date determines that all reports with a creation date earlier than the date defined are printed.
All selected reports are printed as many times as requested when creating the report.
To delete all reports from the spool file after the print job
has terminated, specify PURGE as the last parameter.
In the following examples, all reports from the spool file with
Form A and a destination that begins with ROOM are printed.
//SPPBATPR JOB SPPBATPR,CLASS=G,MSGCLASS=X //LIST EXEC PGM=NATBATCH,PARM='IM=F,FSPOOL=(,XXX)' //STEPLIB DD DSN=NATURAL.V41.LOAD,DISP=SHR // DD DSN=ADABAS.V61.LOAD,DISP=SHR //DDCARD DD DSN=NATURAL.V41.SOURCE(ADAPARM),DISP=SHR //CMPRINT DD SYSOUT=X //CMPRT01 DD SYSOUT=X //CMSYNIN DD * LOGON SYSPOOL SPPBATPR DESTINATION=ROOM*,FORM=A FIN /*
If you want to delete reports by using NSPOBAT,
SPPBATPR or SPPPRINT without printing them, in z/OS,
instead of allocating CMPRINT to SYSOUT, you can
allocate CMPRINT to DUMMY.
LOGON SYSPOOL SPPBATPR DESTINATION=xxxxxxxx,FORM=y,PURGE=PURGE FIN
All reports with destination xxxxxxxx and form yare deleted from the spool file after they have been printed.
All reports from the spool file are printed, and deleted after printing.
LOGON SYSPOOL SPPBATPR DESTINATION=*,FORM=*,PURGE=PURGE FIN
After starting the MENU program in the
SYSPOOL library, this subprogram is invoked. You can use this
subprogram to define your own settings, authorizations, etc. You must not
modify the settings for the message line (%M) and PF-key line
(%Y).
After the SYSPOOL application is terminated, this
subprogram is invoked. You can use this subprogram to control your
environment.
This subprogram is used by the spool server during a Natural session. It receives control before a block is sent to the printer. The delivered source contains all parameter information. When you modify data in this subprogram, the modified data are sent to the printer unchecked.
If your printer requires a different user exit, with the
parameter information supplied with USPSER01 you can write a user
exit subprogram that meets your requirements and catalog it in the Natural
system library SYSPRINT. To assign the user exit to the printer,
use Function 31.4 and enter the name of the user exit subprogram in the field
Server Exit. Your user exit will then take over control before a
block is sent to the printer.
For further details, see Function 31.4 (Printer) in the section Objects - Function 31.
The Natural administrator can use the program
SPPULDUS to unload objects (user profiles, logical printers,
physical printers, etc.) from a spool file into Work File 3.
SPPULDUS is supplied in the library SYSPOOL.
The following functions codes are available for
SPPULDUS:
| Function Code | Description |
|---|---|
1 |
Unload user profile. |
2 |
Unload logical printer. |
3 |
Unload allocation table. |
4 |
Unload physical printer. |
5 |
Unload header pages. |
6 |
Unload application. |
7 |
Unload cluster. |
8 |
Unload NTTC table. |
9 |
Unload calendar. |
* |
Unload all items. |
To load objects from Work File 3 into a spool file, the
administrator can use the program SPPLODUS. SPPLODUS
is supplied in the library SYSPOOL.
In batch mode, SPPLODUS can also be used to load
objects into a spool file from a user-created work file assigned to
CMWKF03. To modify multiple objects in batch, first unload objects
into this work file by using SPPULDUS, then modify objects by
using any edit/change tool, and finally reload the objects by using
SPPLODUS. See the Natural Advanced Facilities online help for
information on the layout of the unloaded objects (on the help menu, select
Function 99 and then Function 1).
Note:
When executing SPPLODUS, none of the above listed
function codes need to be specified.
//SPPULDUS JOB CLASS=K,MSGCLASS=X //SPPULDUS EXEC PGM=NAT41OBT,REGION=2000K,PARM='FSPOOL=(XXX,XXX),IM=D' //STEPLIB DD DSN=NATURAL.V41.LOAD,DISP=SHR // DD DSN=ADABAS.V61.LOAD,DISP=SHR //DDCARD DD DSN=NATURAL.V41.SOURCE(ADAPARM),DISP=SHR //CMPRINT DD SYSOUT=X //CMWKF03 DD DSN=NAF41.UNLOAD,DISP=SHR //CMSYNIN DD * LOGON SYSPOOL SPPULDUS * . FIN
The sample SPPULDUS execution job leads to the
following output:
NEXT LOGON SYSPOOL LOGON ACCEPTED TO LIBRARY SYSPOOL NEXT SPPULDUS DATA * UNLOADED USER PROFILES : 17 UNLOADED LOGICAL PRINTERS : 33 UNLOADED ALLOCATIONS : 101 UNLOADED PHYSICAL PRINTERS : 48 UNLOADED EJECT CONTROLS : 51 UNLOADED MESSAGE HEADERS : 2 DATA . NEXT FIN NAT9995 NATURAL SESSION TERMINATED NORMALLY
. . . LOGON SYSPOOL SPPLODUS FIN . . .