Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## Chapter 6
Convert (CONVERT) Routines

This chapter describes the CONVERT routines. These routines perform the functions of both the Convert and Convert/Reclaim utilities.

## 6.1 Introduction to CONVERT Routines

The Convert utility copies records from one or more files to an output file, changing the record format and file organization to that of the output file. You can invoke the functions of the Convert utility from within a program by calling the following series of three routines, in this order:

1. CONV$PASS_FILES
2. CONV$PASS_OPTIONS
3. CONV$CONVERT

Note that the application program should declare referenced constants and return status symbols as external symbols; these symbols are resolved upon linking with the utility shareable image. Also note that File Definition Language (FDL) errors may be returned to the calling program where applicable.

The Convert/Reclaim utility reclaims empty buckets in Prolog 3 indexed files so new records can be written in them. You can invoke the functions of the Convert/Reclaim utility from within a program by calling the CONV$RECLAIM routine.

These routines cannot be called from the asynchronous system trap (AST) level. In addition, in order to function properly, these routines require ASTs to remain enabled.

## 6.2 Using the CONVERT Routines: Examples

Example 6-1 shows how to use the CONVERT routines in a Fortran program.

Example 6-1 Using the CONVERT Routines in a Fortran Program

    *            This program calls the routines that perform the
    *            functions of the Convert Utility.  It creates an
    *            indexed output file named CUSTDATA.DAT from the
    *            specifications in an FDL file named INDEXED.FDL.
    *            The program then loads CUSTDATA.DAT with records
    *            from the sequential file SEQ.DAT.  No exception
    *            file is created.  This program also returns the
    *            "BRIEF" CONVERT statistics.

    *            Program declarations

            IMPLICIT        INTEGER*4 (A - Z)

    *            Set up parameter list: number of options, CREATE,
    *            NOSHARE, FAST_LOAD, MERGE, APPEND, SORT, WORK_FILES,
    *            KEY=0, NOPAD, PAD CHARACTER, NOTRUNCATE,
    *            NOEXIT, NOFIXED_CONTROL, FILL_BUCKETS, NOREAD_CHECK,
    *            NOWRITE_CHECK, FDL, and NOEXCEPTION.
    *
            INTEGER*4       OPTIONS(19)
            1  /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/

    *            Set up statistics list.  Pass an array with the
    *            number of statistics that you want.  There are four
    *            --- number of files, number of records, exception
    *            records, and good records, in that order.

            INTEGER*4       STATSBLK(5) /4,0,0,0,0/

    *            Declare the file names.

            CHARACTER       IN_FILE*7 /'SEQ.DAT'/,
            1               OUT_FILE*12 /'CUSTDATA.DAT'/,
            1               FDL_FILE*11 /'INDEXED.FDL'/

    *            Call the routines in their required order.

            STATUS = CONV$PASS_FILES (IN_FILE, OUT_FILE, FDL_FILE)
            IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

            STATUS = CONV$PASS_OPTIONS (OPTIONS)
            IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

            STATUS = CONV$CONVERT (STATSBLK)
            IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

    *            Display the statistics information.

            WRITE (6,1000) (STATSBLK(I),I=2,5)
    1000    FORMAT (1X,'Number of files processed: ',I5/,
            1       1X,'Number of records: ',I5/,
            1       1X,'Number of exception records: ',I5/,
            1       1X,'Number of valid records: ',I5)

            END

Example 6-2 shows how to use the advanced features of the CONVERT routines in a C program.

Example 6-2 Using the CONVERT Routines in a C Program

    /*
    **  This module calls the routines that perform the functions
    **  of the Convert utility.  It creates an indexed output file
    **  named CUSTDATA.DAT from the specifications in an FDL file
    **  named INDEXED.FDL, and loads CUSTDATA.DAT with records from
    **  the sequential file SEQ.DAT.  No exception file is created.
    **  This module also returns the CONVERT and SORT statistics
    **  for each key that is loaded by utilizing the new callback
    **  feature that is available through the CONV$CONVERT call.
    */

    #include <stdio>
    #include <descrip>
    #include <lib$routines>
    #include <conv$routines>
    #include <convdef>
    #include <starlet>
    /*

    **  Allocate a statistics block structure using the template provided by
    **  <convdef.h>. This structure will be passed to the CONV$CONVERT routine
    **  to receive both the basic and extended statistics from CONVERT. The
    **  fields returned to the structure from CONVERT are listed in table 5-1.
    **
    **  The number of statistics to be returned is passed as the first element
    **  in the array. The value CONV$K_MAX_STATISTICS will return the set of
    **  basic statistics, while the value CONV$K_EXT_STATISTICS will return all
    **  statistics.
    */
    struct conv$statistics stats;

    /*
    **  Main program (CONVSTAT) starts here
    */
    int CONVSTAT (void)

    {
    $DESCRIPTOR (input_file, "SEQ.DAT");
    $DESCRIPTOR (output_file, "CUSTDATA.DAT");
    $DESCRIPTOR (fdl_file, "INDEXED.FDL");

    void callback();

    int stat;

    /*
    **  Allocate an options block structure using the template provided by
    **  <convdef.h>. This structure will be passed to the CONV$PASS_OPTIONS
    **  routine to indicate what options are to be used for the file convert.
    **  The fields passed to the structure are listed in table 5-2.
    */
    struct conv$options param_list;

    param_list.conv$l_options_count   = CONV$K_MAX_OPTIONS;
    param_list.conv$l_create          = 1;
    param_list.conv$l_share           = 0;
    param_list.conv$l_fast            = 1;
    param_list.conv$l_merge           = 0;
    param_list.conv$l_append          = 0;
    param_list.conv$l_sort            = 1;
    param_list.conv$l_work_files      = 2;
    param_list.conv$l_key             = 0;
    param_list.conv$l_pad             = 0;
    param_list.conv$l_pad_character   = 0;
    param_list.conv$l_truncate        = 0;
    param_list.conv$l_exit            = 0;
    param_list.conv$l_fixed_control   = 0;
    param_list.conv$l_fill_buckets    = 0;
    param_list.conv$l_read_check      = 0;
    param_list.conv$l_write_check     = 0;
    param_list.conv$l_fdl             = 1;
    param_list.conv$l_exception       = 0;
    param_list.conv$l_prologue        = 0;
    param_list.conv$l_ignore_prologue = 1;
    param_list.conv$l_secondary       = 1;

    /*
    ** Init the number of statistics to be returned
    */
    stats.conv$l_statistics_count = CONV$K_EXT_STATISTICS;

    LIB$INIT_TIMER();   /* Start a timer */

    /*
    ** First call to pass all the file names
    */
    stat = CONV$PASS_FILES ( &input_file, &output_file, &fdl_file);
    if (!(stat & 1)) return stat;

    /*
    ** Second call to pass particular options chosen as indicated in array.
    */
    stat = CONV$PASS_OPTIONS ( &param_list );
    if (!(stat & 1)) return stat;

    /*
    ** Final call to perform actual convert, passing statistics block and
    ** callback routine address.
    */
    stat = CONV$CONVERT ( &stats, 0, &callback );
    if (stat & 1)
    {
    /*
    ** Successful Convert! Print out counters from statistics.
    */
     printf ("Number of files processed   : %d\n", stats.conv$l_file_count);
     printf ("Number of records           : %d\n", stats.conv$l_record_count);
     printf ("Number of exception records : %d\n", stats.conv$l_except_count);
     printf ("Number of valid records     : %d\n", stats.conv$l_valid_count);
     LIB$SHOW_TIMER();
     }
     return stat;       /* success or failure */
    }

    void callback ()
    {
       int status, SYS$ASCTIM();
       int cvtflg = 1;
       static char date[15];
       $DESCRIPTOR(out_date, date);

    printf ("Statistics for Key     : %d\n", stats.conv$l_key_number);
    printf (" Records Sorted        : %d\n", stats.conv$l_rec_out);
    printf (" Sort Nodes            : %d\n", stats.conv$l_nodes);
    printf (" Work file allocation  : %d\n", stats.conv$l_wrk_alq);
    printf (" Initial Sort Runs     : %d\n", stats.conv$l_ini_runs);
    printf (" Merge Order           : %d\n", stats.conv$l_mrg_order);
    printf (" Merge Passes          : %d\n", stats.conv$l_mrg_passes);
    printf (" Sort Direct IO        : %d\n", stats.conv$l_sort_dio_count);
    printf (" Sort Buffered IO      : %d\n", stats.conv$l_sort_bio_count);
    status = SYS$ASCTIM (0, &out_date, &stats.conv$q_sort_elapsed_time, cvtflg);
    if (!(status & 1)) LIB$STOP (status);
    printf (" Sort Elapsed Time     : %s\n", date);
    status = SYS$ASCTIM (0, &out_date, &stats.conv$q_sort_cpu_time, cvtflg);
    if (!(status & 1)) LIB$STOP (status);
    printf (" Sort Cpu Time         : %s\n", date);
    printf (" Sort Page Faults      : %d\n\n", stats.conv$l_sort_pf_count);

    printf (" Load Direct IO        : %d\n", stats.conv$l_load_dio_count);
    printf (" Load Buffered IO      : %d\n", stats.conv$l_load_bio_count);
    status = SYS$ASCTIM (0, &out_date, &stats.conv$q_load_elapsed_time, cvtflg);
    if (!(status & 1)) LIB$STOP (status);
    printf (" Load Elapsed Time     : %s\n", date);
    status = SYS$ASCTIM (0, &out_date, &stats.conv$q_load_cpu_time, cvtflg);
    if (!(status & 1)) LIB$STOP (status);
    printf (" Load Cpu Time         : %s\n", date);
    printf (" Load Page Faults      : %d\n\n", stats.conv$l_load_pf_count);

    return;
    }

Example 6-3 shows how to use the CONV$RECLAIM routine in a Fortran program.

Example 6-3 Using the CONV$RECLAIM Routine in a Fortran Program

    *            This program calls the routine that performs the
    *            function of the Convert/Reclaim utility.  It
    *            reclaims empty buckets from an indexed file named
    *            PROL3.DAT.  It also returns all the CONVERT/RECLAIM
    *            statistics.
    *            Program declarations

            IMPLICIT        INTEGER*4 (A - Z)

    *            Set up a statistics block.  There are four -- data
    *            buckets scanned, data buckets reclaimed, index
    *            buckets reclaimed, total buckets reclaimed.

            INTEGER*4       OUTSTATS(5) /4,0,0,0,0/

    *            Declare the input file.

            CHARACTER       IN_FILE*9 /'PROL3.DAT'/

    *            Call the routine.

            STATUS = CONV$RECLAIM (IN_FILE, OUTSTATS)
            IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS))

    *            Display the statistics.

            WRITE (6,1000) (OUTSTATS(I),I=2,5)
    1000    FORMAT (1X,'Number of data buckets scanned: ',I5/,
            1       1X,'Number of data buckets reclaimed: ',I5/,
            1       1X,'Number of index buckets reclaimed: ',I5/,
            1       1X,'Total buckets reclaimed: ',I5)

            END

Example 6-4 shows how to use the CONV$RECLAIM routine in a C program.

Example 6-4 Using the CONV$RECLAIM Routine in a C Program

    /*
    **  This module calls the routine that performs the
    **  function of the CONVERT/RECLAIM utility.  It reclaims
    **  empty buckets from an indexed file named PROL3.DAT.
    **
    **  This module also returns and prints all of the
    **  CONVERT/RECLAIM statistics.
    */

    #include <stdio>
    #include <descrip>

    CONVREC ()
    {
    $DESCRIPTOR (filename, "PROL3.DAT");/* Provide your file name */
    struct { int statistics_count,     /* must precede actual statistics */
          scanned_buckets,
          data_buckets_reclaimed,
          index_buckets_reclaimed,
          total_buckets_reclaimed; } stats = 4 /* 4 statistic arguments */;
    int stat;
    /*
    **  Perform actual operation.
    */
    stat = CONV$RECLAIM ( &filename, &stats );
    if (stat & 1)
        {
        /*
        **  Successful RECLAIM. Now format and print the counts.
        */
        printf ("Data buckets scanned    : %d\n", stats.scanned_buckets);
        printf ("Data buckets reclaimed  : %d\n", stats.data_buckets_reclaimed);
        printf ("Index buckets reclaimed : %d\n", stats.index_buckets_reclaimed);
        printf ("Total buckets reclaimed : %d\n", stats.total_buckets_reclaimed);
        }
    return stat /* succes or failure */;
    }

## 6.3 CONVERT Routines

This section describes the individual CONVERT routines.

## CONV$CONVERT

> The CONV$CONVERT routine uses the Convert utility to perform the actual conversion begun with CONV$PASS_FILES and CONV$PASS_OPTIONS. Optionally, the routine can return statistics about the conversion.

> Note that the CONV$CONVERT routine may return appropriate File Definition Language (FDL) error messages to the calling program, where applicable.

### Format

> CONV$CONVERT [status_block_address] [,flags] [,callback_routine]

### RETURNS

> OpenVMS usage: | cond_value
> type: | longword (unsigned)
> access: | write only
> mechanism: | by value

> Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

### Arguments

> #### status_block_address

> OpenVMS usage: | vector_longword_unsigned
> type: | longword (unsigned)
> access: | write only
> mechanism: | by reference

> The conversion statistics. The status_block_address argument is the address of a variable-length array of longwords that receives statistics about the conversion.

> You can request conversion statistics using zero-based, symbolic offsets (CONV$K_) into the variable-length array of longwords that contains the statistics. The array is defined as a structure (CONV$STATISTICS) of named longwords (CONV$L_) to support access by high-level progamming languages.

> Table 6-1 lists the array elements by number and by symbol. The first element specifies the number of statistics to return by array order. For example, if you assign the symbol CONV$L_STATISTICS_COUNT the value 2, the routine returns the statistics from the first two statistics elements:

> - Number of files converted
> - Number of records converted

> Table 6-1 Conversion Statistics Array
> Array Element | Field Name | Description
> --- | --- | ---
> 0 | CONV$L_STATISTICS_COUNT | Number of statistics specified
> 1 | CONV$L_FILE_COUNT | Number of files
> 2 | CONV$L_RECORD_COUNT | Number of records
> 3 | CONV$L_EXCEPT_COUNT | Number of exception record
> 4 | CONV$L_VALID_COUNT | Number of valid records
> 5 | CONV$L_KEY_NUMBER | Most recent key processed
> 6 | CONV$L_REC_OUT | Number of records sorted
> 7 | CONV$L_NODES | Nodes in sort tree
> 8 | CONV$L_WRK_ALQ | Work file allocation
> 9 | CONV$L_INI_RUNS | Initial dispersion runs
> 10 | CONV$L_MRG_ORDER | Maximum merge order
> 11 | CONV$L_MRG_PASSES | Number of merge passes
> 12 | CONV$L_SORT_DIO_COUNT | Sort direct IO
> 13 | CONV$L_SORT_BIO_COUNT | Sort buffered IO
> 14 | CONV$Q_SORT_ELAPSED_TIME | Sort elapsed time
> 15 | CONV$Q_SORT_CPU_TIME | Sort CPU time
> 16 | CONV$L_SORT_PF_COUNT | Number of page faults for sort
> 17 | CONV$L_LOAD_DIO_COUNT | Load direct IO
> 18 | CONV$L_LOAD_BIO_COUNT | Load buffered IO
> 19 | CONV$Q_LOAD_ELAPSED_TIME | Load elapsed time
> 20 | CONV$Q_LOAD_CPU_TIME | Load CPU time
> 21 | CONV$L_LOAD_PF_COUNT | Number of page faults for load

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Flags (or masks) that control how the CONV$PASS_FILES fdl_filespec argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing control flags (or a mask). If you omit the flags argument or specify it as zero, no flags are set. The flags and their meanings are described in the following table:

> Flag | Function
> --- | ---
> CONV$V_FDL_STRING | Interprets the fdl_filespec argument supplied in the call to CONV$PASS_FILES as an FDL specification in string form. By default, this argument is interpreted as the file name of an FDL file.
> CONV$V_SIGNAL | Signals any error. By default, the status code is returned to the calling image.

> By default, an error status is returned rather than signaled.

> #### callback_routine

> OpenVMS usage: | procedure
> type: | procedure value
> access: | read only
> mechanism: | by reference

> Name of a user-supplied routine to process the statistics information. The callback_routine argument is the address of the procedure value of a user-supplied routine to call at the completion of each key load.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> CONV$_BADBLK | Invalid option block.
> CONV$_BADLOGIC | Internal logic error detected.
> CONV$_BADSORT | Error trying to sort input file.
> CONV$_CLOSEIN | Error closing file specification as input.
> CONV$_CLOSEOUT | Error closing file specification as output.
> CONV$_CONFQUAL | Conflicting qualifiers.
> CONV$_CREA_ERR | Error creating output file.
> CONV$_CREATEDSTM | File specification has been created in stream format.
> CONV$_DELPRI | Cannot delete primary key.
> CONV$_DUP | Duplicate key encountered.
> CONV$_EXTN_ERR | Unable to extend output file.
> CONV$_FATALEXC | Fatal exception encountered.
> CONV$_FILLIM | Exceeded open file limit.
> CONV$_IDX_LIM | Exceeded maximum index level.
> CONV$_ILL_KEY | Illegal key or value out of range.
> CONV$_ILL_VALUE | Illegal parameter value.
> CONV$_INP_FILES | Too many input files.
> CONV$_INSVIRMEM | Insufficient virtual memory.
> CONV$_KEY | Invalid record key.
> CONV$_LOADIDX | Error loading secondary index n.
> CONV$_NARG | Wrong number of arguments.
> CONV$_NOKEY | No such key.
> CONV$_NOTIDX | File is not an indexed file.
> CONV$_NOTSEQ | Output file is not a sequential file.
> CONV$_NOWILD | No wildcard permitted.
> CONV$_OPENEXC | Error opening exception file specification.
> CONV$_OPENIN | Error opening file specification as input.
> CONV$_OPENOUT | Error opening file specification as output.
> CONV$_ORDER | Routine called out of order.
> CONV$_PAD | Packet Assembly/Disassembly (PAD) option ignored; output record format not fixed.
> CONV$_PLV | Unsupported prolog version.
> CONV$_PROERR | Error reading prolog.
> CONV$_PROL_WRT | Prolog write error.
> CONV$_READERR | Error reading file specification.
> CONV$_REX | Record already exists.
> CONV$_RMS | Record caused RMS severe error.
> CONV$_RSK | Record shorter than primary key.
> CONV$_RSZ | Record does not fit in block/bucket.
> CONV$_RTL | Record longer than maximum record length.
> CONV$_RTS | Record too short for fixed record format file.
> CONV$_SEQ | Record not in order.
> CONV$_UDF_BKS | Cannot convert UDF records into spanned file.
> CONV$_UDF_BLK | Cannot fit UDF records into single block bucket.
> CONV$_VALERR | Specified value is out of legal range.
> CONV$_VFC | Record too short to fill fixed part of VFC record.
> CONV$_WRITEERR | Error writing file specification.

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_006.HTML