Programming Cancel() BAPIs

Use

The Cancel() BAPI cancels one instance of a business object.

Unlike the BAPI Delete(), which deletes an object instance from the database, with the BAPI Cancel():

  • The canceled instance of the business object is not deleted
  • An additional instance is created with which the instance of the business object is deleted.

The Cancel() BAPI is used to cancel business processes such as goods movements or invoice receipts.

The Cancel() BAPI is an instance method.

Features

BAPI Interface

Import Parameters

You should keep the following points in mind when defining the import parameters:

  • The import parameters in the function module of the Cancel() BAPI must contain the key fields of the corresponding business object type. The names of the parameters must be identical to the names of the object keys in the BOR and must have the same data elements.

For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.

  • The data of the instance to be created comes from the data of the business object instance to be canceled. As such, it must no longer be explicitly transferred too.
  • You can also create further parameters to specify information relevant for the actual cancellation process, for example, the name of the user performing the cancellation.
  • The BAPI must also have a TestRun parameter that enables it to execute test runs. If this parameter is filled with the value "X", the BAPI executes normally, but does not write the results to the update task. In this way, after the BAPI BapiService.TransactionCommit executes, all results, such as the application log, for example, can be evaluated, but the BAPI has not modified the database.

For more information, see Test Run Parameters.

  • If customers are to be enabled to enhance the import parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionIn. For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Cancel() BAPI, see Customer Enhancements to BAPIs.

Export Parameters

You should keep the following points in mind when defining the export parameters:

  • If customers are to be allowed to extend the export parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionOut.
    For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Cancel() BAPI, see
    Customer Enhancements to BAPIs.
  • The key(s) of the cancellation instance created must be returned in further export parameters.
  • To report messages from the method call back to the calling program, you should create the parameter Return. To ensure the results of a Cancel() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:
    • If the Cancel() BAPI executes successfully, in other words, a cancellation instance is created, the following standardized T100 message must be passed in the Return parameter:

You should keep the following points in mind:

      • The field MESSAGE_V1 contains the external name of the business object type, such as SalesOrder.
      • The key under which the canceled object was accessed is returned in the field MESSAGE_V2. This is the external key when external number assignment is used, or the internal key when internal number assignment is used. If the object has several key fields, the values of these key fields must be concatenated in MESSAGE_V2. The sequence in which the key fields are defined in the BOR must be adhered to for the concatenation. Moreover, the maximum length must be used for each key field. This may require the use of padding.

If the complete key exceeds the maximum capacity of MESSAGE_V2 (that is, 50 characters), it is divided up between the fields MESSAGE_V2 and MESSAGE_V3. The first 50 characters are stored in MESSAGE_V2 and the remaining characters in MESSAGE_V3.

      • The key created for the cancellation instance is returned in MESSAGE_V4. This is the external key when external number assignment is used, or the internal key when internal number assignment is used. If the key also consists of several fields, these must likewise be concatenated.
    • If an error occurs during the execution of the Cancel() BAPI, in addition to the application-specific error messages the following standardized T100 message must be passed in the Return parameter:

Apart from the fact that the field MESSAGE_V4 is not filled, the meaning of the other fields is the same as for successful execution.

    • In addition to the standardized message, further messages can be written in the Return parameter. It is of particular importance when errors occur that messages describing the errors in detail are returned. You should, therefore, use all of the fields of the structure BAPIRET2. You should, in particular, fill the fields Parameter, Row and Field.

For more information about this parameter, see Return Parameters (Error Handling).

See also:

Example of a Cancel() BAPI