Daniel Becker Bighelini

SPEL API: Domain Server Public Messages

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

Chapter 5

Domain Server Public Messages

 

Table of Contents

Overview                                                                                                   

Table of Methods                                                                                                                                            

Understanding method classes                                                                                                                     

MTH: Base class for all objects                                                       

Public Methods:                                                                                                                                           

Private Methods:                                                                                                                                       

OB:WLNK:MTH: A distributed object                                                 

Public Methods:                                                                                                                                        

Private Methods                                                                                                                                        

PATTR:OB:WLNK:MTH: - Distributed object with attributes      

Public Methods:                                                                                                                                        

Private Methods:                                                                                                                                       

TOP:ATTR:OB:WLNK:MTH: Top object                                                 

COGP:OB:WLNK:MTH: checkout/checkin object                             

Public Methods:                                                                                                                                        

Private Methods:                                                                                                                                       

FAC:NC:ATTR:OB:WLNK:MTH: The Factory Object.                          

Public Methods:                                                                                                                                        

Private Methods:                                                                                                                                       

DSET:ATTR:OB:WLNK:MTH: The Domset Object                                

Methods:                                                                                                                                                     

PDOB:PATTR:OB:WLNK:MTH: The Dob                                                   

Public Attributes:                                                                                                                                      

Public Methods:                                                                                                                                        

Private Methods:                                                                                                                                       

PAT:MTH:  Base class for all attributes                                       

Public Methods:                                                                                                                                        

Private Methods:                                                                                                                                       

VLAT:PAT:MTH: An un-modifiable value attribute                        

Public Methods:                                                                                                                                        

Methods in Detail                                                                                                                                      

RW:VLAT:PAT:MTH:- A modifiable value attribute                        

Public Methods:                                                                                                                                        

SREL:PAT:MTH: An srel attribute.                                                     

Public Methods:                                                                                                                                        

* Private Methods:                                                                                                                                    

QREL:PAT:MTH: An srel attribute.                                                    

Methods:                                                                                                                                                     

PLREL:PAT:MTH: An lrel attribute.                                                   

Attributes:                                                                                                                                                  

Warm Links:                                                                                                                                              

Methods:                                                                                                                                                     

* Private Methods:                                                                                                                                    

APPENDIX                                                                                                   

Access_type is one of :                                                                                                                            

required_flag is one of                                                                                                                             

CHECKOUT:                                                                                                                                              

GETTING A NEW OBJECT (DOB)                                                                                                        

CHECKIN on 2 pdobs.                                                                                                                              

Error Codes                                                                                           

The following is for m'soft                                                                                                                       

Errors in the domain server                                                                                                                     

Errors for Animation                                                                                                                                

 

 
 

Overview

 

This document is intended to document the messages in the domsrvr.  It is primarily intended to be used by a bop application programmer to understand what messages the domsrvr will understand and respond to.

Special Interfaces, * and +

It also incorporates deeper information so we can have a summery in one place.  These items are noted by a '*' as the first character (such as this paragraph).  The end user should IGNORE any information started with a *;

Information preceded with a '+' is not typically used by the end user.  They are included for completeness but can usually be ignored.

Before this document will make any sense to you you need some concept of what the domsrvr is, some idea of how messaging works in bopland.  This is covered in the introduction to the system, and in the tutorials.

 

 
 

Table of Methods

 

* Note - this table does NOT contain the private and semi-private  methods

 

MTH: - Base class for everything

                        method_list()                          Provide a list of methods for this class

                        get_class_name()                   Provide the full class name for this object

                        type_info()                              provides some type info.

                        info()                                       Miscelaneous information about the object

                        call_base()                              Way to call a base method, not the derived one

OB:WLNK:MTH: - An object which is a distributed object.

                        get_bpobj()                             Return a Object_Ref for this object

PATTR:OB:WLNK:MTH: - A (distributed) object which has attributes

                        attr_list() return a list of all attributes for the object

                        attr_type_info()                       return type_info about an attribute

                        get_attr()                                 Get an Object_Ref

                        call_attr()                                Dispatch a message to the attribute.

                        is_co()                                     REply if the object is checked out or not

                        get_gl()                                   Return the group leader if checked out

TOP:ATTR:OB:WLNK:MTH:  - The 'Top' object or initial entry point in

                        get_co_group()                       return a list of all attributes for the object

                        get_unique_id()                      return type_info about an attribute

COGP:OB:WLNK:MTH: - The object that handles checkout / checkin etc

                        checkout()                               request a checkout to be done

                        checkin()                                 Request that value changes be saved

                        uncheck()                                Abandon all changes

FAC:NC:ATTR:OB:WLNK:MTH: - The Factory Object.

                        get_domset_list()

                        domset_info()

                        get_domset()

                        dob_by_persid()

                        get_new_dob()

                        get_null_dob()

                        dob_attr_list()

                        dob_attr_type_info()

                        dob_attr_info()

                        dob_info()

                        sync_fetch();

                        info()

                        val_by_key( attr_key_name, key_val, num_attr, attr_desired ...)

DSET:ATTR:OB:WLNK:MTH: - The Domset Object

                        empty()                                   Clear out the domset

                        fetch()                                     Start a fetch of new data

                        fetch_more()                           Continue a fetch

                        dob_by_key()                         get a dob based on key

                        + closest_dob_by_key()         get the closet dob to the key

                        dob_by_index()                      get a dob based on index.

                        + index_by_key()                   get the index based on the key passed in

                        + closest_index_by_key()      Get the closeest index based on key

                        display_by_index()                Get the quick display fields via index

                        persid_by_index()                  Get the persid for a particular row.

                        domset_remap()                     Repoint the public domset to a new list

                        get_where()                            Get the where clause we are using

                        get_storage_where()               Get the parsed where clause.

                        merge()                                   merge data into an existing domset

                        + subscribe_mods()                Ask to be told of changes

                        + unsubscribe_mods()            Remove interest

                        + set_interest_range()            Set an interest for changes

                        type_info()                              Overides the virtual type_info

PDOB:PATTR:OB:WLNK:MTH: - The Dob or Domain or Business Object.

                        dob_mark_delete()                 Mark the dob as deleted.

                        dob_remap()                           re-point the public interface to a new dobo

                        type_info()                              Give some info on the dob.

PAT:MTH:          - Base class for all attributes

                        + subscribe_hot()                   Set up a hotlink

                        + unsubscribe_hot()               clear a hotlink

                        is_checkout()

VLAT:PAT:MTH: - A value attribute that is not modifiable.

                        get_val()                                 get the current value

RW:VLAT:PAT:MTH:- A modifiable value attribute.

                        set_val() get the current value

SREL:PAT:MTH:              - An srel attribute.

                        get_val() get the current value

                        set_val() set the rel_attr to a new value

                        get_dob() Get the dob associated with the attr.

                        get_attr() Get object pointer for an attribute in the srel dob

                        call_attr() Call an attr in the srel dob

QREL:PAT:MTH:              - An srel attribute.

                        call_attr()

                        get_attr();

PLREL:PAT:MTH:             - An lrel attribute.

                        add_dob()

                        remove_dob()

                        move_dob()

                        get_attr()

                        call_attr()

                        + subscribe_mods()

                        + unsubscribe_mods()

                        persid_by_index()

 
 

Understanding method classes

 

When talking about the messages the domsrvr understands, there are several places where you can get tripped up.

 

The first is that these are not function calls, although we document an tend to think of them as if they were.  They are async messages that call a method on the target object.  Each message contains a reply object and method_name to call on the reply.  Most methods you call on the domsrvr will send a reply to the reply object/method. In all cases, the reply is in the form of a message, and that message may contain many combinations of arguments. 

 

Things get somewhat complex due to inheritance.  Any object that messages can be delivered to is typically derived from some base class object which handles some of the methods.  We can identify these base class methods by examination of the class name of the object.  For example, a Domset object's class name is DSET:ATTR:OB:WLNK:MTH:.  This means it understands methods defined in ATTR:OB:WLNK:MTH:, :OB:WLNK:MTH:, etc.  As in any inheritance mechanism, methods may be overidden by the derived class.  All methods in the domsrvr world act like virtual's.  IE you can send the message to a method name without concern for what kind of object it is. If you want to call a method of the base class, there is a way to do this as well.

 

The public/private metaphor is also a point of confusion.  The domsrvr makes extensive use of access objects that hide the actual implemtation from the user.  This document combines information about public and private methods and objects. Any section beginning with an '*' is private and MUST NOT be used by the application programmer!! Indeed if we produce a prettier version of this document for public consumptuion, we will remove those sectuions.

 

Each method is presented in the form of a function with arguments.  Due to the messaging structure, we allow optional arguments and varying arguments.  These are shown with brackets, pipes, etc.  One notation construct is non-obvious.  We often pass lists of information back and forth.  Each element in the list may contain multiple pieces of data. Example:

String arg1,

    (String e1, int e2)[]

The first element in the method will be a string, and it will be arg1.  The second element is the number of e1, e2 pairs that will be in the message.  The third to N argument are the elements of the array.

 

Most of the methods reply one time - immediately.  Some of them don't reply at all.  Some make multiple reply's.  Some define a contract for future messages to be sent back.  For reply's we always use the reply object/method in the message. For defining a contract, we use paramaters in the data portion of the message. 

 

Errors are handled by returning a non-zero error code.  (This is stored in the message).  Typically we also stuff a string in arg[0] which provides text information for the problem.  Exceptions to this should be noted in the document, however this is not guaranteed in all cases.  All error returns are not shown for every method descriptions.  For instance any method will return an error if the arguments are incorrect.  If the message is not defined, etc.  These errors are never noted in the method definition but can always be returned. They are noted here.

            E_BAD_LIST_TYPE            

            E_BAD_ARG_TYPE

            E_TOO_MANY_ARGS

            E_INSUFFICIENT_ARGS

            E_UNKNOWN_MESSAGE

            E_INTERNAL

The error codes are enum values.  These can be found in the appendix.

We have several data types that are supported.  In reality all are derived from BPData.  If we don't know what kind of data type the user may pass, we will typically refer to BPData.  The standard concrete data types of string.  integer, duration are supported.  If any concrete data type is ok, we will notate as 'value'. Additionally we have the type of Object_Ref.  This is a reference to some distributed object.  Please also note that integers are 32 bits.

 

Several of our methods talk about 'persistant_id'.  This is a string which uniquely identifies an instance of some business object.  It includes object type information as well as a unique id.  The format of a persistant id is expected to change, at this point is consists of the producer name, a ':' and the integer database id.

 
 

MTH: Base class for all objects

This is the base class for everything.  All objects have these methods.

Public Methods:

method_list( void )

 

Provides a list of all of the methods for the object. 

 

Arguments

none

On Error

none

On Success

( String method_name) [ ]

           

 

get_class_name( void )

Returns the full class name of the object.  This is the name such as DSET:ATTR:OB:WLNK:MTH:  which defines the object.

 

Arguments

none

On Error

none

On Success

String class_name

 

type_info( void )

Call to return type information about an object.  This method acts like a virtual to return type some brief information about an object.  The type_inf_reply for all types of objects is defined at the end of this document under the Reference section.

Arguments

none

On Error

none

On Success

String type_info_reply

NOTE - this method should only be called on the derived class where the reply is meaningful.  See the reference section under type_info for a summary of all the various returns from this function.

 

info( string request_type, ... )

We discovered that type_info was not enough, so we added the info call. The info call is intended as the primary user interface for information as to the objects, whats happening with them, etc.  It is used for reporting, status, etc.  You supply a request_type with optional arguments, and get a reply of information. This call is also extended in the derived classes.  However the request_types that are defined in a base class are available to the derived class as well.

Arguments

 

On Error

 

On Success

 

 

Arguments:

The request_type string defines the type of info requested.  Each level in the class hierarchy can define additional request types. Each request type may have it's own additional paramaters, and has it's own return format.  For documentation we will define each request type separately.

Valid request types for MTH: are:

TYPE                          Does a type_info call on the class.

                                    Reply:                            See type_info

CLASS_NAME          Does a get_class_name on the class.

                                    Reply:                            See get_class_name

* IS_BPOBJECT          Tells us if the object is a BP object.  IE capable of receiving messages 'over the wire' directly.

                                    Reply:                            String "TRUE" | "FALSE" 

                                    // True means it is a BPObject, FALSE means not a BPObject

IS_ATTR                    Tells us if the object recieving the message is in the attribute class.

                                    Reply:                            String "TRUE" | "FALSE" 

                                    // True means it is an Attribute, FALSE means not

METHOD_LIST         Does a method_list call

                                    Reply:                            See method_list

*METHOD_INFO      Does a method_info call

                                                Reply:                            See method_info

                TRIGGER_TYPES

Each object may have triggers associated with it (although they don't make much sense for many objects, so this may move somewhere else later!!) This returns a list fo the trigger types whech have triggers defined for them.  You can combine this call with a TRIGGGER_INFO call to get information on a specific trigger type.

                        Reply:

                            (String trigger_type_name)[]

                TRIGGER_INFO  trigger_type_name

Return information about the trigger type for this object.  trigger_type_name is one of CI_PRE_VAL, CI_POST_VAL DOB_POST_CI NEW_INIT DB_INIT ATTR_SET_VALIDATE ATTR_SET_NOTIFY.  The types_names is as returned in the TRIGGER_TYPE call.

                Reply:

                            String trigger_type_name,    // the type

                            (String address_node, // Slump address to send to

                             String address_proc_name, // Slump address to send to

                             String address_obj_name, // Slump address to send to

                             String method_name,         // BPMessage name

                             int ordinal,                       // who to fire first

                             String fire_condition, // See Filters in Trigger Doc

                             String params,                    // params to pass

                             String sync_type,                // one of "SYNC TIMEOUT=WARN"

                                                                         // "ASYNC" or

                                                                         // "SYNC TIMEOUT=ERRROR"

                             int timeout_in_secs) []   // How long to wait for sync

                                                                         // reply.

                           )

 

                           See Trigger documentation for a better idea of what these parameters mean.

 

    call_base ( string class_name, string method_name, ...)

 

        If you want to call a method in a specific base class, you can use this method to do it.  This method re-directs to the named method in the class name.

Arguments:

            string class_name,                 The base class name to use.  IE OB:WLNK:MTH:

            string method_name,             The method name in the base class to call

            ...                                 The arguments of the method name you are calling

Reply:

            Whatever the method_name returns.

Private Methods:

 

* method_info( void )

Provides a list of all of the methods for the object. 

Arguments

none

On Error

none

On Success

( String method_name) [ ]

 

* status_info( void )

obsolete call to get status information about an object.  This was never fully implemented and will be removed in the future.

 

Arguments

none

On Error

none

On Success

String of status information

 

 
 

OB:WLNK:MTH: A distributed object

 

This is the class which supports an object which is distributed.  IE it can recieve BPmessages.  You may note that there is no WLNK:MTH:  class This naming is an artifact of some earlier design flaws. This implies that the class names may change in the future.

Public Methods:

get_bpobj( void )

You can get messages to an object by indirect ways, such as call_attr, or you can send messages directly to an object.  This method returns an  Object_Ptr you can use to directly access an object in future calls.

            This method is not used too often.

Arguments

none

On Error

none

On Success

Object_Ref object    // The BPObject you may talk to.

Private Methods

 

* ob_checkout (Object_Ref group_leader)

 

When we want to co, the group leader sends the actual request to the object to checked out. He sends the request to the object. The default object sends it to it's parent, if it knows how to co, it handles it.

 

If there is a 'parent' IE this is an attribute, we forward to the parent object unchanged.  The parent derives it's own ob_checkout handler to manage it.  If there is no parent:

Arguments

Object_Ref group_leader                                           The group leader for the CO

On Error

No Parent Reply:

   String "NO_CO",                // Error string.

    Object_Ref this                                                                   // Who got the message

On Success

( String method_name) [ ]

 

 

* spl_eval (string code, ... )

Executes the string as spell code using this object as context.  The string must start be of the form "( [type arg [, ...]]) { ...    }"

Any other arguments in the calling message are treated as parameters passed to the function defined by the code string.

Arguments

 

On Error

For an error in the syntax:

        E_INVALID -  string description_of_error

On Success

Whatever the spell code sets using set_return_data

 

 

 

* spl_check_syntax (string code )

            Parse the code string to validate it.

Arguments

none

On Error

none

On Success

void

 
 

PATTR:OB:WLNK:MTH: - Distributed object with attributes

 

This class is any object that has attributes (such as those defined in a maj file).  We can get a list of the attributes, get information about them, call the attribute, etc.  This class is used for virtually all of the non-attribute classes in the system. It is used in Dobs, Domsets, Top, Factory, etc.

 

This is a place where we are simplifying what goes on a bit.  The PATTR is really the private class.  Not mentioned is the public class which really dispatches the messages to the appropriate private class.  From the end user the public class seems to be this private class which is why we have documented it this way.  Any class name whith a 'P" in the beginning typically follows this convention.

 

We introduce the ideas of warm links, and checkouts with this class.  Warm links are a way for an object to notify interested parties of state changes within itself.  When one of these pre-defined state changes occurs, the object will send a message to anyone who has asked for a warm_link on that state change event.

 

Checkouts are our way of handling locking and revision control.  In order to make a change to an object, you need to check it out against a group leader. Think of a group leader as an object which keeps track of a set of objects that are being modified.  Objects that share the group leader will see the changes immediately.  Objects that do not share the group leader will see the changes when a checkin occurs. (IE saved to disk).

 
 

Public Methods:

attr_list( void )

All objects of this class have attributes associated with them.  You need to be able to find the names of the attributes so you can send messages to them, etc.  This call does that for you.  It returns a list of all the attributes in the object that are defined in a .maj file.

Arguments

none

On Error

none

On Success

( String attr_name) []                                                    // A list of attribute names

 

attr_type_info( string attribute name )

Return type information about this attribute.  The results of this call vary based on the attribute that is really handling the call.  See the derived class for information as to what it puts out.

This method is equivalent to a type_info on the named attribute.  See the attr_info documentation for what is in the reply.

Arguments

string attributte_name                                                  Who to ask for

On Error

For an internal error:/                E_INTERNAL - "INTERNAL ERROR"

For a bad attribute name:

        E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

On Success

Depends on the attribute type.  See derived type_info_reply;

 

get_attr( string attribute name )

If you will be making lots of calls to an attribute, you usually want to get a reference for the attribute instead of always using the call_attr method. This is a call to get a reference to an attribute that you can use to call it directly.

This actually makes a dirstributed access_object for directly accessing the attribute.

The attribute name can of course contain a dotted name.

Arguments

string                   attribute_name                                 Who to ask for

On Error

For a bad attribute name

E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

On Success

Object_Ref attr_ref      // The reference for the named attribute

 

call_attr( string attribute_name,

                       string method_to_call, ... )

If you have an object that has attributes, you can send messages to the attribute using this function.  Basically it finds the attribute, creates the message to send to it, and dispatches the new message to the attribute.  There is a slight performance penalty over calling the attribute directly if you have a reference for it, but you avoid the overhead of the get_attr() call.

Arguments

string attribute_name, Attribute name to send message to

string method_to_call, Message name to use.

On Error

For a bad attribute name,

E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

On Success

Depends on what the dispatched method returns.  This function itself returns no reply except for errors.

 

 

is_co( void )

A call to ask if the object is checked out or not.  If the object is incapable of being checked out, it will reply as not checked out.

Arguments

none

On Error

 

On Success

For checked out object,                                                   string "IS_CO"

For non checked out object,                                            string "NOT_CO"

 

 

get_gl( void )

If the object is checked out, this call returns the group leader associated with the object. 

Arguments

 

On Error

if not checked out, E_NOT_CHECKED_OUT - string "NOT_CO"

Internal errror,       E_INTERNAL - string reason_for_error

On Success

Object_Ref gleader                                                       // The group leader

 

+ link_category_list( void )

Returns a list of the state change categories this object supports warm links for.

Arguments

 

On Error

 

On Success

(string category_name) []                                            // A list of category names

 

Note:

The warm link functions are denoted semi-private because they are currently only used by the GUI and the function may change.  If you must use it, you should talk with us.

 

+ warm_link( string category,

     Object_Ref catcher_object, string catcher_method )

Set up a warm link for the object.  When the state change modifies, we will send a notification back to the user.

Arguments

 

On Error

if a bad category name, E_NO_WARM_LINK - string reason_for_failure

On Success

void                                                                                 // No arguments

Note:

The error reply has a descriptive string and the bad category in the string.

When you set up a warm_link, you agree to keep the catcher object alive until you do a cut_warm_link.  Don't forget.

 

+ cut_warm_link( string category,

     Object_Ref catcher_object,string catcher_method )

Remove a warm link on an object.  You must do this before the catcher object expires on your end.  This call takes wild cards for the category and catcher_method.  In other words, a 'cut_warm_link( "*", catcher_ob, "*") will delete all warm links for the catcher object.

Arguments

 

On Error

 

On Success

void                                                                                 // No arguments.

Private Methods:

 

* attr_info( string attr_name, [ string type ] )

An obsolete call to return a human readable string about the attribute to the user.  At the current time this is only partially implemted and turned out not to be very useful.

Note - this is NOT the generalized info message for attributes

Arguments

attr_name           The name of the attribute we want info on

type                                                                                 One of "ALL" "desc" or "label"

On Error

 

On Success

String description                                                         A human readable description

 

* UI_get_attr( string attr_name,

     Object_Ref hotlink_catcher,

     string hotlink_method,  string orig_attr_name

 

This method is part of the implemtation of UI_get_attrs.  It sets up hotlinks, and returns the original name, a refeerence, the curr value, and the state of the attribute.

Arguments

string attr_name,                               Who to get

Object_Ref hotlink_catcher           who to send hot link messages too

string hotlink_method                     method to send hot link messages to

string orig_attr_name                      The original possibly dotted attr name.

On Error

For a bad attribute name, E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

On Success

int 1,                                                   For compatability.  One item returned

stirng attr_name,                               The attr name we are returning for

Object_Ref attr_ref,                         a ref for the attr (like get_attr())

Value curr_val,                                 The current value of the attribute

string attr_status                                                           The state of the attribute

Note: The attr_status is a string which is returned on various calls.  It tells us state info for the string such as read only, being changed, etc.  See the reference section of this document for details.

 

ob_ci (BPObject_Ref group_leader)

Check in the single object

 

Arguments

 

On Error

"OK", target_dob

"NO", reason_for_failure, target_ob   error_code = -1;

On Success

Bad - error text, error_code, target_dob

 

* ob_uncheck ( [BPObject_Ref group_leader )

Abort all changes, etc

Arguments

 

On Error

This can't fail. (Except for bad args, etc)

On Success

Success - "OK"

 

* ob_preval_trig (BPObject_Ref group_leader,

     int from_trig, int to_trig)

Check to see if it is valid and can be checked in.

Arguments

 

On Error

"INVALID", reason_for_failure, target_dob error_code = -1;

Failure - error text, error_code, target_dob

On Success

"VALID", target_dob

 

* ob_val (BPObject_Ref group_leader)

Check to see if it is valid and can be checked in.

Arguments

 

On Error

"INVALID", reason_for_failure, target_dob error_code = -1;

Failure - error text, error_code, target_dob

On Success

"VALID", target_dob

 

* ob_postval_trig (BPObject_Ref group_leader,

     int from_trig, int to_trig)

Check to see if it is valid and can be checked in.

Arguments

 

On Error

"INVALID", reason_for_failure, target_dob error_code = -1;

Failure - error text, error_code, target_dob

On Success

"VALID", target_dob

 

* ob_ci_complete()    

            Internal message

 

* ob_grp_co_done

Sent to tell the ob to start receiving msgs again.

 

* ob_newco_done()      Internal message

* ob_checkout( BPObject_Ref group_leader)

When we want to make mods, etc we checkout the object.  This is called only by the group checker outer. We reply to the message

Arguments

 

On Error

"NO", target_dob, reason_for_failure

"RE_TRY", target_dob

Failure - error text, target_dob

On Success

Success - "OK", target_dob who actually did the co

 

 
 

TOP:ATTR:OB:WLNK:MTH: Top object

 

This class is guaranteed to 'always' be there.  it has the well known name of 'TOP' so you can always send a message to it.

 

TOP has two main functions. First, it has as attributes all of the Factories in the domsrvr, so you can find the factories via calls to top in order to get Dobs, etc.  Secondly it provides group_leaders objects when requested.  The group leader is the object that is used to enable you to modify the business objects.

Public Methods:

get_co_group( void )

Provides a group leader object for your use.  The group leader is used to enable you to make changes to dobs.

Arguments

 

On Error

 

On Success

Object_Ref group_leader                                            // The group leader object

 

get_unique_id( string pool_name )

Applications frequently want a unique id for various reasons.  For example the numeric part of a call request number.  This provides a way for the use to get the 'next' number.  We maintain pools of id's by the string name.

Arguments

 

On Error

 

On Success

int                        new_id                                               // The id number

Note:  Not sure what happens if the pool is not already defined.

Private Methods:

 

* get_dict_info( void )

A private method to get dictionary information from the domsrvr. This method is evolving and should not be used.  It also gives more info than is really useful and is slow.

Arguments

 

On Error

 

On Success

(string factory_info) [] // A list of strings with lots of info

 

 
 

COGP:OB:WLNK:MTH: checkout/checkin object

 

When you want to modify the attributes of an object, you need to check out the object.  In order to do that you need one of these checkout group leaders.  (we refer to them as group leaders).  You get these from the top object.

 

If the group leader goes out of scope (IE you drop the reference to the object), all dobs associated with it will be un-checked.

 

Note: The logic behid all of these messages is some of the most complex in the system.  See the Reference section for message flows as to how all of these private messages work.

Public Methods:

 

checkout( Object_Ref who_to_co )

Asks the group leader who recieves this message to check out the object because you want to make some changes to it.  The 'who_to_checkout' can be an attribute or it can be a Dob.  In other words you can call this with an attribute as the object to check out, and the entire object will be checked out.  If the object is already checked out to the group leader, this is not a problem.  It acts as if it is just checked out.

 

When a dob is checked out, the attributes of the dob will accept set_val calls.  Remember though that we have a public private metaphor in our Dobs or business objects. If fred and wilma have dobs for 'Mary Smith', fred checkes out the dob and makes changes - fred will see his changes, but wilma will not see tha changes until fred checks the dob back in. If a third access dob for 'Mary Smith' is checked out to the group leader that owns the checkout, the third dob will see the changes immediately.

Arguments

Object_Ref  who_to_co   The object you want to checkout

On Error

checkout failed,  E_FAILURE - string "NO", string reason_for_failure

Note:  If it fails, you get an error code, a pre_defined string, and a human readable string as to the reason for the failure.

If it succeds, the args returned can vary. Don't look beyond the first argument EVER!!  We will fix this at some point.

On Success

string "OK"        // Success message

...                          // Other things YOU SHOULD IGNORE

 

checkin( void )

Attempts to check in all of the objects in the group leader.  When this method is called, we first call the PRE_VALIDATE triggers on all of the objects, if none of the triggers return an error we do some Object level checking for required fields, etc.  If that check passes, we call the POST_VALIDATE triggers.  If no POST_VALIDATE returns an error we update the database.  We then send out the POST_CI triggers.

 

If the checkin fails for due to a trigger return, the error code and failure message will be provided by the trigger code. 

 

If a checkin fails, you can fix the problem and try again.

If a checkin fails at the database level, and there are multiple objects checked out, you may find that the object values for some of the objects have changed in the database.  This is a known problem having to do with transaction processing.

Arguments

 

On Error

if nothing checked out,  E_NOT_CHECKED_OUT - string error_text;

other reason           varies                                                   - string error_text;

On Success

string "OK"        // We did it.

 

uncheck( void )

Abandons all changes to the objects checked out in the group leader. Delets any dobs 'newed' in this group leader.

Arguments

 

On Error

 

On Success

string "OK"                                                                    // Only possible return

Private Methods:

* add_to_co( Object_Ptr who_to_co )

Sometimes checking out one object forces additional checkouts.  If this occurs, we will see this message while we are in a state of ADD_CO_WAIT.  If we get one, we start a queue of additional objects to CO and process them when the inital CO is done.

Arguments

 

On Error

 

On Success

No reply possible.

 

* is_checkout()

Tells us if this 'group leader' has anything checked out.

Arguments

 

On Error

 

On Success

"YES"                  "NO"

 

* start_newco( BPObject_Ref who_to_ask, String method, ... datao)

Starts a request for a new object which the GL needs to knwo about.

Arguments

 

On Error

 

On Success

None except for bad params1

 

* add_to_newco( BPObject_Ref , array preval_trig_array,

                        array postval_trig_array)

Add a 'new' co to our list

Arguments

 

On Error

 

On Success

None except for bad params1

 

* ob_newco_complete( private_thing, who_to_reply_to, 

method_to_call, what_to_return ...);

We are done with the new

Send message to all we added

 

* ob_co_results

return the results of an object checkout to the group captain.

Import:

    "OK", target_object, pre_val_trig_array, post_val_trig_array

    "DUP", target_object

    "RE_TRY", target_object

    "NO", error_text, target_object, error_code

    error_text, target_object, error_code

No response

 

* ob_uc_results

This is the return for uncheck.

At this point we simply ignore this (UC always succeed)

 

* ob_preval_trig_reply

return the results of a pre_val trigger sequence

Send:

                "VALID", target_object

                "INVALID", failure_reason, target_object

                error_text, target_object

 

* ob_val_reply

return the results of a validate request

            Send:

                "VALID", target_object

                "INVALID", failure_reason, target_object

                error_text, target_object

* ob_postval_trig_reply

return the results of a post_val trigger sequence

            Send:

                "VALID", target_object

                "INVALID", failure_reason, target_object

                error_text, target_object

 

* ob_ci_reply

return the results of an object checkin to the group captain.

            Send:

                "OK", target_object

                "NO", error_text, target_object

                error_text, target_object

 
 

FAC:NC:ATTR:OB:WLNK:MTH: The Factory Object. 

 

This is the base class for all factories.  When you define a factory in majic, you define a class with the factory name pre-pended to the base name.  For example cnt:FAC:NC:ATTR:OB:WLNK:MTH:  for the contact factory.  Any factory can define additional methods in the .maj file.  The methods presented here, however, are the standard ones.

 

There is one and only one instance of each factory class (cnt:FAC:NC:ATTR:OB:WLNK:MTH:).  The instance is an attribute of the TOP object.

 

The class is used as the public interface to getting Dobs and Domsets.  It also serves as the way to get class information about the dobs the factory will provide to you.

 

Each factory has as attributes the Producer that actual does the work of creating the dobs, etc for the factory.  In normal cases, you should ignore this attribute.

What we show here are the methods on each factory.  An individual factory may have additional methods defined in .maj.

Public Methods:

get_domset_list( void )

The factory is what provides domsets (lists) to you.  This is a call to find out what domsets the factory supports.

Arguments

 

On Error

 

On Success

(string domset_name)[]

          

 

domset_info( string domset_name, string info_type,

     string opt_arg,  ... )

Provide some information about a domset that the factory understands.  The Domset has lots of information you may need. This returns them in a human readable format.

This is doing an info call on the underlying object.

            The info_type that this understands are:

                ALL_DOMSET -   returns all the information

                SELECT returns the default select column

                LIST_COLS return the list cols defined for the domset

                SORT_COLS return the sort cols defined for the domset

                ORDER_BY return the order_by for the domset

                MAX_FETCH return the max fetch paramater.

                STYLE return style of domset

Arguments

string domset_name, // The domset of interest

string info_type, // A pre-defined type of info you want

[string opt_arg],                                                                      // Optional arguments.

[...] );                            // optional vararg stuff

On Error

If no domset, E_DOMSET_NAME - "Domset not found"

On Success

for ALL_DOMSET,     Return the entries below in order

for SELECT,      

    string select_string                       // The select defined for the domset

for LIST_COLS

    string list_cols                              // The list cols defined for the domset

for SORT_COLS

    string sort_cols                             // The sort cols defined for the domset

for ORDER_BY

    string order_by                             // The order by string defined.

for MAX_FETCH

int  max_fetch                               // The max fetch paramater

for STYLE

    string "STATIC" | "DYNAMIC" | "PRE_LOAD"

    // The style of the domset

Note:    Domsets are being re-worked at this time.  These may change substantially in the next release.  The intent of this call is for reporting only, you probably do not normally need to call it.

 

get_domset( string domset_name, [Object_Ref parent] )

Get the domset we named.  This call may return an existing domset (if the domset style is defined as PRE_LOAD which means shared) or it may instance a new one for you( STATIC or DYNAMIC).  A static domset will not change once the fetch is done, a dynamic domset will keep itself in sync with any changes.

Arguments

string domset_name,         // The name of the domset

Object_Ref parent             // Optional obsolety parent for ref purposes.  Do not supply

On Error

if bad name,           E_DOMSET_NAME - string error_text

On Success

N Object_Ref domset_ref                                            // The domset you requested.

 

dob_by_persid(  BPData smag, string persistent_id,

     [Object_Ref parent_ob],[Object_Ref group_leader] )

Return a dob with the persistant id if such a dob exists.  If the goup leader is set, and the dob is checked out to this group leader, This dob will be checked out as well.

If the parent_ob is supplied, we will ref the parent in this dob.  This feature is not currentlyused in the system.

The smag object is a way to pass back some context.  We will simply pass it back to you.

Any of the Object_Ref args can be nil

Arguments

BPData smag,                          Returned smag.   Can be nil

string persistend_id                 The persistend id you want to use in the search

Object_Ref parent_ob             The parent ob for refing

Object_Ref group_leader        The group leader for 'auto' checkout

On Error

if persistent_id is badly formed,    E_BAD_ARG - string error_text

if not found,                             E_NOT_FOUND

On Success

Object_Ref dob,                       the dob that was found

BPData  smag,                         the original smag data returned to you

string  dob_pers_id                          The persistant id for the dob returned.

 

get_new_dob( Nil | string producer_attr_name,

     Object_Ref parent_ob,Object_Ref group_leader )

Create a brand new dob with a brand new persistant id and return it to the caller.  It will be checked out to the group leader.  The producer_attr_name can be NIL or "".  In this case it will use the default producer for the factory. At this time all factories only have one producer, so it is probably safe.

Arguments

string producer_attr_name        The explicit producer name to use.

Object_Ref parent_ob               The parent ob for refing

Object_Ref group_leader          The group leader for 'auto' checkout

On Error

 

On Success

Object_Ref dob,                        the dob that was found

BPData  NIL,                             A place holder.

string  dob_pers_id                            The persistant id for the dob returned.

 

get_null_dob(  [BPData smag] )

A null dob is basically an 'empty shell' of the dob.  Any call to an attribute typicall reutns null, etc.  It is only useful because you can re-map a dob. In a UI for example, you could get the null dob, the re-map it to the dob you want to display.

Arguments

BPData smag                                     Optional smag argument.

On Error

 

On Success

Object_Ref dob,                                                            the dob that was found

BPData  NIL,                                     A place holder.

string  dob_pers_id                          The persistant id for the dob returned.

 

dob_attr_list( void )

Tells the user what the attributes are in a dob which can be created by this factory.

On Success

(string attr_name) [] // List of attribute names.

 

dob_attr_type_info( string attr_name )

Does a type_info on the attribute.

On Success

See type_info returns in appendix.

 

dob_attr_info( string attr_name, string type, ... )

Does an info on the attribute.

On Success

See the info call for the various types of attributes.

          

dob_info( string attr_name, string type, ... )

Does an info on the dob.

Currently there are no specific info types on the dob, so we default to those defined  for PATTR:OB:WLNK:MTH:

 

sync_fetch( string domset_name,string select_clause,

     int num_to_fetch,(Value fetch_params)[] )

Get the domset, perform the fetch using the provided select clause.  Don't return until the fetch is complete.  The num_to_fetch can be a number, or '-1'. if -1, we say to select all of them.

This is provided as a convenience for the app developer.

Arguments

string domset_name                The name to fetch.

string select_clause                 The select clause to apply

int  num_to_fetch                    Max number to fetch.

(BPData fetch_params)[]                A list of fetch params for any `?` needed in the select

On Error

For a bad domset name:          E_DOMSET_NAME - string error_text

If the domset is not fetchable. (A PRE_LOAD)           E_REQUEST_DENIED - string error_text

On Success

Object_Ref  new_domset,       // The new domset

int num_in_domset                          // how many in the domset.

 

info( String type, ...)

The re-defined info for factories.  We add to PATTR:OB:WLNK:MTH: the following types:

           UI_SCHEMA - return the UI_schema_info_call

           RESTRICT - Returns any restriction values on factory.

           RLIST_FILTER - returns the filter for the rlist

Arguments

See the base info() call.

On Error

 

On Success

for UI_SCHEMA                     all of the stuff on a UI_schema_info call.

for RESTRICT                            

string data                              The restriction clause if any for the factory

for RLIST_FILTER  

  string data                                        The filter clause for the factory (if any)

 

val_by_key( string attr_key_name, value key_val,

          (string attr_desired) [] )

Sometimes you just want to get some values from a dob where you have a single unique key.  This does this for you.  You provide the attribute name which is unique, the value for the attribute, and a list of the attributes you care about.

The system gets the dob and simply returns the values you specify.

Arguments

string attr_key_name,              // The key attribute.

value key_val,                          // The value to use in the search

((string attr_desired) []                    // A list of attribute names to return.

On Error

If not found or not unique    E_NOT_FOUND - error text.

Other    Lots of possible error codes from the calls this guy makes.

On Success

(Value ret_val)[]                              // An array of values

           

* dob_by_id(  BPData smag, integer id,

     string producer_name, [Object_Ref parent_ob],

      [Object_Ref group_leader] )

Similar to the dob_by_persid call except that we assume and integer for the uniuqe id, and provide the producer name separately.

Arguments

BPData smag, Returned smag.  Can be nil integer id string producer name The persistend id you want to use in the search Object_Ref parent_ob The parent ob for refing Object_Ref group_leader The group leader for 'auto' checkout

On Error

if persistent_id is badly formed E_BAD_ARG - string error_text

if not found E_NOT_FOUND

On Success

Object_Ref dob,                       the dob that was found

BPData  smag, the original smag data returned to you

string  dob_pers_id                          The persistant id for the dob returned.

Private Methods:

* UI_dob_by_persid()

* UI_schema_info()

* dob_by_id()

* UI_dob_by_persid( BPData smag,

      (string persistant_id)[])

This call is put in for the UI to be faster.  Think of it as a number of dob_by_persid calls with the same smag pointer, and no parent or group leader.

On Success

For each persid we passin, we return the equivalent of a dob_by_persid

 
 

DSET:ATTR:OB:WLNK:MTH: The Domset Object

 

Whenever you need a list of things, you need to use a domset object.  You get domsets from a factory.  The domset you get will provide lists of dobs from the factory that match the selection criteria you have provided.

 

The selection criteria are pretty much like SQL where clauses.  The main difference is that they understand the ideas of the dotted names so you could ask for all contacts who are in the organization "Sales" by "WHERE organization.name = 'Sales' "

 

Domsets do some sorting for us.  You can define (in majic) what the sort columns are.  Multiple columns can be defined as a single key.  The domset will allow you to access the entries by any of the keys you have defined.  Note that the sort information is NOT an object attribute, it is a database column. The ability to do this is a speed enhancement.  Some sacrifices are necessary.

You can also define fetch columns.  These are additional columns which are Domsets keep around for fast display.  As in the sort columns they are database cols, not attributes.  Sort columns are also available for this fast display mode.

Duplicate entries into a domset are not allowed (Duplicate meanes the same persistent id for the objects). If multiple fetches or merges cause duplicates, they are quietly ignored.  There is a way to count how many times one has been added using a special sort or fetch column.  If you define a ROW_HITS as a sort or fetch column, it will maintain the number of attempted entries.

We have the idea of three styles of domsets. 

 

PRE_LOAD or global domsets get created and filled before they ever return to you.  There is only one available at anytime and they are shared.  They keep themselves in sync with the underlying where clause on a real time basis.  In other words, if you have a Call Request domset with the where clause = "WHERE status = 'OP'" When a new one is created, the count will go up, when it is deleted it will go down.

STATIC - An ad-hoc domset which is not shared.  This kind does not keep itself in sync.

DYNAMIC - An ad-hoc domset that is not shared.  This kind does keep itself in sync.

 

When the factory is defined in majic, you define some criteria for standard lists.  These define some special name factories, specifically MLIST, RLIST, MLIST_DYNAMIC, RLIST_DYNAMIC, MLIST_STATIC, RLIST_STATIC. STATIC, DYNAMIC.  See the majic documentation for details.

 

There is no way to add methds to a Domset from majic.

 

Note - the core of domsets is being modified for speed enhancements.  The interface is not expected to change however.

 

Attributes:  The domset has two attributes which represent the number of items in the domset.  These can be accessed using any of the methods under VLAT:PAT:MTH: below.

      length - The current length of the domset.

      * approx_count - a slower incrementing count for the GUI.

 

The domset will also consider as attributes the items in the domset based on the default sort order. You can send a dotted name where the first dot is the index number you want it to find.  If the list changes after you have the attribute, you will not be notified however. 

Warm Links:  The domset supports several warm links.  The user can request to set up a notificaiton when the warm link occurs.

 

start_fetch a fetch has been started.

finish_partial A fetch has been completed up to the number asked,  but there may be more to fetch.

finish_fetch A fetch is completed (EOF)

Methods:

empty(void)

Clear all entries from the domset.

This can fail if the domset is PRE_LOAD

Arguments

 

On Error

if it is a PRE_LOAD E_REQUEST_DENIED - string error_msg

On Success

string                   "OK"

 

fetch( string select_clause, int num_to_fetch,

     (Value param) [] )

Add some entries to a domset based on the select clause passed in. The select clause is an sql style 'Where' clause.  The num_to_fetch is how many to retrieve.  A value of -1 is special.  If MAX_FETCH has been defined for this domset it will fetch the MAX_FETCH value.  else it will select all of them.  This method returns to say that it has started the fetch. There is no explicit call when the fetch is complete.  In order to find out when it is done, you need to set up hot links on the length attributes, or subscribe_mods for information.

If the select clause contains '?' (replacable paramaters) you must provide the values.  You do this via a value list.  An example of a where clause might be "id = ? and fred < wilma". There is no keyword "where".

Making this call will create a start_fetch warm link message.

If the domset is currently fetching, the previous fetch is ended, and the new one starts.  Remember that the domset may have restrictions permanently encode into it, as may the factory.

Arguments

string select_clause,                                                     // Select clause to filter on

int num_to_fetch.                                                         // How many to get

(Value param)[]                                                             // replacable params

On Error

If domset can't be fetched, E_REQUEST_DENIED - string error_text

If a bad replacable paramater type,    E_BAD_ARG - string error_text

On Success

string                   "OK"                                                   // The fetch has started

 

fetch_more( int num_to_fetch)

When you make a fetch, you may not get everything that matched, depending on if there is a MAX_FETCH set of if you asked for a small number.  In this case you want to fetch some more.  This call makes that request.  You pass in the number of additional 'rows' you want to fetch. The same rules of -1 being all or MAX_FETCH apply.

As in the fetch, the reply to this call is just that the fetch has started.

Arguments

int num_to_fetch                                                          How many new ones to fetch

On Error

If currently fetching E_IN_FETCH - string error_text

If no more to fetch (EOF) E_NO_MORE_FETCH - string error_text

On Success

string                   "OK"                                                   // Fetch more has started.

 

sync_fetch_more( int num_to_fetch)

It is often useful not to have to watch the length, or register for warm links, etc.  Especially when writing command line interfaces.  This call fetches some 'more' but does not reply until the fetch is complets.  The same rules for 'num_to_fetch' apply as in the other fetches, the difference is that we do not return until the fetch is complete.

Arguments

int num_to_fetch                                                          How many new ones to fetch

On Error

If currently fetching E_IN_FETCH - string error_text

If no more to fetch (EOF) E_NO_MORE_FETCH - string error_text

On Success

int                        num_in_domset                                   // How many are in the domset

 

dob_by_key( string col_name, (Value tgt_val) [])

You can access dobs in the domset based on any of the key values that are defined in the majic file.  You pass in the key name, and the values to use in the search.  The list of values is to handle multiple keys.  In this case you set col_name to be the multiple key name, and pass the individual column values.

For multi part keys you don't have to pass them all in.

For col_name we accept the special name 'DEFAULT' as the first one identified in the formt.  if the col_name is empty or NULL, it is considered to be DEFAULT.

The call returns a string which is the kind of match.  We define three types:

NONE - No match found, and 'first_dob' will be the nil object

UNIQUE - The key matches one and only one dob

MULTI - The key matches multiple, the dob is the first one.

Arguments

string col_name

(Value tgt_val) []                              A list of values to search for.

On Error

 

On Success

string match_type,                            string that says what kind of match

Object_Ref first_dob,                      The dob

string first_persid                             The persistant id of the dob

 

+ closest_dob_by_key( string col_name,

     (Value tgt_val) [])

Sometimes you don't want an exact search, you want the closest search. This call does that search for you. The arguments are the same as dob_by_key.

Whats the difference between dob_by_key and closest_dob_by_key. Consider a domset containing the names "smith", "smyth", "sam", and "adam";

           dob_by_key 'a'     would return NONE.

           closest_dob_by_key would return UNIQUE

 

           dob_by_key 'b'              would return NONE

           closest_dob_by_key would return NONE

 

           dob_by_key 'smi'   would return NONE

           closest_dob_by_key would return UNIQUE

 

           dob_by_key 'sm'    would return NONE

           closest_dob_by_key would return MULTI

Arguments

string col_name

(Value tgt_val) []                              A list of values to search for.

On Error

 

On Success

string match_type,                            A string that says what kind of match

Object_Ref first_dob,                      The dob

string first_persid                             The persistant id of the dob

 

dob_by_index(string key_col, int start_index,

     int end_index);

You can access dobs by index as well as by key value.  Since the domset supports several sorts, each of which would provide a different index for a particular row, you need to define which

        key_col you want to use to define the index.

As in the other dob_by calls, DEFAULT is defined as a special key_col which is the first one.

This returns a range of dobs, not just one.  You supply the start and end index you are interested in.  The reply from this is different from most methods. We may return an error message, or we will return some number of messages, each one containing information about the row requested.  Note that the rows may come back 'out or order'.

Please note that -1 is NOT a special value.

Arguments

string key_col                                   The col name to index against

int    start_index                                                            Where to start

int    end_index                                 where to end

On Error

if invalid start or end index E_BAD_ARG               string error_text

For each index we return on:

Error Reply:       E_NOT_FOUND - string error_text

On Success

Object_Ref dob                                The dob found

int index                                             The index where we found it

string persistent_id                          The persistant id for the dob

 

+ index_by_key( string key_col, (Value key_val) [])

Similar to dob_by_key except you return the index of the row which matches,

Sometimes you want to get the index in the domset for a certain key. This method returns the index value which match the passed in key.  You should note however that the index value may well 'move' between the time you get it, and the time you try to do something with it.

As in the other call that take a key_col, you may pass in DERFAULT. "" or NIL as the key_col.

Arguments

string key_col                                   Key to use for index computation

(Value key_val)[]                            Array of values to use in key.

On Error

If key_col not found,     E_BAD_ARG - string error_string

On Success

string match_type                             See match_type under dob_by_key

int    index                                          Index value for match

 

+ closest_index_by_key( string key_name,

     (Value key_val)[])

Similar to closest_dob_by_key except you return the index.

Arguments

string key_col                                   Key to use for index computation

(Value key_val)[]                             Array of values to use in key.

On Error

If key_col not found,                       E_BAD_ARG - string error_string

On Success

string match_type                             // See match_type under dob_by_key

 

display_by_index( int start_index, int end_index,

     string key_name, (string col_name)[])

You can get display fields from the domset quickly and directly using this call. A display field is the locally cached field that you can get quickly.  You provide the start and end index of interest, and the key_name to drive the index.  The list of col_names are the columns from the Domset you want returned.  The reply is in a single message.

The col_names supplied must be defined in the Domset definition either as sort columns, or as fetch columns.

As always key_name can be DEFAULT, or "" or nil.

If the index is 'beyond' what is available, we will simply return what we have. this is not considered an error.

Each return row contains the persistant_id, followed by the display columns.

Arguments

int start_index                                      Where to start

int end_index                                       Where to end

string key_name                                  The key to drive the index

(string col_name)[]                                         An array of column names to return.

On Error

A bad column name or invalid index,          E_BAD_ARG string error_text

On Success

int start_index                                      // Where we started

(string persistant_id, first_col, ... )[] // Array for each row

 

persid_by_index( int start_index, int end_index)

The domset also sorts by persistant id.  This call returns the persistant id's for a range of rows - sorted by persistant id.  It is simplar to display_by_index except that it returns persistant id's.

Arguments

int                        start_infex,

int                        end_index

On Error

bad index values,                                                          E_BAD_ARG - string error_txt

On Success

int start_infdex,                                                             // Where we start

(string persistant_id)[]                                                 // List of persistant id's

 

domset_remap( Object_Ref map_to, string user_reason)

The domset is really an access object for an underlying private list object. This means that you can request the domsrvr to point a domset to a different underlying private_list object.

You provide the domset you want to 'map' this domset to.  The map_to domset must be the same type as the one you are mapping from.  (Note - the error checking for this looks bogus).

When the map occurs, any hotlinks you have established on the length attributes get called with the user_reason as why the hotlink occured.  Additionally any subscribe_mod links that are set up get tickled with a "B_RMP" for the reason.

Arguments

Object_Ref map_to

string     user_reason

On Error

 

On Success

string "OK

 

get_where( void )

Sometimes you want to get the get the where clause that was passed in when the fetch was started.  This method returns the string the user passed in when the fetch started.  It will also contain any factory restriction or domset restrictions that have been added by the domset before the fetch is actually started.

On Success

string where_clause                         The where clause

(Value params)[]                              Paramaters passed into the orig clause

     

get_storage_where( void )

When a fetch is processed, it gets converted to an underlying sql fetch. This may include making the clause a join, etc.  This call returns the converted where clause.  It is what was submitted to the SQL database for the where clause.

We also return the names of the database tables we are fetching from.

On Success

string where_clause                           The where clause

(Value params)[]                                The paramaters passed into the orig clause

(string table_name)[]                         List of tables we are using in the 'select'

 

merge( Object_Ref thing_to_merge)

Sometimes you need to add things to a Domset by ways other than doing a fetch. For example you may just want to add a dob, add the contents of another domset, add a qrel or lrel.  This call will do this for you.

thing_to_merge is a reference for a dob, domset, qrel, or lrel.

The domset recieving this message must be STATIC.

If there are duplicates we quitely ignore them and do not add them in. Finding a duplicate is not considered an error.

The method returns the new number of elements in the dob.

Arguments

 

On Error

If a bad domset type: E_BAD_DOMSET_TYPE - string error_text;

On Success

string "OK",

int number_now_in_domset

 

type_info( void ) (A virtual)

On Success

See type_info returns in appendix.

 

+ subscribe_mods( Object_Ref catcher,

     string catcher_method, string key_name,

     [int from_index], [int to_index])

This is a call to notify you when something interesting happens to the domset. You are asking to be notified about changes.  You pass in a catcher object and catcher method to be called whenever something has changed.  You specify which key you want to drive the index number passed in the return.

The domset will send a message to the catcher object/method whenever an add, del, modify, length_change, or remap occurs on the domset.

The from/to index are the interest range.  If not supplied you are only interested in length type messages.

The messages sent to you are as follow:

                When a row is added to the domset:

                        string "ADD",

                        int    index_where_added,

                        string persistant_id_of_add

                When a row is deleted

                        string "DEL",

                        int    index_where_deleted,

                        string persistant_id_of_del,

                When a row is modified and it moves it in the domset.

                        string "MOD",

                        int old_index,

                        int new_index,

                        string persistant_id_of_changed

                When the length changes.

                        string "LENGTH"

                        int    new_length

                When a remap occurs

                        string "B_RMP",

                        int    new_length

The subscribe mods is part of the public wrapper for the domset, not part of the private list structures.  This means that if you re-map the domset, the subscribe_mods continue to be associated with the domset you are re-mapping.

On Error

If a bad key_name E_BAD_ARG - string error_text

On Success

string "OK

 

+ unsubscribe_mods( [Object_Ref catcher_object] )

Remove a subscribe mods from the list.  If you provide a catcher_object we will remove the subscribe_mods for the catcher_object only.  If do not provide the catcher_object, we will delete all subscribe mods for the domset.

 

+ set_interest_range( Object_Ref catcher_object,

     int start_index, int end_index)

This is a GUI call.  It allows you to reset the watch index in a subscribe mods based on the catcher object. You provide the range of index you want to now watch for,

NOTE - there is no reply to this message.  This is one added by the GUI designer for his use.

The message returned on an add is the 'ADD' message noted under subscribe_mods.

Arguments

Object_Ref catcher_object

int          start_index,

int        end_index

 

* UI_display_by_index( int start_index, int end_index,

   string key_name, (string col_name)[])

A display_by_index for the GUI.  We stuff the dob ref in the reply

Arguments

int start_index                        Where to start

int end_index             Where to end

string key_name                    The key to drive the index

(string col_name)[]           An array of column names to return.

On Error

A bad column name or invalid index E_BAD_ARG string error_text

On Success

int start_index                        // Where we started

(string persistant_id,

Object_Ref dob,

first_col, ... )[]                                                               // Array for each row

 

 
 

PDOB:PATTR:OB:WLNK:MTH: The Dob

 

This is the base class for the various business objects.  A specific class of business object will pre-pend the producer name to this string.  For example a Contact buisness object ( 'cnt' ) will have the class name of 'cnt:PDOB:PATTR:OB:WLNK:MTH:'.  These classes are what you will usually be manipulating.

 

The specific class of the dob may of course add methods to the ones defined here in the base class. You will discover those additional methods by looking at the .maj files, or by doing an bop_sinfo call on the domsrvr. There are some attributes that are always defined in a dob.  Specifically id, producer_id, and persistant_id.  NOTE - the id field may change in the future.  When you look at the .maj file definitions, you will not see these three attributes, but they are always there.

Public Attributes:

      producer_id

      persistent_id

Public Methods:

dob_mark_delete( void )

Requests that the dob be marked as deleted.  The dob must be checked out in order to sucessfully accept this message. When this message is successfully recieved, the dob will send out attr_status messages for any attributes that have hotlinks set up for them.

The dob is not actually deleted until the group leader is checked in.

Deleting a dob means that it is removed from persistant storage.

Arguments

 

On Error

if not checked out E_NOT_CHECKED_OUT - string error_text

On Success

string "OK"

 

dob_remap(  Object_Ref new_dob | Nil )

Sometimes (primarily in GUI work) you may need to re-map a dob to some other business object.  (Remember the dob is actually an access object and can be repointed).  This call will re-mapp to another dob, or will point it to the 'Null' dob.  The null dob is a special 'guaranteed to be empty' dob.

A remap call will cause hotlink messages with new values and attr_status changes as appropriate.

You cannot map a dob of one class to a dob of another class.  IE you can't map a contact dob to a trouble ticket.

If the dob recieving the message is checked out, you cannot re-map.

 

Arguments

Object_Ref new_dob | NIL            

   You pass either the new dob to point to or a NIL object for the NULL dob.

On Error

Mismatch in dob class names E_REMAP_BAD_CLASS - string error_text

This dob is checked out           E_REMAP_CO - string error_text

On Success

string "OK"

 

type_info(  )

As always the type_info call is overloaded to give info about the object. See the type_info reply summary in the Appendix.

Private Methods:

* UI_get_attrs()          A UI interface for getting attrs and setting up HL

* ob_checkout()  (overloaded from dombase)

* ob_checkin()

* ob_uncheck()

* ob_validate()

* UI_get_attrs( string hotlink_method_name,

     (string attr_name)[], Object_Ref catcher_object)

A private method for the GUI to gets lots of attribute info in a few messages for efficiency.

A UI call.  We request the server for information needed to put up a UI screen about a DOB.  We want the server to return an BPObject attr, the current value information, and to set up a hotlink for each named attribute.

NOTE:  For non value attributes, we will not set up a hot link, nor will we pass back a state string or a Value.  (We will pass back dummy args only)

If the attribute name is dotted, the reply will come back 'later'. Therefore you will get some number of returns for this call.

The reply is a list of information for each named attribute. You get the name, a reference object, the current value, and the state string for the attribute.

Arguments

 

On Error

 

On Success

(string attr_name,

   Object_Ref attr_ref,

   Value attr_val,

   string attr_state)[]    // A list of attributes coming back.

 

 
 

PAT:MTH:      Base class for all attributes

 

This is the base class for the attributes.  By this we 'really' mean attributes on dobs and domsets, not as much the attribute on the TOP object.  We have several kinds of attributes we create from this base class.  Specifically Values, SRel, LRels, and QRels.

This attribute class is where we introduce the idea of a hotlink.  You can ask the domsrvr to notify you when an attribute value and/or state changes.  This is used to keep the screen in sync with the underlying data.

 

Note - there is a 'base class' type method which is defined here but is implemented only in the derived class.  This is get_val().  I document this method only in the derived classes.

Public Methods:

+ subscribe_hot()       Set up a hotlink

+ unsubscribe_hot()   clear a hotlink

info()                           return info about the attribute

is_co() Tell if the holder of the attribute is checked out

+ subscribe_hot( Object_Ref catcher_ob,

     string catcher_method)

This is a request to notify the catcher_ob / catcher_method whenever there is a change in the attribute.  A change includes a change in state (triggerd by the attr_state string being returned) or a change in value if it is a concrete type. 

When a hotlink event occurs it is sent to the catcher_ob / catcher_method in the following form:

                catcher_method( Value value,     

                                       string attr_status,

string how_changed);

The value is the current (usually changed) value for the attribute.  The attr_status is as defined in the Appendix, the how_changed is a string that can be set to say who or why is changing the attribute.

Note the how_changed field may go away.  how_changed is a string define by the caller to set_val.  The intent is for the viewer/user to tag set vals.

We reserve some strings.

                "B_DFS" = Default on save

                "B_RMP" = Remap to a new object

                "B_CO"  = Due to checkout activity

                "B_CI"  = Due to check in activity

                "B_IHL" = Initial hot link entry

                "B_INIT"= Initialization stuff

                "B_INTER" = Internal state var, counts, etc changing

The success reply is to do a hotlink.  There is no 'standard' reply

Arguments

 

On Error

 

On Success

      Value value,

      string attr_status,

      string how_changed

 

+ unsubscribe_hot( BPObject_Ref catcher_ob,

     string catcher_method)

A subscribe needs an un-subscribe.  This is it.  If you pass in a cathcer_method of "*", it is considered to be "all" methods for the catcher_object.

Arguments

 

On Error

 

On Success

no reply !!!

 

type_info()

As always this is sent to the derived class.  See the Appendix for information.

 

info( string request_type, ...)

A way to get other / additional attribute information as to defaults and access flags.  Valid request types and reply methods are noted below:

See info() in the MTH: class for valid args.

Arguments

"DEFAULT"       Asks what defaults are set up on the object. The value tells you what it will be set to, a value string of 'NOW" means the date at the time of the action

On Error

 

On Success

   "NONE", value dummy_value

"DEFAULT_NEW", value val

"DEFAULT_DB", value val

"DEFAULT_CI", value val

       "SET_CI", value val

           

 

Reply:

 

Arguments

"ATTR_FLAGS" Ask for access information on the attribute

On Error

 

On Success

"REQUIRED"     Attr is required

"CONST"            Attr is non modifiable.

"PRIVATE"        modifiable by domsrvr only (future)

"PUBLIC"           Modifiable by anyone

"WIFNEW"        Modifiable only before being saved.

Private Methods:

* ob_checkout() * is_checkout()

is_co( void )

            Tell us if the holder of the attribute is checked out or not.

Arguments

 

On Error

 

On Success

if is checked out                                                                string "IS_CO"

if not checked out "NOT_CO"

 

 
 

VLAT:PAT:MTH: An un-modifiable value attribute

 

This is the base class for a concrete attribute which cannot be modified.  By concrete we mean items like string, int, duration.

 

Note - it is possible that this class may dissappear and be merged with the RW:VLAT:PAT:MTH:  The writable version.  In this case a set_val call would return an error.

Public Methods:

        get_val()  get the current value

Methods in Detail

get_val( void )

Request the currrent value of the attribute.

Success Reply:

            value  curr_value,                  // The current value

            string attr_state                      // The attr state string.

 

 
 

RW:VLAT:PAT:MTH:- A modifiable value attribute

 

An value attribute that can be modified. 

Public Methods:

set_val( Value new_val)

Set the value to the new value.  Calling this method will also call any ON_PRE_VAL or ON_POST_VAL, or ON_POST_VAL_ASYNC triggers on defined for this attribute.  The trigger may return an error, if so the returned error is whatever was sent to us.  The ON_PRE_VAL trigger may morph the initial value.  When the value is changed, any user hotlinked to the attribute who is checked out on the same group leader, will be notified of the change.

Arguments

 

On Error

If you don't have it checked out.  E_MODIFY_NOT_CHECKED_OUT - string error_text

If WIFNEW or other permissions problem E_UPDATE_NOT_POSSIBLE - string error_text

A bad value type passed in. E_FAILURE - string error_text

Timeout in trigger E_TIMEOUT - string error_text

Aborted from a trigger error_set_in_trigger - string error_text

On Success

   string                "OK",

   value   curr_val,

   string  attr_status,

   string  smag_field

 

 
 

SREL:PAT:MTH: An srel attribute.

 

This attribute represents a single relation, ie the assignee in a trouble ticket. 

Note that the interface for this (in the get_val, set_val) is identical to the Value attribute. This is by intention.

 

The item 'stored' in the attribute is the rel_attr defined in the factory of the thing that we are refering to.

 

Please note that attributes of the associated dob may be accessed using a dotted notation.  In other words 'assignee.last_name' to get to the last_name attribute of the dob refered to in the assignee attribute.  A more interesting form might be assignee.organization.contact.phone_number

Public Methods:

get_val( void )

This returns the rel_attr that is 'stored' in the srel attribute. 

Arguments

 

On Error

 

On Success

Value rel_attr,                        // The rel_attr value

string attr_status                               // The status string for the attribute

 

set_val( Value new_val | nil )

Set the rel_attr to a new value.  Passing a nil is ok here, it makes it point to nothing.  A string of "" is special cased to act as if it were nil.  Setting it to a garbage value is not an error.

The standard errors apply if the object is not checked out.

When you update the rel_attr, any references you have gotten to the rel_attr dob will be updated to the new dob the rel_attr refers to.

Arguments

 

On Error

if not checked out E_NOT_CHECKED_OUT - string error_text

If not updatable due to restrictions E_UPDATE_NOT_POSSIBLE - string error_text

On Success

string "OK",

Value new_val,                                                             // The related_attr value

string attr_status,

string smag_string

 

get_dob( void )

Request the dob associated with the reference.  If there is not a 'good' dob associated with the reference, it will return the null dob.  If in the future there is a dob associated, the dob you are given will re-map to the 'new' reference.

Arguments

 

On Error

 

On Success

Object_Ref dob_object,                                             // The dob itself

string                        persistent_id                                // The persistent id of the dob

           

 

get_attr( string attr_name )

If you want not the dob the srel is pointing to, but an attr on the dob, use this call.  A dotted name is supported.  When the srel is changed to point to another dob, this attr will change who it is pointed to as well.

This call is included so you can do 'get_attr" calls on virtually anything. It is usually invisible to you. Using the dotted name on the dob 'really' calls this guy.

Arguments

string attr_name                                                                                               The name you want to get.

On Error

If the attr_name is not found,  E_UNKNOWN_NAME - string error_text

On Success

Object_Ref  attr_object                   // The requested object.

 

call_attr( string attr_name , string method_to_call,

     ...)

Matches the call_attr on the dob, etc.  This is usually invisible to you and is included to make the interfaces to dobs and srels consistent.

Arguments

string attribute_name,                      Attribute name to send message to

string method_to_call,                     Message name to use.

...                                                         rgs for the message you are sending

On Error

For a bad attribute name,   E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

On Success

Depends on what the dispatched method returns. This function itself returns no reply except for errors

* Private Methods:

* UI_get_attrs()

 

 
 

 

QREL:PAT:MTH: An srel attribute.

This attribute represents a list relation which matches some sql query.  The sql query may be automatically generated by refering to an SREL, or you may do your on ad_hoc definition.  When you ask for any information from the attribute, we instance a Domset that contains the information and displatch the message to that domset.  Therefore this attribute has the same behavior as a domset.

Attributes:  The domset has two attributes which represent the number of items in the domset.  These can be accessed using any of the methods under VLAT:PAT:MTH: below. length - The current length of the domset.  * approx_count - a slower incrementing count for the GUI.

Warm Links:  The domset supports several warm links.  The user can request to set up a notificaiton when the warm link occurs.  start_fetch - a fetch has been started.

finish_partial - A fetch has been completed up to the number asked, but there may be more to fetch.

finish_fetch - A fetch is completed (EOF)

Methods:

get_attr( string attr_name )

 

If you want to get a dob in the list that is the lrel, you can use this call. If the first entry is a number, we will look for the dob at that index in the domset.  If the first entry is not a number, we will assume index 0.  The dob returned is not re-mapped on a change of the domset.  You just get it.

The index is based on the default sort order.

Arguments

string attr_name                                The name you want to get

On Error

If the attr_name is not found E_UNKNOWN_NAME - string error_text

If no dob at that index E_NOT_FOUND - string error_text

On Success

Object_Ref  attr_object                   // The requested object.

 

call_attr( string attr_name , string method_to_call, ...)

Similar to the call_attr in other places.  The difference is that we will accept an index number as part of the dotted string and look up that index.  Irf you do not pass an index number, we assume 0.  The index is based on the DEFAULT sort for the domsrvr.

Arguments

string attribute_name,                         Attribute name to send message to

string method_to_call,                         Message name to use.

...                                                          Args for the message you are sending

On Error

For a bad attribute name E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

If no dob at that index E_NOT_FOUND - string error_text

On Success

Depends on what the dispatched method returns.  This function itself returns no reply except for errors.

 

 
 

PLREL:PAT:MTH: An lrel attribute.

 

This attribute represents a many to many relationship.  Unlike the QREL which is a 'passive' filter that puts items that match some query, this relation allows the user to add and delete entries into it.

 

As in the other list type attributes, we support the call_attr and get_attr calls where the index number is the index number of the entry in the list you want to access.

 

Be aware the lrel is not based on the domset, so the other standard domset methods are not available to you.

Attributes:

      length

Warm Links:

      list_change

Methods:

persid_by_index()

 

add_dob( Object_Ref dob_to_add, [ int where_to_add])

This is the call to add the dob to the lrel.  The parent object must be checked out prior to this being done. There is an ordering in the lrel which you can manipulate here.  Each dob in the lrel has a specific index in relation to the other dobs.  If you pass in an index value, it will put this one at the defined index and 'shove the others' down one.  If you don't supply the argument, it places the new one at the end of the list..

Arguments

Object_Ref dob_to_add                                              The dob you want to add

int   where_to_add                                                        Optional index of where to add it

On Error

If not checked out E_UPDATE_NOT_CHECKED_OUT - string error_text

On Success

string                   "OK"

           

remove_dob( Object_Ref dob_to_remove)

Remove the provided dob from the list.  If the dob is not found, we quietly ignore it and tell you all is well.

Arguments

 

On Error

An internal error E_BAD_ARG - string error_text

If not checked out E_UPDATE_NOT_CHECKED_OUT - string error_text

On Success

string "OK"

 

move_dob(   int from, int to)

Move a dob from one location to another location.  If the from/to are bad, we simply ignore them.

 

Arguments

 

On Error

An internal error E_BAD_ARG - string error_text

If not checked out E_UPDATE_NOT_CHECKED_OUT - string error_text

On Success

string "OK"

 

get_attr( string attr_name )

If you want to get a dob in the list that is the lrel, you can use this call. If the first entry is a number, we will look for the dob at that index in the domset.  If the first entry is not a number, we will assume index 0.  The dob returned is not re-mapped on a change of the domset.  You just get it.

The index is based on the default sort order.

Arguments

string attr_name The name you want to get

On Error

If the attr_name is not found E_UNKNOWN_NAME - string error_text

If no dob at that index E_NOT_FOUND - string error_text

On Success

Object_Ref  attr_object                                               // The requested object.

 

 

call_attr( string attr_name , string method_to_call,

     ...)

 

Similar to the call_attr in other places.  The difference is that we will accept an index number as part of the dotted string and look up that index.  Irf you do not pass an index number, we assume 0.  The index is based on the DEFAULT sort for the domsrvr.

Arguments

string attribute_name,       Attribute name to send message to

string method_to_call,      Message name to use.

...                          Args for the message you are sending

On Error

For a bad attribute name E_UNKNOWN_NAME - "Unknown name" , string attr_name, "."

If no dob at that index E_NOT_FOUND - string error_text

On Success

Depends on what the dispatched method returns.  This function itself returns no reply except for errors

* Private Methods:

      * ob_checkout()

      * ob_checkin()

      * ob_uncheck()

      UI_persid_by_index()

 
 

APPENDIX

 

attr_status:

A four char string that gives state info about the attribute.  Each position in the string represents one of the headings below:

                Access = 'V' - Read Only (view) , 'W' - Read/Write,       'X' - Denied access

                Require= 'R' - Required,  'O' - Optional

                Status = 'N' - New object (Not in the backstore),            'D' - Deleted object

                        'C' - checked out - non-new record

                        'B' - Object is backstored. - And not checked out.

                        'T' - Checkout not possible (IE a factory)

                Attr Mod='M" - Modified, 'O' - Original value,

                         'X" = Not applicable (like a factory)

The string is returned from various calls, and is also sent on a hotlink message so the user knows how to change the display, etc.

If no state information is available, the string '????" is sent.

 

type_info_reply;

The type_info call returns various things depending on what it is called. To make it easier, we have put the returns here.

 

The format of the reply is always the same.  We return the attribute name of the object of interest ( if it is not an attribute we return the string "NA"), the kind of object it is, and interesting data based on the type of object.  here are the returns.

           FACTORY  A factory                                   PRODUCER A producer

           VALUE    A Value attribute              SREL     A single relation

           QREL     Qurey relation                                LREL     List relation

           DOB    A dob

Error Reply:

string "No information available on this object."

Success Replies.

For Factory:

                 string attr_name,  Attribute name

                 "FACTORY",       Tells you it is a factory

                 string class_name,           full class name for factory

                 string rel_attr,      Rel_Attr as defined in majic file

                 string common_name, Common name defined in majic file

                 string func_group_name     Func group defined in majic file

For Producer:

                 string attr_name,  Attribute name

                 "PRODUCER",    Tells you it is a producer

                 string class_name       The class name

           For a Value Attribute:

                 string attr_name,  Attribute name

                 "VALUE",            Tells you it is a value attr

                 int val_type          Enum of value type. (See below)

                 int string_len        Length of string if type is string

                 string access_type           access restriction( see below)

                 string required_flag,

           For an SREL Attribute:

                 string attr_name,  Attribute name

                 "SREL",    Tells you it is an srel

                 string factory_name,       What factory contains the srel

                 string attr_name,  Rel Attr from the factory

                 string access_type,

                 string required_flag,

           For a QREL Attribute:

                 string attr_name,  Attribute name

                 "QREL",   Tells you it is a qrel

                 string factory_name,       What factory contains the srel

                 string where_clause,        What where clause is used to fill.

                 string param_list, What paramaters to read from obj

                 string domset_name,       What domset should we use

                 string domset_sort,          Sort cols in the domset

                 string domset_fetch         list cols in the domset

For an LREL Attribute         

                 string attr_name,  Attribute name

                 "LREL",    Tells you it is an lrel

                 string fetch_fac,   Factory holding the info.

String dob_name, Dob name ???

               For a Domset:

                 string "NA",         Dummy to keep alignment working ok

                 "DOMSET",         Tells you it is an lrel

                 string domset_name,       Factory holding the info.

                 string fac_template,

                 string fac_name,

                 string domset_sort,          Sort cols in the domset

                 string domset_fetch         list cols in the domset

                 string "STATIC" | "DYNAMIC"  static flag

                 string AD_HOC | SESSION | USER  | GLOBAL other flags

For a Dob:

                 string "NA",         Dummy to keep alignment working ok

                 "DOB",     Tells you it is an lrel

                 string producer_name      The producer

                 string persistent_id          presid of dob

                Access_type is one of :

                "Constant" - Cannot be modified

                "Private" -  Modifiable only by Triggers, etc.

                "Public"  - Modifiable

                "Write If New" - Write only on first time.

                "Unknown" - an error

                required_flag is one of

                "Required" - is required

                "Not Required" - not requried.

 
 

 

This is info re how checkouts work, who gets the message, etc.  This is terse and only intended to remind someone who understands what is going on what the order, etc is.

Here is the message flow for 'normal' processing for some common group leader stuff.

CHECKOUT:

 

    x               GL                                        ?ob          P_Dob

       checkout

1    ============>

       (***)

                    ** Ex session

         ob_checkout

      *================>

2 ---- c code ---->

                    [ add_to_checkout(n)                ]

3    [<==============================*]  (A CO may cascade)

                     ob_co_results

4    <================================*  (Paired with ob_checkout)

      (while there are more to co (from 'add')

                     ob_checkout

5    *=================================>

                    [ add_to_checkout(n)                ]

      [<==============================*] 

                     ob_co_results

      <================================*

                     ob_grp_co_done (n)

6    *================================>  (One for each 'ob_checkout)

7   ** End ex sessions

         (***) OK

    <===========

 

  1. Outside object sends a checkout msg to the group leader.  Group leader sets an exclusive session and sends an ob_checkout message to the object referenced in the checkout message.  That object is typically a Dob or an Attribute
  2. The object recieving the message routes it via c++ code to the 'real' object to be checked out (IE the P_Dob).
  3. Checking out a P_Dob may cause additional checkouts to be done.  ( On attributes of the P_Dob for example).  In this case the additional things to be checked out are 'added' to the GL with the add_to_checkout message.
  4. The P_Dob returns the results of it's checkout.  (Let's assume it is ok) if it fails, we jump to ob_grp_co_done with a fail.
  5. If we have added any things to the group leader, we send (one at a time) an ob_checkout message to them.  The ob_checkout may again generate additional add_to_checkout, etc.  Finally we get the 'last' ob_co_results message.
  6. We send an ob_grp_co_done message to all objects which have been checked out so they can set their internal states appropriately, etc. If the CO failed, we tell the objects here so they can revert to non-checked out.
  7. Exclusive session is finished, and we tell the original requestor how we did.

GETTING A NEW OBJECT (DOB)

 

    x       factory              gl          prod p_dob        lrel_in_pdob

 

    get_new_dob

1   ===========>

       (***)

                    start_newco

                   =============>

2                                     * EX session

                                       get_new

                                       ========>

3                                                 --- c++ --->

                                                     add_to_newco (n)

4                                     <==============================

                                                 add_to_newco

                                       <======================

                                           ob_newco_complete

                                       <======================

                                            ob_newco_done

5                                     ======================>

                                                   ob_newco_done(n)

                                       ===============================>

                                       *EX end

       (***) new_dob

6 <========================

 

  1. Some object asks for a new dob from the factory.  It builds the start_newco message and sends it to the group_leader
  2. Group leader starts and exclusive session, gets 'who' to ask for the new object and what to call from the start newco.  Sends the message (in this case get_new to the producer).
  3. The producer creates the P_Dob.  As part of the creation any lrel's get checked out as well.  They do this by sending an add_to_newco call to the group leader.
  4. The P_Dob adds itself to the things checked out (add_to_newco) and tells the group leader it is done (ob_newco_complete).
  5. The group leader notifies the things being 'newed / checked out' that the newco is done. and ends it's exclusive session.
  6. original object gets passed the 'new' dob.

CHECKIN on 2 pdobs.

x              GL                          P_Dob1                      P_Dob2

 

     checkin

1   ========>

     (xx)

                                      

                ** EX SESSION

                   ob_preval_trig

2              ======================>

                ob_preval_trig_reply

                <=====================

                                    ob_preval_trig

                ======================================>

                                    ob_preval_trig_reply

                <=====================================

                   ob_preval_trig

                ======================>

                ob_preval_trig_reply

                <=====================

 

                   ob_val

  1. ======================>

                ======================================>

                   ob_val_reply

<======================

                <======================================

 

                                    ob_postval_trig

  1. ======================================>

                                    ob_postval_trig_reply

                <=====================================

                   ob_postval_trig

                ======================>

                ob_postval_trig_reply

                <=====================

 

                   ob_ci

5              ======================>

                ======================================>

6

                   ob_ci_reply

                <======================

                <======================================

ob_ci_complete

                ======================>

                ======================================>

                ** End EX session

     (xx)

7    <========

 

  1. CI message sent to group leader.
  2. Group leader figures out order of pre-val trigger to be called (based on ordinal number in triggers for the objects to be chekced in).  It sends messages to the objects in appropriate order/ranges to assure that the triggers are sequenced and done in the proper order.
  3. After pre_val triggers are all done, we do a backstore (database) validation.There is no sequencing on this.  All objects get the request at the 'same' time.

 

  1. We sequence all postval triggers for the objects.

 

  1. If all is well (ie postval does not fail) we tell the objects to check themselves in. There is no sequence here.

 

  1. After an object is checked in, it does any post_ci triggers (and event triggers in the future) with no pre-determined order.

 

  1. The objects reply with 'done' and we inform the original caller.

 
 

Error Codes

The following is for m'soft

        E_FAILURE = 1,                        // 1 Failure.

        E_INVALID ,                             // 2 Invalid.

        E_TOO_MANY_ARGS ,           // 3 Too many args.

        E_INSUFFICIENT_ARGS ,    // 4 Insufficient args.

        E_BAD_ARG_TYPE ,               // 5 Bad arg type.

        E_BAD_LIST_TYPE , 6 Bad type-expected long list count.

        E_TIMEOUT,                             // 7 Msg method call timed out

        E_ILLEGAL_CALL ,                 // 8 Illegal call on an object.

        E_INTERNAL ,                          // 9 Internal problem.

        E_UNKNOWN_MESSAGE ,// 10 Unknown message.

        E_UNKNOWN_NAME ,            // 11 Unknown name.

        E_UPDATE_NOT_CHECKED_OUT ,     // 12 EMSG_UPDATE_NOT_CHECKED_OUT

        E_UPDATE_NOT_POSSIBLE ,     13 Cannot update for various rsns

        E_CHECKIN_NOT_CHECKED_OUT ,   // 14 EMSG_CHECKIN_NOT_CHECKED_OUT

        E_ABANDON_NOT_CHECKED_OUT , // 15 EMSG_ABANDON_NOT_CHECKED_OUT

        E_CHECKOUT_NOT_POSSIBLE ,          Checkout not possible.

        E_NOT_CHECKED_OUT ,       // 17 Not checked out.

        E_UNINITIALIZED_ATTRIBUTE ,         // 18 Attempt to send to un-init attr.

        E_UNKNOWN_ATTRIBUTE_NAME ,    // 19 Unknown attribute name

        E_NO_WARM_LINK ,           Warm link category not found.

        E_REQUEST_DENIED ,         NO.

        E_VALIDATE_NOT_CHECKED_OUT , Attempt to validate with nothing..

        E_MODIFY_NOT_CHECKED_OUT , Attempt to modify with out ...

        E_ACCESS_NULL_VALUE,  Attempt to acess NULL value.

        E_ABORT,                                 Abort the trigger methods

Errors in the domain server

        E_DOMSET_NAME = 100,    100 Bad domset name passed in

        E_NOT_SUPPORTED,            101 Call of non-supported feature

        E_NOT_FOUND,                     102 Item not found

        E_BAD_ARG,                         103 Bad argument value passed in

        E_CHECK_DEL,                    104 Attempt to checkout deleted

        E_CHECK_NULL,                   105 Attempt to CO a null object

        E_SREL_CO_CONFLICT,      106 Attempt to set an CO srel

        E_REMAP_CO,                      107 Dob remap on checked out dob1

        E_REMAP_BAD_CLASS,      108 Attempt to remap to a bad class

        E_IN_FETCH,                         109 We are in a fetch and can't do it

        E_NO_MORE_FETCH,          110 No more fetch possible

        E_BAD_DOMSET_TYPE,      111 A bad domset type

        E_BAD_MERGE_TYPE,        112 Can't merge that

        E_DUPLICATE,                      113 Duplicate

Errors for Animation

        E_INVALID_TARGET = 200, 201 Bad target +/or method specified

        E_INVALID_PERSID_ID, 202 Bad target instance specification

        E_INVALID_TYPE,                       203 Bad target type

        E_INVALID_POST_ACTIVITY,    204 Bad post action

        E_UNKNOWN_ERROR_CODE   205 Always the last error code

Outcomes