Functionality
The SCHEME_INSTANTIATE function instantiates a schema with the globaldata of the calling program.
A schema is a simple, maintainable method for generating text,especially of ABAP programs. A schema can be compared with thedefinition of a regular expression with variables, alternatives, loops,and subschema calls.
Schemas strictly distinguish between data collection in the callingprogram and syntax definition in the schema program, so that changescan easily be made to the syntax. The syntax in a schema is relativelyclear, in contrast to combining lines under program control withconcatenate and append.

Technique
Program /1SAP1/SCMG_s is generated from schema program s. Foreach schema in s, it contains a form that performs theinstantiation. The program is only generated again if the schemaprogram or schema parser changes.
This technique results in very efficient load times and runtimes forschema instantiations.
A form that returns an error message at instantiation is generated forincorrect schemes. As a result, all correct schemes can be correctlyinstantiated, even if the scheme program contains incorrect schemes.

Schema Syntax
The default control characters are used below, but can be redefined foreach schema program.

Schema Program
A schema program is an ABAP report created with SE38 containing one ormore schemas. This report has type I(nclude) since schemas do notsatisfy the ABAP syntax.

• It is advisable to combine related schemas in a program so that only
one program has to be loaded in order to instantiate these schemas.

• The length of the name of schema programs is limited to 18 characters
(data element SCHEMEPROG) since the prefix for the program generatedfrom it has 12 characters.

Schema
A schema is bracketed by the lines
/>schema_name<(><<)>/
...
/>END<(><<)>/




• The bracketing lines may not contain leading blanks and may not contain
any text or comments.

• 'END' is a reserved name and cannot be used as schema name.


• The length of the schema name is defined by data element SCHEMENAME,
currently 30 places.

Variables
Global variables (and only these!) can be referenced by a charactertype of the calling program in a scheme. '<(>&<)>' is the delimiterfor variables in teh scheme:
<(>&<)>varname<(>&<)>
A value is substituted for a variable, whereby trailing blanks aretruncated, but leading blanks are retained (as in the ABAP statementCONCATENATE). If the variables are not of type Character, the programterminates because the strlen(varname) function is used.


• If the variable name is preceded by '-', the value of the variable is
instantiated with lowercase conversion.
Example:
data: VAR(4) value ' cD '. "in the calling program
'ab<(>&<)>VAR<(>&<)>ef' -> 'ab cDef'
'ab<(>&<)>-VAR<(>&<)>ef' -> 'ab cdef'

Control Structures
Conditions, loops and subschema calls can be defined in schemas. Acontrol structure has the form:
{x$control$ ... $ .... .... }
where x defines the control structure in question and the individualcomponents of the control structure are separated by the character'$'
. 'Control' is the controlling expression.
The number of components depends on the particular control structure,but must be strictly adhered to, even if some parts are empty.Otherwise the syntax of the schema will be incorrect.


• During instantiation, the controlling elements are evaluated, but do
not produce any output, not even blanks.

• There may not be a line feed within '{x$control$'.

Condition
A condition has the form:
{C$condition$then$else}
'Condition' can be a simple variable, meaning 'not(variable isinitial)'. The 'then' part is instantiated if the variable is notinitial; otherwise the 'else' part is instantiated.
Example:
{C$sy-subrc$error$ok} -> 'error', if sy-subrc <> 0
-> 'ok' , if sy-subrc = 0
'Condition' can also be a simple expression of the form 'a op b', where'a' is a variable and 'b' is a variable, string or integer. 'Op' mustbe an ABAP operation with at most 2 places, e.g. =, <, LE, CA, ... .There must be a blank before and after 'op'.
Example:
data: a value 'D', b value 'D'.
{C$a = b $eq$neq} -> 'eq'
{C$a <(><<)>> 'D'$neq D $eq D} -> 'eq D'


• You can also represent 'if ... elseif ...' with this construct:

{C$sy-subrc = 0$ok${C$sy-subrc = 4$warning$error}}

• Both 'then' and 'else' parts can be empty, but all the separators must
be specified:
{C$condition$then$} or {C$condition$$else}.

Table Loop
A table loop has the form:
{T$table$pre1$pre$main$post$postn} or
{T$table WHERE condexpr$pre1$pre$main$post$postn}
where 'table' is the name of an internal table of the calling program.This table must be global there and must have a
header line.
'Condexpr' is a simple expression of the form 'f op b', where f is thename of a field of 'table', and 'op' and 'b' are as described forCondition.
There is a loop over this table, producing the following output:
'pre1mainpost' for the 1st line
'premainpost' for the 2nd - (n-1)th line
'premainpostn' for the nth line
Example:
{T$fieldtab$DATA: $
$fieldtab-fieldname like ... $,$.}
-> DATA: field1 like ... ,
field2 like ... ,
field3 like ... .
If you only want to take the key fields into consideration, the tableloop could be:
{T$fieldtab WHERE key = 'X'$DATA: $ ... }


• Caution: If the table does not exist in the calling program, this
results in the exception 'TABLE_NOT_EXISTS'.

• If the table does not have a (suitable) entry, the result of the table
loop is empty.

• If the table has exactly one (suitable) entry, the result is:
'pre1mainpostn'.

• Variables and even control structures can be used in parts pre1, pre,
post, postn. The variables have the values of the current loop scan inall parts. Using variables or control structures in post, however,costs approximately 20% performance.

Function Loop
A function loop has the form:
{F$function$pre1$pre$main$post$postn}
where 'function' is a form defined in the calling program with aparameter 'CHANGING <(><<)>idx> TYPE I'. This form sets the variablesused in the schema in each scan.
The form is first called with <(><<)>idx> = 1. <(><<)>idx> isincremented by 1 in each further call. The form itself can alsoincrement <<)>idx> internally and return it. The loop is finished whenthe form returns <(><<)>idx> = 0.


• The remarks for the table loop are analogous to the function loop.


• A function loop can be used for example if output should only be
produced selectively for certain entries of a table:
form next_entry changing idx type i.
loop at tab from idx where .... . " start search from idx
idx = sy-tabix. " set idx to found entry
exit. " at next call idx is incremented by 1
endloop.
if sy-subrc <> 0.
idx = 0. " no entry found, set idx=0 to end loop
endif.
endform.

• If you scan the entire table, you should use the table loop since it
only needs about 60% of the runtime of the function loop.

Subschema Call
A subschema call has the form:
{S$schema}
where 'schema' is the name of a schema in the same schema program. Thegiven schema is instantiated at the location of the subschema call.
The instantiated subschema is indented as far as the call itself. If aline of the subschema starts with the comment character '*', it remainsin the first position of the line.
If the line of the subschema call starts with '*', all the lines of theinstantiated subschema also start with '*'.
Examples: see schema program SCHEME_SAMPLE, which can be instantiatedwith report SCHEME_TEST.

Other Features

Comments
Since schemas are bracketed, lines outside the schemas can be used forcomments.
Comments beginning with '*:' can be strewn throughout a schema. Otherlines beginning with '*' are instantiated in the normal manner in orderto be able to create ABAP comments in the result.
Comments at the end of the line begin with '":'. The rest of the lineis not copied to the instantiation.

Uppercase/Lowercase
Since the ABAP Editor converts to uppercase, you can prevent this bybeginning the line with '"%'. For the ABAP Editor, this is a commentand it continues with lowercase. The schema instantiation program skipsthese characters.
If an editor without conversion is used (with 4.6A), this is no longernecessary.

Continuation Line and Indentation
To represent more than one line of a scheme in one instantiation line,you must end the schema lines with '\'. The following line feed is thenomitted in the instantiation of the schema line.


• You need this if the schema for an instantiated line does not fit in
one schema line due to control structures or long variable names.
You can make the schema more readable by indenting lines without theindentation being copied to the result. You must begin the line afterthe indentation with '\'.

• This is useful especially when indenting continuation lines.

Example:
"% This is a long text over several \
"% \lines which is indented in the schema.

Escape Character
Character '#' is used as escape character and masks the meaning of thecharacters '{}$<(>&<)>#<(>&<)>'
Example:
control: #{x#$...#}. Variable: #<(>&<)>var#<(>&<)>'. Escape:##.'
-> 'control: {x$...}. Variable: <(>&<)>var<(>&<)>. Escape: #.'


• Otherwise '#' is simply skipped in schema lines.


• The meaning of other characters is not masked. In particular,
characters that must be at the beginning of a line may not be displacedby the escape character.

Comment Character of the Target Language
This character can be set and has the default '*' for generating ABAPprograms. It is handled specially for indenting subschemas and inautomatic line feeds.
If a subschema line begins with this character, it stays in the 1stposition even after indentation. The indentation is after thischaracter.
If you have to break an instantiated line and this line has a commentcharacter in its 1st position, the continuation lines also have thischaracter in their 1st position.

Automatic Line Feed
If an instantiated line is too long, there is an automatic line feed sothat the lines fit in RESULT_TAB.
There is a line feed at a space or, if this is not possible, before'({[' or after ',.)]}'. The space is replaced with line feed. Line feedis inserted before or after the other characters.
Example:
{t$fieldtab$DATA:$$ fieldtab-fieldname like ... $,$.}
-> DATA: field1 like ... , field2 like ... , ... ,
field5 like ... , ...


• All continuation lines are indented as far as the original line.


• If the original line is a comment line, all the continuation lines are
also comment lines.

• Error case: If you cannot break the line at the given character and the
line is not a comment line, the exception FORCED_LINESPLIT is set. Theinstantiation is always completely executed and returned in RESULT_TAB.

• An instantiated line may be up to 8000 characters long before the line
is split (field SCINSTLINE-TEXT).

Control Characters
Here is an overview of the default control characters for schemas
Character Meaning Length Remarks
# Escape character 1 3
/> Schema definition - start 2 1
<(><<)>/ Schema definition - end 2
{ Control structure - start 1 3
} Control structure - end 1 3
$ Control structure - separator 1 3
<(>&<)> Variable delimiter 1 3
- Lowercase variable notation 1 2
\ Line feed escape, indent escape 1 4
*: Comment line 2 1
": Rest of line comment 2
"% Line with lowercase 2 1
* Comment character of target lang. 1 5
! Input variable in interative mode 1 2, 6
"! Line only for interactive mode 2 1, 6
Remarks
Character only has effect at start of line
Character only has effect within variables before variable name
Character can be masked with escape character
Character only has effect at end of line and as first character afterany number of spaces
Character has no special role in schemas, but in instantiation
Currently not used but taken into consideration in syntactic analysis
If there are conflicts with the schema contents, the control charactersin the schema program can be redefined. To do so, specify in the 1stline starting with the 1st column:
:SET # /> <(><<)>/ { } $ <(>&<)> - \ *: ": "% * ! "!
After :SET Keyword, all or an initial piece of the control charactersare specified in the above-defined order and length(!). Blanks areremoved and the string is assigned to the delimeter string (seeDictionary structure SCMDELIMA). The default is still used for thecontrol characters missing at the end. Specify 'N' there to deactivatethe special handling of the comment character of the target language.

Schema-Controlled Generation
You need 2 programs for the schema-controlled generation: the schemaprogram and a driver program. The driver program provides thevariables, tables and functions used in the schema program and callsthe schema instantiation. The structure of a driver program isdescribed below.

Procedure


• Create the required schemas in a schema program. One way is to first
create an executable program for a fixed example and then generalizethe generic parts with schema syntax.

• Insert the variables, tables and functions needed by the schema in the
driver program in parallel.

• Check the schema program you created with Report SCHEME_TEST in
'symbolic instantiation' mode.
Any syntax errors are output, and the layout can be checked with thesymbolic instantiation. The value for the conditions and the number ofloop scans can be varied. You should check at least the extreme cases 0and 1.

• Then check the driver program together with the schema program. For
test purposes you can call module DD_SCHEME_TEST instead ofSCHEME_INSTANTIATE. You do not have to supply the additional parametersof this module. This module outputs the results and the error messageson the screen.

Errors
All exceptions set the system variables and output the error messagewith MESSAGE.
The exceptions SYNTAX_ERROR and GENERATE_ERROR can usually be avoidedif the schema program is first checked with Report SCHEME_TEST.

Calling Program
The schema program normally has a driver program that provides therequired data for the instantiation.
This program has the following structure:
** global variables usable in schemas
data: var1, ..., varn.
** global tables usable in table loops of schemas
data: tab1 type table of ... with header line,
...
tabm type table of ... with header line.
** functions used in function loops of schemas
form fct1 changing idx type i. ... endform.
...
form fctk changing idx type i. ... endform.
** variables for schema instantiation
data: thisprog like sy-repid,
schemeprog type schemeprog value 'myschemes',
scheme type schemename,
result_tab type abapprog.
**** for each schema S in schemaprog a form instantiate_S
form instantiate_S using ... .
* 1. set global variables and tables used in S
...
* 2. call instantiation
thisprog = sy-repid. "important to fix value of sy-repid here
scheme = 'S'.
refresh result_tab.
call function 'SCHEME_INSTANTIATE'
exporting
calling_prog = thisprog
scheme_program = schemeprog
scheme_name = scheme
tables
result_tab.
exceptions
when others = 8.
if sy-subrc <> 0.
MESSAGE ID SY-MSGID TYPE SY-MSGTY NUMBER SY-MSGNO
WITH SY-MSGV1 SY-MSGV2 SY-MSGV3 SY-MSGV4.
endif.
* 3. use result_tab
...
endform.

Example
Report SCHEME_SAMPLE contains examples and Report SCHEME_ERROR containsincorrect examples.
You can test these examples as well as the schema programs you writeyourself with Report SCHEME_TEST.


This program searches for variables, tables and functions in thescheme.
Never define SY-REPID as parameter since the contents change after thecall. First assign SY-REPID to a local variable and then copy it.