HELPLIB.HLB  —  FDL Routines
    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

    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.

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. 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 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. 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.

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.
Close Help