Adding a New SU

The dummy processor USR provides a convenient vehicle to develop a new SU of any sort. As it is permitted to change its attributes, USR can be either a processor or a support system. It is discussed in the User Manual in the chapter Adding Code to SNOMAN. However, USR is reserved for private work, for any code that becomes part of SNOlib it is necessary to create a new SU. To add a new SU first contact the SNOMAN Coordinator to discuss it and then proceed as follows. For the purposes of the section, the new SU is assumed to have a short name xxx and is assumed to be dependent on SUs yy1, yy2 and yy3.

1. In the file su_mnemonics.inc define a new parameter KSU_xxx with a unique number in the range 1-KSU_MX_SU_ID.

2. In the file su_def.for define the SUs long and short names together with its attributes and supporting SU mask:-

    
         CSU_NML(KSU_xxx) = '... '    (supply some suitable name)
         CSU_NMS(KSU_xxx) = 'xxx'
         ISU_ATR(KSU_xxx) = DYNAMIC_PROCESSOR
         CALL SET_MASK( 1, ISU_SSM(1,KSU_xxx), KSU_yy1, 0 )
         CALL SET_MASK( 1, ISU_SSM(1,KSU_xxx), KSU_yy2, 0 )
         CALL SET_MASK( 1, ISU_SSM(1,KSU_xxx), KSU_yy3, 0 )
   

   See Program Notes of su_def.for for attribute settings:-
   • SUPPORT, PROCESSOR

   • STATIC, DYNAMIC

   • CONTEXT_SETTER

   • NOTIFY_CONTEXT_CHANGE.

3. In the file su_call.inc add lines to call the initialisation and termination routines for the SU (if any). For processors, an execution call is also required E.g.:-

    
    
   *     xxx ...
    
         ELSEIF (ISU_ID .EQ. KSU_xxx) THEN
           IF     (IOPER .EQ. KSU_INITIALISE) THEN
             CALL xxx_*_INI(MODE,IRETC)
           ELSEIF (IOPER .EQ. KSU_PROCESS)    THEN
             CALL xxx_*(MODE,IRETC)
           ELSEIF (IOPER .EQ. KSU_TERMINATE)  THEN
             CALL xxx_*_TRM(IRETC)
           ENDIF
   

4. Add code for the SU as appropriate. The following are required:-
   • An initialisation routine. Recommended name XXX_*_INI. This routine will be called with its MODE parameter set to:-
     • KSU_INITIALISE - normal initialisation.

     • KSU_REINITIALISE - after titles update if DYNAMIC. See section 8.2.4 for further discussion.

     • KSU_SET_CONTEXT - to set an initial context (date and data type) if CONTEXT_SETTER.

     • KSU_CONTEXT_CHANGE - after change of context (date and data type) if NOTIFY_CONTEXT_CHANGE.

     see su_mnemonics.inc for these values.

   • An execution routine. Recommended name XXX_*. This routine is only required for PROCESSOR (support systems are called directly by code that requires their services).

   • A Termination routine. Recommended name XXX_*_TRM.

   The user processor USR may be used as a template for a typical processor.

5. Provide a dummy version of the SU. The following are required:-
   • The file xxx_dummy.inc which contains dummy entry points for any routine called directly by su_call.inc. These must all generate fatal errors except for the initialisation mode KSU_CONFIRM_NOT_DUMMY. For example see usr_dummy.inc.

     For support systems, which are normally called directly by code, rather than by SU_CALL, add dummy entries for any routine called by the outer framework of SNOMAN i.e. the shell (SHL). Consider including additional routines that form part of its interface. For example GEO could include GE_NEAR, GE_NEXT, GE_PICK, and GE_PICK. Such routines must also generate a fatal error unless they can sensibly operate in the context of a dummy. See for example geo_dummy.inc

   • The updating of user_define_task.for. Add:-

     * include 'xxx_dummy.inc'

     to the Dummy SU section. Note the fact that it is commented out!

6. Contact the software coordinator to discuss the updating of the Companion's Software Structure section.

Modify an existing SU in a similar way.