s_mysql_component_sys_variable_register Struct Reference

Service to register variable and get variable value. More...

#include <component_sys_var_service.h>

Public Attributes
mysql_service_status_t(*	register_variable )(const char *component_name, const char *name, int flags, const char *comment, mysql_sys_var_check_func check, mysql_sys_var_update_func update, void *check_arg, void *variable_value)
	Register a new system variable. More...
mysql_service_status_t(*	get_variable )(const char *component_name, const char *name, void **val, size_t *out_length_of_val)
	Fetches the global value of a system variable. More...

Detailed Description

Service to register variable and get variable value.

See also

mysql_component_sys_variable_imp

Member Data Documentation

get_variable

mysql_service_status_t(* s_mysql_component_sys_variable_register::get_variable) (const char *component_name, const char *name, void **val, size_t *out_length_of_val)

Fetches the global value of a system variable.

Call this to get the global value of a variable. You can access both the component variables (SELECT @global.component_name.variable_name) and the "legacy" system variables (SELECT @global.variable_name) that are registered by the server component. To access the latter you need to pass "mysql_server" (lowercase) as a component name.

A pointer to the value is returned into the val input/output argument. And the length of the value (as applicable) is returned into the out_length_of_val argument.

In case when the user buffer was too small to copy the value, the call fails and needed buffer size is returned by 'out_length_of_val'.

Typical use (char * variable):

char *value, buffer_for_value[160];
size_t value_length;
 
value= &buffer_for_value[0];
value_length= sizeof(buffer_for_value) - 1;
get_variable("foo", "bar", &value, &value_length);
 
printf("%.*s", (int) value_length, value);

Parameters

	component_name	Name of the component or "mysql_server" for the legacy ones.
	name	name of the variable
[in,out]	val	On input: a buffer to hold the value. On output a pointer to the value.
[in,out]	out_length_of_val	On input: the buffer size. On output the length of the data copied.

Return values

true	failure
false	success

register_variable

mysql_service_status_t(* s_mysql_component_sys_variable_register::register_variable) (const char *component_name, const char *name, int flags, const char *comment, mysql_sys_var_check_func check, mysql_sys_var_update_func update, void *check_arg, void *variable_value)

Register a new system variable.

The variable registered is then accessible in SQL as "SELECT component_name.name" The variable registration needs a global of the relevant type that stores the value.

To define a new variable you need to:

1. Decide on a variable type among one of the Variable types
2. Decide on attributes of the type among one of the Variable flags
3. Declare a local variable placeholder matching the type using one of the Variable macros.
4. Fill in the placeholder values (min, max, default etc) as appropriate for the selected type.
5. Provide storage for the variable value: usually a global variable of the relevant type.
6. Call the function with all of the above to register the system variable.

Warning

: Make sure to unregister the system variable when you no longer intend to have it or when your component deinitializes. Failure to do so will lead to resource leaks and crashes.

Typical use

static int int_variable_value;
static char *str_variable_value;
static ulong enum_variable_value;
 
static const char *enums[] = {"LOW", "MEDIUM", "STRONG", NullS};
 
static TYPE_LIB enums_typelib_t = {array_elements(enums) - 1,
  "enums_typelib_t",
  enums, NULL};
 
...
 
INTEGRAL_CHECK_ARG(int) int_arg;
int_arg.def_val = 8;
int_arg.min_val = 0;
int_arg.max_val = 1024;
int_arg.blk_sz = 0;
if (mysql_service_component_sys_variable_register->register_variable(
  "foo", "int_sys_var", PLUGIN_VAR_INT,
  "Registering int sys_variable", NULL, NULL, (void *)&int_arg,
  (void *)&int_variable_value)) {
  deal_with_error();
}
 
STR_CHECK_ARG(str) str_arg;
str_arg.def_val = NULL;
if (mysql_service_component_sys_variable_register->register_variable(
  "foo", "str_sys_var", PLUGIN_VAR_STR | PLUGIN_VAR_MEMALLOC,
  "Registering string sys_variable", NULL, NULL, (void *)&str_arg,
(void *)&str_variable_value)) {
  deal_with_error();
}
 
ENUM_CHECK_ARG(enum) enum_arg;
enum_arg.def_val = 1; //  medium
enum_arg.typelib = &enum_typelib_t;
if (mysql_service_component_sys_variable_register->register_variable(
"foo", "enum_sys_var", PLUGIN_VAR_ENUM,
"Registering enum sys_variable", NULL, NULL, (void *)&enum_arg,
(void *)&enum_variable_value)) {
  deal_with_error();
}

See also

mysql_service_component_sys_variable_unregister_t

Parameters

component_name	The name of the component the system variable belongs to.
name	The name of the variable.
flags	one of Variable types plus zero or more of group_components_services_sys_var_service_flags
comment	explanation of what the variable is to be shown in metadata tables
check	A function to be called to check for validity of the new value.
update	A function to be called when the variable value is updated
check_arg	The variable declared through one of Variable
variable_value	A pointer to a storage location of the relevant type.

Return values

true	operation failed
false	operation succeeded

---

The documentation for this struct was generated from the following file:

• include/mysql/components/services/component_sys_var_service.h