[PREVIOUS CHAPTER] [NEXT CHAPTER]

7 FML internal data structures

    Here we describe FML internal data structures. When you hacks FML,
    this knowledge is required. However you do not need to read this
    chapter if you toggle variables only on/off.

    7.1	Naming convention of variables

    * ^[A-Z0-9_]+$ name variable is USER DEFINED VARIABLE for customize.
    It is a global variable. Fundamentally these variables are defined in
    config.ph, sitedef.ph and site_init.ph.

    	Example:	$MAIL_LIST

    * Capitals are global not for USERS but for systems. In principle
      users should not touch them. If you hacks, it must require to handle
      these variable.

    	$MailBody	$Reply_to
    	%Envelope	*_cf

       %Envelope is the most important variable. We should not increase
       the number of global variables. Several variables e.g. @Fld
       are capital but historically left not as global.

      ATTENTION: historically $debug is global for convenience.

    * Lower case word is local variable.

    [Appendix]
    Directory variables consists of two types

    	$*_DIR 		relative path to $DIR
    	$FP_*_DIR 	obsolete path

    $FP_*_DIR is automatically defined based on directory variables.
    In a lot cases absolute path is used.

    	$FP_TMP_DIR
    	$FP_VARDB_DIR
    	$FP_VARLOG_DIR
    	$FP_VARRUN_DIR
    	$FP_VAR_DIR
        	$FP_SPOOL_DIR

    7.2	Naming convention of functions

    Except for a few cases, a function name is capitalized. The word after
    "_" is also capitalized. It is similar to X11 style:D

    * Some exceptions remains after fml 1.5.

    File operation functions are defined as

    	f_function_name 	conversion interface

    	Cnstr_function_name		constructor for this mode
    	Destr_function_name		destructor for this mode

    These are exceptional. In that age I should replace these naming
    convention but still remains ;D

    7.3	%Envelope (hash)

    %Envelope is most important variable(hash). %Envelope contains header,
    each field of the header, body as a hash table. This hash is passed in
    a lot of function calls. It is similar to sendmail's struct ENVELOPE
    e;

    In the age of FML 1.5, perl 5 does not run. Hence we cannot use
    e.g. the following style

    	$Envelope->$Header->$From = "uja@domain";

    It is represented by

    	$Envelope{"h:From:"}  = "uja@domain";

    ":" is a separator. From: is a special syntax to identify this key is
    a field.

    Keys of %Envelope:

    	KEY beginning with "h:" is a field of a header.

    	h:Capital:	adjusted field data to use in delivery e.g. h:Subject:
    	h:lower-case:	original field data e.g. h:subject:

    	h:field:	header field
    			lower case name is original
    			Capital is after changed.

    	fh:field:	enforce a field to use this value

    	oh:field:	enforce fml.pl to use original field value
    			for this field

    	GH:field:	enforce some value for field of command mail results
    			and so on. used in GenerateHeader().

    			reply-to: > From:

    	Addr2Reply:	address to send a command result and so on

    	[mode or method configurations]

    	macro:x		corresponds to $x of sendmail

    	mode:x		mode x is enabled.

    	mci:mailer	Mail Connection Information
    			mci:mailer is ipc or prog.

    	[Internal Data]

    	Header		original header
    	Body		original mail body
    	Hdr		header of sending mails out in distribute phase

    	message		message to send back to a sender
    			for command results and others
    	error		error message to send back to a sender

    	MIME		ISO-2022-JP is detected (toggle Flag)
    	UnixFrom	Unix From

    	MIME		ISO-2022-JP is detected (toggle Flag)
    	UnixFrom	Unix From
    	Hdr2add		buffer when $SUPERFLUOUS_HEADER is set.
    	nclines		number of lines for "# command" style lines
    	nlines		lines of mail body
    	preamble	preamble to put on mail body
    	trailer		trailer to put on mail body

    	tmp:x		temporary used

    Example: Subject:

       $Envelope{'h:subject:'} is
       an in-coming mail's original Subject: field value.

       $Envelope{'h:Subject:'} is after cutting Re:'s and tags e.g. [Elena 100].

    Example: In a header of distribution, used key of %Envelop is as follow:

            Field           key in %Envelope
    	---------------------------------------
    	Date: 		h:Date:
    	From:		h:From:
    	To: 		h:To:
    	Subject: 	h:Subject:

    7.4	Initialize data structures

    Initialization of fml.pl is as follows:

    	initialize $DIR $LIBDIR @INC and so on

    	&InitConfig
    	   &SetDefaults
    		%Envelope
    		DNS, @HdrFieldsOrder, and others

    	   &LoadConfig
    		$DIR/config.ph
    		sitedef.ph

       	   &SetOpts
    		command line options

    	   COMPATIBILITY CODE

    	&Parse

    	&Parse
    		reset %Envelope

    	&GetFieldsFromHeader

    	&GetFieldsFromHeader
    		analyze %Envelope and set h:field: and h:Field: up.

    	&FixHeaderFields

    	&FixHeaderFields
    		adjust h:Field:

    	&CheckCurrentProc

    	&CheckCurrentProc
    		adjust fields, check loops, modes and so on

    	After this fml.pl sets in the main routine,
    	hooks are evaluated in several locations.

    	Example:
    		$START_HOOK
    		$SMTP_OPEN_HOOK
    		$FML_EXIT_HOOK

    After this, the critical section begins.

    7.5	Directory variables

    [Directory variable list]

    		$DIR @INC(original) $LIBDIR ...

    	$DIR

    	$DIR
    		config.ph location. ML's HOME directory.
    		The argument of @INC.

    	$LIBDIR
    		library paths. @LIBDIR is a list of $LIBDIR's.
    		fml pushes $LIBDIR to @LIBDIR.
    		fml searches @LIBDIR for executable and libraries

        	$SPOOL_DIR		$DIR/spool

        	$SPOOL_DIR		$DIR/spool
    		spool of articles of ML

    	[Relative path from $DIR]

    	$TMP_DIR		tmp (temporary)
    	$VARDB_DIR		var/db  (database, 4.4BSD like)
    	$VARLOG_DIR		var/log (log, 4.4BSD like)
    				$DIR/log is exceptional for backward
    				compatibility.
    				($VARLOG_DIR/log is preferable)
    	$VARRUN_DIR		var/run (4.4BSD like)
    				pid's file and several caches
    	$VAR_DIR		var (4.4BSD like)

    	[Corresponding fully pathed directory variables]

    	$FP_TMP_DIR		$DIR/$TMP_DIR
    	$FP_VARDB_DIR		$DIR/$VARDB_DIR
    	$FP_VARLOG_DIR		$DIR/$VARLOG_DIR
    	$FP_VARRUN_DIR		$DIR/$VARRUN_DIR
    	$FP_VAR_DIR		$DIR/$VAR_DIR
        	$FP_SPOOL_DIR		$DIR/$SPOOL_DIR

    7.6	On temporary directory ($TMP_DIR)

    $DIR/tmp is temporary working area. It is defined as $TMP_DIR. We
    should not use the system's /tmp or /var/tmp if the file is left when
    OS crashes.

    7.7	Configuration files

    [Member Lists]

    	$MEMBER_LIST 	 	$DIR/members

    	the ML member list for authentication. If a given address is
    	not in this list, fml.pl does not authenticate the
    	address. This is not a delivery list in non automatically
    	registration mode. In automatic registration mode, this file
    	is both a member and delivery list.

    	$ACTIVE_LIST 		$DIR/actives

    	list of distribution in non automatically registration mode.

    	$REJECT_ADDR_LIST	$DIR/spamlist

    	list to reject as a spammer.

    [files of guides and so on]

    	$OBJECTIVE_FILE	 	$DIR/objective

    	objective of ML

    	$GUIDE_FILE		$DIR/guide

    	guide for general people (for not member)

    	$HELP_FILE	 	$DIR/help

    	help file of ML (for only member)

    	$DENY_FILE	 	$DIR/deny

    	file to send back when fml.pl rejects mail from a non member.
    	This is not used in auto registration mode.

    	$WELCOME_FILE	 	$DIR/guide

    	file to send back in auto-registration mode when
    	a user is automatically registered.

    	$CONFIRMATION_FILE       $DIR/confirm

    	confirmation file in auto-registration mode.
    	Please see confirmation (../how_to_subscribe 5.9).

    [Logfiles]

    	$LOGFILE	 	$DIR/log

    	log file

    	$MGET_LOGFILE    	$DIR/log

    	mget log. In default $MGET_LOGFILE == $LOGFILE.

    	$SMTPLOG		$VARLOG_DIR/_smtplog

    	Log of SMTP (for debug).

    	$SUMMARY_FILE 	 	$DIR/summary

    	summary of ML

    	$SEQUENCE_FILE 	 	$DIR/seq

    	ML's sequence number

    	$MSEND_RC		$VARLOG_DIR/msendrc

    	digest control file.

    	$LOCK_FILE	 	$VARRUN_DIR/lockfile.v7

    	lock file when not flock(2) lock but link(2) based.

    	$LOG_MESSAGE_ID		$VARRUN_DIR/msgidcache

    	Message-Id cache file to prevent loops.

    	$MESSAGE_ID_CACHE_BUFSIZE

    	Message-ID cache file size

    	$INDEX_FILE		$DIR/index

    	Fml.pl works without this file. If exists, "index" commands
    	sends back this file. If not, FML scans $SPOOL_DIR,
    	@ARCHIVE_DIR and sends back the summary.

    7.8	Other useful variables

    	$DO_NOTHING

    	Special flag to declare "do nothing".

    	$NULL

    	dummy:D like "#define null (char *)0".

    	$FML

    	process table name

    	$FACE_MARK

    	e.g. 	P(^^)
    		Be seeing you P(^^)

    	appended in the reply message, e.g. command results.

    	$INCLUDE_SIM_PATH

    	Please ignore this. This is used in simulation.

    	$UNISTD

    	Declare "Unix Standard" flag. undefined on Windows NT4

    	$LOCKFILE

    	lock file variable in some libraries. It may be uncontrolled
    	by a user.

    	%MAKE_FML

    Please not touch %MAKE_FML in config.ph which variable "makefml" uses
    though it is not used today.

    * obsolete variables (renamed to)

       $GUIDE_REQUEST	-> $GuideRequest
       $RPG_ML_FORM_FLAG	-> $COMMAND_SYNTAX_EXTENSION

    * obsolete

       $NON_PORTABILITY

    7.9	Listing variables list

    To dump variable used in fml.pl (by dumpvar.pl), sets

    	$DUMPVAR = 1;

    FYI: fmlserv.pl uses the same technique to switch name spaces.

[PREVIOUS CHAPTER] [NEXT CHAPTER]