Functionality
You can use function module AS_API_READ to access the data of theArchive Information System (AS). After selection criteria are passed tothe function module, the module returns the corresponding contents fromthe archive information structure, namely the archive file and theoffset. The function module AS_API_READ uses this information for theindex-based access of archived data.
This for example, allows for a quick and automatic access to the archivefrom within an application function. Without an interface to the archiveinformation system an index solution would have to be developed. Thefunction module AS_API_READ itself does not make any archive accesses.It only determines the information about where in the archive a specificdata object can be found. The actual archive accesses are then performedwith the function modules commonly used for this purpose, which belongto the Archive Development Kit (ADK), such as ARCHIVE_READ_OBJECT andARCHIVE_GET_TABLE.

Example
The following is a simple example of how the function module AS_API_READis used. In this example data objects that contain bookings of smokersfor flights on 7.9.1998 are requested. In the example the followingfield catalog, called DEMO_SBOOK is used:
Target Field,,Source Table,,Reference Field
CARRID,,SBOOK,,CARRID
CONNID,,SBOOK,,CONNID
FLDATE,,SBOOK,,FLDATE
CLASS,,SBOOK,,CLASS
BOOKID,,SBOOK,,BOOKID
SMOKER,,SBOOK,,SMOKER
Based on this field catalog we would have the following coding:
DATA: BEGIN OF g_sbook<(>,<)>
smoker LIKE sbook-smoker<(>,<)>
fldate LIKE sbook-fldate<(>,<)>
END OF g_sbook<(>,<)>
gt_result TYPE TABLE OF aind_arkey.
g_sbook-smoker = 'X'.
g_sbook-fldate = '19980907'.
CALL FUNCTION 'AS_API_READ'
EXPORTING
i_fieldcat = 'DEMO_SBOOK'
i_selections = g_sbook
IMPORTING
e_result = gt_result[].
This coding fragment has the following meaning:

• Find an infostructure for field catalog DEMO_SBOOK


• From this infostructure determine all records with SMOKER = 'X' and
FLDATE = '19980907'

• Return the archive file and the offset of the found records.

This type of access is usually sufficient for finding individualobjects, using, for example the document number.

Determining the infostructure
With function module AS_API_READ it is not possible to directly enterthe infostructure. Only the field catalog can be specified. Usually eachfield catalog only has one actively used infostructure, which means thatchoosing a corresponding infostructure is only theoreticallysignificant. It is possible, especially during development or testphases, to have several active infostructures for a particular fieldcatalog. These infostructures may have been filled for different archivefiles, meaning they could contain different data. The function moduleAS_API_READ may then choose an infostructure that does not contain therequested data, even though another active infostructure contains thedesired data. In this case the system does not return any data althoughthe desired data is actually available in the Archive InformationSystem.
Below we try to explain in more detail how the function moduleAS_API_READ determines the infostructure from which the data is to beread:
The system determines all active infostructures for field catalog(I_FIELDCAT). If no such infostructure exists the exceptionNO_INFOSTRUC_FOUND is triggered.
If something was transferred in parameter I_OBLIGATORY_FIELDS, onlythose infostructures are taken into account that contain all mandatoryfields. If no such infostructure exists the exception NO_INFOSTRUC_FOUNDis triggered.
From this point on, an active infostructure will definitely exist.However, perhaps there will be several infostructures that would fit,and the choices have to be narrowed down even more.
Only those infostructures are considered that contain the maximum numberof selection fields. This means all fields from I_SELECTIONS that arealso contained in the field catalog.
If at this point there are still several infostructures that could beused then only those with the most results fields are considered.Results fields are those fields that appear in E_RESULTS and in thefield catalog.
If there are still more than one infostructure to choose from, thesystem performs a weighting of the selection fields in the order theyappear in I_SELECTIONS. Infostructures that contain the first selectionfield are then considered to be more fitting than those that do notcontain the first selection field.
If there are still several infostructures that might fit, then they arevery similar, and the system chooses one of them at random.
The determination of the infostructure is completely rule based. Thenumber of entries in the infostructure or other similar factors are nottaken into account. The system always reads from one singleinfostructure, even if several would be suitable for selection.
In addition to fields selected from the underlying field catalog, eachinfostructure contains 3 additional fields, namely client (MANDT),archive file (ARCHIVEKEY) and offset (ARCHIVEOFS).
ILM Retention Warehouse Scenario
As of SAP NetWeaver 7.02, infostructures can contain two additionalfields, namely ORIGINAL_SYSID (name of the SAP original system in ILM)and ORIGINAL_CLIENT (client of the SAP original system in ILM). Bothfields are intended for use only with the Retention Warehouse scenario.You shuld be familiar with the scenario if you use this function.
For AS_API_READ to determine infostructures with ORIGINAL_SYSID andORIGINAL_CLIENT, the following conditions must be fulfilled:
I_SELECTIONS must contain both fields.
Both fields must also be transferred to the import parameterI_OBLIGATORY_FIELDS.
The fields are of the type admi_run-sysid (ORIGINAL_SYSID) andadmi_run-original_client (ORIGINAL_CLIENT).

Notes
Because the function module AS_API_READ has generic (not typed)parameters, it can not be tested in the testing environment of functionmodules (SE37-> "Execute"). To test the function module you musttherefore always write a special program.

Further information
For more information on the Archive Information System and the functionmodule AS_API_READ, see SAP Note 671421. The document "AS_API_READ -Programmed Accesses to AS" contains additional examples and hints foravoiding typical errors.

Description
In E_RESULT the result of the selection is returned. Here an internaltable must be specified that has structured rows. The rows must containat least one field from the field catalog or the field ARCHIVEKEY. (Ifthe structure contains the field ARCHIVEOFS, then ARCHIVEKEY must alsobe included).
Otherwise, any field may appear in the rows of the structure. The systemfills the table as if a MOVE-CORRESPONDING would be performed from theinfostructure to the table rows. This means that the table fields withthe same name as those from the infostructure are filled. This alsoapplies to the fields ARCHIVEKEY and ARCHIVEOFS, if they are containedin E_RESULT.

Example
The following shows how you can have pointers to the corresponding dataobjects in the archive.
DATA: BEGIN OF g_sbook,
fldate LIKE sbook-fldate,
END OF g_sbook,
gt_result TYPE TABLE OF aind_arkey.
g_sbook-fldate = '19980907'.
CALL FUNCTION 'AS_API_READ'
EXPORTING
i_fieldcat = 'DEMO_SBOOK'
i_selections = g_sbook
IMPORTING
e_result = gt_result[].

Description
In order for data to be read, a field catalog must be specified. Thefield catalog in a way defines the evaluation method. The functionmodule AS_API_READ searches for active infostructures for the specifiedfield catalog. If several active infostructures are available, the mostfitting infostructure is selected, based on specific rules.
It is not possible to predetermine a specific infostructure. Fieldcatalogs are generally chosen and predetermined by development(generally by SAP), and infostructures are then created for these fieldcatalogs during the configuration of the Archive Information System.This provides a flexibility which would be impaired if infostructureswere predetermined.

Value range
Field catalogs of the Archive Information System.

Description
This parameter can contain a table of field names that must appear inthe selected infostructure. The parameter type should be an internaltable whose rows have the data type FIELDNAME.
If no active infostructure exists that contains the obligatory fields,the exception NO_INFOSTRUC_FOUND is triggered.

Default
By default, no field is mandatory. This creates the risk that functionmodule AS_API_READ selects an infostructure that contains none of theselection fields and that as a result all entries in the infostructureare read. We therefore recommend that you use parameterI_OBLIGATORY_FIELDS or that you make sure that the selections containfields of which one can be sure that they are contained in theinfostructure.

Example
In the following example only infostructures that contain field FLDATEare considered. If for field catalog DEMO_SBOOK no active infostructureis found that contains the field FLDATE, the exceptionNO_INFOSTRUC_FOUND is triggered.
DATA: BEGIN OF g_sbook,
smoker LIKE sbook-smoker,
fldate LIKE sbook-fldate,
END OF g_sbook,
gt_result TYPE TABLE OF aind_arkey,
gt_oblfields TYPE ttfieldname.
g_sbook-smoker = 'X'.
g_sbook-fldate = '19980907'.
APPEND 'FLDATE' TO gt_oblfields.
CALL FUNCTION 'AS_API_READ'.
EXPORTING
i_fieldcat = 'DEMO_SBOOK'
i_selections = g_sbook
i_obligatory_fields = gt_oblfields
IMPORTING
e_result = gt_result[]
EXCEPTIONS
no_infostruc_found = 1.

Description
Here you indicate according to which criteria the system should searchfor the entries of the Archive Information System. Depending on therequirements, this can be complex or simple criteria, which can betransferred in the following formats:
Type RSDS_FRANGE_T
This is a table with field names with corresponding selection options("Ranges" or "Select Options").
All fields entered in the selections must be fields of the transferredfield catalog. (The field catalog must contain fields with the samename.) If this is not the case the exception FIELD_MISSING_IN_FIELDCATis triggered.
In special cases it is also possible to use the archive file (field nameARCHIVEKEY) and the offset (ARHCIVEOFS) as selection fields.
For the selection executed by the function module only those fields areused that are also contained in the selected infostructure. (Ifnecessary, the system chooses the infostructure that contains as many ofthe selection fields as possible.) It may also happen that none of theinfostructure contains none of the selection fields. In this case all(!) entries of the infostructure are delivered. This can be avoided byusing the parameter I_OBLIGATORY_FIELDS.
Structure (field string)
For the selection it is also possible to transfer a structure. Keep inmind that only real structures work. It is not possible, for example, totransfer an individual field. The structures g_selections1 andg_selections2 from the following example can be used here:
DATA: BEGIN OF g_selections1<(>,<)>
smoker LIKE sbook-smoker<(>,<)>
fldate LIKE sbook-fldate<(>,<)>
END OF g_selections1.
DATA: g_selections2 TYPE sbook.
The selection fields then are all fields of the structure that are notempty (meaning they do not contain the data type-specific initial value)and that are contained in the field catalog. As in point 1. only thosefields that are also contained in the infostructure are used asselection fields. However, it may be that only through the set of allselection fields the system can determine which infostructure to use inthe first place.
The function module delivers all entries with the same values in theselection fields. For selection fields that do not appear in theinfostructure, the same applies as for selections of type RSDS_FRANGE_T.
Table with row structure as in point 2.
Basically here you get the same result as if you called the functionmodule AS_API_READ separately for each table row and then combined theresults.
If the system recognizes that for I_SELECTIONS other data than what hasbeen described here was transferred, then it triggers the exceptionPARAMETERS_INVALID. However, the system cannot recognize some errors,which can lead to unexpected results. We therefore recommend that youcarefully check and test the parameter I_SELECTIONS.

Example
The following coding shows the selections in the format of typeRSDS_FRANGE_T.
TYPE-POOLS: rsds.
DATA: g_selections TYPE rsds_frange_t<(>,<)>
gt_result TYPE TABLE OF aind_arkey.
* Fill G_SELECTIONS with selection criteria
[...]
CALL FUNCTION 'AS_API_READ'
EXPORTING
i_fieldcat = 'DEMO_SBOOK'
i_selections = g_selections
IMPORTING
e_result = gt_result[].
This procedure allows you to use practically any SELECT-OPTIONS for theselections. For this the data object G_SELECTIONS must be filled withthe names of the selection fields and the corresponding ranges. This isespecially suited for selection conditions of reports.
Keep in mind that you cannot simply transfer all selection criteria ofthe report to the function module AS_API_READ, but only those that arecontained in the field catalog. Otherwise you only get the exceptionFIELD_MISSING_IN_FIELDCAT.
Exceptions to this are the fields ORIGINAL_SYSID and ORIGINAL_CLIENT.These fields are not included in the field catalog, however, from SAPNetWeaver 7.02 onwards, they can be added to an infostructure in theRetention Warehouse Scenario. The parameter I_SELECTIONS must containboth fields so that AS_API_READ can determine infostructures withORIGINAL_SYSID and ORIGINAL_CLIENT.