FDL Routines
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help FDL Routines *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
The FDL routines perform many of the functions of the File
Definition Language that define file characteristics.
| 1 - 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]
1.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.
1.2 - 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:
o A character string descriptor pointing to a file containing
the FDL specification to be parsed
o 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:
o Enclose the fdl_desc argument in quotation marks
o Use a semicolon to delimit statements within the fdl_desc
argument
o 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_ The location of the file on the disk. Its value can
NUM range from 1 up to the number of files the disk can
hold.
FID_ The file sequence number, which is the number of times
SEQ the file number has been used.
FID_ The relative volume number, which is the volume number
RVN 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_ Interprets the fdl_desc argument as an FDL
STRING specification in string form. By default, the
fdl_desc argument is interpreted as the file
name of an FDL file.
FDL$V_LONG_ Returns the RESULT_NAME using the long result
NAMES 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:
o A character string descriptor pointing to a file containing
the default FDL specification to be parsed
o 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.
1.3 - 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
SpecificatAdvantages Disadvantages
FDL Variability; for File must be in default directory.
file example, if the Slower.
specification
changes
regularly, you
can revise the
file without
revising the
calling program.
Character You do not have Program must be recoded to change
string to be concerned FDL specification.
with locating a
file.
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.
1.4 - 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.
| 2 - 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]
2.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.2 - 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_ Interprets the fdl_str_dst argument as an FDL
STRING specification in string form. By default, the
fdl_str_dst argument is interpreted as the file
name of an FDL file.
FDL$V_FULL_ Includes the FDL attributes to describe all
OUTPUT 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_ Returns the FDL_FILE_RESNAME using the long
NAMES 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.
2.3 - 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.
| 3 - 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]
3.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.
3.2 - 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.
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_ Interprets the default_fdl_desc argument
STRING 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.
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.
3.3 - 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.
| 4 - FDL$RELEASE |
The FDL$RELEASE routine deallocates the virtual memory used by
the OpenVMS RMS control blocks created by FDL$PARSE. You must
use FDL$PARSE to populate the control blocks if you plan to
deallocate memory later with FDL$RELEASE.
Format
FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags]
[,badblk_addr]
4.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.
4.2 - Arguments
fab_pointer
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
File access block (FAB) to be deallocated using the LIB$FREE_VM
routine. The fab_pointer argument is the address of a longword
containing the address of the FAB. The FAB must be the same one
returned by the FDL$PARSE routine. Any name blocks (NAMs) and
extended attribute blocks (XABs) connected to the FAB are also
released.
If you omit this argument or specify it as zero, the FAB (and any
associated NAMs and XABs) is not released.
rab_pointer
OpenVMS usage:address
type: longword (unsigned)
access: read only
mechanism: by reference
Record access block (RAB) to be deallocated using the LIB$FREE_
VM system service. The rab_pointer argument is the address of a
longword containing the address of the RAB. The address of the
RAB must be the same one returned by the FDL$PARSE routine. Any
XABs connected to the RAB are also released.
If you omit this argument or specify it as zero, the RAB (and any
associated XABs) is not released.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flag (or mask) that controls how errors are signaled. The flags
argument is the address of a longword containing the control flag
(or a mask). If you omit this argument or specify it as zero, no
flag is set. The flag is defined as follows:
FDL$V_ Signals any error. By default, the status code is
SIGNAL returned to the calling image.
FDL$V_LONG_ Deallocates any virtual memory used for a long
NAMES name access block (NAML) created by the FDL$PARSE
routine.
This flag is valid for OpenVMS Alpha only.
badblk_addr
OpenVMS usage:address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of an invalid RMS control block. The badblk_addr argument
is the address of a longword that receives the address of an
invalid control block. If an invalid control block (a fatal
error) is detected, this argument is returned; otherwise, it
is ignored.
4.3 - Condition Values Returned
SS$_NORMAL Normal successful completion.
FDL$_INVBLK Invalid RMS control block at virtual address
'hex-offset'.
LIB$_BADBLOADR Bad block address.
RMS$_ACT File activity precludes operation.
RMS$_RNL Record not locked.
RMS$_RSA Record stream currently active.
SS$_ACCVIO Access violation.
|
|
