Structure of Parameter Documentation (SAP Library - BAPI Programming Guide Reference (CA-BFA))

Structure of Parameter Documentation

Prerequisites

Parameter documentation consists of the keyblocks Description, Value Range, and Default Values. The information you enter in these keyblocks depends on the type of parameter. So you have to ascertain:

Whether the parameter you are documenting implements one of the key fields of the business object

Check in the BAPI Explorer (transaction BAPI) if the parameter to be documented is displayed as a key field in the associated business object, or actually as a parameter in the BAPI.

Whether the you are documenting is the Return parameter.

Whether the parameter you are documenting relates to a single field, a structure, or a table.

To find this out, select the appropriate tab "Import", "Export" or "Tables" in the Function Builder to display the required parameter. Double-clicking on the field Reference field/Reference structure displays the ABAP Dictionary where you can retrieve details of the structure of the parameter:

For structure-based parameters, the Reference field/Reference structure field contains the name of the structure. For example, the parameter PR_HEADER in the function module BAPI_PO_CREATE (which implements the BAPI PurchaseOrder.CreateFromData()) is based on the structure BAPIEKKOC.

For parameters based on a single field, the Reference field/Reference structure field contains the name of the structure, followed by a hyphen (-), followed by the name of the field in the structure on which the parameter is based. For example, the parameter FROM_DATE in the function module BAPI_JOBREQUIRE_GETLIST (which implements the BAPI JobRequirement.GetList()) is based on the field BAPIQUALIFIC-FROM_DATE, i.e. the field FROM_DATE in the structure BAPIQUALIFIC.

Procedure

Using Same Parameters in Several BAPIs

Using transaction SE61, you can write a general text for parameters that are used in several BAPIs at the same time.

You insert this text in the respective parameter documentation by setting an INCLUDE link. To do this, in the parameter documentation, insert the character /: on the left side in the format column and the command INCLUDE <name of general text> in the relevant lines in the SAPscript editor.

Documenting Single-Field Parameters

If the parameter only has one field, ascertain whether data element documentation exists for this field as described in Checking or Writing Data Element Documentation. If not, you have to write the data element documentation.

Check whether the data element documentation describes the parameter in sufficient detail.

Parameter documentation is then structured in the following way:

Keyblock	Contents
Description	If the data element documentation describes the parameter sufficiently, enter the following standard sentence in the keyblock: "For information on the definition of <short text>, see the corresponding data element documentation: <hyperlink to data element documentation>." If other information is relevant for this parameter, you should add it here. If the data element documentation is not appropriate, describe the business content of the parameter.
Value Range	Include any fixed values and their effect. Also say whether a check is carried out and how invalid values are handled. Generally you should not provide information on data types given in the ABAP Dictionary, as this cam be accessed in the ABAP Dictionary. Only provide information on data types if it will be useful. This keyblock should not contain Customizing information that could vary from system to system.
Default Values	Assigning parameters default values. Only describe this information for import parameters. Specify whether a value has been assigned to this field via Customizing and indicate that this makes the field read-only.

Documenting Structure/Table Parameters

If the parameter relates to a structure or table, make sure that data element documentation has been written for each field in the structure/table. This is described in Checking or Writing Data Element Documentation.

Parameter documentation is then structured as follows:

Keyblock	Contents
Description	Describe the business content of the parameter. Do not use any information provided in the data element documentation. State whether the parameter is an import, export, or import/export (table) parameter. You can find this information in the BAPI Explorer. Do not describe the fields themselves - the BAPI Explorer automatically includes the data element documentation for each field into the parameter documentation. Instead, specify: Which field must be filled so that the parameter is valid, that is the mandatory fields. The dependencies between fields. For example, if a specific field must/can be filled depending in another field being filled. Enter the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_DATAELEMENT in the relevant lines in the SAPscript editor. This automatically inserts the following standard sentence: "For more information on the individual parameter fields, see the data element documentation in the ABAP dictionary."
Value Range	Include any fixed values and their effect. Also say whether a check is carried out and how invalid values are handled. For ExtensionIn and ExtensionOut parameters: If these are combined with BAPI Table Extensions, list all available BAPI Table Extensions. Generally you should not provide information on data types given in the ABAP Dictionary, as this cam be accessed in the ABAP Dictionary. Only provide information on data types if it will be useful. This keyblock should not contain Customizing information that could vary from system to system.
Default Values	Assigning parameters default values. Only describe this information for import parameters. Specify whether a value has been assigned to this field via Customizing and indicate that this makes the field read-only.

For an example, see Parameter Documentation.

Documenting Return Parameters

Each BAPI has a Return parameter that returns messages to the application that called the BAPI. Application programmers wanting to use BAPIs must know exactly which messages can be returned by the BAPI so that they can process them in their applications.

When a BAPI is being called, it can call further function modules which can return their own messages. This is why BAPI messages must be listed in the documentation of the Return parameter as well as important or likely messages that are generated by other function modules or programming objects and then passed to the calling program via the BAPI. Ask your BAPI developer about this.

All BAPI messages are entered in table T100. It is easiest if you ask the developer responsible to give you a list of error messages in the table structure described below. It is important that you do not make any changes to the messages in table T100 without first discussing them with your developer. Such changes could affect the stability of the BAPI interface guaranteed by SAP because the changes may be semantically incompatible.

Parameter documentation is then structured as follows:

Keyblock	Contents
Description	To define the parameter, enter a standard sentence using the INCLUDE command as follows: Insert the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_TABLE in the relevant lines in the SAPscript editor. This automatically inserts the following standard sentence: "This table contains the return messages from the method call." Some BAPIs perform a database rollback when an abort message (type A) occurs in the Return parameter, revoking all activities since the last COMMIT WORK command. Document this explicitly, if this is the case.
Value Range	Specify all the return codes for your BAPI, including possible messages that may be indirectly returned to the calling application via the BAPI. Enter the return values in a table under the following columns (specify the format PE instead of AS in the format column): Type ID Number Message To group the error messages together, you should divide the table into theme areas. For example: Authorization messages Type ID Number Message E FN 019 Cannot access … E FN 020 No authorization for… Messages on data input Type ID Number Message E FN 021 Company code .....does not exist Under the heading: Other possible messages enter the most important or likely messages generated by other function modules and passed to the calling program via the BAPI. Notes for BAPIs in Release 3.1: If you are documenting a BAPI implemented in Release 3.1, the table consists of the following columns only: Type Code Message For example: Type Code Message E FN020 Company code ..... does not exist.
Default Values	Leave empty.

For an example, see Parameter Documentation.

Documenting Parameters that Implement Key Fields

Some BAPIs use the key fields of their business object. These are implemented as parameters in the function module the BAPI is based on.

Find out whether the key field of the business object has been documented. If required, create the documentation as data element documentation, as described in Checking or Writing Data Element Documentation.

In the parameter documentation itself, refer to the key field documentation as follows:

Keyblock	Contents
Description	To define the parameter, enter a standard sentence using the INCLUDE command as follows: Enter the character /: on the left side in the format column of the SAPscript editor and the command INCLUDE BAPI_KEYFIELD in the relevant lines in the SAPscript editor. This automatically inserts the following standard sentence: "This parameter implements the key field of the business object with the same name. See the documentation for the key field for more information about this parameter."
Value Range	Leave empty.
Default Values	Leave empty.

For an example, see Parameter Documentation.