Designing SCOadmin object service agents

Execution procedure data structures

The Tcl execution procedures receive information structured around nine parameters shown in ``Tcl parameters''.

Tcl parameters

Parameter per
attribute per
object action
filter
list Description

className used used action
filter
list This is the name of the class being used. This list field is included as several classes can exist in a single program, and multiple classes can share the same execution procedures. In the case of the list operation, this is the name of the subordinate class.

objectName used used action
filter
list This is the object being operated on. In the case of the list operation this is either the name of the superior class (if the original BMIP request gave a NULL object instance) or the object instance named (if one was given in the original BMIP Request).

referenceObjectName ignored create
only If the operation is a create and a reference object was provided by whatever called the Server API, then its identifying string is included here. Otherwise this is an empty string.

operationName used used action
filter
list This is the operation or filter being performed. This field is included as several operations or filters can possibly share the same execution procedures if so needed, and thus the procedures will need to tell which operation or filter they are working for.

subOperationName ignored ignored action
filter If this is an action or filter operation, the exact action or filter being performed is listed here. Otherwise this field is left empty.

subDataField ignored ignored action
filter If this is an action or filter operation this is either; the raw data passed to an action operation, or a list containing the values of the data the a filter will compare an attribute against.

attributeToken used ignored filter This is the string that corresponds to the tokens described in the OSAs CDT attribute section. This field will only be used by filters or by per attribute operations.

attributeList used used This is a list of all the attributes or attribute-value pairs given on the command line for any operation. This field is not used by filters. Attribute-value pairs (such as given to the replace operation) will take the form of {{attr1 value1} {attr2 value2} ...} and attribute lists (such as those given to the get operation) will take the form of {{attr1} {attr2} ...}

osaData opt opt action
filter
list This is an optional OSA defined handle that can be associated with a class at the time the OSA calls OFBinding. This handle can contain any string, and its use is optional. It is provided as a tool for the OSA writer.

When returning values from execution procedures to the Server API, the following functions should be used:

Parameter	per attribute	per object	action filter list	Description
className	used	used	action filter list	This is the name of the class being used. This list field is included as several classes can exist in a single program, and multiple classes can share the same execution procedures. In the case of the list operation, this is the name of the subordinate class.
objectName	used	used	action filter list	This is the object being operated on. In the case of the list operation this is either the name of the superior class (if the original BMIP request gave a NULL object instance) or the object instance named (if one was given in the original BMIP Request).
referenceObjectName	ignored	create only		If the operation is a create and a reference object was provided by whatever called the Server API, then its identifying string is included here. Otherwise this is an empty string.
operationName	used	used	action filter list	This is the operation or filter being performed. This field is included as several operations or filters can possibly share the same execution procedures if so needed, and thus the procedures will need to tell which operation or filter they are working for.
subOperationName	ignored	ignored	action filter	If this is an action or filter operation, the exact action or filter being performed is listed here. Otherwise this field is left empty.
subDataField	ignored	ignored	action filter	If this is an action or filter operation this is either; the raw data passed to an action operation, or a list containing the values of the data the a filter will compare an attribute against.
attributeToken	used	ignored	filter	This is the string that corresponds to the tokens described in the OSAs CDT attribute section. This field will only be used by filters or by per attribute operations.
attributeList	used	used		This is a list of all the attributes or attribute-value pairs given on the command line for any operation. This field is not used by filters. Attribute-value pairs (such as given to the replace operation) will take the form of {{attr1 value1} {attr2 value2} ...} and attribute lists (such as those given to the get operation) will take the form of {{attr1} {attr2} ...}
osaData	opt	opt	action filter list	This is an optional OSA defined handle that can be associated with a class at the time the OSA calls OFBinding. This handle can contain any string, and its use is optional. It is provided as a tool for the OSA writer.

For most execution procedures (create, delete, get, add, remove, replace, and replaceWithDefault) the returned value should be a list of the affected attributes and their new values or any errors that occurred. In Tcl the execution procedures should return a list of attribute value pairs, such as (for single and set valued attributes):
```
   return "{attribute value}"
```
or
```
   return "{attribute {value1 value2}}"
```
In C/C++ the execution procedures should use the helper functions provided to return the values into structure pointed to by the OSAArgDesc_t's retValues attribute. These C/C++ helper OSAReturn...() functions can be called repeatedly in order to return a set of values for on attribute. For example:
```
   OSAReturnLong(retValues, attributeToken, singleIntegerValue);
```
or
```
   OSAReturnString(retValues, attributeToken, setStringValue[0]);
   OSAReturnString(retValues, attributeToken, setStringValue[1]);
```
The Tcl execution procedure for the action operation should simply return the string that it wants to return. For example:
```
   return "{This is action data}"
```
The C/C++ execution procedure for the action operation should use the helper functions provided. For example:
```
   OSAReturnActionData(retValues, actionDataString);
```
The Tcl execution procedure for the filter operation should return either the string "TRUE" or the string "FALSE". For example:
```
   return TRUE
```
The C/C++ execution procedure for the filter operation should use the helper function that is provided for this purpose. This function takes a bool_t type value, as defined in /usr/include/scoAdmin/sysAdmStd.h (TRUE or FALSE). For example:
```
   OSAReturnBoolean(retValues, TRUE);
```
The Tcl execution procedure for the list operation should return a list of those objects that are included in the named superior class. For example:
```
   return "{object1 object2 object3}"
```
The C/C++ execution procedure for the list operation should use the same helper function that is used to return action information. This function can be called repeatedly to return more than one object instance. For example:
```
   OSAReturnActionData(retValues, objectName1);
   OSAReturnActionData(retValues, objectName2);
```
Errors that should be returned from Tcl should be done using the ErrorPush helper function, for example:
```
   ErrorPush {} 1 SCO_OSA_ERR_NO_SUCH_OBJECT_INSTANCE $objectName
```
Errors that should be returned from the C/C++ exec procs should be done using the Error Push helper function, for example:
```
   ErrorPush(errStatusPtr, &SCO_OSA_ERR_NO_SUCH_OBJECT_INSTANCE, object);
   return;
```

In C the execution procedures are given two parameters; the errStatus_cl* and a pointer to an OSAArgDesc_t. The latter is a struct containing all the information the execution procedure will need from the Server API to perform its job. The structure is shown in ``C/C++ structure'' and explained in ``C/C++ parameters''.

struct OSAArgDesc_t {
    objectClass_pt      className;
    objectName_pt       objectName;
    objectName_pt       createObjRef;
    operation_pt        operationName;
    filterToken_t       filterToken;
    attributeToken_t    attrToken;
    int                 filterValueCount;
    attributeValue_t   *filterValueArray;
    ofParameterList_cl *attrList;
    ofParameterList_cl *retValues;
    actionType_pt       actionTypePtr;
    actionInfo_pt       actionInfoPtr;
    void               *osaData;
}

C/C++ structure

C/C++ parameters

Parameter per per action Description

attribute object filter

list

className used used action
filter
list This is a char * labeling the class being used. This is included as several classes can exist in a single program, and multiple classes can share the same execprocs. In the case of the list operation this is the name of the subordinate class.

objectName used used action
filter
list This is a char * labeling the object being operated on. In the case of the list operation this is either the name of the superior class (if the original BMIP request gave a NULL object instance) or the object instance named (if one was given in the original BMIP request).

createObjRef ignored create
only This is a char * labeling the reference object a create operation will use for a template. It will be set to NULL if not being used.

operationName used used action
filter
list This is a char * labeling the operation or filter being performed. This is included as several operations or filters can share the same execution procedures.

filterToken ignored ignored filter If the operation being executed is a filter than this will indicate what filter function should be evaluated.

attrToken used ignored filter This is an attributeToken_t that corresponds to the tokens described in the OSAs CDT attribute section. This field will only be used by filters or by per attribute operations.

filterValueCount ignored ignored action
filter This is an int that corresponds to the number of attributeValue_t are listed in the next entry. This field is only used by filter commands, and by action operations.

filterValueArray ignored ignored action
filter This is an attributeValue_T array alloc'd by the Server API. It contains the values of the data the a filter will compare an attribute against; or the raw data that will be used by an action operation.

attrList used used This is a list of all the attributes or attribute-value pairs given on the command line for any operation. This list can only be seen through the library helper functions provided by the Server API. This field is not used by action, filter or list operations.

retValues used used action
filter
list This is used by all execution procedures when returning data to the Server API. This should only be done for the Get and Action operations, and by the filter and list procedures.

actionTypePtr ignored ignored action When an action operation is being evaluated, this char * will name of the specific action being executed on the named object.

actionInfoPtr ignored ignored action When an action operation is being evaluated, this char * will point to the raw data that was passed to the Server API by whatever invoked it.

osaData opt opt action
filter
list This is an optional OSA defined pointer that can be associated with a class at the time the OSA calls ofBinding. This point can point to anything, and its use is optional. It is provided as a tool for the OSA writer.

Parameter	per	per	action	Description
	attribute	object	filter
			list
className	used	used	action filter list	This is a char * labeling the class being used. This is included as several classes can exist in a single program, and multiple classes can share the same execprocs. In the case of the list operation this is the name of the subordinate class.
objectName	used	used	action filter list	This is a char * labeling the object being operated on. In the case of the list operation this is either the name of the superior class (if the original BMIP request gave a NULL object instance) or the object instance named (if one was given in the original BMIP request).
createObjRef		ignored	create only	This is a char * labeling the reference object a create operation will use for a template. It will be set to NULL if not being used.
operationName	used	used	action filter list	This is a char * labeling the operation or filter being performed. This is included as several operations or filters can share the same execution procedures.
filterToken	ignored	ignored	filter	If the operation being executed is a filter than this will indicate what filter function should be evaluated.
attrToken	used	ignored	filter	This is an attributeToken_t that corresponds to the tokens described in the OSAs CDT attribute section. This field will only be used by filters or by per attribute operations.
filterValueCount	ignored	ignored	action filter	This is an int that corresponds to the number of attributeValue_t are listed in the next entry. This field is only used by filter commands, and by action operations.
filterValueArray	ignored	ignored	action filter	This is an attributeValue_T array alloc'd by the Server API. It contains the values of the data the a filter will compare an attribute against; or the raw data that will be used by an action operation.
attrList	used	used		This is a list of all the attributes or attribute-value pairs given on the command line for any operation. This list can only be seen through the library helper functions provided by the Server API. This field is not used by action, filter or list operations.
retValues	used	used	action filter list	This is used by all execution procedures when returning data to the Server API. This should only be done for the Get and Action operations, and by the filter and list procedures.
actionTypePtr	ignored	ignored	action	When an action operation is being evaluated, this char * will name of the specific action being executed on the named object.
actionInfoPtr	ignored	ignored	action	When an action operation is being evaluated, this char * will point to the raw data that was passed to the Server API by whatever invoked it.
osaData	opt	opt	action filter list	This is an optional OSA defined pointer that can be associated with a class at the time the OSA calls ofBinding. This point can point to anything, and its use is optional. It is provided as a tool for the OSA writer.

Library functions

If you wish to learn more about the helper functions provided by the Server API, consult Section TCL_ADM manual pages and Section S_ADM manual pages.