bstr_object_create(3) — Subroutines

Name

bstr_object_create − Creates an object belonging to the specified class.

Syntax

bstr_t_status bstr_object_create (
                                   bstr_t_fullname    name,
                                   bstr_t_class       class,
                                   bstr_t_sequence    ∗attributes,
                                   bstr_t_rcb         ∗control,
                                   bstr_t_reference   ∗object);

Description

The bstr_object_create procedure creates an object whose full or relative name is specified in name. In addition, the class argument specifies the class to which the object you are creating belongs.

The value contained in each element of the attributes sequence is used by BASEstar Open to set the value in the corresponding attribute of the created object. The attributes argument can be set to NULL for an object which does not have required attributes and for which you do not need to specify the value for one or more of the optional attributes.

The procedure returns the reference to the created object in object.

The table below lists the classes that can be instantiated using the bstr_object_create procedure; for each of them, it specifies the constraints that apply when creating an object.

Class Name	Conditions
Array_Datatype	The specified datatype must already exist.
Structure_Datatype	The specified datatypes must already exist.
Domain	The father Domain must already exist.
Timer	None
Data_Point	The specified datatype must already exist.
Mapped_Data_Point	The specified datatype must already exist. The Data_Point to which you wish to map the Mapped_Data_Point that you are creating must already exist in the Mapped_Data_Point Domain.
Device_Data_Point	The specified datatype must already exist. The specified Device Services MMS variable must already exist.
Data_Point_Set	The Data_Points specified in the components attribute must already exist and must belong to the Domain in which you are creating the Data_Point_Set.
Filter	None
Trigger	The associated Data_Point and Filter must already exist and must belong to the same Domain as the associated Trigger. The Events and Data_Points specified in the event_parameters and filter_parameters attributes must already exist. You can only specify the timer attribute if the trigger_evaluation attribute is set to BSTR_C_ON_TIMEOUT. The associated Timer must already exist.
Event	The datatypes specified in the parameter_types attribute must already exist.
Event_Set	Any Event object (if specified in the components attribute) must already exist and must belong to the Domain in which you are creating the Event_Set.
Enbox	None
Packet	The datatypes specified in the input_parameter_types and output_parameter_types attributes must already exist.
Port	None
Named_Variable	The datatype specified in the datatype attribute must already exist.
Polling_Set	The Named_Variables specified in the named_variable_list attribute and the Unnamed_Variables specified in the unnamed_variable_list attribute must already exist.
Protocol_Profile	None
Unnamed_Variable	The datatype specified in the datatype attribute must already exist.
VMD_Extension_Parameter	None
Activity	The objects referred to in the Program, Nodes, Domains and VMDs attributes must already exist.
Actor	The parent Actor must already exist.
Node	None
Program	None

Arguments

name
access: read
The full or relative name of the object that you wish to create.

class
access: read
The class to which the object you are creating belongs.

attributes
access: read
The address of a sequence. The attributes argument can be set to NULL for an object which does not have required attributes and for which you do not need to specify the value for one or more of the optional attributes.

Each element in the sequence carries the name of an attribute and the value that must be assigned to it.

Each specified element of the sequence carries the value to be assigned to an attribute of the object that you are creating. Depending on its associated datatype, the attribute value can be an immediate value, a reference to another object or an address to a nested sequence. As a result, the relevant fields to be set in each bstr_t_sequence_element are as follows:

•type. Specifies the type of the sequence element, according to the type of attribute value being specified, as follows:

•Set to BSTR_C_VALUE for an immediate value.

•Set to BSTR_C_REFERENCE for a reference to another object.

•Set to BSTR_C_SEQUENCE for a nested sequence.

•attribute_name. A constant that identifies an attribute of the object that you are creating.

•size. Specifies the size of the value buffer (that is, the size of the attribute value).

•value. Specifies the address of the buffer containing the value of an attribute. Depending on the value of the type field, enter one of the following addresses:

•BSTR_C_VALUE. The address of a buffer containing the attribute value. The allocated buffer must be consistent with the attribute value type.

•BSTR_C_REFERENCE. The address of a bstr_t_reference variable which contains a reference to another object.

•BSTR_C_SEQUENCE. The address of a bstr_t_sequence variable which specifies the address of a nested sequence.

control
access: read
The address of an optional request control block.

object
access: write
Returns the reference to the created object. The reference must be specified in subsequent procedure invocations that refer to the created object.

Return Values

BSTR_S_ABORTED	Operation aborted
BSTR_S_ATTRIBUTE_IGNORED	Attribute(s) ignored because not supported on Volatile
BSTR_S_BAD_DATA_ELEMENTS	Bad data elements
BSTR_S_BAD_PARAMETER	Bad parameter value
BSTR_S_BAD_REFERENCE	Bad reference
BSTR_S_BAD_SEQUENCE	Bad sequence
BSTR_S_COMMUNICATION_ERROR	Communication error
BSTR_S_COM_PC_SIZE_MISMATCH	Number of bytes requested does not match the number of bytes returned
BSTR_S_DEVICE_SERVICES_NOT_AVAILABLE	Device Services not available
BSTR_S_FINISH	Request aborted by bstr_finish
BSTR_S_INTERNAL_ERROR	Internal error
BSTR_S_INTR	Operation interrupted
BSTR_S_INVALID_NAME	Invalid name
BSTR_S_INVALID_OPERATION	Invalid operation
BSTR_S_INVALID_RCB	Invalid Request Control Block
BSTR_S_NORMAL	Normal successful completion
BSTR_S_NOT_IMPLEMENTED	Not yet implemented
BSTR_S_NOT_INITIALIZED	BASEstar Open not initialized
BSTR_S_NO_MEMORY	Insufficient virtual memory
BSTR_S_REFERENCE_IN_USE	Reference already in use
BSTR_S_SERVICES_NOT_AVAILABLE	Services not available
BSTR_S_TIMEOUT	Timeout expired
BSTR_S_TOO_MANY_REQUESTS	Too many pending requests