Extracts
Sinceinternal tables have fixed line structures, they are not suited to handle datasets with varying structures. For this purpose, ABAP offers the possibility tocreate so-called extract datasets (extracts, for short).
An extractis a sequential dataset in the memory area of the program. You can onlyaddress the entries in the dataset within a special loop. The index or keyaccess permitted with internal tables is not allowed. You may only create one extractin any ABAP program. The size of an extract dataset is, in principle,unlimited. Extracts larger than 500 KB are stored in operating system files.The practical size of an extract is up to 2 GB, as long as there is enoughspace in the file system.
An extractdataset consists of a sequence of records of a predefined structure. However,the structure need not be identical for all records. In one extract dataset,you can store records of different length and structure one after the other.You need not create an individual dataset for each different structure youwant to store. This fact reduces the maintenance effortconsiderably.
In contrastto internal tables, the system partly compresses extract datasets when storingthem. This reduces the storage space required. In addition, you need notspecify the structure of an extract dataset at the beginning of the program,but you can determine it dynamically during the flow of theprogram.
You can usecontrol level processing with extracts just as you can with internal tables.The internal administration for extract datasets is optimized so that it isquicker to use an extract for control level processing than an internaltable.
Procedurefor creating an extract:
...
1. Define therecord types that you want to use in your extract dataset by declaring them asfield groups. The structure is defined by including fields in each fieldgroup.
Defining anExtract
2. Fill theextract dataset line by line by extracting the requireddata.
Filling an Extractwith Data
3. Once youhave filled the extract, you can sort it and process it in a loop. At thisstage, you can no longer change the contents of the extract.
ProcessingExtracts
Defining an Extract
The objectis defined in two steps. First, the individual records must be declared andthen their structure defined.
Declaring Extract Records as Field Groups
An extractdataset consists of a sequence of records. These records may have differentstructures. All records with the same structure form a record type. You mustdefine each record type of an extract dataset as a field group, using theFIELD-GROUPSstatement.
FIELD-GROUPS fg.
Thisstatement defines a field group fg. A fieldgroup combines several fields under one name. For clarity, you should declareyour field groups at the end of the declaration part of yourprogram.
A fieldgroup does not reserve storage space for the fields, but contains pointers toexisting fields. When filling the extract dataset with records, these pointersdetermine the contents of the stored records.
You can alsodefine a special field group called header:
FIELD-GROUPS header.
This groupis automatically placed before any other field groups when you fill theextract. This means that a record of a field group fg alwayscontains the fields of the field group header. Whensorting the extract dataset, the system uses these fields as the default sort key.
Defining the Structure of a Field Group
To definethe structure of a record, use the following statement to add the requiredfields to a field group:
INSERT f1...fn INTO fg.
Thisstatement defines the fields of field group fg. Before youcan assign fields to a field group, you must define the field group fg using theFIELD-GROUPSstatement.Only globally visible data objects of the ABAP program can be used as fieldsf1... fn. Youcannot assign a local data object defined in a procedure to afield group.
TheINSERT statement,just as the FIELD-GROUPSstatement,neither reserves storage space nor transfers values. You use the INSERTstatement tocreate pointers to the fields f1... fn in thefield group fg, thusdefining the structures of the extract records.
When you runthe program, you can assign fields to a field group up to the point when youuse this field group for the first time to fill an extract record. From thispoint on, the structure of the record is fixed and may no longer be changed.In short, as long as you have not used a field group yet, you can still extendit dynamically.
The specialfield group header is part ofevery extract record.Consequently, you may not change the structure of the header field groupafter you have filled the first extract record.
A field mayoccur in several field groups; however, this means unnecessary data redundancywithin the extract dataset. You do not need to define the structure of a fieldgroup explicitly with INSERT. If thefield group header is defined,an undefined field group consists implicitly of the fields in the field groupheader;otherwise, itis empty.
REPORT demo_extract_field_groups.
NODES: spfli, sflight.
FIELD-GROUPS: header, flight_info, flight_date.
INSERT: spfli-carrid spfli-connid sflight-fldate
INTO header,
spfli-cityfromspfli-cityto
INTOflight_info.
The program is linked to the logical databaseF1S. The NODES statement declares the corresponding interface workareas.
There are three field groups. The INSERT statement assigns fields to two of the field groups.
Filling an Extract with Data
Once youhave declared the possible record types as field groups and defined theirstructure, you can fill the extract dataset using the followingstatements:
EXTRACT fg.
When thefirst EXTRACT statementoccurs in a program, the system creates the extract dataset and adds the firstextract record to it. In each subsequent EXTRACT statement,the new extract record is added to the dataset.
Each extractrecord contains exactly those fields that are contained in the fg fieldgroup, plus perhaps the fields of the header field group.The fields occur as a sort key at the beginning. If you do not explicitlyspecify an fg fieldgroup, the
EXTRACT
statement isa shortened form of the statement
EXTRACT header.
When youextract the data, the record is filled with the current values of thecorresponding fields.
As soon asthe system has processed the first EXTRACTstatement foran fg fieldgroup, the structure of the corresponding extract record in the extractdataset is fixed. You can no longer insert new fields into the fg andheader fieldgroups. If you try to modify one of the field groups afterwards and use it inanother EXTRACTstatement, aruntime error occurs.
Byprocessing EXTRACT statementsseveral times using different field groups, you fill the extract dataset withrecords of different length and structure. Since you can modify field groupsdynamically up to their first usage in an EXTRACT statement,extract datasets provide the advantage that you need not determine thestructure at the beginning of the program.
Assume the following program is linked to the logical databaseF1S.
REPORT demo_extract_extract.
NODES: spfli, sflight.
FIELD-GROUPS: header, flight_info, flight_date.
INSERT: spfli-carrid spfli-connid sflight-fldate
INTO header,
spfli-cityfromspfli-cityto
INTOflight_info.
START-OF-SELECTION.
GET spfli.
EXTRACTflight_info.
GET sflight.
EXTRACTflight_date.
There are three field groups. The INSERT statement assigns fields to two of the field groups. During the GET events, thesystem fills the extract dataset with two different record types. The recordsof the field group flight_info consist of five fields: spfli-carrid, spfli-connid, sflight-fldate, spfli-cityfrom, and spfli-cityto.
The first three fields belong to the prefixed field group header. The records of the field group flight_date consist only of the three fields of the header field group. The following figure shows the structure of the extractdataset:
ProcessingExtracts
Once an extract dataset contains allof the required data, you can process it. When you have started processing adataset, you can no longer extractdata into it.
Reading Extracts
Sorting Extracts
Control LevelProcessing
Calculating Numbersand Totalsn
Reading an Extract
Likeinternal tables, you can read the data in an extract dataset using a loop.
LOOP.
...
[AT FIRST | AT fgi[WITH fgj] | AT LAST.
...
ENDAT.]
...
ENDLOOP.
When theLOOPstatementoccurs, the system stops creating the extract dataset, and starts a loopthrough all entries contained in it. One record from the extract dataset isread in each loop pass. The values of the extracted fields are placed in thecorresponding output fields within the loop. You can execute several loops insuccession. The loop around an extract dataset cannot be nested. It is also nolonger possible to use further EXTRACT statementswithin or after the loop. In both cases, a runtime error occurs.
In contrastto internal tables, extract datasets do not require a special work area orfield symbol as an interface. Instead, you can process each record of thedataset within the loop using its original field names.
Loop control
If you wantto execute some statements for certain records of the dataset only, use thecontrol statements AT andENDAT.
The systemprocesses the statement blocks between the control statements for thedifferent arguments of AT asfollows:
· AT FIRST
The systemexecutes the statement block once for the first record of thedataset.
· AT fgi [WITH fgj] The systemprocesses the statement block if the record type of the currently read extractrecord was defined using the field group fgi. When usingthe WITH fgjaddition, inthe extract dataset, the currently rea128d record of field group fgi must beimmediately followed by a record of field group fgj.
· AT LAST
The systemexecutes the statement block once for the last record of thedataset.
You can alsouse the AT andENDATstatementsfor controllevel processing.
Assume the following program is linked to the logical databaseF1S.
REPORT demo_extract_loop.
NODES: spfli, sflight.
FIELD-GROUPS: header, flight_info, flight_date.
INSERT: spfli-carrid spfli-connid sflight-fldate
INTO header,
spfli-cityfromspfli-cityto
INTOflight_info.
START-OF-SELECTION.
GET spfli.
EXTRACTflight_info.
GET sflight.
EXTRACTflight_date.
END-OF-SELECTION.
LOOP.
AT FIRST.
WRITE /'Start of LOOP'.
ULINE.
ENDAT.
AT flight_info WITHflight_date.
WRITE: /'Info:',
spfli-carrid , spfli-connid, sflight-fldate,
spfli-cityfrom, spfli-cityto.
ENDAT.
ATflight_date.
WRITE: /'Date:',
spfli-carrid, spfli-connid, sflight-fldate.
ENDAT.
AT LAST.
ULINE.
WRITE /'End of LOOP'.
ENDAT.
ENDLOOP.
The extract dataset is created and filled in the same way as shown in theexample for Filling an Extractwith Data. The data retrieval ends before the END-OF-SELECTIONevent, in which the dataset is read once using a LOOP.
The control statements AT FIRST and AT LAST instruct the system to write one line and one underscore line in the list,once at the beginning of the loop and once at the end.
The control statement AT fgi tells the system to output the fields corresponding to each of the two recordtypes. The WITH flight_date addition means that the system only displays the records of field groupflight_info if at least one record of field group flight_datefollows; that is, if the logical database passed at least one date for aflight.
The beginning of the output list looks like this:
The contents of the field sflight-fldate in the header part of record type flight_info are displayed as hash signs (#). This is because the logical database fillsall of the fields at that hierarchy level with the value HEX 00 when itfinishes processing that level. This feature is important for sorting and forprocessing control levels inextract datasets.
Sortingan Extract
You can sort anextract dataset in much the same way as an internal table by using thefollowing statement:
SORT [ASCENDING|DESCENDING] [AS TEXT] [STABLE]
BY f1 [ASCENDING|DESCENDING][AS TEXT]
...
fn[ASCENDING|DESCENDING] [AS TEXT].
The SORT statement terminates the creation of theextract dataset of a program and, at the same time, sorts its records.Without the BY option, the system sorts the dataset by the keyspecified in the header field group.
You can sort anextract dataset as often as you like in a program, using any number ofdifferent keys. The onlyprerequisite is that all fields by which you want to sort are contained in theheader during the extraction process. You must not use the SORT statement between LOOP and ENDLOOP. However, you can sort and read the extract datasetin any sequence. After theSORT statement has been executed you can not useany further EXTRACT statements. Otherwise, a runtime error occurs.
You can define adifferent sort key by using the BYaddition. The system then sorts the dataset according to thespecified components f1... fn. These components must either be fields of theheaderfield group or field groups containing onlyfields from the header field group. The number of key fields is limited to 50.The sequence of the componentsf1... fn determines the sort order. The system uses the options you specify beforeBY as a default for all fields specified afterBY. Theoptions that you specify after individual fields overwrite for these fieldsthe options specified before BY.
You can define thesort direction using the DESCENDING or ASCENDING additions. The default is ascending order. For character strings, you can use theASTEXT addition to define thesort method. This forces analphabetical sort, as with internaltables. If you want to sortan extract dataset alphabetically more than once, you should include a fieldwhich can be sorted alphabetically in the sort key instead of the text fieldfor performance reasons. To fill this field, use the CONVERTstatement.
If you putASTEXT before BY, the addition only applies to typec fields in the sort key. If you place AS TEXT after a field, the field must be of typec. Ifyou place AS TEXT after a field group, the option only appliesto the type c fields within the group.
This sortingprocess is not stable, that is, the old sequence of records with the same sortkey must not necessarily be kept. To force a stable sort, use the STABLEaddition.
If there is notenough main memory available to sort the data, the system writes data to anexternal auxiliary file during the sorting process. The name of the file isdetermined by the SAP profile parameter DIR_SORTTMP.
The SORT statement sorts by all of the fields in thesort key with the contents HEX 00 before all of the otherentries. This is significant whenyou use logicaldatabases. When a logicaldatabase has finished reading a hierarchy level, it fills all of the fields atthat level with the value HEX 00. Equally, if you use a field list in the GET statement(FIELDS addition), the logical database fills all ofthe fields not in the field list with HEX 00.
Each sortingprocess executed on the extract dataset using the SORT statement defines a control level. This isrequired for subsequent control levelprocessing.
Assume thefollowing program is linked to the logical databaseF1S.
REPORTdemo_extract_sort.
NODES: spfli,sflight.
FIELD-GROUPS: header,flight_info, flight_date.
INSERT: spfli-carridspfli-connid sflight-fldate
INTO header,
spfli-cityfromspfli-cityto
INTOflight_info.
START-OF-SELECTION.
GET spfli.
EXTRACT flight_info.
GET sflight.
EXTRACT flight_date.
END-OF-SELECTION.
SORTDESCENDING.
LOOP.
AT FIRST.
WRITE / 'Start of LOOP'.
ULINE.
ENDAT.
AT flight_info WITH flight_date.
WRITE: / 'Info:',
spfli-carrid , spfli-connid, sflight-fldate,
spfli-cityfrom, spfli-cityto.
ENDAT.
AT flight_date.
WRITE: / 'Date:',
spfli-carrid, spfli-connid, sflight-fldate.
ENDAT.
AT LAST.
ULINE.
WRITE/ 'End of LOOP'.
ENDAT.
ENDLOOP.
This exampleis identical with the example in the section Reading anExtract, apart from the SORT DESCENDING statement. The SORT statement tells the system to sort theextract dataset in descending order by the three fields of the header field group, before reading it usingLOOP- ENDLOOP. The end of the list looks like this:
It is worthnoting that the records with the value HEX 00 in the field sflight-fldate (undefined characters in the list) aresorted before the remaining records. This is done to preserve the hierarchy of the datafrom the logical database, independent of the sort sequence.
Control Level Processing
When youperform a sort using the SORTstatement,control levels are defined in the extract dataset. For general informationabout control levels, refer to ProcessingInternal Tables in Loops The controllevel hierarchy of an extract dataset corresponds to the sequence of thefields in the header fieldgroup. After sorting, you can use the ATstatementwithin a LOOP loop toprogram statement blocks that the system processes only when the control levelchanges.
AT NEW f | AT END OF f.
...
ENDAT.
A controlbreak occurs when the value of the field f or asuperior field in the current record has a different value from the previousrecord (AT NEW) or thesubsequent record (AT END). Fieldf must bepart of the header fieldgroup.
If theextract dataset is not sorted, the AT - ENDAT block isnever executed. Furthermore, all extract records with the value HEX null inthe field f are ignoredwhen the control breaks are determined.
TheAT... ENDAT blocks in aloop are processed in the order in which they occur. This sequence should bethe same as the sort sequence. This sequence must not necessarily be thesequence of the fields in the header field group,but can also be the one determined in the SORTstatement.
If you havesorted an extract dataset by the fields f1, f2, …,the processing of the control levels should be written between the othercontrol statements in the LOOP loop asfollows:
LOOP.
AT FIRST.... ENDAT.
AT NEWf1....... ENDAT.
AT NEWf2....... ENDAT.
...
ATfgi..... ENDAT.
Singlerecord processing without control statement
...
AT END OFf2.... ENDAT.
AT END OFf1.... ENDAT.
AT LAST..... ENDAT.
ENDLOOP.
You do nothave to use all of the statement blocks listed here, but only the ones yourequire.
REPORT demo_extract_at_new.
DATA: t1(4) TYPE c, t2 TYPE i.
FIELD-GROUPS: header.
INSERT t2 t1 INTO header.
t1 ='AABB'. t2 = 1. EXTRACT header.
t1 ='BBCC'. t2 = 2. EXTRACT header.
t1 ='AAAA'. t2 = 2. EXTRACT header.
t1 ='AABB'. t2 = 1. EXTRACT header.
t1 ='BBBB'. t2 = 2. EXTRACT header.
t1 ='BBCC'. t2 = 2. EXTRACT header.
t1 ='AAAA'. t2 = 1. EXTRACT header.
t1 ='BBBB'. t2 = 1. EXTRACT header.
t1 ='AAAA'. t2 = 3. EXTRACT header.
t1 ='AABB'. t2 = 1. EXTRACT header.
SORT BY t1 t2.
LOOP.
AT FIRST.
WRITE 'Start ofLOOP'.
ULINE.
ENDAT.
AT NEW t1.
WRITE / ' New T1:'.
ENDAT.
AT NEW t2.
WRITE / ' New T2:'.
ENDAT.
WRITE: /14 t1, t2.
AT END OF t2.
WRITE / 'End ofT2'.
ENDAT.
AT END OF t1.
WRITE / 'End ofT1'.
ENDAT.
AT LAST.
ULINE.
ENDAT.
ENDLOOP.
This program creates a sample extract, containing the fields of the header field group only. After the sorting process, the extract dataset has severalcontrol breaks for the control levels T1 and T2, which are indicated in thefollowing figure:
In the LOOP loop, the system displays the contents of the dataset and the control breaksit recognized as follows:
Calculating Numbers and Totals
When youread a sorted extract dataset usingLOOP, you canaccess two automatically-generated fields cnt(f) andsum(g). Thesefields contain the number of different values and the sums of the numericfields respectively. The system fills these fields at the end of a controllevel and after reading the last record of the dataset as follows:
· cnt(f)
If f is anon-numeric field of the header field groupand the system sorted the extract dataset by f, cnt(f) containsthe number of different values f assumedwithin the control level or entire dataset respectively.
· sum(g)
If g is anumeric field of the extract dataset, sum(g)contains thetotal of the values of g within the control level or entire dataset,respectively.
You canaccess these fields either within the processing blocks following AT END OF or in theprocessing block following AT LAST, afterreading the entire dataset. If you try to access the fields cnt(f) andsum(g) without firstsorting the dataset, a runtime error may occur.
REPORT demo_extract_cnt_sum.
DATA: t1(4) TYPE c, t2 TYPE i.
FIELD-GROUPS: header, test.
INSERT t2 t1 INTO header.
t1 ='AABB'. t2 = 1. EXTRACT test.
t1 ='BBCC'. t2 = 2. EXTRACT test.
t1 ='AAAA'. t2 = 2. EXTRACT test.
t1 ='AABB'. t2 = 1. EXTRACT test.
t1 ='BBBB'. t2 = 2. EXTRACT test.
t1 ='BBCC'. t2 = 2. EXTRACT test.
t1 ='AAAA'. t2 = 1. EXTRACT test.
t1 ='BBBB'. t2 = 1. EXTRACT test.
t1 ='AAAA'. t2 = 3. EXTRACT test.
t1 ='AABB'. t2 = 1. EXTRACT test.
SORT BY t1 t2.
LOOP.
WRITE: /20 t1, t2.
AT END OF t2.
ULINE.
WRITE: 'Sum:', 20sum(t2).
ULINE.
ENDAT.
AT END OF t1.
WRITE: 'Differentvalues:', (6) cnt(t1).
ULINE.
ENDAT.
AT LAST.
ULINE.
WRITE: 'Sum:', 20sum(t2),
/ 'Differentvalues:', (6) cnt(t1).
ENDAT.
ENDLOOP.
This program creates a sample extract, containing the fields of the header field group only. After sorting, the system outputs the contents of thedataset, the number of the different t1 fields, and the totals of the t2 fields at the end of each control level and at the end of theloop: