Developing Write Programs (SAP Library - Archive Development Kit)

Developing Write Programs

Use

Write programs write the data to be archived to archive files.

Procedure

Important Information

To avoid loss of data, the write program must not delete any data in the database itself. The data is deleted by an independent delete program.

The write program can change the database, to set an archiving indicator, for example. The indicator could be used to tell other programs that the data object must not be changed. This should only happen when absolutely necessary, as every change increases the database load and the archiving runtime.

As write programs run in online operation, the data selection should not severely affect performance of the SAP system.

To update the Archive Development Kit’s (ADK) administration data, ADK sends a COMMIT (not the ABAP command COMMIT WORK ) to the database several times during the archiving process.

The function module ARCHIVE_GIVE_STATISTICS must not be called in write programs. ADK automatically collects statistics.

Program Sequence

Open archiving – ARCHIVE_OPEN_FOR_WRITE
This archiving object function module is called only once for each archiving session (per archiving object) and returns a unique archive handle, which is required for all further archive operations. When this function module is called, the initialization phase begins.

The function module performs the following tasks for the archiving object passed:

Controls whether the write program runs in test mode or production mode
Controls whether the delete program should be called in test mode
Creates a new archiving session in archive management
Includes the archiving classes set in AOBJ

Caution

The following three function modules, if used, must be called directly after ARCHIVE_OPEN_FOR_WRITE and before ARCHIVE_NEW_OBJECT is called for the first time.

(Optional) Dynamically include archiving classes – ARCHIVE_REGISTER_CLASS

If you want to use archiving classes, and they are to be included dynamically, you must call this

function module and pass the handle for each archiving class.

(Optional) Dynamically include structures and tables – ARCHIVE_REGISTER_STRUCTURES

As of SAP Web Application Server 6.10, you can use this function module to inform ADK of additional structures and tables to be archived. This is useful for tables and structures that are not known until runtime and should only be used if absolutely necessary.

(Optional) Store initialization data in archive files – ARCHIVE_PUT_INIT_DATA

As of SAP Web Application Server 6.10, you can use this function module to store initialization data in archive files. This is information the application needs to be able to later interpret the archived data and can be any type of information, such as Customizing information, status information, or the like.

To read this data in delete, read, and reload programs, you call ARCHIVE_GET_INIT_DATA. For more information, see the relevant documentation here and the function module documentation.

The following steps (5 - 8) must be called in a loop for all data objects to be archived.

Open new data object – ARCHIVE_NEW_OBJECT
You call this function module for each data object. Only then can you pass data to the ADK function modules. The function module performs the following tasks:

Initializes data container

Calls the archiving class initialization subroutines

Passes data object ID through OBJECT_ID (if required)
The composition of OBJECT_ID must not be changed, and each value passed must be unique; OBJECT_ID must syntactically be CHAR (see also Creating an ADK index and Using it to Access Individual Data Objects in the Archive).

Pass archiving object data to data container – ARCHIVE_PUT_RECORD/ARCHIVE_PUT_TABLE
For each table or structure you want to archive, call the ADK function module ARCHIVE_PUT_RECORD or ARCHIVE_PUT_TABLE.

You must decide whether the data passed should be deleted by the delete program or not. The function module ARCHIVE_PUT_RECORD provides you with the parameter RECORD_FLAGS to pass a delete indicator, so that the delete program knows which data to delete. ARCHIVE_PUT_TABLE includes the parameters RECORD_FLAGS and RECORD_FLAGS_TABLE for this.

Note

To be able to react to a problem with the data selected for archiving, you can include an IF "error" statement that continues with the next loop before executing ARCHIVE_SAVE_OBJECT. ARCHIVE_NEW_OBJECT is called again thus discarding the data already passed.

Tell archiving classes which data to archive – <CLASS>_ARCHIVE_OBJECT

You must decide whether the data passed should be deleted by the delete program or not. The archiving class function module provides the parameter OBJECT_DELETE_FLAG for this purpose. <CLASS>_ARCHIVE_OBJECT selects the data for you and optimizes database access. First it collects the keys for the requested data and only accesses the database when the function module ARCHIVE_SAVE_OBJECT is called. This function module recognizes the data object to which the data belongs through the handle that must be passed to the function module interface.

Save data object to archive file – ARCHIVE_SAVE_OBJECT
You must call the function module ARCHIVE_SAVE_OBJECT to actually save the data object to an archive file.

ARCHIVE_SAVE_OBJECT:

Gets the archiving class data and combines it with the archiving object data
Automatically collects the statistics data in both production and test modes
Locks the data container, so that no more data can be written to the data container

In production mode, ARCHIVE_SAVE_OBJECT also:

Writes the data object to the archive file from the data container in which the records were stored

Closes the archive file when it reaches the maximum size or number of objects set in Customizing, and opens a new one
Passes the archive files to the SAP Content Management Infrastructure (if the Customizing setting Store Before Deleting is set)
Calls the delete program after an archive file has been closed (if Customizing is set to automatically start the delete program after an archive file is closed)

Caution

As of SAP Web Application Server 6.10, you can interrupt and continue archiving sessions (as described in Interruption and Continuation of Archiving Sessions). As such, your write program must handle any interruption requests from ADK through the exception TERMINATION_REQUESTED.

End of the loop

(Optional) Get statistics from ADK – ARCHIVE_GET_STATISTICS

You use this function module to get the statistics ADK collected. You can then use these statistics to create your own specialized log.

(Optional) Output standard statistics log – ARCHIVE_WRITE_STATISTICS
You use this function module to output the standard archiving statistics log at the end of the write phase. This function module must be called directly before ARCHIVE_CLOSE_FILE.

End write phase – ARCHIVE_CLOSE_FILE
You end the write phase by calling this function module. The archive handle becomes invalid and can no longer be used.

Caution

This function module must be called, otherwise the last (physical) archive file to be processed is lost, and the write phase is incomplete.

ARCHIVE_CLOSE_FILE:

Releases the included archiving classes

Discards the current handle

In production mode, ARCHIVE_CLOSE_FILE also:

Updates the archive management records

Closes the current archive file

Passes the archive files to the SAP Content Management Infrastructure for the last archive file (if the Customizing setting Store Before Deleting is set)

Calls the delete program for the last archive file (if the Start automatic. indicator is set in Customizing and no events are set)

Result

When you finish developing your write program, enter it for your archiving object in transaction AOBJ.

Example

For examples of write programs, see sample programs SBOOKA and SFLIGHTA (for use of archiving classes)