Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## CONV$PASS_FILES

> The CONV$PASS_FILES routine specifies a file to be converted using the CONV$CONVERT routine.

### Format

> CONV$PASS_FILES input_filespec ,output_filespec [,fdl_filespec] [,exception_filespec] [,flags]

### 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

> #### input_filespec

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor---fixed-length string descriptor

> The name of the file to be converted. The input_filespec argument is the address of a string descriptor pointing to the name of the file to be converted.

> #### output_filespec

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor---fixed-length string descriptor

> The name of the file that receives the records from the input file. The output_filespec argument is the address of a string descriptor pointing to the name of the file that receives the records from the input file.

> #### fdl_filespec

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor---fixed-length string descriptor

> The name of the FDL file that defines the output file. The fdl_filespec argument is the address of a string descriptor pointing to the name of the FDL file.

> #### exception_filespec

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor---fixed-length string descriptor

> The name of the file that receives copies of records that cannot be written to the output file. The exception_filespec argument is the address of a string descriptor pointing to this name.

> #### flags

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

> Flags (or masks) that control how the fdl_filespec argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags (or mask). If you omit this argument or specify it as zero, no flags are set. If you specify a flag, it remains in effect until you explicitly reset it in a subsequent call to a CONVERT routine.

> The flags and their meanings are described in the following table:

> Flag | Function
> --- | ---
> CONV$V_FDL_STRING | Interprets the fdl_filespec argument as an FDL specification in string form. By default, this argument is interpreted as a 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.

### Description

> The CONV$PASS_FILES routine specifies a file to be converted using the CONV$CONVERT routine. A single call to CONV$PASS_FILES allows you to specify an input file, an output file, an FDL file, and an exception file. If you have multiple input files, you must call CONV$PASS_FILES once for each file. You need to specify only the input_filespec argument for the additional files, as follows:

>     status = CONV$PASS_FILES (input_filespec)

> The additional calls must immediately follow the original call that specified the output file specification.

> Wildcard characters are not allowed in the file specifications passed to the CONVERT routines.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> CONV$_INP_FILES | Too many input files.
> CONV$_INSVIRMEM | Insufficient virtual memory.
> CONV$_NARG | Wrong number of arguments.
> CONV$_ORDER | Routine called out of order.

## CONV$PASS_OPTIONS

> The CONV$PASS_OPTIONS routine specifies which qualifiers are to be used by the Convert utility (CONVERT).

### Format

> CONV$PASS_OPTIONS [parameter_list_address] [,flags]

### 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

> #### parameter_list_address

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

> Address of a variable-length array of longwords used to specify the CONVERT qualifiers. The array is symbolically defined as a structure (CONV$OPTIONS) that you can access in one of the following ways:
> - As an array of named longwords using zero-based symbols (CONV$L_...)
> - As an array using zero-based offsets (CONV$K_...)

> The first longword in the array (CONV$L_OPTIONS_COUNT) specifies the number of elements in the array, and each remaining element is associated with a CONVERT qualifier, as shown in Table 6-2. You can use the first element to assign values to the first n CONVERT qualifiers---where n is the value of CONV$L_OPTIONS_COUNT---and take default values for the remaining qualifiers. For example, to assign values to only the first three qualifiers and to take the default value for the remaining qualifiers, specify CONV$L_OPTIONS_COUNT=3. This effectively changes the size of the array to include only the first three elements, as follows, which have values you specify:

> - /CREATE
> - /SHARE
> - /FAST_LOAD
> The remaining qualifiers take the default values depicted in Table 6-2.

> To assign individual values to the CONVERT qualifiers, access the array and specify the desired value (1 or 0). See the OpenVMS Record Management Utilities Reference Manual for detailed descriptions of the CONVERT qualifiers.

> If you do not specify parameter_list_address, your program effectively sends the routine all of the default values listed in Table 6-2.

> Table 6-2 CONVERT Qualifiers
> Element Number | Symbolic Value | Longword Default Value | Qualifier Default Value
> --- | --- | --- | ---
> 0 | CONV$L_OPTIONS_COUNT | None | Not applicable
> 1 | CONV$L_CREATE | 1 | /CREATE
> 2 | CONV$L_SHARE | 0 | /NOSHARE
> 3 | CONV$L_FAST | 1 | /FAST_LOAD
> 4 | CONV$L_MERGE | 0 | /NOMERGE
> 5 | CONV$L_APPEND | 0 | /NOAPPEND
> 6 | CONV$L_SORT | 1 | /SORT
> 7 | CONV$L_WORK_FILES | 2 | /WORK_FILES=2
> 8 | CONV$L_KEY | 0 | /KEY=0
> 9 | CONV$L_PAD | 0 | /NOPAD
> 10 | CONV$L_PAD_CHARACTER | 0 1 | Pad character=0
> 11 | CONV$L_TRUNCATE | 0 | /NOTRUNCATE
> 12 | CONV$L_EXIT | 0 | /NOEXIT
> 13 | CONV$L_FIXED_CONTROL | 0 | /NOFIXED_CONTROL
> 14 | CONV$L_FILL_BUCKETS | 0 | /NOFILL_BUCKETS
> 15 | CONV$L_READ_CHECK | 0 | /NOREAD_CHECK
> 16 | CONV$L_WRITE_CHECK | 0 | /NOWRITE_CHECK
> 17 | CONV$L_FDL | 0 | /NOFDL
> 18 | CONV$L_EXCEPTION | 0 | /NOEXCEPTION
> 19 | CONV$L_PROLOGUE | None | /PROLOGUE= n 2
> 20 | CONV$L_IGNORE_PROLOGUE | 0 | Not applicable
> 21 | CONV$L_SECONDARY | 1 | SECONDARY=1

1Null character. To specify non-null pad character, insert ASCII value of desired pad character.
2System or process default setting.

If you specify /EXIT and the utility encounters an exception record, CONVERT returns with a fatal exception status.

If you specify an FDL file specification in the CONV$PASS_FILES routine, you must place a 1 in the FDL longword. If you also specify an exceptions file specification in the CONV$PASS_FILES routine, you must place a 1 in the EXCEPTION longword. You may specify either, both, or neither of these files, but the values in the CONV$PASS_FILES call must match the values in the parameter list. If they do not, the routine returns an error.

The PROLOG longword overrides the KEY PROLOG attribute supplied by the FDL file. If you use the PROLOG longword, enter one of the following values:

- The value 0 (default) specifies the system or process prolog type.
- The value 2 specifies a Prolog 1 or 2 file in all instances, even when circumstances would allow you to create a Prolog 3 file.
- The value 3 specifies a Prolog 3 file. If a Prolog 3 file is not allowed, you want the conversion to fail.

If the size of the options block that you pass to CONV$PASS_OPTIONS includes the SECONDARY longword value, then you must specify a value for the IGNORE_PROLOGUE field.

This field is used in conjunction with the PROLOGUE offset to determine if the prologue version of the output file is to be taken from a passed FDL, the input file, the process default or system default, or from the options block itself.

A value of 0 (zero) for the IGNORE_PROLOGUE field indicates that the prologue version of the output file is to be taken from the PROLOGUE value specified in the options block.

If the PROLOGUE value in the options block contains a 0 (zero), the process default or system default prologue version will be used. This will override the prologue version specified in an FDL file or in the input file's characteristics.

A value of 1 (one) for the IGNORE_PROLOGUE field implies that the prologue version of the output file will come from the FDL file (if specified) or from the input file's characteristics.

#### flags

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

Flags (or masks) that control how the fdl_filespec argument, used in calls to the CONV$PASS_FILES routine, is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags (or a mask). If you omit this argument or specify it as zero, no flags are set. If you specify a flag, it remains in effect until you explicitly reset it in a subsequent call to a CONVERT routine.

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.
FDL$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.

### Description

> You can use an options array to generate programmatic CONVERT commands. For example, you can generate the following programmatic CONVERT command by configuring the options array described by the pseudocode that follows the example command line:

>     $ CONVERT/FAST_LOAD/SORT/WORK_FILES=6/EXIT

>     OPTIONS ARRAY [12]         {Allocate a 13-cell array}
>     OPTIONS[0]  =  12          {Number of options]
>     OPTIONS[1]  =   1          {Specifies the /CREATE option}
>     OPTIONS[2]  =   0          {Specifies the /NOSHARE option}
>     OPTIONS[3]  =   1          {Specifies the /FAST_LOAD option}
>     OPTIONS[4]  =   0          {Specifies the /NOMERGE option}
>     OPTIONS[5]  =   0          {Specifies the /NOAPPEND option}
>     OPTIONS[6]  =   1          {Specifies the /SORT option}
>     OPTIONS[7]  =   6          {Specifies the /WORK_FILES=6 option}
>     OPTIONS[8]  =   0          {Specifies the /KEY=0 option}
>     OPTIONS[9]  =   0          {Specifies the /NOPAD option}
>     OPTIONS[10] =   0          {Specifies the null pad character}
>     OPTIONS[11] =   0          {Specifies the /NOTRUNCATE option}
>     OPTIONS[12] =   1          {Specifies the /EXIT option}

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> CONV$_BADBLK | Invalid option block.
> CONV$_CONFQUAL | Conflicting qualifiers.
> CONV$_INSVIRMEM | Insufficient virtual memory.
> CONV$_NARG | Wrong number of arguments.
> CONV$_OPENEXC | Error opening exception file file specification.
> CONV$_ORDER | Routine called out of order.

## CONV$RECLAIM

> The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim utility.

### Format

> CONV$RECLAIM input_filespec [,statistics_blk] [,flags] [key_number]

### 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

> #### input_filespec

> OpenVMS usage: | char_string
> type: | character-coded text string
> access: | read only
> mechanism: | by descriptor---fixed-length string descriptor

> Name of the Prolog 3 indexed file to be reclaimed. The input_filespec argument is the address of a string descriptor pointing to the name of the Prolog 3 indexed file.

> #### statistics_blk

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

> Bucket reclamation statistics. The statistics_blk argument is the address of a variable-length array of longwords that receives statistics on the bucket reclamation. You can choose which statistics you want returned by specifying a number in the first element of the array. This number determines how many of the four possible statistics the routine returns.

> You can request bucket reclamation statistics using symbolic names or numeric offsets into the variable-length array of longwords that contains the statistics. The array is defined as a structure of named longwords (RECL$STATISTICS) to support access by high-level progamming languages.

> Table 6-3 lists the array elements by number and by symbol. The first element specifies one or more statistics by array order. For example, if you assign the symbol RECL$L_STATISTICS_COUNT the value 3, the routine returns the statistics from the first three statistics elements:

> - Data buckets scanned
> - Data buckets reclaimed
> - Index buckets reclaimed

> Table 6-3 Bucket Reclamation Statistics Array
> Array Element | Field Name | Description
> --- | --- | ---
> 0 | RECL$L_STATISTICS_COUNT | Number of statistics specified
> 1 | RECL$L_SCAN_COUNT | Data buckets scanned
> 2 | RECL$L_DATA_COUNT | Data buckets reclaimed
> 3 | RECL$L_INDEX_COUNT | Index buckets reclaimed
> 4 | RECL$L_TOTAL_COUNT | Total buckets reclaimed

> #### flags

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

> Flags (or masks) that control how the fdl_filespec argument, used in calls to the CONV$PASS_FILES routine, 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 flag is defined as follows:

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

> #### key_number

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

> The optional key_number argument permits the calling program to selectively reclaim buckets by key number. If the calling program omits this argument or passes a NULL value in the argument, all buckets are reclaimed, without regard to key designation. If the calling program passes a valid key number as the value for this argument, the routine reclaims only the buckets for the specified key.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> CONV$_BADLOGIC | Internal logic error detected.
> CONV$_INSVIRMEM | Insufficient virtual memory.
> CONV$_INVBKT | Invalid bucket at VBN n.
> CONV$_NOTIDX | File is not an indexed file.
> CONV$_NOWILD | No wildcard permitted.
> CONV$_OPENIN | Error opening file specification as input.
> CONV$_PLV | Unsupported prolog version.
> CONV$_PROERR | Error reading prolog.
> CONV$_PROL_WRT | Prolog write error.
> CONV$_READERR | Error reading file specification.
> CONV$_WRITEERR | Error writing output file.

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_007.HTML