Creating Session Services

Every presentation layer component that deals with data from the physical database must do so by exchanging XML streams with a business layer component called a session service. Each entity defined in the Presentation Application Model (PAM) will have its own session service, therefore if several presentation layer components reference the same entity they can share the same session service.

Most session services will be of Type 1, but in certain circumstances more specialised session services will be required, such as those shown below.

CT3_SSV_1 - Session Service Type 1

This is the general-purpose session service that deals with a single entity in the PAM. It contains the following operations:

GETDATA - retrieve data from the database
PUTDATA - store data on the database
VALIDATE - validate a single field or an entire occurrence
VALIDATEKEY - validate a primary or candidate key
VERIFY_DELETE - verify that an occurrence can be deleted

To create the basic session service the component template will ask for the names of two entities:

PAM_ENTITY - enter the entity name from the Presentation Application Model
BAM_ENTITY - enter the entity name from the Business Application Model

Both entities are needed in the session service as the retrieve profile on the GETDATA operation may contain field names that need to be converted before they can be used to retrieve from the database.

Data Validation

In order to perform data validation you should use the normal <validate field> and <validate occurrence> triggers.

VERIFY_DELETE

If you wish to prevent an occurrence from being deleted if entries exist on subordinate entities then you must do the following:

Paint each of those subordinate entities as an inner entity in the component.
Include each of those entity names in the local proc LP_DONT_DELETE.
Disable the <delete> trigger for each of these entities.

Deleting occurrences from subordinate entities

If you wish to delete occurrences of subordinate entities when an occurrence of the main entity is deleted then you must do the following:

Paint each of those subordinate entities as an inner entity in the component.
Ensure the Delete Constraint on the relationship is set to Cascade.
Ensure the <delete> triggers of those entities contains the delete command.

Merging fields from other entities

By default it is assumed that each field on the PAM entity has a corresponding field on the BAM entity. If this is not the case, such as where the PAM entity contains a field that actually exists on another entity, you may resolve this in one of the following ways:

Paint the other entity in the component and resolve the naming difference with a mapping option.
Paint the other entity in the component, paint the relevant field as a non-database field in the BAM entity, then include code in the <read> trigger of the BAM entity to fill this non-database field. This will require code similar to the following:
```
variables
   string  lv_FieldName
   string  lv_FieldValue
endvariables

read options $options$ order by $order_by$

#include STD:AUDIT_BEFORELOOK

if ($status = 0) & ($operation$ = "GETDATA")

   getitem/id lv_FieldName, $SelectList$, "START_TRAN_DESC"
   if ($status > 0)
       setocc "MNU_TRAN",1
       START_TRAN_DESC.MNU_SECURITY = TRAN_DESC.MNU_TRAN
   endif

   $status = 0
endif
```
You will note that this refers to a component variable called $operation$ . This is filled with the relevant operation name by code in the <operations> trigger. This allows certain actions to be restricted to certain operations. The component variable $selectlist$ is used to check that field has actually been requested by the parent component before it is constructed.

CT3_SSV_2 - Session Service Type 2

This type of session service is used by presentation layer components of type MULTI_4a and MULTI_4b. These deal with an entity structure in the BAM that is shown in figure 1:

Figure 1 - a ONE-to-MANY-to-ONE relationship in the BAM

In this structure the MANY entity consists of nothing more than a primary key which is a combination of the two foreign keys. If an occurrence of MANY exists for a particular combination of the two foreign keys then it indicates that a link exists between those occurrences of the two foreign entities - If no occurrence exists then there is no link.

The presentation layer component will maintain occurrences of the MANY entity, but the entities contained within its structure are as shown in MULTI_4a and MULTI_4b.

This type of session service contains the following operations:

GETDATA - retrieve data from the database
PUTDATA - store data on the database

The component template will ask for the names of the following entities:

PAM_ENTITY - enter the entity name from the Presentation Application Model
ONE_A - enter the name of the OUTER foreign entity from the Business Application Model
MANY - enter the name of the MANY entity from the Business Application Model
ONE_B - enter the name of the INNER foreign entity from the Business Application Model

With the GETDATA operation this session service will expect a retrieve profile to be passed down which identifies a single occurrence from entity ONE_A (displayed as the OUTER entity in the presentation layer component). It will then retrieve occurrences of entity ONE_B subject again to the profile passed down from the parent component. For each occurrence of ONE_B it will do a lookup on entity MANY and set the checkbox to ON if an occurrence is found.

With the PUTDATA operation this session service will scan all occurrences and examine the state of the checkbox. If it is set to ON it will check that an occurrence of the MANY entity exists. If it is set to OFF it will check that an occurrence of the MANY entity does not exist.

NOTE: Entity ONE_A in the session service must be defined as entity OUTER in the presentation layer component that uses this session service. If another presentation layer component requires entity ONE_B to be the OUTER entity then this will require an additional session service of this type with entities ONE_A and ONE_B reversed. This will also require a different PAM entity for INNER which defines the additional session service as its Object Service.

CT3_SSV_3 - Session Service Type 3

This type of session service is used by a presentation layer component of type LIST_5. This deals with an entity structure in the BAM that is shown in figure 2:

Figure 2 - a ONE-to-MANY-to-ONE relationship in the BAM

In this structure there can be zero or more occurrences of the MANY entity for each pair of occurrences from entities ONE(A) and ONE(B). The different occurrences of MANY are usually sorted by something such as date or time.

The LIST_5 presentation layer component will only be able to show one occurrence of the MANY entity, so the $ORDER_BY$ option can be used to determine which is the first occurrence in the hitlist.

This type of session service contains the following operation:

GETDATA - retrieve data from the database

The component template will ask for the names of the following entities:

PAM_ENTITY - enter the entity name from the Presentation Application Model
ONE_A - enter the name of the OUTER foreign entity from the Business Application Model
MANY - enter the name of the MANY entity from the Business Application Model
ONE_B - enter the name of the INNER foreign entity from the Business Application Model

With the GETDATA operation this session service will expect a retrieve profile to be passed down which identifies a single occurrence from entity ONE_A (displayed as the OUTER entity in the presentation layer component). It will then retrieve occurrences of entity ONE_B subject again to the profile passed down from the parent component. For each occurrence of ONE_B it will then do a retrieve on entity MANY, but only pass back details of the first occurrence. The sort sequence contained in $ORDER_BY$ will determine which is the first occurrence in the hitlist.

CT3_SSV_4 - Session Service Type 4

This type of session service is used by a presentation layer component of type MULTI_5. This deals with an entity structure in the BAM that is shown in figure 3:

Figure 3 - a ONE-to-MANY-to-ONE relationship (with dynamic list) in the BAM

In this structure each occurrence of ONE(B) has its own set of occurrences on LIST(B). For each combination of occurrences from ONE(A) and ONE(B) there may be an occurrence of MANY which identifies where access to items on LIST(B) has been switched from their initial setting. MANY is actually a single occurrence which contains an indexed list of item names where this setting has been switched. An occurrence of MANY will only exist where this list of items is not empty. If an occurrence of ONE(B) does not have anything on LIST(B) then it cannot have any occurrences on MANY.

This component contains a constant called <initial_setting> which can be set to either '1' (ON) or '0' (OFF). Thus you can decide whether the settings start as ON and must be turned OFF, or they start as OFF and must be turned ON.

The structure of the parent MULTI_5 component is OUTER-to-INNER-to-LIST, where OUTER can either be ONE(A) or ONE(B) and INNER can either be ONE(B) or ONE(A). This means that the LIST entity can be a child of either ONE(A) or ONE(B). This is dealt with in the session service with a structure as shown in figure 4:

Figure 4 - the structure of the session service

This has a subtype of LIST(B) painted in the structure as an inner entity to ONE(A). This subtype is created in the Business model but does not need a relationship to ONE(A).

This type of session service contains the following operations:

GETDATA - retrieve data from the database
PUTDATA - store data on the database

The component template will ask for the names of the following entities:

PAM_ENTITY - enter the entity name from the Presentation Application Model
ONE_A - enter the name of the OUTER foreign entity from the Business Application Model
MANY - enter the name of the MANY entity from the Business Application Model
ONE_B - enter the name of the INNER foreign entity from the Business Application Model
LIST_B - enter the name of the LIST(B) entity from the Business Application Model
LIST_B_SUBTYPE - enter the name of the LIST(B) subtype from the Business Application Model

With the GETDATA operation this session service will expect a retrieve profile to be passed down which identifies a number of occurrences from entity MANY. It will then expect to retrieve a single occurrence of both ONE_A and ONE_B, followed by a number of occurrences from LIST_B. For each occurrence of LIST_B it will set the ACCESS_FLAG to the value of <initial_setting>, then reverse this switch if that occurrence is identified in the indexed list held on MANY. It will then copy the details from LIST_B to LIST_B_subtype.

With the PUTDATA operation this session service may receive its updates via LIST_B_SUBTYPE in which case it will copy them over to LIST_B. It will the clear the indexed list on MANY and reconstruct it according to the current values of ACCESS_FLAG on each LIST_B occurrence. If the value of ACCESS_FLAG has changed from <initial_setting> then details of that occurrence will be added to the list. An occurrence of MANY will only be written out if the indexed list is not empty.

NOTE: the DTD for this type of session service consists of three entities which are shown as MANY-to-INNER-to-LIST in the presentation layer component MULTI_5. The INNER entity can either be ONE_A or ONE_B, so each of these combinations will require a different DTD and therefore a different PAM entity and session service. Regardless of which PAM entity is used the BAM entities in this session service will be painted with the same structure (i.e. it will not be necessary to reverse the order of ONE_A and ONE_B).

http://www.tonymarston.net