Enabling CDDL-compatible record definition semantics in VDO allows you to define records both with and without nested STRUCTURE keywords.

To enable or disable this feature in an existing VDO session, enter SET DDL or SET NODDL respectively.

You can also start VDO directly in DDL mode by using either the VDDL command or the VDO/DDL command.

When DDL mode is enabled, the prompt changes from VDO> to VDDL>.

The following examples demonstrate the available methods for entering and leaving DDL mode:

To create a new repository, you can either use the DEFINE REPOSITORY command or the legacy DEFINE DICTIONARY command. To specify where the repository should be created, supply the directory path after the command as follows:

VDO> DEFINE REPOSITORY [.VDD]

After the operation completes, you should see that the file REPOSITORY.DB has been created in the specified directory.

To show the current virtual directory where the VDO Utility operates, you can use the SHOW DEFAULT command:

VDO> SHOW DEFAULT
SYS$COMMON:[SYSTEMREPO]

When VDO is started, it tries to find the default repository file (REPOSITORY.DB) in the current working directory. If it finds the repository file, then it assumes that the current directory should be set for future use. In case of failure (when there is no REPOSITORY.DB in the current directory), VDO by default sets the current working directory to SYS$COMMON:[SYSTEMREPO]. Unlike the CDD, VDO does not maintain multiple logical names to locate dictionary files.

To set the current working directory, use the following VDO command:

VDO> SET DEFAULT DISK:[DIR]

To show which VDD records or elements are available, you can use the DIRECTORY command. The command accepts a name argument. However, if the argument is not provided, VDO lists all of the elements that are available in the current working directory:

VDO> DIRECTORY
Directory repository-root
CDD$PROTOCOLS                                     DIRECTORY
ACMS$DIR                                          DIRECTORY
MENU1(1)                                          CDD$MENU
F1(1)                                             FIELD
F1(3)                                             FIELD
F1(4)                                             FIELD
F1(5)                                             FIELD
REC1(1)                                           CDD$RECORD
REC1(2)                                           CDD$RECORD

The first line indicates the directory type. In the above example, repository-root indicates that we are currently in the root directory for the repository in question.

You can also show the contents of a specific directory as follows:

VDO> DIRECTORY ACMS$DIR.*
Directory ACMS$DIR

ACMS$WORKSPACES     DIRECTORY

To create a new directory, you can use the DEFINE DIRECTORY command. This command can be used for both DDL- and CDO-style directories:

VDO> DEFINE DIRECTORY DIR.

To delete the given directory, you can use the DELETE DIRECTORY command:

VDO> DELETE DIRECTORY DIR.

To define a new field, you can use the DEFINE FIELD command:

VDO> DEFINE FIELD FLD.
DEFINE FIELD FLD.

Note that after defining elements, VDO will print the complete element definition. The above example creates an "empty" field with no attributes. You can specify various attributes after specifying the field names. In the example below, you can see how the DATATYPE attribute is used:

VDO> DEFINE FIELD FLD DATATYPE IS WORD.
DEFINE FIELD FLD DATATYPE IS WORD.

To delete a field, you can use the DELETE FIELD command:

VDO> DELETE FIELD FLD.

You can also specify which version of a field will be deleted. In the following example, version 3 of the field F1 is deleted:

VDO> DIRECTORY
Directory repository-root
CDD$PROTOCOLS                                     DIRECTORY
ACMS$DIR                                          DIRECTORY
F1(3)                                             FIELD
F1(1)                                             FIELD
F1(4)                                             FIELD
F1(5)                                             FIELD
REC1(1)                                           CDD$RECORD
REC1(2)                                           CDD$RECORD

! DELETE A FIELD 
VDO> DELETE FIELD F1;3.
VDO> DIRECTORY
Directory repository-root
CDD$PROTOCOLS                                     DIRECTORY
ACMS$DIR                                          DIRECTORY
F1(1)                                             FIELD
F1(4)                                             FIELD
F1(5)                                             FIELD
REC1(1)                                           CDD$RECORD
REC1(2)                                           CDD$RECORD

If you do not specify any version, or leave a trailing semicolon (;) at the end of the field name, the latest version of the field will be deleted.

You can use the EXTRACT name command to print out the definition of an element, as illustrated in the following example:

VDO> EXTRACT SAMPLE$ROOT.SAMPLE$RECORD

DEFINE RECORD SAMPLE$ROOT.SAMPLE$RECORD.
   SAMPLE$PROCESSING_STATUS STRUCTURE .
      SAMPLE$L_F0 DATATYPE IS LONGWORD INITIAL_VALUE IS 1.
      SAMPLE$T_F1 DATATYPE IS TEXT SIZE IS 1 CHARACTERS INITIAL_VALUE IS "S".
      SAMPLE$T_F2 DATATYPE IS TEXT SIZE IS 1 CHARACTERS INITIAL_VALUE IS "G".

      VARIANTS.
        VARIANT.
           SAMPLE$T_V0 DATATYPE IS TEXT SIZE IS 132 CHARACTERS INITIAL_VALUE IS " ".
        END VARIANT.
        VARIANT.
           SAMPLE$T_V1 DATATYPE IS TEXT SIZE IS 80 CHARACTERS.
        END VARIANT.
     END VARIANTS.
   END STRUCTURE.
END RECORD.

As you can see, the entire definition is printed from top to bottom.

To create a new record, you can use the DEFINE RECORD command. Note that the definition should end with its respective END RECORD command:

VDO> DEFINE RECORD RCD. END RECORD.
DEFINE RECORD RCD.
END RECORD.

Records generally contain a body, which itself is a collection of fields, arrays, or other record types. You can also nest records.

When defining records in VDO, be aware of the following:

To delete a record, you can use the DELETE RECORD command:

VDO> DELETE RECORD RCD.

You can also specify which version of a record will be deleted. In the following example, version 1 of the record REC1 is deleted:

VDO> DIRECTORY
Directory repository-root
CDD$PROTOCOLS                                     DIRECTORY
ACMS$DIR                                          DIRECTORY
F1(1)                                             FIELD
F1(4)                                             FIELD
F1(5)                                             FIELD
REC1(1)                                           CDD$RECORD
REC1(2)                                           CDD$RECORD

!DELETE A RECORD 
VDO> DELETE RECORD REC1;1.
VDO> DIRECTORY
Directory repository-root
CDD$PROTOCOLS                                     DIRECTORY
ACMS$DIR                                          DIRECTORY
F1(1)                                             FIELD
F1(4)                                             FIELD
F1(5)                                             FIELD
REC1(2)                                           CDD$RECORD

You can enter the VDO HELP command to display helpful information about the VDO utility:

$ VDO
VDO> HELP

  Information available:

  Expressions           File_Area_Key         fld-properties
  Logical_Names         rec-properties        Start-up-info
  Sys-properties        User-properties       VDO_CommandProc
  VDO_Commands          VDO_Edit_Strs

Topic?

To exit the VDO utility, you can either enter the EXIT command or use the Ctrl/Z key binding:

$ VDO
VDO> EXIT
$ VDO
VDO> Ctrl/Z
$

There are multiple ways to initialize a VDD context. The legacy method is to use the SIGN_IN/OUT methods, whereas the newer method expects the user to create a context and then attach to it.

The following example shows the legacy method to initialize a VDD context:

long status;
long context;

status = vdd$sign_in(&context);
if (!(status & 1)) {
    lib$signal(status);
}
// ...

status = vdd$sign_out(&context);

The code simply initializes the context, which can then be used by the other procedures.

The following example shows how to initialize a VDD context with newer procedures:

long status;

long message_vector[20];
long nad_user_handle[2];
long context_handle[2];

ots$move5(0, NULL, 0, sizeof (message_vector), message_vector);
ots$move5(0, NULL, 0, sizeof (nad_user_handle), nad_user_handle);
ots$move5(0, NULL, 0, sizeof (context_handle), context_handle);

status = vdd$attach(message_vector, nad_user_handle, context_handle);
if (!(status & 1)) {
        sys$putmsg(message_vector);
        goto CLEANUP;
}

long session_handle[2];

ots$move5(0, NULL, 0, sizeof (session_handle), session_handle);

status = vdd$start_session(message_vector, nad_user_handle,
                        session_handle, NULL, NULL, context_handle);
if (!(status & 1)) {
        sys$putmsg(message_vector);
        goto CLEANUP;
}

// define CLEANUP somewhere

status = vdd$end_session(message_vector, session_handle, 
                        NULL, context_handle, NULL);
if (!(status & 1)) {
        sys$putmsg(message_vector);
}

status = vdd$detach(message_vector, nad_user_handle, context_handle);
if (!(status & 1)) {
        sys$putmsg(message_vector);
}

While the newer method is more verbose, it lets you control the behavior of the operations more precisely. Note that all procedures accept message_vector as an argument. This vector can be used to trace the errors. If you simply print out the message text associated with the status variable, this will only display the last error; with message_vector you have the entire error trace in one array.

On line 11, the above example first tries to attach to the VDD context. The supplied arguments are internal memory pointers that need to be passed to the procedures that perform VDD operations. The same applies to the procedure that is being used on line 21.

Sometimes, it can be useful to dump the VDD Buffer to see the errors. VDD APIs that use these buffers usually report errors when they are unable to parse the buffer. However, the error description is often not sufficient, which is why we have to rely on a debugging APIs such as the VDD$DUMP_BUFFER to obtain additional information when a problem is encountered:

// assuming you have the buffer built before calling this procedure

unsigned short buffer_length;
vdd$dump_buffer(msg_vec, &buffer_length, buffer, session);

// OUTPUT:
// 1  begin
// 13 directory_info_dsc V3.0
// 14    directory_name_list
// 56       directory_name "DISK:[REPO]CDD$PROTOCOLS"
// 57    end
// 62    type MCS_DIRECTORY
// 63 eoc

This VDD debug API call parses the binary data associated with the operation in question and prints it with VDD tokens. In the case of errors, you will find out immediately which portion is corrupted. The listed line numbers indicate the offset in that given buffer, where the names are mnemonics of VDD Tokens.

To create a directory, you can use the VDD$CREATE_DIRECTORY procedure:

// initialize the VDD Context first
// ...

const uint8_t directory_path[] = "TEST$PARENT.TEST$CHILD";

uint8_t directory_buffer[64];
uint8_t *directory_pointer;
{
    directory_pointer = directory_buffer;

    *(uint8_t*)directory_pointer = vdd$k_begin;
    directory_pointer += sizeof (uint8_t);
    *(uint32_t*)directory_pointer = vdd$k_directory_info_dsc;
    directory_pointer += sizeof (uint32_t);
    *(uint32_t*)directory_pointer = 2;
    directory_pointer += sizeof (uint32_t);
    *(uint32_t*)directory_pointer = 0;
    directory_pointer += sizeof (uint32_t);
    {
        *(uint8_t*)directory_pointer = vdd$k_directory_name_list;
        directory_pointer += sizeof (uint8_t);
        {
            *(uint8_t*)directory_pointer = vdd$k_directory_name;
            directory_pointer += sizeof (uint8_t);
            *(uint16_t*)directory_pointer = sizeof (directory_path) - 1;
            directory_pointer += sizeof (uint16_t);
            ots$move3(sizeof (directory_path) - 1, 
                    directory_path, directory_pointer);
            directory_pointer += sizeof (directory_path) - 1;
        }
        *(uint8_t*)directory_pointer = vdd$k_end;
        directory_pointer += sizeof (uint8_t);
    }
    *(uint8_t*)directory_pointer = vdd$k_eoc;
    directory_pointer += sizeof (uint8_t);
}

struct dsc$descriptor_s directory_descriptor;
directory_descriptor.dsc$w_length  = directory_pointer - directory_buffer;
directory_descriptor.dsc$a_pointer = directory_buffer;
directory_descriptor.dsc$b_class   = DSC$K_CLASS_D;
directory_descriptor.dsc$b_dtype   = DSC$K_DTYPE_T;

long status;
status = vdd$create_directory(message_vector, session_handle, 
                            &directory_descriptor);
if (!(status & 1)) {
    sys$putmsg(message_vector);
    goto CLEANUP;
}

Here we can see how a VDD Buffer gets used. We first allocate a small portion of space, then we move around the buffer using an alias pointer. Each time we set a piece of the memory to some token we move the pointer forward. Later on, we use that pointer to calculate the final length.

The expressions in the buffer usually have a header and footer (see k_begin and k_end or k_eoc tokens). Inside of these expressions, you can specify the body of the expression.

To delete a given directory, you can use the VDD$DELETE_DIRECTORY procedure:

// initialize the VDD Context first
// ...

const uint8_t directory_path[] = "TEST$PARENT.TEST$CHILD";

uint8_t directory_buffer[64];
uint8_t *directory_pointer;
{
    directory_pointer = directory_buffer;

    *(uint8_t*)directory_pointer = vdd$k_begin;
    directory_pointer += sizeof (uint8_t);
    *(uint32_t*)directory_pointer = vdd$k_directory_info_dsc;
    directory_pointer += sizeof (uint32_t);
    *(uint32_t*)directory_pointer = 2;
    directory_pointer += sizeof (uint32_t);
    *(uint32_t*)directory_pointer = 0;
    directory_pointer += sizeof (uint32_t);
    {
        *(uint8_t*)directory_pointer = vdd$k_directory_name_list;
        directory_pointer += sizeof (uint8_t);
        {
            *(uint8_t*)directory_pointer = vdd$k_directory_name;
            directory_pointer += sizeof (uint8_t);
            *(uint16_t*)directory_pointer = sizeof (directory_path) - 1;
            directory_pointer += sizeof (uint16_t);
            ots$move3(sizeof (directory_path) - 1, 
                    directory_path, directory_pointer);
            directory_pointer += sizeof (directory_path) - 1;
        }
        *(uint8_t*)directory_pointer = vdd$k_end;
        directory_pointer += sizeof (uint8_t);
    }
    *(uint8_t*)directory_pointer = vdd$k_eoc;
    directory_pointer += sizeof (uint8_t);
}

struct dsc$descriptor_s directory_descriptor;
directory_descriptor.dsc$w_length  = directory_pointer - directory_buffer;
directory_descriptor.dsc$a_pointer = directory_buffer;
directory_descriptor.dsc$b_class   = DSC$K_CLASS_D;
directory_descriptor.dsc$b_dtype   = DSC$K_DTYPE_T;

long status;
status = vdd$delete_directory(message_vector, session_handle, 
                            &directory_descriptor);
if (!(status & 1)) {
    sys$putmsg(message_vector);
    goto CLEANUP;
}

The code is similar to the previous example in terms of general structure.

To define an element, we first need to build the desired VDD Buffer and then supply it to the VDD$DEFINE_ELEMENT procedure:

const char field_path[] = "DISK:[REPO]FIELD_0";

char el_buff[512];
char *el_ptr;
{
    el_ptr = el_buff;

    *(uint8_t*)el_ptr = vdd$k_begin;
    el_ptr += sizeof (uint8_t);
    *(uint32_t*)el_ptr = vdd$k_metadata_buf_dsc;
    el_ptr += sizeof (uint32_t);
    *(uint32_t*)el_ptr = 2;
    el_ptr += sizeof (uint32_t);
    *(uint32_t*)el_ptr = 0;
    el_ptr += sizeof (uint32_t);
    {
        *(uint8_t*)el_ptr = vdd$k_entity;
        el_ptr += sizeof (uint8_t);
        *(uint32_t*)el_ptr = vdd$k_ent_data_element;
        el_ptr += sizeof (uint32_t);
        *(uint32_t*)el_ptr = 1;
        el_ptr += sizeof (uint32_t);
        *(uint32_t*)el_ptr = 0;
        el_ptr += sizeof (uint32_t);
    }
    {
        *(uint8_t*)el_ptr = vdd$k_begin;
        el_ptr += sizeof (uint8_t);
        *(uint32_t*)el_ptr = vdd$k_directory_info_dsc;
        el_ptr += sizeof (uint32_t);
        *(uint32_t*)el_ptr = 2;
        el_ptr += sizeof (uint32_t);
        *(uint32_t*)el_ptr = 0;
        el_ptr += sizeof (uint32_t);
        {
            *(uint8_t*)el_ptr = vdd$k_directory_name_list;
            el_ptr += sizeof (uint8_t);
            {
                *(uint8_t*)el_ptr = vdd$k_directory_name;
                el_ptr += sizeof (uint8_t);
                *(uint16_t*)el_ptr = sizeof (field_path) - 1;
                el_ptr += sizeof (uint16_t);
                ots$move3(sizeof (field_path) - 1, field_path, el_ptr);
                el_ptr += sizeof (field_path) - 1;
            }
            *(uint8_t*)el_ptr = vdd$k_end;
            el_ptr += sizeof (uint8_t);
        }
        {
            *(uint8_t*)el_ptr = vdd$k_type;
            el_ptr += sizeof (uint8_t);
            *(uint32_t*)el_ptr = vdd$k_ent_element;
            el_ptr += sizeof (uint32_t);
        }
        *(uint8_t*)el_ptr = vdd$k_eoc;
        el_ptr += sizeof (uint8_t);
    }
    {
        *(uint8_t*)el_ptr = vdd$k_attribute_list;
        el_ptr += sizeof (uint8_t);
        {
            *(uint8_t*)el_ptr = vdd$k_attribute;
            el_ptr += sizeof (uint8_t);

            *(uint32_t*)el_ptr = vdd$k_att_processing_name;
            el_ptr += sizeof (uint32_t);
            *(uint8_t*)el_ptr = vdd$k_literal;
            el_ptr += sizeof (uint8_t);
            *(uint8_t*)el_ptr = DSC$K_DTYPE_T;
            el_ptr += sizeof (uint8_t);
            *(uint16_t*)el_ptr = sizeof (field_path) - 1;
            el_ptr += sizeof (uint16_t);
            ots$move3(sizeof (field_path) - 1, field_path, el_ptr);
            el_ptr += sizeof (field_path) - 1;
        }
        *(uint8_t*)el_ptr = vdd$k_end;
        el_ptr += sizeof (uint8_t);
    } 
    *(uint8_t*)el_ptr = vdd$k_end;
    el_ptr += sizeof (uint8_t);
    *(uint8_t*)el_ptr = vdd$k_eoc;
    el_ptr += sizeof (uint8_t);
}
unsigned short el_diff;
el_diff = el_ptr - el_buff;

struct dsc$descriptor_s el_desc;
el_desc.dsc$a_pointer  = el_buff;
el_desc.dsc$w_length   = el_diff;
el_desc.dsc$b_class    = DSC$K_CLASS_D;
el_desc.dsc$b_dtype    = DSC$K_DTYPE_T;

long element_handle[2];
ots$move5(0, NULL, 0, sizeof (element_handle), element_handle);

long status;
status = vdd$define_element(msg_vec, session, 
                            &el_desc, element_handle);
if (!(status & 1)) {
    lib$signal(status);
        return 1;
}

This example uses the metadata_buf_dsc token to include the element definition in it. First, we specify that our element is a field by using the ent_data_element token, and then we specify the path by using the directory_info_dsc token.

Having these two required descriptions, we can then start specifying the attributes of the element. We do this using the attribute_list token, which contains all of the attributes that should describe our new element. Here, we only specify one attribute, which is its name. We do this by embedding the att_processing_name into our buffer.

To specify values in the buffer, we often need to use the literal token. With this token we can precisely describe what type of value we want to have. In our case, we use a static character array, which is why we chose the default VMS DSC$K_DTYPE_T enum here. Once the buffer is complete, we can supply it to the procedure, which can be seen on line 97.

This procedure can be used to define all types of elements. You can define records, generic types such as the ACMS Task, or DATATRIEVE Objects. However, note that we cannot define a directory with this API call. This seeming inconsistency derives from equivalent CDD interface, which does not support such functionality.

Before using ACMS with VDD, ensure that the following requirements have been met:

When using ACMS with VDD, be aware of the following considerations:

Before running the Datatrieve test with VDD, make sure of the following:

To set up the required environment for the Datatrieve test, run the NEWUSER.COM executable by entering the following command:

$ @DTR$LIBRARY:NEWUSER

You should see output similar to the following:

        NEWUSER creates the environment to help new users to get started
        with DATATRIEVE. It gives you the necessary files to perform
        the introductory examples in the DATATRIEVE documentation.

        This procedure will copy the DATATRIEVE data files from
        DTR$LIBRARY to your directory and will create the DATATRIEVE
        objects into your dictionary.

        You now have the following options:

        1.      Copy the DATATRIEVE data files to your directory and
                create the DATATRIEVE objects into your dictionary.

        2.      Copy only the DATATRIEVE data files to your directory.

        3.      Create only the DATATRIEVE objects into your dictionary.

        E.      None of the above and EXIT.

        Select option: 1

    Your default directory is [USER.EXAMPLE]

        Do you want to copy the DATATRIEVE data files there ? (Y/N) Y

    Your default Dictionary directory is SYS$COMMON:[SYSTEMREPO]

        Do you want to define the DATATRIEVE objects there ? (Y/N) Y

    NEWUSER is working... It will take a few minutes.


VSI DATATRIEVE V7.4-4
Digital Query and Report System
Type HELP for help

[Record is 104 bytes long.]
[Record is 382 bytes long.]
[Record is 56 bytes long.]
[Record is 57 bytes long.]
[Record is 18 bytes long.]
[Record is 35 bytes long.]
[Record is 624 bytes long.]
[Record is 41 bytes long.]
[Record is 47 bytes long.]
[Record is 142 bytes long.]



        The following command has been defined for you, but you will need
        to add it to your LOGIN.COM file for the next time you log in:


        DEFINE/PROCESS VDD$DEFAULT SYS$COMMON:[SYSTEMREPO]


    All data copied successfully.

    If you need help, see the person responsible for DATATRIEVE on your system.

    To invoke DATATRIEVE just type:     DATATRIEVE

Complete the following test to ensure that Datatrieve is working correctly:

$ DATATRIEVE
VSI DATATRIEVE V7.4-4
Digital Query and Report System
Type HELP for help
DTR> PRINT "TODAY" USING DD-MMM-YYYYBBW(9)
5-Oct-2025  Sunday

DTR> SHOW YACHT
RECORD YACHT USING
01 BOAT.
  03 TYPE.
     06 MANUFACTURER PIC X(10)
        QUERY_NAME IS BUILDER.
     06 MODEL PIC X(10).
  03 SPECIFICATIONS
     QUERY_NAME SPECS.
     06 RIG PIC X(6)
        VALID IF RIG CONT "SLOOP","KETCH","MS","YAWL".
     06 LENGTH_OVER_ALL PIC XXX
        VALID IF LOA BETWEEN 15 AND 50
        QUERY_NAME IS LOA.
     06 DISPLACEMENT PIC 99999
        QUERY_HEADER IS "WEIGHT"
        EDIT_STRING IS ZZ,ZZ9
        QUERY_NAME IS DISP.
     06 BEAM PIC 99 MISSING VALUE IS 0.
     06 PRICE PIC 99999
        MISSING VALUE IS 0
        VALID IF PRICE>DISP*1.3 OR PRICE EQ 0
        EDIT_STRING IS $$$,$$$.
;
DTR> READY YACHTS
DTR> PRINT AVERAGE PRICE OF YACHTS

AVERAGE
PRICE

[Function computed using 50 of 113 values.]
$25,389

DTR>