HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

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.

While these routines can be invoked within a single thread of a threaded process, the callable Convert utility is not a reentrant, thread safe utility. Multiple concurrent invocations of the callable Convert utility interface are not supported. These routines are not reentrant and cannot be called from the asynchronous system trap (AST) level. In addition, these routines require ASTs to remain enabled in order to function properly.

6.2 Using the CONVERT Routines: Examples

Example 6-1 shows how to use 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.

/*
**  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.

*            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.

/*
**  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 */;
}

This section describes the individual CONVERT routines.

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.