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 to save, to exit, 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 (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 you can cycle between entering data and validating/saving the data for one or more personal folders. When you have completed the offline work, use to return to the main menu. If necessary select an appropriate host using or to match your #speedlimit configuration. Finally 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, ,,, 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 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 with 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 . 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