#EMBED (define embedded source point) 

Top  Previous  Next

 

 

#EMBED

( identifier [, descriptor ] ) [, symbol ] [, HLP( helpid ) ] [, DATA ] [, HIDE ]

 

 

[, WHERE( expression ) ] [, MAP( mapsymbol, description ) ] [, LABEL ] [, NOINDENT ]

 

 

[, LEGACY ] [, PREPARE( parameters ) ] [, TREE( displaytext) ]

#EMBED

Identifies an explicit position in the Template where the programmer may place their own source code.

identifier

A user-defined template symbol which identifies the embedded source code point for the Application Generator.

descriptor

A string constant containing a description of the embedded source code's position in the Template. This is the string displayed in the list of available embedded source code windows for a procedure Template (normally omitted if the HIDE attribute is present).

symbol

A multi-valued template symbol or a literal string. You may have multiple symbols on a single #EMBED statement. This may also have a description to specify the text to display in the embedded source tree appended to it with square brackets (i.e. %symbol[%description]).

HLP

Specifies on-line help is available for the #EMBED.

helpid

A string constant containing the identifier to access the Help system. This may be either a Help keyword or "context string."

DATA

Specifies the embed point is in a data section, so the Text Editor's Window and Report Formatters can be used.

HIDE

Specifies the source code point does not appear in the tree of available embedded source code points. Therefore, the #EMBED is only available for #CODE, #CONTROL, or #EXTENSION code generation.

WHERE

Specifies the #EMBED is available only for those instances of the symbol where the expression is true.

expression

An expression that specifies the condition.

MAP

Maps the description to the symbol for display in the embedded source tree. You may have as many MAP attributes as there are symbols.

mapsymbol

Names which of the #EMBED symbols the MAP references.

description

An expression that specifies the text to display in the embedded source tree.

LABEL

Specifies the embed point is generated in column one (1) so the Text Editor will correctly color-code the labels.

NOINDENT

Specifies the code generated into the embed point retains the indention from its source (either generated or entered in by the programmer) source in column 1 is generated into column 1, no matter where the #EMBED is placed.

LEGACY

Specifies to show the embed only when you press the legacy button on the embed tree. The #EMBED is displayed in the list of available embed points only if there is already code in it. This indicates an embed point which has been superceded and is only present to allow the existing code in it to be moved to a new embed or deleted.

PREPARE

Executes preparatory code before evaluating the #EMBED symbol s. The nth parameter to PREPARE is evaluated immediately before the nth symbol is evaluated.

 

parameters is a comma-delimited list of expressions or calls to #GROUPs. You may have as many PREPARE parameters as there are symbols on the #EMBED.

TREE

Specifies what will be added to the embeds dialog tree. This overrides the MAP attribute.

 

displaytext is a comma-delimited list of strings (constraints or variables) containing tree level text, color, and priority information. Each tree level may be a separate TREE entry or contained in single quotes and separated by a vertical bar (|) character.

 

’Level One|LevelTwo|Level Three’

 

Following the text to display you may have optional color and priority information contained in curly braces, in the following format:

 

‘TextToDisplay{{Color(0FFh),priority(5000)}’

 

The color information may be either a number or the text for a color EQUATE from the EQUATES.CLW file.

#EMBED identifies an explicit position in the Template where the programmer may call a procedure, generate code from a code template, or place their own custom embedded source code within the procedure. The Application Generator prompts the programmer for the procedure to call, or the code template to use, or calls the Text Editor to allow the programmer to write the embedded source code. #EMBED is also used as the destination of all the source automatically generated by #CODE, #CONTROL, and #EXTENSION template sections. If no code is written in the embedded source code point by the programmer or any code template, control template, or extension template, no code is generated.

In a #PROCEDURE section, the source code is automatically placed in the exact column position at which #EMBED is located within the Template. If #EMBED is directly placed in the data section of a #PROGRAM, #MODULE, or #PROCEDURE, it must be in column one (1) of the Template file (so the embedded code may contain data labels). If the #EMBED statement has the DATA atribute, the Window and Report Formatters in the Text Editor are available for use. In executable code sections, #EMBED may be placed in column one, but that is not required.

#EMBED is valid in a #GROUP section, however, this should be used with care. Since it is possible for a #GROUP to be recursive (call itself), it is possible to create embedded source code that is repeated within each iteration of the recursive #GROUP's generated code. The source code is generated in the same relative column position as the code generated from the #GROUP. A #EMBED using the symbol attribute is used within a #FOR statement to allow a different piece of embedded source to be inserted for each instance of the symbol. It can also be used within #FOR, #LOOP, and/or recursive #GROUPs for the current instance of the symbol (if it has been #FIXed). The MAP attribute allows you to replace a description for the symbol in the embedded source tree.

Example:

#PROCEDURE(SampleProc,'This is a sample procedure'),WINDOW

#EMBED(%DataSection,'Data Section Source Code Window'),DATA #!Source code in column 1

 CODE               !Begin executable code

#EMBED(%SetupProc,'Code Section Source Code Window 1')    #!Source code in column 3

 OPEN(Screen)       !Open window

 ACCEPT             !Event handler

   CASE SELECTED()  !Handle field-selection events

   #FOR(%Control)

   OF %Control

    #EMBED(%ScreenFieldSetupEmbed,'Field Selected Embed'),%Control

   #ENDFOR

   END

   CASE ACCEPTED()  !Handle field-action events

   #FOR(%Control)

   OF %Control

    #EMBED(%ScreenFieldEditEmbed,'Field Accepted Embed'),%Control

   #ENDFOR

   END

 END

#EMBED(%CustomRoutines,'Code Section Source Code Window 2'),LABEL  #!Source in col 1

 

See Also:     #AT (insert code in an embed point) , #CODE , #CONTROL #EXTENSION, #PRIORITY