# 9.21. ODPI-C Subscription Functions

Subscription handles are used to represent subscriptions to events such as continuous query notification and object change notification. They are created by calling the function `dpiConn_subscribe()` and are destroyed by calling the function `dpiConn_unsubscribe()` or releasing the last reference by calling the function `dpiSubscr_release()`.

int dpiSubscr_addRef(dpiSubscr *subscr)

  Adds a reference to the subscription. This is intended for situations where a reference to the subscription needs to be maintained independently of the reference returned when the subscription was created.

  The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

  Parameter | Mode | Description
  --- | --- | ---
  `subscr` | IN | The subscription to which a reference is to be added. If the reference is NULL or invalid, an error is returned.

int dpiSubscr_prepareStmt(dpiSubscr *subscr, const char *sql, uint32_t sqlLength, dpiStmt **stmt)

  Prepares a statement for registration on the subscription. The statement is then registered by calling the function `dpiStmt_execute()`. The reference to the statement that is returned should be released as soon as it is no longer needed.

  The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

  Parameter | Mode | Description
  --- | --- | ---
  `subscr` | IN | A reference to the subscription on which the statement is to be prepared for registration. If the reference is NULL or invalid, an error is returned.
  `sql` | IN | The SQL that is to be prepared, as a byte string in the encoding used for CHAR data.
  `sqlLength` | IN | The length of the sql parameter, in bytes.
  `stmt` | OUT | A reference to the statement that was prepared, which will be populated when the function completes successfully.

int dpiSubscr_release(dpiSubscr *subscr)

  Releases a reference to the subscription. A count of the references to the subscription is maintained and when this count reaches zero, the memory associated with the subscription is freed. The subscription is also deregistered so that notifications are no longer sent, if this was not already done using the function `dpiConn_unsubscribe()`.

  The function returns DPI_SUCCESS for success and DPI_FAILURE for failure.

  Parameter | Mode | Description
  --- | --- | ---
  `subscr` | IN | The subscription from which a reference is to be released. If the reference is NULL or invalid, an error is returned.