Introduction

JBSO is a Csound framework for a kind of object oriented design. Csound itself does not offer object oriented mechanisms to implement types with memeber variables and methods. This framework still requires a developer to "manually" implement a systematic interface, but takes care of some global management in the background and offers further macros and utility opcodes to aid in a systematic standard.

Types or classes created with JBSO automatically manage type specific and global object counters, some validity checks and a global name to ID mapping system, which can be used for object lookup. Furthermore versioining of type APIs is enforced.

JBSO Version 1.1 offers a few macros to standardise status codes, like errors, warnings, information and success, as well as opcodes to handle retrieval and management of errors.

JBSO already provides a few features specifically intended for object data storage, but does not supply opcoodes to manage these, yet. Aside from a global storage format header, there is support for versioning, numerical type IDs and a provision for a types storage size.

[Back to top]

Changes and updates

Changes from version 1.0

Fixed a bug pertaining to .Size property. Updated all opcodes to use the new status codes (see macros and constants.

New opcdes: mjbsoc_get_status, m_jbsoc_move_status, m_jbsoc_set_status, m_jbsoc_get_status_string, m_jbsoc_move_status_string and m_jbsoc_set_status_string

[Back to top]

Basic concepts and ideas

The JBSO framework is implemented first as a set of User Defined Opcodes (UDOs). There are two families of opcodes:

m_jbso_* - these are directly related to the JBSO system
m_jbsoc_* - these related to general class/type and object operations, such as version inquiry, object count of a particular type and helpers to create and destroy objects

Internally JBSO relies on Csound channels and ftables to store and pass around data. Channel names follow a fixed system. There are namespaces. Namespaces are sperated by dots ".". Each valid JBSO channel name begins with "JBSO.".

Special subspaces

Both directly under JBSO and underneath the classname there is a special namespace "Global", which means that no class/type and no object can be called Global. In the global namespaces there are properties almost exclusively managed and used by the JBSO system. These include version numbers, object counters, object IDs and lookup tables. JBSO offer opcodes to deal with these properties and query them.

Object creation and destruction

To create a JBSO type you should call m_jbsoc_new as the first call in your creation opcode. This will attempt to set up basics for your object, like its validity, object ID, error status and error message (0 and empty respectively) and name lookup, as well as increase object counters. If this operation fails, m_jbsoc_new will return a status other than 1.

to destroy an object of your type, you should call m_jbsoc_delete as the last call in your destruction opcode, this will deinitialise the same properties and decrease the object counters. This opcode also return 1 upon success, which allows you to print a further error message or otherwise try to handle problems.

Your object properties

As mentioned above, JBSO relies on Csound channels and ftables to store data. Channels are used to store single values, audio and character strings. ftables are used to store large collections of data, like arrays of values. To properly reference an ftable across multiple instruments, its table number should also be stored in a channel.

Channel names are hirarchical, so all properties of one object live under the names: JBSO._CLASSNAME_._OBJECTNAME_.* where _CLASSNAME_ is the name of the object's type or class and _OBJECTNAME_ is the name of the object itself.

Storage on disk a.k.a. serialisation

Some elements have been put into place for a systematic serialisation process. The channelname JBSO.Global.Header1 to JBSO.Global.Header4 hold four arbirary values that should be written to the first four elements of a stored object. This should be followed by the class/type ID, the major and minor version number of the type and the storage size. Each class should provide its storage size in JBSO._CLASSNAME_.Global.Size, if appropriate.

Opcode naming

There is nothing to enforce any system of naming opcodes, but it is helpful to choose a naming convention that includes the name of the class/type to avoid conflicts with builtin Csound opcodes or other UDOs.

JBSO itself - for example - prefixes any UDO name with m_jbso_ or m_jbsoc_. Further, whereever possible, it adopts the convention of get_* and set_* to query and change values. is_* and has_* are good contenders to query boolean values or states. There are a few conventions described in general purpose programming literature. For a clean approach it is highly useful to find one system and adhere to it! Especially when, like in this case, the environment or toolkit still leaves a lot of organisation and "encapsulation" to the developer.

[Back to top]

Macros and constants

There are several families of macros defined in JBSO. Below are organised lists. It may be helpful to reuse these macros in your own code to improve readability and robustness.

JBSO information

JBSO_VER_MAJOR - Major version number of JBSO
JBSO_VER_MINOR - Minor version number of JBSO

Status and error codes

JBSO_STAT_OK - Success or validity
JBSO_STAT_WARN - A warning. After this the program may continue, but if you see it you should probably do something about it.
JBS_STAT_ERR - Error. Handling or exiting is required.
JBSO_STAT_INFO - Noteworthy information, print the object's error message

[Back to top]

JBSO system opcodes

As noted in the basic concepts and ideas there are two families of opcodes, making up this framework, those related to the system itself and those related to types and objects within it. This section lists the UDOs that purely address the framework.

m_jbso_init - Initialise the JBSO system
m_jbso_is_valid - Check if the JBSO system has been initialised
m_jbso_get_version - Return major and minor version number of the JBSO system
m_jbso_get_count - Return the count of all JBSO objects in existence
m_jbso_is_class - Check if the given name references an existing class
m_jbso_class_version - Return the version of the named class/type

[Back to top]

Class and object related opcodes

The UDOs below are class or object related, in the case of m_jbsoc_new and m_jbsoc_delete they should be used by the developer of a JBSO class/type directly, as described in the basic concepts and ideas.

m_jbsoc_new - Help create a JBSO object
m_jbsoc_delete - Help delete/destroy a JBSO object
m_jbsoc_is_object - Check whether the given name references an object of the given class
m_jbsoc_get_count - Return the number of objects of the given class currently in existence
m_jbsoc_get_id - Get the numeric ID associated to an object name
m_jbsoc_get_size - Return the storage size of the given object
m_jbsoc_get_status - Return the object's status code
m_jbsoc_move_status - Return the object's status code and reset it
m_jbsoc_set_status - Set the object's status code
m_jbsoc_get_status_string - Return the object's status message
m_jbsoc_move_status_string - Return the object status message and reset it
m_jbsoc_set_status_string - Set the object's status message

[Back to top]

List of opcodes

m_jbso_init

DESCRIPTION

Initialise the JBSO object system, i.e. set up a few global channels for management.

SYNTAX

m_jbso_init

INITIALIZATION

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbso_is_valid

DESCRIPTION

Return 1 if the JBSO system is already setup, 0 otherwise.

SYNTAX

kValid m_jbso_is_valid

INITIALIZATION

PERFORMANCE

kValid - 1 if the JBSO object system is set up, 0 otherwise

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbso_get_version

DESCRIPTION

Return the major and minor version numbers of the JBSO class system itself.

SYNTAX

iMajor, iMinor m_jbso_get_version

INITIALIZATION

iMajor - Major version number of JBSO, -1 if JBSO isn't running
iMinor - Minor version number of JBSO, -1, if JBSO isn't running

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbso_get_count

DESCRIPTION

Return the number of all JBSO object in existence. All objects should take care of the global counter.

SYNTAX

kNumberOfObject m_jbso_get_count

INITIALIZATION

PERFORMANCE

kNumberOfObjects - Number of all JBSO currently in existence

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbso_is_class

DESCRIPTION

Check whether the supplied name denotes an existing JBSO class. This will only work once the class has been setup.

SYNTAX

kValid m_jbso_is_class SclassName

INITIALIZATION

PERFORMANCE

kValid - 1 if the name denotes an existing class, 0 otherwise
SclassName - Potential name of a JBSO class

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbso_class_version

DESCRIPTION

Return the version of JBSO class API. For this to work, the class must be initialised.

SYNTAX

iMajor, iMinor m_jbso_class_version SclassName

INITIALIZATION

iMajor - Major version number or -1 if the class doesn't exist
iMinor - Minor version number or -1, if the class doesn't exist
SclassName - Name denoting a JBSO class

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of system opcodes]

m_jbsoc_new

DESCRIPTION

This is a utility opcode meant only to be used in higher level UDOs to create JBSO objects. It is highly recommended to use it in tandem with m_jbsoc_delete .

SYNTAX

iSuccess m_jbsoc_new SclassName, Sname, iVersionMajor, iVersionMinor

INITIALIZATION

iSuccess - 1 on successful setup, !=1 otherwise
SclassName - Name of the object's class
Sname - Name of the object to set up
iVersionMajor, iVersionMinor - Major and minor version number of the type

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_delete

DESCRIPTION

The final operations to be performed when destroying a JBSO object.

SYNTAX

iSuccess m_jbsoc_delete SclassName, Sname

INITIALIZATION

iSuccess - 1 upon success, != otherwise
SclassName - Name of the class the object belongs to
Sname - Name of the object to delete

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_is_object

DESCRIPTION

Check whether the supplied name refers to an object of the given class.

SYNTAX

kValid m_jbsoc_is_object SclassName, Sname

INITIALIZATION

PERFORMANCE

kValid - 1 if this is an object of the given class, 0 otherwise
SclassName - Name of the class in question
Sname - Name of the object to check

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_get_count

DESCRIPTION

Return the number of existing objects of the given class, or $JBSO_STAT_ERR otherwise.

SYNTAX

kNumberOfObjects m_jbsoc_get_count SclassName

INITIALIZATION

PERFORMANCE

kNumberOfObjects - The number of currently existing objects or $JBSO_STAT_ERR on error
SclassName - Name of the class to count objects from

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_get_id

DESCRIPTION

Return the numerical ID of a JBSO object. This ID is used for management purposes.

SYNTAX

iID m_jbsoc_get_id SclassName, Sname

INITIALIZATION

iId - The object's ID or $JBSO_STAT_ERR on error
SclassName - Name of the object's class
Sname - Name of the object

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_get_size

DESCRIPTION

Return the storage size for objects of the given class/type or $JBSO_STAT_ERR on error.

SYNTAX

kSize m_jbsoc_get_size SclassName

INITIALIZATION

PERFORMANCE

kSize - Storage size of the class/type or $JBSO_STAT_ERR on error. 0 is a valid storage size, for objects that can't be saved to disk or have no data to save yet.
SclassName - Name of the class to check for storage size

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_get_status

DESCRIPTION

Retrieve the status code from the specified object.

SYNTAX

iStatus m_jbsoc_get_status SclassName, Sname

INITIALIZATION

iStatus - Status code from the given object
SclassName - Name of the class/type of the object
Sname - Name of the object

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_move_status

DESCRIPTION

Retrieve the status code from the specified object and reset the code to $JBSO_STAT_OK, only if the previous code was _NOT_ $JBSO_STAT_ERR .

SYNTAX

iStatus m_jbsoc_move_status SclassName, Sname

INITIALIZATION

iStatus - Status code from the given object
SclassName - Name of the class/type of the object
Sname - Name of the object

PERFORMANCE

CREDITS

Author: Jeanette C.

[Back to top] [Back to list of object opcodes]

m_jbsoc_set_status

DESCRIPTION

Set an object's status.

SYNTAX

kResult m_jbsoc_set_status SclassName, Sname, kStatus

INITIALIZATION

PERFORMANCE

kResult - $JBSO_STAT_OK on success, $JBSO_STAT_ERR when the object does not exist
SclassName - Name of the object's type
Sname - Name of the object
kStatus - Status to set (suggested values are the JBSO_STAT_* constants)