Natural under IMS TM - Service Programs

#### Search Results

Search

# Natural under IMS TM - Service Programs

This document describes the service programs of the Natural IMS TM Interface.

The following topics are covered:

- Introduction to the Natural IMS TM Interface Service Programs

- Description of the Natural IMS TM Interface Service Programs

- NIIBRCST - Send Passed Message to Terminal

- NIICMD - Pass IMS TM Command to IMS TM

- NIIDEFT - Prepare Deferred Switch to Natural Transaction Code

- NIIDEFTX - Prepare Deferred Switch to Non-Natural Transaction Code

- NIIDIRT - Prepare Direct Switch to Natural Transaction Code

- NIIDIRTX - Prepare Direct Switch to Transaction Code

- NIIEMOD - Modify Setting of Module Output Descriptor

- NIIGCMD - Retrieve Next Reply Segment of Previous IMS TM Command

- NIIGMSG - Retrieve First Segment Next Message

- NIIGSEG - Retrieve Next Segment of Input Message

- NIIGSPA - Retrieve Data from SPA Beginning

- NIIIMSIN - Retrieve IMS TM Environment Info

- NIIISRTF - Create Multi-Segment Messages

- NIIISRTM - Insert Message Segment into Message Queue

- NIIPCBAD - Return PSB Name and PCB Address

- NIIPCOM - Move Data to Reply Area

- NIIPMSG - Send Message

- NIIPSBAD - Return PSB Address

- NIIPSPA - Replace Data in SPA

- NIIPURG - Issue PURG Call

- NIIRETRM - Move Data into Message Area

- NIISASD - Modify SENDER and OUTDEST Settings

- NIIU3962 - Terminate Session

## Introduction to the Natural IMS TM Interface Service Programs

### Purpose of Natural IMS TM Interface Service Programs

Service programs are Natural subprograms which provide Natural under IMS TM with additional functionality. You can call them from within a Natural program using a standard `CALLNAT` statement.

### Location of Service Programs

The service programs are provided in the library `SYSEXTP` and you must copy them to the `SYSTEM` or steplib library. Sample Natural programs to invoke the service programs are also provided in the library `SYSEXTP`.

### Common Return Codes

The last parameter in each service program is the return code whose format is (I4).

The following return code values are common for all service programs:

0 | OK
-1 | Non-supported function. This is an internal error, please contact Software AG support.

For specific return code values, refer to the individual service program descriptions below.

### Error Handling

If an error occurs, either a Natural error message is issued or the session is terminated with a Natural IMS TM error message; see Natural under IMS TM Error Messages in the Natural Messages and Codes documentation.

## Description of the Natural IMS TM Interface Service Programs

The following service programs are described below:

`NIIBRCST` | `NIICMD` | `NIIDEFT` | `NIIDEFTX` | `NIIDIRT` | `NIIDIRTX` | `NIIEMOD` | `NIIGCMD` | `NIIGMSG` | `NIIGSEG` | `NIIGSPA` | `NIIIMSIN` | `NIIISRTF` | `NIIISRTM` | `NIIPCBAD` | `NIIPCOM` | `NIIPMSG` | `NIIPSBAD` | `NIIPSPA` | `NIIPURG` | `NIIRETRM` | `NIISASD` | `NIIU3962`

## NIIBRCST - Send Passed Message to Terminal

Sends the passed message to the specified terminal using the message output descriptor specified in the `MOD_name` parameter.

The following parameters are provided:

Parameter | Format/Length
--- | ---
`Terminal_name` | (A8)
`Message` | (A1/1:V)
`Message_length` | (I4)
`MOD_name` | (A8)
`Return_code` | (I4)

Specific Return Code Values: None.

Sample Program: `NIPGMSG`

## NIICMD - Pass IMS TM Command to IMS TM

Passes the IMS TM command specified to IMS TM. If there is a reply, it is moved into the reply area provided. If the reply does not fit into the reply area, it is truncated and the return code is set to 4.

The following parameters are provided:

####

Parameter | Format/Length | Type
--- | --- | ---
`Command` | (A1/1:V) | Input
`Command_length` | (I4) | Input
`Reply_area` | (A1/1:V) | Input/Output
`Reply_area_length` | (I4) | Input
`Reply_length` | (I4) | Output
`Status_code` | (A2) | Output
`Return_code` | (I4) | Output

Specific Return Code Values: 4 (reply truncated)

Sample Program: `NIPCMD`

## NIIDEFT - Prepare Deferred Switch to Natural Transaction Code

Prepares a deferred switch to the specified Natural transaction code. With the next terminal I/O, the output is sent to the terminal and the next input from this terminal is processed by the transaction code specified in the parameter `Transaction_code`.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Transaction_code` | (A8) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPDEFT`

## NIIDEFTX - Prepare Deferred Switch to Non-Natural Transaction Code

Prepares a deferred switch to a non-Natural transaction code. With the next terminal I/O, the output is sent to the terminal using the given `MOD_name` and the next input from this terminal is processed by the transaction code specified in the parameter `Transaction code`.

If the suspend flag is set to `Y`, the Natural session will be suspended and can be resumed later. If the Natural session is resumed, it will first issue the last Natural screen.

If the suspend flag is set to `Y` you may not switch from a conversational Natural session to a non-conversational transaction code. If you try to do so, a Natural error message is issued.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Transaction_code` | (A8) | Input
`Transaction_type` | (A4) | Input Possible values: `CONV` for conversational `NONC` for non conversational
`Suspend_flag` | (A1) | Input Possible values: `Y` - the Natural session will be suspended else the Natural session will be terminated
`MOD_name` | (A8) | Input
`Message` | (A1/1:V) | Input
`Message_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPDEFTX`

## NIIDIRT - Prepare Direct Switch to Natural Transaction Code

Prepares a direct switch to a specified Natural transaction code. On the next terminal write, the `CHNG` command to the specified transaction code is issued and the Natural screen is inserted using the alternate TP PCB.

If you switch from a conversational Natural session to a non-conversational one, the conversation is terminated and a dummy message using `MOD_name` `NIIMODNC` is inserted. This message unprotects the screen temporarily, and is thus overwritten by the first screen of the non-conversational Natural session.

Parameter | Format/Length | Type
--- | --- | ---
`Transaction_code` | (A8) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPDIRT`

## NIIDIRTX - Prepare Direct Switch to Transaction Code

Prepares a direct switch to the specified transaction code. On the next terminal write, the `CHNG` call for the new transaction code is issued and the message and or the SPA are inserted using the alternate TP PCB. The transaction type defines the type of the new transaction code.

- If you switch from a conversational transaction code to a non-conversational one, the conversation is finished by issuing a dummy message using `MOD_name` `NIIMODN`, which unprotects the screen temporarily, thus it will be overwritten by the screen issued from the non conversational transaction code.

- If the suspend flag is set to `Y`, the Natural session is suspended and may be resumed at a later time. When the Natural session is resumed, the last Natural screen is issued.

- If the suspend flag is set to `Y` you may not switch from a conversational Natural to a non conversational transaction code. If you try to do so, a Natural error message will be issued.

- If message length is set to zero, no message at all is inserted. This however is only possible if you switch to a conversational transaction code.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Transaction_code` | (A8) | Input
`Transaction_type` | (A4) | Input Possible values: `CONV` for conversational transaction code `NONC` for non-conversational transaction code
`Suspend_flag` | (A1) | Input Possible values: `Y` - the Natural session will be suspended else the Natural session will be terminated
`Message` | (A1/1:V) | Input
`Message_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPDIRTX`

## NIIEMOD - Modify Setting of Module Output Descriptor

Modifies the current setting of the module output descriptor to be used in the insertion of the last message in a Natural session and sets it to the value specified in the parameter `MOD_name`.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`MOD_name` | (A8) | Input
`Return_code` | (I4) | Output

Sample Program: `NIPEMOD`

## NIIGCMD - Retrieve Next Reply Segment of Previous IMS TM Command

Retrieves the next reply segment of a previously issued IMS TM command. The length of the reply is return in the parameter reply length. If the reply does not fit into the reply area, the reply is truncated and return code 4 is issued.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Reply_area` | (A1/1:V) | Input/Output
`Reply_area_length` | (I4) | Input
`Reply_length` | (I4) | Output
`Status_code` | (A2) | Output
`Return_code` | (I4) | Output

Specific Return Code Values: 4 (reply truncated)

Sample Program: `NIPCMD`

## NIIGMSG - Retrieve First Segment Next Message

Retrieves the first segment of the next message from the message queue by issuing a GU. The message area will contain the retrieved message including the leading `LLZZ` bytes. If there are no messages in the message queue, `LLZZ` is set to zero.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Message_area` | (A1/1:V) | Output
`Message_area_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Programs: `NIPGMSG`, `NIPGSEG`

## NIIGSEG - Retrieve Next Segment of Input Message

Retrieves the next segment of the input message by issuing a GN call. The message area will contain the retrieved message including the leading `LLZZ` bytes. If there are no more message segments in the current message, `LLZZ` is set to zero.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Message_area` | (A1/1:V) | Output
`Message_area_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPGSEG`

## NIIGSPA - Retrieve Data from SPA Beginning

Retrieves data from the SPA beginning at the specified offset in the specified length.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Offset` | (I4) | Input
`Length` | (I4) | Input
`Area` | (A1/1:V) | Input/Output
`Return_code` | (I4) | Output

Specific Return Code Values: 4

The retrieved data resides entirely or partially within the part of the SPA reserved for Natural.

Sample Program: `NIPGSPA`

## NIIIMSIN - Retrieve IMS TM Environment Info

Retrieves the IMS TM environment information using the `INQY ENVIRON` call. If you specify a `Reply_area_length` smaller than 102, the reply will be truncated and you will receive return code `X'0100'` with reason code `X'000C'`.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Reply_area` | (A1/1:V) | Output
`Reply_area_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: `nnxx`

nn: The first two bytes contain the AIB return code. xx: The second two bytes contain the AIB reason code. AIB denotes "Application Interface Block" and is used when calling IMS TM through the `AIBTDLI` interface.

Sample Program: `NIPIMSIN`

## NIIISRTF - Create Multi-Segment Messages

Creates multi-segment messages. `NIIISRTF` performs the `CHNG` call for the specified destination and inserts the first message segment without performing a `PURG` call. Further message segments may be inserted using `NIIISRTM`. The message has to be terminated using `NIIPURG`. The `LLZZ` bytes are created by the service module.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Destination` | (A8) | Input
`Message` | (A1/1:V) | Input
`Message_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPISRTM`

## NIIISRTM - Insert Message Segment into Message Queue

Inserts the next message segment into the message queue without performing a `CHNG` or a `PURG` call. The `LLZZ` bytes are created by the service module.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Message` | (A1/1:V) | Input
`Message_length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPISRTM`

## NIIPCBAD - Return PSB Name and PCB Address

Returns the currently scheduled PSB name and the address of the PCB identified by the logical name. If the logical PCB name is not defined in the transaction code table, a Natural error message is issued.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`PSB_name` | (A8) | Output
`Logical_PCB_name` | (A8) | Input
`PCB_address` | (B4) | Output
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPPCBAD`

## NIIPCOM - Move Data to Reply Area

Moves the data provided in the data area into the reply area specified in the `NIIBOOTS` call at the specified offset in the specified length. `NIIPCOM` may be called from the server environment only.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Offset` | (I4) | Input
`Data_area` | (A1/1:V) | Input
`Length` | (I4) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: 4 (calling environment, not server environment)

Sample Program: `NIPPCOM`

## NIIPMSG - Send Message

Sends a message using a given `MOD_name` to the destination which is represented by the I/O PCB. The message is taken from the message area in the specified message area length. The message area must not contain the leading `LLZZ` bytes. In this way you can send MFS-formatted output messages back to the originator of the input message.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Message` | (A1/1:V) | Input
`Message_length` | (I4) | Input
`MOD_name` | (A8) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPPMSG`

## NIIPSBAD - Return PSB Address

Returns the address of the PSB which is the address of the PCB address list.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`PSB_address` | (B4) | Output
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPBOOTS`

## NIIPSPA - Replace Data in SPA

Replaces the data located in the SPA at the specified offset in the given length by the data provided in the data area.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Offset` | (I4) | Input
`Length` | (I4) | Input
`Data_area` | (A1/1:V) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

An attempt to override the header of the SPA (first 14 bytes) and/or data residing in the Natural-reserved area is refused and a Natural error message is issued.

Sample Program: `NIPPSPA`

## NIIPURG - Issue PURG Call

Issues a `PURG` call.

The following parameter is provided:

Parameter | Format/Length | Type
--- | --- | ---
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPISRTM`

## NIIRETRM - Move Data into Message Area

Moves data from the input message beginning at the specified offset in the specified length into the provided message area.

The offset is calculated from the `LLZZ` bytes.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Offset` | (I4) | Input
`Length` | (I4) | Input
`Message_area` | (A1/1:V) | Input/Output
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPRETRM`

## NIISASD - Modify SENDER and OUTDEST Settings

Modifies the current setting of the Natural profile parameters `SENDER` and `OUTDEST`.

The following parameters are provided:

Parameter | Format/Length | Type
--- | --- | ---
`Sender` | (A8) | Input
`Outdest` | (A8) | Input
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPNTRD`

## NIIU3962 - Terminate Session

Terminates the session with user abend code U3962 and produces a dump.

The following parameter is provided:

Parameter | Format/Length | Type
--- | --- | ---
`Return_code` | (I4) | Output

Specific Return Code Values: None.

Sample Program: `NIPU3962`

### On this page

- Introduction to the Natural IMS TM Interface Service Programs
- Description of the Natural IMS TM Interface Service Programs
- NIIBRCST - Send Passed Message to Terminal
- NIICMD - Pass IMS TM Command to IMS TM
- NIIDEFT - Prepare Deferred Switch to Natural Transaction Code
- NIIDEFTX - Prepare Deferred Switch to Non-Natural Transaction Code
- NIIDIRT - Prepare Direct Switch to Natural Transaction Code
- NIIDIRTX - Prepare Direct Switch to Transaction Code
- NIIEMOD - Modify Setting of Module Output Descriptor
- NIIGCMD - Retrieve Next Reply Segment of Previous IMS TM Command
- NIIGMSG - Retrieve First Segment Next Message
- NIIGSEG - Retrieve Next Segment of Input Message
- NIIGSPA - Retrieve Data from SPA Beginning
- NIIIMSIN - Retrieve IMS TM Environment Info
- NIIISRTF - Create Multi-Segment Messages
- NIIISRTM - Insert Message Segment into Message Queue
- NIIPCBAD - Return PSB Name and PCB Address
- NIIPCOM - Move Data to Reply Area
- NIIPMSG - Send Message
- NIIPSBAD - Return PSB Address
- NIIPSPA - Replace Data in SPA
- NIIPURG - Issue PURG Call
- NIIRETRM - Move Data into Message Area
- NIISASD - Modify SENDER and OUTDEST Settings
- NIIU3962 - Terminate Session