User data

The CS_USERDATA property defines user-allocated data. This property allows an application to associate user data with a particular connection or command structure.

There is no default value for CS_USERDATA. If an application retrieves the property when no value is set, then ct_con_props or ct_cmd_props returns with outlen set to 0.

CS_USERDATA is useful when a callback routine and the main-line application need to share information without using global variables.

When an application stores data with CS_USERDATA, Client-Library copies the actual data pointed to by the buffer parameter of ct_con_props or ct_cmd_props; not a pointer to the data, into internal data space.

CS_USERDATA takes as its value any piece of application-defined data. When setting the property, the application passes a pointer to the data (cast to CS_VOID *) and specifies the exact length of the data in bytes. Most applications actually install the address of an application-allocated data structure as CS_USERDATA. This allows the application to retrieve, as CS_USERDATA, a pointer to the data. The application changes the data through the pointer, and does not need to reinstall the data in the context, connection, or command structure after changing it.

To associate user data with a context structure, an application calls cs_config. CS_USERDATA property values are not inherited at the connection or command levels.

The following code fragment demonstrates the CS_USERDATA property:

          CS_CHAR         set_charbuf[32];

           CS_CHAR         get_charbuf[32];

           CS_CONNECTION   *con;

           CS_RETCODE      ret;

           CS_INT          outlen;

           CS_COMMAND      *set_cmd;

           CS_COMMAND      *get_cmd;

         /*

           ** Store a character string in the userdata field. 

           ** Set the length field to one greater than the length 

           ** of the string so that the null terminator will be 

           ** stored as part of the user data. If the null 

           ** terminator is not explicitly stored as part of the 

           ** userdata, then the string will not be null-

           ** terminated when it is retrieved.

           */

           strcpy(set_charbuf, "some userdata");

           ret = ct_con_props(con, CS_SET, CS_USERDATA, 

                set_charbuf, strlen(set_charbuf) + 1, NULL);

           if (ret != CS_SUCCEED)

           {

                error("ct_con_props() failed");

           }

         ret = ct_con_props(con, CS_GET, CS_USERDATA, 

                get_charbuf, sizeof(get_charbuf), &outlen);

           if (ret != CS_SUCCEED)

           {

                error("ct_con_props() failed");

           }

         /*

           ** The next example stores a pointer to a CS_COMMAND 

           ** structure in the connection’s user data field.

           */

           ret = ct_con_props(con, CS_SET, CS_USERDATA, 

                &set_cmd, sizeof(set_cmd), NULL);

           if (ret != CS_SUCCEED)

           {

                error("ct_con_props() failed");

           }

         ret = ct_con_props(con, CS_GET, CS_USERDATA, 

                &get_cmd, sizeof(get_cmd), &outlen);

           if (ret != CS_SUCCEED)

           {

                error("ct_con_props() failed");

           }