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]
1 – 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.
2 – 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:
o As an array of named longwords using zero-based symbols
(CONV$L_ . . . )
o 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 CONVERT
Qualifiers. 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:
o /CREATE
o /SHARE
o /FAST_LOAD
The remaining qualifiers take the default values depicted in
CONVERT Qualifiers.
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 CONVERT Qualifiers.
Table 4-2 CONVERT Qualifiers
Longword
Element Default
Qualifier
Number Symbolic Value Value 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_ 0 Not applicable
PROLOGUE
21 CONV$L_SECONDARY 1 SECONDARY=1
Footnotes:
1. Default is a null pad character. To specify a non-null
pad character, insert the ASCII value of the desired pad
character.
2. Specify a system 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:
o The value 0 (default) specifies the system or process prolog
type.
o 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.
o 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_ Interprets the fdl_filespec argument supplied
STRING 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.
3 – 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}
4 – 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.