APIs for the SPoD Utility Protocol

With the SPoD utility protocol it is possible to invoke a program on the Natural Development Server, send alphanumeric data to the server (up to a maximum of 5000 bytes) and receive alphanumeric data from the server (up to a maximum of 5000 bytes). This works similar to a Natural RPC call. The server program(s) can communicate with the client program(s), i.e. data can be exchanged with the client when the server program is still running.

Important:
The programs running on the Natural Development Server must not perform any screen I/O operations. This would result in a break down of the server connection.

Two APIs and two example programs are provided in library SYSEXNDC of Natural for Windows installed on the client side.

The corresponding APIs and example programs on the server side are provided in the library SYSEXNDV of the Natural Development Server.

The APIs can be used together with the SPoD utility protocol.

This document covers the following topics:

APIs for Natural on the Client

For the client programs the following APIs and examples are provided in library SYSEXNDC of Natural for Windows:

NDVC001N This subprogram returns the status of a connection to the remote Natural Development Server environment. It can be used to check whether it is possible to connect to a server application.
NDVC002N This subprogram provides access to a connection to the remote Natural Development Server environment. It invokes a program on the server. The library and program name are part of the data sent to the server.
NDVC001P This example explains how to design a user-defined program to call subprogram NDVC001N. It also contains a description of the parameters of subprogram NDVC001N.
NDVC002P This example explains how to design a user-defined program to call subprogram NDVC002N. It also contains a description of the parameters of subprogram NDVC002N.

APIs for Natural on the Server

On the server, the following APIs and examples are provided in the library SYSEXNDV of the Natural Development Server. The description of the parameters can be found in the text member A-README in the same library.

NDVS001N This subprogram, which must be called when a server program is started, is used for the initialization of the server environment. It sets the steplibs SYSLIB and SYSLIBS in the user steplib table and checks if the trace function is active.
NDVS002N This subprogram should be called at the end of a server program before the END or STOP instruction for cleanup reasons. It deletes the steplibs SYSLIB and SYSLIBS from the user steplib table.
NDVS003N Natural subprogram that enables you to exchange data with the client program.
NDVS004N Natural subprogram that enables you to write trace data into a Natural text member or into the Natural Development Server log file. This may be helpful during program development and for error tracing.

Note:
On the mainframe, every time a trace message has been written into a Natural text member, an END TRANSACTION is performed.

Example Application

A small example application that illustrates how to use the different APIs is provided with the Natural Development Server.

The client program is provided in the library SYSEXNDC of Natural for Windows.

The server programs are provided in the library SYSEXNDV of the Natural Development Server.

Client Program in Library SYSEXNDC

For the client side, the following program is provided:

NDVCMAIN This program checks whether the remote environment is active and enables you to invoke five different programs on the server side. To activate the program, create a customized user command as described in the section How to Execute a Program Locally in Natural Studio When a Remote Environment is Active.

Server Programs in Library SYSEXNDV

For the server side, the following example programs are provided:

NDVSPING This is an example program for the PING function. It reads the data sent by the client program and simply returns a filled buffer.
NDVSINTA This is an example program for the interaction handling. It reads the data sent by the client program, returns data to the client, and waits for an answer from the client. Depending on the data sent by the client, it continues sending data or stops processing.
NDVSEMPR This is an example program that reads the EMPLOYEES file and sends the data to the client. It is an extension of the interaction handling demonstrated in NDVSINTA.
NDVSTRCE This is an example program that enables you to switch the trace facility on or off. The above mentioned example programs all write trace data if the trace facility is activated.
NDVSWRLG This is an example program that writes a message into the Natural Development Server log file.

How to Execute a Program Locally in Natural Studio When a Remote Environment is Active

In order to communicate with a program on the Natural Development Server, a Natural program or dialog must be executed locally in Natural Studio when you are connected to a remote Natural Development Server environment (that is, when your current active library is a library on the Natural Development Server). This can be easily achieved by defining a customized user command in Natural Studio.

In order to execute NDVCMAIN, your customized user command must contain the following: 

LOGON SYSEXNDC; NDVCMAIN

A detailed description on how to create customized user commands is given in the Natural for Windows documentation under User Commands in the section Customizing Natural Studio of the Using Natural Studio documentation.