Reference Collections and Simulating Events
Public and Partner Operations
Public and Partner Attributes
Public and Partner Handles
$componentType
Timer
Pre Load Occurrence
Post Load Occurrence
Pre Save Occurrence
Post Save Occurrence
<$cmpStateManagedBy>
<$componentName>
<$componentType>
<$modelName>
<$tableName>
<$entName>
<$fieldName>
<$triggerAbbr>
<$library>
/anm (Analyze Model)
/ceo (Compile Entity Operations)
/esv (Compile Entity Services)
/ssv (Compile Session Services)
/dtd (7.2.06: Compile DTDs)
/all /hts (7.2.05: Include Skeleton Generation)
UNIFACE 7 supported supertypes and subtypes. Fields were only defined for supertypes and thus could not be customized per subtype.
UNIFACE 8 supports supertypes, functional subtypes and component subtypes. Fields can be customized per subtype, except for those properties pertaining to the physical database structure (e.g. field datatype or field packing codes). UNIFACE 7 subtypes are represented by UNIFACE 8 functional subtypes.
UNIFACE 8 supports component operations, but also entity occurrence operations and entity collection operations. They can be accessed by a handle.
Entity occurrence attributes are represented by the entity its fields. They can be accessed by a handle. Yet, attributes can only be accessed intra-component, i.e. they are only usable by partners which live inside the same component.
Entity collection attributes and component attributes are not yet supported.
Entity and field triggers are inherited from supertype to functional subtype.
Entity and field triggers are inherited from supertype to component subtype.
Entity and field triggers are inherited from functional subtype to component subtype.
Properties are not inherited.
Entity and field triggers are inherited from model to component.
Entity and field properties are inherited from model to component.
Component triggers are inherited from component template to component.
Component properties are inherited from component template to component.
For triggers, the following cases apply:
Handles are defined as a datatype and grant access to operations and attributes.
The datatype 'handle' can be used in Proc variables, component variables, global variables, non database fields and params. For example:
operation foo
params
handle h1: in
endparams
variables
handle h2
endvariables
...
end ; foo
Before operations or attributes are accessed, a handle to an entity occurrence, entity collection or component needs to be obained. The following Proc functions are available:
A handle to a component instance can also directly be obtained via the new_instance Proc statement. Then, UNIFACE takes care of garbage collection and you don't have to keep a seperate instance administration.
Examples:
variables
handle h1, h2, h3, h4
endvariables
new_instance componentName, h1
h2 = $occHandle("CLIENT") ; CLIENT must be painted on this component
h3 = $collHandle ("CLIENT") ; CLIENT must be painted on this component
h4 = $instanceHandle("myInstance")
Operations are accessed by the '->' operator, for example:
h1->myComponentOperation()
h2->myOccurrenceOperation()
h1->myCollectionOperation()
Attributes are accessed similarly, for example:
variables
partner handle h ; !!!
endvariables
h = $occHandle (CLIENT)
$1 = h->name
h->name = "Bert Visscher"
When using the '->' operator, the same error codes as for the 'activate' Proc statement apply.
Handles can be tested if they are pointing to something. For example, if a handle was pointing an occurrence, and the occurrence was removed, then the handle may still exist, but it is pointing to nothing.
if (h1 = "")...
Handles cannot be compared to each other, only the content to which they are pointing to can be compared.
Handles can be passed to other components. As such, entity occurrence operations and entity collection operations can be accessed from an inter-component perspective.
If an operation invocation at a handle does not succeed, then check:
An entity with a non database field of data type 'handle', can act as a reference collection by filling multiple occurrences with handles and by exposing a set of collection operations. Download the sample.
Public operations can be used from other other components.
Partner operations can only be used inside a component, i.e. they are only visible for partners which live inside the same component.
-> Partner operations are less visible
Partner operations are typically used for making functional decompositions, similar to entries.
Partner operations do not show-up in the signature repository.
For example:
public operation foo
...
partner operation foo1
...
Partner operations look similar to entries, but have a number of differences:
In UNIFACE 8.1.01, attributes are always partner. Partner attributes are only visible for partners who live inside the same component.
Handles can be defined as public or partner. Public handles can just access public operations. Partner handles can also access partner operations and partner attributes.
-> Partner handles can do more
A variable declaration with datatype 'handle' is public by default.
$instanceHandle, $occHandle, and $collHandle each return a partner handle by default.
Partner handles are implicitly casted to public handles once they are exposed to other components.
Public handles cannot be casted to partner handles.
Local Proc modules (entries) support a formal "returns dataType" declaration. It must be defined before the Params section. For example:
entry isEven
returns boolean
params
numeric n: in
endparams
if ((n % 2) = 0)
return 1
else
return 0
endif
end ; isEven
Entries can then be called as functions in expressions. For example:
if (isEven (5))
message "Something's wrong ..."
endif
Calling an entry as a function can be nested. For example:
if (isEven (aNumber() + 5))
message/info "I processed an even number !"
endif
If an entry is called and the entry has a formal 'returns...', but the caller is not interested in the return value, then the entry can be called using 'void'. For example:
void isEven (6)
Making an explicit call to an entry is of course also still allowed. $status will contains the returned value after calling. This can only be a numeric. For example:
call isEven (6)
if ($status = 1)
message/info "Once again, I processed an even number!"
endif
Entries can only be used as functions if the entry name follows the same syntax as defined for operations. Effectively, an entry name starting with a digit is allowed, but cannot be used as a (void) function. For example, the following is not allowed:
entry 2isEven
returns boolean
...
end ; 2isEven
if isEven(6)
Operations do not yet support the formal 'returns' declaration. However, operations can also be called as functions in expressions. For example:
EXECUTE
if ($instanceHandle()->isEven(5))
...OPERATIONS
operation isEven
params
numeric n: in
endparams
if ((n % 2) = 0)
return 1
else
return 0
endif
end ; isEven
The same rules apply as for entries. However, for operations:
Attributes can be used in expressions.
Attributes can be used as a parameter (IN, OUT, INOUT).
Some examples:
variablespartner handle h1, h2 ; !!!
endvariables
h1 = $collHandle(CLIENT)->first()
h1->name = "Bert Visscher"
h2 = $collHandle(CLIENT)->next()
if (h1->name != h2->name)
$collHandle->duplicateName(h1->name, h2->name)
endif
Nesting and indirection are bot supported for attributes and operations. For example:
$1 = handle1->(handle2->anOperation())
$2 = handle1->handle2->anAttribute
Components can be activated stateless or asynchrenous::
activate/stateless
activate/async
Stateless or asynchroneous invocation is not supported for handles.
UNIFACE 8 supports #Define statements at component level, entity level, and field level. There is a DEFINES trigger for each of these levels. The component DEFINES triggers replaces the UNIFACE 7 'Define Component Constants' trigger. UNIFACE component constants are migrated into the DEFINES trigger.
If a #Define is redefined, then the redefinition remains valid within the respective context. For example:
ENTITY CLIENT: DEFINES
#Define NAME = ElvisENTITY CLIENT: OCCURRENCE GETS FOCUS
$1 = "<NAME>" ; name is ElvisFIELD ID.CLIENT: DEFINES
#Define NAME = PelvisFIELD ID.CLIENT: FIELD GETS FOCUS
$1 = "<NAME>" ; name is PelvisFIELD ID.CLIENT: DETAIL
#Define NAME = Priscilla
$1 = "<NAME>" ; name is PriscillaFIELD ID.CLIENT: HELP
$1 = "<NAME>" ; name is Pelvis
In case of inheritance: #Defines are 'overlayed' on top of each other.
$componentType
The values for $componentType are extended to entity service and session service. Supported values for $componentType are now:
F - form
S - service
R - report
P - server page
E - entity service
N - session service
Timer
to be documented...
Pre Load Occurrence
Name <Pre Load Occurrence>
Abbreviation PRLO
Level Entity
Activation The <Pre Load Occurrence> trigger is fired just before an occurrence is loaded from a xml stream into a hitlist. The occurrence itself is not yet available and cannot be accessed.
Default action If no Proc code is present in this trigger, there is no action
Return Value The structure editor is not affected by the value of $status
Description Tunes the execution of xmlLoad and xmlSave: Customize the process of loading a xmlstream into a hitlist.
For example: block loading (return -1) because a certain maximum has been achieved.
Post Load Occurrence
Name <Post Load Occurrence>
Abbreviation PSLO
Level Entity
Activation The <Post Load Occurrence> trigger is fired just after an occurrence is loaded from a xml stream into a hitlist. The occurrence is available and can be accessed.
Default action If no Proc code is present in this trigger, there is no action
Return Value The structure editor is not affected by the value of $status.
Description Tunes the execution of xmlLoad: customize The process of loading a xmlstream into a hitlist.
For example: saving an occurrence can be blocked (return -1), or the value for a derived field can be calculated.
Pre Save Occurrence
Name <Pre SaveOccurrence>
Abbreviation PRSO
Level Entity
Activation The <Pre Save Occurrence> trigger is fired just before an occurrence is saved from a hitlist into a xml stream. The occurrence is available and can be examined.
Default action If no Proc code is present in this trigger, there is no action
Return Value The structure editor is not affected by the value of $status
Description Tunes the execution of xmlSave: Customize the process of saving a hitlist into a xmlstream.
For example: an occurrence can be excluded from the save or the value for a derived field can be calculated.
Post Save Occurrence
Name <Post Save Occurrence>
Abbreviation PSSO
Level Entity
Activation The <Post Save Occurrence> trigger is fired just after an occurrence is loaded from a xml stream into a hitlist
Default action If no Proc code is present in this trigger, there is no action
Return Value The structure editor is not affected by the value of $status.
Description Tunes the execution of xmlSave: Customize the process of saving a hitlist into a xmlstream.
For example: notification/ logging an occurrence for being saved.
UNIFACE 8 introduces new pre-compiler directives.
<$cmpStateManagedBy>
Corresponds to: server page/ session service component property 'State Managed By'
Values: 0 = none; 1 = by cookie; 2 = by state manager component
Use this directive to tweak your Proc code in the GETSTATE and SETSTATE triggers.
<$componentName>
Corresponds to:the component name.
Value:the component name.
Scope: component, entity and field triggers
<$componentType>
Corresponds to:the component type
Value:same as Proc function $componentType
Scope: component, entity, and field triggers
<$modelName>
Corresponds to:the entity's business object model
Value:the name of the entity's business object model
Scope: entity and field triggers
<$tableName>
Corresponds to:the entity's database table name, i.e the entity's supertype.
Value:the name of the entity's supertype.
Scope: entity and field triggers
<$entName>
Corresponds to:the entity name
Value:the entity name
Scope: entity and field triggers
<$fieldName>
Corresponds to:the field name name
Value:the field name
Scope: field triggers
<$triggerAbbr>
Corresponds to:trigger abbreviation
Value: start-up shell, component, entity and field triggers
Scope: all triggers
<$library>
Corresponds to:library in which a global object resides
Value: library name
Scope: include proc, global proc, menu triggers
/anm (Analyze Model)
Purpose: This command line switch is a synonym to the UNIFACE 7 command line switch /con (ee the UNIFACE library).
Syntax: similar to /con.
/ceo (Compile Entity Operations)
Purpose: This command line switch compiles entity occurrence operations and entity collection operations into the signature repository.
The entity occurrence interface (see the 'Define Entity' form) and its occurrence operations (see the Trigger Editor for model entities) are written in the signature repository as a signature. The name of the signature equals the name of the entity occurrence interface.
Similarly, the entity collection interface and its collection operation is written as a signature.
Why: Allow inter-component direct addressing of entity occurrence operations and entity collection operations. There are handles in Proc available for this purpose.
Syntax: /ceo {entityName{.applicationModelName}}
Note: in the second beta, the switch is yet named /ces.
/esv (Compile Entity Services)
Purpose: This command line switch compiles entity services.
Syntax: similar to /frm.
/ssv (Compile Session Services)
Purpose: This command line switch compiles session services.
Syntax: similar to /frm.
/dtd (Compile DTDs)
Purpose: This command line switch was introduced in UNIFACE 7.2.06 and compiles all DTDs in a particular business object model.
Syntax: /dtd {dtdName{.applicationModelName}}
/all /hts
Purpose: This command line combination was introduced in UNIFACE 7.2.05, in order to include HTML skeleton generation in a '/all' compilation.
The DLL name for a 3gl component can be specified in the signature editor, as part of the
implementation details for "C" call-out.
Then UNIFACE is able to find the entry points defined for that component without having to
specify the DLL in the [user_3gl] section of the .asn file.
If an operation contains parameters of data type 'handle' or 'xmlStream', then these can have a classification defined for.
For 'handle', this means: to which signature is the handle pointing.
For 'xmlStream' this means: which DTD is to be used.
For example:
operation foo
params
xmlStream [dtd: aDtd] x: in
handle clientCollection h: in
endparams
...
end ; foo
After compilation, the classification is shown in the signature repository. Yet, this is only to be used as a development aid, because UNIFACE does not yet support a strong typing model.
u8events.xml illustrates the use of:
How to use: