Decentralized administration programs

If the administered applications use complete administration programs as described in chapter "Writing your own administration programs", the control of an administration service will essentially reside with the application that is being administered. The administration program must therefore:

• interpret a message received from the administration application or - in the case of automatic administration, for example - from an application-internal MSGTAC program

• correctly supply all areas for the administration call

• evaluate and respond to the return codes, i.e. it must notify the administration application in the event of errors and, where appropriate, roll back the transaction

• evaluate the returned data and decide what data is to be sent to the administration application.

It is advisable to write individual program units for the various administration tasks or, if you are using a complete administration program, to address the program with different TACs depending on the task required. This will ensure that the tasks is selected on the basis of the TAC and not on the basis of the message.

Portable administration programs

If you want to use your administration programs in different applications running on different platforms, you can write the relevant programs in such a way that they can run both on Unix, Linux or Windows systems and BS2000 systems.

This task is simplified by the fact that the program interface has the same data structures on all platforms. You will, however, need to note the following platform-specific differences:

• There are certain fields and substructures which only have any meaning on one platform

  • When reading data, fields which are not relevant to the given platform are always populated with binary zeros.

  • When modifying or generating objects, the fields which are not relevant to the given platform must be populated with binary zeros. For this reason, the program should first establish the platform on which it is running. To do this it has to evaluate the field system_type in the structure kc_system_par_str after calling KDCADMI with the following parameters:

    opcode=KC_GET_OBJECT
    subcode1=KC_APPLICATION_PAR
    obj_type=KC_SYSTEM_PAR

    Once it has determined which platform it is running on, the program must first reserve the fields that are valid for all of the operating systems for the administration calls themselves. It then reserves the fields that are needed for the relevant platform.

• The sort order for characters differs between BS2000 systems and Unix, Linux and Windows systems: BS2000 systems generally use an EBCDIC code and Unix, Linux and Windows systems an ISO code.

• Names on BS2000 applications only use uppercase letters, whereas Unix, Linux and Windows systems names can use both lowercase and uppercase.

• Unix, Linux or Windows systems normally use other character sets than BS2000 systems (ASCII/EBCDIC problem).

The following example shows a portable administration program which replaces a load module, shared object or DLL in the decentralized application. The program verifies which platform it is running on and uses the result to effect a program-internal branch.

On Unix, Linux and Windows systems, only the shared object/DLL is replaced, whereas BS2000 systems check whether the load module is in a common memory pool and, therefore, whether the application in fact needs to be replaced.

 #include <kcadminc.h>       /* Include file for the administration      */
 INIT
 ...
 MGET                         /* Read in name/date of the program unit    */
 ... Analyze input
 KDCADMI opcode=KC_GET_OBJECT /* Query operating system                   */
 KDCADMI opcode=KC_GET_OBJECT
                              /* Determine current version of load        */
                              /* module and check whether it is at all    */
                              /* possible to replace it.                  */
  
 if (BS2000)                  /* BS2000 routine                           */
    { KDCADMI opcode=KC_GET_OBJECT
                              /* Query load mode and determine whether    */
                              /* program is marked for exchange   .       */
      KDCADMI opcode=KC_MODIFY_OBJECT
                              /* Replace or mark load module if it is     */
                              /* in a common memory pool.                 */
      if (common memory pool) 
          KDCADMI opcode=KC_CHANGE_APPLICATION
                              /* Replace application                      */
    }                         /* End of the BS2000 routine                */
 else                         /* Unix/Linux/Windows routine */
      KDCADMI opcode=KC_MODIFY_OBJECT
                              /* Replace shared object/DLL             */
                              /* End of the Unix/Linux/Windows routine */
 MPUT                         /* Message to the initiator                 */
 PEND FI

The program can also be supplemented by means of dynamic generation (TAC, PROGRAM,...) as described in the example in chapter "Several administration calls".