DP Tool Club 17/CD_ASCQ_17_101194.iso/vrac/ensmgr14.zip/MGR_DOC.TXT

Text File | 1994-07-24 | 26KB | 571 lines

                            ENS MGMT SCRIPTS

INTRODUCTION

This zip file contains a set of OzCIS scripts which provide a management
capability for creating/deleting/editing Executive News Service (ENS)
personal clipping folders.  It requires OzCIS ver 2.0c or better to run.
Related scripts can be found in OzCIS Lib 7 as ENSCHD.ZIP (scheduled
reading/mailing of clipped articles) and ENSSCN.ZIP (offline quickscan
of clipped articles).  Lib 8 contains ENSHOW.ZIP, a tutorial text file
on how to use ENS.

My thanks to Ed Wiggins [71540,3363] for his many suggestions, and his
careful testing.  Don't blame Ed if I missed something!

INSTALLATION

Copy the scripts to your..\ozcis2\scripts  directory.  The two scripts
ENS_MGRA.SCR and ENS_MGRZ.SCR (they handle all script maintenance from
A-Z) must be present in the same directory for either to work.  I'll use
the designation ENS_MGR.SCR to mean both used together.

There are configuration options which must be edited before use.
Speedlimit and shortcut are specified by uncommenting one, and only one,
of the variables in the configuration box.  You make any script line
into a comment by inserting a semicolon as the first non-blank character
on the line.

;= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
   ; CONFIGURATION OPTIONS - SEE DOCUMENTATION FOR DETAILS

define #speedlimit %true
;define #speedlimit %false

define #shortcut %true
;define #shortcut %false

define $path     "d:\oz2\ens\"
define $logfile  "d:\oz2\ens\ens_mgr.log"
;= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

Defining #speedlimit %true will limit the script to operation at 2400
baud and below.  See the discussion under SAVING MONEY.  If you access a
script at, for example 9600 baud, while #speedlimit is set true, the
script will issue a message and abort before entering ENS where
surcharges apply.

Defining #shortcut %true will avoid the surcharged online time required
to store a copy of the current folder specifications in effect before


24 Jul 1994              ENSMGR.ZIP  Ver 1                 Page 1



the script modifies them.  This saves 20-40 seconds of online time per
folder.  Setting it %false will write the added data in the $logfile.

Neither #speedlimit nor #shortcut are present in ENS_MGRA.SCR since that
script can not be run online.  These variables only apply to the online
script ENS_MGRZ.SCR.

The last two variables control where the script stores its working
files.  By default all temporary program files are located in the
directory configured in your OzCIS Hosts file.  You may change that by
editing the variable $path.  The $path variable MUST be the SAME in BOTH
scripts, ENS_MGRA.SCR and ENS_MGRZ.SCR!  This manual shows correctly
formatted examples; the supplied script has null values to match the
default case.

Make sure that you supply a complete specification: drive, path, and
final '\' character.  If you want a new directory, e.g. ..\ens\, you
must create it when installing the script.  The script will fail if the
directory doesn't exist.  Be sure to enclose the new names in double
quotes.  Relative paths or paths lacking a drive will usually fail.

There is one CompuServe parameter which you may want to edit.  The line
define #MaxName 10 in ENS_MGRA.SCR specifies the length of a folder
name.  CIS permits up to ten characters.  DOS file names are limited to
eight characters.  You can define #MaxName 8 to ensure that your folder
names online are also legal DOS filenames.  Check that existing online
files don't have ten character names before doing this.  See also the
note regarding #MaxWire under DATA ENTRY, Wire Services below (pg 7).

The file $logfile contains a record of what the script did while online.
Always check the last line of this file after each run to check for
online errors.  It is stored in the directory configured in your host
file.  To change the default location edit the $logfile definition to
include a complete drive,path,file spec.

ENS_KEYS.SCR

This script accesses ENS and generates DOS files containing the current
specifications for each of your personal folders.  The files are stored
as NAME.KEY (NAME is the online folder name) in the directory configured
by $path, or in the host default directory if no $path is given.  See
the discussion of #MaxName above.  This data is helpful if you can't
remember which search key words you used, or if you want to check the
current folder expiration date.  Once you have these files, you can
avoid the expense of accessing ENS for this information on subsequent
occasions.  Deleting a folder with ENS_MGR.SCR will erase the
corresponding local file NAME.KEY.

The script also produces a file, NEWSWIRE.KEY, which contains a list of
the available news wires and their ordinal number which you use to
specify wire services in ENS_MGR.SCR.  You must already have at least


Page 2                 ENSMGR.ZIP  Ver 1              24 Jul 1994



one personal folder created in ENS before NEWSWIRE.KEY can be created.
This may cause a small problem if you are using ENS_MGR.SCR to create
your first ENS folder.  You won't be able to find news wire keys to
create the first folder, and without a folder you can't easily get the
list of wire services.

One solution is to use ENS_MGR.SCR to create your initial folder by
entering 1 and accepting whatever wire service that is.  After this
first run the log file, ENS_MGRZ.LOG, will contain the wire service
list.  Then, if necessary, modify your folder by again running
ENS_MGR.SCR.

Since subsequent runs of ENS_MGR.SCR may not leave the wire list in the
log file, run ENS_KEYS.SCR to get a permanent list of available wire
services.  That will create files NAME.KEY for each personal folder and
NEWSWIRE.KEY listing all the wire services.  Now use ENS_MGR.SCR
exclusively to make all further changes, and you will always have
current and recognizable specification files for all your personal
folders.

A very similar script, ENS_GTKY.SCR, is located in the ENS scheduling
script package, ENSCHD.ZIP.  This script differs in two ways.  First, it
captures in a local file named NEWSWIRE.KEY the numbered list of wire
services which you can use to specify wires in ENS_MGR.SCR.  Second,
ENS_GTKY.SCR information is stored in a series of DOS text files:
FOLDERx.KEY where x is 5-7 corresponding the folder number.  Note that
ENS_GTKY.SCR uses file names FOLDERx.KEY while ENS_MGR.SCR and
ENS_KEYS.SCR both name files after the folder, i.e. NAME.KEY.

ENS_MGR.SCR

The scripts ENS_MGRA.SCR and ENS_MGRZ.SCR are designed to make the
creation and maintenance of personal ENS folders a little easier and
cheaper.  You can specify folder attributes offline and then go online
and automatically create, delete, or modify up to three folders com-
pletely under the control of the script.  Thus it eliminates online time
correcting typos in a surcharged area like ENS.  If you do this task
infrequently as I do, you will save time by not having to think about
the correct menu responses to achieve what you want.  The scripts, alas,
are not perfect.  The limitations of a script language do not permit all
the features one might wish in these scripts.  Nevertheless, I hope you
will find the capabilities that are here to be useful.

ENS_MGRA.SCR

To use this script edit the first page of the script file offline using
the OzCIS general editor.  It is most convenient if you access the
editor from the Online Manual Tools Edit series of menus.  Note that
there are about two screens of data to supply; make sure you review
everything between the two * * * bars.  See DATA ENTRY for details.
Then save the edited file.


24 Jul 1994              ENSMGR.ZIP  Ver 1                 Page 3



Run the script ENS_MGRA.SCR offline in Manual Terminal mode to check the
correctness of the data entered via the editor.  Running the script may
temporarily fill the screen with what appears to be garbage.  This is
normal.

ENS_MGRA.SCR provides a minimal check of your data which will eliminate
wasted time online if you have a simple error.  Unfortunately, not all
possible errors can be checked, and you would be wise to carefully
review your data before the next step.  If your data passes the
validation checks, you will see a dialog box asking if you want to save
these data for later online processing.

When your data passes all validation checks ENS_MGRA.SCR will also
display the contents of NAME.KEY if it exists for this folder.  This
allows you to see the current folder contents and the proposed changes.
The limited screen real estate means that you will have to drag the
dialog box around with your mouse in order to see all of the background
information.  Place the mouse cursor on the top border, hold down the
left mouse key, and drag the dialog box to uncover the underlying
screen.  By resizing the edit window and dragging it to either the
screen top or bottom you can compare new key phrases against old
phrases, verify correct delete phrase numbers, etc.

You can move the data entry dialog box down to the bottom of the screen
with your mouse.  Just place the mouse cursor on the top border of the
dialog box, hold the left mouse key down, and DRAG THE BOX DOWN.  This
will prevent the dialog box from covering some of your proposed folder
data.  The box will stay in that position until the next time you
restart OzCIS from DOS.

The slickest way to enter data and run an offline validation check is to
first enter Online Manual.  Then use Tools Edit to bring up the edit
window and load the script file.  After completing data entry, press
<F2> to save, <ESC> to exit, <AltS> to run the script offline.  If the
script detects any errors, repeat Tools Edit and you will be able to see
both the script results and the script text ready for editing.  I find
it handy to use a macro to toggle back and forth between editing and
running.

The script does not list all errors found at one time.  It lists only
the first error found.  Thus if more that one error is present, only one
will be described.  After correcting a data input error don't assume
that your data is now error free.  You must run the script another time
offline to ensure that there is no second error lurking to trip you up.
Only when no errors were detected will you be asked if it is OK to save
the data.

You may run ENS_MGRA.SCR and store good data for up to three folders.
Each folder will have its data stored in a separate file in the $path
directory.  These will be processed in turn by the online script,
ENS_MGRZ.SCR.


Page 4                 ENSMGR.ZIP  Ver 1              24 Jul 1994



ENS_MGRZ.SCR

To make the changes effective run ENS_MGRZ.SCR online using the Custom
Script feature of OzCIS.  Or you may wish to configure ENS_MGRZ.SCR as a
Special Services script.

Always check the log file, ENS_MGRZ.LOG, if you have any doubt about
possible errors.  That file contains a record of the ENS response to
each datum entry attempted.  The last line of this log file will contain
one of three possible messages.

"Normal script termination."  This means that no online errors were
detected.  It does NOT mean that you got the intended result.  For
example, if CIS has changed the order of listing wire services, you may
have selected/deleted an unintended wire service.  Check through the
logfile and/or the key file discussed below to be sure.

"A non-fatal ERROR occurred.  Check this log."  This message means that
one or more online errors were detected.  The script will ignore the
problematic datum and process the remaining data.  If, for example, you
have supplied an illegal key phrase, you will see this error message
where the error occurred and again at the end of the logfile.  I
recommend that you do a global text search backward on the word ERROR
(all cap) with Ignore Cap off to be sure you see all non-fatal errors.
In a pass with several folders it is possible to have a non-fatal error
in one folder, but a successful processing of other folders.

"An ERROR occurred."  Only fatal errors will place this message at the
end of the log file.  Fatal errors include online timeouts, dropped
communications line, failure to open and read local disk files, etc.
Such errors cause the script to abort immediately.

At the conclusion of each run any new or changed personal folders have
their specifications recorded in local DOS files named after the folder
name with KEY as the file extension, e.g. STOCKS.KEY.  These files are
stored in the directory pointed to by the configured $path variable.
This why it is a good idea to define #MaxName 8.  You can refer to these
local files later to remind yourself what the clipping file key phrases
are or when the folder expires.

DATA ENTRY - ENS_MGRA.SCR

Data entry consists of supplying the required ENS information, e.g.
folder name, expiration date, key words, etc., for each define.  It does
not involve editing any other script commands.  Each line of information
MUST be enclosed in quotation marks.  You can omit information by
leaving the empty quote marks in place.  Note that "" is not equivalent
to " ".  Be careful to delete no longer relevant information remaining
from previous use of the script!




24 Jul 1994              ENSMGR.ZIP  Ver 1                 Page 5



Folder Name - The three names are handled in the following order.
First, if $DelName is present the script looks for that folder and
deletes it if it exists.  Second, if $ChgName exists all other data,
including $NewName, are processed as changes to the existing folder
$ChgName.  In this case partial data is permitted.  Third, if $ChgName
is null and $NewName exists all data are used to create a new folder
with the name $NewName. In this last case the new folder must have
complete data.

The script will convert folder names to all upper case.  This makes it
possible to search for matching names.  You may find it convenient to
enter upper case names just to see how they will look online.

Folder names usually are limited to one of a kind, either Delete, New,
or Change.  You may either Create or Change a folder, but not both in
the same pass.  The single exception, and it is sometimes very useful,
is that you may Delete and then Create folders in one pass.  This is
often useful when deleting an existing folder and recreating it with
different key words is better than changing the key words.  Here one
pass means processing the results of one ENS_MGRA.SCR run.  You can
create a folder and change a second folder in one online session by
making two passes of ENS_MGRA.SCR followed by one online session running
ENS_MGRZ.SCR.

Deleting any folder would lose any stories currently in that folder.  If
you want them, you should empty the folder before deleting it.  The
collections listed earlier provide scripts for doing this.

Expiration/Retention - The entries for expiration date and retention
period are self explanatory.  The script knows nursery rhymes, but
doesn't know about leap years.  February 29 is always illegal.  I find
it convenient to have folders expire on the last day of a month; it
avoids confusion between month number and day number.  Make sure that
you use the indicated MM/DD/YY format, and that you choose a date not
more than one year in the future.

Wire Services - Wires are specified in two groups, those to be added and
those to be deleted.  Both lists of wires must be entered in numerically
increasing order.  The numbers corresponding to each wire service can be
found in file NEWSWIRE.KEY if ENS_KEYS.SCR has been previously run.  If
this is your first use of ENS, select wire service 1 for your first new
folder.  The list of wire service names will appear in the ENS_MGRZ.LOG
file created when your first folder is created online.  You can edit the
wires in a subsequent pass with the script.  Note that CompuServe may
change this wire list by adding, deleting, or renumbering wire services
which ENS supports.  You may want to update this list every six months
or whenever you get a strange wire service in your personal folder.
While you can specify as many wires as you like, in my experience too
many wire services just results in duplicate stories.




Page 6                 ENSMGR.ZIP  Ver 1              24 Jul 1994



NOTE:  If CompuServe changes the number of wire services offered (they
did this twice during script development) you will need to change the
constant  #MaxWire  in the CIS Constants section on Page 1 of
ENS_MGRA.SCR.  This constant should always be set to the highest
numbered wire service listed in NEWSWIRE.KEY.

Key Phrases - Deletes are done before changes which are done before
additions.

Deleting a phrase modifies the ordinal position of the remaining key
phrases.  Deletions are made before changes so take this into account
when positioning new phrases in your change list.  When using this
option users must input phrase numbers in numerically decreasing order,
i.e. from high to low.  That will preserve the order of phrases
remaining in the case where several phrases are to be deleted.

After every change to any search phrase ENS sorts the phrases in
alphabetical order.  This occasionally makes it difficult or impossible
to know the phrase number of subsequent phrases which you want to
change.  Careful attention to alphabetizing your changed phrases or
deleting and recreating all key phrases will overcome this feature.

Changing a phrase.  What happens to a (replace/add) key phrase depends
on its position in the ENS_MGRA list, AND on how many phrases previously
existed.  Note that deleting phrases changes both how many remain and
what position the remaining phrases occupy online when the script starts
replacing-adding.  Key phrases often contain non-alpha characters.  It
is usually necessary to use parenthesis to create useful combinations of
search text with logical AND and OR, e.g.

     (( comput* | microchip ) | company )

Since the '(' character has ASCII value less than 'A' it will sort
first.  Note the following sort order:

     (( SEARCH + WORD ) | ( FOUND + SOMETHING))
     ( NEXT + PHRASE )
     A + (WORD)

The script will check for matching left and right parentheses.  Passing
this test doesn't mean that they are logically correct, just that they
balance.  I have noticed that CIS will reject unnecessary parenthesis
(last example above) with the unhelpful error message, 'Unmatched
Parentheses' so check carefully.  The script language just doesn't
permit a rigorous syntax check for correct key phrases acceptable to
CIS.

Phrase edits are applied to the same numbered phrase.  Thus if you
supply change data for an existing key phrase three, the given phrase
will replace the online phrase three.  If the new keys change the
alphabetic ordering, this phrase may be moved by ENS to a different


24 Jul 1994              ENSMGR.ZIP  Ver 1                 Page 7



location in the list.  If that happens a new phrase at position four in
your change list may replace a completely different phrase; the former
phrase four which you wanted to modify may now be number three.

Adding key phrases is supported indirectly.  Change phrases numbered
above the current highest numbered key phrase will be added as
additional search phrases.

SAVING MONEY

While ENS is powerful with its key phrase capability, it is heavily
surcharged.  I've found that using this script allows me after a few
days to hone my key phrases narrowing in on just the interesting topics.

The big advantage of these scripts is avoiding online charges while you
fix your typos.  You save again because ENS_MGR.SCR automatically issues
commands at the correct place in the ENS menu tree as fast as CIS will
accept the data.

There is a lot of waiting dead time while using ENS.  The CIS computers
take time to respond to each of your commands.  This particularly
pronounced when creating or modifying the key phrases.  Depending on
your usage 2400 baud operation may be cheaper than operation at higher
baud rates.  There may be an exception if you run ENS_KEYS.SCR when
three folders already exist, each with many key phrases.  In that case
there is usually enough data downloaded to justify 9600 baud.

The timelog file ENS_SCPT.LOG in the host default directory records the
time spent by each online script and the baud rate used.  Careful use of
this record and adjusting your usage accordingly can lead to
considerable savings in CIS charges.  This file grows cumulatively, so
check and clear it monthly.  The script itself doesn't handle this
chore.  I find it convenient to import the text data from this file into
Lotus 123.  Then I use the Data Parse function, subtract adjacent ON and
OFF times, and sum the result.  One could also use the baud information
adding stored rates to calculate cost estimates.

HINTS: MACROS AND OZCIS.INI

The easy way to edit the define statements in ENS_MGRA.SCR is to go
first to Manual Terminal, then use Other Editor to call up the general
editor.  That brings up a movable resizable edit window which can be
viewed at same time as the results of the offline script run.  It makes
correcting errors detected by ENS_MGRA.SCR offline a snap.  I use a
macro to toggle back and forth between edit and run.

Accessing the editor from the main screen Tools Text menus requires many
more keystrokes to go back and forth between editing the script
variables and running the script to validate the data.




Page 8                 ENSMGR.ZIP  Ver 1              24 Jul 1994



If you want to use 2400 baud to access ENS and 9600 baud for forum
tasks, it is very handy to have a macro to switch between various host
configurations.  Such macros can be loaded when OzCIS is first started.
Check the following entry in ozcis.ini using Configure General from the
main menu.

; The following defines a keyboard macros file to be loaded at startup.

DefaultMacroFile=hosts.mac

This package contains a sample macro file which you may find helpful as
a starting point for developing your own.  Since I don't know which keys
you may have redefined with your own macros, this may not work exactly
for you.  It is based on using <CtrlN> (N is a digit) with the 10 key
numeric keypad in a progression which follows the normal order of
editing and running ENS_MGR.SCR offline/online.

                           +---------+
the host selection cycle ->|  7 8 9  |
offline/online-run cycle ->|  4 5 6  |
edit/check offline cycle ->|  1 2 3  |
                           +---------+

                                +<<-----define host#2
       define host#1 --->> 7    8    9 <<--- define host#3
                                +<<-----run ENS_MGRZ.SCR online
goto Manual Terminal --->> 4    5    6 <<--- goto Main Menu
                                +<<-----see ENS_MGRZ.LOG offline
Edit script ENS_MGRA --->> 1    2    3 <<--- Run script ENS_MGRA


The current OzCIS ver 2.0c(5) requires two macro keys, one to enter
Manual Terminal and then a second to Run Script.  Thus after loading the
macro file one executes the cycle 4,1,3,6,5 counterclockwise on the
keypad.  After entering Manual Terminal with <Ctrl4> you can cycle
between entering data <Ctrl1> and validating/saving the data <Ctrl3> for
one or more personal folders.  When you have completed the offline work,
use <Ctrl6> to return to the main menu.  If necessary select an
appropriate host using <Ctrl7> or <Ctrl9> to match your #speedlimit
configuration.  Finally <Ctrl5> will run the online ENS_MGRZ.SCR and
send to CIS your new folder characteristics.  Because of the way OzCIS
handles macros the host selection cycle, <Ctrl7>,<Ctrl8>,<Ctrl9>, is
available only from the main menu.

If the ENS_MGRZ.SCR encounters online errors repeat the cycle to correct
the errors.  In this case <Ctrl4><Ctrl2> will display the log file.

This macro file can not be used exactly as packaged here.  Your host
configurations will be in different positions, and your available macro
keys may be different.  You might prefer replace <Ctrl5> with <Ctrl7>



24 Jul 1994              ENSMGR.ZIP  Ver 1                 Page 9



for the run online command.  That would group the online keys in the top
row.  I like to keep the online run as the centerpiece at <Ctrl5>.

WARNINGS AND LIMITATIONS

The key phrases can NOT contain certain characters, i.e. <,>, etc.  If
illegal characters are detected online by CIS the script will ignore
that key phrase and attempt to transmit the balance of the phrases.
This error is not caught running the script in manual mode.

There is no offline check for the case of attempting to delete a key
phrase numbered above the highest numbered phrase present online.

The script does not check that deleted wire services were previously
active, nor that added wire services were previously inactive.

No provision is made in the scripts for deleting data files produced by
ENS_MGRA.SCR except running ENS_MGRZ.SCR online.

There certainly are other possible online errors which are not caught in
the offline data validation.

While the CIS defined constants will handle some possible future changes
by CompuServe in the ENS menus, they won't handle all of them.  For
example, changing the maximum number of key search phrases requires more
than simply redefining #MaxPhrase.

REVISION HISTORY

July 1994   Original upload.  Version 1:4























Page 10                 ENSMGR.ZIP  Ver 1              24 Jul 1994