Version 4.2.6 for Mainframes
 —  TP Monitor Interfaces  —

Natural under IMS TM - Special Functions

This document describes the use of special functions available with the Natural IMS Interface.

The following topics are covered:


Prerequisites

Some of these functions require the Natural Authorized Services Manager (ASM).

Top of page

Accounting

The accounting function is only available in dialog-oriented environments. It is activated by setting the environment table parameter ACTACTV to YES.

With each terminal I/O, information about the specific Natural session is written to the IMS log or to SMF, depending on the setting of the Natural IMS parameter ACTLOG.

The following information about each Natural user session is stored with each terminal I/O:

The information is mapped by the DSECT NIMACTR. There are two areas for storing the DBID and FNR of the Natural system files used. In the first area, one byte is used for each DBID and FNR; this is supported for compatibility reasons. In the second area, a fullword is used for each DBID and FNR to support Adabas Version 6. The accounting record is prefixed with a length and version field.

Before the accounting record is written to the IMS TM log, respectively to SMF, the user exit NIIXACCT is called. You can use this user exit to tailor the accounting record to your requirements. You may also append information to the accounting record. In this case, you must set the length field to the new length.

Since the accounting record is built in the command buffer, the total length must not exceed the value specified with the Natural IMS parameter CMBSIZE minus 17 bytes. The maximum length allowed is passed as parameter.

If NIIXACCT returns with a non-zero value in register 15, no accounting record is written.

Top of page

Monitoring

The monitoring function is only available in dialog-oriented environments. It is activated by setting the environment table parameter MONACTV to YES and uses the SIP function of the Authorized Services Manager. The Natural subsystem must be the same as the one used by the Natural session to be monitored.

You can follow the ongoing activity of all Natural sessions which use the same Natural subsystem by using the Monitoring (M) function of the SYSTP utility. For more information on this utility, see SYSTP in the Natural Utilities documentation. The SYSTP session must also use the same Natural subsystem.

Top of page

Broadcasting

The broadcasting function is only available in dialog-oriented environments. It is activated by setting the environment table parameter BROACTV to YES and uses the SIP function of the Authorized Services Manager.

Once broadcasting is active, it is possible to send broadcast messages to targeted users of a given Natural subsystem. Such users can be:

When a session comes to a terminal output, a check is made to see whether the session has to receive a message or not. If not, the normal Natural output is sent. If yes, the message is sent instead of the normal output and, when pressing ENTER, the Natural nucleus is instructed to re-send the last screen. In this way, you first see the message and afterwards receive the normal Natural output screen.

If more than one broadcast message is available, the messages are displayed one after the other until the last message has been shown. Afterwards, the normal Natural output screen is displayed.

A broadcast message will be displayed only if its expiration time specified in   the message creation procedure has not been exceeded.

When a broadcast message is sent, you must press RESET before you can press ENTER again. All possible attention IDs have the same effect as pressing ENTER.

The utility SYSTP can be used to create broadcast messages and to display the contents of all active messages together with the LTERM/IMSID of the sender. The text of a message is limited to 72 bytes.

Messages to be broadcast are saved in a pool maintained by the SIP server. They remain there until you delete them using the SYSTP utility or until you shut down the Authorized Services Manager.

Warning:
When a broadcast message is deleted or created, all expired messages are deleted as well.

Top of page

Multi-Session Feature

The following topics are covered below:

Functionality of the Multi-Session Feature

The multi-session feature is only available in dialog-oriented environments. It is activated by setting the Natural IMS parameter MSACTV to YES and allows to run up to nine simultaneous Natural sessions on the same logical terminal.

Creating and resuming Natural sessions is controlled using PF keys. The Natural IMS parameters MSCRKEY and MSRSKEY define the create and resume keys.

Note:
The Natural IMS Interface Version 2.2 mode is still supported for compatibility reasons, but is no longer documented. The Version 2.2 mode is activated by setting the Natural IMS parameter MSCMPTB to YES.

Session ID

The session ID is the internally used unique identification of a session. It has the form XXXXXXxY, where XXXXXXx is the prefix and Y is the session number in the form of a numeric digit in the range of 1 to 9.

The session prefix is built by compressing the logical terminal name into a 6-byte binary number XXXXXX and by setting x to binary zero.

If the compression algorithm is not suitable for the LTERM names used (error 3635 is issued in this case), the user exit NIIXMSSP must be used in order to build a unique 7-byte prefix of the session ID.

Multi-Session Database

The multi-session database is a HDAM root-only database which contains the Natural-reserved area of the SPA for each suspended session.

The model DBD for the description of the multi-session database is delivered in the source module NIIMSDBD and must be defined to IMS TM.

The DBD name must be specified in the Natural IMS parameter module using the parameter MSDBD. The PCB number must be specified in the transaction code table using the parameter MSPCB of macro NIMTRNTG.

Top of page

Server Environment

The server environment allows 3GL applications to execute Natural programs using a call interface. It is available in all supported IMS TM environments and consists of the Natural IMS driver NIISRVD of the server call interface NIIBOOTS and of the service API NIIPCOM.

NIISRVD and NIIBOOTS are delivered as source modules and must be assembled and link-edited on your site. For details, see Installing the Natural IMS Interface in the Natural Installation documentation.

The server environment allows you to start a Natural session by calling NIIBOOTS from any 3GL program. After the Natural session has been started, it returns to the calling 3GL program and waits for further input. The input would normally be expected from CMSYNIN, which means that the 3GL program has to simulate Natural's primary input dataset.

It is strongly recommended to always put the server Natural on the NEXT line. This allows the next call to NIIBOOTS to either execute a Natural command or a Natural program. Otherwise, the next call to NIIBOOTS would be treated as input for a Natural program which had been started by a previous call to NIIBOOTS.

Similarly as with the message-oriented interface, all output normally written to CMPRINT is sent to the IMS TM destination specified with the Natural profile parameter SENDER. For details about special destinations used by the Natural IMS interface, refer to Sender Destination in the section Natural under IMS TM - Environments.

Warning:
In an MPP Environment, the same server Natural will be used by all transactions scheduled in this region by default. If you want to use multiple server Naturals in the same MPP region, you must generate multiple server call interfaces. Each server call interface must be generated with a unique name specified with the NIMBOOT parameter SERVERN and must be linked under a unique name. It is recommended to name the load module with the name specified with SERVERN.

Call Interface NIIBOOTS

NIIBOOTS is the default name as used in the documentation and in the delivered sample programs. This default name can be changed during installation.

NIIBOOTS requires the following parameters:

In the command area, the following may be passed:

The startup parameters are passed in two contiguous 80-byte areas. The first area contains the name of the environment table and the name of the transaction code to be used as follows:

ENV-TAB=environment-table-name
TRNCODE=transaction-code-name

The transaction code is only honored if TRNCODE=YES is specified on the NIMDRIV macro. For details about the usage of the transaction code, refer to the NIMBOOT macro in the section Natural under IMS TM - Environments).

The second area contains the dynamic Natural parameters with which the Natural session is to be started.

The reply area is the area in which a reply is to be entered from the executed Natural program using the service API NIIPCOM.

Each time it is invoked, NIIBOOTS checks whether the server Natural has been initialized.

The NIIBOOTS-specific commands STAT and REFR do the following:

ON ERROR Routine Recommended

It is highly recommended to use an ON ERROR routine in the executed Natural programs in order to give back to the calling 3GL program some information in the reply area using NIIPCOM.

Return Codes

NIIBOOTS passes the return code provided by Natural on the termination of Natural.

Sample Programs

To illustrate usage of NIIBOOTS and NIIPCOM, the sample programs NIPBOOTS and NIPPCOM are provided. NIPBOOTS plays the role of the calling 3GL program, NIPPCOM is a sample Natural program executed in the server environment and writes the string NIISRVR into the reply area. The ON ERROR routine places the Natural error number in the reply area.

With the sample programs, you can go through the following scenario:

  1. Pass the command STAT. The string COLD is returned to the reply area.

  2. Pass the command: STACK=(LOGON SYSEXTP),SENDER=S0201, where S0201 is the LTERM name of the assigned printer device in the server Natural. Natural will be initialized and will be ready to receive a Natural command in library SYSEXTP. The successful logon message is issued on the assigned printer. Nothing is returned in the reply area.

  3. Pass the command STAT. The string WARM is returned to the reply area.

  4. Pass the command NIPPCOM. Program NIPPCOM is executed and the string NIPSRVR is returned to the reply area. Natural is ready to accept the next command in library SYSEXTP.

  5. Pass the command: REFR STACK=(LOGON SYSEXTP;NIPPCOM),SENDER=S0201

    Natural is reinitialized and program NIPPCOM in library SYSEXTP is executed. The reply area contains the string NIPSRVR.

  6. Pass the command FIN. Natural is terminated and no information is passed to the reply area. The return code will contain the return code of the Natural termination. The Natural termination message is issued on the assigned printer device.

  7. Pass the command STAT. The string COLD is returned to the reply area.

Top of page