[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

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:

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

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4493PRO_006.HTML