NAF - Features in a BS2000/OSD Environment

This document explains the features of Natural Advanced Facilities specific to a BS2000/OSD environment:

Overview

NATSPOOL accumulates all reports generated during a Natural user session in the spool file. To physically print a report, NATSPOOL performs an event to pass control to a Natural batch session.

This new Natural session, the NATSPOOL spool server, retrieves various dynamic parameters from the task which has issued the event by using a BS2000/OSD common memory pool (CMP).

The logical connection between the two Natural sessions used by NATSPOOL is shown below.

BS2000/OSD Options

After Natural Advanced Facilities has been installed, you must set the BS2000/OSD options by using Function 30.5.

Automatic Start of Spool Server - openUTM only

It is possible to start the spool server automatically when openUTM is started by specifying the SPOOL parameter in the NATUM macro. The spool server will then be active any time Natural Advanced Facilities is used in a openUTM environment.

The SPOOL parameter has the following syntax: 

SPOOL=(NATSPOOL,'name',nn)
Parameter Description
NATSPOOL Refers to the remote spool system of Natural Advanced Facilities.
' name' The name of the enter-job which starts the spool server.
nn The number of spool servers to be started. As many as 30 spool servers may be started at the same time.

Example of the SPOOL Parameter: 

SPOOL=(NATSPOOL,'E.PTTASK',2)

If a spool server cannot be started (for example, if the batch limit has been reached) the openUTM driver will issue the message: 

SYSTEM ERROR: PLEASE GIVE KDCOFF

Printing on System Printers

If a report is to be sent to a system printer, the user profile must contain the following:

  • a physical printer with the name SYSTEM must be defined; and

  • a logical printer which must be assigned to the physical printer SYSTEM.

The spool server then recognizes that any reports generated for this printer are to be sent to the system printer. The report is written to the BS2000/OSD EAM-space via the WRLST macro, and then the report is printed on the appropriate system printer (via the BS2000/OSD command PRINT *SYSLST). No remote printer is activated.

The various print preprocessing activities, affecting, for example, the print control characters, are performed in the spool server. As long as the report remains in the spool file, it can be sent to any remote printer.

For printing of reports on a system printer, the macro PRNT is used with the following specifications: 

PRNT *SYSLST,ERASE,SPACE=E,
             COPIES=number of duplicates as specified in the LPF,
             PNAME=user ID of report,
             FORM=destination of report or value of BS2FORM from 
                  NAF parameter module,

Note:
If Natural Security is installed, the Natural Security user ID is taken as Sending User ID. If Natural Security is not installed, the terminal ID is taken as Sending User ID.

Printing on RSO Printers

For printing of reports on an RSO printer, the macro PRNT is used with the following specifications: 

PRNT *SYSLST,ERASE,SPACE=E,
             COPIES=number of duplicates as specified in the LPF, 
             PNAME=user ID of report,
             FORM=destination of report, or value of RSOFORM from NAF parameter
                  module, or value defined for physical printer (31.4),
             DEV=physical printer

Note:
If Natural Security is installed, the Natural Security user ID is taken as Sending User ID. If Natural Security is not installed, the terminal ID is taken as Sending User ID.

Implementation of Spooling

One or more spool servers (maximum 30) must be active for NATSPOOL to function under BS2000/OSD. These tasks are started as batch tasks and are always present. If no reports are allocated to a printer, the spool server is in WAIT status and minimal CPU time is used. When a report is generated from a Natural session, the NATSPOOL nucleus searches for the specified printer and activates the spool server with the P1-EVENTING mechanism.

The communication for P1-EVENTING is defined by the parameters NAFERK1 and NAFERK2 in the BS2000/OSD parameter module NAFB2P for Natural Advanced Facilities; for more information, see Installing Natural Advanced Facilities on BS2000/OSD. The values for NAFERK1 and NAFERK2 must be unique for a given CPU. Thus, it is possible to run two different Natural environments in parallel on the same CPU and to work with different NATSPOOL environments. For each Natural installation and for each Natural Advanced Facilities installation, the parameters for P1-EVENTING and DCAM communication (DC0 - DC30) must be different. When installing two or more Natural or Natural Advanced Facilities environments using the same BS2000/OSD user ID, it is possible to create different modules for NAFB2P by the setting the BS2000/OSD procedure parameter PRGSUFF in the respective installation jobs. This parameter must be unique for each installation.

The spool server, which is a DCAM application, performs the following:

  • Activates the specified printer (DCAM macro YOPNCON). If the printer cannot be activated the spool server sets the printer to INOP status.

  • Reads the report from the spool file.

  • Sets the printer control characters to correspond with those for that printer as specified in the printer definition.

  • Submits the report (DCAM macro YSEND) to the printer in segments equal in size to the printer buffer size.

After each segment of the report has been submitted, the transfer acknowledgment (DCAM macro YRECEIVE) will be checked to determine whether the report was printed. Otherwise, following a specific waiting period, another attempt will be made. If submitting is still not successful, the printer will be set to INOP status.

After the report has been printed, the spool server checks whether an additional report for this printer has been written to the spool file. If so, this report will be printed immediately. If no additional reports are waiting, the printer will be deactivated (DCAM macro YCLSCON) and become available for other spool systems. The spool server will return to WAIT status until a new PRINT command for this or another printer is issued.

User Exits for the Spool Server

Under BS2000/OSD, Natural Advanced Facilities provides the user exits described below. The user exits are written in Assembler. All information passed to these user exits uses Software AG-defined DSECTS named NAFDINFO, NAFDTECH and NATDINFO.

NAFEXIT1

This user exit must be linked to the front part of the spool server by using the CSECT name NAFEXIT1. The exit is activated for all physical printers defined with the field User Exit defined as EXIT1. The exit gets control line by line for each report. The spool server will not rework any report data.

This exit executes the following functions:

Code Function
1 Open report
2 Write report
3 Send report

Correct execution of the exit has to be communicated via register 15 (value=0). Otherwise, the content of the exit is recognized as a negative return code.

Register 1 adresses the following parameter area:

Offset Address of
0 Function code
4 Unused, must not be modified
8 Data area
12 Length
16 NAFDINFO
20 NAFDTECH
24 NATDINFO

Unused addresses are set to a high value by the spool server.

Register 13 adresses the save area for registers. Register 15 must contain the return code.

NAFEXIT2

This user exit must be linked to the front part of the spool server by using the CSECT name NAFEXIT2.

Before the DCAM macro YSEND is executed, the message block is passed to the exit to enable the user to modify the data area. The modified message block will then be sent to the respective printer by using the DCAM macro YSEND. If a modification to the message block results in a new message length, the corresponding parameter must be updated.

Correct execution of the exit has to be communicated via register 15 (value=0). Otherwise, the content of the exit is recognized as a negative return code.

Register 1 adresses the following parameter area:

Offset Address of
0 Unused
4 Unused
8 Data area
12 Length
16 NAFDINFO
20 NAFDTECH
24 NATDINFO

Unused addresses are set to a high value by the spool server.

Register 13 adresses the save area for registers. Register 15 must contain the return code.

NAFEXIT3

This user exit must be linked to the spool server by using the CSECT name NAFEXIT3.

This exit controls all functions to be executed for a start request. The spool server ignores all activities, it only calls the exit and checks the return code.

This exit executes the following functions:

Code Function
1 Open connection to the spool device
2 Open report
3 Send report data
4 Close report
5 Close connection to the spool device

Correct execution of the exit has to be communicated via register 15 (value=0). Otherwise, the content of the exit is recognized as a negative return code. When a function terminates with an error, a function name can be returned by using offset 4 of Register 1.

Register 1 adresses the following parameter area:

Offset Address of
0 Function code
4 abnormally terminated function
8 Data area
12 Length
16 NAFDINFO
20 NAFDTECH
24 NATDINFO

Unused addresses are set to a high value by the spool server.

Register 13 adresses the save area for registers. Register 15 must contain the return code.

NAFEXIT4

This user exit must be linked to the front part of the Natural openUTM or TIAM Interface by using the CSECT name NAFEXIT4.

This exit controls all functions executed when creating a report. The spool data is not stored on the spool file and ET/BT logic is not supported.

This exit executes the following functions:

Code Function
1 Open report
2 Write report
3 Close report and write no more data
4 Close report and write last data

Correct execution of the exit has to be communicated via register 15 (value=0). Otherwise, the content of the exit is recognized as a negative return code.

Register 1 adresses the following parameter area:

Offset Address of
0 Function code
4 Number of logical printer
8 Data area
12 Length
16 NAFDINFO
20 Unused
24 NATDINFO
28 User-specific field

Unused addresses are set to a high value by the spool server.

Register 13 adresses the save area for registers. Register 15 must contain the return code.

Communication with Natural

Online Natural communication with the spool server is done via the P1-EVENTING mechanism and a common memory pool.

Besides the parameter FSPOOL for the Natural spool file, the values for the parameters FNAT and FSEC are also transmitted.

Under BS2000/OSD, three ways of communication between Natural and the spool server are possible, see the illustrations below.

If an error occurs while Natural communicates with the spool server, the system administrator is able to reset the common memory pool. See Function 40.6.

One Natural Environment with One Spool Server

Two Natural Environments with One Common Spool Server

Two Natural Environments with Own Spool Server Each

BS2000/OSD Monitor

With the help of the BS2000/OSD monitor you can start a report from the computer where it has been created, even if the configuration cannot communicate with a spool server.

When using a monitor task, the following must be defined in the NAF parameter module:

  • The parameter MONEVT must be defined for the P1-EVENTING of the monitor. For P1-EVENTING, you can only start one monitor task.

  • The parameter PAMO must be defined with a valid LOGON command for the monitor.

The Natural program SVPMON01 which is activated when the monitor is started, expects the following input:

  • The time interval in minutes for checking the spool file. Valid values are 1 to 300.

  • How the messages concerning the executed actions (for example, check or start) are to be treated.

  • Database ID and file number of the spool file to be checked. You can define up to 50 different spool files. After the last required spool file, specify 99999 as the database ID to indicate the end of the list.

Example:

Computer 1 has no printers, no spool file and no spool server. Only Computer 2 has printers connected to it as well as a spool file and spool server.

Reports created on Computer 1 can only be printed by using Computer 2. They are stored on the spool file of Computer 2. Since the start of output is controlled by P1-EVENTING, it is not possible to start reports from Computer 1.

To start reports from Computer 1, you can proceed as follows:

  • On the spool file of Computer 2, define logical printers which refer to allocations whose queue status is set to MONITOR.

  • All reports created on Computer 1 use the above logical printers

  • On Computer 2, define and start a monitor task (in addition to the spool servers).

In defined intervals, the monitor task will now check the spool file for reports that belong to a monitor queue. When reports are found and a spool server for this queue is not active, output for this queue is automatically started.