 |
OpenVMS Utility Routines Manual
See the description of the fdl_desc argument for
details.
This argument allows you to specify default FDL attributes. In other
words, FDL$CREATE processes the attributes specified in this argument
unless you override them with the attributes you specify in the
fdl_desc argument.
You can code the FDL defaults directly into your program, typically
with an FDL specification in string form.
Description
FDL$CREATE calls the FDL$PARSE routine to parse the FDL specification.
The FDL specification can be in a file or a character string.
| Source of FDL Specification |
Advantages |
Disadvantages |
|
FDL file
|
Variability; for example, if the specification changes regularly, you
can revise the file without revising the calling program.
|
File must be in default directory.
Slower.
|
|
Character string
|
You do not have to be concerned with locating a file.
|
Program must be recoded to change FDL specification.
|
|
|
Faster access.
|
|
If the FDL specification is relatively simple and is not going to
change, put the FDL specification in a character string as the
fdl_desc argument to the call.
FDL$CREATE opens (creates) the specified RMS file and then closes it
without putting any data in it.
FDL$CREATE does not create the output file if an error status is either
returned or signaled.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
FDL$_ABKW
|
Ambiguous keyword in statement
number<CRLF>
reference-text.
|
|
FDL$_ABPRIKW
|
Ambiguous primary keyword in statement
number<CRLF>
reference-text.
|
|
FDL$_BADLOGIC
|
Internal logic error detected.
|
|
FDL$_CLOSEIN
|
Error closing
filename as input.
|
|
FDL$_CLOSEOUT
|
Error closing
filename as output.
|
|
FDL$_CREATE
|
Error creating
filename.
|
|
FDL$_CREATED
|
Filename created.
|
|
FDL$_CREATED_STM
|
Filename created in stream format.
|
|
FDL$_FDLERROR
|
Error parsing FDL file.
|
|
FDL$_ILL_ARG
|
Wrong number of arguments.
|
|
FDL$_INSVIREM
|
Insufficient virtual memory.
|
|
FDL$_INVBLK
|
Invalid RMS control block at virtual address 'hex-offset'.
|
|
FDL$_MULPRI
|
Multiple primary definition in statement
number.
|
|
FDL$_OPENFDL
|
Error opening
filename.
|
|
FDL$_OPENIN
|
Error opening
filename as input.
|
|
FDL$_OPENOUT
|
Error opening
filename as output.
|
|
FDL$_OUTORDER
|
Key or area primary defined out of order in statement
number.
|
|
FDL$_READERR
|
Error reading
filename.
|
|
FDL$_RFLOC
|
Unable to locate related file.
|
|
FDL$_SYNTAX
|
Syntax error in statement
number
reference-text.
|
|
FDL$_UNPRIKW
|
Unrecognized primary keyword in statement
number<CRLF>
reference-text.
|
|
FDL$_UNQUAKW
|
Unrecognized qualifier keyword in statement
number<CRLF>
reference-text.
|
|
FDL$_UNSECKW
|
Unrecognized secondary keyword in statement
number<CRLF>
reference-text.
|
|
FDL$_VALERR
|
Specified value is out of legal range.
|
|
FDL$_VALPRI
|
Value required on primary in statement
number.
|
|
FDL$_WARNING
|
Parsed with warnings.
|
|
FDL$_WRITEERR
|
Error writing
filename.
|
|
RMS$_ACT
|
File activity precludes operation.
|
|
RMS$_CRE
|
Ancillary control process (ACP) file create failed.
|
|
RMS$_CREATED
|
File was created, not opened.
|
|
RMS$_DNF
|
Directory not found.
|
|
RMS$_DNR
|
Device not ready or not mounted.
|
|
RMS$_EXP
|
File expiration date not yet reached.
|
|
RMS$_FEX
|
File already exists, not superseded.
|
|
RMS$_FLK
|
File currently locked by another user.
|
|
RMS$_PRV
|
Insufficient privilege or file protection violation.
|
|
RMS$_SUPERSEDE
|
Created file superseded existing version.
|
|
RMS$_WLK
|
Device currently write locked.
|
FDL$GENERATE
The FDL$GENERATE routine produces an FDL specification and writes it to
either an FDL file or a character string.
Format
FDL$GENERATE flags ,fab_pointer ,rab_pointer [,fdl_file_dst]
[,fdl_file_resnam] [,fdl_str_dst] [,bad_blk_addr] [,retlen]
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
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags (or masks) that control how the fdl_str_dst
argument 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. The flags and their meanings are as follows:
| Flag |
Function |
|
FDL$V_FDL_STRING
|
Interprets the
fdl_str_dst argument as an FDL specification in string
form. By default, the
fdl_str_dst argument is interpreted as the file name
of an FDL file.
|
|
FDL$V_FULL_OUTPUT
|
Includes the FDL attributes to describe all the bits and fields in the
OpenVMS RMS control blocks, including run-time options. If this flag is
set, every field is inspected before being written. By default, only
the FDL attributes that describe permanent file attributes are included
(producing a much shorter FDL specification).
|
|
FDL$V_LONG_NAMES
|
Returns the
FDL_FILE_RESNAME using the long result name from a
long name access block (NAML). By default, the
FDL_FILE_RESNAM is returned from the short fields of a
name access block (NAM) and thus may have a generated specification.
This flag is valid for OpenVMS Alpha only.
|
|
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.
fab_pointer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
RMS file access block (FAB). The fab_pointer argument
is the address of a longword containing the address of a FAB.
rab_pointer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
RMS record access block (RAB). The rab_pointer
argument is the address of a longword containing the address of a RAB.
fdl_file_dst
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the FDL file to be created. The fdl_file_dst
argument is the address of a character-string descriptor containing the
file name of the FDL file to be created. If the FDL$V_FDL_STRING flag
is set in the flags argument, this argument is
ignored; otherwise, it is required. The FDL specification is written to
the file named in this argument.
fdl_file_resnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor---fixed-length string descriptor |
Resultant name of the FDL file created. The
fdl_file_resnam argument is the address of a variable
character-string descriptor that receives the resultant name of the FDL
file created (if FDL$GENERATE is directed to create an FDL file).
fdl_str_dst
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor---fixed-length string descriptor |
FDL specification. The fdl_str_dst argument is the
address of a variable character string descriptor that receives the FDL
specification created. If the FDL$V_FDL_STRING bit is set in the
flags argument, this argument is required; otherwise,
it is ignored.
bad_blk_addr
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of an invalid RMS control block. The
bad_blk_addr argument is the address of a longword
that receives the address of an invalid control block (a fatal error).
If an invalid control block is detected, this argument is returned;
otherwise, it is ignored.
retlen
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters received in either the
fdl_file_resnam or the fdl_str_dst
argument. The retlen argument is the address of a
longword that receives this number.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
FDL$_INVBLK
|
Invalid block.
|
|
RMS$_ACT
|
File activity precludes operation.
|
|
RMS$_CONTROLC
|
Operation completed under Ctrl/C.
|
|
RMS$_CONTROLO
|
Output completed under Ctrl/O.
|
|
RMS$_CONTROLY
|
Operation completed under Ctrl/Y.
|
|
RMS$_DNR
|
Device not ready or mounted.
|
|
RMS$_EXT
|
ACP file extend failed.
|
|
RMS$_OK_ALK
|
Record already locked.
|
|
RMS$_OK_DUP
|
Record inserted had duplicate key.
|
|
RMS$_OK_IDX
|
Index update error occurred.
|
|
RMS$_PENDING
|
Asynchronous operation pending completion.
|
|
RMS$_PRV
|
Insufficient privilege or file protection violation.
|
|
RMS$_REX
|
Record already exists.
|
|
RMS$_RLK
|
Target record currently locked by another stream.
|
|
RMS$_RSA
|
Record stream currently active.
|
|
RMS$_WLK
|
Device currently write locked.
|
|
SS$_ACCVIO
|
Access violation.
|
|
STR$_FATINERR
|
Fatal internal error in run-time library.
|
|
STR$_ILLSTRCLA
|
Illegal string class.
|
|
STR$_INSVIRMEM
|
Insufficient virtual memory.
|
FDL$PARSE
The FDL$PARSE routine parses an FDL specification, allocates OpenVMS
RMS control blocks (FABs, RABs, or XABs), and fills in the relevant
fields.
Format
FDL$PARSE fdl_desc ,fdl_fab_pointer ,fdl_rab_pointer [,flags]
[,default_fdl_desc] [,stmnt_num]
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
fdl_desc
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor---fixed-length string descriptor |
Name of the FDL file or the actual FDL specification to be parsed. See
the description of the fdl_desc argument for the
FDL$CREATE routine for details.
fdl_fab_pointer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of an RMS file access block (FAB). The
fdl_fab_pointer argument is the address of a longword
that receives the address of the FAB. FDL$PARSE both allocates the FAB
and fills in its relevant fields.
fdl_rab_pointer
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Address of an RMS record access block (for VAX, this is the RAB; for
Alpha, it is the RAB64). The fdl_rab_pointer argument
is the address of a longword that receives the address of the RAB or
RAB64. FDL$PARSE both allocates the RAB or RAB64 and fills in any
fields designated in the FDL specification.
For Alpha, the 64-bit record access block (RAB64) consists of the
traditional 32-bit RAB followed by some 64-bit fields. The RAB64 is
automatically allocated for Alpha users, who can either use it as a
RAB64 or overlay it with the 32-bit RAB definition and use it as a
traditional 32-bit RAB.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags (or masks) that control how the default_fdl_desc
argument is interpreted and how errors are signaled. The
flags argument is the address of a longword containing
the control flags. If you omit this argument or specify it as zero, no
flags are set. The flags and their
meanings are as follows:
| Flag |
Function |
|
FDL$V_DEFAULT_STRING
|
Interprets the
default_fdl_desc argument as an FDL specification in
string form. By default, the
default_fdl_desc argument is interpreted as the file
name of an FDL file.
|
|
FDL$V_FDL_STRING
|
Interprets the
fdl_desc argument as an FDL specification in string
form. By default, the
fdl_desc argument is interpreted as the file name of
an FDL file.
|
|
FDL$V_LONG_NAMES
|
Allocates and returns a long name access block (NAML) linked to the
returned RMS file access block (FAB). The appropriate values are set in
the NAML and FAB blocks so that the long file name fields of the NAML
block will be used.
By default, a name block is not allocated and the file name fields
of FAB are used.
If the FDL$V_LONG_NAMES flag is set, then the FDL$V_LONG_NAMES bit
must also be set in the
flags argument to the FDL$RELEASE routine to ensure
that memory allocated for the NAML block is deallocated properly.
This flag is valid for OpenVMS Alpha only.
|
|
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.
default_fdl_desc
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor---fixed-length string descriptor |
The default_fdl_desc argument is the address of a
character-string descriptor pointing to either the default FDL file or
the default FDL specification. See the description of the
fdl_desc argument for the FDL$CREATE routine for
details.
This argument allows you to specify default FDL attributes. In other
words, FDL$PARSE processes the attributes specified in this argument
unless you override them with the attributes you specify in the
fdl_desc argument.
You can code the FDL defaults directly into your program, typically
with an FDL specification in string form.
stmnt_num
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
FDL statement number. The stmnt_num argument is the
address of a longword that receives the FDL statement number. If the
routine finishes successfully, the stmnt_num argument
is the number of statements in the FDL specification. If the routine
does not finish successfully, the stmnt_num argument
receives the number of the statement that caused the error. Note that
line numbers and statement numbers are not the same and that an FDL
specification in string form has no "lines."
By default, an error status is returned rather than signaled.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
LIB$_BADBLOADR
|
Bad block address.
|
|
LIB$_BADBLOSIZ
|
Bad block size.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
|
RMS$_DNF
|
Directory not found.
|
|
RMS$_DNR
|
Device not ready or not mounted.
|
|
RMS$_WCC
|
Invalid wildcard context (WCC) value.
|
|
