Version 6.3.8 for OpenVMS
 —  Operations  —

Natural in Batch Mode

This document contains special considerations that apply when running Natural in batch mode. It covers the following topics:


What is Batch Mode?

Natural distinguishes between two processing modes:

The main difference between these two modes is that in interactive mode, the commands and data are input by the user by means of the keyboard and the output is displayed on a screen. In batch mode, input is read from a file and output is written to a file - without user interaction.

When Natural is run as a batch job, no interaction between Natural and the person who submitted the batch job is necessary. The batch job consists of programs that are executed sequentially and that receive sequential input data.

Batch mode is useful for mass data processing on a regular basis.

Top of page

Starting a Natural Session in Batch Mode

Batch mode is activated with the parameter BATCHMODE.

Start of instruction setTo start a Natural session in batch mode

  1. Start Natural with the dynamic parameter BATCHMODE as shown below:

    natnn BATCHMODE

    where nn is the current version number

    The above call (where only the BATCHMODE parameter is specified) assumes that the required input and output channels have already been defined in the Configuration Utility. For information on the input and output channels, see Using Natural in Batch Mode later in this section). For information on the batch-mode-relevant profile parameters in the parameter file, see Batch Mode in the Configuration Utility documentation.

    It is also possible to add the required input and output channels as dynamic parameters to the above call. This is illustrated in Sample Session for Batch Mode later in this section. Any input and output channels that are specified as dynamic parameters with the above call override the channel definitions in the parameter file.

  2. Check the file which has been defined as the output channel. At its end, this file should contain the message that your session has terminated normally.

Top of page

Terminating a Natural Session in Batch Mode

A Natural session in batch mode is terminated when one of the following is encountered during the session:

Note:
When an end-of-input condition occurs in the batch input file, the batch session is also terminated. In this case, the file which has been defined as the output channel contains a message which indicates an unexpected end.

Top of page

Using Natural in Batch Mode

To start a Natural session in batch mode you have to specify the dynamic parameter BATCHMODE. In addition, input and output channels have to be defined as described below.

Important:
The input channels CMSYNIN and/or CMOBJIN and the output channel CMPRINT are always required for batch mode.

The following topics are covered below:

Input and Output Channels

The following parameters are available for batch mode:

Parameter Description
CMSYNIN Defines the batch input file which contains the Natural commands and (optionally) data to be read by INPUT statements during execution of Natural programs.
CMOBJIN Defines the batch input file which contains the data to be read by INPUT statements. This data can alternatively be placed in the file defined with the parameter CMSYNIN, immediately following the relevant RUN or EXECUTE command.
CMPRINT Defines the batch output file for the output resulting from DISPLAY, PRINT and WRITE statements in a Natural program.
CMPRTnn Defines an output file for additional reports referenced by any Natural program executed during the session. nn is a two-digit decimal number in the range from 01 to 31 which corresponds to the report number used in a DISPLAY, PRINT or WRITE statement.
CMWRKnn Defines a work file referenced by any Natural program executed during the session. nn is a two-digit decimal number in the range from 01 to 32 which corresponds to the number used in a READ WORK FILE or WRITE WORK FILE statement.
NATLOG Used to log messages that could not be written to the batch output file defined with the parameter CMPRINT. It is recommended to enable NATLOG in batch mode.

Code Pages for the Input and Output Files

The following parameters are used to specify the code pages in which the input files are encoded and in which the output file shall be encoded.

Parameter Description
CPSYNIN Specifies the code page in which the batch input file for commands is encoded. This file is defined with the parameter CMSYNIN.
CPOBJIN Specifies the code page in which the batch input file for data is encoded. This file is defined with the parameter CMOBJIN.
CPPRINT Specifies the code page in which the batch output file shall be encoded. This file is defined with the parameter CMPRINT.

Encoding for CMSYNIN and CMOBJIN:

Encoding for CMPRINT:

If the encoding/decoding fails (for instance if a character is written to CMPRINT that is not contained in the code page used to encode the file), the batch job terminates with a startup error 42 (batch mode driver error) that specifies the file on which the encoding/decoding error occurred.

Note that it is possible in particular to specify UTF-8 as code page in each of these parameters. This allows for reading and writing Unicode data encoded in UTF-8.

Top of page

Sample Session for Batch Mode

This example demonstrates how to start Natural in batch mode. A simple Natural program is executed and data items are taken from the batch input file. After the items are processed with the INPUT statement, a DISPLAY statement follows, which writes the data to the batch output file. Then, Natural terminates.

This example uses the program RECCONT which is stored in the library SYSEXBAT.

Note:
See the text A-README in the library SYSEXBAT for information on the objects that are stored in this library.

The sample session is invoked with the following call:

natnn BATCHMODE CMSYNIN=cmd.txt CMOBJIN=data.txt CMPRINT=out.txt NATLOG=ALL

Note:
This call assumes that all files can be found in the current directory and that the output is written to this directory. If the files are located in different directories or if the output is to be written to a different directory, you have to specify the path.

The parameters in the above call are described below:

BATCHMODE

The parameter BATCHMODE enables batch mode and sets the value of the system variable *DEVICE to "BATCH".

CMSYNIN=cmd.txt

The batch input file cmd.txt is a text file which is stored in your file system. The content of this file is shown below. It contains Natural system commands for logging on to the library SYSEXBAT, executing the Natural program RECCONT, and terminating the Natural session.

LOGON SYSEXBAT
EXECUTE RECCONT
FIN

The Natural program RECCONT has the following content:

DEFINE DATA
LOCAL
  1 #firstname   (A10)
  1 #lastname    (A10)
END-DEFINE
INPUT (IP=OFF AD=M) #firstname #lastname
DISPLAY #firstname #lastname
END
CMOBJIN=data.txt

The INPUT statement in the program RECCONT uses the data which is defined in the batch input file data.txt. This is a text file which is stored in your file system. The content of this file is shown below.

Ben %
Smith

Note:
The character "%" indicates that the information continues in the next line.

CMPRINT=out.txt

The DISPLAY statement in the program RECCONT writes the data to the batch output file out.txt which is created in your file system. The content of this file is shown below:

NEXT LOGON SYSEXBAT
Logon accepted to library SYSEXBAT.
NEXT EXECUTE RECCONT

                      
DATA Ben %
DATA Smith
Page     1                                                   25.04.05  13:39:09 

#FIRSTNAME #LASTNAME                                                            
---------- ----------                                                           

Ben        Smith                                                                
NEXT FIN
NAT9995 Natural session terminated normally.
NATLOG=ALL

When you invoke the sample session with the above call, a log file is created with contains all types of messages (which also includes the names of the batch input and outfile files). The log file is normally created in Natural's temporary directory which is defined in the local configuration file. See also the description of the NATLOG parameter.

The image below illustrates the different ways in which Natural reads input and writes output in batch mode.

Batch mode

As shown in the above graphic, you can proceed in one of the following ways:

Top of page

Batch Mode Detection

The system variable *DEVICE indicates whether Natural is running in batch mode or interactive mode.

Mode Description
Batch mode *DEVICE contains the value "BATCH". This value is set by the parameter BATCHMODE.
Interactive mode *DEVICE contains a value other than "BATCH". In most cases, it contains the value "VIDEO".

Example:

IF *DEVICE = "BATCH" THEN
   WRITE 'This is the background task'
ELSE
   WRITE 'This is the interactive session'
END-IF

Top of page

Batch Mode Restrictions

When Natural is running in batch mode, some features are not available or are disabled:

Top of page

Batch Mode Simulation

In addition to the batch mode as described above, you can also simulate batch mode. However, it is recommended to use batch mode instead of batch mode simulation. Batch mode has the following advantages over batch mode simulation:

If the input channel is redirected to a file, Natural does not read the input commands and data from the keyboard but from this file. You have to specify the data in exactly the same way as you would do on the terminal. For example, for two input fields you have to fill up the first field with trailing blanks to position to the second field. No keyword delimiter mode is supported. To use keyword delimiter mode, use batch mode instead of batch mode simulation.

If the output channel is redirected to a file, Natural writes any output that would appear on the screen to this file. Control sequences are also written to the file, which makes the file unreadable. To get a formatted output, use batch mode instead of batch mode simulation.

Use the dynamic parameter BATCH when starting Natural, to set the system variable *DEVICE to the value "BATCH". This value can be checked within a Natural program.

Example: Redirecting the Input Channel

DEFINE NATINPUT input-file-name
NATURAL BATCH

Natural then receives all input operations from this input file (an example of this input file is provided below).

Example: Redirecting the Input and Output Channel

DEFINE NATINPUT input-file-name
DEFINE NATOUTPUT output-file-name
NATURAL BATCH

If you want to keep Natural reports only and hide all other output (write output to the null device), set the profile parameter MAINPR to a valid printer number and assign an executable file to the corresponding logical printer (device) in the parameter file, then specify:

DEFINE NATINPUT input-file-name
DEFINE NATOUTPUT nla0:
NATURAL BATCH

Any Natural reports are written to the executable file, whereas any screen output is suppressed. An input file must be specified even if Natural does not expect any input at all. In this case, also the null device may be used.

Sample Input File

dlist program *
fin

The input file for batch mode simulation must contain the same keystrokes that you would make in an interactive session.

The following keystrokes are used in the above sample input file:

d Opens the Direct Command window.
list program * Executes the Natural system command which is used to list all programs.
fin Executes the Natural system command which is used to terminate the Natural session.

Top of page