DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
Designing SCOadmin object service agents

Application procedures

For each valid operation that a object class can perform on an object instance, the OSA writer must provide some procedure to apply that operation. There are three types of application procedures (or operation execution procedures); per attribute, per object and action. Whenever any of these procedures are called, they are all passed an identically formatted data structure. Each type of execution procedure will only be concerned with select portions of the data structure passed to them. This is implemented in this manner so as to facilitate OSA writers who wish to combine execution procedures that might be similar but of different synchronization. For instance, an OSA writer may wish to combine the create and replaceWithDefault functions, or the filter and get functions. Then the execution procedure would just have to identify what it is being asked to do exactly by looking in the data structure passed to it, and ignore the portions of the data structure that are irrelevant to its operation.

Attribute operations

These can be performed on one or more attributes specified when the operation is called. Those procedures that are invoked per attribute will be called once for each attribute listed in the client's request for each object in the request.

An operation of this type can be applied individually on each of the attributes specified on the command line, or on all the attributes at once. This synchronization of this application is left up to the OSA writer to decide. If the writer decides to have each attribute applied individually (on a per attribute basis), then each attribute application should be attempted regardless of the success or failure of any attribute's attempt. If the writer decides to have all the given attributes evaluated at once (on a per object basis), then the writer should write code that will either always apply all the attributes successfully, or none at all. The operations that modify or access an object's attributes can be described this way are as follows:


get
Return a value or set of values for each specified attribute. If no attributes are specified, the values of all attributes of the current object are returned.

replace
Replace the current value of the specified attribute with a new specified value.

replaceWithDefault
Replace the current value(s) of the specified attribute(s) with a default value. If no attributes are specified, replace attribute values for the current object instance with defaults.

add
Add the specified value(s) to the current value(s) of the specified attribute of the current object instance. (Make sure the value is part of the set.)

remove
Remove the specified value(s) from the current value(s) of the specified attribute of the current object instance. (Make sure the value is not part of the set.)

filter
Limit the affected object instances as defined. This is the only operation of all the attribute accessing functions that can only be written on a per attribute synchronization.
In the passed data structure, only these parameters are important to per-attribute operations:

class name
The class to which the specified object instance belongs. This accommodates sharing procedures between classes.

object name
The object instance being worked on. The OSA should check the existence or validity of the object instance.

operation name
The operation being worked on. This accommodates procedures being shared by operations by providing a way for the procedure to identify which operation is calling it.

attribute token
The token for the attribute being worked on. Simple operations can act on each attribute in one procedure, but more complex operations can simply identify which attribute is being worked on and forward to relevant information to an appropriate subroutine.

attribute list
The attributes (and corresponding values) specified when the operation was called.

Object operations

These are performed on each object instance as a whole. Object operations:

All of these operations require that an object instance be specified:

create
Create the object; assign any attributes to the object instance.

delete
Remove the object instance.

action
Perform this action with arguments specified. The Server API will not check the arguments or any returned information for validity.

list
Evaluates the given object instance and returns a list of all the object instances that are contained by the specified object instance. This is used in containment and scoping. Every class that has object instances contained by another should have a list function.

Those procedures that are invoked per object will be called only once per object instance listed in a client's request.

In the passed data structure, only these parameters are important to per-object operations:


class name
The class to which the specified object instance belongs. This accommodates sharing procedures between classes.

object name
The object instance being worked on. The OSA should check the existence or validity of the object instance.

reference object name
The name of a template object instance used by the create operation to create the specified object instance. When used, the template is created by duplicating an existing object instance. If not a template is not used, the field is blank.

operation name
The operation being worked on. This accommodates procedures being shared by operations by providing a way for the procedure to identify which operation is calling it.

attribute token
The token for the attribute being worked on. Simple operations can act on each attribute in one procedure, but more complex operations can simply identify which attribute is being worked on and forward to relevant information to an appropriate subroutine.

attribute list
The attributes (and corresponding values) specified when the operation was called.

Action operations

Action operations can be only be called with "per object" synchronization, but unlike the regular per object, only only these parameters are important to per-action operations:


class name
The class to which the specified object instance belongs. This accommodates sharing procedures between classes.

object name
The object instance being worked on. The OSA should check the existence or validity of the object instance.

action name
The specific action being worked on. This accommodates actions being shared by operations by providing a way for the action to identify which operation is calling it.

action data
The arguments specified for the action it was called.

Next topic: Filter procedures
Previous topic: Defining execution procedures

© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003