Apostial Function - SAP

®

%&�([WHQGHG�DSSOLFDWLRQVIXQFWLRQ�OLEUDU\

+(/3�%&':

%/,%�

5HOHDVH �� %

%&�([WHQGHG�DSSOLFDWLRQV�IXQFWLRQ�OLEUDU\ �6$3�$*

� -XQH��

&RS\ULJKW© Copyright 1998 SAP AG. All rights reserved.

No part of this brochure may be reproduced or transmitted in any form or for any purpose withoutthe express permission of SAP AG. The information contained herein may be changed withoutprior notice.

SAP AG further does not warrant the accuracy or completeness of the information, text, graphics,links, or other items contained within these materials. SAP AG shall not be liable for any special,indirect, incidental, or consequential damages, including without limitation, lost revenues or lostprofits, which may result from the use of these materials. The information in this documentation issubject to change without notice and does not represent a commitment on the part of SAP AG forthe future.

Some software products marketed by SAP AG and its distributors contain proprietary softwarecomponents of other software vendors.

Microsoft®, WINDOWS®, NT®, EXCEL® and SQL-Server® are registered trademarks ofMicrosoft Corporation.

IBM®, DB2®, OS/2®, DB2/6000®, Parallel Sysplex®, MVS/ESA®, RS/6000®, AIX®, S/390®,AS/400®, OS/390®, and OS/400® are registered trademarks of IBM Corporation.

OSF/Motif® is a registered trademark of Open Software Foundation.

ORACLE® is a registered trademark of ORACLE Corporation, California, USA.

INFORMIX®-OnLine IRU�6$3 is a registered trademark of Informix Software Incorporated.

UNIX® and X/Open® are registered trademarks of SCO Santa Cruz Operation.

ADABAS® is a registered trademark of Software AG.

SAP®, R/2®, R/3®, RIVA®, ABAP/4®, SAP ArchiveLink®, SAPaccess®, SAPmail®,SAPoffice®, SAP-EDI®, R/3 Retail®, SAP EarlyWatch®, SAP Business Workflow®, ALE/WEB,Team SAP, BAPI, Management Cockpit are registered or unregistered trademarks of SAPAG.

,FRQV

,FRQ 0HDQLQJ

Caution

Example

Note

�6$3�$* %&�([WHQGHG�DSSOLFDWLRQV�IXQFWLRQ�OLEUDU\

-XQH��

&RQWHQWV

%&�([WHQGHG�DSSOLFDWLRQV�IXQFWLRQ�OLEUDU\�� 6WDQGDUGL]HG�GLDORJV�� 2YHUYLHZ�� &RQFHSW�� 3URFHGXUH ��

Determine dialog type............................................................................................................... 11Create dialog text Document.................................................................................................... 12

&RQILUPDWLRQ�SURPSW�GLDORJV �� 'LDORJV�IRU�FKRRVLQJ�IURP�DPRQJ�DOWHUQDWLYHV�� 'LDORJV�IRU�GLVSOD\LQJ��LQSXWWLQJ�DQG�FKHFNLQJ�GDWD �� 'DWD�SULQW�GLDORJV �� 7H[W�GLVSOD\�GLDORJV �� 6FUROOLQJ�LQ�WDEXODU�VWUXFWXUHV �� ([WHQGHG�WDEOH�PDLQWHQDQFH �� 2YHUYLHZ�� &RQFHSW�� &UHDWH�PDLQWHQDQFH�GLDORJ�� &DOOLQJ�WKH�VWDQGDUG�PDLQWHQDQFH�GLDORJ �� &DOO�YLD�IXQFWLRQ�PRGXOH �� +LJKHVW�OHYHO�HQWU\�� 0LGGOH�OHYHO�HQWU\�� /RZHVW�OHYHO�HQWU\�� &HQWUDO�DGGUHVV�PDQDJHPHQW �� 2YHUYLHZ�� &DOHQGDU�� 2YHUYLHZ�� &RQFHSW�� 'HWHUPLQH�FDOHQGDU�,'�� &DOHQGDU�IXQFWLRQV �� 0HDVXUHPHQW�XQLWV �� 2YHUYLHZ�� &RQFHSW�� &KHFN�PHDVXUHPHQW�XQLW�WDEOH �� 0HDVXUHPHQW�XQLW�FRQYHUVLRQ�� &RQYHUVLRQ�RI�PHDVXUHPHQW�XQLWV�DQG�SRVVLEOH�HQWULHV��)��KHOS �� &KDQJH�GRFXPHQWV �� 2YHUYLHZ�� &RQFHSW�� 3URFHGXUH ��

Define change document object............................................................................................... 58Set change document flag........................................................................................................ 59


� -XQH��

Generate update and INCLUDE objects .................................................................................. 60Integrating the functionality into the program ........................................................................... 62

Writing the fields in the program ......................................................................................... 63&UHDWLQJ�FKDQJH�GRFXPHQWV �� 5HDG�DQG�IRUPDW�FKDQJH�GRFXPHQWV �� 5HDG�DQG�IRUPDW�SODQQHG�FKDQJHV�� 'HOHWH�FKDQJH�GRFXPHQWV�DQG�SODQQHG�FKDQJHV �� $UFKLYHG�FKDQJH�GRFXPHQWV�PDQDJHPHQW �� &UHDWH�DSSOLFDWLRQ�ORJ �� 2YHUYLHZ�� &RQFHSW�� 3URFHGXUH �� 'HILQH�DSSOLFDWLRQ�ORJ�REMHFWV�� &UHDWH�DSSOLFDWLRQ�ORJ �� 'LVSOD\�DSSOLFDWLRQ�ORJ�� 5HDG�DSSOLFDWLRQ�ORJ�� 'HOHWH�DSSOLFDWLRQ�ORJ�� 3ODWIRUP�LQGHSHQGHQW�)LOH�1DPH�$VVLJQPHQW�� 2YHUYLHZ�� 'HILQLWLRQV�RI��3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV �� 7KH�)XQFWLRQ�0RGXOH�),/(B*(7B1$0(�� 8VLQJ�3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV�LQ�3URJUDPV �� 5HIHUHQFH�� 1XPEHU�UDQJHV �� 2YHUYLHZ�� &RQFHSW�� 1XPEHU�UDQJH�REMHFW�W\SHV �� 3URFHGXUH ��

Determine the number range object type................................................................................. 99Maintain number range object................................................................................................ 100Function module calls............................................................................................................. 103

1XPEHU�UDQJH�DQG�JURXS�PDLQWHQDQFH�GLDORJV�� 1XPEHU�UDQJH�DQG�JURXS�UHDG�DQG�PDLQWDLQ�VHUYLFHV �� 1XPEHU�UDQJH�REMHFW�UHDG�DQG�PDLQWDLQ�VHUYLFHV �� 1XPEHU�DVVLJQPHQW�DQG�FKHFN �� 8WLOLWLHV �� $UFKLYLQJ �� 2YHUYLHZ�� $'.�DV�DUFKLYLQJ�SURJUDP�GHYHORSPHQW�HQYLURQPHQW �� ,QWHUDFWLRQ�EHWZHHQ�3URJUDP��$'.�DQG�$UFKLYH�ILOH �� $UFKLYLQJ�ZLWK�$'. ��

Archiving activities .................................................................................................................. 117Archiving object ...................................................................................................................... 118Standard class........................................................................................................................ 120Archiving classes.................................................................................................................... 121Archive management.............................................................................................................. 123


-XQH��

Network graphic...................................................................................................................... 124Accessing data objects in the archive – Index ....................................................................... 125

'HYHORSLQJ�DUFKLYLQJ�SURJUDPV�� Define archiving objects ......................................................................................................... 127Define standard class hierarchical structure .......................................................................... 129Archive customizing................................................................................................................ 130Assign archiving classes ........................................................................................................ 132

'HYHORS�DUFKLYLQJ�SURJUDP �� Standard archiving program ................................................................................................... 136Archiving using archiving classes........................................................................................... 137

'HYHORS�GHOHWH�SURJUDP�� 'HYHORS�UHORDG�SURJUDP �� 'HYHORS�DQDO\VLV�SURJUDP��RSWLRQDO� �� 0DLQWDLQ�QHWZRUN�JUDSKLF �� &UHDWH�DQ�LQGH[�DQG�XVH�LW�WR�DFFHVV�LQGLYLGXDO�GDWD�REMHFWV�LQ�WKH�DUFKLYH �� 8VH�RI�DUFKLYLQJ�FODVVHV�� 'HYHORS�DUFKLYLQJ�FODVVHV��

Specify function group............................................................................................................ 151Develop function modules ...................................................................................................... 152Develop Form routines ........................................................................................................... 153

Initialize the archiving class for writing .............................................................................. 154Get data............................................................................................................................. 155Delete archiving class local memory................................................................................. 156Declare a handle invalid .................................................................................................... 157Initialize the archiving class for reading ............................................................................ 158Copy data from the data container.................................................................................... 159Delete archived data ......................................................................................................... 160Discard the data flagged for delete ................................................................................... 161Reload archived data ........................................................................................................ 162

Define archiving class............................................................................................................. 163*HQHUDWH�DUFKLYLQJ�SURJUDPV �� 0RGHO�3URJUDPV��

Model write program – ARCHIVE........................................................................................... 167Model delete program – DELETE .......................................................................................... 170

$UFKLYLQJ�IXQFWLRQV ��


� -XQH��

%&�([WHQGHG�DSSOLFDWLRQV�IXQFWLRQ�OLEUDU\


6WDQGDUGL]HG�GLDORJV

-XQH��

6WDQGDUGL]HG�GLDORJVThis section explains how you can standardize the dialogs in your developments.

2YHUYLHZ�>3DJH��@

&RQFHSW�>3DJH��@

3URFHGXUHV

3URFHGXUH�>3DJH��@

'HWHUPLQH�GLDORJ�W\SH�>3DJH��@

&UHDWH�GLDORJ�WH[W�'RFXPHQW�>3DJH��@

5HIHUHQFHV

&RQILUPDWLRQ�SURPSW�GLDORJV�>3DJH��@

'LDORJV�IRU�FKRRVLQJ�IURP�DPRQJ�DOWHUQDWLYHV�>3DJH��@

'LDORJV�IRU�GLVSOD\LQJ��LQSXWWLQJ�DQG�FKHFNLQJ�GDWD�>3DJH��@

'DWD�SULQW�GLDORJV�>3DJH��@

7H[W�GLVSOD\�GLDORJV�>3DJH��@

6FUROOLQJ�LQ�WDEXODU�VWUXFWXUHV�>3DJH��@


2YHUYLHZ

� -XQH��

2YHUYLHZSome dialog steps and functions are required frequently during the realization of applicationdevelopment dialogs. These are available as function modules in self-contained modules. Theiruse standardizes application dialogs, which in turn simplifies use.


&RQFHSW

-XQH��

&RQFHSWThe function modules provide a standardized dialog box with function keys which are tested atthe end of the dialog. Depending on the function module, texts for information, for choices and/orfor the available function keys can be passed.


3URFHGXUH

�� -XQH��

3URFHGXUHNo preparatory steps are necessary for the use of the function modules for standardized dialogboxes, with the exception of the text display function modules (function group SP06). In this case,the texts must be created previously.

To use standardized dialog boxes, perform the following steps:

1. Determine dialog type [Page 11]

If you want to use a function module from the function group SPO6: Create dialog textDocument [Page 12]

2. Choose the appropriate function module in the function group found in step 1.

3. Call this function module in the application.


'HWHUPLQH�GLDORJ�W\SH

-XQH��

'HWHUPLQH�GLDORJ�W\SHDetermine what information you want to provide the user, and the decision logic you require.Then choose the appropriate function group from the following table.

6LWXDWLRQ )XQFWLRQ�JURXS

The user is to be warned of potential data loss SPO1

The user should answer a question about further processing with Yes orNo

SPO1

The user is to be warned about potential data loss, and decide whether heor she wants to continue with the action

SPO1

The user must choose between further processing alternatives SPO2

The user must continue the current action or cancel SPO2

The user is to input data (with or without check against a value table) SPO4

Data are to be displayed to the user SPO4

The user is to receive detailed information SPO6

The user is to be able to scroll in a displayed list STAB

The user is to print data from a table or a table view STRP


&UHDWH�GLDORJ�WH[W�'RFXPHQW

�� -XQH��

&UHDWH�GLDORJ�WH[W�'RFXPHQWTo create a “Dialog text” (for function modules in the function group SP06), proceed as follows:

1. In the initial screen choose the function 7RROV �→�$EDS��:RUNEHQFK�→(QYLURQPHQW �→� 'RFXPHQWDWLRQ.

2. Position the cursor on the document class output field and press F4.

3. Choose the class 'LDORJ�WH[W.

4. Enter a document name and choose &UHDWH.

5. Enter the text and save it.Saving via the icon creates a raw document. Raw versions can not be transported ortranslated. The document must be a final version for these actions to be possible.You achieve this with the function 6DYH�ILQDO�YHUVLRQ. You must be authorized to savefinal versions of documents in this development class.


&RQILUPDWLRQ�SURPSW�GLDORJV

-XQH��

&RQILUPDWLRQ�SURPSW�GLDORJV

)XQFWLRQ�JURXS�632�

This function group contains the following function modules:

• 32383B72B&21),50B67(3With this function module you create a dialog box in which you ask the user during anaction, whether he or she wishes to perform the step. You pass the title and a two-linequestion. The user must choose <HV, 1R or &DQFHO.The possible responses are provided by the function module.In the interface, the response "Yes" is pre-selected, but "No" can also be pre-selectedvia a parameter.The user response (<HV,�1R or�&DQFHO) is returned in a parameter.

• 32383B72B&21),50B:,7+B0(66$*(With this function module you create a dialog box in which you inform the user abouta specific decision point during an action. You pass a title, a three-line diagnosis textand a two-line question, which he or she must answer with <HV, 1R or &DQFHO.The possible responses are provided by the function module. In the interface theresponse "Yes" is pre-selected, but "No" can also be pre-selected via a parameter.The user response (<HV,�1R or &DQFHO) is returned in a parameter.

• 32383B72B&21),50B:,7+B9$/8(With this function module you create a dialog box in which you ask the user, duringan action, whether he or she wishes to perform a processing step with a particularobject. You pass a title, a two-line decision question and the object, which is insertedbetween the two parts of the question. The user must choose <HV, 1R�or &DQFHO.The possible responses are provided by the function module.In the interface the response "Yes" is pre-selected, but "No" can also be pre-selectedvia a parameter.The user response (<HV,�1R or &DQFHO) is returned in a parameter.

• 32383B72B&21),50B/266B2)B'$7$With this function module you create a dialog box in which you ask the user, duringan action, whether he or she wishes to perform a processing step with loss of data.You pass the title and the two-line question. The warning that data are lost and thepossible responses are provided by the function module. The user must answer"Yes", "No" or “Cancel”.In the interface the response "No" is pre-selected and can not be changed.The user response (<HV,�1R or &DQFHO) is returned in a parameter.


'LDORJV�IRU�FKRRVLQJ�IURP�DPRQJ�DOWHUQDWLYHV

�� -XQH��

'LDORJV�IRU�FKRRVLQJ�IURP�DPRQJ�DOWHUQDWLYHV



• 32383B72B'(&,'(With this function module you create a dialog box in which you require the user tochoose between the two further processing alternatives offered, or to cancel theaction.The action, the question and the alternative actions are passed as parameters. In theinterface the alternative 1 is pre-selected, but alternative 2 can also be pre-selectedvia a parameter.The user action (Alternative 1, Alternative 2, or Cancel) is returned in a parameter.

• 32383B72B'(&,'(B:,7+B0(66$*(With this function module you create a dialog box in which you inform the user abouta specific decision point via a diagnosis text, during an action. He or she can chooseone of two alternative actions offered or cancel the action.The action, the diagnosis text, the question and the alternative actions are passed asparameters.The user action (Alternative 1, Alternative 2, or Cancel) is returned in a parameter.


'LDORJV�IRU�GLVSOD\LQJ��LQSXWWLQJ�DQG�FKHFNLQJ�GDWD

-XQH��




• 32383B*(7B9$/8(6This function module sends a dialog box for data display and input.The input fields are passed in a structure and must be defined in the Dictionary. Youcan also specify individual field display attributes and a field text, if the key word fromthe Dictionary is not to be displayed as field text in the dialog box, in the structure.The standard help functionality (F1, F4) is supported.

• 32383B*(7B9$/8(6B'%B&+(&.('This function module sends a dialog box for data to be input und checked against thedatabase.The input fields are passed in a structure and must be defined in the Dictionary. Youcan also specify individual field display attributes and a field text in the structure, if thekey word from the Dictionary is not to be displayed as field text in the dialog box.A comparison operator for checking the input data in the database is passed. You canspecify whether the check is for the existence or absence of an object. A foreign keyrelationship check is supported.The standard help functionality (F1, F4) is supported.The user action is returned in a parameter.

• 32383B*(7B9$/8(6B86(5B&+(&.('This function module sends a dialog box for data to be input and checked in anexternal sub-routine (user exit). The input fields are passed in a structure and must bedefined in the dictionary. You can also specify individual field display attributes and afield text in the structure, if the key word from the Dictionary is not to be displayed asfield text in the dialog box.The Data input by the user in the dialog box are passed to the sub-routine specified inthe interface for checking. Errors found by the check are entered in an error structureand are evaluated on return from the sub-routine by the function module.The standard help functionality (F1, F4) is supported.The user action (&RQWLQXH or &DQFHO) is returned in a parameter.

• 32383B*(7B9$/8(6B86(5B+(/3This function module sends a dialog box for data to be input with the possibility of acheck in an external sub-routine (user exit) and branching in a user F1 or F4 help.The input fields are passed in a structure and must be defined in the Dictionary. Youcan also specify individual field display attributes and a field text in the structure, if thekey word from the Dictionary is not to be displayed as field text in the dialog box.You can pass the data which are entered by the user in a dialog box to a sub-routinewhich must be specified in the interface for checking. Errors occurring in the checkare stored in an error structure and are analyzed by the function module upon returnfrom the sub-routine. The data, and an error message, if appropriate, are displayedagain.The standard help functionality (F1, F4) is supported.User exits for a user F1 or F4 help can also be specified.The user action (&RQWLQXH or &DQFHO) is returned in a parameter.

• 32383B*(7B9$/8(6B86(5B%877216This function module is like the previous function module



�� -XQH��

POPUP_GET_VALUES_USER_HELP, with the additional possibility of passing oneor two additional pushbuttons and a standard pushbutton, which the user can name.

• 32383B*(7B9$/8(6B6(7B0$;B),(/'With this function module you can specify the maximum number of fields which canbe displayed in dialog boxes for this function group (SPO4). The specified value isstored in the function group local memory and applies for the rest of the application.Dialog boxes which display more then this number of fields are displayed with a scrollbar.


'DWD�SULQW�GLDORJV

-XQH��

'DWD�SULQW�GLDORJV

)XQFWLRQ�JURXS�6753

With the two function modules in this function group you can print database table or view records.With a parameter you can control whether the table records are output with a standard list formator whether the user can specify the print format in a dialog box. The user can choose fields,specify a sort sequence and specify the column sequence and titles in these dialog boxes.Standard output (without dialog box) error cases are caught by exceptions. Output with user-defined format generates error messages in case of error.

• 7$%/(B35,17B6758&785(B.12:1You pass data from tables whose structure is known in the program to this functionmodule.

• 7$%/(B35,17B6758&785(B81.12:1You pass data from tables whose structure is not known in the program to thisfunction module. These structure data are fetched independently by the functionmodule.


7H[W�GLVSOD\�GLDORJV

�� -XQH��

7H[W�GLVSOD\�GLDORJV


With this function module you can display pre-prepared texts which exist in the system. Thesetexts must have been created as documents of the class “Dialog text “ with the documentationmaintenance transaction (7RROV�→�$%$3��:RUNEHQFK��→�(QYLURQPHQW��→'RFXPHQWDWLRQ).

• 32383B',63/$<B7(;7With this function module you display a text which exists in the system in a dialog box.

• 32383B',63/$<B7(;7B:,7+B3$5$06With this function module you display a text which exists in the system withparameters in a dialog box. The parameter values are passed in a table. The use ofnumbered texts is recommended, to make the parameter values translatable.The parameter names must be passed in upper-case letters.


6FUROOLQJ�LQ�WDEXODU�VWUXFWXUHV

-XQH��

6FUROOLQJ�LQ�WDEXODU�VWUXFWXUHV

)XQFWLRQ�JURXS�67$%

• 6&52//,1*B,1B7$%/(With this function module you enable the user to scroll in a list which you havecreated, e.g. as a logical part of an internal table. You can enable either page-wisescrolling or positioning on individual records.


([WHQGHG�WDEOH�PDLQWHQDQFH

�� -XQH��

([WHQGHG�WDEOH�PDLQWHQDQFHThis section explains how you can use the extended table maintenance standard maintenancedialog in your developments.



3URFHGXUH

&UHDWH�PDLQWHQDQFH�GLDORJ�>3DJH��@

&DOOLQJ�WKH�VWDQGDUG�PDLQWHQDQFH�GLDORJ�>3DJH��@

5HIHUHQFHV

&DOO�YLD�IXQFWLRQ�PRGXOH�>3DJH��@

+LJKHVW�OHYHO�HQWU\�>3DJH��@

0LGGOH�OHYHO�HQWU\�>3DJH��@

/RZHVW�OHYHO�HQWU\�>3DJH��@


2YHUYLHZ

-XQH��

2YHUYLHZThe extended table maintenance maintenance dialog provides the possibility of processing tabledata in a consistent maintenance dialog, independently of whether access is to be made directlyvia the table or via a view defined in the dictionary.

Integrating the maintenance dialog into user developments offers simplified access to tablecontents, and has the following advantages, among others:

• 7KH�SURJUDPPLQJ�HIIRUW�LV�FRQVLGHUDEO\�UHGXFHG�

• 7KH�RSHUDWLRQ�LV�FRQVLVWHQW��FRPSUHKHQVLEOH�DQG�FRQYHQLHQW�

The convenience is produced by comprehensive operating functionality, which guarantees thecomprehensibility and transparency of the maintenance procedures.

The maintenance dialog also allows table data to be viewed on two levels. You can branch froman overview screen to a detail screen for a selected record.

The maintenance dialog can be used in its entirety as a standard maintenance dialog, or table orview-specific modifications can be made.


&RQFHSW

�� -XQH��

&RQFHSWThe following standard table maintenance dialog functionality is already available in the systemfor user applications:

• A FHQWUDO�SURJUDP�PRGXOH, which contains all the maintenance functionality,including mark functions for multiple record processing, the possibility of selecting allrecords processed, recover deleted records, and much more besides.

• The PDLQWHQDQFH�WUDQVDFWLRQ, which uses the table or view-specific components aswell as the central program module.

,QWHUQDO�SURFHVVLQJ�VHTXHQFH

The processing sequence is illustrated using views as an example, in the following figure:

Database

Buffer

Interface

Table1

Table 2

Table 3

001

001

001

Table 3

for example Company Code

View 1 View 2 View 3

Company Code DataCompany Data

F11 = Save F11 = Save

InsertDeleteCopySelectetc.

InsertDeleteCopySelectetc.

A work area, which can contain all existing views or be restricted by a selection, is fetched fromthe database for processing on the screen. This work area is first loaded into internal tables. Atthis point, a further selection for processing by field contents can be made.

Field contents are maintained in the internal tables. The database is not accessed automaticallyafter the maintenance of each individual view record. Changes made are only copied from theinternal buffer to the database when the user chooses save. This buffering gives the


&RQFHSW

-XQH��

maintenance processing the form of a transaction. This enables the user to cancel changesbefore the database access (user-controlled „Rollback“) and allows the calling main program tocheck entries for consistency in context.

0DLQWHQDQFH�GLDORJ�LQWHJUDWLRQ

The maintenance dialog can be integrated as follows:

• 0DLQWHQDQFH�WUDQVDFWLRQ�LQWHJUDWLRQ in a menu or an application.

• 0DLQWHQDQFH�GLDORJ�LQWHJUDWLRQ�XVLQJ�IXQFWLRQ�PRGXOHV in an application withparameter passing.There are three possible entry levels, which differ according to the extent to which themaintenance procedure can be controlled.

±� +LJKHVW�OHYHOWith this interface you call the complete maintenance dialog for a table or a view.You can restrict the table entries which are read from the database usingselections.

±� 0LGGOH�OHYHOThis level contains the actual maintenance dialog with the steps “Read, Edit,Save” in this order. You must program preparatory actions, such as locking thedata, reading the Dictionary, etc., yourself.

− /RZHVW�OHYHOWith this interface you control all maintenance procedures individually from yourprogram. You pass the actions to be performed to the function module asparameters.In this way you can easily integrate individual maintenance steps (“Read, Edit,Save”) in your program.


&UHDWH�PDLQWHQDQFH�GLDORJ

�� -XQH��

&UHDWH�PDLQWHQDQFH�GLDORJYou can make the following maintenance components available with the table maintenancedialog generation transaction (7RROV �→�$%$3��:RUNEHQFK��→�'HYHORSPHQW��→�2WKHU7RROV��→�*HQ�WDE�PDLQW�GLDORJ):

• *HQHUDWHG�REMHFWVGenerates all maintenance modules which are required to call the maintenancedialog.

• 7DEOH�RU�YLHZ�GHILQLWLRQ�in the DictionaryProcesses the definition of the current table or view.During the definition, table and field level access type authorizations can be specified.It can also be specified whether there is to be a detail screen for each overviewscreen record.

This is necessary for two-step procedures, but also for tables or views whoserecords can not be completely displayed on the overview screen because of thenumber or length of their fields. It can also be appropriate when complicatedmaintenance procedures require long input field explanatory texts, e.g. bydisplaying data from foreign key tables.

• $XWKRUL]DWLRQ�JURXSVYou can create authorization groups for tables or views.The activities defined for an authorization group apply during the use of themaintenance dialog for the tables or views in the authorization group.

• $XWKRUL]DWLRQ�JURXS�DVVLJQPHQWYou can group tables or views.

To be able to call the maintenance dialog, you must generate the table or view-specificmaintenance modules. Proceed as follows:

1. Choose 7RROV�→�$%$3��:RUNEHQFK�→�'HYHORSPHQW��→�2WKHU�7RROV�→*HQ�WDE�PDLQW�GLDORJ� You enter the maintenance transaction initial screen.

2. Enter the name of the table or view.

3. Mark the option “Generated objects”.

4. Choose &UHDWH�&KDQJH.

5. Confirm that the maintenance module is to be created in the following dialog box,.

Instead of steps 1. to 5. you can call the function 8WLOLWLHV�→�*HQ�PDLQW��GLDORJ inthe Dictionary (7RROV�→�$%$3��:RUNEHQFK�→�'HYHORSPHQW��→�'LFWLRQDU\)for the table or view in question. You go to the maintenance screen for thegenerated object for the current table.

6. Enter the data required for generation:

- Function group to which the maintenance module is to belong


&UHDWH�PDLQWHQDQFH�GLDORJ

-XQH��

It is possible to store the maintenance modules for several tables or views. in onefunction group

- Authorization group

- Maintenance type (one/two-step)

- Maintenance screen (one-step) or screens (two-step) number

- Recording routine (standard/individual or none)

7. Then choose &UHDWH. All required maintenance modules are now generated.

If you subsequently want to make changes, you must call the function &KDQJH, tore-generate the maintenance module in question.

Then you can call the standard maintenance dialog or the maintenance function modules for thetable or view in question.


&DOOLQJ�WKH�VWDQGDUG�PDLQWHQDQFH�GLDORJ

�� -XQH��

&DOOLQJ�WKH�VWDQGDUG�PDLQWHQDQFH�GLDORJIf you want to call the standard maintenance dialog in your application, code the maintenancedialog call in your program, and pass the name of the table or view as a parameter.


&DOO�YLD�IXQFWLRQ�PRGXOH

-XQH��

&DOO�YLD�IXQFWLRQ�PRGXOHWhen the maintenance dialog is called via function modules, three entry levels are distinguished:

• +LJKHVW�OHYHOCall of the complete maintenance dialog

• 0LGGOH�OHYHOYou can control the maintenance dialog to a limited extent.

• /RZHVW�OHYHOYou call the maintenance object-specific function modules yourself and control thedialog completely.


+LJKHVW�OHYHO�HQWU\

�� -XQH��

+LJKHVW�OHYHO�HQWU\You can call the standard maintenance dialog via the function moduleVIEW_MAINTENANCE_CALL. The function module performs the following activities:

• Authorization check

• Locking

• Fetching and formatting the necessary information from the Dictionary

• Selection, processing and saving the data

• Restrict the data selection in the sub-set field dialog

• Dynamic interface modification (menus and functions)

You can influence the maintenance dialog at run-time in the following ways:

• 6HOHFWLRQ�FRQGLWLRQVYou specify the selection conditions with which you wish to restrict thedata selection in the database, in an internal table.

• ,QWHUIDFHYou can dynamically disactivate functions of the central standardinterface SAPLSVIM via an internal table.

Please see the function module documentation in the system for the interfacedescription.


0LGGOH�OHYHO�HQWU\

-XQH��

0LGGOH�OHYHO�HQWU\At this entry level, you call function modules to control the table maintenance.

Call the function module VIEW_MAINTENANCE.

For this function module, only the table or view name need be specified. The control functionmodule name for the maintenance dialog call is put together and then called.

The function module performs the selection, processing and saving of the data and the interfacelayout. You must have already performed the following activities yourself before you callVIEW_MAINTENANCE.

• $XWKRUL]DWLRQ�FKHFN�IRU�WKH�WDEOH�YLHZThe function module VIEW_AUTHORITY_CHECK can be used.

• /RFN�WKH�WDEOH�YLHZThe function module VIEW_ENQUEUE can be used.

• )HWFKLQJ�DQG�IRUPDWWLQJ�WKH�UHTXLUHG�LQIRUPDWLRQ�IURP�WKH�'LFWLRQDU\The function module VIEW_GET_DDIC_INFO can be used.

• 3RVVLEO\�UHVWULFWLQJ�WKH�GDWD�DUHD�LQ�GLDORJThe function module TABLE_RANGE_INPUT can be used.

At run-time you can influence the maintenance dialog in the following ways:

• 6HOHFWLRQ�FRQGLWLRQVYou save the selection conditions with which you wish to restrict the dataselection in the database in an internal table.

• ,QWHUIDFHYou can dynamically disactivate functions of the central standardinterface SAPLSVIM via an internal table.

Please see the function module documentation in the system for the interfacedescription.

,QWHUIDFH�GHVFULSWLRQ

,PSRUW�SDUDPHWHUV

• &255B180%(5Change request number of the change made, see function moduleVIEW_MAINTENANCE_CALL documentation

• 9,(:B$&7,21Action (Display, maintain or transport)see function module VIEW_MAINTENANCE_CALL documentation

• 9,(:B1$0(Name of the table/view to be processed

([SRUW�SDUDPHWHUV

none



�� -XQH��

7DEOHV

• '%$B6(//,67Database access selection conditions.

Structure: INCLUDE STRUCTURE VIMSELLIST, see function moduleVIEW_MAINTENANCE_CALL documentation.

All data which are read for table processing and are created by maintenance, arestored at run-time in the internal table TOTAL.

The table TOTAL has the structure:

– INCLUDE STRUCTURE <view name> or <table name>

– INCLUDE STRUCTURE VIMFLAGTAB

• '3/B6(//,67Selection conditions for the display of part of a work area on the maintenancescreens.

Structure and documentation as for DBA_SELLIST.

The data are stored at run-time in the internal table EXTRACT. The table EXTRACTalways contains only the table records which were filtered out of the table TOTAL as aresult of a user action.

The table EXTRACT has the same structure as the table TOTAL

• (;&/B&8$B)81&7Interface functions which can be dynamically de-activated.

Structure: INCLUDE STRUCTURE VIMEXCLFUN, see function moduleVIEW_MAINTENANCE_CALL documentation

• ;B+($'(5Control block table for the view/table.

Structure: INCLUDE STRUCTURE VIMDESC.

The table contains the table or view header information from the Dictionary, such assub-set, selection conditions, maintenance status, delivery class. The table alsocontains information about the table or view generation and event times for user formroutines. You can fill this table with the function module VIEW_GET_DDIC_INFO.

• ;B1$07$%Control block table for the table/view fields.


The table contains the table or view field information from the Dictionary, such asstructure field positions, key information and maintenance characteristics of the field.You can fill this table with the function module VIEW_GET_DDIC_INFO.

([FHSWLRQV

• 0,66,1*B&255B180%(5Correction number missing

• 12B'$7$%$6(B)81&7,21Data processing module missing



-XQH��

• 12B(',725B)81&7,21Control module missing

• 12B9$/8(B)25B68%6(7B,'(17Sub-set field value missing


/RZHVW�OHYHO�HQWU\

�� -XQH��

/RZHVW�OHYHO�HQWU\For this entry level, the function modules generated for data processing are available.

Call the function module VIEW_MAINTENANCE_LOW_LEVEL. Knowledge of the view or table-specific function module name for the data processing is not necessary, as it is put together bythe system and then called.

Pass the name of the table or view and the desired function when calling. You must evaluate thereturned user commands.

You must also perform all the activities which the maintenance dialog otherwise performs:

• Authorization check

• Lock

• Fetch and format the required information from the Dictionary

• Select, edit and save the data

• Restrict the data selection in dialog for subset fields

• Dynamic interface modification (menus and functions)

,QWHUIDFH�GHVFULSWLRQ

,PSRUW�SDUDPHWHUV

• )&2'(desired function.

– 'READ' Read the data from the DB

– 'EDIT' process data

– 'RDED' Read and edit

– 'SAVE' Write the data to the DB

– 'ORGL' Re-set all marked entries

– 'ORGD' Re-set one entry

• 9,(:B$&7,21Action (Display, maintain or transport).see function module VIEW_MAINTENANCE_CALL documentation

• 9,(:B1$0(Name of the table or view.

• &255B180%(5Change request number for the changes made.see function module VIEW_MAINTENANCE_CALL documentation

([SRUW�SDUDPHWHUV

• /$67B$&7B(175<Index of the record in table EXTRACT on which the cursor was positioned.

• 8&200Last maintenance dialog user command.



-XQH��

You must process the following commands yourself on this entry level:

– 'SAVE' Save the data in the DB

– 'ORGL' Re-set all marked entries in the display table (EXTRACT)

If this command is returned, you must call the lowest entry level function moduleagain with this command and then with the previous command. You do not haveto write your own re-set program.

The lowest entry level was called with the moduleVIEW_MAINTENANCE_LOW_LEVEL and the function 'EDIT'. The user hascalled the function 'ORGL'. The module VIEW_MAINTENANCE_LOW_LEVELhas now to be called first with the function 'ORGL'. The module runs in thebackground. Then the module VIEW_MAINTENANCE_LOW_LEVEL has to becalled again with the function 'EDIT'.

– ‘ORGD' Re-set the entry in the display table (EXTRACT) header.

see command 'ORGL' for command processing.

− 'ANZG' Change action: Change -> Display

− 'AEND' Change action: Display -> Change

− ‘ENDE' End processing

− ‘BACK' Return to calling position

− 'ATAB' Fetch another table or viewThis field also contains the commands which were realized in user modules in themaintenance screens.

• 83'$7(B5(48,5('Flag: Entries changed, Save required.

The user has made changes which make it necessary to save the data before leavingthe maintenance dialog.

7DEOHV

• &255B.(<7$%Table with the keys of the entries to be transported. The table is only used intransport mode.

Structure: INCLUDE STRUCTURE E071K

• '%$B6(//,67Selection conditions for the database access.

Structure: INCLUDE STRUCTURE VIMSELLIST see function moduleVIEW_MAINTENANCE _CALL documentation.

All data which are read in for the table processing or are created during maintenance,are stored in the internal table TOTAL at run time.

The table TOTAL has the structure:




�� -XQH��


See also the function module VIEW_MAINTENANCE_CALL documentation.

• '3/B6(//,67Selection conditions for the display of part of a work area on the maintenancescreens.

Structure and documentation as DBA_SELLIST

The data are stored at run time in the internal table EXTRACT. The table EXTRACTalways only contains the table records which have been filtered out of the tableTOTAL as a result of a user action.

The table EXTRACT has the same structure as the table TOTAL

See also the documentation of the function module VIEW_MAINTENANCE_CALL

• (;&/B&8$B)81&7dynamically activated interface functions.

Structure: INCLUDE STRUCTURE VIMEXCLFUN, see function moduleVIEW_MAINTENANCE_CALL documentation.

• 727$/Data table, contains all data which have been read in and changed, deleted or addedduring the processing.

Structure:



All data which are read in for the table processing or are created during maintenanceare stored at run time in the internal table TOTAL. After the function has been carriedout, the table gets a processing flag for each record processed.

• (;75$&7Data display work table.

Structure as table TOTAL

The data are stored at run time in the internal table EXTRACT. The table EXTRACTalways only contains the table records which have been filtered out of the tableTOTAL as the result of a user action. After the function has been performed, the tablecontains all the data found by the last selection for display.

• ;B+($'(5Control block table for the table or view.

Structure: INCLUDE STRUCTURE VIMDESC

The table contains the Dictionary header information about the table or view, such assub-set, selection conditions, maintenance status, delivery class. The table alsocontains the generation information and event time information for the table or view.You can fill this table with the function module VIEW_GET_DDIC_INFO.

• ;B1$07$%Control block table for the fields of the table or view.




-XQH��

The table contains the field information about the table or view, from the dictionarysuch as the position of the field in the structure, key information and the maintenancecharacteristics of the field. You can fill this table with the function moduleVIEW_GET_DDIC_INFO.

([FHSWLRQV

• 0,66,1*B&255B180%(5Correction number missing

• 6$9,1*B&255(&7,21B)$,/('Error while saving the entries in a change request.


&HQWUDO�DGGUHVV�PDQDJHPHQW

�� -XQH��

&HQWUDO�DGGUHVV�PDQDJHPHQW2YHUYLHZ�>3DJH��@


2YHUYLHZ

-XQH��

2YHUYLHZAddresses can arise in many different forms. There are, on the one hand, various kinds ofadddress, e.g. addresses of companies or of private individuals, they can also, e.g.internationally, have a different structure. A central address management has been created tosimplify the address management across all applications, and to make access and processingeasier.


&DOHQGDU

�� -XQH��

&DOHQGDUThis section explains which holiday and factory calendar data you can access in the system, anduse in your own developments.



3URFHGXUH

'HWHUPLQH�FDOHQGDU�,'�>3DJH��@

5HIHUHQFHV

&DOHQGDU�IXQFWLRQV�>3DJH��@


2YHUYLHZ

-XQH��

2YHUYLHZLocation-specific calendars can be defined in the SAP system. These can take account of bothregional holidays and location-specific conditions of service.

Function modules are available to enable you to use these data in your own developments.


&RQFHSW

�� -XQH��

&RQFHSWPublic holidays can be defined and be combined into regionally valid holiday calendars. A holidaycalendar is identified in the system by a two-character calendar ID.

A holiday calendar is assigned to each factory calendar. The following information can also bedefined and stored:

• Definition of the working days

• Special conditions

The days which count as working days according to this definition are numbered sequentiallyfrom 0 (unless otherwise defined). These numbers represent the factory date. The calendar datecan be directly accessed via the factory date, e.g. to calculate delivery dates.

The factory calendar is identified in the system by a two-character calendar ID.

&DOHQGDU�KLHUDUFK\

Maintaining publicholiday calendar

2.

Maintainingpublic holidays

1.

3. Maintaining factorycalendar

. . . Def. publicholiday n

Def. publicholiday 2

Def. publicholiday 1

Public holiday calendar K1Def. weekdays/publicholidays, special rules

Define factorycalendarID: F1

Public holiday 1. . .Public holiday n

Define public holidaycalendarID: K1


'HWHUPLQH�FDOHQGDU�,'

-XQH��

'HWHUPLQH�FDOHQGDU�,'Some function modules only get general calendar data. They can be called without anypreparation. Others provide data about particular holiday or factory calendars. To call thesefunction modules, you need the relevant calendar ID. To find it, proceed as follows:

1. Call the calendar maintenance transaction in one of the following two ways:

- In the implementation guide for *OREDO 6HWWLQJV choose →�0DLQWDLQ�FDOHQGDU →([HFXWH

- Call the transaction SCAL in the OK-Code field.

2. Choose the option “Holiday calendar” or “Factory calendar”.

3. Choose 'LVSOD\.You receive a list of all holiday or factory calendars which exist in the system, withdescriptive text and ID.

4. Choose a calendar.Call the function 'LVSOD\��GHILQLWLRQ, to get the definition of the chosen calendar.Call the function 'LVSOD\�FDOHQGDU, to get a calendar overview. In the factorycalendars overview screen you can choose a year and display a calendar page forthe chosen year with the function 'LVSOD\�\HDU.


&DOHQGDU�IXQFWLRQV

�� -XQH��

&DOHQGDU�IXQFWLRQVAll function modules are contained in the function group SCAL.

• '$7(B&20387(B'$<This function module returns the day of the week for the date passed.

• '$7(B*(7B:((.This function module returns the week for the date passed.

• :((.B*(7B),567B'$<This function module returns the first day of the week passed. (This is always aMonday, regardless of whether it is a working day or a holiday.)

• ($67(5B*(7B'$7(This function module returns the date of Easter Sunday for the year passed.

• )$&725<'$7(B&219(57B72B'$7(This function module returns the calendar date for the factory date and the factorycalendar passed.

• '$7(B&219(57B72B)$&725<'$7(This function module returns the factory date for the date and factory calendarpassed. You can specify with a parameter whether the next or the previous workingday is returned if the day is not a working day.

• +2/,'$<B&+(&.B$1'B*(7B,1)2With this function module, you test whether a particular date in the holiday calendarpassed is a holiday. If so, the definition of the holiday is returned.


0HDVXUHPHQW�XQLWV

-XQH��

0HDVXUHPHQW�XQLWVThis section explains which function modules you can use in your developments for processingmeasurement units.



3URFHGXUH

&KHFN�PHDVXUHPHQW�XQLW�WDEOH�>3DJH��@

5HIHUHQFHV

0HDVXUHPHQW�XQLW�FRQYHUVLRQ�>3DJH��@

&RQYHUVLRQ�RI�PHDVXUHPHQW�XQLWV�DQG�SRVVLEOH�HQWULHV��)��KHOS�>3DJH��@


2YHUYLHZ

�� -XQH��

2YHUYLHZMeasurement units often have to be converted in applications. In multi-lingual systems, or withlanguage-dependent measurement units, there is also the problem of displaying the relationshipsbetween measurement units correctly in the interface. For these reasons, SAP function modulesare provided, with which all tasks which arise in connection with measurement units can beperformed. The required information for each measurement unit is stored in a measurement unittable, which is accessed by the function modules for performing conversions.

This includes conversion exits, which perform an automatic conversion between external andinternal format when using certain domains for screen input/output fields.

The function modules are buffered by default to minimize the number of database accessesneeded for the conversion. The buffer is created at the first call of a module in each functiongroup. This call therefore takes somewhat longer to complete. In general though, many modulesin both function groups are used repeatedly, so that the effort of creating the buffer is justified.


&RQFHSW

-XQH��

&RQFHSWMeasurement units serve to measure properties of business applications. These propertiescomprise physical properties, that can be associated with dimensions in a measurement system,and properties without dimension, that cannot be defined unequivocally in a measurementsystem.

To work with electronic data interchange (EDI) you must name measurement units correspondingto the recommendations for ISO-codes. Furthermore, measurement units carry several othernames for internal and external presentation in the R/3 system.

3K\VLFDO�3URSHUWLHV

For physical properties, you can distinguish between basic and derived properties. Derivedproperties can be defined from algebraic combinations of basic properties. Which physicalproperties are viewed as basic and which as derived is a question of the purpose. There aremany different measurement systems with different basic properties. Each basic property definesone basic dimension of a measurement system.

The SAP standard shipment uses the international measurement unit system (SI) with the sevenbasic properties length, time, mass, temperature, electrical current, light intensity, and molarity.Therefore, the SI-System has seven basic dimensions. The basic properties of each dimensioncan be measured in specific measurement units. The measurement units of the SI-system for itsseven basic dimensions are the SI units meter (m), second (s), kilogram (kg), Kelvin (K), ampere(A), candela (cd) and mol (mol).

The dimensions of all derived properties of a measurement system are algebraic combinations ofits basic dimensions. In the SI system, the measurement units of derived properties arecombinations of the SI units and have partly own names and abbreviations.

'HULYHG�SURSHUW\ 0HDVXUHPHQW�8QLW 1DPH

speed m/s ---

acceleration m/s2 ---

force kg m/s2 Newton (N)

energy kg m2/s2 joule (J)

Besides the SI units, you can define for each dimension of the SI systems other measurementunits to any extend. Linear relations exist between different measurement units of one dimension.These relations allow conversions between the measurement units of one dimension and areference to the corresponding SI unit.

'LPHQVLRQ 0HDVXUHPHQW�8QLW &RQYHUVLRQ�WR�6,�8QLW

length inch (") 0,0254 m

mass ton (t) 1000 kg

temperature Celsius (°C) K - 273,14


&RQFHSW

�� -XQH��

energy erg (erg) 0.0000001 J

Such definitions serve for better handling of measurement units (for example centimeters andkilometers) or they are country specific (for example feet and miles).

The relations between the dimensions as well as the different measurement units of onedimension are defined unequivocally. Therefore, in the R/3 system, measurement units aremaintained centrally in customizing tables. The dimensions of derived properties are defined inthese tables by listing the exponents of the involved basic dimensions. The names of thecorresponding customizing tables start with T006. You maintain these tables with thetransactions CUNI and OMSC. The function modules that are described in the present sectionwork with these tables.

In the R/3 system, combinations of basic dimensions must be unique and can be related to onederived dimension only. For example, energy (force times distance) and torque (force timesradius) cannot be defined in one R/3 system simultaneously.

3URSHUWLHV�ZLWKRXW�'LPHQVLRQV

Besides the measurement units for the seven physical properties of the SI system, measurementunits for properties without dimensions are important for business applications. These units areused for countable properties. Examples for units without dimensions are : palette, box, pieceetc. There are no unequivocal relations between measurement units without dimensions. Therelations depend on the business applications. For example, a box can contain one, six, or twelvepieces.

In the R/3 system, the conversions between the measurement units without dimensions aredefined material specifically in the table MARM. You maintain table MARM with transactionsMM01 and MM02 in the applications. The function modules described in the present section workalso with this table.

$EEUHYLDWLRQV�RI�0HDVXUHPHQW�8QLWV��,62�&RGH

The ISO standard 31 describes measurement units. But in this standard, there is no rule for theofficial abbreviations (ISO-code) of the measurement units. For the ISO-codes of measurementunits exists the recommendation 20 of WP.4 in the UN/ECE (UN Economic Commission forEurope, Information Office, Palais des Nations, CH-1211 Geneva, phone +4122917 2893, fax+4122917 0036, e-mail [email protected], http://www.unicc.org/unece/oes/info.htm). Sinceyou need the ISO-Code for electronic data exchange (EDI), you should maintain therecommended ISO-code for each measurement unit in the corresponding tables of the R/3system.

,QWHUQDO�DQG�([WHUQDO�3UHVHQWDWLRQ�RI�0HDVXUHPHQW�8QLWV

For measurement units in the R/3 system, you can distinguish between internal and externalpresentation. The internal presentation is language independent, serves exclusively for internalprocessing, and does not appear on the surface. The external presentation is language-dependent and serves for screen output. For the external presentation, you can choose betweendifferent naming types for different applications:

• commercial (three-character, only upper case)

• technical (six-character)

• short text (ten-character)


&RQFHSW

-XQH��

• long text (thirty-character)

These naming types are maintained language-dependently in table T006A. For example, thecommercial presentation of the dimension-less measurement unit piece is PC in English, ST(Stück) in German, and PI (Pièce) in French.

The commercial and technical presentation together with the languageinformation form a language dependent key for the corresponding internalpresentation of the measurement unit. Therefore, they must be maintaineduniquely for each language.

The system uses the language-dependent key that is defined from commercial and technicalpresentation in conversion exits. It calls these conversion exits automatically on screens(dynpros) or during WRITE statements if the domains LUNIT (for technical measurement units)and CUNIT (for commercial measurement units) are used for data elements.


&KHFN�PHDVXUHPHQW�XQLW�WDEOH

�� -XQH��

&KHFN�PHDVXUHPHQW�XQLW�WDEOHBefore you use the measurement unit function modules, you should ensure that the requiredmeasurement units and dimensions are maintained.

To do so, go to the implementation guide in section *OREDO�6HWWLQJV�→�&KHFN�XQLW�RIPHDVXUHPHQW.


0HDVXUHPHQW�XQLW�FRQYHUVLRQ

-XQH��


)XQFWLRQ�JURXS�6&9�


• %8))(5B&21752/If the default buffering is not wanted for the modules in this function group, you canswitch it off and on again by calling this module. You can also use the module torefresh the buffer (if, e.g. the contents of the table T006 were changed during theprogram run).

• &219(56,21B)$&725B*(7With this function module, you determine the conversion factors for the conversion ofa measurement unit into another using the measurement units table. This does notapply to measurement units within a dimension.The module also returns the number of decimal places to which the values in the unitUNIT_OUT are to be rounded. This also applies to units with no dimension.The following formula applies for the conversion:

(value in the unit UNIT_OUT) = (value in the unit UNIT_IN) * numerator/denominator+ additive constant.

• 5281'With this function module, you round a value to the specified number of decimalplaces. You can choose between three rounding types:

− Rounding up

− Rounding down

− Commercial rounding

The rounding is performed internally with the same field type as that of the fieldpassed.Rounding errors can thus occur when rounding a FLOAT value. If you want a highdegree of accuracy, the passed field should have the type 3.

• 6,B81,7B*(7You pass either a unit or a dimension to this function module to get the SI unit. If youpass both a unit and a dimension, the SI unit for the dimension is returned.

• 81,7B&219(56,21B:,7+B)$&725With this function module, you convert a value according to the factor passed.

• 81,7B&255(6321'(1&(B&+(&.With this function module, you can check whether the two units passed belong to thesame dimension.

• 81,7B*(7With this function module, you get the appropriate measurement unit for the specifieddimension and conversion factor.

• 81,7B&219(56,21B6,03/(With this function module, you convert a value using the measurement unit table, andround it, if appropriate.You can also perform the rounding without conversion.Conversion with this function module requires that the measurement unit table is



�� -XQH��

maintained for both units, and that both units belong to the same dimension, i.e. alsothat they have dimensions.The rounding can, however, also be performed for units which have no dimension.


&RQYHUVLRQ�RI�PHDVXUHPHQW�XQLWV�DQG�SRVVLEOH�HQWULHV��)��KHOS

-XQH��

&RQYHUVLRQ�RI�PHDVXUHPHQW�XQLWV�DQG�SRVVLEOH�HQWULHV�)��KHOS

)XQFWLRQ�JURXS�6&98


• %8))(5B&21752/B6&98If you do not want the default buffering for the modules in this function group, you canswitch it off, and on again, by calling this module. You can also use the module torefresh the buffer (e.g. if the contents of the table T006 were changed during theprogram run).

• &219(56,21B(;,7B&81,7B,1387With this function module, you specify the internal measurement unit for a commercialmeasurement unit (three-character external measurement unit).It is automatically called when measurement units are input on the screen.

• &219(56,21B(;,7B&81,7B287387With this function module, you specify the language-dependent commercialmeasurement unit (three-character external measurement unit) and the associatedshort and long text, for an internal measurement unit.It is automatically called when measurement units are output to the screen, and bythe WRITE command.

• &219(56,21B(;,7B/81,7B,1387With this function module, you specify the internal measurement unit associated witha technical measurement unit (six-character external measurement unit).It is called automatically when measurement units are input on the screen.

• &219(56,21B(;,7B/81,7B287387With this function module, you specify the language-dependent technicalmeasurement unit (six-character external measurement unit) and its associated shortand long text for an internal measurement unit.It is called automatically when measurement units are output to the screen, and bythe WRITE command.

• ',0(16,21B&+(&.With this function module, you check whether the internal measurement unitcorresponds to the specified dimension. It may also be checked whether it is acommercial unit. It is recommended, that you support the choice of validmeasurement units for a specified dimension with the function moduleUNIT_OF_MEASUREMENT_HELP.

• ',0(16,21B*(7With this function module, you specify the dimension key and the dimension text,depending on the contributions of the basic units.As the seven possible contributions have the default value zero, you must onlyspecify the non-zero contributions under EXPORTING when calling.

• ',0(16,21B*(7B)25B81,7With this function module, you specify the dimension key associated with ameasurement unit


&RQYHUVLRQ�RI�PHDVXUHPHQW�XQLWV�DQG�SRVVLEOH�HQWULHV��)��KHOS

�� -XQH��

• 81,7B2)B0($685(0(17B+(/3With this function module, you display in a dialog box either all measurement units orall commercial measurement units of a specified dimension (external measurementunit and associated long text). If you do not specify a dimension, all measurementunits are displayed. You can control whether the measurement units are onlydisplayed, or are offered for selection, with a parameter.


&KDQJH�GRFXPHQWV

-XQH��

&KDQJH�GRFXPHQWVThis section describes how you can log application changes, using change documents.



3URFHGXUH


'HILQH�FKDQJH�GRFXPHQW�REMHFW�>3DJH��@

6HW�FKDQJH�GRFXPHQW�IODJ�>3DJH��@

*HQHUDWH�XSGDWH�DQG�,1&/8'(�REMHFWV�>3DJH��@

,QWHJUDWLQJ�WKH�IXQFWLRQDOLW\�LQWR�WKH�SURJUDP�>3DJH��@

:ULWLQJ�WKH�ILHOGV�LQ�WKH�SURJUDP�>3DJH��@

5HIHUHQFHV

&UHDWLQJ�FKDQJH�GRFXPHQWV�>3DJH��@

5HDG�DQG�IRUPDW�FKDQJH�GRFXPHQWV�>3DJH��@

5HDG�DQG�IRUPDW�SODQQHG�FKDQJHV�>3DJH��@

'HOHWH�FKDQJH�GRFXPHQWV�DQG�SODQQHG�FKDQJHV�>3DJH��@

$UFKLYHG�FKDQJH�GRFXPHQWV�PDQDJHPHQW�>3DJH��@


2YHUYLHZ

�� -XQH��

2YHUYLHZMany commercial objects are frequently changed. It is often useful, or even necessary, to be ableto trace the changes made. If changes are logged, you can find out at any time, what waschanged and when and how the change was made. This can sometimes make the analysis oferrors easier. In financial accounting, for example, change documents are used to make auditingpossible.

Changes are logged in change documents, which can be created for actual or planned changes.


&RQFHSW

-XQH��

&RQFHSWFor changes to a commercial object to be able to be logged in a change document, the objectmust have been defined in the system as a change document object. A FKDQJH�GRFXPHQWREMHFW definition contains the tables which represent a commercial object in the system. Thedefinition can also specify whether the deletion of individual fields is to be documented. If a tablecontains fields whose values refer to units and currency fields, the associated table, containingthe units and currencies, can also be specified.

It must be specified for each table, whether a commercial object contains only one (single case)or several (multiple case) records. For example, an order contains an order header and severalorder items. Normally one record for the order header and several records for the order items arepassed to the change document creation when an order is changed.

The name under which a change document object is created is an REMHFW�FODVV.

The object class BANF was defined for the change document object “Purchaserequisition”, which consists of the tables EBAN (purchase requisition) and EBKN(purchase requisition account assignment).

Changes to this commercial object can then be saved in the system under the object values ofthis change document object, i.e. the REMHFW�,' and a change document number. The object ID isthe key to the object value, i.e. all records which are defined as belonging to a given changedocument object.

All changes to a commercial object constitute an object value under this key. This is for examplethe order number for orders or the number range object name for number range objects. Allchanges to a given order or to a given number range object can be accessed in this way.

The object value BANF with the object ID "3000000000" consists of the records ofthe tables EBAN and EBKN with the order number "3000000000".

If changes are not yet to be made, but are planned, they can be logged as SODQQHG�FKDQJHV. Aplanned date for the changes can be specified. The planned changes can be analyzed andcopied into the tables. You must program the copy yourself.

All logging functions are supported by SAP function modules. The application development mustcontain certain INCLUDE programs. Old and new status are passed to the change documentcreation. The included function modules determine the changes for all table fields which areflagged as being change-relevant in the Dictionary.

&KDQJH�GRFXPHQW

A change document logs changes to a commercial object. The document is createdindependently of the actual database change. The change document structure is as follows:

• &KDQJH�GRFXPHQW�KHDGHUThe header data of the change to an object ID in a particular object class are storedin the change document header. The change document number is automaticallyissued.


&RQFHSW

�� -XQH��

• &KDQJH�GRFXPHQW�LWHPThe change document item contains the old and new values of a field for a particularchange, and a change flag.The change flag can take the following values:

±� 8�SGDWH�Changed data. (Log entry for each changed field which was flagged in theDictionary as “change document-relevant”)

±� ,�QVHUW�Data inserted.Changes: Log entry for the whole table recordPlanned changes: Log entry for each table record field

±� '�HOHWH�Data were deleted (log entry for the whole table record)

±� ,�QGLYLGXDO�ILHOG�GRFXPHQWDWLRQ�Delete a table record with field documentation1 log entry per field of the deleted table entry, the deleted text is saved

• &KDQJH�GRFXPHQW�QXPEHUThe change document number is issued when a change is logged, i.e. when thechange document header is created by the change document creation functionmodule (function group SCD0).

The change number is not the same as the change document number. TheFKDQJH�GRFXPHQW�QXPEHU�is issued automatically by the function group SCD0function modules when a change document is created for a change documentobject. The FKDQJH�QXPEHU is issued by the user when changes are planned.The same change number can be used for various change document objects.

,QWHUQDO�SURFHVVLQJ

When the object-specific update is called, the object-specific change document creation is called.The object-specific change document header is written with a change document number. TheDictionary is searched for which fields are to be logged for each table in the object definition. Thelog records for these fields are then created as change document items according to the objectdefinition.


3URFHGXUH

-XQH��

3URFHGXUHTo use the change document functionality in your application, proceed as follows:

1. Define the change document object

2. Check in the Dictionary, whether the data elements of the fields which are to belogged are flagged appropriately.

3. Generate the update.

4. Program the appropriate calls in your program.


'HILQH�FKDQJH�GRFXPHQW�REMHFW

�� -XQH��

'HILQH�FKDQJH�GRFXPHQW�REMHFWProceed as follows:

1. Call the change document maintenance transaction (7RROV�→�$%$3��:RUNEHQFK→�'HYHORSPHQW�→�2WKHU�WRROV�→�&KDQJH�GRF��REMHFW). An overview of existingchange document objects is displayed.

2. Choose the menu option &UHDWH�

3. Enter a name for the change document object which is to be created. It can be anyname starting with "Y" or "Z" (customer name area).

4. Choose &RQWLQXH. A new window for inputting the associated tables appears.

5. Enter a descriptive short text for the change document object.

6. Make the following entries for each table whose changes are to be logged in thechange document for this change document object:

� 7DEOH QDPHName of the table, as defined in the Dictionary

� &RS\�DV�LQWHUQDO�WDEOH flag�If the change data are to be passed in an internal table (multiple case), mark thisfield. If it is not marked, the change data are passed in a work area (single case).

� 'RF��IRU�LQGLYLGXDO�ILHOGV�DW�GHOHWH flagIf you want separate log entries for each field when data are deleted, mark thisfield. If it is not marked, the deletion of all relevant fields is entered in onedocument item.

� 5HI��WDEOH�QDPH��(Name of the reference table)If the currency and unit fields are defined in a reference table, rather than in thetable passed, you must pass the name of the reference table, and the fieldreferred to, to the function module. Create an INTTAB structure in the Dictionary,and define fields for this structure, which are made up of the names of theassociated reference table and the reference fields.Enter the name of this structure here.In the individual case, the reference information is passed in the form of two extrawork areas (old, new). In the collective case, the internal tables are extended toinclude the reference structure.

� 1DPH�RI�WKH�ROG�UHFRUG�ILHOGVOnly possible for single case, i.e. when passing change data in a work area: Ifyou do not want to use the * work area, enter an alternative work area name here.

7. After inputting all relevant tables, choose ,QVHUW�HQWULHV. The new entries are copiedinto the display.

8. Save your entries.

7UDQVSRUW�FKDQJH�GRFXPHQW�REMHFW

The change document objects are a transport object type, a change request is made when theobject is created.

During transport the object-specific update is generated in the target system.


6HW�FKDQJH�GRFXPHQW�IODJ

-XQH��

6HW�FKDQJH�GRFXPHQW�IODJNow check whether the change document flag is set for the corresponding data element in theDictionary for the fields whose changes are to be logged. This is necessary so that the object-specific function modules can identify which field of the defined object should be entered in thechange document during logging.

If the flag is not set, you can change it. The flag becomes effective after the activation.

If the flag is set by hand, it can have undesirable side-effects: If a table field inanother application, which is based on the data element in question, belongs to achange document object, but was not previously logged, setting the flag will startlogging in this application as well.It is therefore important to consider whether data elements are, or could be,change-relevant when creating them, and to set the flag accordingly. If the dataelement is not in any change document object via a table field, this has nonegative effect on the system.


*HQHUDWH�XSGDWH�DQG�,1&/8'(�REMHFWV

�� -XQH��

*HQHUDWH�XSGDWH�DQG�,1&/8'(�REMHFWVThe generation creates INCLUDE objects, which contain general and specific data definitionsand the program logic for the update function module. Proceed as follows:

1. Call the change document maintenance transaction (7RROV �→�$%$3��:RUNEHQFK→�'HYHORSPHQW��→�2WKHU�WRROV��→�&KDQJH�GRFXPHQWV).

2. Position the cursor on a change document object and choose the menu option*HQHUDWH�XSGDWH�SJP. A dialog box, in which you must make the following entries, isdisplayed:

± ��FKDUDFWHUV�IRU�,1&/8'(�QDPHThis 4-character abbreviation (�.�!) is used to complete the name of thegenerated INCLUDE program parts.

± )XQFWLRQ�JURXSEnter the name of the function group, to which the change document updateprogram is to belong, here. If this function group does not yet exist in the system,it is automatically created during generation.Exactly one function group must belong to each change document object. Otherfunction modules may not be assigned to this function group.

± 3UHIL[�IRU�)P�VWUXFWXUHData passing structures for multiple case tables are created during generation.Their names are constructed from this prefix and the name of the multiple casetables. A proposed value is offered.

± 0HVVDJH�,'�IRU�HUURU�PHVVDJHVThe application-specific error messages generated are stored under thismessage ID (also called work area). A proposed value is offered.

± (UURU�QXPEHUNumber with which errors occurring in connection with this change documentobject can be identified in the system. A proposed value is offered.

±� ([HFXWLRQ�W\SHFlag to indicate how the update should be performed:

immediate executiondelayed executionin dialog

± 6SHFLDO�WH[W�SURFHVVLQJ flagMark this field if you want to log long text changes.The old and new status of long texts is not logged. Only the fact that they havebeen changed is noted.

3. Choose�*HQHUDWH�

The following INCLUDE objects are generated:

±� �FKDQJH�GRFXPHQW�REMHFW!B:5,7(B'2&80(17The object-specific update function module calls the following function modules,with object-specific parameters:

CHANGEDOCUMENT_OPEN


*HQHUDWH�XSGDWH�DQG�,1&/8'(�REMHFWV

-XQH��

CHANGEDOCUMENT_SINGLE_CASE and/orCHANGEDOCUMENT_MULTIPLE_CASE and possiblyCHANGEDOCUMENT_TEXT_CASE

CHANGEDOCUMENT_CLOSE

±� )�.�!&'&INCLUDE program part with FORM statement for calling the object-specificupdate program.

±� )�.�!&'7INCLUDE program part containing two INCLUDE program parts (F<K4>CDF andF<K4>CDV, see below), which contain the data definitions which are to bepassed to the update program.The data definitions correspond to the function group SCD0 function modulesinterface definition. The fields, record fields and tables are to be filled in in theapplication program and passed to the update program.

� )�.�!&')INCLUDE program part with data definitions which are the same for all changedocument objects.

±� )�.�!&'9INCLUDE program part with data definitions, which are specific to the changedocument object.

±� 9�''�VWUXFWXUH�QDPH�! (only for multiple case tables)This structure contains the following INCLUDE structures:

INCLUDE <table name>

INCLUDE KZ

INCLUDE <ref. table name>

The generated program parts contain the object-specific program code, and areincluded in the application program per INCLUDE statement. The data definitionsof the change document-relevant fields correspond to the function group SCD0function module interface definitions.

If several change document objects are to be processed in one applicationprogram, the update program must be generated for each change documentobject with a different <K4> code (e.g. XX01, XX02, XX03 etc.).


,QWHJUDWLQJ�WKH�IXQFWLRQDOLW\�LQWR�WKH�SURJUDP

�� -XQH��

,QWHJUDWLQJ�WKH�IXQFWLRQDOLW\�LQWR�WKH�SURJUDP1. Include the generated program parts in your program code with an INCLUDE

statement.

2. When application changes are made, complete the change-relevant fields asappropriate.

3. To create the change document, call the object-specifically generated updateprogram with a PERFORM statement using the name defined in F<K4>CDC.

The INCLUDE program part F<K4>CDT can only be included once, because itcontains a further INCLUDE program part (F<K4>CDF, with generally valid datadefinitions), which is also contained in the other F<K4>CDT program parts (e.g.FXX02CDT, FXX03CDT, etc.). It must be included in the global data definitions.In this case the F<K4>CDT program part must be included for the first changedocument object or <K4> code, which contains the INCLUDE program parts forgeneral (F<K4>CDF) and object-specific data definitions (F<K4>CDV), for allothers only the F<K4>CDV program parts.


:ULWLQJ�WKH�ILHOGV�LQ�WKH�SURJUDP

-XQH��

:ULWLQJ�WKH�ILHOGV�LQ�WKH�SURJUDPComplete the change document-relevant fields and tables as follows.

*HQHUDO�GDWD

These are the fields which are defined in the INCLUDE program part )�.�!&').

• 2%-(&7,'Object value (key) of the object

• 7&2'(Transaction, with which the change was made

• 87,0(Change time

• 8'$7(Change date

• 86(51$0(Changed by

2EMHFW�VSHFLILF�GDWD

These are the fields which are defined in the INCLUDE program part�)�.�!&'9.

6LQJOH�FDVH�WDEOHV�

• Table� �WDEOH�QDPH�!�or record fields��ROG�UHFRUG�ILHOGV�QDPH�! (with the tablestructure)The table header record or the record fields must contain the original data.

• Table �WDEOH�QDPH�!The table header record must contain the new data.

• Table� �UHI��WDEOH�QDPH�!(only if UHI��WDE� QDPH�was specified when the change document object was defined)The table header record must contain the original currencies and units.

• 83'B�WDEOH�QDPH�!With this flag, you specify the processing logic.The following values are possible:

- "'" (DELETE)A change document item is to be created for the record in *<table name > or <oldrecord fields name > which is to be flagged as deleted. <table name > is notprocessed.

- "," (INSERT)A change document item is to be created for the record in <table name > which isto be flagged as created. *<table name > or <old record fields name > is notprocessed.

- "8" (UPDATE)*<table name > or <old record fields name > and <table name > are comparedand a change document item is created for each changed field. The keys of*<table name > or <old record fields name > and <table name > must be identical.



�� -XQH��

- " " (space, no processing)*<table name > or <old record fields name > and <table name > are notprocessed by the update program. (If no changes have been made, theprocessing can be skipped to save time.)

0XOWLSOH�FDVH�WDEOHV�

These tables must be passed sorted by key.

• <�WDEOH�QDPH�!The table must contain the original version of the changed or deleted records. Thestructure consists of the table, as specified in the change document object definitionunder WDEOH�QDPH, a processing flag (TYPE C, length 1) and possibly the structure of theassociated currency and units table, as specified in the definition of the change documentobject under 5HI��WDEOH�QDPH� It is created during the change document object INCLUDEgeneration and saved under the name V<table name > in the Dictionary.

The processing flag can be switched from space to "D", if it is to be processed in the application.Otherwise it has no effect.

• ;�WDEOH�QDPH�!The table must contain the current version of the changed or created records. Thestructure is the same as Y<table name > (see above).The following values are possible for the processing flag:

- "," (INSERT)Records were created, or table records were deleted, then a record with the samekey was created in the same transaction, and this is to be documented as”Delete” and “Create” (special case), not as “Change”.

- "8" or " " (space) (UPDATE)

The parameter UPD_<table name > (see below) initially determines whether therecord is new or changed. The processing flag is only checked when, with theparameter value "U", the following key comparison between the two tablesTABLE_OLD and TABLE_NEW finds two records with the same key.

Multiple case internal table processing flags can always contain space, with theexception of the special case (in X<table name >). The possibility of setting theprocessing flag to "D", "I" or "U" as well was created so that the tables could alsobe used for other purposes in which such processing flags are useful, inapplication programs.

• 83'B�WDEOH�QDPH�!With this flag you determine the processing logic.The following values are possible:

- "'" (DELETE)A change document item is to be created for each record in Y<table name >which is to be flagged as deleted. X<table name> is not processed.



-XQH��

- "," (INSERT)A change document item is to be created for each record in X<table name> whichis to be flagged as created. Y<table name> is not processed.

- "8" (UPDATE)The keys of TABLE_OLD and TABLE_NEW are compared. The following casesare distinguished:

±� ��5HFRUG�H[LVWV�LQ�7$%/(B2/'�EXW�QRW�LQ�7$%/(B1(:� Changedocument items are to be created for the record in TABLE_OLD which is tobe deleted.

±� ��5HFRUG�H[LVWV�LQ�7$%/(B1(:�EXW�QRW�LQ�7$%/(B2/'� A changedocument item is to be created for the records in TABLE_NEW which are tobe flagged as created.

±� ��5HFRUG�H[LVWV�LQ�ERWK�7$%/(B2/'�DQG�7$%/(B1(:� A changedocument item is created for each changed field which is defined as changedocument-relevant in the Dictionary.

- " " (space, no processing)Y<table name> and X<table name > are not processed by the update program. (Ifno changes have been made, the processing can be skipped to save time.)

7H[W�FKDQJHV�

If text changes are to be logged (according to the change document object definition), thefollowing fields are to be completed:

• ,&'7;7B�2EMHFW!This structure contains the change document-relevant texts with correspondingdetails:

- TEILOBJIDKey of the changed table record

- TEXTARTText type of the changed texts

- TEXTSPRLanguage key

- UPDKZChange flag for the table record: '(elete), ,(nsert) or 8(pdate)

• 83'B,&'7;7B�2EMHFW!Change flag for the text table:

- " " (space)Table is ignored by the update program

- "8"Table is taken into account by the update program

2SWLRQDO�SDUDPHWHUV

You can also use the following INCLUDE program part )�.�!&') parameters:

• &'2&B3/$11('B25B5($/With this parameter you control whether the changes to be logged are actual or



�� -XQH��

planned changes.Possible values

±� “5” actual (real) changes

±� “3” planned changes

±� “ “(space) if no plan number exists: actual changeif a plan number exists: planned change

• &'2&B83'B2%-(&7If the change document is relevant for determining which change action wasperformed for the object, you can pass the action performed here.Possible values:

±� “,” the object was inserted.

±� “8” the object was changed.

±� “'” the object was deleted.


&UHDWLQJ�FKDQJH�GRFXPHQWV

-XQH��

&UHDWLQJ�FKDQJH�GRFXPHQWV

)XQFWLRQ�JURXS�6&'�

Object-specific update change documents for a particular object ID are created with the functionmodules in this function group.

These function modules are called, in the right order, by the object-specificallygenerated update program, as soon as it is called. They are generally notrequired for application developments. Only in exceptional cases, in which anindividual update is to be programmed, should the change document creation beprogrammed by the user with these function modules.

• &+$1*('2&80(17B23(1This function module is required by every change document creation. It initializes theinternal fields for a particular change document object ID.

• &+$1*('2&80(17B08/7,3/(B&$6(This function module creates change document items. The change data are passedin tables.

• &+$1*('2&80(17B6,1*/(B&$6(This function module creates change document items. The change data are passedin a work area.

• &+$1*('2&80(17B7(;7B&$6(Change document-relevant texts are passed in a structure with this function module.

• &+$1*('2&80(17B&/26(This function module is required for every change document creation. It writes thechange document header for a particular change document ID, and closes thedocument creation.

• &+$1*('2&80(17B35(3$5(B7$%/(6With this function module, you compare the records in two tables, which you pass asTABLE_OLD and TABLE_NEW.You can specify via a parameter, whether these internal tables should be prepared forthe multiple case. Identical records are then deleted, and a processing flag is set inchanged records.


5HDG�DQG�IRUPDW�FKDQJH�GRFXPHQWV

�� -XQH��

5HDG�DQG�IRUPDW�FKDQJH�GRFXPHQWVTwo function groups exist for these tasks:


With the function modules in this function group, you can read change documents.

• &+$1*('2&80(17B5($'B+($'(56This function module reads the change document numbers, with the associatedheader information, for a particular change document object. The search can berestricted by various parameters (changed by, date, time).You can use this function module in the database and in the archive.

• &+$1*('2&80(17B5($'B326,7,216This function module reads the change document items for a given change documentobject number, and formats the old and new values according to their type.You can use this function module in the database and in the archive.

• &+$1*('2&80(17B35(3$5(B326You format a previously read change document item for printing with this functionmodule.


You can process change document objects by classes with the function modules in this group.

• &+$1*('2&80(17B5($'With this function module, you read change document headers and the associateditems for a given object class and format the old and new values according to theirtype. The search can be restricted by various parameters (changed by, date, time).You can use this function module in the database and in the archive.


5HDG�DQG�IRUPDW�SODQQHG�FKDQJHV

-XQH��

5HDG�DQG�IRUPDW�SODQQHG�FKDQJHV


With the function modules in this function group, you find the planned changes.

• 3/$11('B&+$1*(6B5($'B+($'(56With this function module, you find the document headers of planned changes for agiven change document object. The search can be restricted by various parameters(changed by, date, time, change number).

The change number is not the same as the change document number. TheFKDQJH�GRFXPHQW�QXPEHU�is automatically issued by the function group SCD0function modules when a change document object change document is created.The FKDQJH�QXPEHU is assigned by the user when changes are planned. Thesame change number can be used for various change document objects.

• 3/$11('B&+$1*(6B5($'B326,7,216This function module reads the change document items for a given change documentnumber, and formats the old and new values according to their type.


'HOHWH�FKDQJH�GRFXPHQWV�DQG�SODQQHG�FKDQJHV

�� -XQH��

'HOHWH�FKDQJH�GRFXPHQWV�DQG�SODQQHG�FKDQJHV


With the function modules in this function group, you delete log entries of changes or plannedchanges.

• &+$1*('2&80(17B'(/(7(This function module deletes the change documents for a given change documentobject. The deletion can be restricted to a given change document number and/or achange date.An authorization check is made before the deletion.

• 3/$11('B&+$1*(6B'(/(7(With this function module, you delete planned changes. The deletion can be restrictedto a given change document object, a change document number, or specified changenumbers.

The change number is not the same as the change document number. TheFKDQJH�GRFXPHQW�QXPEHU is issued automatically by the function group SCD0function modules when a change document object change document is created.The FKDQJH�QXPEHU�is issued by the user when changes are planned. The samechange number can be used for various change document objects.


$UFKLYHG�FKDQJH�GRFXPHQWV�PDQDJHPHQW

-XQH��

$UFKLYHG�FKDQJH�GRFXPHQWV�PDQDJHPHQW


This function module is the archiving class for the change document (see also Archiving [Page110] in the archiving section in this document):

• &+$1*('2&8B$5&+,9(B2%-(&7With this function module, you pass the objects for which change documents are tobe archived, to the archiving.


&UHDWH�DSSOLFDWLRQ�ORJ

�� -XQH��

&UHDWH�DSSOLFDWLRQ�ORJThis section explains how you can log events in the application log in your application.



3URFHGXUH


'HILQH�DSSOLFDWLRQ�ORJ�REMHFWV�>3DJH��@

5HIHUHQFHV

&UHDWH�DSSOLFDWLRQ�ORJ�>3DJH��@

'LVSOD\�DSSOLFDWLRQ�ORJ�>3DJH��@

5HDG�DSSOLFDWLRQ�ORJ�>3DJH��@

'HOHWH�DSSOLFDWLRQ�ORJ�>3DJH��@


2YHUYLHZ

-XQH��

2YHUYLHZApplication events can be centrally logged in the application log. The advantage is system-widestandardized and uniform event logging, which is convenient to analyze.

Several different logs (for various objects) can be written at the same time by an application.

The application log is, in principal, similar to the system log. Whereas system event information islogged in the system log, relevant application events should be captured in the application log.

The application log can also be used as a message collector.


&RQFHSW

�� -XQH��

&RQFHSWApplication log objects are defined in the system. The object definition assigns a work area. Anobject can be divided into sub-objects.

Logging is performed object-specifically, via function modules.

An object log entry has the following structure:

• /RJ�KHDGHU with a unique log number.It contains the information, who, when, with which program or which transaction, gaverise to which event.It also contains the problem class of the message in the log with the greatest urgency.

• Any number of ORJ�PHVVDJHV with their urgency.The messages are divided into problem classes according to their urgency.

The log data are initially collected in local memory, and are then written to the database. Thisprocedure speeds up processing and reduces the number of database accesses. It is alsopossible to write log data to the database individually, to avoid losing the log records collected upto that point in the event of termination of the application, for example if the system crashes.

The logged data can be read in the database and displayed on the screen. It is also possible toread and to display the log data which is buffered in local memory with a log number (Messagecollector).

The logs have an expiry date, by which time at the latest they must be in the database. They canlater be removed from the database again, by a delete program.

Detailed information, either for the whole log or for each individual log message, can be saved intwo ways:

• Text module with any number of parameters

• User exit with any number of parameters

When the log is analyzed either the text module with the specified parameters is displayed, or theuser exit is performed, on request.

Additional information can be saved in an INDX-type table, which is used by the user exitanalysis.

In this way it is possible, for example, to save lists which can be displayed when the log isanalyzed, with the help of the user exit.

Classifying attributes can also be specified (importance of the log, or of the message).

If you want to perform your own log analysis, you can use the function modules to read from thedatabase or from local memory.

Logs can be deleted if necessary.


3URFHGXUH

-XQH��

3URFHGXUHBefore you can log events, you must first define an object, and possibly sub-objects. Applicationlog objects are maintained in an extra maintenance transaction.

You can then create and analyze the object log by calling the appropriate function modules.


'HILQH�DSSOLFDWLRQ�ORJ�REMHFWV

�� -XQH��

'HILQH�DSSOLFDWLRQ�ORJ�REMHFWV1. Call the maintenance transaction with 7RROV�→�$%$3��:RUNEHQFK�→

'HYHORSPHQW�→�2WKHU�WRROV�→�$SSOLFDWLRQ�ORJ.

2. Choose 1HZ�HQWULHV. An empty input area is displayed.

3. Enter an object name according to the naming convention:

- first character “Y” or “Z”

- second and third character: application ID (e.g. FI)

- fourth position, any character

4. Enter a descriptive short text.

5. Save your entries.

6. If you want to define sub-objects:

a) Choose the line with the object.

b) Choose 7DEOH�YLHZ�→�2WKHU�YLHZ� A structure overview is displayed forselection.

c) Position the cursor on “Sub-objects”, and choose &KRRVH. The sub-object displaywindow for the chosen object is displayed.

d) Choose 1HZ�HQWULHV.

e) Enter a sub-object name (beginning with “Y” or “Z”) and a descriptive short text.

f) Save your entries.

If several systems are being used, the object data must be transported. Sub-object data are not automatically transported with the object. They must each beentered separately in a change request.



-XQH��


)XQFWLRQ�JURXS�6/*�

You write the application log records with these function modules.

• $33/B/2*B:5,7(B+($'(5With this function module, you write the log header data in local memory.

• $33/B/2*B:5,7(B/2*B3$5$0(7(56With this function module, you write the name of the log parameters and theassociated values for the specified object or sub-object in local memory.If this function module is called repeatedly for the same object or sub-object, theexisting parameters are updated accordingly.If you do not specify an object or sub-object with the call, the most recently used isassumed.

• $33/B/2*B:5,7(B0(66$*(6With this function module you write one or more messages, without parameters, inlocal memory.

• $33/B/2*B:5,7(B6,1*/(B0(66$*(With this function module you write a single message, without parameters, in localmemory. If no header entry has yet been written for the object or sub-object, it iscreated.If you do not specify an object or sub-object with the call, the most recently used isassumed.

• $33/B/2*B:5,7(B0(66$*(B3$5$06With this function module you write a single message, with parameters, in localmemory. Otherwise the function module works likeAPPL_LOG_WRITE_SINGLE_MESSAGE.

• $33/B/2*B6(7B2%-(&7With this function module, you create a new object or sub-object for writing in localmemory. With a flag you can control whether the APPL_LOG_WRITE_… messagesare written in local memory or are output on the screen.

• $33/B/2*B,1,7This function module checks whether the specified object or sub-object exists anddeletes all existing associated data in local memory.

• $33/B/2*B:5,7(B'%With this function module you write all data for the specified object or sub-object inlocal memory to the database.If the log for the object or sub-object in question is new, the log number is returned tothe calling program.


'LVSOD\�DSSOLFDWLRQ�ORJ

�� -XQH��

'LVSOD\�DSSOLFDWLRQ�ORJ


With these function modules you display logs for analysis.

• $33/B/2*B',63/$<With this function module you can analyze logs in the database.

• $33/B/2*B',63/$<B,17(51With this function module you can analyze logs in local memory, e.g. when you haveonly collected log records at runtime and do not want to write to the database.


5HDG�DSSOLFDWLRQ�ORJ

-XQH��

5HDG�DSSOLFDWLRQ�ORJ


If you want to analyze the log yourself, you can read the logs with these function modules.

• $33/B/2*B5($'B'%With this function module you read the log data in the database for an object or sub-object according to specified selection conditions.

• $33/B/2*B5($'B,17(51With this function module you read all log data whose log class has at least thespecified value, from local memory, for the specified object or sub-object.


'HOHWH�DSSOLFDWLRQ�ORJ

�� -XQH��

'HOHWH�DSSOLFDWLRQ�ORJ


With this function module you delete logs.

• $33/B/2*B'(/(7(With this function module you delete logs in the database according to specifiedselection conditions.


3ODWIRUP�LQGHSHQGHQW�)LOH�1DPH�$VVLJQPHQW

-XQH��

3ODWIRUP�LQGHSHQGHQW�)LOH�1DPH�$VVLJQPHQWThis section explains how to use platform-independent file names in your application programs toaddress files to be stored.


'HILQLWLRQV�RI�3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV�>3DJH��@

7KH�)XQFWLRQ�0RGXOH�),/(�*(7�1$0(�>3DJH��@

8VLQJ�3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV�LQ�3URJUDPV�>3DJH��@

5HIHUHQFH�>3DJH��@


2YHUYLHZ

�� -XQH��

2YHUYLHZApplication data must often be stored in files outside the database. Depending on the particularoperating system in use, files are stored in different directories, and file and path names mustcomply with different syntax requirements. Therefore, many SAP application programs useplatform-independent logical file names and call the function module FILE_GET_NAME whenstoring data in files. The function module takes a logical file name as input and returns thecorresponding platform-specific file name and path.

By using this function module, you can assign file names in your application programs in astandardized way and independently of different hardware and software platforms.

To achieve this, logical file names and paths must be defined in the system. These definitions aremaintained in the implementation guide in section %DVLV�&RPSRQHQWV → 6\VWHP�$GPLQLVWUDWLRQ→ 3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV, or with transactions FILE and SF01.

Definitions used by SAP applications are delivered with the system and possibly adjusted in theimplementation process. See the application-specific documentation for information on whichapplications use which logical file names. Further definitions can be added according torequirements.


'HILQLWLRQV�RI��3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV

-XQH��

Definitions of Platform-independent File NamesThe conversion of a platform-independent file name to a platform-specific one is controlled bydefinitions that are stored in tables. These definitions refer to the following objects:

• 2SHUDWLQJ�V\VWHPV�DQG�6\QWD[�JURXSVAll operating systems are assigned to syntax groups. A syntax group is a group ofoperating systems that share a common syntax for file names and paths. Thedefinition of a syntax group specifies, for instance, how long file names may be, andwhether file name extensions are permitted or not.

• /RJLFDO�ILOH�QDPHA logical file name is a platform-independent descriptive name for a file to be stored inthe file system. Its definition applies to all clients of an R/3 system. In addition, it ispossible to specify client-specific definitions of a logical file name.

• 3K\VLFDO�ILOH�QDPHA physical file name is assigned to every logical file name.

• /RJLFDO�SDWKA logical path is a platform-independent descriptive name for a path where files are tobe stored. For the conversion of a logical file name to work for different platforms, it isnecessary that a logical path be assigned to that logical filename.

• 3K\VLFDO�SDWKOne or more physical paths are assigned to a logical path, each one applying to adifferent syntax group (platform).

The following figure shows the relationships between these objects that determine how a logicalfile name is converted to a platform-specific file name:

operating system logical file name

physical file name

syntax group logical path

physical path

platform-specific file name

Parameters in physical file names and paths

Physical file names and paths may contain the following keywords enclosed in angle bracketswhich are replaced at runtime:

7DEOH��.H\ZRUGV

.H\ZRUG 6XEVWLWXWLRQ�9DOXH

<OPSYS> operating system according to function module FILE_GET_NAME



�� -XQH��

<INSTANCE> instance of R/3-system

<SYSID> name of R/3-system according to system field SY-SYSID.

<DBSYS> database system according to system field SY-DBSYS

<SAPRL> R/3-Release according to system field SY-SAPRL

<HOST> host name according to system field SY-HOST

<CLIENT> client according to system field SY-MANDT

<LANGUAGE> logon language according to system field SY-LANGU

<DATE> date according to system field SY-DATUM

<YEAR> year according to system field SY-DATUM, 4-character

<SYEAR> year according to system field SY-DATUM, 2-character

<MONTH> month according to system field SY-DATUM

<DAY> day according to system field SY-DATUM

<WEEKDAY> week day according to system field SY-FDAYW

<TIME> time according to system field SY-UZEIT

<STIME> hour and minute according to system field SY-UZEIT

<HOUR> hour according to system field SY-UZEIT

<MINUTE> minute according to system field SY-UZEIT

<SECOND> second according to system field SY-UZEIT

<PARAM_1> value of Parameter 1 in function module FILE_GET_NAME

<PARAM_2> value of Parameter 2 in function module FILE_GET_NAME

<P=name> value of profile parameter of current system

<V=name> value of variable as defined in variable table

<F=name> value of export parameter OUTPUT of a function module

All physical paths must contain the keyword <FILENAME> as a placeholder forthe file name.

Inclusion of these parameters in physical file names and paths helps to both differentiate andstandardize the assignment of file names. The keyword <TIME>, for instance, can be usefulwhen a file needs to be stored several times in a row within a short time interval. Apart from thesystem fields, the following keywords, in particular, give you considerable flexibility in assigningfile names:

• <PARAM_1> and <PARAM_2> are replaced by values that are passed explicitly tothe function module FILE_GET_NAME in your program.

• <P=name> is replaced by values of profile parameters of the current system. To getthe list of profile parameters and their values, start report RSPARAM.



-XQH��

• <V=name> is replaced by values of variables from the customizing tables forplatform-independent file names.

• <F=name> is replaced by values that are returned by function modules. The names ofthese function modules must have the prefix "FILENAME_EXIT_". Note that in thekeyword such a function module is addressed only with the part of its name thatfollows this prefix. For example, when the function moduleFILENAME_EXIT_EXAMPLE is used, the appropriate keyword would read<F=EXAMPLE>.The function module used must have the export parameter OUTPUT and noreference type must be specified for this parameter. Import parameters must havedefault values. Table parameters are not supported.


7KH�)XQFWLRQ�0RGXOH�),/(B*(7B1$0(

�� -XQH��

The Function Module FILE_GET_NAMEPlatform-independent file names are used in applications programs by the function moduleFILE_GET_NAME. For a given logical file name, the function module generates thecorresponding platform-specific file name at runtime, based on definitions stored in customizingtables for converting platform-independent file names.

The following table gives an overview of its import and export parameters and of its exceptions.

7DEOH��,QWHUIDFH�RI�IXQFWLRQ�PRGXOH�),/(B*(7B1$0(

,03257�SDUDPHWHU )XQFWLRQ

CLIENT Logical file names can be client-specific. Here you can specifythe client to be used. The current client as stored in the systemfield SY-MANDT is used as default.

LOGICAL_FILENAME Here you specify the logical filename. (Uppercase letters mustbe used!)

OPERATING_SYSTEM Here you can specify the operating system for which togenerate the appropriate file name. The application server’soperating system as stored in the system field SY-OPSYS isused as default.

PARAMETER_1

PARAMETER_2

Here you can specify values that substitute the placeholders<PARAM_1> and <PARAM_2> in physical file names andpaths.

USE_PRESENTATION_SERVER

Specifies that the presentation server’s operating system beused as the basis for generating a platform-specific file name.

WITH_FILE_EXTENSION Specifies that the logical file name’s data format be used asfilename extension.

USE_BUFFER Specifies that the customizing tables for converting platform-independent file names be buffered in main memory.

(;3257�SDUDPHWHU )XQFWLRQ

EMERGENCY_FLAG If the returned value is not SPACE, then no physical path has beenfound for the logical filename under the current operating system. Inthis case the path specified in the profile parameter DIR_GLOBALwill be used as physical path.

FILE_FORMAT Returns the data format defined for the logical file name. You canuse this parameter to decide in which mode to open the file. It isalso required as a parameter for DOWNLOAD of files to thepresentation server.

FILE_NAME Returns the fully instantiated platform-specific file name and path.

([FHSWLRQV )XQFWLRQ

FILE_NOT_FOUND Raised if logical file name is not defined.

OTHERS Raised if other errors occur.



-XQH��

If the function module cannot find a physical path for the current operating system(see parameter EMERGENCY_FLAG), this may have various causes:

– the operating system is not defined in the customizing tables

– the operating system is not assigned to a syntax group

– no physical path is assigned to the logical path for the relevant syntax group

– no logical path is assigned to the logical file name.

Assume that in the customizing tables for platform-independent file names thefollowing definitions exist for the logical file name DATA_FILE and the logical pathDATA_PATH:

DATA_FILE SK\V��ILOH� file<PARAM_1>GDWD�IRUPDW�� BINORJLFDO�SDWK� DATA_PATH

DATA_PATH V\QWD[�JURXS� UNIX SK\V��SDWK� /tmp/<FILENAME>V\QWD[�JURXS� DOS SK\V��SDWK� c:\tmp\<FILENAME>

Assume also that the application server’s operating system has been assigned tosyntax group UNIX while the presentation server’s operating system has beenassigned to syntax group DOS.

The following two calls of the function module will then return the respectivevalues.

&$//�)81&7,21�),/(B*(7B1$0(

��(;3257,1*�� /2*,&$/B),/(1$0(�� '$7$B),/(

3$5$0(7(5B��

��,03257,1*�� (0(5*(1&<B)/$*�� )/$*�� ),/(B)250$7�� )250$7�� ),/(B1$0(�� )1$0(

��(;&(37,216�� ),/(B127B)281'�� 27+(56��

Returned values:

FLAG:FORMAT: BINFNAME: /tmp/file01

&$//�)81&7,21�),/(B*(7B1$0(

��(;3257,1*�� /2*,&$/B),/(1$0(�� '$7$B),/(



�� -XQH��

86(B35(6(17$7,21B6(59(5 �;� :,7+B),/(B(;7(16,21 �;

��,03257,1*�� (0(5*(1&<B)/$*�� )/$*�� ),/(B)250$7�� )250$7�� ),/(B1$0(�� )1$0(

��(;&(37,216�� ),/(B127B)281'�� 27+(56��

Returned values:

FLAG:FORMAT: BINFNAME: c:\tmp\FILE.BIN


8VLQJ�3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV�LQ�3URJUDPV

-XQH��

8VLQJ�3ODWIRUP�LQGHSHQGHQW�)LOH�1DPHV�LQ�3URJUDPV1. Make sure that the customizing tables contain definitions for the logical file name you

want to use, and that these definitions produce the intended file name conversion.Use transaction FILE to inspect existing definitions or to specify new ones. (Fordetails refer to the implementation guide in section %DVLV�&RPSRQHQWV → 6\VWHP$GPLQLVWUDWLRQ → Platform-independent File Names [Page 81].)

2. Make sure the physical paths referred to in these definitions do actually exist in thefile system at runtime. If necessary, create the respective directories or consult yoursystem administrator.

3. Test the file name conversion by calling the function module FILE_GET_NAME, usingtransaction SE37.

4. Include a call of the function module in your program. (In the ABAP/4 editor you cando this with function (GLW → ,QVHUW�VWDWHPHQW��.)

For more information on storing files on the application server and on the presentation serverplease refer to :RUNLQJ�ZLWK�)LOHV in the $%$3��8VHUV�*XLGH.

Problems with storing files may sometimes be due to a mismatch between thepaths defined for platform-independent file names and the file system. Generationof a valid platform-specific file name by the function module FILE_GET_NAME isnot sufficient; the path generated must also exist in the file system at runtime.


5HIHUHQFH

�� -XQH��

Reference• ),/(B*(7B1$0(

With this function module you can generate a platform-specific file name for aplatform-independent logical file name in your application program at runtime.


1XPEHU�UDQJHV

-XQH��

1XPEHU�UDQJHVThis section explains how you can use the automatic number assignment in your applications.



1XPEHU�UDQJH�REMHFW�W\SHV�>3DJH��@

3URFHGXUH


'HWHUPLQH�WKH�QXPEHU�UDQJH�REMHFW�W\SH�>3DJH��@

0DLQWDLQ�QXPEHU�UDQJH�REMHFW�>3DJH��@

)XQFWLRQ�PRGXOH�FDOOV�>3DJH��@

5HIHUHQFHV

1XPEHU�UDQJH�DQG�JURXS�PDLQWHQDQFH�GLDORJV�>3DJH��@

1XPEHU�UDQJH�DQG�JURXS�UHDG�DQG�PDLQWDLQ�VHUYLFHV�>3DJH��@

1XPEHU�UDQJH�REMHFW�UHDG�DQG�PDLQWDLQ�VHUYLFHV�>3DJH��@

1XPEHU�DVVLJQPHQW�DQG�FKHFN�>3DJH��@

8WLOLWLHV�>3DJH��@


2YHUYLHZ

�� -XQH��

2YHUYLHZIt is often necessary to directly access individual records in a data structure. This is done usingunique keys. Number ranges are used to assign numbers to individual database records for acommercial object, to complete the key. Such numbers are e.g. order numbers or materialmaster numbers.

These numbers provide, apart from unique identification of a data record, the possibility ofencoding differentiating information for an object. One could tell from the number e.g., to whichmaterial type a material belongs.

The R/3 number range management also monitors the number status, so that numbers whichhave already been issued are not re-issued.

All dialogs, database accesses or other activities which are necessary for the maintenance ofnumber range objects and number ranges and number allocation in user developments, can beperformed using SAP function modules.


&RQFHSW

-XQH��

&RQFHSWA commercial object, for which part of the key is to be generated via number ranges, is definedas a QXPEHU�UDQJH�REMHFW in the SAP system. If this commercial object contains sub-objects,e.g. company codes or controlling areas, this differentiation can also be made in the numberranges. This happens by specifying a field for the sub-object when defining the number rangeobjects. (Example: company code as sub-object of documents)

The number range interval within a commercial object and sub-object never overlap. The numberrange intervals in various sub-objects of a commercial object can overlap.

A number range interval is assigned to a commercial object via the number range number. Thisassignment is usually saved in a table belonging to the commercial object, the group table. Thefield (OHPHQW must be all or part of this table’s key. Elements which refer to the same numberrange interval form a group. You can decide whether you want to make this assignment possiblefor the user during the number range object maintenance (via the assignment of elements togroups) or whether you want to program it yourself.

When a new material master is created, the material type should determine fromwhich number range interval a number to complete the material master keyshould be assigned. The commercial object is the material master, the grouptable the material type table, with the element field material type as key field. Thenumber range numbers for the various element values (material types) are savedin this table. Material types are e.g. semi-finished or finished products.

A�QXPEHU�UDQJH contains a number range interval with a defined character set. The QXPEHUUDQJH�LQWHUYDO consists of numeric or alpha-numeric characters (only for external numberranges) and is delimited by the fields )URP�QXPEHU and 7R�QXPEHU. Either one interval, orseveral if financial years are to be distinguished, is assigned to a number range.

The QXPEHU�UDQJH�QXPEHU identifies a number range for the system and makes system-internalaccess to the number range interval possible. It can be numerical or alpha-numeric. This numberis generally assigned system-internally. If you do not need grouping or if you want to program thegroup table maintenance for the grouping yourself, you must enter the number range numberduring interval maintenance yourself.

If financial years are to be distinguished in the number assignment, there can be severalintervals. Separate intervals are then specified for each financial year. Number ranges can beH[WHUQDO�(number to be assigned manually by the user) or�LQWHUQDO (number assignedautomatically by the system).

A commercial object can either have only one number range (external RU�internal) or two numberranges (external DQG internal).

The various distinctions between commercial objects gives rise to eight Number range objecttypes [Page 95].

(OHPHQW�DQG�JURXS

Element is the field in the group table according to whose value a commercial object can begrouped. The grouping is done by number range assignment.

Element values to which the same number ranges are assigned constitute a group. For thematerial master, for example, the groups are managed in the material type table. The groups can


&RQFHSW

�� -XQH��

be maintained via the standard maintenance dialog for number range intervals. If you do not wantto do this, you must program it yourself.

Groups can be either dependent or independent of sub-objects. This depends on whether thesub-object is a group table field.

The following table shows as an example the grouping of material types and the associatednumber range assignment.

*URXSLQJ�PDWHULDO�W\SHV

Group Material type Internal no. range External no.range

Group 1 )LQLVKHG 01 02

Group 1 6HPL�ILQLVKHG 01 02

Group 2 5DZ�PDWHULDO 03 04

The material types )LQLVKHG and 6HPL�ILQLVKHG form one group, and the material type 5DZPDWHULDO another.

8QWLO�ILQDQFLDO�\HDU

Fixed time periods (financial years) are assigned to number range intervals within a numberrange with a year value. These intervals can overlap within a number range. In this case thefinancial year or until financial year, as well as the assigned number, must be part of theapplication table key.


1XPEHU�UDQJH�REMHFW�W\SHV

-XQH��


The description "with group" means that the assignment of number ranges toelements, i.e. the grouping, should be done via the standard maintenance dialog.

• Objects without sub-objects

ZLWKRXW�JURXS(1) one, two or several number ranges

ZLWK�JURXS(2) one number range, external RU�internal, per group(3) two number ranges, external DQG�internal, per group

• Objects with sub-objects

ZLWKRXW�JURXS(4) one, two or several number ranges

ZLWK�JURXS, independent of sub-object(5) one number range, external RU internal, per group(6) two number ranges, external DQG�internal, per group

ZLWK�JURXS, dependent on sub-object(7) one number range, external RU internal, per group(8) two number ranges, external DQG�internal, per group

All eight object types can also be distinguished by until financial years.

The definition of an object controls the number range maintenance dialog. If you, e.g. specify agroup table, the assignment of number ranges to element values in the group table can becarried out by the user in the standard maintenance dialog.

The following illustration provides an overview of the object types.



�� -XQH��

7KH�HLJKW�QXPEHU�UDQJH�REMHFW�W\SHV

Withgroup

Withgroup

2 Numberranges

category 6

1 Numberrange

category 7

2 Numberranges

category 8

Groupdependent on

sub-object

Group in-dependent of

sub-object

Withsub-object

2 Numberranges

category 3

1 Numberrange

category 2

Withoutsub-object

Object

1 Numberrange

category 5

Without group

category 1Without group

category 4

The following illustration shows, using two examples, the relationships between the conceptsdescribed in the previous sections.



-XQH��

([DPSOHV�RI�QXPEHU�UDQJH�REMHFW�W\SHV��DQG��

...

...

100 ... 199 200 ... 299 300 ... 399 400 ... 499

Number range 01

internal external

NoRg 02 NoRg 03

internal external

NoRg 04 NoRg 05

NoRg Object

Accounting documents Material master

Element

Fini Semi Raw ...

Group 01 Group 02

Material type

Object category 4 Object category 3NoRg Object

0037 1980 ...

0037 1990 ...

accounting document table material master table

... FINI

FINI

... RAW

SEMI

...

...

00100

00101

00400

00200

CLOCK RADIO

TOASTER

IRON PIN

TRANSISTOR

...

...

...

...

Example of Example of

1980 1990 2000

1 ... 50 1 ... 50 51 ... 100

To-Fiscal Year

GI

GR

001

001


3URFHGXUH

�� -XQH��

3URFHGXUHIf you want to use the SAP number range functionality in your application, proceed as follows:

1. Determine which type the new number range object is to have, and create thedefinition.

2. Maintain the number range intervals for the new object, or have them maintained bythe end users.

3. Use the Number assignment and check [Page 108] function modules in yourapplication program.


'HWHUPLQH�WKH�QXPEHU�UDQJH�REMHFW�W\SH

-XQH��

'HWHUPLQH�WKH�QXPEHU�UDQJH�REMHFW�W\SHTo determine the type of number range to be used, you must clarify the following points:

• How many number ranges are required: 1, 2 or more?

• Are the number ranges dependent on a sub-object (company code, plant, controllingarea, etc.)?

• Is a group to be formed (e.g. by material type)?

• If so, is the group dependent on the sub-object?

• Is the number range to depend on the financial year?

From the answers to these questions, using the illustration “Eight number range object types”,you can uniquely determine the type.


0DLQWDLQ�QXPEHU�UDQJH�REMHFW

�� -XQH��

0DLQWDLQ�QXPEHU�UDQJH�REMHFW1. Call the number range transaction (7RROV �→�$%$3��:RUNEHQFK��→�'HYHORSPHQW

→�2WKHU�7RROV��→�1XPEHU�UDQJHV).

2. Enter an object name and choose &UHDWH. An input window appears for thedevelopment class in which you want to save the number range object.

3. Enter a development class, and choose 6DYH. The object definition fields window nowappears.

4. To define the number range object, enter the following fields:

±� 6KRUW�WH[WObject short text (length 20), number range maintenance dialog explanations

±� /RQJ�WH[WObject long text (length 60), number range maintenance dialog explanations

±� 1XPEHU�OHQJWK�GRPDLQVThe domains determine the lengths of the numbers to be issued. They must be oftype NUMC or CHAR, and have a field length of 1-20. Choose an appropriatedomain from the Dictionary or create a new one.

±� 3HUFHQW�ZDUQLQJVThis value specifies from what percent free interval a warning is issued whennumbers are assigned. It must lie between 0.1 and 99,9.

±� 1XPEHU�UDQJH�WUDQVDFWLRQIf you enter a transaction code here, You can maintain the intervals for just thisobject by calling this code.

&UHDWH�VXE�REMHFW

If you want differentiate a number range object, enter the data element according to whose valueyou want to differentiate:

• 'DWD�HOHPHQW�VXE�REMHFW (object types 4-8)This data element must exist and be active in the Dictionary and have a check table.The domains must have a field length between 1 and 6.

'LVWLQJXLVKLQJ�E\�ILQDQFLDO�\HDU

If the commercial object records are to be distinguished by financial year, mark the field:

• 8QWLO�ILQDQFLDO�\HDU�IODJ��(all object types)

&UHDWH�JURXSV

If the commercial objects are to be grouped by elements, you can specify, by completing thefollowing fields, that the group table is to be maintained via the standard maintenance dialog.Otherwise you must program the assignment yourself.

• *URXS�WDEOH�(object types 2, 3, 5-8)Enter the name of the table which contains the grouping element, e.g. for the materialmaster, the material type table. The table must exist and be active in the Dictionaryand contain the number range element field as key. If the groups depend on the sub-object, the sub-object must be part of the key. Otherwise the group table must not



-XQH��

have any other key fields.A group table can only be assigned to at most one number range object.

• 6XE�REMHFW�ILHOG�LQ�JURXS�WDEOH��(object types 7 and 8)If the commercial object is differentiated by sub-object, and the groups are dependenton the sub-object, enter here the group table field which contains the sub-object value(object types 7 and 8). The sub-object field must be part of the key.

• 1R��UDQJH�HOHPHQW�ILHOG (object types 2, 3, 5-8)If the commercial object is to be grouped, enter here the group table field whichcontains the value according to which groups are to be formed. The number rangeelement field must be part of the key.

• ,QW��H[W�QR��UDQJH�QR��ILHOG (object types 3, 6, 8)Enter here the group table fields for internal and external number ranges, if theapplication is to support both external and internal number assignment. A group tablemust be specified at the same time. The fields must have the format char (2) or num(2).

• 1R��UDQJH�QR��ILHOG (object types 2, 5, 7)Enter here the group table field for the number ranges, if the application is to supportonly one number range (external or internal). The field must be part of the key andhave the format char (2) or num (2).Whether it is an external or internal number range is indicated when the interval forthis number range is created.

*URXS�PDLQWHQDQFH�HOHPHQW�WH[W�GLVSOD\

If the element text is to be displayed during group maintenance, mark this field:

• 'LVSOD\�HOHPHQW�WH[W

You must also maintain the following element text table entries with the text entries maintenancefunction:

• (OHPHQW�WH[W�WDEOH

• /DQJXDJH�ILHOG

• 6XE�REMHFW�ILHOGThis field only appears in the interface when the groups are defined as beingdependent on sub-objects.

• (OHPHQW�ILHOG

• 7H[W�ILHOG

When you have saved the input data, number range intervals can be created for the object.

'HOHWH�QXPEHU�UDQJH�REMHFW

To be able to delete a number range object, you must first delete the number range intervalswhich belong to it.

0DLQWDLQ�QXPEHU�UDQJHV

Have the end-user create number ranges with intervals, using the implementation guide. You canfind information about this in the system administration document in the section on numberranges.



�� -XQH��

7UDQVSRUW�QXPEHU�UDQJH�REMHFWV

When number range objects are maintained, they are entered in a change request. When thetransport is released, various consistency checks are made, to avoid the transport of objects witherrors. Error messages or warnings appear in the transport log. If errors occur, the export orimport is refused.


)XQFWLRQ�PRGXOH�FDOOV

-XQH��

)XQFWLRQ�PRGXOH�FDOOVThe function modules distinguish between the following objects:

• 1XPEHU�UDQJH�REMHFWV

• 1XPEHU�UDQJH�LQWHUYDOV�DQG�JURXSV

The following illustration shows the context of the function groups and their possible connectionsto application programs.

)XQFWLRQ�JURXSV�RYHUYLHZ

Menu

Applicationprogram

Function group

SNR0

Function group

SNR1

Function group

SNR2

Function group

SNR3

Function group

SNR4

Tools

Number check andassignment

Services for readingand maintainingand maint. dialog of

CALL FUNCTION ... CALL FUNCTION

CALL FUNCTION ...

CALL FUNCTION ...

CALL FUNCTION ...

CALL FUNCTION ...

...

...

...

...

DriverSNUM

Services for readingand maintainingnum. range intervalsand groups

Maintenance dialogfor number ranges,intervals, andgroups

num. range objects

Call via parametertransaction acc. todef. of num.range object

DB

If you want to work with the standard number range functionality, you only needthe function modules in the function group SNR3.


1XPEHU�UDQJH�DQG�JURXS�PDLQWHQDQFH�GLDORJV

�� -XQH��

1XPEHU�UDQJH�DQG�JURXS�PDLQWHQDQFH�GLDORJV


The function modules in this function group constitute the dialog with which number ranges,number range intervals and number range groups can be maintained.

The function modules which are labeled " " can only be used for the object types2 and 3 and 5-8 (see illustration in number range object types).

• 180%(5B5$1*(B6+2:This function module displays the groups which exist for a particular number rangeobject, with their number range intervals.After return, the return code chosen by the user (%DFN�or &DQFHO) is available.

• 180%(5B5$1*(B(/(0(176B6+2:� This function module displays all elements, which are assigned to a number rangeinterval.After return, the return code chosen by the user (%DFN�or &DQFHO) is available.

• 180%(5B5$1*(B,17(59$/B0$,17$,1With this function module the maintenance dialog for number range intervals for agiven number range object is offered. A parameter specifies the processing type.Possible processing types are:

- Maintain intervals

- Change number status

- Display intervals

- Create new groups (only for object types 2 and 3 and 5-8)

The dialog path is determined by the object type.After return, the return code chosen by the user (%DFN�or &DQFHO) is available.

• 180%(5B5$1*(B*5283B0$,17$,1� This function module is the maintenance dialog (Create, Change, Display) for numberrange groups for a given number range object. A processing flag determines whetherthe object is to be displayed only or whether it can be maintained. Groups are deletedby deleting their intervals.After return, the return code chosen by the user (%DFN�or &DQFHO) is available.

• 180%(5B5$1*(B68%2%-(&7B&23<�(only object types 4-8)This function module enables you to copy number range objects from groups andintervals of an existing sub-object of a given number range object to another of itsexisting sub-objects.After return, the return code chosen by the user (%DFN�or &DQFHO) is available.

• 180%(5B5$1*(B68%2%-(&7B*(7�(only object types 4-8)This function module provides a dialog box in which the user can enter a sub-objectfor a given number range object. If the specified sub-object already exists for thenumber range object, it is returned in the export parameter. If it does not exist, eitheran exception is raised or the return code "A" for user abort is returned.


1XPEHU�UDQJH�DQG�JURXS�UHDG�DQG�PDLQWDLQ�VHUYLFHV

-XQH��



The function modules in this group perform all number range, number range interval and groupread and maintenance database accesses.

Function modules marked with " " can only be used for the object types 2 and 3and 5-8 (see illustration in number range object types).

• 180%(5B5$1*(B(148(8(With this function module, you lock the number range object which is to bemaintained, and its groups and intervals, for access by other users. Lock errors arereturned as exceptions.

• 180%(5B5$1*(B'(48(8(With this function module, you unlock the number range object which has beenmaintained.

• 180%(5B5$1*(B(/(0(17B/,67� This function module gets the elements which are assigned to a particular numberrange interval for a number range object. The elements found are passed in a table.Errors are returned as exceptions.

• 180%(5B5$1*(B(/(0(17B7(;7B/,67� With this function module you can find element texts in the specified language for agiven number range object. The texts are returned in a table. Execution errors arereturned as exceptions.

• 180%(5B5$1*(B*5283B/,67� This function module gets information about groups and the associated group andelement texts for a specified number range object. The information is put in a table.The table can be used to change the element assignment or the group text. Thechange request is to be passed to the function moduleNUMBER_RANGE_GROUP_UPDATE.Errors are returned as exceptions.

• 180%(5B5$1*(B*5283B83'$7(� With this function module, already assigned elements can be assigned to otherintervals, or the assignment can be withdrawn. Group texts can also be maintained.All change requests are checked. Request errors are returned in an error table.

The changes are passed in an internal table and are copied into the local memory ofthe function group.Before you call this function module, you must lock the number range object inquestion with NUMBER_RANGE_ENQUEUE, and unlock it again withNUMBER_RANGE_DEQUEUE after writing the changes to the database.To copy the contents of local memory to the database, call the function moduleNUMBER_RANGE_UPDATE_CLOSE.

• 180%(5B5$1*(B,17(59$/B/,67This function module gets the existing intervals to a given number range object, andputs them in a table. The table can be passed to the function moduleNUMBER_RANGE_INTERVAL_UPDATE to change intervals.



�� -XQH��

• 180%(5B5$1*(B,17(59$/B83'$7(With this function module you maintain intervals for a given number range object.The changes are passed in an internal table, and are copied into local memory.Before you call this function module, you must lock the number range object inquestion with NUMBER_RANGE_ENQUEUE, and unlock it again withNUMBER_RANGE_DEQUEUE, after the changes have been written to the database.To copy the contents of local memory to the database, call the function moduleNUMBER_RANGE_UPDATE_CLOSE.

• 180%(5B5$1*(B2%-(&7B*(7B,1)2This function module gets information for a given number range object. Thisinformation is put in a table structure, which must be declared like the table structureINROI.

• 180%(5B5$1*(B68%2%-(&7B/,67 (only object types 4-8)This function module gets the existing sub-objects of a given number range object,and puts them in the table passed.

• 180%(5B5$1*(B68%2%-B*(7B,1)2This function module gets information about the existing sub-objects of a givennumber range object. This information is put in a table structure, which must bedeclared like the table structure INROI.

• 180%(5B5$1*(B83'$7(B&/26(With this function module you write changes which have been made to local memoryto the database, with NUMBER_RANGE_GROUP_UPDATE andNUMBER_RANGE_INTERVAL_UPDATE. After calling this function module, youshould unlock the changed number range object.

• 180%(5B5$1*(B83'$7(B,1,7With this function module, you can initialize local memory if you want to discard thechanges which have not yet been copied to the database.


1XPEHU�UDQJH�REMHFW�UHDG�DQG�PDLQWDLQ�VHUYLFHV

-XQH��

1XPEHU�UDQJH�REMHFW�UHDG�DQG�PDLQWDLQ�VHUYLFHV


The function modules in this group perform all read and maintenance accesses to number rangeobjects in the database.

• 180%(5B5$1*(B2%-(&7B0$,17$,1This function module provides all the screens needed to maintain a given numberrange object, with the possibility of branching to interval maintenance and changedocument display.An export parameter states which action the user has performed with the numberrange object.

• 180%(5B5$1*(B2%-(&7B&/26(With this function module, you write all changes to a given number range object,which were put in local memory with NUMBER_RANGE_OBJECT_UPDATE, to thedatabase. If intervals are affected by the changes, they are updated. Changedocuments are created for all changes. A flag states whether intervals have beenupdated.

• 180%(5B5$1*(B2%-(&7B'(/(7(With this function module, you can delete either the whole definition of a givennumber range object, including texts, or only the texts. The deletion is performeddirectly in the database.The function module provides no connection to the correction and transport system.

• 180%(5B5$1*(B2%-(&7B,1,7With this function module, you initialize local memory for a given number rangeobject.You only need this call when you offer number range object maintenance in a usertransaction, in which you want to provide the possibility of canceling changes whichhave not been saved.

• 180%(5B5$1*(B2%-(&7B/,67This function module gets a list of all number range objects with their texts andattributes. The information is put in a table.The contents of local memory are not taken into account.

• 180%(5B5$1*(B2%-(&7B5($'This function module gets the texts and attributes of a given number range object.The records returned can be used for changes with the function modulesNUMBER_RANGE_OBJECT_UPDATE and NUMBER_RANGE_OBJECT_DELETE.

• 180%(5B5$1*(B2%-(&7B83'$7(This function module copies new number range objects or changes to existingnumber range objects into local memory, after error checks.The function module does QRW�provide a connection to the correction and transportsystem.


1XPEHU�DVVLJQPHQW�DQG�FKHFN

�� -XQH��

1XPEHU�DVVLJQPHQW�DQG�FKHFN


The function modules in this group manage the number assignment.

• 180%(5B&+(&.You only need this function module for external number assignment. It checkswhether a number range object number lies in a specified number range interval.

• 180%(5B*(7B,1)2This function module gets information for a specified number range object numberrange interval.

• 180%(5B*(7B1(;7You need this function module for internal number assignment. It assigns the nextfree number(s) in a number range interval of a specified number range object. If thelast number in the interval has been issued, the number assignment begins againwith the first number in the interval.The return code states whether the assigned number was assigned without anyproblem, or whether it lies in the critical range.


8WLOLWLHV

-XQH��

8WLOLWLHV


• 180%(5B5$1*(B,17(59$/B,1,7With this function module you initialize all internal number range intervals of aspecified number range object or sub-object.


$UFKLYLQJ

�� -XQH��

$UFKLYLQJThis section explains how you can create a user archiving program using the ArchiveDevelopment Kit.

&RQFHSW


$'.�DV�DUFKLYLQJ�SURJUDP�GHYHORSPHQW�HQYLURQPHQW�>3DJH��@

,QWHUDFWLRQ�EHWZHHQ�3URJUDP��$'.�DQG�$UFKLYH�ILOH�>3DJH��@

$UFKLYLQJ�ZLWK�$'.�>3DJH��@

$UFKLYLQJ�REMHFW�>3DJH��@6WDQGDUG�FODVV�>3DJH��@$UFKLYLQJ�FODVVHV�>3DJH��@$UFKLYH�PDQDJHPHQW�>3DJH��@1HWZRUN�JUDSKLF�>3DJH��@$FFHVVLQJ�GDWD�REMHFWV�LQ�WKH�DUFKLYH�±�,QGH[�>3DJH��@

3URFHGXUH

'HYHORSLQJ�DUFKLYLQJ�SURJUDPV�>3DJH��@

'HILQH�DUFKLYLQJ�REMHFWV�>3DJH��@'HILQH�VWDQGDUG�FODVV�KLHUDUFKLFDO�VWUXFWXUH�>3DJH��@$UFKLYH�FXVWRPL]LQJ�>3DJH��@$VVLJQ�DUFKLYLQJ�FODVVHV�>3DJH��@'HYHORS�DUFKLYLQJ�SURJUDP�>3DJH��@6WDQGDUG�DUFKLYLQJ�SURJUDP�>3DJH��@$UFKLYLQJ�XVLQJ�DUFKLYLQJ�FODVVHV�>3DJH��@'HYHORS�GHOHWH�SURJUDP�>3DJH��@'HYHORS�UHORDG�SURJUDP�>3DJH��@'HYHORS�DQDO\VLV�SURJUDP��RSWLRQDO��>3DJH��@0DLQWDLQ�QHWZRUN�JUDSKLF�>3DJH��@&UHDWH�DQ�LQGH[�DQG�XVH�LW�WR�DFFHVV�LQGLYLGXDO�GDWD�REMHFWV�LQ�WKH�DUFKLYH�>3DJH��@

$UFKLYLQJ�FODVVHV

8VH�RI�DUFKLYLQJ�FODVVHV�>3DJH��@

'HYHORS�DUFKLYLQJ�FODVVHV�>3DJH��@

6SHFLI\�IXQFWLRQ�JURXS�>3DJH��@

'HYHORS�IXQFWLRQ�PRGXOHV�>3DJH��@

'HYHORS�)RUP�URXWLQHV�>3DJH��@

,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�ZULWLQJ�>3DJH��@


$UFKLYLQJ

-XQH��

*HW�GDWD�>3DJH��@'HOHWH�DUFKLYLQJ�FODVV�ORFDO�PHPRU\�>3DJH��@'HFODUH�D�KDQGOH�LQYDOLG�>3DJH��@,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�UHDGLQJ�>3DJH��@&RS\�GDWD�IURP�WKH�GDWD�FRQWDLQHU�>3DJH��@'HOHWH�DUFKLYHG�GDWD�>3DJH��@'LVFDUG�WKH�GDWD�IODJJHG�IRU�GHOHWH�>3DJH��@5HORDG�DUFKLYHG�GDWD�>3DJH��@'HILQH�DUFKLYLQJ�FODVV�>3DJH��@

*HQHUDWLQJ�DUFKLYLQJ�SURJUDPV

*HQHUDWH�DUFKLYLQJ�SURJUDPV�>3DJH��@

0RGHO�3URJUDPV�>3DJH��@0RGHO�ZULWH�SURJUDP�±�$5&+,9(�>3DJH��@0RGHO�GHOHWH�SURJUDP�±�'(/(7(�>3DJH��@

5HIHUHQFH

$UFKLYLQJ�IXQFWLRQV�>3DJH��@


2YHUYLHZ

�� -XQH��

2YHUYLHZArchiving compresses system data und stores it on external storage media. The archived datacan then be deleted in the system. Memory can then be re-used, and the archived data arestored safely.

Archiving is recommended in the following cases:

• WKH�GDWDEDVH�LV�RFFXSLHG�E\�PDVV�GDWD which must be stored externally

• PDVWHU�GDWD�DUH�QR�ORQJHU�UHTXLUHG

SAP provides the “$rchive 'evelopment .it” ($'.) for the realization of secure and efficientarchiving procedures, to support and simplify the development of archiving programs.

The ADK is designed to be used in Client/Server architecture. The system load is shared amongthe database and application servers. This makes efficient use of system resources.

At the same time, data localization and the provision of access function modules support objectoriented procedures, which in turn help you to keep your data consistent.

The ADK provides the interfaces, function modules, example programs and documentation whichyou need to develop your own archiving programs.

Particularities of the new archiving are:

• FRQQHFWLRQ�WR�WKH�DUFKLYH�V\VWHP

• FRPSUHVVLRQ during archiving

• the possibility of DUFKLYLQJ�ZKLOH�WKH�V\VWHP�LV�UXQQLQJ

• greater HDVH�RI�XVH

• QHWZRUN�JUDSKLF for showing object dependencies

• access to individual data objects in the archive

You can use the program RSARCH09 to copy old transaction F040 archivingprocedures.

You must identify from which archiving objects you want to copy the old controldata into the new archive management by entering the name of the archivingobject under which the control data are to be copied into the new archivemanagement, in the field 5HRUJ��YDULDQW in the table TR01 (6\VWHP�→�6HUYLFHV→ 7DEOH�PDLQWHQDQFH).

When the control data have been successfully copied, the program RSARCH09deletes the entry in table TR01, so the old archiving program can no longer beexecuted via the transaction F040.


$'.�DV�DUFKLYLQJ�SURJUDP�GHYHORSPHQW�HQYLURQPHQW

-XQH��

$'.�DV�DUFKLYLQJ�SURJUDP�GHYHORSPHQW�HQYLURQPHQWThe Archive Development Kit (ADK) supports the development of standardized archivingprograms and their delete, read, and reload programs.

The archiving function has the following components:

• Archiving object [Page 118]�and their methods

• Standard class [Page 120] (generally valid) with its methods

• Archiving classes [Page 121] (created by the user) with their methods

• Archive management [Page 123]

• Network graphic [Page 124]

• Authorization check (see Archive management [Page 123])

• Generator for Archiving programs [Page 164]

These components provide an environment in which you can develop your own archivingprogram. Example programs are also provided.

The archiving object and standard class methods are provided as function modules. You do notneed to know the technical details of the archiving procedures, as they are localized in thefunction modules. You can use all the ADK functionality because your archiving programscommunicate with these function modules.

The ADK performs many of the necessary archiving activities for you. You can develop simpleprograms very quickly using the standard class (which already exists in the system) functionmodules and appropriate control parameters.

If you want to develop more complex, object-oriented archiving programs, you should use thefunctionality provided in dedicated archiving classes provided by an expert in the area, whichcontain, and hide, all information which is specific to the data to be archived. This offers you theadvantage that you no longer need detailed knowledge of the commercial object in question,because you need not concern yourself with the technical realization. You only need to call theappropriate function modules, which then perform the technical processing for you.

The development of an archiving program is based on the definition, in the system, of anArchiving object [Page 118], in which is specified which tables comprise a commercial object.Archiving objects are complex objects of inter-dependent tables. They can contain sub-objectswhich are used repeatedly in the system, e.g. change documents.

If, in exceptional cases, archiving object data structures only become known after delivery tocustomers, it is posible to generate the required archiving programs (see Generate archivingprograms [Page 164]).


,QWHUDFWLRQ�EHWZHHQ�3URJUDP��$'.�DQG�$UFKLYH�ILOH

�� -XQH��

,QWHUDFWLRQ�EHWZHHQ�3URJUDP��$'.�DQG�$UFKLYH�ILOHThe following graphic illustrates the various R/3 system components which are involved inarchiving sessions.

'%

$%$3�� SURJUDP

$UFKLYH ILOH

PDQXDO+60

/'%

$UFKLYLQJFODVV

$UFKLYH/LQN

$UFKLYH V\VWHPZLWK WHUWLDU\ VWRUDJH PHGLD

5�� V\VWHP

'% LQWHUIDFH

$'.�

Conversion of:Codepage, record structures,number formats, for exampleDEC/HP integer conversion

HSM (Hierarchical Storage Management), e.g. HP OmniStorage manages archive files onexternal storage media as though they were a system component, independently of the mediumon which they are actually stored.


$UFKLYLQJ�ZLWK�$'.

-XQH��

$UFKLYLQJ�ZLWK�$'.The ADK archiving concept and data flow are illustrated in the following graphic.

archiving object definition

archiving object datacontainer with data packetsarchiving program

archive with alogical archivefile which canconsist ofseveralphysical files

...

..

.. .. ....

archivingobject methods

with handle

local memory

changedocuments

internaldataarea

standard class

with handle

. . .

. . .

archiving classes with handle

local memory

SAPscripttext

([SODQDWLRQV

• 7KH�DUFKLYLQJ�SURJUDP selects data to be archived in the database, according tospecified criteria, so that they can be passed to the archive file. Records can beflagged for subsequent deletion by the delete program.


$UFKLYLQJ�ZLWK�$'.

�� -XQH��

A single table field is the smallest recognizable entity in the program.

• The data object to be archived or read from the archive file is passed to a ORJLFDOGDWD�FRQWDLQHU. The archiving object standard class or archiving class methodsaccess this data container.

Table entries or archiving class data packets are the smallest recognizable entitywhen reading or writing data to the data container with the archiving or read programrespectively.

The data are passed between the data container and the archive file by the archivingobject methods.

• 7KH�DUFKLYH�ILOH contains the archived data objects of an archiving object. The size inbytes or the number of data objects is specified by a customizing setting. Any numberof data objects, up to the maximum file size, can be written.

The program accesses the archive file with archiving object function modules. Forthese function modules, a data object is the smallest recognizable unit.

If a maximum archive file size was specified in customizing, and if this size isexceeded when writing to an archive file, a new file is created. All archive files for anarchiving object in one archiving session are handled as one logical file.

,GHQWLI\LQJ�DUFKLYH�ILOHV�DQG�DUFKLYLQJ�VHVVLRQVThe archive files are identified during a program run by a number (archive handle). This numberis assigned uniquely to an archive file when it is opened, and identifies it in the program. In thisway, several archive files can be processed in a program.

The archive files are identified in the system via the archiving session number. This number isassigned by ADK, and stored in the archive management with other data, e.g. archive file(s)status.

If archive file accesses are programmed (e.g. delete or read), the ADK provides a run-time dialogbox, in which the archiving sessions which exist for the access are offered for selection. For aprogram which is to run in the background, the desired archive files can be entered in the archivemanagement, before the start.


$UFKLYLQJ�DFWLYLWLHV

-XQH��

$UFKLYLQJ�DFWLYLWLHVArchiving consists of at least two activities:

• :ULWH�WKH�GDWD�ZKLFK�LV�WR�EH�DUFKLYHG�IURP�WKH�GDWDEDVH�LQWR�WKH�DUFKLYH�ILOHThe data objects which are to be archived are written sequentially in the archive file.A data object consists of a record sequence according to the object definition. Thedata are compressed by object.

This program can generally be executed during dialog processing. The programis executed in the archive management via the action “Create archive”, always inthe background. The system looks for the next free background process,preferably on the DB server.

The data to be archived are written in archive files. The size of the files and thenumber of data objects is specified In the Archive customizing [Page 130]. If this sizeor number is reached while writing, the archive file is automatically closed and a newone is created.

• 'HOHWH�GDWD�IURP�WKH�GDWDEDVHThe program first reads the archived data in the archive file. After reading, these dataare usually deleted from the database. Sometimes only a delete flag is set, and thedeletion is carried out later.The program can then pass the archive files to the ArchiveLink, if an archiving systemis connected via ArchiveLink.In Archive customizing [Page 130] it can be specified whether the delete program isto be called automatically after closing an archive file.

Other archiving activities e.g. archiving analyses, are possible.


$UFKLYLQJ�REMHFW

�� -XQH��

$UFKLYLQJ�REMHFWIf the data for a commercial object are to be archived, you must first determine which data belongto the object, how they are to be archived and which processing options should be available. Thisdefinition is saved in the system as an archiving object.

The archiving object specifies the database tables from which archiving data are to be taken.Archiving classes, which are tailored to particular logical objects (e.g. change documents) can beused.

An accounting document with all its items, change documents and long texts is anarchiving object.

$UFKLYLQJ�REMHFW�PHWKRGV

Each archiving object automatically has certain methods which can be used by archivingprograms.

• )RU�DOO�DFFHVV�W\SHV�

– open archive file for writingARCHIVE_OPEN_FOR_WRITE

– open archive file for readingARCHIVE_OPEN_FOR_READ

– open archive file to reloadARCHIVE_OPEN_FOR_MOVE

– open archive file to deleteARCHIVE_OPEN_FOR_DELETE

These function modules return an identifying number (archive handle), with whichyou can access the associated archive file and its data container in all accessesfrom the program.

– close archive file

• )RU�ZULWH�DFFHVV�

– get new data object (initialize data container)ARCHIVE_NEW_OBJECT

– write data object from data container into archive fileARCHIVE_SAVE_OBJECT

This is the moment at which the archive class data are fetched from the databaseand written into the data container, if archiving classes are being used.

• )RU�UHDG�DFFHVV��LQFO��UHORDG��


$UFKLYLQJ�REMHFW

-XQH��

– read next data object from the archive into the data containerARCHIVE_GET_NEXT_OBJECT

• )RU�DOO�DFFHVV�W\SHV�

– close archive file(s)ARCHIVE_CLOSE_FILE

How the data is transfered from the database into the data container depends on the existence ofarchiving classes:

• $UFKLYLQJ�FODVVHV�H[LVWThe data are passed by the archiving class function modules.

• 1R�DUFKLYLQJ�FODVVHV�H[LVWThe data must first be copied into the program area using user program logic, andcan then be put in the data container using the standard class function modules.


6WDQGDUG�FODVV

�� -XQH��

6WDQGDUG�FODVVThe standard class is a set of function modules which are available to all archiving objects.These function modules perform general archiving data accesses.

The functionality includes data set read and write and simple conversions during reading, suchas changing the code page, the number format or in sentence structure. Archived data can notbe deleted from the database or reloaded with the standard class. If you use the standard classfor an archiving object, you must program such actions yourself.

This standard class is general, it must be told which archiving object it is dealing with. Thisinformation is passed in control parameters.

6WDQGDUG�FODVV�WDVNV

• Write data records for the data container

• Read data from the data container

• Automatic conversion while reading

– codepage

– number format, e.g. DEC/HP integer conversion

– simple structure changes

3UH�FRQGLWLRQV

The archiving object must be defined in the system.

:KHQ�LV�WKH�VWDQGDUG�FODVV�XVHG"

The standard class methods should always be used when no archiving class exists. It is alsoappropriate when the data in question are only used in exactly one place in the system.

If the data to be archived contain sub-objects, which are used repeatedly in the system asservice functionality, e.g. change documents, you should consider developing an archiving class.


$UFKLYLQJ�FODVVHV

-XQH��

$UFKLYLQJ�FODVVHVArchiving classes make object-oriented processing of the data to be archived possible. Theysimplify access to the data of commercial entities for the archiving.

An archiving class is a set of function modules and form routines for a commercial object, whichis usually used repeatedly as a service function in the system and is archived with the data whereit is used, rather than independently, e.g. SAPscript texts, change documents, or purchaserequisitions. It collects the data and passes it as a data packet to the data container. This datapacket can only be processed by the archiving class’ own function modules.

Because of the localization of the data, the calling program no longer needs to know theparticular data structures and hierarchies. By using archiving classes, you can easily archive dataof which you have no detailed knowledge.

The archiving classes should be created by the developer resposible for thearchiving object in question.The development of archiving classes involves an initial additional work load, butthis is recovered in simplified program development and consistent data.It is worth making sure that archiving classes are created for the data which youhave to archive.

$GYDQWDJHV

Archiving objects can be created with the archiving classes if necessary. An archiving class canbe used in any number of archiving objects. This can either be done statically, by specification inADK, or dynamically in the archiving program (by calling an ADK function module).

The archiving object “FI document”. data are copied into the data container withthe standard class. Archiving classes exist for the transfer of long text and changedocument data between the database and the data container.

The use of archiving classes has the following advantages:

• 5H�XVH without extra work

• The VLPSOH�H[WHQVLRQ�RI�WKH�DUFKLYLQJ�REMHFW with new classes

• The possibility of G\QDPLF�LQFOXVLRQ�LQ�DUFKLYLQJ�REMHFWV

• &RQVLGHUDWLRQ�RI�WKH�REMHFW�LWVHOI, not its physical data structure

• 'DWD�LQWHJULW\

• 0RGXODULW\�of the data and methods

• &HQWUDO�LPSOHPHQWDWLRQ�of archiving functionality

$UFKLYLQJ�FODVV�WDVNV

• Communicate with the archiving object function modules

• fetch complex data


$UFKLYLQJ�FODVVHV

�� -XQH��

• prepare data packets for the data container

• read archived data packets from the data container

• delete archived data in the database

• write archived data back to the database

3UH�FRQGLWLRQV

Detailed knowledge of the data structure is necessary for the development of archiving classes.

For an existing archiving class to be used, it must be assigned to the archiving object in question.There are two possibilities:

• 6WDWLF�FRQQHFWLRQA permanent assignment is made via a table entry in ADK. The function modules areconnected to the archiving object when the archive file is opened. (This is the usualtype of connection.)

• '\QDPLF�FRQQHFWLRQThe archiving class is connected by a function module call in the archiving program.This procedure is appropriate when it is only decided at run-time, e.g. by user input,with which sub-objects an archiving object is to be archived.

:KHQ�DUH�DUFKLYLQJ�FODVVHV�XVHG"

Archiving classes should be provided for complex logical objects, which must also be archived asservice functions when application data are archived. This avoids data inconsistencies.

Their use is always appropriate as soon as an archiving contains such a logical object.

Processing logic may not be covered by the standard class methods. In this case, archivingclasses must be used.

Use of archiving classes [Page 148] contains further information.


$UFKLYH�PDQDJHPHQW

-XQH��

$UFKLYH�PDQDJHPHQWPrograms which process archived or to-be-archived data, generally need a long run-time, so theymust always run in the background.

The ADK provides a management transaction with which a background job for all the archivingprograms, i.e. archive, delete, analyze and reload data, can be created. You can run thistransaction with 7RROV�→�$GPLQLVWUDWLRQ�→�$GPLQLVWUDWLRQ�→�$UFKLYLQJ.�Enter the name of thearchiving object for which you want run a program, in the initial screen and choose ENTER. Youare offered the actions which are available for this object for selection.

The action $GPLQLVWUDWLRQ is always available. You can display all archiving sessions which haveso far been carried out for this object, in a list, with this action. You can obtain the followinginformation for each archiving session from this list:

• Date, time, user

• File name and path

• Status (whether deleted or sent to archive system)

• File size in MB

0DNH�QRWHV

You can make notes about the archiving sessions, e.g. about the archive file location or otherparticularities.

$XWKRUL]DWLRQ�FKHFN

Access to the archiving object programs is controlled using an authorization object(S_ARCHIVE). The check is made by ADK when an archive file is opened for one of the followingactions:

• Write

• Delete

• Read

• Reload

The following authorizations can be assigned per archiving object and application (e.g. FI, BC):

• All authorizations:

– Write, read and reload archives

– Execute delete program

– Change mode in the archive management (notes)

• Change mode in the archive management

• Read and analyze archives and display mode in the archive management

Additional application-specific authorization checks may be made for database accesses.


1HWZRUN�JUDSKLF

�� -XQH��

1HWZRUN�JUDSKLFThe ADK enables you to display archiving object dependencies in the archiving process opticallyin a network graphic. You can see the sequence in which the data must be archived to store thedata optimally, from the hierarchical archiving object representation.

The nodes in this network graphic represent the archiving objects. A node shows the followinginformation:

• $UFKLYLQJ�REMHFW�QDPH

• $SSOLFDWLRQ�QDPH

• 6KRUW�GHVFULSWLRQ

• 'DWH�RI�WKH�ODVW�DUFKLYLQJThe colours used have the following significance:

– Greenlast archiving and delete successful

– Yellowsuccessfully archived, but not yet deleted orarchiving still running ordelete is still running ordelete cancelled

– Rednot yet archived orarchiving cancelled


$FFHVVLQJ�GDWD�REMHFWV�LQ�WKH�DUFKLYH�±�,QGH[

-XQH��

$FFHVVLQJ�GDWD�REMHFWV�LQ�WKH�DUFKLYH�±�,QGH[You can access individual data objects in the archive as well as processing complete archivessequentially for analysis or reload,.

This can be necessary or useful, for example when you have archived data objects to savespace, but you want to access them on-line.

You can create an index which creates a logical connection between the archiving object, thedata object and the archive file. This connection is made during the delete program, and requiresthat a unique value be passed to the function module ARCHIVE_NEW_OBJECT via theparameter OBJECT_ID when writing the archive. This value is used for creating the index.

The index is created in a database table. If you create an index for each archivingsession for an archiving object, this database table grows. If a million records areentered, the table occupies about 100 MB in the database, so old records, whichare no longer required, should be deleted from the table. The programRSARCH14 is provided to do this. It deletes all records which are older than aspecified date.

You determine whether an index can be created for an archiving object in the archiving objectdefinition. You can control the actual index creation with an appropriate Customizing [Page 130]entry so that the index is only filled with such entries as are actually required. You read this valuein the delete program, and call the appropriate function module if the flag is set.

5HWURVSHFWLYH�LQGH[�FUHDWLRQ

You can create the index retrospectively for an existing archive file which was written without anindex, or whose index entries have been deleted (see note above).


'HYHORSLQJ�DUFKLYLQJ�SURJUDPV

�� -XQH��

'HYHORSLQJ�DUFKLYLQJ�SURJUDPVTo develop programs for archiving application data with the ADK, proceed as follows:

1. Define archiving objects [Page 127]

2. Define standard class hierarchical structure [Page 129] (optional)

3. Customizing settings [Page 130] (optional)

4. Assign archiving classes [Page 132] (optional)

5. Program development:

– Develop archiving program [Page 133]

– Develop delete program [Page 139]

– Develop reload program [Page 141]

– Develop analysis program (optional) [Page 143]

6. Maintain network graphic [Page 145]

([DPSOHV

Example programs, which are intended to explain how the function modules work, are alsoprovided with the ADK:

• 56$5&+��Create archive files

• 56$5&+��Read archive files

• 56$5&+��Read archive data deletion files

• 56$5&+��Read archive data reload files

• 56$5&+��Generate archiving programs

• 56$5&+��Read individual data objects in the archive via an index

• 56$5&+��Create archive files using an archiving class

• 56$5&+��Delete program with archiving class

• 56$5&+��Reload program with archiving class


'HILQH�DUFKLYLQJ�REMHFWV

-XQH��

'HILQH�DUFKLYLQJ�REMHFWVCall the transaction AOBJ. A list of objects which exist in the system is displayed.

Choose the function�1HZ�HQWULHV and make the following entries:

• 2EMHFW�QDPHName of the archiving object

• 7H[WExplanatory short text

• :RUN�DUHDOrganizational category for assigning archive files

• $SSO��FRPS. (Application component)Organizational criterion for assigning archive files

The programs specified below must already exist in the system, because checksare carried out when an archiving object is created.

• :ULWH�SURJUDPName of the program which writes the archive files.

• 'HOHWH�SURJUDPName of the program which deletes the data from the database after the archivingprogram.

• 5HORDG�SURJUDP�(optional, but recommended)Name of the program with which the data can be loaded from the archive back intothe database.

• 3UHSDUDWLRQ�SURJUDP�(optional, only when absolutely necessary)Name of the program with which data are to be prepared for archiving.

• 3RVW�SURFHVVLQJ�SURJUDP�(optional, only when absolutely necessary)Name of the program with which data are to be processed after they have beenarchived. If, e.g. the data were only flagged for deletion in the delete program, theactual deletion can be done in the post-processing program.

• Flag 3UJ��JHQHUDWHG�(program generated)The program should, or may, be generated.

• Flag ,QGHSHQGHQWThe archiving should be client-independent.

• Flag (QG�GLDORJThe archiving is not to be carried out in dialog mode.

• Flag &UHDWH�,QGH[An index can be created for this archiving object (see also Accessing data objects inthe archive – Index [Page 125])The actual index creation can be controlled by a Customizing [Page 130] entry.

• +HOS�DUFK�Name of a document which contains help text for the object-specific archivingprogram.


'HILQH�DUFKLYLQJ�REMHFWV

�� -XQH��

• +HOS�GHOHWHName of a document which contains help text for the object-specific delete program.

• +HOS�UHORDGName of a document which contains help text for the object-specific reload program.

• +HOS�SUHS�If a preparation program is planned, you can enter here the document with help textfor the preparation program.

• +HOS�SRVW�SURF�If a post-processing program is planned, you can enter here the document with helptext for the post-processing program.

The help function documents are created with the documentation maintenancetransaction in the document class “TX”. You access this maintenance transactionvia 7RROV�→�$%$3��:RUNEHQFK�→�(QYLURQPHQW�→�'RFXPHQWDWLRQ. Thistransaction has its own documentation.

Save your entries and return to the initial screen of the transaction AOBJ. Your newly createdarchiving object is now contained in the list of objects which exist in the system.

You can now create further information about your archiving object by marking the line andchoosing one of the actions offered under 1DYLJDWLRQ.


'HILQH�VWDQGDUG�FODVV�KLHUDUFKLFDO�VWUXFWXUH

-XQH��

'HILQH�VWDQGDUG�FODVV�KLHUDUFKLFDO�VWUXFWXUHIn the archiving hierarchy, inter-dependent tables are described as segments in a structure. Theirdependencies must be represented in the structure of the standard class. (In the archivingclasses the structuring is achieved by means of program logic.)

To make the structure of the tables in your archiving object known, proceed as follows:

Mark the archiving object in the list in the initial screen of the transaction AOBJ, and choose�theaction 6WUXFWXUH 'HILQLWLRQ�under 1DYLJDWLRQ� You branch to the hierarchy maintenance.

Choose 1HZ�(QWULHV� and make the following entries:

• 5HFRUG�QXPEHUOrganizational numbering without any functional significance. You are recommendedto use sequential values for the sake of simplicity.

• 3DUHQW�VHJPHQWStructure name of the higher-level segment (this field remains free for the highest-level segment)

• 6HJPHQWStructure name

• 6WUXFWXUHName of the structure, if you are working with a logical database and the structurename under 6HJPHQW is a pseudonym for a real structure.

• 'R�QRW�GHOHWH�flag�(only for generated archiving programs)For a segment with this flag, the delete program is so generated that it is not deleted.

Save your entries, and return to the initial screen of the transaction AOBJ.


$UFKLYH�FXVWRPL]LQJ

�� -XQH��

$UFKLYH�FXVWRPL]LQJTo maintain the archiving control parameters for your archiving object, proceed as follows:

Mark the archiving object in the list in the initial screen of the transaction AOBJ, and choose theaction &XVWRPL]LQJ�VHWWLQJV under 1DYLJDWLRQ. You branch to the customizing maintenancescreen.

You can also maintain the customizing settings in the implementation guide: &URVV�DSSOLFDWLRQIXQFWLRQV��→�*HQHUDO�DSSOLFDWLRQ�IXQFWLRQV�→�$UFKLYLQJ��→�$GMXVW�DUFKLYLQJ�FRQWUROSDUDPHWHUV.

Both the “logical file” and the variants must be maintained per client. All other values are client-independent.

You can set the following values:

• ORJ��ILOH�QDPHLogical file name for the archive file, under which the data are stored platform-independently.

The logical file name must already exist in the system (transaction FILE or in theimplementation guide under %DVLV�→�%DVLV�JHQHUDO�→�3ODWIRUP�LQGHSHQGHQWILOHQDPH�DVVLJQPHQW.

• $UFKLYH�ILOH�VL]H

− size in MB

− maximum number of data objects

If one of these two sizes is exceeded when writing an archive file, the systemautomatically creates a new archive file:

• 'HOHWH�SURJUDP�VHWWLQJVThe archived data records in the database are usually deleted. Under certaincircumstances, however, this deletion is only logical, i.e. a delete flag is set. Thephysical deletion occurs later in a post-processing program.

– Flag: ([HFXWH�DXWRPDWLFDOO\

– Flag: &UHDWH�LQGH[ (only appears when the flag is set in the object definition)Controls whether the data object to be archived should be copied into the index.

– Commit counterThis value helps to optimize the run-time.

– Test variantSpecify the delete program variant for the test.

– Productive variantSpecify the delete program variant for the productive system.

You can maintain variants for the delete program by using the 9DULDQW�pushbuttonnext to the line.


$UFKLYH�FXVWRPL]LQJ

-XQH��

The program variants specified under 7HVW and 3URGXFWLYH are client-dependent.They PXVW�be�created�LQ�HDFK�FOLHQW�XQGHU�WKH�VDPH�QDPH��ZLWK�WKH�VDPHSDUDPHWHUV.

Save your entries, and return to the initial screen of the transaction AOBJ.


$VVLJQ�DUFKLYLQJ�FODVVHV

�� -XQH��

$VVLJQ�DUFKLYLQJ�FODVVHVIf you want to use existing archiving classes, you must tell the ADK, so that ADK finds therequired interfaces during the archiving. You can either specify this statically, if the archiving isalways to be structured in the same way, or dynamically by calling a function module in yourarchiving program (set reference), if you want to control, e.g. whether particular sub-objects areto be archived or not, by input parameters.

To specify the assignment statically, proceed as follows:

Mark the archiving object in the list in the AOBJ initial screen, and choose�the action $VVLJQ$UFKLYLQJ�FODVVHV under 1DYLJDWLRQ. You branch to the assignment maintenance screen.

Choose 1HZ�HQWULHV� and enter the desired archiving class. You can use the F4 help, which liststhe existing archiving classes in the system.

Save your inputs, and return to the initial screen of the transaction AOBJ.


'HYHORS�DUFKLYLQJ�SURJUDP

-XQH��

'HYHORS�DUFKLYLQJ�SURJUDPArchiving programs write the data to an archiving object in an archive file. These programs canbe adjusted to individual requirements. The data objects to be archived can either be fetcheddirectly in the archiving program or via a logical database.

All archiving programs have one thing in common. In the last analysis, they use the ADK functionmodules (function group ARCH), to save their data by objects in archive files. All archive fileaccess methods are covered by these function modules (see also Standard archiving program[Page 136]).

For the development of archiving programs it is also advantageous if archiving classes aredefined. These contain the program logic for the data transfer between the database and thedata container (see also Archiving using archiving classes [Page 137]). If no archiving classesexist, the archiving program must fetch the data from the database. They are passed on to thedata container via the ADK standard class.

*XLGHOLQHV

• To avoid loss of data, the archiving program must not delete any data in the databaseitself. (Deletion is performed by an independent delete program.)

• The archiving program can change the database, however, to set an archiving flag,for example. This should only happen when absolutely necessary, as every changeincreases the database load and the archiving run-time.

• The data selection should be planned carefully to minimize the system load, asarchiving programs can run in on-line mode.

Extensive documentation of all ADK function modules (function group ARCH) andtheir parameters is available in the system. You can call it up in the functionlibrary.

1. Choose the push button )XQFWLRQ�OLEUDU\ under 7RROV�→�$%$3��:RUNEHQFK.

2. Enter the name of the function module.

3. Mark the option 'RFXPHQWDWLRQ, and choose 'LVSOD\.The function module short text and all interface parameters aredisplayed.

To display the function module documentation, choose the push button )�PRG�GRF� To display parameter documentation or an exception, double-click on thecorresponding line.

)XQFWLRQ�PRGXOHV�FDOO�VHTXHQFH

1. 2SHQ�DUFKLYLQJ�±�$5&+,9(B23(1B)25B:5,7(This archiving object function module is called RQFH RQO\�IRU�HDFK�DUFKLYLQJVHVVLRQ��SHU�DUFKLYLQJ�REMHFW��and returns a unique handle which is required for allfurther archive operations. The function module performs the following tasks for thearchiving object passed:

- Check whether an archive file is to be created



�� -XQH��

- Check whether the delete program should be called in test mode

- Create a header entry in the archive management

- Include the static archiving classes

- Open the first archive file

- Write the header entry in the first archive file, e.g. information about the Dictionary(Nametab) tables involved

2. '\QDPLFDOO\�LQFOXGH�DUFKLYLQJ�FODVVHV�±�$5&+,9(B5(*,67(5B&/$66If you want to use archiving classes, and they are to be included dynamically, youmust call this function module for each archiving class, passing the handle.

- Write the information to the archive file(for the use of the following programs)

Must be called directly after ARCHIVE_OPEN_FOR_WRITE.

7KH�IROORZLQJ�VWHSV��PXVW�EH�FDOOHG�LQ�D�ORRS�IRU�DOO�GDWD�REMHFWV�ZKLFK�DUH�WR�EHDUFKLYHG�

3. *HW�QHZ�GDWD�REMHFW�±�$5&+,9(B1(:B2%-(&7You call this function module for each data object. Only then can you pass data toarchiving object function modules. The function module performs the following tasks:

- Data container initialization

- Call the archiving class initialization routines

- Pass index entry value via OBECT_ID (if required)The composition of this character string value must not be changed, and eachvalue passed must be unique (see also Create an index and use it to accessindividual data objects in the archive [Page 146]).

If you have saved a data object in the archive file with the function moduleARCHIVE_SAVE_OBJECT and you want to archive further data, you must callthis function module again.

4. &RQVWUXFW�WKH�GDWD�REMHFWCall either the standard class�function module ARCHIVE_PUT_RECORD or archivingclass function modules. These are subject to a naming convention, in which “class”represents the archiving class name: class_ARCHIVE_OBJECT.

You must decide whether the data passed should be deleted by the delete programor not. The archiving class function modules provide the parameterOBJECT_DELETE_FLAG for this purpose.The function module ARCHIVE_PUT_RECORD offers you this functionality with theparameter RECORDS_FLAGS.The archiving class function modules relieve you of the data selection and optimizedatabase access. They first collect the requests and only then access the databasewhen the function module ARCHIVE_SAVE_OBJECT is called. These functionmodules recognize the data object to which the data belong through the handle,which must be passed to the function module interfaces.



-XQH��

If you have already passed data, which you do not want to archive, call thefunction module ARCHIVE_NEW_OBJECT. It causes the passed standard classand archiving class data to be “forgotten”.

5. 6DYH�GDWD�REMHFW�LQ�DUFKLYH�ILOH�±�$5&+,9(B6$9(B2%-(&7You must call the function module ARCHIVE_SAVE_OBJECT to request the actualarchiving of a data object. It performs the following tasks:

- Get archiving class data packets

- Compress standard class data

- Collect statistics data

- Update archive management records

- Write the data object to the archive file (from the data container in which theywere stored by the archiving classes and the standard class)

- Close the archive file if it is full, and open a new one

- Call the delete program after an archive file has been closed

- Close the data container, so that no more data can be written to the datacontainer after a data object has been written to the archive file.

(QG�RI�WKH�ORRS��VWHS��

6. (QG�DUFKLYLQJ�,�±�$5&+,9(B:5,7(B67$7,67,&6With this function module, you can generate statistics about the archived data at theend of the archiving. For data records which were passed by the standard classes(ARCHIVE_PUT_RECORD), the records are listed individually.The function module performs the following tasks:

- Generate a list on which the archiving procedures are documented

7. (QG�DUFKLYLQJ�,,�±�$5&+,9(B&/26(B),/(You end the archiving by calling this function module. The handle passed becomesinvalid and can no longer be used.

This call must not be forgotten, otherwise the last (physical) archive file to beprocessed is lost, and the archiving therefore incomplete.

- Update the archive management records

- Close the current archive file

- Release the included archiving classes

- Discard current handle

- Call archive delete program (if automatic deletion is required)


6WDQGDUG�DUFKLYLQJ�SURJUDP

�� -XQH��

6WDQGDUG�DUFKLYLQJ�SURJUDPThe following illustration shows the logic of an archiving program for an archiving object withoutarchiving classes in simplified form. The archiving object ABC consists of the entity table A withtwo dependent tables B and C.

$'.'DWD %DVH

$%$3�� 3URJUDP ZLWKLQWHUQDO WDEOH

'DWD &RQWDLQHUZLWK &XUUHQW'DWD 2EMHFW

$5&+,9(B387B5(&25'

$5&+,9(B387B5(&25'

$5&+,9(B387B5(&25'

$5&+,9(B1(:B2%-(&7

5HTXHVW GDWD FRQWDLQHU

$5&+,9(B23(1B)25B:5,7(

$5&+,9(B&/26(B),/(

6HOHFW

:ULWH 'DWD 5HFRUG WR'DWD &RQWDLQHU

B

B

B

B

B

B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

:ULWH 'DWDWR $UFKLYH)LOH

$5&+,9(B6$9( B2%-(&7

$UFKLYH)LOH

$

%

&

Definition of Archiving Object ABC

A TableB TableC Table

$

%

%

%

&

&

&

&

The program opens the archive file for writing, and receives a number (archive handle) whichidentifies the file for all further data container and archive file accesses.

A new data container must be fetched for each record in the entity table $. All dependent records% and & are appended to it individually, until the data object is complete.

The complete data object is written to the archive file.

When all data objects which are to be archived have been written to the achive file, the archivefile is closed.


$UFKLYLQJ�XVLQJ�DUFKLYLQJ�FODVVHV

-XQH��

$UFKLYLQJ�XVLQJ�DUFKLYLQJ�FODVVHVThe following illustration shows the logic of an archiving program which processes archivingobject data using archiving classes, in simplified form. The archiving object consists of the entitytable A with two dependent archiving classes B and C. These archiving classes contain, in turn, ntables.

'DWDEDVH

$%$3

'DWD &RQWDLQHU

/RFDO 0HPRU\$UFKLYLQJ&ODVVHV

$5&+,9(B387B5(&25'

%B$5&+,9(B2%-(&7

$5&+,9(B&/26(B),/(ADK: B_FREE_DATA

C_FREE_DATA

ADK: B_GET_DATAC_GET_DATA

from the Data Base

&B$5&+,9(B2%-(&7

$5&+,9(B23(1B)25B:5,7(ADK: B_INIT_WRITE

C_INIT_WRITE

$5&+,9(B1(:B2%-(&7

ADK: B_RENEW_DATAC_RENEW_DATA

Write Data Record toData Container

Invoke ArchivingClass

B

B

B B B B B B B B

B B B B B B B B

$5&+,9(B6$9( B2%-(&7

$UFKLYH)LOH

$

$

%

&

.H\

.H\

'HO IO�

'HO IO�

%

%

&

&

$'.


6HOHFW

A TableB Archiving ClassC Archiving Class

When the archive file is opened, ADK calls the initialization form routines for the archivingclasses B and C. ADK determies which archiving classes must be called for the current archivingobject as follows:

• Which archiving classes belong to the archiving object is determined either staticallyin the transaction AOBJ (action $VVLJQLQJ�DUFKLYH�FODVVHV), or dynamically in theprogram, before the archive is opened.


$UFKLYLQJ�XVLQJ�DUFKLYLQJ�FODVVHV

�� -XQH��

• ADK finds the function group in which the required form routines are to be found fromthe assignment of function groups to archiving classes in the transaction AOBJ(action 'HILQH�DUFKLYLQJ�FODVVHV).

A new data container, in which the data object is constructed when writing, must first berequested for each entity table record.

The program puts a table A record in the data container and passes the key to the archivingclasses B and C, which save it in an internal table.

The program issues the command to write the data object to the archive file. The B and Crecords which depend on A are fetched from the database by the archiving classes and put in thedata container, and the complete data object is written to the archive file.

After all data objects to be archived have been written into the archive file, the archive file isclosed.

It is of course, also possible to develop an archiving program using only archivingclasses. In this case, only the selection logic of the data objects to be archivedmust be programmed in the archiving program.


'HYHORS�GHOHWH�SURJUDP

-XQH��

'HYHORS�GHOHWH�SURJUDPFor reasons of data security, the archiving program itself must not delete any data in thedatabase. The archived data must therefore be deleted in the database by a separate deleteprogram.

The delete program uses the function modules to read the archive and then deletes the data inthe database. This ensures that no data can be lost during the archiving, and makes onlinearchiving possible.

The delete programs can be adjusted to individual requirements. The data for the data objectswhich are to be deleted can be fetched either directly in the delete program, or via a logicaldatabase. The data are read object-wise from the archive files by the ADK function modules(function group ARCH).

You can specify, via control parameters in Archive customizing [Page 130], whether the deleteprogram should be called automatically, as soon as the archiving program closes an archive file,and whether the index should be updated (see also Accessing data objects in the archive – Index[Page 125] and Create an index and use it to access individual data objects in the archive [Page146]). You can also create delete program test and productive variants in archive customizing.

A delete program always only processes one archive session file. Several delete programs canrun in parallel and process one archive session file each.

*XLGHOLQHV

The delete programs must determine which data are to be deleted from the database by readingthe archive files. This guarantees that only data which have also been legibly stored in thearchives are deleted from the database.

The archiving classes’ function modules must be called to delete their data. These functionmodules do not COMMIT WORK and do not delete the data immediately, they call PERFORMON COMMIT.

The delete programs must get the value of the object counter with the function moduleARCHIVE_GET_CUSTOMIZING_DATA, which controls after how many data objects a COMMITWORK is called by the delete program.

)XQFWLRQ�PRGXOH�FDOO�VHTXHQFH

1. ,QLWLDOL]H�GHOHWH�±�$5&+,9(B23(1B)25B'(/(7(This function module is called only once, at the start of the delete program. Itperforms the following tasks:

- Open the archive file to read

- Provide a handle for the archive access

- Include all archiving classes mentioned in the archive file

- Set the status information in the archive management

- Pass the archive files to the ArchiveLink

2. 5HDG�QH[W�GDWD�REMHFW�IURP�DUFKLYH�ILOH�±�$5&+,9(B*(7B1(;7B2%-(&7As for all archive read accesses, you read the next archived data object with thisfunction module. It performs the following tasks:

- Read an archived data objects from the archive file


'HYHORS�GHOHWH�SURJUDP

�� -XQH��

- Supply the archiving classes with data packets

- Provide the data container for the standard class

This function module must be called in a loop, until no more data objects can beprovided.

3. 'HOHWH�DUFKLYHG�GDWD�LQ�WKH�GDWDEDVHThe function module ARCHIVE_DELETE_OBJECT_DATA deletes the data in thedatabase for all archiving classes for the last data object to be read withARCHIVE_GET_NEXT_OBJECT, if the OBJECT_DELETE_FLAG was set to ‘X’ inthe archiving program when the data were written. This function module musttherefore be called in the delete program only once per data object read(ARCHIVE_GET_NEXT_OBJECT).You must read the standard class data from the data object yourself und delete themin the database. Put the standard class read function module(ARCHIVE_GET_NEXT_RECORD) in a loop until the data object can provide nomore records. If your archiving program has stored information in theRECORD_FLAGS field, you can use this information in the delete program todetermine which data should actually be deleted from the database.

4. (QG�GHOHWH�±�$5&+,9(B&/26(B),/(This function module performs the following tasks:

- Close the archive file


- Discard the current handle


'HYHORS�UHORDG�SURJUDP

-XQH��

'HYHORS�UHORDG�SURJUDPA reload program must be provided for archiving objects whose archived data need to bereloaded into the database. The archived data of a complete archiving session must always beprocessed.

You can again use the ADK function modules for this purpose. They allow a selective reloadingof the data objects. Data objects which are not to be reloaded, are saved in new archive files.

Reload programs must be written with great care, because the archive of the reloaded dataobjects can no longer be accessed via the archive management. This is to avoid a duplicatearchiving of objects, and to guarantee that the R/3 system can be revised.

ADK creates a new archive file during reloading, into which the not reloaded data objects mustbe copied. The old archive file is retained, although access via the archive management is nolonger possible, therefore the reloaded data must be archived again.

)XQFWLRQ�PRGXOH�FDOOLQJ�VHTXHQFH

1. 2SHQ�UHORDG�±�$5&+,9(B23(1B)25B029(This function module passes you two handles:

- ARCHIVE_READ_HANDLEThis corresponds to the handle which is returned by the function moduleARCHIVE_OPEN_FOR_READ. You can perform all read operations with it.

- ARCHIVE_WRITE_HANDLEThis handle enables you to write data objects which are not to be written back tothe database into a new archive. You can therefore only call the function moduleARCHIVE_SAVE_OBJECT with this handle.

The function module performs the following tasks:

- Open the existing archive for read

- Open a new archive for write

- Create a header entry in the archive management

- Include the archiving classes of the current archive

You can use the function module ARCHIVE_GET_CUSTOMIZING_DATA, to use thesame commit counter for the reload program as that which must also be used for thedelete program.

Both function modules are called only once, at the start of the reload program.

7KH�VWHSV��DQG��PXVW�EH�FDOOHG�LQ�D�ORRS�IRU�DOO�DUFKLYHG�GDWD�REMHFWV�

2. 5HDG�DUFKLYHG�GDWD�REMHFW�IURP�DUFKLYH�ILOH�±�$5&+,9(B*(7B1(;7B2%-(&7As for all archive read accesses, you read the next archived data object with thisfunction module. You must use the ARCHIVE_READ_HANDLE for this. The functionmodule performs the following tasks:

- Read an archived data object from the archive file

- Supply the archiving classes with data packets

- Provide the data container for the standard class

- Pass the archived data objects to the WRITE_HANDLE data container


'HYHORS�UHORDG�SURJUDP

�� -XQH��

This function module must be called in a loop, until the archive file can notprovide any more data objects.

3. 5HORDG�DUFKLYHG�GDWD�LQWR�WKH�GDWDEDVHThe data of all archiving classes of the last data object read in byARCHIVE_GET_NEXT_OBJECT are reloaded into the database by the functionmodule ARCHIVE_RELOAD_OBJECT_DATA. This function module must thereforebe called only once per data object read in (ARCHIVE_GET_NEXT_OBJECT) in thereload program.You must program the reloading of the standard class data into the databaseyourself.

If the last data object read is not to be reloaded, you must transfer it into the newarchive file with ARCHIVE_SAVE_OBJECT. Otherwise you lose data, as you can nolonger access the old archive file via the archive management.

:LWK�WKLV�FDOO��VWHS��\RX�HQG�WKH�ORRS��DIWHU�DOO�DUFKLYH�ILOH�GDWD�REMHFWV�KDYH�EHHQSURFHVVHG

4. (QG�UHORDG�±�$5&+,9(B&/26(B),/(With this function module you end the reload procedure. It performs the followingtasks:

- Close the archive file

- Update the archive management records



You only need to pass one of the two handle with the call. The archiving objectknows automatically which second handle belongs to it.


'HYHORS�DQDO\VLV�SURJUDP��RSWLRQDO�

-XQH��

'HYHORS�DQDO\VLV�SURJUDP��RSWLRQDO�If you want to analyze the archived data, you can develop an analysis program to read thearchive, with the function modules.

The archiving classes offer you function modules with which you can access the archivingclasses’ archived data as though they were still in the database. There is one restriction: you cannot access all the data in an archiving file at the same time. You can only access the last dataobject to be read. Interactive reporting using archived data therefore requires some extra effort.

The following illustration shows how a read or analysis program can access archived data.

$'.

'DWDEDVH

$%$3�� 3URJUDP ZLWK,QWHUQDO 7DEOHV

'DWD &RQWDLQHUZLWK &XUUHQW'DWD 2EMHFW

$5&+,9(B*(7B1(;7B5(&25'

$5&+,9(B*(7B1(;7B5(&25'

$5&+,9(B*(7B1(;7B5(&25'

$5&+,9(B23(1B)25B5($'

$5&+,9(B&/26(B),/(

5HDG 'DWD 5HFRUG IURP'DWD &RQWDLQHU

B

B

B

B

B

B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

B B B B B B B B

5HDG 'DWD2EMHFW IURP$UFKLYH )LOH

$5&+,9(B*(7B1(;7 B2%-(&7

$UFKLYH)LOH

$

%

&


A TableB TableC Table

$

%

%

%

&

&

The program opens the archive file for reading. Each record in the entity table is read incompletely from the archive file into the data container.

From there the program reads the records individually into its internal table.

The analysis is performed when all data objects have been read in from the archive.

The archive file is closed again.


'HYHORS�DQDO\VLV�SURJUDP��RSWLRQDO�

�� -XQH��

)XQFWLRQ�PRGXOH�FDOOLQJ�VHTXHQFH

1. 2SHQ�DUFKLYH�IRU�UHDG�±�$5&+,9(B23(1B)25B5($'This function module returns the handle ARCHIVE_READ_HANDLE for performingread operations.

The function module performs the following tasks:

- Open the existing archive for read

- Include the archiving classes of the existing archive

Both function modules are called only once at the start of the reload program.

2. 5HDG�QH[W�GDWD�REMHFW�±�$5&+,9B*(7B1(;7B2%-(&7Call this function module in a loop for all data objects in the archive file.With this function module you read the opened archive file’s data objects sequentiallyinto the data container.

3. 5HDG�WKH�QH[W�GDWD�REMHFW�UHFRUG

� $5&+,9(B*(7B1(;7B5(&25'�(standard class)Call this function module in a loop for all the standard class records of the lastdata object to be read.With this function module you read the current data object’s next standard classdata record into the data container for further processing in the program. The firstcall for a data object automatically reads the first record.

- $UFKLYLQJ�FODVV�IXQFWLRQ�PRGXOHV(These are not subject to a naming convention, and must therefore be specified)With these function modules, you read the archiving class data into the datacontainer for further processing in the program.

4. (QG�DQDO\VLV�±�$5&+,9(B&/26(B),/(With this function module, you end the analysis. It performs the following tasks:

- Close the archive files




0DLQWDLQ�QHWZRUN�JUDSKLF

-XQH��

0DLQWDLQ�QHWZRUN�JUDSKLFIf your archiving object depends on other applications, you must provide the network graphic withthe necessary data. Proceed as follows:

Call the transaction AOBJ. You receive a list of the existing archiving objects in the system.

If your archiving object has predecessors which must be archived first, proceed as follows:

1. Mark your archiving object and choose�the action 0DLQWDLQ�QHWZRUN�JUDSKLF under1DYLJDWLRQ.You may have to scroll in the navigation area to find the desired action.

2. Choose 1HZ�HQWULHV.

3. Enter the object or objects whose data must be archived immediately before those ofyour archiving object.

4. Save your entries and return to the initial screen of the transaction AOBJ.

If the archiving of data for your archiving object is a pre-condition for the archiving of other data inthe system, i.e. when your archiving object is the predecessor of other objects:

1. Mark the successor archiving object in the object list in the initial screen of thetransaction AOBJ, and choose�the action 0DLQWDLQ�QHZRUN�JUDSKLF under 1DYLJDWLRQ.You may have to scroll in the navigation area to find the desired action.


3. Enter the name of your archiving object.

4. Save your entries, and return to the initial screen of the transaction AOBJ.

5. Continue for all archiving objects for which your object is the predecessor.


&UHDWH�DQ�LQGH[�DQG�XVH�LW�WR�DFFHVV�LQGLYLGXDO�GDWD�REMHFWV�LQ�WKH�DUFKLYH

�� -XQH��

&UHDWH�DQ�LQGH[�DQG�XVH�LW�WR�DFFHVV�LQGLYLGXDO�GDWDREMHFWV�LQ�WKH�DUFKLYHThe index is usually maintained by the delete program during the archiving processes, but it canalso be done retrospectively for already existing archive files.

The following conditions must be satisfied:

– The &UHDWH�LQGH[�flag is set in the Definition of the Archiving object [Page127].

– a unique value was passed for the function moduleARCHIVE_NEW_OBJECT parameter OBJECT_ID when writing thearchive. This value is used for creating the index.

&UHDWH�LQGH[�LQ�GHOHWH�SURJUDP

The index entry is written by calling the function module ARCHIVE_ADMIN_SAVE_INDEX afteryou have read the data object from the archive file for deletion. You pass the name of thearchiving object, the index entry and the archive file key, which you have previously fetched withthe function module ARCHIVE_GET_INFORMATION to this function module. You can consultthe example program RSARCH06 for the technical implementation.

The index entry format is unconstrained. You pass a character string which you have constructedas required. It is, of course, necessary, that the character string composition remains constant.

The value of this character string can be passed, with the parameter OBJECT_ID to the archivefile when the archive is written, and is copied from the archive file when the function moduleARCHIVE_GET_NEXT_OBJECT is called.

You should get the value for MAINTAIN_INDEX with the function moduleARCHIVE_GET_CUSTOMIZING_DATA before calling the function module forsaving the index entry (ARCHIVE_ADMIN_SAVE_INDEX), to make the indexcreation externally controllable and thus avoid unnecessary entries.

This value is maintained for the archiving object in question in Archivecustomizing [Page 130] before any archiving session.

&RQVWUXFW�LQGH[�UHWURVSHFWLYHO\

You can enter the archived data objects for individual archiving sessions for an archiving objectretrospectively in the index with the program RSARCH15. Proceed as follows:

1. Execute the program RSARCH15. An input field for the archiving object nameappears.

2. Enter the name of the archiving object whose index you want to maintain, andexecute the program. A list of all archiving sessions which have been performed forthis archiving object appears in a dialog box.

3. Mark an archiving session, and choose &RQWLQXH (tick icon). The data objectscontained in the chosen archiving session are entered into the index.


&UHDWH�DQ�LQGH[�DQG�XVH�LW�WR�DFFHVV�LQGLYLGXDO�GDWD�REMHFWV�LQ�WKH�DUFKLYH

-XQH��

$FFHVV�LQGLYLGXDO�GDWD�REMHFWV�XVLQJ�DQ�LQGH[

Individual data objects in an archive file are accessed using an index by the function moduleARCHIVE_READ_OBJECT. You pass the archiving object name and the index entry. ADKopens the file containing the data object being sought and reads the data object into the datacontainer.

The index must have been created, either when writing the archive orsubsequently.

You receive the archive handle to the opened archiving file, and can now access the individualdatasets in the data container either with the standard class methods(ARCHIVE_GET_NEXT_RECORD) or, if the archiving object uses archiving classes, with thoseof the archiving class.

An example of access using an index is the program RSARCH13.


8VH�RI�DUFKLYLQJ�FODVVHV

�� -XQH��

8VH�RI�DUFKLYLQJ�FODVVHVFor data which represent a commercial object, you should then create an archiving class whenyou can answer one of the following questions with “Yes”:

• Are the data used repeatedly in the system in the same form, and are they alsoarchived in the various contexts?

• Should my data structures be used and archived by other applications?

$UFKLYLQJ�FODVV�VHUYLFHVArchiving classes offer the following services:

• Function module for�ZULWLQJ�DUFKLYHV

• Function module for�UHDGLQJ�DUFKLYHG�GDWD

• Possibly function modules for�FRQYHUWLQJ�DUFKLYHV

• $XWRPDWLF�FRQYHUVLRQ�ZKHQ�UHDGLQJ�DUFKLYHV

– Codepage adjustment

– Number format adjustment

– Change record structure

All archiving class function module interfaces contain the parameterARCHIVE_HANDLE.

)XQFWLRQ�PRGXOHVEvery archiving class must provide a function module, with which an archiving program can makethe data to be archived for a class known. This function module is subject to a namingconvention. It must begin with the archiving class name, and end with “_ARCHIVE_OBJECT”.

$UFKLYLQJ�FODVV )XQFWLRQ�PRGXOH

Change documents CHANGEDOCU_ARCHIVE_OBJECTSAPscript texts TEXT_ARCHIVE_OBJECT

The function module interface is individually adjusted for the requirements of the data to bearchived. There are however two parameters which occur in every function module of this type:

• ARCHIVE_HANDLEArchiving session handle

• OBJECT_DELETE_FLAGDelete flag for the data to be archived by the archiving class

A IXQFWLRQ�PRGXOH�IRU�UHDGLQJ archived data is usually additionally provided for analysisprograms. This function module is not subject to a naming convention; it is never called directlyby ADK. This function module may be able to read in the database and in the archive file.


8VH�RI�DUFKLYLQJ�FODVVHV

-XQH��

This is controlled by the parameter ARCHIVE_HANDLE. If the value “0” is passedfor the ARCHIVE_HANDLE, the function module reads in the database, otherwiseit reads in the archive file belonging to the archive handle.

Thi archiving class receives the data to read via a form routine which is called when the functionmodule ARCHIVE_GET_NEXT_OBJECT is called by ADK.

$'.�LQWHUIDFHThe archiving class function group contains standardized form routines which ADK always thenneeds when function modules of the archiving object are called.


'HYHORS�DUFKLYLQJ�FODVVHV

�� -XQH��

'HYHORS�DUFKLYLQJ�FODVVHVTo create an archiving class, proceed as follows:

1. Specify function group [Page 151]

2. Develop function modules [Page 152]

3. Develop Form routines [Page 153]

4. Define archiving class [Page 163]

An example of an archiving class is the function group SFIL, which you can find in the system.

As an archiving class can be included in various archiving objects, and severalarchiving sessions could be processed in an archiving program, several datapackets (of an archiving class) must be able to be processed at the same time insuch a case. This makes higher demands at the same time on the internalmemory organization of the function group.


6SHFLI\�IXQFWLRQ�JURXS

-XQH��

6SHFLI\�IXQFWLRQ�JURXSYou can use an existing function group for your archiving class. It has no functional significancewhich function modules it contains in addition to the archiving classes. ADK recognizes thearchiving class form routines from the naming convention.

You can, however, also create your own function group for your archiving class, if this, e.g.provides clarity.

You can, for example also use an existing function module, adjusted as necessary, for reading inthe database.

Whether you put the archiving class function modules in the same function group as the readfunction module is up to you. The change document archiving class, for example, has beengiven a new function group, but the SAPscript archiving class has not. The interfaces of theexisting function modules for reading the change documents were extended, and theycommunicate internally with the new function group to read the desired data. If the parameterARCHIVE_HANDLE is passed with the initial value "0", these function modules read directly fromthe database.


'HYHORS�IXQFWLRQ�PRGXOHV

�� -XQH��

'HYHORS�IXQFWLRQ�PRGXOHVSpecify which services you want to provide with your archiving class. A write function modulemust always be provided. It is also useful to provide a read function module for analysisprograms.

Reloading data is only necessary in exceptional cases, so it is only necessary in particularcircumstances to provide this functionality.

'HFODUH�JOREDO�GDWD

First describe the required data and structures in INCLUDE LxxxxTOP. Bear in mind that thearchiving class can be called by several programs at the same time and you must therefore beable to administer instances. The instances are distinguished by the identifying number (archivehandle) and the object key.

)XQFWLRQ�PRGXOH�FODVVB$5&+,9(B2%-(&7

This function module is subject to a naming convention where “class” is the archiving class namein the object definition. It must receive the archive handle and the key for the data to be archivedin the interface.

You are responsible for how the class “remembers” the data. It is advisable to only “remember”the data key initially. The key could, e.g. be saved in an internal table defined in the mainprogram. You only need to provide the data to the data object when the form routineclass_GET_DATA is called by the ADK function module ARCHIVE_SAVE_OBJECT. You arerecommended to use array operations for this.

The class must “remember” the data until the form routine class_FREE_DATA (byARCHIVE_CLOSE_FILE) or class_RENEW_DATA (by ARCHIVE_NEW_OBJECT) is called bythe ADK function modules.

5HDG�IXQFWLRQ�PRGXOH

This function module is not subject to a naming convention, as it is only called directly from theprogram (not from ADK). If you have already developed a database read function module, youcan use it here. You must just extend it by one parameter, via which you specify whether the dataare to be read from the database or from the archive.

A function module for reading the data of an archiving class in the database for normalapplications already exists. You therefore need not necessarily create a new function module,you can use the existing one if you extend it appropriately. The extension must include aparameter with which the handle can be passed. This parameter must always be calledARCHIVE_HANDLE. The handle specifies whether the function module is used for a normaldatabase read, or for archiving. If the handle is passed with the initial value “0”, the functionmodule reads directly in the database, otherwise it takes the data from the data packet in its localmemory.


'HYHORS�)RUP�URXWLQHV

-XQH��

'HYHORS�)RUP�URXWLQHVADK requires class-specific form routines for controlling the communication between thearchiving class and the archive. You must provide these form routines in the archiving class(LxxxxFnn) function group.

ADK needs these form routines whenever an archiving object method is called by the program.

• ARCHIVE_OPEN_FOR_READ or WRITE

– class_INIT_WRITEInitialize the archiving class for writing (pass the archive handle)

– class_INIT_READInitialize the archiving class for reading

• ARCHIVE_NEW_OBJECT

– class_RENEW_DATAInitialize the archiving class for a new data object

This routine discards the current archiving class key when writing, or all the data ifreading the archive.

• ARCHIVE_SAVE_OBJECT

– class_GET_DATA (“GET“ from the ADK perspective)Provide data in data container for archiving

• ARCHIVE_CLOSE_FILE

– class_FREE_DATADeclare an archive handle invalid when closing an archive

• ARCHIVE_GET_NEXT_OBJECT

– class_PUT_DATA (“PUT“ from the ADK perspective)Copy data from the data container after reading the archive

• ARCHIVE_DELETE_OBJECT_DATA

– class_DELETE_ARCHIVE_OBJDelete the data contained in the data container in the database

To avoid data inconsistencies, this routine calls another routine, in which the dataare actually deleted in the database according to global internal tables provided,with PERFORM ON COMMIT.

• ARCHIVE_ROLLBACK_WORK

– class_ROLLBACK_WORKDiscard the data which are flagged for deletion in the database by the archivingclass

• ARCHIVE_RELOAD_OBJECT_DATA

– class_ARCHIVE_RELOAD_OBJReload the data in the data container into the database


,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�ZULWLQJ

�� -XQH��

,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�ZULWLQJThe name of this form routine starts with the name of the archiving class, and ends with"_INIT_WRITE".

7DVNV

This form routine initializes the archiving class for archiving data.

The classes are informed by this routine that archiving methods must be provided for this$5&+,9(B+$1'/(. The archiving classes can pass a data packet to the archiving via aninternal table, which they get back when the archive is read by the class_INIT_READ routine.This table must have been compressed via the function module 7$%/(B&2035(66� or beempty.

Several archives can have been opened for an archiving class. The archiving class receives aunique $5&+,9(B+$1'/( for each opened archive.

:KHQ�FDOOHG

This routine is called by the archiving whenever a new archive file is opened for writing. Asseveral archive files can be created in one archiving session, this routine is called for eacharchive file. The $5&+,9(B+$1'/( remains the same.

,QWHUIDFH

FORM class_INIT_WRITE TABLES INIT_TABUSING HANDLECHANGING LEN.

3DUDPHWHUV

The parameter ,1,7B7$% indicates the table in which the archiving class can save data which itneeds for initialization when it reads the archive, and which should be valid for all the dataobjects in an archive file. Control data can, for example be stored there, so that the appropriatecontrol data are used when the archive is subsequently analyzed, rather than the current valuesat that time.

The parameter +$1'/( contains the ARCHIVE_HANDLE for which the initialization should run.The archiving class function modules should note that only write operations are allowed with thishandle and must refuse all other calls by raising the exceptionWRONG_ACCESS_TO_ARCHIVE.

The result of the compression by the function module TABLE_COMPRESS is passed to thearchiving via the parameter /(1. The function module parameter is calledCOMPRESSED_SIZE.

You can register further archiving classes which you want to use in your archiving class in thisroutine (ARCHIVE_REGISTER_CLASS).


*HW�GDWD

-XQH��

*HW�GDWDThe name of this form routine starts with the name of the archiving class, and ends with"_GET_DATA".

7DVNV

This routine gathers the data which the archiving program has requested for archiving a dataobject. These data are passed via a table, which must be in compressed form.

It is recommended to get the data in this routine rather than in the function moduleclass_ARCHIVE_OBJECT, as the archiving program requests can be collected by the functionmodule and be efficiently processed in this routine. An archiving program can also request datafor archiving, but discard them later by calling the function module ARCHIVE_NEW_OBJECTbefore they are saved in the archive.

:KHQ�FDOOHG

The archiving calls this routine whenever the function module ARCHIVE_SAVE_OBJECT iscalled in the archiving program for an ARCHIVE_HANDLE.

,QWHUIDFH

FORM class_GET_DATA TABLES DATA_TABLEUSING HANDLECHANGING LEN.

3DUDPHWHUV

The data packet of the data object which is to be written is passed to the data object in the formof a compressed table via the parameter '$7$B7$%/(. The compression must have beenperformed by the function module TABLE_COMPRESS.

The parameter +$1'/( contains the $5&+,9(B+$1'/(, for which the data packet wasrequested.

The result of the compression by the function module TABLE_COMPRESS is passed to thearchiving via the parameter /(1. The function module parameter is calledCOMPRESSED_SIZE.


'HOHWH�DUFKLYLQJ�FODVV�ORFDO�PHPRU\

�� -XQH��

'HOHWH�DUFKLYLQJ�FODVV�ORFDO�PHPRU\The name of this form routine starts with the name of the archiving class, and ends with"_RENEW_DATA".

7DVNV

This routine discards all the data of an archiving class for the current data object by deleting itfrom the archiving class memory. This task must be performed when data for a new data objectare expected.

:KHQ�FDOOHG

This routine is called at two different events:

• The archiving program has called the function module ARCHIVE_NEW_OBJECT.

• The program which reads an archive file has called the function moduleARCHIVE_GET_NEXT_OBJECT. This routine is then called before the routineclass_PUT_DATA.

,QWHUIDFH

FORM class_RENEW_DATA USING HANDLE.

3DUDPHWHUV

The parameter +$1'/( contains the ARCHIVE_HANDLE for which the routine was called.


'HFODUH�D�KDQGOH�LQYDOLG

-XQH��

'HFODUH�D�KDQGOH�LQYDOLGThe name of this form routine starts with the name of the archiving class, and ends with"_FREE_DATA".

7DVNV

This is a house-keeping routine. All handle information which is passed via the interface, can bedeleted from the function group memory. No more calls are made to this handle. If a programcalls the function modules of the archiving class with this handle, after this routine has beencalled by the archiving, the function module is to raise the exception:521*B$&&(66B72B$5&+,9(.

:KHQ�FDOOHG

This routine is called whenever an $5&+,9(B+$1'/( becomes invalid. An$5&+,9(B+$1'/( becomes invalid whenever the function module ARCHIVE_CLOSE_FILE iscalled for this handle.

,QWHUIDFH

FORM class_FREE_DATA USING HANDLE.

3DUDPHWHUV

The parameter +$1'/( contains the ARCHIVE_HANDLE which is to be declared invalid.


,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�UHDGLQJ

�� -XQH��

,QLWLDOL]H�WKH�DUFKLYLQJ�FODVV�IRU�UHDGLQJThe name of this form routine starts with the name of the archiving class and ends with"_INIT_READ".

7DVNV

This form routine initializes the archiving class for reading from archives.

The classes are informed that methods must be provided for reading archived data for thisARCHIVE_HANDLE.

Several different archives can be opened for an archiving class. The archiving class receives aunique ARCHIVE_HANDLE for each archive opened.

:KHQ�FDOOHG

The archiving calls this routine whenever a new archive file is opened for reading. As severalarchive files can be read for one ARCHIVE_HANDLE, this routine is called once per archive file,but then always only for the archive file which is about to be read.

,QWHUIDFH

FORM class_INIT_READ TABLES INIT_TABUSING HANDLERELEASE_NUMBERCODE_PAGENUMBER_FORMATDATE.

3DUDPHWHUV

The parameter ,1,7B7$% indicates the table in which the archiving class stored data duringclass_INIT_WRITE, which it needs for the read initialization of the archive, and which should bevalid for all the data objects in an archive file. Control data can, for example be stored there, sothat the appropriate control data are used when the archive is subsequently analyzed, rather thanthe current values at that time.

The parameter +$1'/( contains the ARCHIVE_HANDLE for which the initialization should run.The archiving class function modules should note that only write operations are allowed with thishandle and must refuse all other calls by raising the exceptionWRONG_ACCESS_TO_ARCHIVE.

The parameter 5(/($6(B180%(5 contains the R/3 system release number at the time whenthe archive was written.

The parameter &2'(B3$*( contains the name of the codepage which was active at the timethat the archive was written. You can use this parameter, to adjust the data to the currentcodepage with the ABAP/4 language element TRANSLATE.

You get the number format which was valid at the time of archiving via the parameter180%(5B)250$7. You can also use this parameter for the ABAP/4 language elementTRANSLATE, to adjust the data to the current number format.

The parameter '$7(�contains the date on which the archive was written.


&RS\�GDWD�IURP�WKH�GDWD�FRQWDLQHU

-XQH��

&RS\�GDWD�IURP�WKH�GDWD�FRQWDLQHUThe name of this form routine starts with the name of the archiving class and ends with"_PUT_DATA".

7DVNV

This routine copies data from the data object, so that they can be read by the archiving classfunction modules.

:KHQ�FDOOHG

This routine is called whenever the function module ARCHIVE_GET_NEXT_OBJECT is called inthe archiving program and data for this archiving class exist in the data object.

,QWHUIDFH

FORM class_PUT_DATA TABLES DATA_TABLEUSING HANDLE.

3DUDPHWHUV

The data packet which was read from the data object is passed to the archiving class in the formof a compressed table, via the parameter '$7$B7$%/(.

The parameter +$1'/( contains the ARCHIVE_HANDLE, to which the data are passed.


'HOHWH�DUFKLYHG�GDWD

�� -XQH��

'HOHWH�DUFKLYHG�GDWDThe name of this form routine begins with the name of the archiving class and ends with"_DELETE_ARCHIVE_OBJ".

)XQFWLRQ

One of the services performed by the archiving classes is to provide a form routine which deletesthe archived data for an archiving class in the database. The archiving class decides whetherthese data are actually deleted, or whether only a reference may be deleted, thus avoidinginconsistencies.

The archiving classes automatically know which data were archived, so they do not need to begiven this information. The data which were most recently read by the function moduleARCHIVE_GET_NEXT_OBJECT, and were flagged for deletion when the archive was written,are automatically deleted.

The class receives the data to be deleted via the call of the form routine class_PUT_DATA by thearchiving. The data format corresponds exactly to the format which was passed to the archivingwith the form routine class_GET_DATA when archiving

&DOO

The form routine is called automatically by the ARCHIVE_DELETE_OBJECT_DATA functionmodule. This function module is called only once for each data object which is read byARCHIVE_GET_NEXT_OBJECT.

,QWHUIDFH

FORM class_DELETE_ARCHIVE_OBJ

USING HANDLE

3DUDPHWHUV

The interface of this form routine consists of only the parameter $5&+,9(B+$1'/(, whichspecifies the associated archiving object.

The form routine must save the data which are to be deleted in global tables, andcall a form routine with PERFORM ON COMMIT. This form routine is thenprocessed by the R/3 system when the delete program calls COMMIT WORK.The actual delete operations should then be passed to the database in this formroutine.

The R/3 system calls the form routine only once each COMMIT WORK, howeveroften this PERFORM ON COMMIT is called. If ROLLBACK WORK is called bythe function module ARCHIVE_ROLLBACK_WORK, the PERFORM does nottake place.


'LVFDUG�WKH�GDWD�IODJJHG�IRU�GHOHWH

-XQH��

'LVFDUG�WKH�GDWD�IODJJHG�IRU�GHOHWHThe name of this form routine begins with the name of the archiving class, and always ends with"_ROLLBACK_WORK".

)XQFWLRQ

The key entries of the class data, which were marked in the class_DELETE_ARCHIVE_OBJform routine, are to be discarded by this form routine.

&DOO

This routine is called by the ARCHIVE_ROLLBACK_WORK function module.

,QWHUIDFH

FORM class_ROLLBACK_WORK USING HANDLE

3DUDPHWHUV

The parameter HANDLE contains the ARCHIVE_HANDLE for which the routine was called. Thefunction module class_ROLLBACK_WORK calls the form routine for all handles.


5HORDG�DUFKLYHG�GDWD

�� -XQH��

5HORDG�DUFKLYHG�GDWDThe name of this form routine begins with the name of the archiving class, and ends with"_RELOAD_ARCHIVE_OBJ".

)XQFWLRQ

This form routine reloads archived data from the archive into the database. The archiving classknows automatically, which data were archived. and which data were deleted from the databaseby the archiving. Data can not be reloaded selectively in the archiving classes. All the data in anarchiving class, for the most recently read data object, are always reloaded.

&DOO

The form routine is called automatically by the ARCHIVE_RELOAD_OBJECT_DATA functionmodule. this function module is called only once for each data object read byARCHIVE_GET_NEXT_OBJECT.

,QWHUIDFH

FORM class_RELOAD _ARCHIVE_OBJ

USING HANDLE

3DUDPHWHUV

The interface of this form routine consists only of the parameter $5&+,9(B+$1'/(, whichspecifies the associated archiving object.

When programming the form routine, you can specify which data from thearchiving class can be reloaded, and which not. This can be useful if reloadingcertain data would cause database collisions, e.g. if the database alreadycontains data with the same key, which would be overwritten by the reload.


'HILQH�DUFKLYLQJ�FODVV

-XQH��

'HILQH�DUFKLYLQJ�FODVVYou must make known which function group contains the archiving class, so that ADK knowswhere it can find the form routines belonging to the archiving object.

Proceed as follows:

1. Call the transaction AOBJ. A list of the existing archiving objects in the system isdisplayed.

2. Mark the archiving object and choose�the action 'HILQH aUFKLYLQJ�FODVVHV�under1DYLJDWLRQ.You may have to scroll in the navigation area to be able to choose the desired action.


4. Enter the archiving class name, a short text, and the associated function group.

5. Save your entries and return to the initial screen of transaction AOBJ.


*HQHUDWH�DUFKLYLQJ�SURJUDPV

�� -XQH��

*HQHUDWH�DUFKLYLQJ�SURJUDPVArchiving programs can be generated in cases where data structures can only bedetermined on the customer site, e.g. as for conditions.

A logical database is a pre-requisite for running the generated programs. Theymust use the ADK function modules, so that the delete program can read thearchive file.

The following conditions must be satisfied:

• 'HILQLWLRQ�RI�WKH�DUFKLYLQJ�REMHFWsee Define archiving objects [Page 127]

− Specify program name

− Set the “Prog. generated” flag

• 2EMHFW�VWUXFWXUH�GHILQLWLRQThe maintenance can be performed manually (see Define standard class hierarchicalstructure [Page 129]), but you are recommended to use the function moduleARCHIVE_DEFINE_OBJECT_STRUCT. The structure must correspond to the logicaldatabases.

• 8VHU�H[LW�VSHFLILFDWLRQThe maintenance can be performed manually (transaction AOBJ, action $VVLJQ�H[LWURXWLQHV�LQ�JHQHUDWLRQ), but you are also here recommended to use the appropriatefunction module ARCHIVE_DEFINE_PROGRAM_EVENTS.

Archiving classes can only be used in connection with user exits. It is not possiblefor the generator to recognize when the archiving class function modules must becalled.


0RGHO�3URJUDPV

-XQH��

0RGHO�3URJUDPVTwo models are available to you for generating archiving programs:

• $5&+,9(for the write program

• '(/(7(for the delete program

The generated programs have the generated attribute. This attribute causes a warning to beissued when you try to edit the generated program. Manual changes to generated programs arepointless, as they are overwritten at the next generation.

The tables defined with the ABAP/4 statement TABLES are automatically placed in a globalmemory space. There is an include with the name "ARCHCOMO" for the archiving data fields,which puts them in global memory. The logical database of the program to be generated mustcontain this include.

The global fields of this include are the following:

• RECORD_FLAGSThe field specifies the archiving memory space in which control information for a dataobject record is stored.

• ARCHIVE_HANDLEThe field contains the handle of the opened archive. You can use this field in theexternal sub-routine to communicate with the archive, or with the archiving classes.

• TESTMODEThe field must be filled by the logical database. The contents of this field is passed tothe function module ARCHIVE_OPEN_FOR_WRITE parameterCREATE_ARCHIVE_FILE. If this field has the value space, no archive file is written,no delete program executed, and also no entry made in the archive management.The archiving function modules just compile statistics about the data object passed.

• DELETE_DATAThe field must be filled by the logical database. The contents of this fields is passedto the function module ARCHIVE_OPEN_FOR_WRITE parameterCALL_DELETE_JOB_IN_TEST_MODE. If this field has a value other than space, thedelete program is called, but the delete program parameter TESTRUN is given thevalue "X".

(YHQWV

The generator events are closely based on the ABAP/4 syntax, and are therefore almost all self-explanatory.

• $UFKLYLQJ�PRGHO��$5&+,9(��HYHQWV

– END-OF-SELECTION

– GET

– GET LATE

– INITIALIZATION

– START-OF-SELECTION


0RGHO�3URJUDPV

�� -XQH��

– TOP-OF-PAGE

• 'HOHWH�PRGHO��'(/(7(��HYHQWV

– AFTER DELETEdirectly after delete

– BEFORE DELETEdirectly before delete

– COMMIT WORKdirectly before a Commit


– GET

– GET LATE

– INITIALIZATION


– TOP-OF-PAGE


0RGHO�ZULWH�SURJUDP�±�$5&+,9(

-XQH��

0RGHO�ZULWH�SURJUDP�±�$5&+,9(The model "ARCHIVE" is based on the logical databases logic. All ABAP/4 event languageelements are supported. You can have external sub-routines called at any event.

The external sub-routine calls are defined via the function moduleARCHIVE_DEFINE_PROGRAM_EVENTS, or manually in the transaction AOBJ (action “$VVLJQHxit routines LQ�JHQHUDWLRQ").

The structure of the archiving object must be derived from the logical database which is to beused. The structure is defined via the function module ARCHIVE_DEFINE_OBJECT_STRUCT,or manually in the transaction AOBJ (action "6WUXFWXUH�GHILQLWLRQ").

Each record in an archiving object can contain additional information in the eight-byte fieldRECORD_FLAGS. There are no rules for the use of these eight bytes. The field is filled at theevent GET in the generated archiving programs, before any existing external sub-routines arecalled, and before the GET event dataset is passed to the data object by the function moduleARCHIVE_PUT_RECORD.

The field has the following default values, depending on the object definition,:

• “ “(SPACE) the segment is not deleted

• “X” the segment is deleted

The delete program model checks, whether the first position in the field RECORD_FLAGScontains the value "X", before this dataset is deleted. You can change the value of the field, bycalling an external sub-routine in the archiving program at the event GET.

The external sub-routine interface depends on the event at which they are called.

([WHUQDO�VXE�URXWLQH�FDOOV

• ,QWHUIDFH��

FORM formname USING ARCHIVE_HANDLE CHANGING RECORD_FLAGS.

Event:

– GET

• ,QWHUIDFH��

FORM formname USING ARCHIVE_HANDLE.

Event:


– GET LATE


– TOP-Of-PAGE

• ,QWHUIDFH��

FORM formname.

Event:

– INITIALIZATION



�� -XQH��

*HQHUDWHG�SURJUDP�SURFHVVLQJ

• INITIALIZATION

– call external sub-routine (if one exists)

• START-OF-SELECTION

– open archive for writing


• GET

– enter 'X' in field RECORD_FLAGS


– request a new data object (only for the first segment)

– pass the dataset to the data object

• GET LATE


– write data object to archive (only for the first segment)

• END-OF-SELECTION


– output archiving statistics

– close archive

• TOP-OF-PAGE


*XLGHOLQHV�IRU�WKH�ORJLFDO�GDWDEDVH�XVHG

The logical database must include ARCHCOMO.

The logical database needs special selection screens for the archiving.

The ARCHCOMO includes the fields TESTMODE and DELETE_DATA which must be filled forthe archiving program call. You can create a user selection screen, in which the user enters oneof the three meaningful combinations of the two fields per radio button:

• FUHDWH�DUFKLYH�ILOHV�DQG�GHOHWH�GDWD�ZLWK�GHOHWH�SURJUDPTESTMODE = ' '; DELETE_DATA = 'X'

• FUHDWH�DUFKLYH�ILOHV��H[HFXWH�GHOHWH�SURJUDP��EXW�GR�QRW�GHOHWHTESTMODE = ' '; DELETE_DATA = ' '

• FUHDWH�QR�DUFKLYH�ILOHV�DQG�GR�QRW�H[HFXWH�D�GHOHWH�SURJUDPTESTMODE = 'X'

The two parameters were deliberately placed on the database selection screen and not in thegenerated program, to simplify the user interface and relieve the user of needing to know thepossible combinations.

([WHUQDO�VXE�URXWLQH�JXLGHOLQHV



-XQH��

The external sub-routines should access existing archiving classes’ function modules to archivetheir data. The external sub-routine interface parameter ARCHIVE_HANDLE is available for thispurpose.

If you need the structure of the RECORD_FLAGS parameter, you can specify the structure"ARC_BUFFER-FLAGS" via STRUCTURE.


0RGHO�GHOHWH�SURJUDP�±�'(/(7(

�� -XQH��

0RGHO�GHOHWH�SURJUDP�±�'(/(7(The model "DELETE" is based on logical database logic. All ABAP/4 event language elementsare supported. You can have external sub-routines called at any event. The archive file readwhich is required for deletion must be performed by the logical databases.

The external sub-routine calls are defined by the function moduleARCHIVE_DEFINE_PROGRAM_EVENTS, or manually in the transaction AOBJ (action $VVLJQH[LW�URXWLQHV�LQ�JHQHUDWLRQ).

The structure of the archived data object must be derived from the logical database which is tobe used. The structure is defined by the function module ARCHIVE_DEFINE_OBJECT_STRUCTor manually in the transaction AOBJ (action “6WUXFWXUH�GHILQLWLRQ").

The model for the delete program checks whether the first position of the field RECORD_FLAGShas the value "X", before it deletes the dataset. You can change the value of the field by callingan external sub-routine in the delete program at the event GET.

([WHUQDO�VXE�URXWLQH�FDOOV

The external sub-routine interface depends on the event at which they are called.

• ,QWHUIDFH��

FORM formname USING ARCHIVE_HANDLE CHANGING RECORD_FLAGS.

Event:

– GET

• ,QWHUIDFH��

FORM formname USING ARCHIVE_HANDLE.

Event:

– COMMIT WORK


– GET LATE


– TOP-OF-PAGE

• ,QWHUIDFH��

FORM formname.

Event:

– INITIALIZATION

• ,QWHUIDFH��inttab contains all the records of a database table which are to be deleted

FORM formname TABLES inttab USING ARCHIVE_HANDLE.

Event:

– AFTER DELETE

– BEFORE DELETE



-XQH��

*HQHUDWHG�SURJUDP�SURFHVVLQJ

• INITIALIZATION


• START-OF-SELECTION


• GET


– collect datasets in delete table (if RECORD_FLAGS(1) = 'X')

• GET LATE


– only for the first dataset:

increment object count fieldcall delete sub-routine (if data objects were collected)

• END-OF-SELECTION

– call delete sub-routine (for remaining data)


• TOP-OF-PAGE


• Sub-routine for deleting collected data

– LOOP (per table)

– check whether datasets were collected for the table

– call external sub-routine (if BEFORE DELETE exists)

– Array operation to delete the datasets from the table

– call external sub-routine (if AFTER DELETE exists)

– delete internal collecting table

– ENDLOOP (per table)

– call external sub-routine (if COMMIT WORK exists)

– depending on whether it is a test or productive session, database Rollback orCommit respectively

/RJLFDO�GDWDEDVH�JXLGHOLQHV

The logical database must include ARCHCOMO.

The logical database needs special archiving selection screens. For the delete program, thelogical database must call the function module ARCHIVE_OPEN_FOR_DELETE to open anarchive file.

The ADK function modules must perform the read.



�� -XQH��

([WHUQDO�VXE�URXWLQH�JXLGHOLQHV

You can not COMMIT WORK in external sub-routines. In a test session, all database changesare automatically discarded in the generated program with ROLLBACK WORK. This is necessarybecause otherwise every external sub-routine used must know that it is a test session. The sameapplies for any function modules used. The use of Rollback has also the advantage that the testprograms are very realistic. A successful test thus guarantees a successful productive session.

The archiving class function modules themselves do not Commit or Rollback database changes.

The external sub-routines should use existing archiving class function modules to delete theirdata. The parameter ARCHIVE_HANDLE in the external sub-routine interface is provided for thispurpose.

If you need the structure of the RECORD_FLAGS parameter, you can specify the structure"ARC_BUFFER-FLAGS" via STRUCTURE.


$UFKLYLQJ�IXQFWLRQV

-XQH��


)XQFWLRQ�JURXS�$5&+

• $5&+,9(B$'0,1B6$9(B,1'(; (Delete program)With this function module you write an index entry for the current data object.

• $5&+,9(B&/26(B),/(With this function module, you close all archive files which are gathered under onehandle, independently of whether they were opened for reading, writing or reloading.

• $5&+,9(B'(/(7(B2%-(&7B'$7$With this function module, you call the delete routines of the archive classes for thecurrent data object.

• $5&+,9(B*(7B&86720,=,1*B'$7$This function module returns the Commit counter and the create index flag. TheCommit counter determines, after how many data objects a COMMIT WORK isissued. The create index flag specifies whether the delete program should insert thearchived and deleted data objects in the index.

• $5&+,9(B*(7B),567B5(&25' (standard class only)With this function module you set the record pointer to the first record in the datacontainer in the data object which was previously read byARCHIVE_GET_NEXT_OBJECT, and read this record.This function module combines the functionality of theARCHIVE_SET_RECORD_CURSOR and ARCHIVE_GET_NEXT_RECORD functionmodules.If you only need the fields RECORD_FLAGS and RECORD_STRUCTURE, you canuse the function module ARCHIVE_GET_RECORD_INFO.

• $5&+,9(B*(7B,1)250$7,21With this function module you get current information for a handle, such as date,release, SAP system, archive name.

• $5&+,9(B*(7B23(1B),/(6With this function module, you fill a table with the file names of all archive files whichare currently being processed by the ADK function modules.

• $5&+,9(B*(7B1(;7B2%-(&7With this function module, you read the next data object for a handle, from an archivewhich is open for reading in the data container. This call is a prerequisite for thefunction module ARCHIVE_GET_NEXT_RECORD orARCHIVE_GET_FIRST_RECORD and the archiving classes call.If you use archiving classes, their data are accessible via their function modules afterthey have been called.

• $5&+,9(B*(7B1(;7B5(&25'�(standard class only)With this function module, you sequentially read the next record in a data container ina data object which was read by ARCHIVE_GET_NEXT_OBJECT. The first callautomatically reads the first record.

The following function modules (ARCHIVE_GET_NEXT_STRUCT_SPECIF undARCHIVE_GET_RECORD_INFO) were developed for the easy implementation



�� -XQH��

of logical database archive read operations. They can, of course, also be used inother programs.

• $5&+,9(B*(7B1(;7B6758&7B63(&,)�(standard class only)With this function module you read archives with specified structures with logicaldatabases. The group change logic is integrated.You can, however, also use the function module ARCHIVE_GET_NEXT_RECORD,but in this case you must program the hierarchy step group change logic yourself.

• $5&+,9(B*(7B5(&25'B,1)2�(standard class only)With this function module, you get information in logical databases about archiveddatasets.

• $5&+,9(B*(7B7$%/(With this function module, you read several records from a data object which wasread by ARCHIVE_GET_NEXT_OBJECT, into an internal table.

• $5&+,9(B*(7B:,7+B&85625�(standard class only)With this function module, you can directly read standard class datasets in a dataobject. You get the necessary record pointer during sequential access to a dataobject record via the parameter RECORD_CURSOR.This function module is useful for ”remembering“ records via the record pointer forlater further processing.

• $5&+,9(B1(:B2%-(&7With this function module you request a new data container to write for a handle.

• $5&+,9(B23(1B)25B029(With this function module you open one or several archive files for reloading archiveddata. You receive an archive handle for the archive file to be read and anotherarchive handle for writing those data objects, which are not to be reloaded. Thisfacilitates the selective reloading of individual data objects from archives into the R/3system.

• $5&+,9(B23(1B)25B5($'With this function module you open an existing archive file for reading. A handle iscreated, via which this file can be read. You can also open several archive files at thesame time.They all share one handle.Function modules which read via this handle treat all the files with this handle like asingle file.

• $5&+,9(B23(1B)25B:5,7( With this function module you create a new archive file and a handle, with which youhave write access to this file.If you have not specified a file name in the Archive customizing [Page 130], theplatform independent logical file name ARCHIVE_DATA_FILE is automatically used,to determine a valid, platform-independent file name.You can also specify via control parameters, whether the delete program for thearchived data should be automatically called after writing.

• $5&+,9(B387B5(&25'�(standard class only)With this function module you pass a data set to the data container which waspreviously requested with the function module ARCHIVE_NEW_OBJECT.All data sets which you pass to the data container are written to the archive filetogether by the function module ARCHIVE_SAVE_OBJECT.



-XQH��

• $5&+,9(B387B7$%/( (standard class only)With this function module, you pass an internal table to the data container which waspreviously requested by ARCHIVE_NEW_OBJECT. The internal table records areentered in the data container as single records.

• $5&+,9(B5(*,67(5B&/$66With this function module, you dynamically assign archiving classes to an archivingobject.

• $5&+,9(B5(/2$'B2%-(&7B'$7$�(only for archiving classes)With this function module, you call the reload routines of the archiving classes.

• $5&+,9(B52//%$&.B:25.If a ROLLBACK WORK has to be carried out in a delete or reload program, it shouldbe done by calling this function module, not by the ABAP/4 command ROLLBACKWORK. This function module guarantees the correct resetting of the data for allarchiving classes used.

• $5&+,9(B6$9(B2%-(&7With this function module, you write a data object into the archive file. As well as thedata passed by ARCHIVE_PUT_RECORD, the data which were passed via thearchiving classes are taken into account.

• $5&+,9(B6(7B5(&25'B&85625 (standard class only)With this function module you set the standard class record pointer of the last dataobject to be read. You can then read the next record withARCHIVE_GET_NEXT_RECORD.

• $5&+,9(B:5,7(B67$7,67,&6�(standard class only)With this function module, you create a statistics print-out for the data object whichyou have written to the archive files with ARCHIVE_SAVE_OBJECT.

Documents

Apostial Function - SAP