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.

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.

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.

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.

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.

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.

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.

Contents

Index

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor---fixed-length string descriptor

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

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.

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

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.

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference