 |
HP OpenVMS Utility Routines Manual
12.3 FDL Routines
This section describes the individual FDL routines.
Note that the fdl_desc and the
default_fdl_desc arguments that are used as part of
these routine calls are character strings that can be either of the
following:
- A string descriptor pointing to a file that contains a specification
- A character string that is the actual specification
For additional details, see the descriptions of the individual routine
calls.
FDL$CREATE
The FDL$CREATE routine creates a file from an FDL specification and
then closes the file.
Format
FDL$CREATE fdl_desc [,filename] [,default_name] [,result_name]
[,fid_block] [,flags] [,stmnt_num] [,retlen] [,sts] [,stv]
[,default_fdl_desc]
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 |
The fdl_desc argument is one of the following:
- A character string descriptor pointing to a file containing the FDL
specification to be parsed
- A character string containing the actual FDL specification
The choice depends on the application making the call. For example, if
the application wants to create data files that are compatible with a
PC application, it might create the following FDL file and name it
TRANSFER.FDL:
FILE
ORGANIZATION sequential
RECORD
FORMAT stream_lf
|
The application could then include the address of the FDL file as the
fdl_desc argument to the FDL$PARSE call:
call fdl$parse transfer.fdl ,...
|
Optionally, the application might code the FDL specification itself
into the call using a quoted character string as the
fdl_desc argument:
call fdl$parse "FILE; ORG SEQ; FORMAT STREAM_LF;" ,...
|
Note that directly including the FDL specification into the call
requires you to do the following:
- Enclose the fdl_desc argument in quotation marks
- Use a semicolon to delimit statements within the
fdl_desc argument
- Assign the symbol FDL$M_FDL_STRING as the flags
mask value
filename
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor---fixed-length string descriptor |
Name of the OpenVMS RMS file to be created using the FDL specification.
The filename argument is the address of a character
string descriptor pointing to the RMS file name. This name overrides
the default_name parameter given in the FDL
specification.
default_name
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor---fixed-length string descriptor |
Default name of the file to be created using the FDL specification. The
default_name argument is the address of a character
string descriptor pointing to the default file name. This name
overrides any name given in the FDL specification.
result_name
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor---fixed-length string descriptor |
Resultant name of the file created by FDL$CREATE. The
result_name argument is the address of a character
string descriptor that receives the resultant file name.
fid_block
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
File identification of the RMS file created by FDL$CREATE. The
fid_block argument is the address of an array of
longwords that receives the RMS file identification information. The
first longword contains the FID_NUM, the second contains the FID_SEQ,
and the third contains the FID_RVN. They have the following definitions:
|
FID_NUM
|
The location of the file on the disk. Its value can range from
1 up to the number of files the disk can hold.
|
|
FID_SEQ
|
The file sequence number, which is the number of times the file number
has been used.
|
|
FID_RVN
|
The relative volume number, which is the volume number of the volume on
which the file is stored. If the file is not stored on a volume set,
the relative volume number is
0.
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Flags (or masks) that control how the fdl_desc
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 0, no flags are set. The following table shows the flags and their
meanings:
| Flag |
Function |
|
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
|
Returns the
RESULT_NAME using the long result name from a long
name access block (NAML). By default, the
RESULT_NAME 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.
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."
retlen
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of characters returned in the result_name
argument. The retlen argument is the address of a
longword that receives this number.
sts
| OpenVMS usage: |
longword_unsigned |
| type: |
longword_unsigned |
| access: |
write only |
| mechanism: |
by reference |
RMS status value FAB$L_STS. The sts argument is the
address of a longword that receives the status value FAB$L_STS from the
$CREATE system service.
stv
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
RMS status value FAB$L_STV. The stv argument is the
address of a longword that receives the status value FAB$L_STV from the
$CREATE system service.
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 one of the following:
- A character string descriptor pointing to a file containing the
default FDL specification to be parsed
- A character string containing the actual default FDL specification
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
|
RMS$_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.
|
|
