FAL$LOG

If you issue e.g. a copy command containing a DECnet node name a File Access Listener (FAL) process will startup and produce a netserver.log file in your login directory on the remote node. The amount of information written to this logfile can be influenced using the FAL$LOG logical.

Techninal description

Original Posting to Info-VAX by Glenn Everhart based on information gained by Nick de Smith from the FAL sources

INTRODUCTION TO FAL LOGGING

The following describes the format and use of the FAL logging options which are specified via the logical names FAL$LOG and FAL$OUTPUT. These are normally defined in the user's LOGIN.COM file, but they can be placed in a group or system logical name table to affect a larger class of remote file accesses. FAL$LOG conveys logging and control directives to FAL and FAL$OUTPUT is used to specify the name of the log file to create (in place of SYS$OUTPUT).

NOTE: Use of the logical names FAL$LOG and FAL$OUTPUT by FAL is an UNSUPPORTED feature intended as a diagnostic, debugging, and performance monitoring tool for use by Digital. The format and function of these logical names may change at any time, or perhaps not be used in the future.

NOTE: Logging of information other than file name and statistics (parameter bits 0, 1, and 5) can severly reduce data throughput!!!

SYNTAX RULES

The primary function of the logical name FAL$LOG is to request the logging of various types of information about the file operations performed by FAL. This includes identifying each file accessed, displaying the Data Access Protocol (DAP) messages exchanged, computing data throughput statistics, and logging the logical link and mailbox QIO calls and the subsequent delivery of ASTs. Logging operations are requested via the parameter bitmask value. A secondary use of the logical name is to specify qualifiers that control various aspects of FAL's operation such as determining buffer sizes or disabling features. Currently, the format of the FAL$LOG options string is:


    [parameter][/qualifier-1,...,qualifier-n]

where each qualifier is of the form keyword=value (e.g., /BPM=20).

The parameter and qualifiers are optional. However, the parameter, if present, must precede any qualifiers. In addition, only the first three characters of a qualifier keyword are examined to determine a match. Thus, /DISABLE=xx can be abbreviated to /DIS=xx. Spaces and tabs are ignored and keywords can be be entered using either uppercase or lowercase characters.

PARAMETER VALUES

The parameter is a hexadecimal bitmask used to specify FAL logging options. If this parameter is non-zero (indicating that FAL logging output will be generated), then an attempt is made to translate the logical name FAL$OUTPUT prior to opening the log file. If FAL$OUTPUT is defined, then its equivalence string is used as the file specification of the log file; otherwise logging output is directed to SYS$OUTPUT which normally points to the default network log file named SYS$LOGIN:NETSERVER.LOG. The bitmask definitions for the parameter are as follows:

bit0: enable logging of file name and type of file access requested.
bit1: enable logging of data throughput and other performance statistics.
bit2: enable logging of individual DAP messages as they are processed from the input buffer or assembled in the output buffer
bit3: enable logging of DAP message packet and mailbox AST routine completions.
bit4: enable logging of DAP message packet and mailbox QIO requests.
bit5: enable logging of internal counters.

QUALIFIER VALUES

The following qualifiers are recognized where 'd' denotes a decimal digit and 'x' denotes a hexadecimal digit:

/DISABLE=xx

(Disable FAL Options) where the bitmask value denotes:

bit0: disable DAP level CRC checksum generation and comparison. (Note that CRC checking will be automatically disabled if the initiating node does not support DAP level CRC computation.)
bit1: disable DAP message blocking in both directions (i.e., transmit each DAP message in a separate QIO system service call).
bit2: disable RMS multi-block caching to/from disk when block I/O file transfer mode is in effect. This restores the pre-VMS V3.4 block I/O processing behavior of FAL where each DAP DATA message resulted in one RMS $READ or $WRITE call to be executed. Note also that selection of this option elimimates one MOVC3 copy of the data in memory at the expense of greatly increasing the number of RMS I/O operations performed during a file transfer.
bit3: disable poor-man's (or manual) routing (i.e., have FAL reject any file specification it receives that contains a node name).
bits4-7: undefined.

/ENABLE=xx

(Enable FAL Options) where the bitmask value denotes:
bits0-7 are undefined.

/BPM=ddddd

(Bytes per Message) this is the maximum number of bytes per DAP message to display (used only if parameter bit2 is set). The default value is 20 bytes per message.

/BPL=dd

(Bytes per Line) this is the maximum number of bytes per line to display when dumping a DAP message (used only if parameter bit2 is set). The default value is 20 bytes per line.

/RBK_CACHE=ddd

(RMS Multi-block Cache Size) this controls the number of disk blocks per RMS $READ or $WRITE call to transfer when block I/O file transfer mode is selected (if bit2 of the /DISABLE option is set, this option is ignored). The number can be from 1 to 127. The default is 64.

/DBS=ddddd

(DAP Buffer Size) requests FAL to send this value in the DAP Configuration message for the <BUFSIZ> field.

/SYSTEM_ID=xxxx

(System Identification) requests FAL to send this value in the DAP Configuration message for the <FILESYS><OSTYPE> fields (the OSTYPE field is the low order byte of the value).

/VERSION=xxxxxxxx

(DAP Version Number) requests FAL to send this value in the DAP Configuration message for the <DECVER><USRNUM><ECONUM><VERNUM> fields (the VERNUM field is the low order byte of the value).

/SC1=xxxxxxxx

(System Capabilities Part 1) requests FAL to send this value in the DAP Configuration message for bits <31-00> of the <SYSCAP> field.

/SC2=xxxxxxxx

(System Capabilities Part 2) requests FAL to send this value in the DAP Configuration message for bits <63-32> of the <SYSCAP> field.

Note that any qualifier that cannot be interpreted or that contains an invalid value is ignored and a parse error message is written to the log file.

EXAMPLES

The following DCL commands illustrate how FAL logging options might be setup in one's LOGIN.COM file.

    $ DEFINE FAL$LOG 1

The above command enables the logging of file name and type of access in the default network log file NETSERVER.LOG.

    $ DEFINE FAL$LOG 3
    $ DEFINE FAL$OUTPUT FAL.LOG

This requests the logging of file name, type of acesss, and data throughput statistics in SYS$LOGIN:FAL.LOG.

    $ DEFINE FAL$LOG "3/RBK_CACHE=16/DBS=1056"
    $ DEFINE FAL$OUTPUT work_disk:[testing]statistics.star_to_galaxy

The above definitions are used to gather data throughput statistics in the specified log file while altering buffer sizes.

    $ DEFINE FAL$LOG "7/bpm=80"

This definition causes the first 80 bytes of each DAP message to be dumped and file identification and statistics to be displayed in the log file.

    $ DEFINE FAL$LOG 7_50

Same as the previous example, except the VMS V3.n parameter format of xx_yyyy is used where yyyy is the number of bytes per DAP message to display expressed as a hexadecimal value.

    $ DEFINE FAL$LOG "/DISABLE=8"

This disables poor-man's routing which prevents users from using FAL as a pass-through object on this node.

    $DEFINE FAL$LOG 2F

This enables all FAL logging options excluding qualifier control options.

Example output

The following gives example output for fal$log with values between 1 and 7.

Comments to: Martin P.J. Zinser
Last modified: 20020628