bstr_reference_set(3) — Subroutines
Name
bstr_reference_set − Sets the reference to an object.
Syntax
bstr_t_status bstr_reference_set (
bstr_t_fullname name,
bstr_t_class expected_class,
bstr_t_behaviour type,
bstr_t_rcb ∗control,
bstr_t_reference ∗reference,
bstr_t_class ∗actual_class);
Description
The bstr_reference_set procedure returns in reference the reference to the BASEstar Open object whose name is specified in name. The object may be identified by its full name, or by a relative name. You can only specify a relative name if you have set the appropriate context with the bstr_context_set_default procedure.)
The type argument is used to specify how and when the reference must be evaluated.You must also specify the expected_class of the object that you want to reference, but the procedure returns the class identifier to which the object actually belongs in actual_class. The returned reference must be specified for any subsequent operations on the specified object since, in most cases, objects are identified by reference rather than by name.
If you invoke the bstr_reference_set procedure to set the reference to a datatype object, you must set type to BSTR_C_ON_FIRST_USE.
Arguments
name
access: read
The name of the object for which a reference is required. This argument can specify a full name, or a relative name if you have set the appropriate context.
expected_class
access: read
The class to which the object is expected to belong.
type
access: read
Indicates how and when the required reference must be evaluated. Possible values are as follows:
| Constant Name | Reference Evaluation |
| BSTR_C_NOW | A fast-access and implementation-dependent reference is evaluated and returned. This implies getting the object reference from the appropriate server. |
| BSTR_C_ON_FIRST_USE | The reference is returned immediately, but it is only evaluated when the first operation on the object referred to is performed. This means that the bstr_reference_set procedure only performs local operations, and that the reference value is obtained from the appropriate server the first time the reference performs an operation on the object. |
| BSTR_C_ON_EVERY_USE | Reserved for future use. |
| BSTR_C_RECOVERY_REQ | The reference is recoverable (by means of the bst_reference_recover procedure.) |
control
access: read
The address of the optional request control block.
reference
access: read/write
Returns the object reference.
actual_class
access: write
The optional address of a bstr_t_class structure (NULL must be specified otherwise). If specified, the structure returns the object class as found by BASEstar Open.
Return Values
| BSTR_S_ABORTED | Operation aborted |
| BSTR_S_BAD_PARAMETER | Bad parameter value |
| 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_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_NO_MEMORY | Insufficient virtual memory |
| BSTR_S_OBJECT_NOT_FOUND | Object not found |
| BSTR_S_REFERENCE_IN_USE | Reference already in use |
| BSTR_S_SERVER_NOT_REACHABLE | Server not reachable |
See Also
| bstr_context_set_default | # |
| bstr_references_are_equal | # |
| bstr_reference_copy | # |
| bstr_reference_get_info | # |
| bstr_reference_recover | # |
| bstr_reference_unset | # |