! Help for SP
! Edit	Edit Date	By	Why
!  01	15-Aug-86	NMdS	First attempt
!
1 SP (Set Privileges)
SP is used to manipulate the privilege bits for the executing process. 
SP is very felixible (probably overly so) but it provides a nice example of a
simple parser for its commands, and examples of many system services in C. 

Format
 $ Sp == "$Atg$Tools:Sp"
 $ Sp [priv-list] [sp-logical]
!
2 priv-list
Syntax:
 priv-list   := [no | -] priv-item [,priv-list]
                (A list of names)
 priv-item   := . | # | [.] priv-token | _ priv-name
                ("." as a prefix means "noall,priv_token")
 priv-token  := priv-name | sp-logical | vms-logical
                (An SP special name, VMS privilege or VMS/SP logical)
 priv-name   := ALL | CMKRNL | CMEXEC | SYSNAM | GRPNAM ...
                (A VMS prililege name)
 sp-logical  := name-char [sp-logical]
                (An SP logical name)
 vms-logical := name-char [vms-logical]
                (A VMS logical. Translates to "priv-list")
 name-char   := 0..9 | A..Z | $ | _
                (VMS logical name characters)
3 "." (LAST or ONLY)
"."     as a token means use last set of privileges set by SP.
        "." is internally translated to "LAST", which is the name
        SP uses for the last set of privileges active.
        "." as a token is treated as having an implicit "noall" prefix.
        "-." and "no." have the same effect as ".".
"."     as a prefix to a token means set ONLY those privileges specified
        by the token. It may be considered as an implicit "noall".
        ie. ".token" means "noall,token". If "." is not used as a prefix
        the "token" is "or"ed into the current set of privileges.
3 "#" (LOGIN privileges)
"#"     means use the authorised privileges, ie. the process's "LOGIN"
        privileges. "#" is treated as having an implicit "noall" prefix.
        "-#"/"no#" has the same effect as "#".
3 "_" (LITERAL)
"_"     as a prefix to a name means use the name literally, ie. do not
        try to perform VMS or SP logical name translation on the following
        token. 
3 priv-name
any unique subset of a a VMS privilege name will be accepted as an abbreviation
of that name. No abbreviations are allowed for SP or VMS logical names. 
3 sp-logical
See the discussion on sp-logical one level up from this help message.
3 vms-logical
VMS logicals may be used to assign commonly used strings to a logical name. The
SP command parser will translate a VMS logical, and recurse attempting to treat
the translation as part or all of an SP command. No recursion is therefore
allowed in VMS logicals given to SP. A negation request on a VMS logical
(prefix of "-" or "NO") is ignored. If you want to be really nasty, a VMS
logical can reference SP logicals (why?). eg.

$ Assign "group,bypass" grp
$ Sp grp,world			! Set GROUP,BYPASS and WORLD
!
2 sp-logical
sp-logical  := name-char [sp-logical]
               (An SP logical name)
name-char   := 0..9 | A..Z | $ | _
               (VMS logical name characters)

SP logicals are stored in the process logical name table with a prefix
(normally as SP$$name). This method of storage usually prevents conflicts with
other programs logicals. You only specify the "name" part. eg. "FRED" (without
the "SP$$"). The SP logical "LAST" is used to hold the bitmap of the set of
privileges active before the last invokation of SP. This SP logical is normally
referenced as "." (see above). The value of "LAST" is only changed if the
invokation of SP changes the current privileges. SP logicals translate to
bitmaps of privileges and are therefore not subject to recursion in the parser.
!
2 Qualifiers
/e (Examine)
Examine the contents of an SP logical. eg.

$ Sp/e last		! See what our last set of privileges were (or Sp/e .)
/q (Quiet)
Set "quiet" mode (No "Changes: xx" text).
/b (Build masks)
Just build masks and set name (do not change privs).
The "/b" qualifier may be used to set up SP type logicals without
disturbing the current environment, eg.

$! Set "GROPE" to mean "login privs plus GROUP and BYPASS"
$! (/b flag ensures that the current privileges do not change)
$!
$ Sp/b #,group,bypass grope

It is much more efficient to use the "/b" flag to build bitmaps of required
logicals than to use VMS logicals. Normally the "/b" construct is used
in LOGIN command files. 
!
2 Examples
$ Sp                               show current settings
$ Sp cmexec,bypass,nogroup         set CMEXEC and BYPASS privileges,
                                   clear GROUP privilege
$ Sp cmexec,bypass,nogroup priv_a  as above, but save state in PRIV_A
$ Sp "" priv_b                     as above, just save current as PRIV_B
$ Sp #          (or $ Sp#)         return to "LOGIN" settings
$ Sp .          (or $ Sp.)         return to "LAST" settings
$ Sp priv_a                        set those privileges in PRIV_A
                                   (add to current privilege settings)
$ Sp .priv_b                       set just those privileges in PRIV_B
                                   (same as "noall,priv_b")
$ Sp #,priv_a priv_c               set privs to login privs
                                   plus privs active at PRIV_A above, then
                                   set PRIV_C to the new current privs.
!
2 Notes
Logical name translation depth is limited to 10.
No recursion in VMS logical names is allowed!
Privilege names in the above examples can be prefixed by "NO" or "-" in order
to turn off that bit. SP type logicals may be negated by using a prefix of
"NO" or "-". 
Ordinary VMS logicals can be prefixed by "NO" or "-", but the negation request
is ignored. eg. "NOGRP" has the same effect as "GRP" 
Priority of translation is SP logical, VMS logical, Priv name. eg.

$ Sp/b #,group,bypass world

would change the effect of "WORLD" to meaning "set only login privileges plus
GROUP and BYPASS". Note that this only works for SP logicals, as recursion of
names in VMS logicals is not allowed. You may use "_WORLD" to refer to WORLD
privilege on its own. eg. (using the above example) 

$ Sp world            ! Set login privs plus GROUP and BYPASS
$ Sp _world           ! Set only WORLD privilege
!
