Daniel Becker Bighelini

SPEL API: BOP - Schema - Majic

Blog Post created by Daniel Becker Bighelini on Jun 13, 2016

Chapter 3

BOP - Schema - Majic

 

 

Table of Contents

 

Chapter 3                                                                                                    1

BOP - Schema -Majic                                                                                 1

  1. I. Overview                                                                                                 3
  2. II. Syntax Notation                                                                                  4
  3. III. Objects Statement                                                                            5
  4. A. Attributes Statement................................................................................................................................. 7
  5. 1. Value Attribute Statement...................................................................................................................... 8
  6. a. Object Trigger Statements .................................................................................................................. 9
  7. b.  Triggers on Attributes...................................................................................................................... 10
  8. 2. QRel Attribute Statement...................................................................................................................... 11
  9. a. Parameter Names Statement............................................................................................................. 12
  10. 3. BRel Attribute Statement...................................................................................................................... 12
  11. B. Methods Statement.................................................................................................................................. 14
  12. C. Triggers Statement for Objects........................................................................................................... 16
  13. D. Factory Statement................................................................................................................................... 19
  14. 1. Factory Domset Statement.................................................................................................................... 19
  15. a. Order by Statement............................................................................................................................ 21
  16. 2. Relational Attribute Statement............................................................................................................ 21
  17. 3. Common Name Statement.................................................................................................................... 21
  18. 4. Function Group Statement.................................................................................................................... 21
  19. 5. Standard Lists Statement...................................................................................................................... 22
  20. a. Sort By Statement.............................................................................................................................. 23
  21. b. Fetch Statement.................................................................................................................................. 24
  22. c. MLIST Statement............................................................................................................................... 24
  23. d. RLIST Statement................................................................................................................................ 24
  24. 6. Restrict Statement.................................................................................................................................. 25
  25. E. Event Statement....................................................................................................................................... 26
  26. F. Display Name Statement........................................................................................................................ 26
  27. G. Cache Size Statement............................................................................................................................. 26
  28. IV. LRel Statement                                                                                 27
  29. A. Left Maximum Statement...................................................................................................................... 27
  30. B. Right Maximum Statement.................................................................................................................... 27
  31. V. Common Statements                                                                         28
  32. A. Where Clause........................................................................................................................................... 28
  33. B. Order_by Clause...................................................................................................................................... 28
  34. C. Domset Clause.......................................................................................................................................... 29
  35. D. Maximum Fetch Clause.......................................................................................................................... 29
  36. VI. Modification Statements                                                               30
  37. A. Attribute Modification Statements...................................................................................................... 30
  38. B. Modify Factory Statement..................................................................................................................... 31
  39. 1. Standard Lists Statement...................................................................................................................... 31
  40. C. Modify Business Object syntax............................................................................................................ 31
  41. VII. Example .maj File                                                                             33
  42. VIII. Triggers at execution time                                                         34
  43. A. Overiew...................................................................................................................................................... 34
  44. B. Object Triggers........................................................................................................................................ 36
  45. 1. NEW_INIT.............................................................................................................................................. 36
  46. 2. DB_INIT.................................................................................................................................................. 36
  47. 3. PRE_VALIDATE.................................................................................................................................... 37
  48. 4. POST_VALIDATE................................................................................................................................. 37
  49. 5. POST_CI.................................................................................................................................................. 38
  50. C. Attribute Triggers................................................................................................................................... 39
  51. 1. ON_PRE_VAL........................................................................................................................................ 39
  52. 2. ON_POST_VAL..................................................................................................................................... 40
  53. 3. ON_POST_VAL_ASYNC..................................................................................................................... 41

lB. Object Triggers

l1. NEW_INIT

This is executed prior to the creation (as opposed to instantiation) of an object. It is here that one can do complex initial default calculations for a new object.  This is a serial trigger.  Execution will not proceed until the trigger returns.

 

 

Arguments:

The function you define for the trigger is called with an array of triplets which correspond to the attributes you defined in majic.  Each element of the triplet consists of the attribute name, the 'old' value, and the 'new' value.  Old is the 'original' and new is the 'changed'. 

            (string attr_name, value old_val, value new_val) []

 

 

Reply:

For the reply, you provide the attributes you want to set, and what the value to set should be.  An error return is not supported.  Do not attempt to change the attributes using a 'this' pointer;

            (string attr_name, value change_val)[]

Note:   There is NO context here.  Do not attempt to access the dob.  It does not exist.  Ignore the 'new_val' in the input arguments.

l2. DB_INIT

This is executed prior to instantiation.  At this point the backstore has been asked for data, and you have a chance to add any attribute values you wish.  This is the last chance for initialization after reading values from the database.  This is a serial trigger.  Execution will not proceed until the trigger returns.

 

 

Arguments:

The function you define for the trigger is called with an array of triplets which correspond to the attributes you defined in majic.  Each element of the triplet consists of the attribute name, the 'old' value, and the 'new' value.  Old is the 'original' and new is the 'changed'. 

            (string attr_name, value old_val, value new_val) []

 

 

Reply:

For the reply, you provide the attributes you want to set, and what the value to set should be.  An error return is not supported.  Do not attempt to change the attributes using a 'this' pointer;

            (string attr_name, value change_val)[]

Note:   There is NO context here.  Do not attempt to access the dob.  It does not exist.  Ignore the 'new_val' in the input arguments.

l3. PRE_VALIDATE

This is executed prior to a validate/checkin.  It is here that one can modify the values prior to a checkin. This is a serial trigger. Execution will not proceed until the trigger returns.

From your function you can typically do two things.  Either simply return an error code saying that the validation check has failed, or you can modify attributes using the 'this' pointer.

 

 

Arguments:

The function you define for the trigger is called with an array of triplets which correspond to the attributes you defined in majic.  Each element of the triplet consists of the attribute name, the 'old' value, and the 'new' value.  Old is the 'original' and new is the 'changed'.

(string attr_name, value old_val, value new_val) []

 

 

Error Reply:

Set error_code != 0, put a string error_text in msg[0]

 

 

Success Reply:

Set error_code == 0

 

 

Notes/Side Effects:

You are in the exclusive session of the group leader doing the checkin (CI) when you get this call.  We make a Dob just for your use on this function.  Do not attempt to save the 'this' pointer.

 

l4. POST_VALIDATE

This is executed after the validate pass, and prior to the saving of the changes. It is here that one can do additional modifications of attributes before it is written to the database.  This is a serial trigger.  Execution will not proceed until the trigger returns.

From your function you can typically do two things.  Either simply return an error code saying that the validation check has failed, or you can modify attributes using the 'this' pointer.

 

 

Arguments:

The function you define for the trigger is called with an array of triplets which correspond to the attributes you defined in majic.  Each element of the triplet consists of the attribute name, the 'old' value, and the 'new' value.  Old is the 'original' and new is the 'changed'.

(string attr_name, value old_val, value new_val) []

 

 

Error Reply:

Set error_code != 0, put a string error_text in msg[0]

 

 

Success Reply:

Set error_code == 0

 

 

Notes/Side Effects:

You are in the exclusive session of the group leader doing the checkin (CI) when you get this call.  We make a Dob just for your use on this function.  Do not attempt to save the 'this' pointer.

l5. POST_CI

This is executed to notify a change of value.  This is an asynchronous trigger.  You do not reply.

You can do virtually nothing from this function except fire off notifications, set events, etc.

 

 

Arguments:

The function you define for the trigger is called with an array of triplets which correspond to the attributes you defined in majic.  Each element of the triplet consists of the attribute name, the 'old' value, and the 'new' value.  Old is the 'original' and new is the 'changed'.

(string attr_name, value old_val, value new_val) []

 

 

No Reply's:

 

 

Notes/Side Effects:

This is an asynchronous only call.  There is NO 'this' pointer, and you do not get a change to respond in any way.

 

lC. Attribute Triggers

l1. ON_PRE_VAL

This is executed during a set on an attribute.  This function is intended to allow you to check that what is entered is valid.  It also gives you a way to coerce the value being set to some other value without calling the validate triggers.

You will typically either fail the change, causing an error, or you can coerce the value to some other value and continue.  If we did not coerce the value, we would do another ON_PRE_VAL and things get nasty quickly.

 

 

Arguments:

The function you define for the trigger is called with a bunch of stuff for the attribute, then the standard array of attribute triblets you passed in as part of the majic definition.

attr_name            attribute name for attribute being set

attr_val.orig        original attribute value (could be in the db)

attr_val.last attribute value prior to set

attr_val.new        value passed with set_attr message

set_val_smag      smag value from the set_attr message

group_leader      object reference for a group leader or NIL

(string attr_name, value old_val, value new_val) []

 

 

Error Reply:

Set error_code != 0, put a string error_text in msg[0]

 

 

Success Reply:

            Set error_code == 0

 

 

Success Reply - and coerce the set_val to a new value:

            Set error_code == 0;

            set msg[0] to the new value

l2. ON_POST_VAL

This is executed to notify of a change to an attribute, IE it has passed all validation steps.  This is a serial trigger.  Execution will not proceed until the trigger returns.

What you do here is to perhaps set other attributes based on the value just set, etc using the 'this' pointer..

 

 

Arguments:

The function you define for the trigger is called with a bunch of stuff for the attribute, then the standard array of attribute triblets you passed in as part of the majic definition.

attr_name           attribute name for attribute being set

attr_val.orig       original attribute value (could be in the db)

attr_val.last        attribute value prior to set

attr_val.new        value passed with set_attr message

set_val_smag        smag value from the set_attr message

group_leader        object reference for a group leader or NIL

(string attr_name, value old_val, value new_val) []

Example, call manager has

ON_POSTVAL build_combo_name(last,first,middle);

but routine names argv[9], argv[12], and argv[15]. ???

 

 

Error Reply:

            No error reply is possible.

 

 

Success Reply:

            Set error_code == 0

 

 

Notes/Side Effects:

A Dob reference is passed in the synchronous case.  No return errors possible.

l3. ON_POST_VAL_ASYNC

This is executed to notify of a change to an attribute, IE it has passed all validation steps.  This is an async trigger.  Execution will proceed immediately and will not wait for a reply.

What you do here is to perhaps set other attributes based on the value just set, etc using the 'this' pointer..

 

Arguments:

The function you define for the trigger is called with a bunch of stuff for the attribute, then the standard array of attribute triblets you passed in as part of the majic definition.

      attr_name          attribute name for attribute being set

      attr_val.orig       original attribute value (could be in the db)

      attr_val.last        attribute value prior to set

      attr_val.new      value passed with set_attr message

      set_val_smag     smag value from the set_attr message

      group_leader     object reference for a group leader or NIL

      (string attr_name, value old_val, value new_val) []

 

 

Reply:

None supported.

 

 

Notes/Side Effects:

There is no Dob reference passed.

 

Majic Keywords

ABORT                        Used in Trigger Statements.

ATTRIBUTES              See Attribute Statement.  There are three types of attributes: value, QRel, and BRel.

BREL                           See BRel Attribute Statement.  A BRel attribute is a "back" query attribute, that is, it is the obverse of a SRel attribute.

COMMON_NAME       See Common Name Statement.  See Factory Statement for use.

CONST                        Used in Value Attribute Statement.

DATE                          Used in Value Attribute Statement.

DB_INIT                      Used in Trigger Statement.

DEFAULT                    Used in a Built-in Attribute Trigger Statement.

DOMSET                     See Domset Statement.  See QRel Attribute, BRel Attribute, and Modify QRel Attribute Statements for use.

                                    Also see Factory Domset Statement. 

                                    A domset is a collection of instances of an object.

DOUBLE                     Used in Value Attribute Statement.

DURATION                 Used in Value Attribute Statement.

DYNAMIC                   Used in QRel Attribute, BRel Attribute, Factory Domset, Modify QRel Attribute, and Modify BRel Attribute Statements.

EVENTS                      See Event Statement.

FACTORY                   See Factory Statement.  A factory is the entity that is responsible for the building of objects and collections of objects.

FILTER                        See Trigger Statement.  A filter is a further refinement to determining whether to execute a trigger.

FUNCTION_GROUP    See Function Group Statement.  This is a security kludge.

IGNORE                      Used in Trigger Statements.

INTEGER                     Used in a Value Attribute Statement.

LEFT_MAX                 See Left Maximum Statement.  See LRel Statement for use.

LOCAL                        See Value Attribute Statement.  Indicates a local spell method.

LREL                           See LRel Statement.  An LRel represents a relation between two objects.

MAX_FETCH              See Maximum Fetch Statement.  See QRel Attribute, BRel Attribute, Factory Domset, Modify BRel Attribute, and Modify QRel Attribute Statements for use.

MLIST                         See MLIST Statement.  See Factory and Modify Factory                                Statements for use.

METHODS                   See Methods Statement.  A method is a late bound method.

                                    There are two types of methods, local and remote.

MODIFY                      See Modify Statements.

NEW_INIT                   Used in Trigger Statement.

NOT_REQUIRED         Used in Value Attribute and Modify Value Attribute Statements.

NOT_SHARED            Used in Factory Domset Statement.

OBJECT                       See Object Statement.  An object is a business object of interest to an application that can be reflected or not in a back store.

ON_CI                         Used in a Built-in Attribute Trigger Statement.

ON_DB_INIT               Used in a Built-in Attribute Trigger Statement.

ON_NEW                     Used in a Built-in Attribute Trigger Statement.

ON_PRE_VAL             Used in Attribute Trigger Statement.

ON_POST_VAL           Used in Attribute Trigger Statement.

ON_POST_VAL_ASYNC  Used in Attribute Trigger Statement.

ORDER_BY                 See Order By  Statement.  See QRel Attribute, BRel

                                    Attribute, Modify BRel Attribute, Modify QRel Attribute Statements, and actory Domset Statement for use.

PARAM_NAMES         See Attribute Names Statement.  See QRel Attribute and Modify QRel Attribute Statements for use.

PDM                            Used in Object Statement.  Indicates a Paradigm object.

POST_CI                      Used in Trigger Statement.

POST_VALIDATE       Used in Trigger Statement.

PRE_LOAD                  Used in Factory Domset Statement.

PRE_VALIDATE         Used in Trigger Statement.

PRIVATE                     Used in Value Attribute Statement.

PUBLIC                       Used in Value Attribute Statement.

QREL                           See QRel Attribute Statement.  A QRel attribute         represents a query.

REL_ATTR                  See Relative Attribute Statement.  See Factory Statement for use.

REMOVE                     See Remove MLIST and Remove Domset Statements.

REQUIRED                  Used in Value Attribute and Modify Value Attribute Statements.

RESTRICT                   See Restrict Statement.  See Factory Statement for use.

RIGHT_MAX               See Right Maximum Statement.  See LRel Statement for use.

SET                              Used in a Built-in Attribute Trigger Statement.

SHARED                      Used in Factory Domset Statement.

SQL                             Used in Object Statement.  Indicates a back stored object.

SREL                           Used in Value Attribute Statement.  A SRel attributerepresents a single relationship.

STATIC                       Used in QRel Attribute, BRel Attribute, Factory Domset, Modify QRel Attribute, and Modify BRel Attribute Statements.

STRING                       Used in Value Attribute Statement.

TRIGGERS                  See Trigger Statement.  A trigger is a method that is executed at specific points in the life of an object.

VALUE                        See Value Attribute Statement.  A value attribute is an attribute of either double, duration, integer, string, date, or SREL value type.

WHERE                       See Where Statement.  See QRel Attribute, BRel        Attribute, Factory Domset, Modify BRel Attribute, and Modify QRel Attribute Statements for use.

WRITE_NEW               Used in Value Attribute Statement.

Outcomes