Functions for Registered CPI-C Programs 

Use

You can use these functions to write a CPI-C program which, unlike "normal" CPI-C programs, is not started after the connection is established but which starts and then waits for a connection to be established.

This means that a single run of the program can accept several connections. This is particularly useful for programs which are executed very frequently, since it avoids the repeated overhead of starting up.

Features

The following SAP-specific functions are available for registered programs:

For a short description refer to the chapter SAP-Specific CPI-C Functions.

The process consists of the following steps:

  1. Registering the program

    2. The SAP_CMREGTP function registers a program with a TP name with the SAP Gateway. A socket handle is then returned.

    The TP name is the name of the program that waits for a connection setup.

  2. Accept connection

The SAP_CMACCPTP function waits for the connection to be established. You can specify a timeout period for the function.

If the function times out without establishing a connection, then it terminates with the return code CM_SAP_TIMEOUT_RETRY.

The return code CM_DEALLOCATED_NORMAL indicates that the registered program was terminated by the Gateway. Possible causes are:

If the connection is successfully established then the Conversation ID is returned, and this is used in the subsequent CPI-C communication.

After the connection has been broken, SAP_CMACCPTP() can be called again. The program does not need to be restarted each time.

If there is data at the socket handle, then you just need to call SAP_CMACCPTP(). The SELECT function can be used to check for this.

If the program is to perform other tasks without being interrupted, you can reset the registration status using the function SAP_CMUNACCPTP. The program will then not be addressed by the gateway. Calling SAP_CMACCPTP changes the status from INIT to WAITING, and makes the programm wait for a new connection setup.
  1. Terminating the program

The SAP_CMUNREGTP function deregisters the program and cancels the connection to the SAP Gateway.

You can use the function SAP_CMCANCREGTP to cause the Gateway to terminate a registered program. In contrast to the function SAP_CMUNREGTP the program to be terminated does not have to be logged on the Gateway by you (SAP_CMREGTP). Instead you can stop any program.

Both functions will only terminate programs that have the status INIT or WAITING.

CM_RETCODE return_code;
CPIC_CHAR *tpname;
CPIC_CHAR *gwhost;
CPIC_CHAR *gwserv;
PCONVERSATION_ID convid;
CPIC_INT handle;
CPIC_INT timeout;

SAP_CMREGTP(tpname,gwhost,gwserv,&handle,&return_code);
for(;;)
{
SAP_CMACCPTP(handle,timeout,convid,&return_code);
CMRCV(...);
CMSEND(...);
CMDEAL(...);
}
SAP_CMUNREGTP(handle,&return_code);

Note the contrast to "normal" CPI-C programs which are started after the connection has been established:

main (int argv, char ** argc)

CM_RETCODE return_code;

CONVERSATION_ID convid;

..
SAP_CMACCP(argv);
CMACCP(convid,&return_code);
CMRCV(...);
CMSEND(...);
CMDEAL(...);

Example program which resets the registration status:

SAP_CMREGTP(tpname, gwhost, gwserv, &handle, &return_code);
SAP_CMACCPTP(handle, timeout, convid, &return_code);

If ( return_code == CM_SAP_TIMEOUT_RETRY)
{

/* timeout, some other action not */
/* to be interrupted */

SAP_CMUNACCPTP(handle,&return_code);

…

SAP_CMACCPTP(handle, timeout, convid, &return_code);

}

…

Determining the Number of Programs Registered at the Gateway

You can use the function SAP_CMNOREGTP() to find out how often a program has been registered with a specific name at the SAP Gateway. The total number and the program status are returned:

total Number of registered programs (total of programs in INIT,WAITING und RUNNING status)

init Number of registrations in INIT status, which means, not waiting for tasks

waiting Number of registrations in WAIT status, which means, available for new tasks

running Number of registrations in RUNNING status, which means, currently working on tasks

CM_RETCODE return_code;
CPIC_CHAR *tpname;
CPIC_CHAR *gwhost;
CPIC_CHAR *gwserv;
CPIC_INT total;
CPIC_INT init;
CPIC_INT waiting;
CPIC_INT running;

SAP_CMNOREGTP(tpname,gwhost,gwserv,
&total,&init,&waiting,&running,
&return_code);

The function module GWY_GET_NO_REG_PROGRAMS provides the same functionality in the R/3 System.

Changing Statuses of Registered Programs

SAP_CMREGTP(2): INIT

SAP_CMACCPTP (call): INIT ® WAITING

SAP_CMACCPTP (rc=timeout): WAITING ® RUNNING

SAP_CMACCPTP (connection setup): WAITING ® RUNNING

SAP_CMUNACCPTP WAITING ® INIT

CMDEAL: RUNNING ® INIT

Communication with a registered program requires protocol type R.