From R/2 to an External Program (registered progra (SAP Library - SAP Communication: CPI-C Programming (BC-CST-GW))

From R/2 to an External Program (registered program)

Purpose

An ABAP program in an R/2 System starts an ABAP program in an R/3 System or an non-SAP program, and exchanges data with this program.

You can start the target program from the R/2 host via an SAP communications program.

Communication is possible with the following external target programs:

ANSI-C programs on UNIX platforms by RFC or CPI-C call
Visual Basic programs on Windows and WindowsNT platforms by RFC

Prerequisites

With this constellation, you must note the following guidelines:

Using the RFC interface:

The side info tables XCOM and RFCD must be configured.

The destination of the function call must match the corresponding entry in XCOM and RFCD.

The called function must exist as a function module in the ABAP function library and have the "remote" ID.
A C target program must have the following structure:

:
#include "saprfc.h"
:
main(int argc,char **argv)
{
:
Rfc_Handle handle;
handle=RfcAccept(argv)
:
}

To link the C program, use the RFC library librfc.a.

A Visual Basic target program must be structured as follows:

:
Sub Main()
gCommand$ = Command$
:
hRfc = RfcAcceptExt(gCommand$)
:
End Sub

To link the Visual Basic program, use the librfc.lib (Windows) or ntlibrfc.lib libraries.

The following DLLs are used:

librfc.dll
librfc2.dll
nidll.dll (for Windows only)

For more details on the RFC interface, refer to the documentation Remote Communications.

Using the CPI-C interface

The SAP Gateway must be in use.
The target program must have exactly the same structure as described in the previous section.
A C target program must have the following structure:

Non-registered program	Registered Program
. . < poss. host type define, see Define Variables for Host Types > . . #define SOCK 1 #include "cpic.h" . . main(int argc,char **argv) { . . SAP_CMACCP(argv); . . CMACCP(..); . . }	. . <poss. host type define > : . #define SOCK 1 #include "cpic.h" . . main(int argc,char **argv) { SAP_CMREGTP(argv); . . SAP_CMACCPTP(argv); . . CMACCP(..); . . }

To link the C program, use the function library cpictlib.o.

The function SAP_CMACCP is used to pass the parameters needed to establish the connection to the CPI-C interface.

If an error occurs, SAP_CMACCP gives a return code not equal to CM_OK. After calling SAP_CMACCP, you can use CPI-C programming as usual.

The pointer passed when SAP_CMACCP is called cannot point to data in the stack.

This is because the pointer is also used in the subsequent CPI-C functions.

The communications program must be known to the SNA software.
The User ID and the work directory of the program started are manufacturer-specific:

IBM:	The program runs under the user ID specified in the SNA definition, in the home directory of this user ID.
HP:	The program runs under the user ID sna (ID, under which the SNA kernel runs), in the directory containing the program.

Special Features under BS2000

The tasks SAPGWHO (program gwhost) are started by the R/2 System at initialization. These tasks build the connection to an SAP Gateway under UNIX (not under BS2000).

IMS:

If you log on to an IMS security system, the session must not be closed. For this reason, the environment variable SAP_KEEP_SESSION was introduced.

For SAP_KEEP_SESSION=1, the session is retained despite the statement COMMUNICATION DEALLOCATE.

Process flow

The communication process depends on the host you are using:

R/2 System on MVS/VSE Host
R/2 System on BS2000 Host

R/2 System on MVS/VSE Host

The SAP communications program and the SAP Gateway must be on a UNIX host known in the SNA network. The target program, on the other hand, can be on a UNIX host not in the SNA network.

The process consists of the following steps:

The calling ABAP program reads the TP name in the XCOM table and starts the SAP communications program gwhost (for CICS) or gwims (for IMS) under this name on a host known in the SNA network.
The communications program sets up a Conversation with the SAP Gateway.
The SAP Gateway starts the actual target program. The host, on which it is located, does not have to be known in the SNA network.

The communications program simply passes on the data during the CPI-C dialog.

Side info files must be configured on the UNIX host known in the SNA network and on the Gateway host.

For details on the configuration of side info files, refer to the following topic in the documentation BC SAP Communication: Configuration:

Side Information in R/2 on the MVS/VSE Host: XCOM

Parameters on SNA Subsystem Platform with R/2

R/2 System on BS2000 Host

In BS2000 the SAPGWHO jobs (program gwhost) perform the functions of the communications program when connection is set up by the R/2 System.

The process consists of the following steps:

The calling ABAP program reads the TP name in table XCOM and starts the SAPGWHO jobs.
The communications program sets up a Conversation with a SAP Gateway on the UNIX host.
The SAP Gateway starts the actual target program.

Side info files must be configured on the UNIX host and on the BS2000 host.

For details on the configuration of side info files, refer to the following topic in the documentation BC SAP Communication: Configuration: under the topic:

Connection Setup by the R/2 System.