User exits in delivery processing

Symptom

You are not sure which user exits exist in delivery processing and how the delivery data in the existing exits can be changed so that it conforms with the standard.

Reason and Prerequisites

This is due to inadequate documentation.

Solution

Up to now, in delivery processing, user exits have been available in the form of includes, which are no longer changed by SAP, for example when you upgrade or when you import a Support Package. The includes contain empty FORM routines that are called from different points in delivery processing. You can fill the FORM routines with your own source code to process your own data or to change delivery data.
This note provides an overview of the call and the function of the individual user exits. Note that only general recommendations for the correct implementation of the user exits can be given here and that SAP cannot assume any responsibility for the effects of the implementation. If you require support, contact an experienced consultant or SAP Consulting.
Test your own developments in user exits thoroughly before implementing them in your production system. Also check whether your own developments have incorrect effects on less obvious functions in the delivery; for example, the statistics and change documents update or the structure of the billing due list (table VKDFS), the shipment planning index (table VTRDI) and the delivery due index (table VEPVG). Even if the data of the delivery that is written to the database seems to be correct, inconsistent internal tables may cause errors in the update of the worklists mentioned.
Use only local structures for the selection result for database accesses in the user exits. The use of the global structures defined in delivery processing with TABLES may cause errors that are extensive and difficult to understand.

General information about the internal tables of delivery processing
The most important data of the delivery is managed in coupled internal tables: The internal table whose name starts with an X contains the current data, including the last changes made by the user. Generally, the table with Y as the first letter of the name contains the database status before the change. It is significant only in change mode of the delivery.
In general, the change indicator (UPDKZ) of the X or Y table states whether the record is to be inserted (UPDKZ = 'I'), updated ('U') or deleted ('D') in the database.
The following list gives an overview of the most important internal tables and structures of the delivery:

* LIKP and XLIKP are the header lines of the current delivery. In dialog processing, only the structure LIKP contains the current status up to the start of the saving process. The corresponding internal table XLIKP is reliably filled only during collective processing; in dialog processing only as of the start of the delivery saving process.
During the saving process, the indicator XLIKP-UPDKZ states for each individual table entry whether the respective header is to be inserted (UPKDZ = 'I'), changed ('U') or deleted ('D'). The change indicator is SPACE if no changes were made.

* The structure YLIKP contains the database status of the delivery header in change mode. The indicator XLIKP_UPDKZAs is filled with 'U' if the header is changed; as of Release 4.6, the table YLIKP is also filled in this case.

* The internal table XLIPS contains the current status of the delivery items. The change indicator (XLIPS-UPDKZ) states whether the item is to be inserted, changed or deleted (see above).

* Items that were deleted or changed in change mode also appear in the table YLIPS, which represents the database status of the respective items.

* The item status of the individual delivery items is stored in the internal table XVBUP. The table also contains a change indicator in accordance with the logic mentioned above; however, entries to be deleted are always removed directly from the table. Therefore, the change indicator 'D' does not occur in XVBUP.

* The original status of the item status data is stored in change mode in the table YVBUP. You can recognize items to be deleted by the change indicator YVBUP-UPDKZ = 'D'.

* As with the item statuses, the tables XVBUK and YVBUK contain the header status information. The change indicator is used in accordance with the same logic as for XVBUP and YVBUP to ensure that the change indicator 'D' does not occur in the table XVBUK either. Note that the header and item status tables may also contain the status information of the supplied preceding documents.

* The document flow for the delivery is stored in the tables XVBFA and YVBFA; the change indicator is managed as in the table XLIPS. Generally, the document flow table also contains data from the preceding documents.

* The partners are stored in the tables XVBPA and YVBPA. The change indicator is managed like the status tables (no change indicator 'D' in XVBPA).

Determinating the processing status of the delivery

It is often necessary to distinguish between the different processing statuses of the delivery because the exit is run both when creating and changing deliveries. You can use the following indicators to determine the processing status of the delivery:

* Create, change or display?
The field T180-TRTYP has the value 'H' in creation mode, the value 'V' in change mode and the value 'A' in display mode.

* Dialog or collective processing?
The indicator V50AGL-SAMMELGANG (as of Release 4.0) or KZ_SAMMELGANG (up to Release 3.1I) has the value 'X' in collective processing; the indicator SPACE is in the dialog.
Note: At times, this indicator may also be set in dialog processing; for example, when creating batch split items. In this case, it should suppress the output of error messages in the dialog.

* Pick order verification or change of delivery in the dialog?
The indicator KOMMIRUECKMELDUNG is set if a delivery is changed by a pick order verification from Warehouse Management or by importing an IDoc.

* Goods movement posting active?
If goods issue posting or goods receipt posting is active, the indicator V50AGL-WARENAUSGANG is set. In the case of a cancellation, the indicator V50AGL-WARENAUSG_STORNO may be queried. However, both indicators are available only as of Release 4.0.
In Release 3.1, you can recognize active goods issue posting by the function code: The field FCODE has the value 'WABU'.

* Is the delivery deleted completely?
If a delivery document is deleted completely, the field YLIKP_UPDKZ is set to 'D'; T180-TRTYP has the value 'V' in this case.

* Is the subsequent delivery split active? (only relevant in Release 4.6)
The indicator V50AGL-MULT is set if deliveries are saved that were subsequently split. In this case, the indicator T180-TRTYP has the value 'V'. The internal tables of delivery processing may contain several deliveries (as in collective processing).

* Synchronous or asynchronous update?
The indicator V50AGL-SYNCHRON (Release 3.1I: KZ_SYNCHRON) is set if the delivery is to be updated synchronously. If the indicator is not set, the delivery is updated asynchronously. The update function modules must then be called with the addition IN UPDATE TASK.

Note that the query for the transaction code (SY-TCODE) in dialog processing no longer works reliably in Release 4.6 since you can switch between display mode and change mode within delivery processing. The field SY-TCODE is also no longer filled with the expected value if

* deliveries are generated in parallel processing within transaction VL10

* collective processing is executed for generating deliveries as a background job.

You can find more information about this topic in Note 209846.

FORM routine USEREXIT_REFRESH_DOCUMENT (include MV50AFZ1)

Purpose
The FORM routine USEREXIT_REFRESH_DOCUMENT is used for the initialization of your own data areas before the processing of a new delivery document.

Call
The routine is called from within the standard routine BELEG_DATEN_INIT (SAPMV50A).
Basically, the data initialization is called on the following occasions:

* After deliveries have been saved in the dialog (not in the new delivery dialog, except for transaction VL01NO).

* In the dialog, before returning to the initial screen with functions 'Back' or 'Cancel' (not in the new delivery dialog).

* In the new delivery dialog, when switching between 'Display' and 'Change' and when reading a new document using the function 'Other Outbound Delivery' or 'Other Inbound Delivery'.

* As of Release 4.6: In collective processing for delivery creation before the processing of a new package for supplied preceding documents.

* Prior to Release 4.6: In collective processing for delivery creation after the processing of a package for supplied preceding documents.

* When calling the transaction in the old delivery transactions (VL01, VL02, VL03). In the new delivery dialog, the initialization is not called for performance reasons.

Data access
During the document initialization, the access to delivery data leads to undefined results.

Output of messages
The output of error messages during the document initialization is not useful.

FORM routine USEREXIT_DELETE_DOCUMENT (include MV50AFZ1)

Purpose
If a delivery is deleted, you can delete your own dependent data using this FORM routine.

Call
The FORM routine is called from the FORM routine BELEG_LOESCHEN (SAPMV50A) if the document can be deleted completely. Immediately after the FORM routine USEREXIT_DELETE_DOCUMENT is called, the document backup is called for which the logically deleted delivery is removed from the database.

Data access
You can access the delivery data that has already been deleted logically within the FORM routine:

* The structure LIKP contains the delivery header to be deleted.

* The internal table XLIPS contains the current status of the items to be deleted, including the last changes made by the user before deletion. All items have the change indicator 'D'.

* The internal table YLIPS contains the database status of all delivery items in this special case.

* The internal table for the item status XVBUP no longer contains any items of the current delivery, the database status of the item status can be determined only from the internal table YVBUP.

* An entry no longer exists for the current delivery either in the internal table for the header status of the delivery XVBUK. The current status information (database status) can be taken from the table YVBUK.

* The internal table with the partner data XVBPA is also empty. The database status of the partner data is in the internal table YVBPA.

* The internal tables of delivery processing must never be manipulated in this exit to avoid data inconsistencies.

Display of messages
The output of error messages and user dialogs is possible only with restrictions in the FORM routine USEREXIT_DELETE_DOCUMENT. Messages of the type E or W cannot be output. This causes the runtime error DYNPRO_MSG_IN_HELP as of Release 4.0.

Other notes
The deletion of the delivery can no longer be prevented at this point by returning to the dialog, since all the delivery data has already been deleted logically. If the user has to prevent the deletion of the delivery for certain reasons, the system should issue an error message of the type A.

FORM routine USEREXIT_READ_DOCUMENT (include MV50AFZ1)

Purpose
The exit is used to make your own data available for processing in the delivery.

Call
The routine is run exactly once every time the delivery document data is read in change or display mode of the delivery. Exception: The routine is not executed when reading deliveries during the subsequent delivery split and when enhancing deliveries.

Data access
You have full access to all the data of the delivery that has just been read within the exit. In principle, you can make changes in this exit to the delivery data read. Note the recommendations about changing delivery data in the description of the user exit USEREXIT_SAVE_DOCUEMENT_PREPARE.

Display of messages
There are no restrictions placed on the output of error messages and user dialogs in this exit. Note however that the exit is also run in the background:

* User interaction is not useful for the pick order verification from Warehouse Management or when importing IDocs. You recognize this processing case by the fact that the indicator KOMMIRUECKMELDUNG is set.

* For goods issue posting using the delivery monitor (transaction VL06G) or transactions VL19, VL21, and VL23, the delivery dialog may be called in batch input mode. In these cases, the output of a dialog box may cause processing to terminate because no batch input data is available for the dialog box. The batch input case is recognized by the fact that the indicator SY-BINPT is set. If a clearer distinction is required with regard to the batch input mode, the output of the function module BDC_RUNNING can be used (see Note 416150 for this).

FORM routine USEREXIT_MOVE_FIELD_TO_LIKP (include MV50AFZ1)

Purpose
The exit is used to provide your own additional fields of the header table LIKP with data.

Call
The FORM routine is run exactly once when creating a new delivery. The FORM routine USEREXIT_MOVE_FIELD_TO_LIKP is always called at the end of the routines LIKP_FUELLEN (SAPFV50K; delivery creation with predecessor reference) and LIKP_FUELLEN_OR (SAPFV50K; delivery creation without predecessor reference). In the case of deliveries with predecessor reference, the copy routine for transferring the preceding data is called once before and once after this exit.

Data access

* Within the FORM routine, you cannot access other data of the delivery yet since this data is not yet available at that time. However, when creating deliveries with order reference, you can access the data of the delivered order using the internal tables CVBAK (order header), CVBAP (order item), CVBPA (order partner) and CVBEP (order schedule lines). When importing data from these tables, make sure that the current header lines of the tables are not changed. Use local structures instead.

* If standard fields of the structure LIKP are changed, you may have to carry out determinations and checks that have already been performed again to avoid data inconsistencies. Therefore, analyze the dependencies before you change standard fields in the table LIKP in this exit.

* Data from preceding documents should be prioritized and transferred using the copy control.

* You are advised against using the exit for manipulating other delivery data, for instance for creating your own partners, since this may adversely affect the data consistency and how the collective availability check works.

Display of messages
The exit must not be used for the direct output of error messages. However, messages of the type I and E can be included in the delivery creation log using the FORM routine MESSAGE_HANDLING (main program SAPMV50A). (If this routine is run in change mode, messages are not output directly but collected in the log). Messages of the type W are not written to the log.

Other notes
Note that changing data in the structure LIKP affects the delivery split during delivery creation.

FORM routine USEREXIT_MOVE_FIELD_TO_LIPS (include MV50AFZ1)

Purpose
The routine is used to provide your own additional fields of the table LIPS with data.

Call
The routine is run exactly once for each item during the creation of delivery items. The FORM routine USEREXIT_MOVE_FIELD_TO_LIPS is always called at the end of the routines LIPS_FUELLEN (creation of items with predecessor reference) and LIPS_FUELLEN_OR (creation of items without predecessor reference and creation of additional items in the delivery such as batch split items or packaging items). When you create items with predecessor reference, the routines of the copy control are called before and after this user exit.

Data access
Within the exit, you have access to the corresponding delivery header data (structure LIKP) and partner data of the delivery (XVBPA). No status information is available for the new item yet. If, prior to the current item, other items were already delivered in the same delivery, you can access the header status of the delivery using the table XVBUK. The status of the items that were generated in the same transaction or that already existed in the delivery can be read from the table XVBUP.
When you change standard fields of the item, note that checks and determinations with reference to these fields may have already been carried out and unchecked changes to these fields may result in data inconsistencies. Therefore, analyze any possible dependencies before making any changes to standard fields.
Note that the item number for the new item is already assigned only for items without predecessor reference during the exit call.
It is not useful to change other data of the delivery in this exit. Here, you should only access other data of the delivery in read mode. Make sure that the current header lines of the internal tables are not changed. Define local structures to read data from your own internal delivery tables.
Note that when you create a batch split items, the fields for the delivery quantity (LIPS-LFIMG, LIPS-LGMNG) are not yet filled during the FORM routine run because batch split items are generated with quantity 0 and are only assigned a quantity in a second step.

Display of messages
The direct output of messages is not allowed in this exit because this can result in document inconsistencies. Instead, use the FORM routine MESSAGE_HANDLING (main program SAPMV50A), which, in change mode, transfers messages of the type E or I to the delivery processing log.
If you want to prevent the item from being created because an error occurred, you should also set the indicator XLIPS_LOESCHEN_MENGE_0 in the routine to the the value 'X'.

FORM routine USEREXIT_BATCH_DETERMINATION (include MV50AFZZ)

Purpose
You can use the routine to determine the batch, which is to be assigned to the delivery item, in accordance with your own criteria.

Call
The user exit is called during item creation within the routine LIPS_BEARBEITEN (program SAPFV50P).

Data access
Within the routine, you can access order item data that is already determined (LIPS). In addition, you can access the corresponding header data of the delivery (XLIKP, XVBPA).
In the routin,e only the batch of the delivery should be changed (field LIPS-CHARG). The current header lines of the internal tables must not be changed. Use local structures to read data from internal tables instead.

Display of messages
The exit must not be used for the direct output of error messages. However, messages of the type I and E can be included in the delivery creation log using the FORM routine MESSAGE_HANDLING (main program SAPMV50A). (If this routine is run in change mode, messages are not output directly but collected in the log). Messages of the type W are not written to the log.

FORM routine USEREXIT_SAVE_DOC_BEFORE_PREP (include MV50AFZ1)


This routine is available only after you implement Note 751000.

Purpose
This routine can be used for the final change of all delivery data. At the time of the call, the delivery is complete and consistent; only the document number has not yet been determined in the creation case and the final processing of the requirements has not yet taken place. Therefore, changes to the delivery at this time must be made with particular care because no subsequent checks can prevent possible data inconsistencies.
Since requirements processing has not yet occurred, this user exit is, in particular, suitable for changes relevant for requirements when the delivery is saved.

Call
This exit is called from the routine BELEG_SICHERN (SAPMV50A) before deliveries are saved in the dialog and during delivery creation in collective processing. The call is executed before the final determination of the requirements and before the call of the user exit USEREXIT_SAVE_DOCUMENT_PREPARE (include MV50AFZ1).

Data access
The data access corresponds to that of the FORM routine USEREXIT_SAVE_DOCUMENT_PREPARE (include MV50AFZ1).

Display of messages
With the output of messages or user dialogs, you must make sure that this exit can be run both in the dialog and in the background. In particular, during goods issue posting, messages or user dialogs must never be output because this may result in incorrect material documents.

FORM routine USEREXIT_SAVE_DOCUMENT_PREPARE (include MV50AFZ1)

Purpose
This routine is the most powerful exit in delivery processing and can be used for the final change of all delivery data. At the time of the call, the delivery is complete and consistent, only the document number has not yet been determined in the creation case. Therefore, changes to the delivery at this time must be made with particular care because no subsequent checks can prevent possible data inconsistencies.

Call
This exit is called from the routine BELEG_SICHERN (SAPMV50A) before deliveries are saved in the dialog and during delivery creation in collective processing.

Data access
Since the delivery is about to be saved, all relevant delivery data can be accessed. The current document status is in the X tables and the previous database status is in the corresponding Y tables. Note the following when accessing data:

* When you create deliveries in collective processing or when you execute the subsequent delivery split (as of Release 4.6), several deliveries may exist in the internal tables. Therefore, in general, it is not sufficient for processing to consider only the header lines LIKP or XLIKP.

* The header lines of the internal tables may be changed in this exit. Therefore standard routines, which require a previous correct positioning of the work areas, can also be called for processing.

* If you want to change item data consistently, you should note the source code example EXAMPLE 1 from the correction instruction. With this, the internal tables of the delivery including the change indicators are updated correctly.

* If you want to delete delivery items consistently, call the FORM routine XLIPS_LOESCHEN (program SAPFV50P) in the same way as the source code example EXAMPLE 3 in the correction instructions.

Note: The source code examples described in the correction instruction are only meant to illustrate the correct call of the standard FORM routines and they do not have any business significance. If implemented in a production system, check the exact conditions under which the source code can be processed usefully (for example, deleting items in the case of an active goods issue posting is not useful). Use the indicators mentioned above, which characterize the processing status of the delivery, to formulate the conditions under which the source code is to be executed.

* The requirements update is already completed when the routine is called. If you make changes relevant for requirements, the FORM routine USEREXIT_SAVE_DOC_BEFORE_PREP (include MV50AFZ1) from Note 751000 should be used.

* Note that the requirements can be updated incorrectly if you delete the entire document in this user exit. Use a user-defined check in the incompletion control if you want to delete the entire document (see Note 158807). If you cannot use the incompletion control, you should use the user exit USEREXIT_SAVE_DOC_BEFORE_PREP for the deletion.

* The header status of the documents involved has also already been determined. With regard to status updates, you may have to execute the routine XVBUK_PFLEGEN (program SAPFV50K).

Display of messages
With the output of messages or user dialogs, you must make sure that this exit can be run both in the dialog and in the background. In particular, during goods issue posting, messages or user dialogs must never be output because this may result in incorrect material documents.

FORM routine USEREXIT_SAVE_DOCUMENT (include MV50AFZ1)

Purpose
The routine is used to save your own data when saving deliveries. Delivery data cannot be changed here anymore since it has already been transferred to the update.

Call
The call occurs when the document is saved (routine BELEG_SICHERN, program SAPMV50A) immediately before the COMMIT WORK statement.

Data access
As in the routine USEREXIT_SAVE_DOCUMENT_PREPARE, you can access all the global data of the delivery. When you create the delivery, the document number of the delivery is now also known.
If your own data is to be updated, this should be done using function modules that can be updated. Depending on how the indicator V50AGL-SYNCHRON (Release 3.1I: KZ_SYNCHRON) has been set, carry out the update in synchronous or asynchronous mode:

* V50AGL-SYNCHRON = 'X': Synchronous update

* V50AGL-SYNCHRON = ' ': Asynchronous update, required to call the update function module with the addition IN UPDATE TASK.

Never use your own COMMIT WORK or ROLLBACK WORK statements.

Display of messages
The output of messages or user dialogs is generally not allowed since a COMMIT WORK is sent implicitly here. In serious cases, processing can be terminated with a message of the type 'A'.