[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP 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