COMMUNICATION

COMMUNICATION Syntax Diagram

Variants:

1. COMMUNICATION INIT DESTINATION dest ID id.
2. COMMUNICATION ALLOCATE ID id.
3. COMMUNICATION ACCEPT ID id.
4. COMMUNICATION SEND ID id BUFFER f.
5. COMMUNICATION RECEIVE ID id
...BUFFER f
...DATAINFO d
...STATUSINFO s.
6. COMMUNICATION DEALLOCATE ID id.

The COMMUNICATION statement allows you to develop applications which perform direct program-to-program communication. The basis for this is CPI-C (Common Programming Interface - Coummunication), defined by IBM within the context of SAA standards as a standardized communications interface.

The COMMUNICATION statement provides the essential parameters for implementing simple communication. The basis for this is the CPI-C starter set which covers the following functionality:

Establishing a connection

Accepting a communication

Sending data

Receiving data

Closing a connection

The other essential part of such a communication is an ABAP/4 program containing a FORM routine which is executed when the connection has been established. This program may be in an R/3 System or an R/2 System. If the called program makes database changes, you must remember to write them to the database using a COMMIT WORK statement.

When you create applications that use communications, remember that the application programs declare their own protocol. In particular, the calling program must log onto the partner SAP system. The partner program must also control certain parameters itself (ASCII-EBCDIC ). Remote Function Call (RFC) provides a communication method in which the user does not have to worry about these problems.

External programs (e.g. a program written in C on a UNIX workstation) can also be used as partner programs. For this purpose, SAP provides a platform-specific development library. For more detailed information about communication in the SAP System, you can refer to the manual

SAP Communication: Programming

For further information about communication, refer to any of the the following:

IBM SAA
Common Programming Interface
Communication Reference
SC 26-4399

X/Open Developers' Specification CPI-C
X/Open Company Ltd.
ISBN 1 872630 02 2


... RETURNCODE rc


The partner system is specified in the dest field. You can use any name you like, but it must be entered in the connection table TXCOM and can be no more than 8 characters long. This entry in the table TXCOM determines to which physical system a connection is established using the symbolic name of the target system.

In the field id, the system assigns an eight-character ID number of type C to the connection. id has to be defined by the user. The system field SY-SUBRC contains an appropriate return code value.
All return codes can be read using their symbolic names. For this purpose, you can use the program RSCPICDF which contains these names and can be included, if required.

Note

The system automatically performs an authorization check. If the user does not have the appropriate authorization, a runtime error occurs. You can check the existence of the authorization object with the function module AUTHORITY_CHECK_CPIC.

Example

TYPES: CONVERSATION_ID(8) TYPE C, 
	 DESTINATION(8)	 TYPE C, 
	 RETURN_CODE		LIKE SY-SUBRC. 
DATA:  CONVID  TYPE CONVERSATION_ID, 
	 DEST	TYPE DESTINATION VALUE 'C00', 
	 CPIC_RC TYPE RETURN_CODE. 
INCLUDE RSCPICDF. 
 
COMMUNICATION INIT DESTINATION DEST 
				 ID		CONVID 
				 RETURNCODE  CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: /'COMMUNICATION INIT, RC = ', CPIC_RC. 
   EXIT. 
ENDIF.

Addition:

As for variant 1.

Effect

Sets up a program-to-program connection. The call must immediately follow COMMUNICATION INIT.

Example

TYPES: CONVERSATION_ID(8) TYPE C, 
	 DESTINATION(8)	 TYPE C, 
	 RETURN_CODE		LIKE SY-SUBRC. 
DATA:  CONVID  TYPE CONVERSATION_ID, 
	 DEST	TYPE DESTINATION VALUE 'C00', 
	 CPIC_RC TYPE RETURN_CODE. 
INCLUDE RSCPICDF. 
 
COMMUNICATION INIT DESTINATION DEST 
				 ID		CONVID 
				 RETURNCODE  CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: /'COMMUNICATION INIT, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION ALLOCATE ID CONVID RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: /'COMMUNICATION ALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF.

Addition:

As for variant 1.

Effect

Accepts a connection requested by the partner program. id is a field of type C which is 8 characters long and contains the ID of the accepted connection after a successful call.

Note

The system automatically performs an authorization check. If the user does not have the appropriate authorization, a runtime error occurs. You can check the existence of the authorization object with the function module AUTHORITY_CHECK_CPIC . However, since the system checks the authorization before the FORM routine that accepts the connection is called, the called ABAP/4 program cannot check the authorization beforehand.

Example

FORM CPIC_EXAMPLE. 
  TYPES: CONVERSATION_ID(8) TYPE C, 
		 RETURN_CODE		LIKE SY-SUBRC. 
  DATA:  CONVID  TYPE CONVERSATION_ID, 
		 CPIC_RC TYPE RETURN_CODE. 
  INCLUDE RSCPICDF. 
  COMMUNICATION ACCEPT ID CONVID 
					 RETURNCODE  CPIC_RC. 
  IF CPIC_RC NE CM_OK. 
	 EXIT. 
  ENDIF. 
ENDFORM.


1. ... RETURNCODE rc
2. ... LENGTH len

Effect

Sends data to the partner program. The data is stored in the field f which follows the key word parameter BUFFER. It is sent in the full length of the field f. If the partner program is part of a system which has a different character set, you must perform an appropriate conversion yourself. To do this, use the TRANSLATE statement.

Effect

Sends the contents of the field f to the partner program in the specified length.

Example

TYPES: CONVERSATION_ID(8) TYPE C, 
	 DESTINATION(8)	 TYPE C, 
	 RETURN_CODE		LIKE SY-SUBRC. 
DATA:  CONVID  TYPE CONVERSATION_ID, 
	 DEST	TYPE DESTINATION VALUE 'C00', 
	 CPIC_RC TYPE RETURN_CODE. 
INCLUDE RSCPICDF. 
 
COMMUNICATION INIT DESTINATION DEST 
				 ID		CONVID 
				 RETURNCODE  CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: /'COMMUNICATION INIT, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION ALLOCATE ID CONVID 
					 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: /'COMMUNICATION ALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
RECORD = 'The quick brown fox jumps over the lazy dog'. 
COMMUNICATION SEND ID	 CONVID 
				 BUFFER RECORD 
				 LENGTH LENG 
				 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION SEND, RC = ', CPIC_RC. 
   EXIT. 
ENDIF.

Since the length is specified explicitly in this example, only the part 'The quick brown fox ' is transferred from the contents of the field RECORD.

Variant 5

COMMUNICATION RECEIVE ID id ...BUFFER f ...DATAINFO d ...STATUSINFO s.

1. ... RETURNCODE rc
2. ... LENGTH leng
3. ... RECEIVED m
4. ... HOLD

Effect

Receives data in the field f. If no length is explicitly defined, the amount of data accepted depends on the length of the field. The fields d and s contain information about the receive process. You can address the contents of these using symbolic names in the include program RSCPICDF. The field d indicates whether the data was received in its entirety. The status field s informs the RECEIVE user of the status of the program. Here, it is important to know whether the program is in receive status or send status. It is, for example, not possible to send data if the program is in receive status.
For more detailed information about these protocol questions, refer to the manuals listed above.

Effect

After the call, m contains the number of bytes received by the partner program.

Effect

Normally, data is received asynchronously, i.e. the system performs a rollout. However, this may not be desirable if, for example, the data is received in a SELECT loop, the database cursor is lost due to the rollout and the loop is terminated. To prevent a rollout, you can use the addition HOLD. Then, the SAP process waits until the data has been received and is thus available for use by other users.

Note

The fields d, s and m which contain information about the outcome of the call must be of type X with length 4.

Example

FORM CPIC_EXAMPLE. 
  TYPES: CONVERSATION_ID(8) TYPE C, 
		 RETURN_CODE		LIKE SY-SUBRC, 
		 C_INFO(4)		TYPE X. 
  DATA:  CONVID  TYPE CONVERSATION_ID, 
		 CPIC_RC TYPE RETURN_CODE, 
		 RECORD(80) TYPE C, 
		 DINFO	TYPE C_INFO, 
		 SINFO	TYPE C_INFO. 
  INCLUDE RSCPICDF. 
 
  COMMUNICATION ACCEPT ID CONVID 
					 RETURNCODE  CPIC_RC. 
  IF CPIC_RC NE CM_OK. 
	 EXIT. 
  ENDIF. 
 
  COMMUNICATION RECEIVE ID		 CONVID 
						BUFFER	 RECORD 
						STATUSINFO SINFO 
						DATAINFO   DINFO 
						RETURNCODE CPIC_RC. 
  IF CPIC_RC NE CM_OK. 
	 EXIT. 
  ENDIF. 
ENDFORM.


As for variant 1

Example

TYPES: CONVERSATION_ID(8) TYPE C, 
	 DESTINATION(8)	 TYPE C, 
	 RETURN_CODE		LIKE SY-SUBRC, 
	 C_INFO(4)		TYPE X. 
DATA:  CONVID  TYPE CONVERSATION_ID, 
	 CPIC_RC TYPE RETURN_CODE, 
	 DEST	TYPE DESTINATION VALUE 'C00'. 
 
DATA:  RECORD(80) TYPE C, 
	 LENG	 TYPE I VALUE 20. 
 
INCLUDE RSCPICDF. 
 
COMMUNICATION INIT DESTINATION DEST 
				 ID		CONVID 
				 RETURNCODE  CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION INIT, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION ALLOCATE ID CONVID 
					 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION ALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
RECORD = 'The quick brown fox jumps over the lazy dog'. 
COMMUNICATION SEND ID	 CONVID 
				 BUFFER RECORD 
				 LENGTH LENG 
				 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION SEND, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION DEALLOCATE ID CONVID 
						 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION DEALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 

Note

The above examples illustrate the basic functionality of the key words. However, the example program can only have an external system as partner. If the partner is an SAP System, the calling program must first logon to the SAP System and receive an acknowledgement. Only then can you begin to transmit the actual data. When logging on to an R/2 System and an R/3 System, the logon data must be converted to EBCDIC. All user data should be converted according to the partner system. This is in the concluding example of an R/3 - R/2 connection.

Example

PROGRAM ZCPICTST. 
TYPES: CONVERSATION_ID(8) TYPE C, 
	 DESTINATION(8)	 TYPE C, 
	 RETURN_CODE		LIKE SY-SUBRC, 
	 C_INFO(4)		TYPE X. 
 
DATA:  BEGIN OF CONNECT_STRING, 
		 REQID(4) VALUE 'CONN', 
		 TYPE(4)  VALUE 'CPIC', 
		 MODE(4)  VALUE '1   ', 
		 MANDT(3) VALUE '000', 
		 NAME(12) VALUE 'CPICUSER', 
		 PASSW(8) VALUE 'CPIC', 
		 LANGU(1) VALUE 'D', 
		 KORRV(1), 
		 REPORT(8) VALUE 'ZCPICTST', 
		 FORM(30)  VALUE 'CPIC_EXAMPLE', 
	 END OF CONNECT_STRING. 
 
DATA:  CONVID   TYPE CONVERSATION_ID, 
	 DEST	 TYPE DESTINATION VALUE 'R2-SYST', 
	 CPIC_RC  TYPE RETURN_CODE, 
	 DINFO	TYPE C_INFO, 
	 SINFO	TYPE C_INFO. 
 
DATA:  RECORD(80) TYPE C, 
	 LENG	 TYPE I VALUE 20. 
INCLUDE RSCPICDF. 
 
COMMUNICATION INIT DESTINATION DEST 
				 ID		CONVID 
				 RETURNCODE  CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION INIT, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION ALLOCATE ID CONVID 
					 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION ALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
 
* Convert logon data to EBCDIC 
TRANSLATE CONNECT_STRING TO CODE PAGE '0100'. 
COMMUNICATION SEND ID CONVID BUFFER CONNECT_STRING. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION ALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
* Receive acknowledgement of logon 
COMMUNICATION RECEIVE ID	CONVID 
				 BUFFER	 RECORD 
				 DATAINFO   DINFO 
				 STATUSINFO SINFO 
				 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION RECEIVE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
* Convert acknowledgement to ASCII 
TRANSLATE RECORD FROM CODE PAGE '0100'. 
 
* Now begin user-specific data exchange 
RECORD = 'The quick brown fox jumps over the lazy dog'. 
 
* Depending on the partner system, convert to another 
* character set 
TRANSLATE RECORD TO CODE PAGE '0100'. 
 
COMMUNICATION SEND ID	 CONVID 
				 BUFFER RECORD 
				 LENGTH LENG 
				 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION SEND, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
COMMUNICATION DEALLOCATE ID CONVID 
						 RETURNCODE CPIC_RC. 
IF CPIC_RC NE CM_OK. 
   WRITE: / 'COMMUNICATION DEALLOCATE, RC = ', CPIC_RC. 
   EXIT. 
ENDIF. 
 
PROGRAM ZCPICTST. 
INCLUDE RSCPICDF. 
* The receiving procedure in the relevant partner program follows 
FORM CPIC_EXAMPLE. 
  TYPES: CONVERSATION_ID(8) TYPE C, 
		 RETURN_CODE		LIKE SY-SUBRC, 
		 C_INFO(4)		TYPE X. 
  DATA:  CONVID  TYPE CONVERSATION_ID, 
		 CPIC_RC TYPE RETURN_CODE, 
		 RECORD(80) TYPE C, 
		 DINFO	TYPE C_INFO, 
		 SINFO	TYPE C_INFO. 
 
  COMMUNICATION ACCEPT ID CONVID 
					 RETURNCODE  CPIC_RC. 
  IF CPIC_RC NE CM_OK. 
	 EXIT. 
  ENDIF. 
  COMMUNICATION RECEIVE ID		 CONVID 
						BUFFER	 RECORD 
						STATUSINFO SINFO 
						DATAINFO   DINFO 
						RETURNCODE CPIC_RC. 
  IF CPIC_RC NE CM_OK AND CPIC_RC NE CM_DEALLOCATED_NORMAL. 
	 EXIT. 
  ENDIF. 
ENDFORM.