SPAREDEV.TXT                                                November 13th, 1998
~~~~~~~~~~~~

             USER GUIDE FOR SPARE DEVICE SURVEY SCRIPT FILE
             ==============================================


  Script Function :
  ~~~~~~~~~~~~~~~~~
      Performs a survey of all LI/LI1/LI2/LI3/LIBA/LIBAE/LIRA1/LIPRA/LIPRAE and
      SEPRM/SEPRM1/SEPRM2/SEUBF devices in /A4, /29, /36, /66 or /69 AXE 
      exchanges which are equipped but not in use.


  User controls :
  ~~~~~~~~~~~~~~~  
      On initial start, the opening screen allows the user to select the 
      following options :

        1.  Create new EXEDP data file ? - 
             Options include : (C)lear ALL data and begin again.
                                NOTE: This option completely replaces
                                      the data for the selected site.
                             : (U)pdate profile data for current EMG list.
                             : Use existing EXEDP.PRO file data (N) (default)

      Note: If no data is found for the Node/EMG to be surveyed, EXEMP or 
            EXEDP is output to read required data from the exchange.

        2.  Read EXEDP's only ? - This option does just that, and appends 
            or updates the EXEDP.PRO data file.  For mainstream nodes, an
            EXEMP printout is checked for analog LI's and node-associated
            Special Equipment (SEPRM/SEPRM1/SEPRM2).  No survey is performed.
            Default is to perform survey.

        3.  Check LI/LI1/LI2/LI3/LIBA/LIRA1/LI... devices ?     Default is Yes.

        4.  Get hardware equipping status for LI/LI1/LI2/LI3/LIBA/LI....
            devices ?  (no h/w checking done for SE devices).  Default is Yes.

        5.  Check Special Equipment (SEPRM/SEPRM1/SEPRM2/SEUBF devices) ?
            (NO check for SSS-5 (P90) SEPRMI yet)  Default is No.

      Note: If you don't want to get data for a device type, edit the
            EXEDP.PRO file to comment out the unwanted lines by placing an
            exclamation mark (!) at the beginning of the line, before 
            commencing the survey.

        6.  Count number of TSMs in node's Group Switch Stage  (Not displayed
            for application /69).    Default is Yes.

        7.  If required, a summarised report can be specified (no details
             of spare devices for individual EM's are reported).  Default is Yes.

        8.  Script run-time can be immediate or time scheduled.  Selected
            menu options are stored in file SPAREDEV.CFG until execution
            ecution is started at the specified time, after which the file
            file may be deleted as per option 8 (for time scheduled operation).
            Default is No (run immediately).

        9.  Clear Configuration File after loading - default is No.
            (i.e. Preserve SPAREDEV.CFG for next run, based on the settings
                  found in the "config" file.)


  Files :
  ~~~~~~~
  OZTERM\CMDS\PMB\SPAREDEV.CMD  Script file for control of survey actions.
  C:\SPAREDEV\SPAREDEV.EXE      Executable file for processing of survey logs.
  \PMB_RTNE\lncd\SPAREDEV.LOG   Contains PRINT VAR's for processing (input)
  \PMB_RTNE\lncd\SPARlncd.TXT   Report (output) file
  \PMB_RTNE\lncd\EMGLIST.TXT    List of NODE/EMG names to process
  \PMB_RTNE\lncd\EXEDP.LOG      EXEDP printout for analysis/copying to 
                                profile data file EXEDP.PRO
  \PMB_RTNE\lncd\EXEMP.LOG      EXEMP printout for analysis/copying to 
                                profile data file EXEDP.PRO (not used in /69)
  \PMB_RTNE\lncd\EXEDP.PRO      Profile of LI and SE in EM's for EMG's in 
                                this exchange.
  \PMB_RTNE\lncd\EXEDP.TMP      Copy of selected EMG data from EXEDP.PRO
  \PMB_RTNE\lncd\SPAREDEV.CFG   Current survey controls for auto/scheduled 
                                execution.

  What it does : 	
  ~~~~~~~~~~~~~~
      Initially, the exchange application system and CNA are established
      by processing an ALSTP printout.

      If a SPAREDEV.CFG file is found, the flags are set from the contents,
      otherwise the default settings are activated.

      If the script was started from a menu or directly from 'New Transmit
      file', the user has the option to change any of the settings(flags)
      or reset all to defaults.

      If the script was started from a Time Event, the specified actions
      are carried out without further operator intervention.  The settings
      are briefly displayed before the script commences the activity as set.

      If the option to Clear profile data was selected, the user is 
      prompted to confirm the action before the file EXEDP.PRO is deleted.
      The option to remove the EMGLIST.TXT file is also prompted and
      actioned as per user response.

      If "Read EXEDPs only" has been specified, these commands are input 
      to the logged-on exchange for all EMG's (from EXEGP or EMGLIST.TXT)
      and the new data stored in EXEDP.PRO (no report file is created).
      On completion, the script terminates.

      A LASIP print is requested to match Software ID's against the list
      stored in the script file, and the appropriate variables for each
      device type are set from a lookup table.

      Any previous survey result file (SPARxxxx.TXT) is deleted.

      If selected (and applicable), GSSTP command is input to the exchange
      and the number of TSM's and the GSS size is output to the report
      file.

      If it exists, a text file containing a list of selected EMG's to
      be surveyed is read into an array of EMG names.  This file is 
      called EMGLIST.TXT and should be stored in the sub-directory for
      the node being surveyed ( e.g. C:\PMB_RTNE\BUNX ).

      If no EMGLIST.TXT file is found, a list of EMG names attached to 
      the node is read from an EXEGP print, and also stored in the file
      EMGLIST.TXT .  

      If the exchange is not /69, and the current name read from the list
      of EMG names is that of the connected node, then an EXEMP printout
      is requested and processed to obtain any/all LI's and SE devices 
      which may be attached to the node.

      Then, for each EMG, a print of all EM's which may contain LIxx
      or SE devices is performed (EXEDP), from which the device ranges
      per EM are derived and stored in an array.  If, however, a file
      containing the EMG, EM, DETY, and device ranges is found (EXEDP.PRO)
      then the data from that file is used in specifying the Test System
      parameters (except if Update was selected - see Option 1).

      If LIBA devices were detected in the EXEDP printout, an EXHMP print
      is also requested to get the device ranges.

      Test System prints for hardware equipping (HWCON) and SNB allocation
      (SNBCON) are processed to determine spare LIxx's for each EM in turn,
      based on the LI ranges stored previously.   For Special Equipment
      variable ADMSTATE (SEPRM) or INDSTATUS (SEPRM2 and SEUBF) is used.

      Directives prefixed by exclamation marks are inserted into the log
      file before each block of PRINT VAR's to tell the external processor
      what to do next.  When all prints are completed, the log is closed
      and the processing program reads the data and compiles the survey.

      The spare devices for each EM are written to the output file 
      (SPARES.TXT), followed by the unequipped positions (if any), except
      if Summary Only was selected at Option 6.

      After all EM's for the EMG are processed, a summary of the devices in
      use, spare devices and the total equipped devices is written, before
      starting processing for the next EMG.

      !--------------------------------------------------------------------!

      Format of SPAREDEV.CFG is all eight flags on one line.  
      e.g    YNYYNNNY
      translates as:
        Perform hardware check of LIxx's
        Don't create/update a new EXEDP profile list (i.e. use EXEDP.PRO)
        Check allocated LI/LI1/LI2/LI3/LIBA/LIRA1/LIPRA devices
        Check allocated SEPRM/SEPRM1/SEPRM2/SEUBF devices
        Create Full report (i.e. not summary)
        Collect all data (not just EXEDP's)
        Don't Clear Configuration File after loading (leave for next run)
        Read GSSTP and count TSM's

       These are NOT the default settings (see above notes).
   
      !--------------------------------------------------------------------!

      Format of EMGLIST.TXT is simply one EMG name per line, followed by 
      a single character which identifies the EMG as LSS-D or RSS-D.  
      e.g.
          BUNX
          BBYX0  L
          PICD0  R
          !AUDS1  R
          CLRS0  R
                for exchange BUNX (first entry is node name for LI's, etc.)

      Leading and trailing spaces are removed before storing/using the name.

      EMG's not required can be commented out by placing '!' at the beginning
      of the line.
      
      !--------------------------------------------------------------------!

      EXEDP.PRO (example)          - exchange device 'profile'
0   0       1       2         3
1   5       3       1         1
EM  DEV     START   END       ADDITIONAL INFO
      ----- file start -----!
ADLSQ LI
00  LIPRA   0       127       ETGAM-0&&-3
01  LIPRA   128     255       ETGAM-4&&-7
02  LIPRA   256     383       ETGAM-8&&-11
03  LIPRA   384     511       ETGAM-12&&-15
04  LIPRA   512     639       ETGAM-16&&-19
05  LIPRA   640     767       ETGAM-20&&-23
06  LIPRA   768     895       ETGAM-24&&-27
07  LIPRA   896     1023      ETGAM-28&&-31
08  LIPRA   1024    1151      ETGAM-32&&-35
09  LIPRA   1152    1279      ETGAM-36&&-39
10  LIPRA   1280    1407      ETGAM-40&&-43
end
BUNX  SE
01  SEPRM1  0       15        58
02  SEPRM1  16      31    
08  SEPRM1  32      47    
09  SEPRM1  48      63    
10  SEPRM1  64      79    
11  SEPRM1  80      95    
12  SEPRM1  96      111   
end

      ----- file end -----!

      Lines not required can be commented out by placing '!' at the beginning
      of the line.

      !--------------------------------------------------------------------!

