Here's something I prepared earlier... Absolutely no responsibility for anything at all is accepted, and PLEASE note the caveats about system performance... Nick de Smith, 04-January-1994 nick NICK@NCDLAB.ULCC.AC.UK (preferred) nick@nick01.demon.co.uk (if you must) European DECUS OpenVMS Chairman Introduction to FAL logging --------------------------- This document is extracted from the VMS listings CDs (updated to V5.5-2). The following describes the format and use of 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 access. 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 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 type 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 subsequent delivery of ASTs. Logging operations are requested through the parameter bitmask value. A secondry use of the logical name is to specify qualifiers the 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 entered using either upper or lower case 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 will be made to translate the logical name SYS$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: <0> Enable logging of file name and type of file access requested. <1> Enable logging of data throughput and other performance statistics. <2> Enable logging of individual DAP messages are they are processed from the input buffer or assembled in the output buffer. <3> Enable logging of DAP message packet and mailbox AST routine completions. <4> Enable logging of DAP message packet and mailbox QIO requests. <5> Enable logging of internal counters. Qualifier values ---------------- The following qualifiers are recognised, where 'd' denotes a decimal digit and 'x' denotes a hexadecimal digit: /DISABLE=xx (Disable FAL Options) where the bitmask value denotes: <0> 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 generation. <1> Disable DAP level message blocking in both directions. i.e. Transmit each DAP message in a separate QIO system service call. <2> 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 behaviour 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 eliminates one MOVC5 copy of the data in memory at the expense of greatly increasing the number of RMS I/O operations performed during file transfer. <3> Disable poor-man's routing. i.e. have FAL reject any file specification it receives that contains a node name. <4> Disable parsing of the requested file name or resultant file name before it is sent to the log file. <5..7> Undefined. /ENABLE=xx (Enable FAL Options) where the bitmask value denotes: <0..7> Undefined. /BPM=ddddd (Bytes Per Message) This is the maximum number of bytes per DAP message to display (used only if parameter bit <2> 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 bit <2> 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 bit <2> 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 field. /SYSTEM_ID=xxxx (System Identification) Requests FAL to send this value in the DAP configuration message for the 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 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 <0..31> of the field. /SC2=xxxxxxxx (System Capabilities Part 2) Requests FAL to send this value in the DAP configuration message for bits <32..63> of the 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 may be set up in one's LOGIN.COM file. $ ASSIGN 1 FAL$LOG The above command enables the logging of file name and type of access in the default network log file NETSERVER.LOG. $ ASSIGN 3 FAL$LOG $ ASSIGN FAL.LOG FAL$OUTPUT This requests logging of file name, type of access, and data throughput statistics in SYS$LOGIN:FAL.LOG. $ ASSIGN "3/RBK_CACHE=16/DBS=1056" FAL$LOG $ ASSIGN some-file-name FAL$OUTPUT The above definitions are used to gather data throughput statistics in the specified log file while altering buffer sizes. $ ASSIGN "7/bpm=80" FAL$LOG 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. $ ASSIGN 7_50 FAL$LOG 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. $ ASSIGN "/DISABLE=8" FAL$LOG This disables poor-man's routing which prevents users from using FAL as a pass-through object on this node. $ ASSIGN "2F" FAL$LOG This enables all FAL logging options excluding qualifier control options. [end]