Приложения

Приложение А. Функции, константы и структуры RDS

А.5. Сервисные функции и макросы RDS

А.5.25. Вспомогательный объект для изменения структуры переменных блока

А.5.25.4. rdsVSAddVar – добавить переменную

Функция rdsVSAddVar добавляет переменную в объект-редактор.

  int RDSCALL rdsVSAddVarA(
    RDS_HOBJECT Vars,    // Редактор переменных
    int Index,           // Номер переменной или -1
    RDSCSTR VarName,     // Имя переменной (UTF8)
    char BaseVarType,    // Тип переменной
    RDSCSTR StructType,  // Имя типа структуры (UTF8)
    DWORD Flags,         // Флаги переменной (RDS_VARFLAG_*)
    int ArrayDepth,      // Вложенность матрицы
    RDSCSTR DefVal       // Значение по умолчанию (UTF8)
  );
  int RDSCALL rdsVSAddVarW(
    RDS_HOBJECT Vars,    // Редактор переменных
    int Index,           // Номер переменной или -1
    RDSWCSTR VarName,    // Имя переменной (UTF16)
    char BaseVarType,    // Тип переменной
    RDSWCSTR StructType, // Имя типа структуры (UTF16)
    DWORD Flags,         // Флаги переменной (RDS_VARFLAG_*)
    int ArrayDepth,      // Вложенность матрицы
    RDSWCSTR DefVal      // Значение по умолчанию (UTF16)
  );
  // Функция-псевдоним
  int RDSCALL rdsVSAddVar(
    RDS_HOBJECT Vars,    // Редактор переменных
    int Index,           // Номер переменной или -1
    RDSXCSTR VarName,    // Имя переменной (кодировка по умолчанию)
    char BaseVarType,    // Тип переменной
    RDSXCSTR StructType, // Имя типа структуры (кодировка по умолчанию)
    DWORD Flags,         // Флаги переменной (RDS_VARFLAG_*)
    int ArrayDepth,      // Вложенность матрицы
    RDSXCSTR DefVal      // Значение по умолчанию (кодировка по умолчанию)
  );

Тип указателя на эту функцию

RDS_IHoISCSDwIS (для UTF8) или RDS_IHoIWsCWsDwIWs (для UTF16)

Параметры

Vars (RDS_HOBJECT)

Идентификатор вспомогательного объекта-редактора переменных, ранее созданного функцией rdsVSCreateEditor.

Index (int)

Начинающийся с нуля номер, который будет иметь эта переменная (уже существующие в наборе переменные начиная с этого номера сдвинутся на одну позицию вниз), или −1 для добавления переменной в конец списка.

VarName (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку с именем переменной.

BaseVarType (char)

Тип переменной – одна из констант RDS_VARTYPE_* кроме RDS_VARTYPE_STRUCTEND (это служебная константа, не тип переменной) и RDS_VARTYPE_ARRAY (массивы задаются другим способом). Если нужно указать в качестве типа структуру, в BaseVarType передается RDS_VARTYPE_STRUCT, а в параметре StructType – имя типа структуры, под которым она зарегистрирована в RDS. Если нужно указать в качестве типа матрицу, в BaseVarType передается тип элемента матрицы, а в параметре ArrayDepth – вложенность (1 для матрицы, 2 для матрицы матриц и т.д., см. ниже).

StructType (RDSCSTR, RDSWCSTR, RDSXCSTR)

Имя типа структуры, если в параметре BaseVarType передана константа RDS_VARTYPE_STRUCT.

Flags (DWORD)

Набор битовых флагов переменной (аналогично полю Flags структуры описания переменной RDS_VARDESCRIPTION). Кроме стандартных флагов, можно также указать специальный битовый флаг RDS_VARFLAG_EXT_CHGNAME, разрешающий автоматически изменить имя добавляемой переменной, если переменная с таким именем уже есть в наборе. Если переменная с именем VarName уже есть, и флаг RDS_VARFLAG_EXT_CHGNAME не указан в параметре Flags, новая переменная добавлена не будет и функция вернет –1.

ArrayDepth (int)

Вложенность матрицы переменной: 0 – простая переменная типа BaseVarType, 1 – матрица типа BaseVarType, 2 – матрица матриц BaseVarType и т.п.

DefVal (RDSCSTR, RDSWCSTR, RDSXCSTR)

Указатель на строку значения переменной по умолчанию (аналогично функции rdsSetBlockVarDefValueStr).

Возвращаемое значение

Номер добавленной переменной или −1 в случае ошибки.

Примечания

Эта функция добавляет в набор переменных объекта-редактора Vars новую переменную с именем VarName в позицию Index. Тип переменной задается сочетанием параметров BaseVarType, StructType и ArrayDepth. Параметр BaseVarType задает базовый тип элемента (тип самой переменной или тип элемента матрицы), в параметре StructType передается имя типа структуры, если базовый тип – структура, а в параметре ArrayDepth – вложенность матриц (0 – простая переменная). Например:

Пример

Пример использования функции rdsVSAddVar приведен в §2.16.1 руководства программиста.

См. также

rdsVSCreateEditor, rdsVSAddVarByTypeText, rdsVSAddVarByDescr, rdsVSCreateByDescr, rdsSetBlockVarDefValueStr, типы переменных, RDS_VARDESCRIPTION.