Amiga MA Magazine 1998 #3/amigamamagazinepolishissue1998.iso/bazy/config_server/doc/config-server.doc

Text File | 1995-02-12 | 13KB | 309 lines

(Internal note: An HTML based version of this file will be written.  I'm
 only medium-warm about AmigaGuide, compared with HTML, and if no good
 HTML/WWW browser is written for the Amiga, I will eventually do one for my
 tastes.  `Good' == Full support for v2.x of the Amiga OS, and independant
 of the massive MUI junk that a known (but not-so-good) Amiga HTML browser
 uses.  I have nothing against MUI, except that it's huge, even larger than
 most applications that use it.  Worse, the first "requires MUI" program I
 used was a _miniscule_ "login" program for muFS, a program which has
 little reason for using _any_ GUI, much less the monstrous MUI.

 Suffice to say I'm massively turned off on MUI.  (^&

 (ramble) )


Config-server uses/maintains a configuration database.

General copyright, disclaimer, license:
    The general "legal.doc" file applies, EXCEPT with regard to modifying
    config-server:

    As far as customization of config-server is concerned...  I don't
    object to your customizing it for your needs.  However, since the vain
    hope is that config-server can act as a "standard" configuration tool,
    I ask that no one else use the "config-server" name for a message port
    or software program/title.  If you do a better job of writing a similar
    tool, then we can all unmistakably migrate to that; if you don't
    materially improve things, it would be a bad idea for us to step on one
    anothers' toes, obviously.

A sample config-server database is provided (env/config-server.config).
Copy this to env: and envarc: on your system before starting config-server.
The sample entries show some of the flexibility of config-server.  The
entries for Indra's Net tools (IndraSMTPd, etc.) are quasi-real.  Something
like each will be used my my Indra's Net pieces (beads? nodes?), but as the
sample config file was written before the pieces/beads/nodes were ready to
use config-server, the names were just "tossed out".  Now that I have a
servicable config-editor for config-server, I am ready to begin making the
pieces of software _use_ config-server, and the names of some of the tags
may change...  Regardless, the sample database gives you some idea of how
config-server can be used.

On-disk, the database has the form of lines of text.  Due to a flaw of
ARexx, lines cannot exceed 1000 characters in length.  The format of the
lines is:
    <application>:<encoding>:<tag>:<value>

 ** <application> is the name of a program that is at issue.  An "umbrella"
    configuration set may be explicitly used by applications.  E.g., if I
    write a suite of programs to send and receive Internet mail and Usenet
    news, many of the configuration options may be the same...but some
    application-specific details may vary (or I may wish to turn up the
    log-detail on ONE of the programs without affecting the others).

 ** <encoding> indicates the way in which the <value> data is encoded.
    There are several encoding forms:

        text        Plain ASCII.
        hex         Hexadecimal rep. of the raw data.
        env         Global ENV: var.
        var         Private Shell var.
        file        Specified file.
        cliplist    A member of the ARexx cliplist is indicated.
        command     A command who's output to capture.

    ...NOTE that Shell "private" variables are of limited value when you
    have config-server evaluate them.  In fact, I can think of NO practical
    value for having config-server do so, since config-server, written in
    ARexx, cannot meaningfully use Shell variables.  HOWEVER, they serve as
    place-holders so that single- and double-asterisk prefixed versions
    (*var, **var) will be standard.

    Use a single asterisk prefix (*var, *command, etc.), if you want the
    <encoding> to pass through to the application (this may be useful for
    expressions or local shell variables).

    Use a double-asterisk prefix (**var, **command, etc.) for encodings
    that you wish to be evaluated EACH TIME THE VALUE IS USED.  This may be
    useful if you wish to include a "fortune cookie" message in a
    signature, for example, and so you wish the application to run the
    program for every message you write.

    If you wish to use a custom format, I would suggest a triple-asterisk
    (***) prefix.  Such an encoding may mean anything you wish it to mean.

    config-server reserves the right to add new encoding types, and to
    expect the "standard" single- and double-asterisk prefixes to be safely
    applicable to all of them, with the standard meaning.  Unknown
    encoding types that don't begin with at least one asterisk for a prefix
    will have extra "junk" tacked onto the front -- this will render such
    encodings useless, and will hopefully discourage anyone planning such.


 ** <tag> is an indication of the interpretation of the included data in
    the database.  The definition and interpretation of most <tag>'s will
    be up to the application.  Several standard <tag>s are defined:

        comment    used for user-info
        comments   (internal)
        version    used for knowing which version of software last run

    Enumerated tags (i.e., when you are talking about JUST ONE PARTICULAR
    instance of a tag) should end with .<N> where <N> is the numbered
    version you are interested in.  (All tags are implicitly numbered; if
    you don't enumerate a tag, then the config-server will "work at the
    end" (creating a new highest-<N>, or returning the current highest-<N>,
    as the case may be).

    Pluralized tags (i.e., where you want to talk about ALL of the tags at
    once -- normally to retrieve a count of how many tags are available)
    always end with a 'S.  (E.g., COMMENT'S or SIGNATURE'S.)

    Each "standard <tag>" will NOT begin with an asterisk (*) to avoid
    trompling, and being trompled by, application-specific <tag>'s. This
    also means that application-specific <tag>'s MUST start with asterisks.

 ** <value> is the information that, when decoding by the config-server
    according to the <encoding> will provide the raw data that the
    application is looking for.

General usage:
    Use ADDATTR <app>':'<enc>':'<tag>':'<val> to add a quadruple.

    Use GETATTR APPS to get a colon-delimited list of applications.
        (Prefix of 'TEXT' (encoding) + ':' is added.)

    Use GETATTR TAGS <app> to get a colon-delimited tag-list for <app>.
        (Prefix of 'TEXT' (encoding) + ':' is added.)

    Use GETATTR TAG <app>':'<tag> to get the "raw" <value> of a tag.
        (result: <encoding>':'<value>; <encoding> is never resolved for
         you.)

        (NOTE: if you use a 'S suffix on the <tag>, you should be told the
         number of times that the "base" <tag> occurs.  E.g., if you ask
         for "my-app:comment's", you will be told how many COMMENT tags
         occur for MY-APP.  This value MAY BE a null-string ('') if no
         occurances of the given <tag> exist.)

        (NOTE: If you use a .<n> suffix on the <tag>, you will be given the
         Nth occurance of that tag for the <app>.  E.g., if you ask for
         "my-app:comment.1" you will be given the first COMMENT.)

        (NOTE: If you give no .<n> NOR 'S suffix, the config-server will
         first try adding a 'S to the end to get an occurance-count, then
         will use a .<count> to return the LAST occurance of that config
         tag.  E.g., if you ask for 'my-app:comment', you will be given the
         _last_ COMMENT in the database for MY-APP.

    Use GETATTR VAL <app>':'<tag> to get the "real" <value>.
        (SEE result: and NOTE:'s for GETATTR TAG, above.)

    Use HELP to get a help-string.

    Use QUIT to cause the config-server to exit.

    Use RELOAD to cause config-server to re-read the config file.
        (Aliases: NEW, CLEAR, OPEN (allow OPEN to read an alternative
         config?)

    Use REMATTR to cause config-server to remove an <app> or a <tag>.
        (If <tag> is pluralized, then all instances of <tag> are removed.)

        (If <tag> has a .<N> form, then that <tag>-instance is removed, and
         other instances of that <tag> are moved down by one.)

        (If <tag> is neither pluralized ('S) nor enumerated (.<N>), then
         a default enumeration of the LAST instance of <tag> is used.)

    Use SAVE to cause config-server to save its database.

Results:
    All commands return results of some sort, unless there was an error
    (and some return success/failure indicators in RESULT rather than an
    error-code/-level in RC).

    RESULT strings generally have the form:

        <encoding>:<rest>

    ...however, this format isn't always appropriate (e.g., in a GETATTR
    TAG command, the format should always be presentable as TEXT:, and an
    "inner encoding" is given anyway.

    I'm interested in comments on this.

    Generally, this is a moot point; you will be interested in the results
    of a GETATTR, whose format is assured to be in this format already.

RESTRICTIONS:
    Restrictions can be divided into two sets: Those intrinsic to the way
    the config-server config data file and ARexx commands are parsed, and
    those that are to avoid undue bother for end-users. The latter may be
    because a user may opt to edit a file with a text editor (which may
    freely convert between TAB's and SPACE's and/or truncate trailing
    spaces on lines, for example), or it may be something which, if you
    manage to make it work, may prove difficult to maintain, and which I
    may not expend great effort ensuring continued support for.

    Intrinsic limitations are:
     ** The <value> data can be DEcoded to contain essentially anything
        that will fit in an ARexx string for returning to the caller. The
        ENcoded version (which is the same as the decoded, for "text"
        <encoding>'s) cannot contain EOL's.  If fields are not "plain
        text", or need to include colons or EOL's, then the fields should
        be encoded as hex, or indirected through a file.

     ** <tag> values should not contain dots (.), apostrophes ('), colons
        (:), or EOL's.

     ** The other fields must not contain EOL's or colons.

    To be nice to users (and/or yourself):
     ** Except for the <value> string, embeded, leading, and trailing
        spaces are strongly discouraged (but it's possible they may work,
        if you are very careful).

     ** In <value> strings, if you use spaces to delimit sub-fields (as
        opposed to actually considering spaces as intrinsic components of
        the data), try to be liberal in your definition of "space". A
        "space" may be a single ASCII <Space> character (hex code 20), or
        it maybe a <Tab> (09), or 5 <Tab>'s, 3 <Space>'s, and another
        <Tab>.

     ** Use of control-characters other than the ASCII LineFeed (EOL) is
        permitted in any field, but probably is a bad idea.

Global variable worth noting (of interest ONLY to people who want to
modify config-server's behavior):
    CONFIG_FILE
        Contains the name (sans path) of the file to use for
        config-server's database.  'ENV:' is prefixed onto the name for
        READING.  Both 'ENV:' and 'ENVARC:' are prefixed onto the name for
        WRITING.

        (NOTE: Suggest a better place for this file than ENV:/ENVARC:?)

        This is used for readingand writing the database file, and so is
        only needed by a couple of functions.

    CONFIGS.
     ** This root/stem variable holds the database in-memory.  This is used
        extensively.


     ** It is organized like so:

            CONFIGS.<app>':'<tag>

        ...where <app> and <tag> are forced to upper-case to avoid
        case-sensitivity problems.  (Trying to be case-aware for this, in
        ARexx, is difficult...for this, and other reasons, I may re-write
        config-server in C eventually.)

        <app>':'<tag> can be considered, together, as an <app-tag>


     ** To determine all app's available available, use the <app-tag> for
        'config-server:applications'.  This will return:

            <encoding>':'<tag-list>

        As with all other automatically maitained and generated tag sets,
        the <encoding> for `config-server:applications' will always be
        `TEXT', so you may strip off the `TEXT:' prefix and use the value
        directly.

        You may then use the resulting <tag-list>, parsing by colons, to
        get each app-name.

        (Note, this duplicates the GETATTR APPS command.)


     ** To get a list of tags for a given application, you use the app-tag
        of:

            <app>":TAG'S"

        ...which will return:

            "TEXT:"<tag-list>

        You can then parse <tag-list> as a colon-delimited field.

        (Note, this duplicates the GETATTR TAGS command.)


     ** To get the "raw" value of a config entry (e.g., the filename or
        env-var-name that the config-server keeps track of internally), use
        the app-tag of:

            <app>':'<tag>'.'<N>

        ...where <N> is the occurance-number you want to access (each tag
        may appear any number of times).  To find out how many time's a
        given <tag> occurs for a given <app>, use:

            <app>':'<tag>"'S"

        ...these return

            <encoding>':'<tag-list>
            'TEXT:'<count>

        ...repsectively.

        (Note, these duplicate GETATTR TAG more or less.)