structToComponent

Converts data from a Struct or collection of Structs into the entities and occurrences in the component.

Example: structToComponent vStruct

Annotations

When preparing a Struct programmatically for conversion to a component, you can use $tags to set the u_type annotation tag. Using this tag can help to resolve ambiguity if a field and an entity have the same name. Matching the Struct against the component is name based, so the u_type tag may not be required—it is clear from the component structure that one thing is a field and another thing is an entity.

Reconnect Loaded Data

If you are using Struct to transport disconnected record sets, the Struct may contain occurrence processing tags. These tags will be available if the Struct was created with componentToStruct/reconnecttags. In this case, the structToComponent statement sets state flags used by reconnect.

You should use a reconnect statement immediately after the structToComponent command. reconnect removes duplicates of occurrences, removes occurrences marked for deletion from the component, and sets the appropriate modification flags. For more information, see Reconnect Process.

Note:  The structToComponent statement only handles the reconnect processing tags if the u_type is present and has a value of occurrence.

Triggers

The structToComponent statement fires the following triggers that can be used to customize how the Struct is loaded into a component:

• trigger preDeserialize—fired immediately before an occurrence is loaded into a component. The new occurrence is not yet available and cannot be accessed.
• trigger postDeserialize—fired immediately after an occurrence is loaded into a component. The new occurrence is available and can be accessed. For example, use this trigger if an occurrence can be discarded, or the value for a derived field can be calculated.

Name Matching Rules

The structToComponent is primarily name driven. The following name matching rules apply:

• Tag names (annotations) are case sensitive. Tags should only occur once, else the value is empty.
• All tag value matching against component structure elements is case insensitive.
• Entity names or field names can be non-qualified (ENTITYNAME, or FIELDNAME), partially qualified (FIELDNAME.ENTNAME), or fully qualified (ENTITY.MODEL for an entity or FIELD.ENTITY.MODEL for a field). If an entity is not fully qualified matching it to a component structure can be ambiguous, in which case the outcome is not defined.

  This behavior is the same as statements such as retrieve/eEntity, where the specified name matches two different entities, each within a different model. Field names can normally be unqualified, as they are implicitly qualified by the location within the context of an entity.

In case of ambiguity (identical names of a field and an entity drawn on the same level), names must be fully qualified, or tags can be used to specify the type of the object.

Conversion Logic

The top-most Struct to be converted must represent a component or an entity.

Note:  If an entity is the starting point, it is not necessarily the top-level entity. It can be an entity that is nested inside the component structure.

From the starting point, the structToComponent conversion routine processes each member Struct in turn. For each Struct:

• If no tag is specified, it matches the Struct to the component structure based on the name.
• If no name match is found, a warning (STRUCTERR_NO_MATCHING_NAME) with related information is put in $procReturnContext, and the Struct (and all its children) is skipped.
• If the u_type tag is specified, the match is based on this value, and the name.

More specifically, the conversion routine does the following:

1. Finds the starting point.
   1. Check whether the top-level Struct (or Structs, in a collection) has a u_type tag. If it does, the value must be component or entity; otherwise a warning is put in $procReturnContext.
   2. Match the Struct name to a component or entity name.
      • If a match is found with the component name, continue at step 2.
      • If a match is found with an entity name, continue at step 3.
      • If no match is found, raise a warning in $procReturnContext.
2. Processes the component Struct. For each Struct member:
   1. Check whether the member has a u_type tag. If it does, the value must be entity; otherwise a warning is put in $procReturnContext.
   2. Match the name of the Struct member to top-level entity in the current component structure.
      • If a match is found, continue at step 3.
      • If no match is found, raise a warning in $procReturnContext.
3. Processes each entity Struct. For each Struct member:
   1. Check whether the member has a u_type tag. If it does, the value must be occurrence; otherwise a warning is put in $procReturnContext.
   2. For each occurrence Struct found, continue at step 4.

      Note:  The Struct name is not used for matching.

4. Processes each occurrence Struct member.
   1. Create a new occurrence at the end of the list of existing occurrences in the current entity.
   2. For each member, check whether it has a u_type tag. If it does, the value must be entity or field; otherwise a warning is put in $procReturnContext.
   3. Match the name of the member Struct with an entity or field. If u_type is not specified, it first tries to match an entity, and then a field.

      If no match is found, raise a warning in $procReturnContext.

5. Processes each field Struct member, assigning the value specified by the Struct to the field, and converting the data type if required.

$procReturnContext for structToComponent

$procReturnContext contains context and error information about the conversion, in the form of a Uniface list.

Context=structToXml ;}
{Infos=Number ;
{Warnings=Number ;} 
{Errors=Number ;}
{DETAILS=ID=MsgNum !!;SEVERITY=Type !!;MNEM=Mnemonic !!;DESCRIPTION=ErrorDescription !!;CURRENTSTRUCT=Struct !!;ADDITIONAL=SPECIFIEDNAME=StructName !!!;{INDEX=N !!!;}
EXPECTEDTYPE=ExpectedValue}  { !!!;TAGNAME=u_type !!!;TAGVALUE=ValueID= ...}