Docstoc

139

Document Sample
139 Powered By Docstoc
					Chapter 5


Communications




Communications Control Facility on Windows
            Windows

            The communications techniques used within BASIS are grouped into two
            categories: Inter-Process Communications (IPC) and Network
            Communications (DMNAM). Inter-Process Communications are used
            when the user program and the Kernel operate on the same computer.
            Network Communications are used when the user program and the Kernel
            are on different network nodes.

            The Inter-Process Communications (IPC) software used by the BASIS
            system is controlled by the Communications Control Facility (CCF).
            BASIS users and Kernels use the CCF to coordinate communications. The
            Kernel also uses the CCF to process operating options.

            The CCF contains parameters for Kernels in a Kernel Set. It allows each
            Kernel configuration to be customized if necessary, when operating
            multiple Kernels. For more information on Kernel Set operation, see
            “Tuning the System.”




                                                                  Communications  139
               BASIS user processes use the same CCF for the Kernel Set they are
               referencing when a BASIS signon is performed.

               The CCF is part of the Kernel environment. Each Kernel has its own CCF
               located in the registry under the key
               HKEY_LOCAL_MACHINE\SYSTEM\Current
               ControlSet\Services\xxx_dmkyy\ccf where xxx indicates the BASIS release
               number and yy indicates the individual Kernel.

               Windows provides an application for viewing and modifying entries in the
               registry. This application is found in the %SYSTEM%\system32
               directory. You can run the program RegEdt32.exe to edit the registry.
               When editing registry entries, variables, values, or files, use extreme
               caution.

               When a Kernel is installed on a 4.0 or later version of Windows, the
               registry path for that Kernel's CCF entry is added to the
               HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Secire
               PipeServers\ Winreg\AllowedPaths\Machine entry if the latter entry exists.
               Storing the CCF path in the Machine entry allows access to the CCF
               registry entry from applications running on another Windows machine.

               The following three types of information are included in each CCF record:
                    Kernel Log Files. Included are the Kernel name and the name and
                     location of both the Kernel‟s output and the Sort Kernel‟s output.
                    Inter-Process Communications (IPC) Parameters. Included are
                     parameters that control the interaction between the Kernel and the
                     BASIS user processes.
                    Network Communications Parameters. Included are parameters that
                     control the interaction between the Kernel and the BASIS user process
                     when the Kernel and the user are on different network nodes.

                   WARNING       Do not change the CCF parameters while the Kernel is
                   running. Users signing on to the Kernel may end up with different
                   values for these parameters—making the system unusable.




140  Communications
Kernel Log Files on Windows
Windows

Kernel Log File

Indicates the name and location that receives messages output by the
Kernel.

Sort Kernel Log File

Indicates the name and location that receives messages output by the Sort
Kernel.




                                                       Communications  141
               Kernel Name
               Indicates the Kernel‟s name in the form dmkxy where x indicates the
               Kernel set A:Z and y designates the Kernel number within the set.
               IPC Parameters on Windows
               Windows

               These parameters are used to define the Kernel and user process
               communications:
               Communication buffer size

               Communication buffer size in hexadecimal bytes. The default value is
               4096. This parameter determines the size of each communication buffer
               that is allocated in shared memory. The buffer is used for communications
               between the Kernel and the user process. One buffer is allocated for each
               communications line (see Max lines). This value must be in multiples of
               512 bytes and be between 1024 and 65536. This parameter may affect
               performance significantly!
               If applications using the Kernel characteristically use very large records,
               increasing the size reduces the number of packets the Kernel and a user
               process must exchange to retrieve or update a database record. Increasing
               the buffer size increases the Kernel process memory by (delta * Max lines)
               and could contribute to excessive paging. Decreasing the buffer size
               increases the number of packets exchanged between the Kernel and the
               user process, but the Kernel process memory requirements are decreased.

               This would be one approach to finding a good value:
               1. Increase the buffer size to the size of the median record size for the
                  application.
               2. If paging increases substantially, split the difference between the
                  previous buffer size and the amount tried in step 1 (in 512-byte
                  chunks).
               3. Repeat these steps until a good balance between paging and speed of
                  operations is achieved. For more information on tuning, see “Tuning
                  the System.”


142  Communications
Max lines

Maximum number of IPC communications lines (1:511). The default is
32. This is the maximum number of local (non-network) users that can
communicate with the Kernel at any given time. This allocation is for user
processes that are running on the same node as the Kernel process (local
processes). Local processes use the Inter-Process Communications (IPC)
facilities for communications between user and Kernel. It is independent
of the allocation of communications lines for network users. The
maximum number of network communications lines is defined by
Network max lines (see below). Allocating more IPC lines than needed
causes excess shared memory to be allocated (see Communication buffer
size parameter above).




                                                       Communications  143
               User group

               The Windows group to which users must belong in order to communicate
               with the Kernel. The special group name $ALL indicates that users do not
               have to belong to a specific Windows group in order to communicate with
               the Kernel. The default is $ALL.

               Network Communications Parameters on Windows
               Windows

               These parameters are used in defining the Kernel and user process
               communications when the Kernel process and the BASIS user process are
               running on different network nodes. These parameters are very similar to
               the preceding IPC parameters.

               Network buffer size

               Network communication buffer size in hexadecimal bytes. The default is
               4096. This parameter determines the size of each network communication
               buffer. The buffer is used for communications between the Kernel and the
               user process when the user process and the Kernel are running on different
               nodes. One buffer is allocated for each network communications line (see
               Network max lines). This value must be in multiples of 512 bytes and be
               between 1024 and 65536.

               Network max lines

               This is the maximum number of network communications lines (1:511).
               The default is 10. This is the maximum number of remote user processes
               that can communicate with the Kernel at any given time. This allocation is
               for user processes that are running on a node different from the node
               running the Kernel process. Such user processes must use network
               communications facilities. Network max lines is independent from the
               allocation of lines for non-network users. The maximum number of non-
               network communications lines is defined by Max lines (see above).
               Allocating more lines than needed causes excess memory to be allocated
               (see Network buffer size parameter above).



144  Communications
Network Status

This indicates whether network communications is installed. The default
is 0x1 which indicates “true.” Setting this value to zero (0x0) restricts
access to this Kernel from other nodes.




                                                       Communications  145
Communications Control Facility on UNIX and VMS
               UNIX, VMS

               The communications techniques used within BASIS are grouped into two
               categories: Inter-Process Communications (IPC) and Network
               Communications (DMNAM). Inter-Process Communications are used
               when the user program and the Kernel operate on the same computer.
               Network Communications are used when the user program and the Kernel
               are on different network nodes.

               Three files are used to control communications. They are the
               Communications Control Facility (CCF), the Global Database Directory
               (GDD), and the Kernel Directory (KD). Inter-Process Communications
               use the CCF and the KD. Network Communications use all three files.
               The System Administrator uses DMCCF (Communications Control
               Facility) to update these files.

               The Inter-Process Communications (IPC) software used by the BASIS
               system is controlled by the Communications Control Facility (CCF).
               BASIS users and Kernels use the CCF to coordinate communications. The
               Kernel also uses the CCF to process operating options.

               The CCF contains parameters for Kernels in a Kernel Set. It allows each
               Kernel configuration to be customized if necessary, when operating
               multiple Kernels. For more information on Kernel Set operation, see
               “Tuning the System.”

               A CCF is defined for each Kernel Set. A Kernel Set is one to nine Kernels
               that share an Authority Database (ADB) and CCF. Normally the Kernel
               Set‟s CCF is located in the directory referenced by the environment
               variable DM_RUNDMK for UNIX and the logical DM$RUNDMK for
               VMS. The Kernels operating out of this directory use the CCF referenced
               by the environment variable DM_CCF for UNIX and the logical DM$CCF
               for VMS at the time the Kernel is started. For more information about
               environment variables, see BASIS Reference, “Environment Variables.”



146  Communications
BASIS user processes use the same CCF for the Kernel Set they are
referencing when a BASIS signon is performed. Opening databases
outside the Kernel Set can be performed via DMNAM (Network Access
Module) after the initial signon. In the latter situation, DMNAM locates
the appropriate CCF by consulting the Global Database Directory (GDD)
and the Kernel Directory (KD).




                                                       Communications  147
               The CCF is part of the Kernel environment. Other parts of the
               environment, the Authority Database and work files, are normally copied
               as part of the installation procedure described in the Installation Guide.
               DMCCF must be used to update the CCF whenever a site moves from one
               release to another. The CCF does NOT copy forward to the new release.

               A CCF may contain 18 records. Records 1 through 9 are used by Kernels
               1 through 9 of a Kernel Set. Kernel number 1 uses record 1, Kernel 2 uses
               record 2, etc. Records 11 through 19 are used by the Sort Kernels for
               Kernels 1 through 9. Sort Kernel 1 uses record 11, Sort Kernel 2 uses
               record 12, etc.

               The following types of information are included in each CCF record:
                  Kernel Run Parameters. These include the Kernel process name, its
                   password, names of image and log files, etc.
                  Kernel Process Resource Controls. These include parameters
                   corresponding to priority, quotas, and privileges under which the
                   Kernel process operates.
                  Inter-Process Communications (IPC) Parameters. Included are
                   parameters that control the interaction between the Kernel and the
                   BASIS user processes.
                  Network Communications Parameters. Included are parameters that
                   control the interaction between the Kernel and the BASIS user process
                   when the Kernel and the user are on different network nodes.

               Kernel Run Parameters on UNIX
               UNIX

               These parameters are used to set up a Kernel to run:

               RECORD_TAG

               Internal tag used to verify that the file is indeed a CCF.

               Record number




148  Communications
Kernel (Control module) number. A number (1:9, 11:19) identifies the
Kernel or Sort Kernel to which the CCF record applies.




                                                     Communications  149
               IMAGE

               Image file name. This is the image executed when the Kernel process is
               created by DMSA. It is usually of the form

                   $DM_RUNDMK/dm#a_xx
               where # is replaced by „s‟ or „k‟ and xx is the database. The Kernel will
               run with the UID and GID of the image file. The setuid and setgid bits for
               this file must be on.

               The following tunable parameters for DMK are settable in the IMAGE file
               specified in the CCF record:

               DMK_FILE_LIMIT

               ulimit value for files created by DMK.
               DMK_PRIORITY

               Process priority of DMK.
               LOG

               Error file name. The default is $DM_RUNDMK/dm#a?_xx.log where
               “xx” is the Kernel number (CM_NR). This is the log file assigned to the
               IMAGE (above) when the Kernel process is created by DMSA. Certain
               UNIX error messages are written to this file. It is equivalent to stderr and
               stdout of an interactive process.
               PW

               BASIS Kernel Password. This is the password that must be supplied on
               the DMSA BEGIN statement when the Kernel is started. The password
               can be an integer or identifier that contains letters and/or digits. Only the
               first 8 characters are used. The default value is PW.
               Process name

               UNIX Process name of the Kernel. All Kernel process names must have a
               format of xxxxx_rr_Knn where xxxxx is the Kernel Name, rr is a BASIS
               release ID, and nn is the Kernel number (CM_NR) within the Kernel Set.



150  Communications
For example, the process name dmka1_L1_k01 is for the Kernel named
dmka1, release L1, and the Kernel is Kernel 1 of the set. All Kernel
Names must be unique and five characters in length. The letter “k” must
precede the Kernel Number for a BASIS Kernel and the letter “s” must
precede the Kernel Number for a Sort Kernel. The Kernel Number must
be a value from “01” to “19”, where 01 to 09 are used for Kernels and 11
to 19 used for Sort Kernels.




                                                       Communications  151
               IPC Parameters on UNIX
               UNIX

               These parameters are used to define the Kernel and user process
               communications:

                 WARNING:      Do not change the CCF IPC parameters while the
                 Kernel is running. Users signing on to the Kernel may end up with
                 different values for these parameters—making the system unusable.

               Hostile Environment Flag

               Environment (0=Non-hostile; 1=Hostile). The default value is 0. This
               parameter indicates whether or not the Kernel must protect the shared
               memory used in Inter-Process Communications. By setting this parameter
               to 1, the shared memory is prevented from being in the users address
               space.

               Note:    The hostile environment is currently not supported on UNIX. This
               flag is ignored.

               Communication buffer size

               Communication buffer size in bytes. The default value is 2048. This
               parameter determines the size of each communication buffer that is
               allocated in shared memory. The buffer is used for communications
               between the Kernel and the user process. One buffer is allocated for each
               communications line (see Max lines). This value must be in multiples of
               512 bytes and be between 1024 and 4096. This parameter may affect
               performance significantly!
               If applications using the Kernel characteristically use very large records,
               increasing the size reduces the number of packets the Kernel and a user
               process must exchange to retrieve or update a database record. Increasing
               the buffer size increases the Kernel process memory by (delta * Max lines)
               and could contribute to excessive paging. Decreasing the buffer size



152  Communications
increases the number of packets exchanged between the Kernel and the
user process, but the Kernel process memory requirements are decreased.

This would be one approach to finding a good value:
1. Increase the buffer size to the size of the median record size for the
   application.
2. If paging increases substantially, split the difference between 2048 and
   the amount tried in step 1 (in 512-byte chunks).
3. Repeat these steps until a good balance between paging and speed of
   operations is achieved. For more information on tuning, see “Tuning
   the System.”




                                                         Communications  153
               Max lines

               Maximum number of IPC communications lines (1:511). The default is
               32. This is the maximum number of local (non-network) users that can
               communicate with the Kernel at any given time. This allocation is for user
               processes that are running on the same node as the Kernel process (local
               processes). Local processes use the Inter-Process Communications (IPC)
               facilities for communications between user and Kernel. It is independent
               of the allocation of communications lines for network users. The
               maximum number of network communications lines is defined by
               Network max lines (see below). Allocating more IPC lines than needed
               causes excess global memory to be allocated (see Communication buffer
               size parameter above). Max lines + Network max lines must not exceed
               SIGNON_LIMIT. (See the Installation Guide)

               Protocol number

               Communications protocol number. The protocol number is an internal
               number assigned by DMCCF. It insures that the Kernel and the user
               processes are using the same communications protocol.

               User group

               User group name. The UNIX group name of the user who will be
               accessing this control module. The special group name $ALL will allow
               kernel access all names.

               Network Communications Parameters on UNIX
               UNIX

               These parameters are used in defining the Kernel and user process
               communications when the Kernel process and the BASIS user process are
               running on different network nodes. These parameters are very similar to
               the preceding IPC parameters.




154  Communications
 WARNING:      Do not change the CCF IPC parameters while the
 Kernel is running. Users signing on to the Kernel may end up with
 different values for these parameters—making the system unusable.

Network status flag

Network communications status flag. The default value is 0. This
parameter indicates whether the Kernel is available for communications
with remote users (user processes on remote nodes). A value of 0
indicates the Kernel is not available for remote usage and a value of 1
indicates it is available for remote usage.




                                                       Communications  155
               Network buffer size

               Network communication buffer size in bytes. The default is 2048. This
               parameter determines the size of each network communication buffer.
               The buffer is used for communications between the Kernel and the user
               process when the user process and the Kernel are running on different
               nodes. One buffer is allocated for each network communications line (see
               Network max lines). This value must be in multiples of 512 bytes and be
               between 1024 and 16384.

               Network max lines

               This is the maximum number of network communications lines (1:511).
               The default is 10. This is the maximum number of remote user processes
               that can communicate with the Kernel at any given time. This allocation is
               for user processes that are running on a node different from the node
               running the Kernel process. Such user processes must use network
               communications facilities. Network max lines is independent from the
               allocation of lines for non-network users. The maximum number of non-
               network communications lines is defined by Max lines (see above).
               Allocating more lines than needed causes excess memory to be allocated
               (see Network buffer size parameter above). Network max lines + Max
               lines must not exceed SIGNON_LIMIT. (See the Installation Guide)

               Network protocol number

               Network Communications protocol number. The network protocol
               number is an internal number assigned by DMCCF. It ensures that the
               Kernel and the user processes are using the same network communications
               protocol.

               Kernel Run Parameters on VMS
               VMS

               These parameters are used to set up a Kernel to run:

               RECORD_TAG




156  Communications
Internal tag used to verify that the file is indeed a CCF.

CM_NR

Kernel (Control module) number. A number (1:9, 11:19) identifies the
Kernel or Sort Kernel to which the CCF record applies.




                                                             Communications  157
               IMAGE

               Image file name. This is the image executed when the Kernel process is
               created by DMSA. It should always be
               SYS$SYSTEM:LOGINOUT.EXE.

               INPUT

               Input file name. The default is DM$RUNDMK:DMIxx.DAT where “xx”
               is the Kernel number (CM_NR). This is the input file the IMAGE (above)
               executes when the Kernel process is created by DMSA. This is the
               command procedure that runs the Kernel.

               OUTPUT

               Output file name. The default is DM$RUNDMK:DMOxx.DAT where
               “xx” is the Kernel number (CM_NR). This is the output file assigned to
               the IMAGE (above) when the Kernel process is created by DMSA. This is
               the log file of the Kernel. This is equivalent to SYS$OUTPUT of an
               interactive process. The Kernel writes activity information including
               recovered databases, errors, invalid signon attempts, etc., to this file.

               ERROR

               Error file name. The default is DM$RUNDMK:DMExx.DAT where “xx”
               is the Kernel number (CM_NR). This is the error file assigned to the
               IMAGE (above) when the Kernel process is created by DMSA. Certain
               VMS error messages are written to this file. It is equivalent to
               SYS$ERROR of an interactive process. This file is used very seldom.

               UIC

               VMS User Identification Code of the Kernel process. This should be the
               UIC of the DMPROD account. The UIC is set when the system is
               installed.

                   Format: [group,member]

               where:



158  Communications
   group & member are octal numbers .

PW

BASIS Kernel Password. This is the password that must be supplied on
the DMSA BEGIN statement when the Kernel is started. The password
can be an integer or identifier that contains letters and/or digits. Only the
first 8 characters are used. The default value is PW.




                                                          Communications  159
               PROCNAME

               VMS Process name of the Kernel. All Kernel process names must have a
               format of xxxxx_rr_Knn where xxxxx is the Kernel Name, rr is a BASIS
               release ID, and nn is the Kernel number (CM_NR) within the Kernel Set.
               For example, the process name DMKA1_L1_K01 is for the Kernel named
               DMKA1 release L1 and the Kernel is Kernel 1 of the set. All Kernel
               Names must be unique and five characters in length. The letter “K” must
               precede the Kernel Number for a BASIS Kernel and the letter “S” must
               precede the Kernel Number for a Sort Kernel. The Kernel Number must
               be a value from “01” to “19”, where 01 to 09 are used for Kernels and 11
               to 19 used for Sort Kernels.

               STATUS

               Kernel status options. The default is NOUAF. The VMS status options
               are described below. In addition the status option “NO STATUS” may be
               selected while using the DMCCF utility. This indicates that no options are
               selected.

               Under normal circumstances, these options are not changed from those
               sent on the release tape. The only option a site may wish to consider
               changing is NOUAF.


               DISAWS           Disable system-initiated working set adjustment.

               BATCH            Batch (non-interactive) process (DETACH privilege
                                required).

               NOACNT           Do not perform accounting (NOACNT privilege
                                required).

               NOSWAP           Inhibit process swapping (PSWAPM privilege
                                required).

               SSFE             Enable system service failure exception in user mode
                                (SSFEXCU).



160  Communications
NORESWAIT   Disable system service resource wait mode
            (SSRWAIT).

NOUAF       Do not check authorization file if the process is
            detached and the image is LOGINOUT.EXE. This
            formerly was referred to as LOGIN in VMS manuals.

NETWRK      Process is a network connect object (DETACH
            privilege required).




                                                Communications  161
               Kernel Process Resource Controls on VMS
               VMS

               If the STATUS option NOUAF is selected, Kernel privileges, quotas, and
               base priority are taken from the values of the CCF parameters described
               below. Otherwise, they are taken from the UAF (the VMS User
               Authorization File) for the account starting the Kernel (usually
               DMPROD).

               When the Kernel is started, the privileges and quotas selected are
               requested for the Kernel‟s process. All may not be granted however. The
               privileges and quotas requested are minimized with those of the owner
               UAF (which should be DMPROD if the Kernel was started up correctly;
               see the Installation Guide). In the case of privileges, installation of the
               Kernel image may allow it to run with privileges not granted here or even
               to the DMPROD UAF. When the Kernel is installed with privileges, those
               privileges remain until the Kernel is deinstalled.

               BASPRI

               This is the base priority of the Kernel. The default value is 6. The priority
               selected should be the same as the priority of most of the interactive users
               of this Kernel.

               PRIVILEGES

               The following VMS privileges may be granted to the Kernel process (the
               default privileges are marked with an asterisk):


               ACNT                    ALLSPOOL                ALTPRI

               BUGCHK                  BYPASS                  CMEXEC

               *CMKRNL                 *DETACH                 DIAGNOSE

               *EXQUOTA                *GROUP                  *GRPNAM



162  Communications
LOG_IO                MOUNT                 *NETMBX

OPER                  PFNMAP                PHY_IO

*PRMCEB               *PRMGBL               PRMMBX

PSWAPM                SETPRV                SHMEM

*SYSGBL               SYSLCK                *SYSNAM

*SYSPRV               *TMPMBX               VOLPRO

*WORLD

If the LEVEL parameter (discussed below) is SYSTEM, the Kernel needs
the privileges, DETACH, WORLD, PRMCEB, and PRMGBL. If it is
GROUP, the Kernel needs the privileges, DETACH, GROUP, PRMCEB,
and PRMGBL.

DETACH privilege is needed in order for the Kernel to startup the Sort
Kernel. PRMCEB is needed in order to coordinate communications with
BASIS user processes. PRMGBL is needed to create global
communications sections used for communications with user processes.

Process Quotas

VMS process quotas for the Kernel process. The following quotas are
described in the VMS system management documentation. The quotas
recommended in the installation instructions should be used. However,
fine-tuning WSDEFAULT and WSQUOTA may result in overall
improved VMS system throughput if competition for memory is extreme.
For a discussion of these and the NOSWAP option, see “Tuning the
System.”


ASTLM                            Asynchronous Trap limit

BIOLM                            Buffered I/O limit



                                                      Communications  163
               BYTLM                              Buffered I/O byte count quota

               CPULM                              CPU time limit

               DIOLM                              Direct I/O quota

               FILLM                              Open file quota

               PGFLQUOTA                          Paging file quota

               PRCLM                              Subprocess quota

               TQELM                              Timer queue entry quota

               WSDEFAULT                          Default working set size

               WSQUOTA                            Working set size quota

               For the Kernel to operate properly, the following settings should be
               coordinated:
                  the VMS sysgen parameter Channel Count (CHANNELCNT)
                  the VMS Open file quota (FILLM) for the DMPROD account
                  the DMCCF Open file quota (FILLM) field

               Follow these instructions to determine each of these settings on your
               system:


               To determine this setting          Issue these commands

               VMS sysgen Channel Count           $MCR SYSGEN

               (CHANNELCNT)                       SYSGEN>SHOW CHANNELCNT

               DMPROD account‟s VMS               $SHOW PROCESS/QUOTA

               Open file quota (FILLM)

               DMCCF Open file quota              $DMCCF ACTION=READ/MODE=DIALOG




164  Communications
To determine this setting         Issue these commands
(FILLM)

FILLM is the maximum number of files the Kernel job can have open at
one time. The VMS Open file quota (FILLM) for the DMPROD account
and the DMCCF Open file quota (FILLM) field should be equal.
Therefore, FILLM should be greater than or equal to the maximum
number of files the Kernel would try to have open at the same time, which
is determined by the calculation

   USERS_PER_KM*3 + KM_DBFP_LE + SYSTEM_FILES +
   OS_FILES




                                                      Communications  165
               where
               USERS_PER_KM           is the BASIS SYSGEN parameter
                                      USERS_PER_KM. Use the DMSA command
                                      SHOW/SYSGEN USERS_PER_KM to
                                      determine the value of this parameter on your
                                      system.

               KM_DBFP_LE             is the BASIS SYSGEN parameter
                                      KM_DBFP_LE. Use the DMSA command
                                      SHOW/SYSGEN KM_DBFP_LE to determine
                                      the value of this parameter on your system.

               SYSTEM_FILES           is 216. This is the total of


                        10   sort files
                         8   general files (e.g., dump, ADB, etc.)
                       198   thread-related files (2 * the max_number_of_threads; the DMSA
                             command SHOW/SYSGEN THREADS will indicate the maximum
                             number of threads)
                   +___
                    216


               OS_FILES               is 8. These are job-related files opened as the
                                      Kernel begins execution (e.g., SYS$OUTPUT).

               Using the BASIS defaults, FILLM should be greater than or equal to 520.

               The VMS sysgen parameter CHANNELCNT controls the maximum
               number of channels a process can use at one time. Each open file uses a
               channel, and several other operations performed by the Kernel use
               channels:
                  certain VMS system services used while executing a request
                  each signon to the Kernel via DMNAM
                  if the Kernel makes itself a Network Kernel via DMNAM



166  Communications
   when the Kernel opens up the Inter Process Communications file

The VMS sysgen parameter CHANNELCNT should be set to a value
which is greater than or equal to

    FILLM +1 + (CCF.NETMAXLINENR+1) + 99




                                                     Communications  167
               Using the BASIS defaults,
                    for a system without DMNAM, CHANNELCNT should be greater
                     than or equal to 620
                    for a system with DMNAM, CHANNELCNT should be greater than
                     or equal to 631

               IPC Parameters on VMS
               VMS

               These parameters are used to define the Kernel and user process
               communications:

                   WARNING       Do not change the CCF IPC parameters while the
                   Kernel is running. Users signing on to the Kernel may end up with
                   different values for these parameters—making the system unusable.

               CLUSTER

               Common Event Flag Cluster name. (See VMS system services
               documentation). If the LEVEL parameter (described below) is set to
               GROUP operations, this is the name of the event flag cluster that the
               Kernel and the users of the GROUP use to coordinate communications.
               When the LEVEL parameter is set to SYSTEM, the CLUSTER parameter
               is not used.

               ENVIRONMENT

               Environment (0=Non-hostile; 1=Hostile). The default value is 0. This
               parameter indicates whether or not the Kernel must protect the global
               sections used in Inter-Process Communications. If the environment is
               hostile, the Kernel unprotects the global sections each time it needs to
               communicate with a user and reprotects them when it finishes updating the
               global sections. This overhead is normally not needed. By setting this
               parameter to 1, the Global Communications Table is prevented from being
               in the users address space.



168  Communications
IPC_BUF_LC

Communication buffer size in bytes. The default value is 1024. This
parameter determines the size of each communication buffer that is
allocated in global memory. The buffer is used for communications
between the Kernel and the user process. One buffer is allocated for each
communications line (see MAXLINENR). This value must be in
multiples of 512 bytes and be between 1024 and 16384. This parameter
may affect performance significantly.




                                                       Communications  169
               If applications using the Kernel characteristically use very large records,
               increasing the size reduces the number of packets the Kernel and a user
               process must exchange to retrieve or update a database record. Increasing
               the buffer size increases the Kernel process memory by (delta *
               MAXLINENR) and could contribute to excessive VMS

               Paging. Decreasing the buffer size increases the number of packets
               exchanged between the Kernel and the user process, but the Kernel
               process memory requirements are decreased.

               This would be one approach to finding a good value:
               1. Increase the buffer size to the size of the median record size for the
                  application.
               2. If VMS paging increases substantially, split the difference between
                  1024 and the amount tried in step 1 (in 512-byte chunks).
               3. Repeat these steps until a good balance between paging and speed of
                  operations is achieved. For more information on tuning, see “Tuning
                  the System.”

               GLOBAL

               Global Section name. This parameter determines the name of the VMS
               global memory section that the Kernel shares with user processes. VMS
               system services refer to this as GDSNAM. The name must be different for
               each Kernel; otherwise the Kernels attempt to share the same memory.

               LEVEL

               Communications level {SYSTEM | GROUP}. Either SYSTEM or
               GROUP must be entered. SYSTEM level allows users of the Kernel to be
               from any VMS account group. GROUP level requires that all users of the
               Kernel be from the same VMS account group as the group assigned via the
               UIC parameter (above).

               MAXLINENR

               Maximum number of IPC communications lines (1:511). The default is
               32. This is the maximum number of local (non-network) users that can


170  Communications
communicate with the Kernel at any given time. This allocation is for user
processes that are running on the same node as the Kernel process (local
processes). Local processes use the Inter-Process Communications (IPC)
facilities for communications between user and Kernel. It is independent
of the allocation of communications lines for network users. The
maximum number of network communications lines is defined by
NETMAXLINENR (see below). Allocating more IPC lines than needed
causes excess global memory to be allocated (see the IPC_BUF_LC
parameter above). MAXLINENR + NETMAXLINENR must not exceed
SIGNON_LIMIT. (See the Installation Guide)




                                                       Communications  171
               PROTOCOL

               Communications protocol number. The protocol number is an internal
               number assigned by DMCCF. It insures that the Kernel and the user
               processes are using the same communications protocol.

               SECTFILE

               Global Section File name. This parameter determines the name of the
               VMS global section file. This file is used as the backing store for pages of
               memory. Currently this file is implemented with the option of using the
               VMS paging file so the Section File is not used.

               Network Communications Parameters on VMS
               VMS

               These parameters are used in defining the Kernel and user process
               communications when the Kernel process and the BASIS user process are
               running on different network nodes. These parameters are very similar to
               the preceding IPC parameters.

                 WARNING       Do not change the CCF IPC parameters while the
                 Kernel is running. Users signing on to the Kernel may end up with
                 different values for these parameters—making the system unusable.

               NET_BUF_LC

               Network communication buffer size in bytes. The default value is 1464.
               This parameter determines the size of each network communication buffer.
               The buffer is used for communications between the Kernel and the user
               process when the user process and the Kernel are running on different
               nodes. One buffer is allocated for each network communications line (see
               NETMAXLINENR). This value must be in multiples of 8 bytes and be
               between 1024 and 16384.

               NETMAXLINENR




172  Communications
         This is the maximum number of network communications lines (1:511).
         The default is 10. This is the maximum number of remote user processes
         that can communicate with the Kernel at any given time. This allocation is
         for user processes that are running on a node different from the node
         running the Kernel process. Such user processes must use network
         communications facilities. NETMAXLINENR is independent from the
         allocation of lines for non-network users. The maximum number of non-
         network communications lines is defined by MAXLINENR (see above).
         Allocating more lines than needed causes excess memory to be allocated
         (see NET_BUF_LC parameter above). NETMAXLINENR +
         MAXLINENR must not exceed SIGNON_LIMIT.

         NETPROTOCOL

         Network Communications protocol number. The network protocol
         number is an internal number assigned by DMCCF. It ensures that the
         Kernel and the user processes are using the same network communications
         protocol.

         NETSTATUS

         Network communications status flag. The default value is 0. This
         parameter indicates whether the Kernel is available for communications
         with remote users (user processes on remote nodes). A value of 0
         indicates the Kernel is not available for remote usage and a value of 1
         indicates it is available for remote usage.



Network Communications - DMNAM
         All


         DMNAM Overview
         The BASIS Network Access Method (DMNAM) allows a user program to
         define, access, and update a database residing on another network node.
         Databases available for such usage are known as Global Databases. Users
         can simultaneously use databases on remote nodes and the local node.



                                                                Communications  173
               These features are completely transparent to the user program. As such,
               no programming changes are necessary for a user to switch from a local
               database to a global database.

               DMNAM is a useful tool for the system manager. By using DMNAM,
               you can achieve better load balancing by moving the load on a network
               from node to node. For instance, an application involving many end users
               and a centralized, integrated database can be spread across numerous
               network nodes. Users do not need to be concerned about which node they
               are logged on to. As long as the database is known to DMNAM as
               “global”, it can be accessed (queried and updated) from any node of the
               network. DMNAM is not a utility. Rather, it is a set of routines
               integrated into the User Program Interface (UPI) and the Kernel. Each
               user program links to the BASIS library of UPI routines. These routines
               handle all communications between the user program and the appropriate
               Kernel.

               Each database is “owned” by one and only one Kernel (read-only
               databases can be shared by multiple Kernels). All update and access is
               done by that Kernel. When a user requires access to a global database,
               DMNAM opens a line of communications with the

               appropriate Kernel. DMNAM determines the location of the appropriate
               Kernel for each database being used. All user requests for each database
               are then sent to the proper Kernel. The user program need not know the
               location of the Kernel.

               DMNAM locates the proper Kernel by consulting the Global Database
               Directory (GDD) or the Kernel Directory (KD). The GDD contains one
               entry for each database accessible to users on remote nodes. Each entry
               contains the name of the controlling Kernel. The KD contains an entry for
               each Kernel, the node name, and any other information required to access
               the Kernel.. The SA updates these directories when necessary.

               You need DMNAM in two situations:
                  If a user and the Kernel are on different nodes. For example, a user‟s
                   primary Kernel, DMKA1, runs on Node A. If the user needs access to
                   a database on Node B, where Kernel DMKA2 controls that database,
                   NAM would provide an access path to the other database.


174  Communications
   If the user needs to use a Kernel in a different Kernel set (on the same
    node) and the user does not set his primary Kernel (symbol
    DM_PRIMARY_KERNEL) to that Kernel, NAM would provide
    access to the other Kernel Set.

Related Terminology
To aid in the understanding of DMNAM, certain definitions are necessary.
From the perspective of DMNAM, the following definitions are assumed:




                                                         Communications  175
               Network        A set of computers (nodes) having the ability to
                              communicate with one another. There is not a base of
                              common files. Each file is “owned” by a network node.
                              A three-node network is illustrated below.




                  NODE A                                   NODE B




     NODE A                                                            NODE B
      FILES                                                             FILES


                                         NODE C




                                          NODE C
                                           FILES


                       Figure 5-1: A 3-node network




176  Communications
    VMS

     Cluster         A network with the added feature of a shared set of files.
                     Files are not “owned” by any node of the cluster. The
                     primary difference between a cluster and a network is the
                     shared file base feature of a cluster. The following figure
                     illustrates a three node cluster.




NODE X                            NODE Y                         NODE Z




                                CLUSTER
                                 FILES


               Figure 5-2: A 3-node cluster




                                                                Communications  177
               It is possible to have a network/cluster combination. The following figure
               illustrates a five-node network with three of the nodes forming a cluster.



             NODE                                                           NODE
               A                                                              B




     NODE A                                                                   NODE B
      FILES                                                                    FILES

                       NODE                 NODE                 NODE
                         X                    Y                    Z




                                          CLUSTER
                                           FILES


                       Figure 5-3: A 5-node network with a 3-node cluster


               All

               Local Node             is the network node running the user‟s current
                                      process. A local user is a user on the local node.

               Remote Node            is a node of the network other than the user‟s local
                                      node. Consider, for example, a network with nodes
                                      A, B, and C. If a user‟s process is running on node
                                      A, nodes B and C are considered remote nodes.
                                      Node A is the local node. A remote user is a user on



178  Communications
                     a remote node.

Primary Kernel       Each BASIS user has one “primary” Kernel that is
                     used for non-database specific accesses (e.g.
                     DMSA SIGNON). The name of the primary Kernel
                     is made known to the system via the host variable
                     DM_PRIMARY_KERNEL. The value of this
                     symbol can be changed as necessary. The primary
                     Kernel is usually running on the user‟s local node.
                     It is possible, though, to have a Kernel on a remote
                     node be a user‟s primary Kernel although this is not
                     recommended unless a Kernel never runs on the
                     user‟s local node.

Secondary Kernel     is any Kernel other than the user‟s primary Kernel.
                     One user‟s secondary Kernel can be another user‟s
                     primary Kernel.

Kernel Set           is a set of one to nine Kernels that share the same
                     Authority Database (ADB). On UNIX and VMS,
                     they also share the Communications Control
                     Facility (CCF). The CCF contains one record for
                     each Kernel. Typically, each Kernel of a Kernel Set
                     runs on a separate node although it is possible to
                     run multiple Kernels on the same node. Kernel
                     Sets should use a common shared file base for ADB
                     and CCF files.

DMNAM Architecture
Each BASIS database is under the control of one and only one Kernel
(read only databases can be shared by multiple Kernels). All access to a
database (retrieval and update) is done via its controlling Kernel. In order
for a program to communicate with the proper Kernel, the SA must
Windows

use the Kernel directory utility or registry to maintain the Kernel directory.



                                                          Communications  179
               UNIX, VMS

               use the DMCCF utility to create and maintain the Global Database
               Directory file and the Kernel Directory file. A more detailed description
               of the DMCCF utility appears later in this chapter.




180  Communications
Global Database Directory (GDD)
UNIX, VMS

The purpose of this directory is to indicate which Kernel (thus Kernel Set
and ADB) is in control of each global database. A “Global Database” is a
database that is available to users on remote nodes and other Kernel sets.
These databases can be viewed as remote databases, but the term “Remote
Database” is relative. The same database can be remote (on another node)
to one user and local (on the same node as the user) to another. The term
“remote database” should be avoided due to its relative nature. If a
database is not listed in the GDD, it is considered a local database.

A database is not automatically available for remote usage. This occurs
only when the SA makes an entry for the database in the GDD. To prevent
a database from being accessed by remote users, no entry is made in the
GDD for that database. The full set of BASIS security features (privacy,
privileges, etc) is available to global databases as well as local databases.

The GDD contains one entry per global database. Each entry lists the
“Global Database Alias” and the “Global Database Primary Name” and
specifies the Kernel name to use to process the requests related to the
global database.

The “Global Database Alias” is the name used to identify a global
database. It is also the key to the records in the GDD. As such, each
global database alias must be unique.

The “Global Database Primary Name” is the name used to identify a
database to the Kernel that controls the database. This name is also the
key to the database record stored in the Authority Database (ADB) of the
specified Kernel. This name is used when a database is created and
uniquely identifies a database within a Kernel Set.

The “Global Database Alias” and the “Global Database Primary Name”
should be the same. In so doing, confusion can be minimized. This is not
always possible when different sets of local databases have been
established and are then later merged.



                                                         Communications  181
               The “Kernel Name” is the name used to identify a Kernel network-wide.
               It is also the key to the Kernel records in the Kernel Directory (KD). Each
               Kernel name is unique.

               The following table illustrates a small, but typical GDD:




182  Communications
Global Database      Global Database         Kernel
Alias                Primary Name            Name

AJAX                 AJAX                    DMKA1

FINANCE              FINANCE                 DMKB6

KILROY               KILROY                  DMKA1

SMITH1               AJAX                    DMKB6

There are four databases available for use by remote users. They are
named AJAX, FINANCE, KILROY, and SMITH1 (their respective global
aliases). Databases AJAX and KILROY are controlled by the Kernel
named DMKA1 while databases FINANCE and SMITH1 are controlled
by the Kernel named DMKB6. Global database SMITH1 has an alias that
is different from its primary name, which is AJAX. The reason for this is
that the alias AJAX is already used for another database. Since all global
database aliases must be unique, another name had to be used. Realize
that there is not necessarily any relationship between database AJAX
(primary name) on Kernel DMKA1 and database AJAX (primary name)
on Kernel DMKB6. They just happened to have the same primary name.
This situation can occur when multiple networks are merged into one.

The database alias is used to refer to a global database. In the example
above, all users of AJAX (primary name) on Kernel DMKB6 must refer to
the database as SMITH1. An obvious problem arises when users refer to
this database as AJAX as this would be AJAX on DMKA1, not DMKB6.

The dynamic binding of the database name and version can be utilized
with global databases. This is a useful feature when programs have been
written referring to a database via its primary name, but the database‟s
alias is different from its primary name. The dynamic binding is
performed before the GDD is searched. Consider the GDD shown above.
Assume user programs were written to use the AJAX (primary name)
database on Kernel DMKB6, but the database was not referred to via its
alias of SMITH1. To prevent having to change the programs, the global


                                                       Communications  183
               symbol DM_DB_AJAX can be set to “SMITH1” before the database is
               opened. DMNAM then searches the GDD looking for SMITH1 rather
               than AJAX even though the program refers to AJAX, not SMITH1.

               When you define a global database, always try to make the alias and
               primary name the same. The best approach is to use DMCCF to establish
               the alias and primary names prior to creating the database. By “staking
               out” a good alias, you will avoid confusion over differing alias and
               primary names. If you‟re only using one Kernel Set, a GDD is not
               necessary. If you will be using multiple Kernel Sets and the databases
               must be shared, the GDD is required.

               Kernel Directory (KD) on Windows
               Windows

               The Kernel Directory indicates where a Kernel may be running. The
               Kernel Directory contains the Kernel names and a search list of nodes for
               each of the Kernel names. Below is an example of a Kernel Directory on
               Windows operating systems.




184  Communications
 Figure 5-4: Example of a Kernel Directory on Windows operating systems


All Kernel names on Windows operating systems must be unique. The
format of a Kernel name is DMKxy where x is the letter indicating the
Kernel set name and y is the Kernel number within that set.

The node names used in the Kernel Name Table are the network node
names. Obviously, these names are site dependent. When a node name of
DM$LOCAL is used, the user‟s current node is assumed.




                                                              Communications  185
               Kernel Process Name on Windows
               If DMNAM is given the Kernel name, it will use the KD to determine
               where that Kernel may be running. DMNAM will then attempt to connect
               to the Kernels on each node on the list until a successful connection is
               established or until the list is exhausted. In the latter situation, the Kernel
               is not available.

               Primary Kernel on Windows
               Whenever a user program issues a non-database specific request (for
               example, SIGNON), the request is sent to the user‟s primary Kernel. The
               name of the primary Kernel is made known to BASIS by the following
               host variable:

                   DM_PRIMARY_KERNEL = Kernel_name

               where:

                   Kernel_name specifies the name of the user‟s primary Kernel.

               The value of DM_PRIMARY_KERNEL specifies the location in the KD
               from which it can retrieve a list of node names. The list indicates the order
               in which the user program searches for an active kernel on a given node.
               If the list shows node_x first, it will attempt to sign on to node_x first.
               Only if it fails to do so, will it attempt to sign on to node_y.

               How to Set Up DMNAM on Windows
               As an example, suppose Kernel DMKA1 runs on node_x and you want to
               make that Kernel available on another node, node_y. By default, BASIS
               Kernels are DMNAM-enabled.
               1. Make sure BASIS is generally available on node_y.
               2. On node_y, go to the BASIS program group icon and double click on
                  the Setup Kernel Directories icon. Add node_x to the node list for
                  Kernel dmka1.
               3. If node_x is an Windows 4.0 Server, use the Registry Editor to see if
                  the key:



186  Communications
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
SecurePipeServers\Winreg exists. If it does not exist, remote Registry
access is not restricted and you can go on to step 4. Otherwise, add the
following key (entry type REG_MULTI_SZ):
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
SecurePipeServers\Winreg\AllowedPaths\Machine




                                                    Communications  187
                   This key may or may not already exist. In any case, add the Registry
                   path of the BASIS CCF as an entry of the Machine key. The path will
                   typically be:
                   SYSTEM\CurrentControlSet\Services\v9_dmka1\CCF

                   where "v9_dmka1" is the name of the V9.0 DMKA1 kernel.
                   Substitute your kernel name here if it is different. Adding this entry
                   allows remote Registry access to the CCF Registry information.
               4. For both node_x and node_y, an entry must appear in the file
                  %SystemRoot%\system32\drivers\etc\services. The entry is of the
                  form: service_name port number/protocol, for example, v9_dmka1
                  7201/tcp.

               Remote BASIS Access to Kernels
               Assume that BASIS was installed on a Server called Jupiter in your
               Domain. The share name BASIS was created which maps to the directory
               \Program Files\Basis on Jupiter.

               How can you run the BASIS modules on your workstation and access the
               Kernel on the server Jupiter without installing BASIS on your
               workstation?
               1. Map a network drive to the BASIS share name using the Tools menu
                  in Explorer. For this example, assume you mapped the network drive
                  N to the BASIS share.
               2. Have your profile,
                   a. Set your command path to include the DM and DMK bin
                      directories.
                      That is, N:\xx \dm\bin and N:\ xx \dmk\bin where xx corresponds
                      to the release of BASIS.
                   b. Execute the script file N:\xx \dm\bin\dmcmds.bat to set up the
                      BASIS environment. Be sure that this script file contains the same
                      drive and directory mappings as Jupiter:
                       set DM_ROOT=\\Jupiter\BASIS
                       set DM=%DM_ROOT%\dm




188  Communications
       Alternately, create a new dmcmds.bat file on the workstation with
       the following settings:
       set DM_ROOT=N:
       set DM=%DM_ROOT%\dm

3. To access a specific remote Kernel, an entry must exist in the Kernel
   directory on your workstation. The Kernel directory is a registry key.
   To create or update the Kernel directory on your workstation, run:
   %DM_ROOT%\setup\kerndir\setup.exe.




                                                       Communications  189
               4. For each remote kernel an entry must appear in the file,
                  %SystemRoot%\system32\drivers\etc\services. The entry is of the
                  form: service_name port number / protocol, for example, v9_dmka1
                  7201/tcp. This entry on your workstation must mirror the entry in the
                  services file on the server Jupiter.

                   By default, the Kernel directory update procedure which you
                   performed in step 3 will add an entry to your local services file.

               After performing these steps, BASIS modules can be run in a console on
               your workstation and connect to Kernels on the server Jupiter.

               Kernel Directory (KD) on UNIX and VMS
               UNIX, VMS

                The Kernel Directory indicates where a Kernel may be running. This
               directory [file] contains the Kernel Name and a search list of
               Communications Control Files (CCF) for each Kernel.

               Conceptually, the KD is divided into the Kernel Name Table and the CCF
               Name Table. The Kernel Name Table contains a Kernel Name and an
               ordered search list of one to ten CCF names for each Kernel. The Kernel
               Name must be unique. Each entry in the ordered list contains a node
               name, CCF name, and Kernel Number. The node name refers to a node on
               which the Kernel can execute. The CCF name is a one to seven character
               value used to refer to an entry in the CCF Name Table (discussed below).
               The Kernel Number indicates the number for the Kernel within the Kernel
               Set. This value is used to refer to an entry in the CCF file. The following
               illustrates a sample Kernel Name Table:


               Kernel Name      Entry     Node       CCF Name        Kernel
                                                                     Number

               DMKA1            1         ND21       CCFA            1

                                2         ND22       CCFA            1




190  Communications
Kernel Name     Entry    Node      CCF Name       Kernel
                                                  Number

DMKA2           1        ND22      CCFA           2

                2        ND23      CCFA           2

                3        ND24      CCFA           2

Kernel DMKA1 has a two-entry search list and is Kernel Number 1 of the
Kernel set. Kernel DMKA2 has a three-entry search list and is Kernel 2 of
the set. All entries in the table refer to the CCF named CCF1. This is a
reference to an entry in the CCF Name Table.




                                                      Communications  191
               All Kernel Names must be unique. Although no specific format for the
               name is required, it is recommended that all Kernels be named in a
               consistent way. The recommended approach is to name the Kernel
               DMKxy, where x is a letter identifying the Kernel Set and y is the Kernel
               Number within the set. For example, Kernel DMKA2 is Kernel 2 within
               set A. Each site can determine the naming convention that best meets its
               needs.
               UNIX

               Note that the Kernel name must be consistent with the process name given
               in the CCF record.
               UNIX, VMS

               The node names used in the Kernel Name Table are the network node
               names. Obviously, these names are site dependent. When a node name of
               DM$LOCAL is used, the user‟s current node is assumed.

               The purpose of the CCF Name Table is to provide a means of symbolically
               referring to a CCF file. Each entry in the CCF Name Table contains a one-
               to-seven character CCF name and a CCF file descriptor. The CCF name is
               unique within the table and provides a referencing mechanism between an
               entry in the Kernel Name Table and a CCF file descriptor.

               The CCF file descriptor identifies a CCF file, and the value is from one to
               80 characters in length.
               UNIX

                   The CCF file can be on a remote file system, or it can be on the user‟s
                   local file system. To allow the CCF file to be accessed from a remote
                   file system, the file system must be mounted and the file server, as well
                   as the local node, must support remote file locking.
               VMS

                   The CCF file can be on a remote node, or it can be on the user‟s local
                   node. When the CCF file is on a remote node, the file descriptor
                   includes a node specification. The node specification contains a node


192  Communications
name and, optionally, an access control string. The access control
string specifies that a particular account on the remote node is to be
used for the file access rather than the default network account. This
may not be needed at all sites.




                                                     Communications  193
               UNIX, VMS

               The value used for the file descriptor is dependent upon the requirements
               of your installation. Whatever value is provided for the file descriptor is
               simply used as the file descriptor.
               VMS

                   See VMS networking documentation for more information with
                   respect to accessing files on remote nodes

                   When the CCF file is on the local node, the file descriptor does not
                   include a node specification (it‟s ignored if it is supplied). The node
                   specification should not be included in a cluster environment.
               UNIX, VMS

               When the Kernel Name Table indicates the Kernel is on a remote node,
               but the CCF file descriptor indicates the CCF file is a local file, the CCF
               file is most likely a copy of the “real” CCF file on the remote node. It is
               the responsibility of the System Administrator to control the copies of the
               CCF file.




194  Communications
The following tables illustrate sample UNIX and VMS CCF Name Tables:
UNIX




CCF Name       CCF File Descriptor (UNIX)

CCFA           $DM_RUNDMKA/dmccfile.ccf

CCFB           $DM_RUNDMKB/dmccfile.ccf

CCFC           $DM_RUNDMKC/dmccfile.ccf

VMS




CCF Name       CCF File Descriptor (VMS)

CCFA           DM$RUNDMKA:DMCCFILE.CCF

CCFB           ND22::DM$RUNDMKB:DMCCFILE.CCF

CCFC           ND23"SMITH
               XX"::DM$RUNDMKC:DMCCFILE.CCF

   The file for CCFA is either on the local node or a cluster is being used.
   The file for CCFB is on node ND22, and either a proxy login account
   exists for the user on node ND22 or the default DECnet account is
   being used. The file for CCFC is on node ND23, and the user ID of
   SMITH and a password of XX is to be used to log in on node ND23 to
   access the file.
UNIX, VMS

The purpose of the CCF name list is to define multiple locations where the
Kernel can run. The KD does not indicate where the Kernel is actually
running, rather it indicates where it could be running. At the time a
database is opened, the Kernel is located by searching down the CCF name



                                                        Communications  195
               list. If the search of the CCF name list finds that the required Kernel is not
               running, the user program is informed that the Kernel is not available.

               On a network of nodes that share files on a common server (UNIX) or for
               clusters (VMS), the CCF name list provides a great deal of flexibility
               regarding where a Kernel can run. For instance, in the event a node is
               unavailable, a Kernel can be started on another node. Likewise, should a
               node fail while a Kernel is running, the Kernel can be restarted on another
               node. Automatic recovery is performed if necessary. In the Kernel
               Directory there must be a CCF entry for the Kernel that corresponds to the
               node on which the Kernel is started/restarted. If there is not such an entry,
               remote users cannot communicate with the Kernel.

               For a network where files are not shared (UNIX) or a non-cluster network
               (VMS), the CCF name list for a Kernel usually has only one entry. If a
               node (UNIX) or a non-cluster node (VMS) on the network is unavailable,
               the files on that node are not accessible from the other nodes. Thus,
               starting a Kernel on an alternate node does little good; the files are
               inaccessible.

               The following tables illustrate a typical Kernel Directory in a three-node
               network that has file-sharing (UNIX) or cluster (VMS):

               Table 5-1: Kernel Name Table for a 3-node network with file sharing (UNIX)
               or a 3-node cluster (VMS)


               Kernel Name       Entry     Node      CCF           Kernel Number
                                                     Name

               DMKA1             1         ND21      CCFA          1

                                 2         ND22      CCFA          1

               DMKA2             1         ND22      CCFA          2

                                 2         ND23      CCFA          2

               DMKA3             1         ND23      CCFA          3




196  Communications
Kernel Name      Entry     Node     CCF          Kernel Number
                                    Name

                 2         ND21     CCFA         3

Table 5-2: CCF Name Table for a 3-node network with file sharing (UNIX)


CCF Name             CCF File Descriptor

CCFA                 $DM_RUNDMK/dmccfile.ccf




                                                       Communications  197
               Table 5-3: CCF Name Table for a 3-node cluster (VMS)


               CCF Name              CCF File Descriptor

               CCFA                  DM$RUNDMK:DMCCFILE.CCF

               One Kernel Set is being run with a preferred configuration of one Kernel
               per node. Each Kernel Name has a two-entry CCF name list. This
               structure allows each Kernel to be run on one of two nodes. For example,
               if node ND21 is unavailable, Kernel DMKA1 could

               be run on ND22. Since the files (UNIX) or the files of a cluster (VMS) are
               available to all nodes, it is practical to run Kernel DMKA1 on node ND22.
               Only one CCF name and file descriptor are used since only one Kernel Set
               is being used.

               The following tables illustrate a typical Kernel Directory in a three-node
               network without file-sharing:

               Table 5-4: Kernel Name Table for a 3-node network without file sharing
               (UNIX) or a 3-node non-cluster network (VMS)


               Kernel Name       Entry     Node      CCF            Kernel
                                                     Name           Number

               DMKB1             1         ND11      CCFB           1

               DMKC1             1         ND12      CCFC           1

               DMKD1             1         ND13      CCFD           1

               Table 5-5: CCF Name Table for a 3-node network without file sharing
               (UNIX)


               CCF Name           CCF File Descriptor

               CCFB               $DM_RUNDMKB/dmccfile.ccf



198  Communications
CCF Name   CCF File Descriptor

CCFC       $DM_RUNDMKC/dmccfile.ccf

CCFD       $DM_RUNDMKD/dmccfile.ccf




                                      Communications  199
               Table 5-6: CCF Name Table for a 3-node non-cluster network (VMS)


               CCF Name             CCF File Descriptor

               CCFB                 DM$RUNDMKB:DMCCFILE.CCF

               CCFC                 DM$RUNDMKC:DMCCFILE.CCF

               CCFD                 DM$RUNDMKD:DMCCFILE.CCF

               Each Kernel Name has a single-entry CCF name list since files are not
               shared. The CCF file descriptors do not specify a node which indicates the
               files are on the user‟s local node.

               The following tables illustrate a typical Kernel Directory in a five-node
               network where three of the nodes (ND21, ND22, and ND23) share files
               (UNIX) or form a cluster (VMS):

               Table 5-7: Kernel Name Table for a 5-node network where 3 nodes share
               files (UNIX) or form a cluster (VMS)


               Kernel Name      Entry     Node      CCF           Kernel
                                                    Name          Number

               DMKA1            1         ND21      CCFA          1

                                2         ND22      CCFA          1

               DMKA2            1         ND22      CCFA          2

                                2         ND23      CCFA          2

               DMKA3            1         ND23      CCFA          3

                                2         ND21      CCFA          3

               DMKB1            1         ND11      CCFB          1




200  Communications
Kernel Name   Entry   Node   CCF    Kernel
                             Name   Number

DMKC1         1       ND12   CCFC   1

DMKD1         1       ND13   CCFD   1




                                        Communications  201
               Table 5-8: CCF Name Table for a 5-node network where 3 nodes share files
               (UNIX)


               CCF Name        CCF File Descriptor

               CCFA            $DM_RUNDMKA/dmccfile.ccf

               CCFB            $DM_RUNDMKB/dmccfile.ccf

               CCFC            $DM_RUNDMKC/dmccfile.ccf

               CCFD            $DM_RUNDMKD/dmccfile.ccf

               Table 5-9: CCF Name Table for a 5-node network where 3 nodes form a
               cluster (VMS)


               CCF Name        CCF File Descriptor

               CCFA            DM$RUNDMKA:DMCCFILE.CCF

               CCFB            DM$RUNDMKB:DMCCFILE.CCF

               CCFC            DM$RUNDMKC:DMCCFILE.CCF

               CCFD            DM$RUNDMKD:DMCCFILE.CCF

               The Kernels running in the same Kernel Set (DMKA1, DMKA2, and
               DMKA3) use the same CCF name and file descriptor, like the example
               above. As in the network example, Kernels DMKB1, DMKC1, and
               DMKD1 each have a single-entry CCF list.

               Kernel Process Name on UNIX and VMS
               For a user program to communicate with a process on another node, the
               node name and the name of the other process are needed. The KD directs
               DMNAM to the node and the CCF file. In the CCF file is the process
               name of each Kernel of the Kernel Set.




202  Communications
All Kernel process names must follow a specific format. The format is
xxxxx_rr_Knn where xxxxx is the Kernel Name, rr is a BASIS release ID,
and nn is the Kernel Number within the Kernel Set. For example, the
process name dmka1_L1_k01 is for the Kernel named dmka1 of BASIS
release L1, and the Kernel is Kernel 1 of the set. All Kernel Names must
be unique and five characters in length. The letter “k” must precede the
Kernel Number. The Kernel Number must be a value from “01” to “09”.




                                                      Communications  203
               Primary Kernel on UNIX and VMS
               UNIX, VMS

               Whenever a user program issues a non-database specific request (for
               example, SIGNON), the request is sent to the user‟s primary Kernel. The
               name of the primary Kernel is made known to BASIS by the following
               host variable:

                   DM_PRIMARY_KERNEL = Kernel_name

               where:

                   Kernel_name specifies the name of the user‟s primary Kernel.

               The value of DM_PRIMARY_KERNEL is used to search the KD to
               retrieve an ordered list of CCF file descriptors. Each entry on the list is
               then examined to find the required Kernel. Normally, a user‟s primary
               Kernel runs on the user‟s local node. It is possible for a user‟s primary
               Kernel to be running on a remote node. If DM_PRIMARY_KERNEL has
               no value, the default Kernel on the local node is assumed. The default
               Kernel is Kernel Number 1 of the Kernel Set using the CCF file pointed to
               by the environment variable DM_CCF on UNIX and the logical DM$CCF
               on VMS.

               The value of DM_PRIMARY_KERNEL is set for BASIS users when
               DM_COMMANDS (UNIX) or DM$COMMANDS (VMS) is executed.
               Then, setdmsite.sh (UNIX) or DM$SETDMSITE (VMS) sets the value.

               Search Order on UNIX and VMS
               UNIX, VMS

               The host variable DM_SEARCH_ORDER indicates the search order used
               by BASIS when a database OPEN is performed. The possible values are
               as follows:

                   DM_SEARCH_ORDER = ADB | GDD | (ADB,GDD) | (GDD,ADB)

               where:



204  Communications
ADB   indicates that only the ADB (Authority Database) of the
      user‟s primary Kernel is searched for the database name.
      Only databases entered in the ADB of the user‟s primary
      Kernel can be accessed.

GDD   indicates that only the GDD (Global Database Directory)
      is searched to find the name of the Kernel that controls the
      database. Only databases entered in the GDD can be
      accessed.




                                                Communications  205
               (ADB,GD       indicates that the ADB of the user‟s primary Kernel is
               D)            searched first. If the database name is not found in the
                             ADB, the GDD is searched.

               (GDD,AD       indicates that the GDD is searched first. If the database
               B)            name is not found in the GDD, the ADB of the user‟s
                             primary Kernel is searched.

               If DM_SEARCH_ORDER has no value, ADB is assumed. The search
               process stops as soon as the database name is found. The search does not
               resume if the database is not known to the Kernel. For example, if the
               search order is (GDD,ADB) and the database name is found in the GDD,
               but the database is not known to the Kernel, the search process does not
               resume.

               The value of DM_SEARCH_ORDER can be changed as necessary. The
               preferred value is (GDD,ADB). This creates a hierarchical search order.
               If the database is available for remote usage, its name is in the GDD. If
               the name is not in the GDD, the ADB is searched. If a user never intends
               to use a global database, ADB should be used. If a user always wants to
               use only global databases, GDD is the proper value. By setting
               DM_SEARCH_ORDER to (ADB,GDD), the local database is used if it is
               present. Otherwise, the GDD is searched.

               The value of DM_SEARCH_ORDER should be set automatically when
               DM_COMMANDS (UNIX) or DM$COMMANDS (VMS) is executed.
               DM_COMMANDS calls setdmsite.sh on UNIX and DM$COMMANDS
               calls DM$SETDMSITE on VMS, which set the value.

               Being able to change the search order is very useful when a local copy of a
               global database is needed (for testing purposes, for example). By setting
               the search order to (ADB,GDD) and creating a copy of the database on the
               local node, programming changes are not necessary to access the local
               copy. This technique works only when the original database is not under
               the control of a Kernel on the local node.

               Consider the following Global Database Directory:



206  Communications
Global Database Alias   Global Database   Kernel Name
                        Primary Name
AJAX                    AJAX              DMKA1
FINANCE                 FINANCE           DMKB6
KILROY                  KILROY            DMKA1
SMITH1                  AJAX              DMKB6




                                                Communications  207
               Assume that USER1 has DM_SEARCH_ORDER set to (GDD,ADB) and
               that USER2 has DM_SEARCH_ORDER set to (ADB,GDD). For both
               users, DM_PRIMARY_KERNEL is set to DMKB6. When USER1 opens
               the AJAX database, AJAX (primary name) on Kernel DMKA1 is opened
               since the GDD is searched before the ADB. But when USER2 opens the
               AJAX database, the ADB of Kernel DMKB6 is searched before the GDD.
               Thus, AJAX (primary name) on Kernel DMKB6 is opened. Should
               USER2 change DM_SEARCH_ORDER to either (GDD,ADB) or GDD,
               opening AJAX would result in AJAX (primary name) on Kernel DMKA1
               being opened.

               How to Set up DMNAM on UNIX
               UNIX

               As an example, suppose Kernel DMKA1 runs on node_x and you want to
               make that Kernel available on another node, node_y.
               1. Log in to the BASIS system account on node_x.
               2. Determine whether DMNAM is installed on your machine by checking
                  for the executable dmnetio in $DM.
               3. Edit setdmsite.csh and setdmsite.sh to uncomment the line that sets up
                  the DM_PRIMARY_KERNEL environment variable.
               4. Stop the Kernel using stopdmk.
               5. Run DMCCF with action=update. Access the CCF in dialog mode.
                  Either Show the record to verify that the Network Status Flag is
                  already 1, or select Change a record. Give the number of the Kernel to
                  be modified (1-9). Select Network Status Flag and set it to 1. Select
                  No more changes and then Exit out of DMCCF.
               6. Use DMCCF to change the Kernel Directory. Add search entry 2 to
                  the Kernel Name Table for Kernel DMKA1. Entry 2 should be
                  identical to entry 1 except the node name(s) should be node_x rather
                  than DM$LOCAL.
               7. Start the Kernel using startdmk.




208  Communications
8. Verify that the Kernel is up by reviewing the log files in
   $DM_RUNDMK. Look for lines beginning with SE. These indicate
   some sort of Kernel start problem. Run DMSTAT, specifying the
   DMSTAT number, or DMHSC, specifying any numbers that begin
   with H#. This will help get you started.
9. Make BASIS generally available on node_y.

For more information, see Example 14.




                                                 Communications  209
               How to Set up DMNAM on VMS
               VMS

               As an example, suppose Kernel DMKA1 runs on NODE_X and you want
               to make that Kernel available on another cluster node, NODE_Y.
               1. Determine if DMNAM is part of your site configuration. If the logical
                  DM$NETLIB = DM$OBJ:NETLIBA.OLB, DMNAM is present. If
                  DM$NETLIB = DM$OBJ:NETDUMMYLIBA.OLB, DMNAM is not
                  present.
               2. Log in to the DMPROD account on NODE_X.
               3. Stop the Kernel.
               4. Use DMCCF to change the CCF. Change the NETSTATUS field from
                  0 to 1.
               5. Use DMCCF to change the Kernel Directory. Add search entry 2 to
                  the Kernel Name Table for Kernel DMKA1. Entry 2 should be
                  identical to entry 1 except the node name(s) should be NODE_X rather
                  than DM$LOCAL.
               6. Make BASIS generally available on NODE_Y.
               VAX

                   On VAX/VMS systems, run the command procedures

                   DEV$DMPROD:[DMROOT.DM]SETUPDM.COM
                   DEV$DMPROD:[DMROOT.DM]SHAREDM.COM
               ALPHA

                   On VMS/AXP systems, run the command procedures

                   DEV$DMPROD:[DMROOT.DM]SETUPDM_AXP.COM
                   DEV$DMPROD:[DMROOT.DM]SHAREDM_AXP.COM

                   These should be part of the system startup procedure.




210  Communications
Redundant Copies of the GDD and KD on UNIX and VMS
UNIX, VMS

In a network environment, every file is “owned” by some node. If a node
is unavailable, all files on that node are inaccessible by the other nodes.
To prevent operations from being impaired when a network node is
unavailable, up to nine redundant copies of the GDD and nine redundant
copies of the KD can be scattered across the network.




                                                         Communications  211
               The environment variables DM_KDx (UNIX) or logical names DM$KDx
               (VMS), where x varies from 1 to 9, point to the redundant copies of the
               Kernel directory. When the KD is being accessed, the file assigned to
               DM_KD1 (UNIX) or DM$KD1 (VMS) is first accessed. Should it not be
               available, DM_KD2 (UNIX) or DM$KD2 (VMS) is tried and so on.

               The environment variables DM_GDDx (UNIX) or logical names
               DM$GDDx (VMS), where x varies from 1 to 9, point to the redundant
               copies of the global database directory. When the GDD is being accessed,
               the file assigned to DM_GDD1 (UNIX) or DM$GDD1 (VMS) is first
               accessed. Should it not be available, DM_GDD2 (UNIX) or DM$GDD2
               (VMS) is tried and so on.
               VMS

                   The redundant copies feature is applicable in a cluster environment
                   also. A redundant copy of the GDD and KD could be placed on
                   different volumes. In the event one of the volumes is unavailable, the
                   redundant copy is used. Consideration might be given to putting
                   redundant copies on volumes controlled by different HSCs. In the
                   event an HSC is unavailable, the redundant copy is used.
               UNIX, VMS

               By default, the environment variables (UNIX) or logical names (VMS) for
               the KD and the GDD are assigned as follows:


                On this           The file for the KD is      The file for the GDD is
                operating
                system

                UNIX              $DM_RUNDMK/dmkd1.           $DM_RUNDMK/dmgdd1.
                                  kdf                         gdf

                VMS               DM$RUNDMK:DMKD1             DM$RUNDMK:DMGDD1
                                  KDF                         .GDF




212  Communications
No node name is provided in these name assignments. It is the
responsibility of the System Administrator to assign the proper names to
the environment variables DM_KDx and DM_GDDx (UNIX) or logical
names DM$KDx and DM$GDDx (VMS), to distribute and control the
redundant copies of the files, and to ensure that they are identical.

Controlling the GDD and KD on UNIX and VMS




                                                       Communications  213
               UNIX, VMS

               The GDD and KD are the responsibility of the System Administrator.
               Users should not be allowed to update these files. Manual procedures
               should be established at each site as to how a DBA would request a new
               database be added to the GDD, how a systems manager would request the
               movement of a Kernel from one node to another, etc. Protect these files
               from unauthorized changes, and back them up.
               VMS

                   Consider using an Access Control List to control usage.
               UNIX, VMS

               The DMCCF utility is used to create, update, and read these files. Each
               file has a separate internal password that DMCCF uses to help prevent
               unauthorized users from changing these files.

               Compatible Versions of DMNAM on UNIX and VMS
               UNIX, VMS

               A user program can communicate with a Kernel of any BASIS release as
               long as DMNAM and the Kernel are compatible. If they aren‟t, the user
               program receives an error message indicating the incompatibility. Each
               “packet” of information sent to and from a Kernel contains a version
               identifier. The Kernel checks the version of each packet it receives and
               DMNAM also checks the version of each packet it receives. The version
               numbers must match.

               Starting and Restarting Kernels on UNIX and VMS
               UNIX, VMS

               DMNAM adds a great deal of flexibility to running Kernels in a file-
               sharing (UNIX) or cluster (VMS) configuration. For example, assume that
               a Kernel was running on a node that just failed (i.e., hardware failure).
               That Kernel can now be restarted on another node (UNIX) or node of the
               cluster (VMS). Recovery, if needed, is performed automatically. This



214  Communications
flexibility comes mainly from the shared file base. The database files
necessary to run the Kernel and perform recovery are available to all
nodes.

When starting/restarting a Kernel, use the DMSA BEGIN command. The
CCF used for the BEGIN command is determined by the environment
variable DM_CCF (UNIX) or logical name DM$CCF (VMS). The value
of DM_PRIMARY_KERNEL is not used by the BEGIN command.
DMSA must be executing on the node on which the Kernel is to run.
Also, the Kernel must be started/restarted on a node specified in that
Kernel‟s ordered search list in the Kernel Directory. If it isn‟t, remote
user‟s won‟t be able to communicate with the Kernel.

For a network without file-sharing (UNIX) or a non-cluster network
configuration (VMS), the Kernel cannot simply be restarted on another
node. This is because the files on one node aren‟t available to another
node unless both nodes are available. Thus, some flexibility is lost.

Using Dynamic Binding on UNIX and VMS
UNIX, VMS

Dynamic binding of the database name and/or version allows a program
written to use database A, for example, to use database B without
changing the program. Of course, this works only as long as databases A
and B are compatible.

When accessing a global database, the database is referred to by its
database alias. Under normal situations, the alias and primary name for a
database are the same. If they are not, a potential problem arises. For
example, assume a global database has an alias of ABC and a primary
name of QRS. Further, assume that numerous programs have been written
referring to the database by its primary name, QRS. One choice is to
change all references from QRS to ABC. Another choice is to use
Dynamic Binding of the database name. To do this, the global symbol
DM_DB_QRS is set to “ABC” before the database is opened (this is
usually done in command language outside the program). From that point
on, all references to database QRS are internally changed to ABC. This is
in effect until the symbol DM_DB_QRS is deleted.



                                                        Communications  215
               Creating Global Databases
               UNIX, VMS

               There is very little difference between creating a local database and
               creating a global database. Whenever possible, the database alias and
               primary name should be the same. This avoids potential confusion. The
               first step, then, is to have the System Administrator put the appropriate
               entry into the Global Database Directory. This “stakes out” a good
               database alias and primary name.

               The second step is to set DM_PRIMARY_KERNEL to the name of
               Kernel one of the Kernel Set. This is necessary because DMDBA uses the
               user‟s primary Kernel to define a new database and only Kernel Number
               one can update the ADB. Other Kernels of the set can only read the ADB.
               UNIX

                   When defining a database on a network without file-sharing and the
                   primary Kernel is on a remote node, the user must log on to the remote
                   node and create the database on that node.




216  Communications
VMS

   When defining a database in a non-cluster network environment and
   the primary Kernel is on a remote node, potential file protection
   problems may arise. If the database files are on the remote node, the
   user must be authorized to create and update files on that node. If the
   database files are on the user‟s local node, the files must allow world
   update so that the Kernel on the remote node can modify the files.
   Obviously, the best approach is to avoid creating a new database with a
   Kernel on a remote node. Log on to the remote node and create the
   database on that node.
UNIX, VMS

Whenever possible, DMDBA should be run on the same node as the
Kernel controlling the new database. Also, the database files should
always be on the same node as the Kernel controlling the database. This is
not required, but performance will be better.

Netserver Log Files on VMS
VMS

When running Kernels on the network using DMNAM, certain conditions
can cause NETSERVER.LOG files to be created in the users login
directory. This occurs when a user program on one node tries to connect
to a Kernel on another node, but the Kernel is not presently running on the
other node. These files are not automatically deleted.

To control the build-up of netserver logs, the VMS Network Control
Program (NCP) can be directed to execute a command file in the DM$
directory which controls the build-up of these logs. The command file is
DEV$DMPROD:[DMROOT.RELxx.DM]DMKNET.COM where xx is
the BASIS release id. This procedure renames NETSERVER.LOG files
created by BASIS to DMKNET.LOG and then purges the DMKNET.LOG
files.

The following NCP commands direct the network to execute this
procedure:



                                                        Communications  217
                   $ RUN SYS$SYSTEM:NCP
                   NCP> SET OBJECT DMKA1_D2_K01 NUMBER 0 -
                   ...FILE DEV$DMPROD:[DMROOT.RELD2.DM]DMKNET.COM
                   NCP> SET OBJECT DMKA1_D2_K02 NUMBER 0 -
                   ...FILE DEV$DMPROD:[DMROOT.RELD2.DM]DMKNET.COM
                   NCP> EXIT

               These commands direct the network to execute DMKNET.COM whenever
               a connection fails on that node for Kernels DMKA1_D2_K01 and
               DMKA2_D2_K02. If other Kernels are being run, their names must be
               entered also. Notice that the recommended Kernel naming convention is
               being used.




218  Communications
These commands must be entered through NCP by the system manager on
each node which might be running that Kernel. Also, the SET commands
used above only effect the volatile network database. This means that
whenever the NET is restarted, these definitions will be lost. To be
permanent, the NCP DEFINE command should be used instead of SET.

DM_COMMANDS (UNIX) and DM$COMMANDS (VMS)
UNIX, VMS

On UNIX, DM_COMMANDS executes a script to define the BASIS
commands (DMDBA, FQM, etc.); on VMS, DM$COMMANDS executes
a command procedure to define the same commands. All BASIS users
should execute this script or command procedure upon login. The UNIX
script is named $DM/dmcmds.sh; the VMS command procedure is named
DM$DMCMD.COM. Do not modify this script or command procedure.
To allow site-dependent extensions to DM_COMMANDS, there is
another UNIX shell script named $DM/setdmsite.sh that can be used; on
VMS, use the command procedure DM$:SETDMSITE.COM. On UNIX,
$DM/setdmsite.sh is executed by $DM/dmcmds.sh; on VMS,
DM$:SETDMSITE.COM is executed by DM$DMCMD.COM.

A basic version of $DM/setdmsite.sh (UNIX) or DM$:SETDMSITE.COM
(VMS) is provided to each site. Without modification, a site can run a
single Kernel Set with one Kernel. Usage of DMNAM requires this
procedure to be modified to reflect your site configuration.

$DM/setdmsite.sh (UNIX) and DM$:SETDMSITE.COM (VMS) are
composed of six sections labeled A through F. The overall flow of control
is Section A to Section B to Section C and so on. An overview of each
section and a description of the changes you might make follow.

$DM/setdmsite (UNIX) and DM$:SETDMSITE.COM (VMS)
Section A provides a convenient place for site-dependent symbol
definitions of use to BASIS users.




                                                      Communications  219
               Section B defines the BASIS environment variables and sets them to their
               respective default values. If you prefer different default values, change
               Section B.

               Section C defines the environment variables (UNIX) or logical names
               (VMS) for each Kernel Set on your system. Each Kernel Set requires
               definitions for the environment variables DM_RUNDMKx, DM_CCFx,
               and DM_DBx (UNIX) or the logical names DM$RUNDMKx, DM$CCFx,
               and DM$DBx (VMS), where x is a single letter identifier of the Kernel
               Set. Note that the sample script (UNIX) and command procedure (VMS)
               make heavy use of the recommended Kernel naming convention of
               DMKxy where x indicates the Kernel Set and y indicates the Kernel within
               the set. Each site is strongly urged to follow this naming convention.

               If multiple Kernel Sets are to be used, this section needs to modified.
               Copy the template and replace the letter x with the proper Kernel Set letter
               (“B” for example). Running multiple Kernel Sets involves much more
               than just modifying the sample script (UNIX) or command procedure
               (VMS). For more information on running multiple Kernel Sets, see
               “Tuning the System.”

               Section D sets the symbol DM_PRIMARY_KERNEL. As mentioned
               above, DM_PRIMARY_KERNEL is the name of the user‟s primary
               Kernel. It is recommended that the user‟s primary Kernel be on the same
               node as the user.
               UNIX

                   Section D also sets the proper value for DM_PRIMARY_KERNEL
                   and DM_KS and assigns the proper file names for the environment
                   variables DM_RUNDMK, DM_CCF, and DM_DB. Adjust Section D
                   of the sample script for your site‟s requirements.
               VMS

                   Section D provides the control logic necessary to set
                   DM_PRIMARY_KERNEL based on the node.

                   Section D uses the BASIS command SETDMKS to switch a user from
                   one Kernel to another. This command assumes the recommended


220  Communications
   Kernel naming convention is being used. SETDMKS has one
   argument xi where “x” is the Kernel Set identifier and “i” is the Kernel
   within the set. For example, to switch to Kernel 4 of Kernel Set C, the
   command would be SETDMKSC4. The SETDMKS command sets
   the proper value for DM_PRIMARY_KERNEL and DM_KS and
   assigns the proper file names for the logical names DMRUNDMK,
   DM$CCF, and DM$DB. Use the template to adjust Section D to the
   site requirements.
UNIX, VMS

Section E defines the environment variables (UNIX) or logical names
(VMS) for the Kernel Directory file, Global Database Directory file, and
any redundant copies of these files.
VMS

   If DMNAM is being used, remove the comment from the ASSIGN
   statement for DM$GDD1 and update the GDD using DMCCF. Use
   the template lines in Section E to identify the locations of the
   redundant copies of the KD and GDD.
UNIX, VMS

Section F assigns a value to the symbol DM_SEARCH_ORDER. As
mentioned above, this symbol indicates the searching order when a
database is to be opened. This section rarely needs modification.
UNIX

Sample $DM/setdmsite (UNIX)
   :
   #
   #   TITLE:        setdmsite - Set site-dependent
   #                 environment variables
   #
   #   DIRECTIONS:   $DM/setdmsite
   #
   #   NOTES:        1.   Called only by $DM_COMMANDS
   #
   #                 2.   Should be modified by DM System
   #                      Administrator to meet site requirements.
   #
   #                 3.   Does not need to be modified in the normal



                                                       Communications  221
                   #                   case where one Kernel is to be run in a
                   #                   stand-alone environment.
                   #
                   #                4. Typically needs to be modified in
                   #                   these cases:
                   #                   a.) multiple Kernels of one set are to be
                   #                       run on nodes with file sharing.
                   #                   b.) multiple Kernel sets exist in a
                   #                       network.
                   #
                   #                5. Refer to the BASIS Reference manual
                   #                   for more information regarding the
                   #                   environment variables defined in this
                   #                   procedure.
                   #
                   # SECTION A - Insert definitions unique to the site here.
                   #
                   DM_LINKOPT=debug
                   BASIS_SYS=/usr/vendor/releaseK/run
                   export DM_LINKOPT BASIS_SYS
                   #
                   # SECTION A - END
                   #




222  Communications
# SECTION B - Set miscellaneous environment variables.
#
#     These environment variables govern certain
#     aspects of DM modules.
#     Modify this section if these default values are
#     not appropriate.
#
DM_AIDS=YES
DM_EDIT=vi
DM_MRT=YES
DM_SPAWN=YES
export DM_AIDS DM_EDIT DM_MRT DM_SPAWN
#
# SECTION B - END
#
# SECTION C - Declare every possible Kernel set.
#
#     Unless DMNAM is installed, this section should
#     need no changes.
#
#     For each possible Kernel set, the two
#     environment variables DM_RUNDMKx and DM_CCFx,
#     where x is the letter designating the Kernel
#     set, must be set. Defined below are the
#     environment variables for Kernel set A,
#     normally the only Kernel set of a site.
#
# SECTION C - END
#
# SECTION D - Establish the primary Kernel.
#
#     Unless DMNAM is installed, this section should
#     need no changes.
#
#     In this section, the following environment
#     variables are defined:
#
#             DM_PRIMARY_KERNEL
#             DM_KS
#             DM_RUNDMK
#             DM_CCF
#
#     The convention for naming a Kernel is DMKxi,
#     where x is a letter (A,B,C,...) designating the
#     Kernel set, and i is a digit (1:9) designating
#     a particular Kernel within the set. The
#     desired Kernel is specified to setdmks via a
#     parameter containing the "xi" part of the
#     Kernel name.
#
#     Usually there exists just one Kernel (DMKA1) at
#     a site so, by default, this section enables the
#     user to utilize that Kernel.
#
DM_PRIMARY_KERNEL=DMKA1
DM_KS=A



                                             Communications  223
                   DM_RUNDMK=$DM_RUNDMKA
                   DM_CCF=$DM_CCFA
                   export DM_PRIMARY_KERNEL DM_KS DM_RUNDMK DM_CCF
                   #
                   # SECTION D - END
                   #
                   # SECTION E - Define directories, Kernel (KD) and
                   # Global Database (GDD).
                   #
                   #     Unless DMNAM is installed, this section should
                   #     need no changes.
                   #
                   #     Logical names DM_KDn and DMGDDn, where n=1:9,
                   #     refer to the Kernel directories and Global
                   #     Database directories, respectively.
                   #     Define DM_KD1 to point to the main Kernel
                   #     directory (KD).
                   #     Define DM_GDD1 to point to the main Global
                   #     Database directory (GDD).
                   #     Define DM_KDn and DM_GDDn, n=2:9, for redundant
                   #     copies of KDs and GDDs on different devices.
                   #     Follow the example below for assigning the
                   #     logical names required by the site.
                   #
                   DM_KD1=$DM_RUNDMK/dmkd1.kdf
                   DM_GDD1=$DM_RUNDMK/dmgdd1.gdf
                   export DM_KD1 DM_GDD1
                   #
                   # SECTION E - END
                   #
                   # SECTION F - Define search order for database names.
                   #
                   #     Unless DMNAM is installed, this section should
                   #     need no changes.
                   #
                   #     Define global symbol DM_SEARCH_ORDER, which
                   #     specifies the sequence of places where database
                   #     names are to be looked up.
                   #     Valid values are as follows: ADB, GDD,
                   #     (ADB,GDD), (GDD,ADB).
                   #     ADB, the default, stands for the Authority
                   #     Database. GDD stands for the Global Database
                   #     Directory.
                   #
                   DM_SEARCH_ORDER="ADB"
                   export DM_SEARCH_ORDER
                   #
                   # SECTION F - END




224  Communications
VMS

Sample DM$:SETDMSITE.COM (VMS)
  $VERIFY='F$VERIFY()
  $!
  $! TITLE:        SETDMSITE.COM - Set site-dependent
  $!               DM symbols and logical names.
  $!
  $! DIRECTIONS: @DM$:SETDMSITE.COM
  $!
  $! NOTES:        1. Called only by DM$:DMCMD.COM
  $!
  $!               2. Should be modified by DM System
  $!                   Administrator to meet site
  $!                   requirements.
  $!
  $!               3. Does not need to be modified in
  $!                   the normal case where one Kernel
  $!                   is to be run in a stand-alone
  $!                   environment.
  $!
  $!               4. Typically needs to be modified in
  $!                   these cases:
  $!                   a. multiple Kernels of one set
  $!                      are to be run in a cluster.
  $!                   b. multiple Kernel sets exist in
  $!                      a cluster or network.
  $!
  $!               5. Refer to the System Administration
  $!                   and BASIS Reference manuals
  $!                   for more information regarding
  $!                   the global symbols and logical
  $!                   names defined in this procedure.
  $!
  $! SECTION A - Insert definitions unique to the site here.
  $!
  $! Define SD if not previously defined.
  $! Demo areas
  $ASSIGN/NOLOG DEV$DMPROD:[DMROOT.RELL1M.DB]       BASIS$DB
  $ASSIGN/NOLOG DEV$DMPROD:[DMROOT.RELL1M.DB.DEMO] BASIS$DEMO
  $ASSIGN/NOLOG DEV$DMPROD:[DMROOT.RELL1M.DB.SRC]   BASIS$DBSRC
  $!
  $! SECTION A - END
  $!
  $! SECTION B - Set miscellaneous environment variables.
  $!
  $!     These global symbols govern certain
  $!     aspects of DM modules.
  $!     Modify this section if these default values are
  $!     not appropriate.
  $!
  $IF "''dm_aids'".EQS."" THEN dm_aids :== YES ! or NO
  $IF "''dm_edit'".EQS."" THEN dm_edit :== EDT ! or LSE or TPU



                                                Communications  225
                   $IF "''dm_mrt'".EQS."" THEN dm_mrt   :== YES ! Display
                   $!                                               module
                   $!                                               revision
                   $                                              ! tags for DM
                   $!                                               modules
                   $IF "''dm_broadcast_box'".EQS."" THEN -
                          dm_broadcast_box :== NO ! Intercept unsolicited
                   $                               ! broadcast messages in user
                   $                               ! screen programs
                          dm_global_memory :== PO ! Which memory region DM
                   $                               ! global memory sections are
                   $                               ! mapped to
                   $DMBATCH :== SYS$BATCH          ! The name of a valid batch
                   $DM_SPAWN :== YES               ! queue or NO
                   $DM_MODE :== 'F$MODE()'         ! There is no alternative
                   $                               ! value for DM_MODE.
                   $!
                   $! SECTION B - END
                   $!
                   $! SECTION C - Declare every possible Kernel set.
                   $!
                   $!     Unless DMNAM is installed, this section should
                   $!     need no changes.
                   $!
                   $!     For each possible Kernel set, the two
                   $!     logical names must be assigned. The logical names
                   $!     are DM$RUNDMKx and DM$CCFx,
                   $!     where x is the letter designating the Kernel
                   $!     set. Defined below are the
                   $!     logical names for Kernel set A,
                   $!     normally the only Kernel set of a site.
                   $!
                   $!             Kernel set A
                   $!ASSIGN/NOLOG DEV$DMPROD:[DMROOT.RELLIM.DM.RUNDMK] DM$RUNDMKA
                   $!ASSIGN/NOLOG DM$RUNDMKA:DMCCFILE.CCF                DM$CCFA
                   $!
                   $!      If additional Kernel sets (B, C, D, ...) are to be
                   $!      established for a site utilizing DMNAM, follow the
                   $!      template below by substituting the letter of the
                   $!      Kernel set for x.
                   $!
                   $!      Kernel set x                                 !template
                   $!ASSIGN/NOLOG DEV$DMPROD:[DMROOT.RELLIM.DM.RUNDMKx] DM$RUNDMKx
                   $!                                                   !template

                   $!ASSIGN/NOLOG DM$RUNDMKx:DMCCFILE.CCF DM$CCFx      !template
                   $!
                   $!
                   $! SECTION C - END
                   $!
                   $! SECTION D - Establish the primary Kernel.
                   $!
                   $!     Unless DMNAM is installed, this section should
                   $!     need no changes.
                   $!
                   $!     In this section, the command SETDMKS is invoked to



226  Communications
$!     define the global symbols and logical names that
$!     enable the user executing this procedure to utilize a
$!     specific Kernel. SETDMKS defines the following:
$!
$!           global symbols         logical names
$!           --------------         -------------
$!           DM_PRIMARY_KERNEL      DM$RUNDMK
$!           DM_KS                  DM$CCF
$!
$!     The convention for naming a Kernel is DMKxi,
$!     where x is a letter (A,B,C,...) designating the
$!     Kernel set, and i is a digit (1:9) designating
$!     a particular Kernel within the set. The
$!     desired Kernel is specified to SETDMKS via a
$!     parameter containing the xi part of the
$!     Kernel name.
$!
$!     Usually there exists just one Kernel (DMKA1) at
$!     a site so, by default, this section enables the
$!     user to utilize that Kernel. In other words, the
$!     command "SETKS A1" is executed by default.
$!
$!     If DM is running in a cluster/network environment
$!     under the auspices of DMNAM, there are multiple
$!     Kernels (perhaps multiple Kernel sets), so a single
$!     primary Kernel must be chosen from the many. The
$!     primary Kernel should be local, i.e., on the same node
$!     as the user currently executes this procedure. Follow
$!     the template below in order to set the proper primary
$!     Kernel. Substitute valid node names for aaaaaa,
$!     bbbbbb, cccccc. Substitute a Kernel set letter for x
$!     and Kernel set numbers for i, j, k.
$!
$NODE = "''F$GETSYI("NODENAME")'
$!
$!IF "''NODE'" .EQS. "aaaaaa" THEN $ SETDMKS xi !template
$!IF "''NODE'" .EQS. "bbbbbb" THEN $ SETDMKS xj !template


$!IF "''NODE'" .EQS. "cccccc" THEN $ SETDMKS xk !template
$!
$IF "''DM_KS'" .EQS. "" THEN      $ SETDMKS A1 !default
$!
$! SECTION D - END
$!
$! SECTION E - Define directories, Kernel (KD) and
$! Global Database (GDD).
$!
$!     Unless DMNAM is installed, this section should
$!     need no changes.
$!
$!     Logical names DM$KDn and DM$GDDn, where n=1:9,
$!     refer to the Kernel directories and Global
$!     Database directories, respectively.
$!     Define DM$KD1 to point to the main Kernel
$!     directory (KD).



                                              Communications  227
                   $!     Define DM$GDD1 to point to the main Global
                   $!     Database directory (GDD).
                   $!     Define DM$KDn and DM$GDDn, n=2:9, for redundant
                   $!     copies of KDs and GDDs on different devices.
                   $!     Follow the example below for assigning the
                   $!     logical names required by the site.
                   $!
                   $ASSIGN/NOLOG DM$:DMKD1.KDF DM$KD1     ! main Kernel
                   $!                                       directory
                   $!ASSIGN/NOLOG DM$:DMGDD1.GDF DM$GDD1 ! main global database
                   $!                                       directory
                   $!ASSIGN/NOLOG dev:DMKDn.KDF DM$KDn    ! redundant KD n on
                   $!                                       device dev
                   $!ASSIGN/NOLOG dev:DMGDDn.GDF DM$GDDn ! redundant GDD n on
                   $!                                       device dev
                   $!
                   $!
                   $! SECTION E - END
                   $!
                   $! SECTION F - Define search order for database names.
                   $!
                   $!     Unless DMNAM is installed, this section should
                   $!     need no changes.
                   $!
                   $!     Define global symbol DM_SEARCH_ORDER, which
                   $!     specifies the sequence of places where database
                   $!     names are to be looked up.
                   $!     Valid values are as follows: ADB, GDD,
                   $!     (ADB,GDD), (GDD,ADB).
                   $!     ADB, the default, stands for the Authority
                   $!     Database. GDD stands for the Global Database
                   $!     Directory.

                   $!
                   $DM_SEARCH_ORDER :==     ADB          !default search order
                   $!
                   $! SECTION F - END
                   $!
                   $!EXIT




228  Communications
DMCCF on UNIX and VMS
        UNIX, VMS

        You can use the Communications Control Facility utility (DMCCF) to
        create, update, or read the communications files. The files are the
        Communications Control Facility (CCF), the Kernel Directory (KD), and
        the Global Database Directory (GDD). The CCF is used to define the
        number of Kernels in the Kernel Set that are allowed to run and how many
        users are allowed to be connected to each Kernel. It is also used to define
        the process names, global sections, and other host system facilities. The
        KD defines the name and CCF file descriptor for each Kernel. The GDD
        is used to define which Kernel is in control of each database that is
        available to remote users.

        Syntax
        DMCCF
            {ACTION=READ | CREATE | UPDATE}
            {CCF=file}
            {GDD=file}
            {GDD_PW=password}
            {GET=file}
            {INPUT=file}
            {KD=file}
            {KD_PW=password}
            {MODE=DIALOG | GDD_STATEMENTS |
            KD_STATEMENTS}
            {OUTPUT=file}
            {PUT=file}
            {VF=file}

        Parameters
        You can use either the comma (,) or slash (/) or a space to separate
        parameters.


                                                                 Communications  229
               ACTION=READ | CREATE | UPDATE                                    (Optional)

               With READ, the CCF file must already exist. You can only display
               records or have the fields of a record explained. If you attempt anything
               else, you‟ll get an error message. The default is READ.

               CREATE makes a new CCF file. You can then create, modify, delete or
               display communications control records, or have the fields of a record
               explained.




230  Communications
UPDATE works on a communications control file you‟ve already created.
You select from menus to create, modify, delete or display records, or to
have the record fields explained.

CCF=file                                                        (Optional)

A valid communications control file that has been or will be created. The
default is $DM_CCF (UNIX) or DM$CCF (VMS).

GDD=file                                                        (Optional)

A valid Global Database Directory (GDD) file that has been or will be
created by DMCCF. The default is $DM_GDD1 (UNIX) or DM$GDD?
(VMS).

GDD_PW=password                                                 (Optional)

A Global Database Directory (GDD) password. When you create or
update a GDD, you must supply a password.

GET=file                                                        (Optional)

A file that contains statements for processing in Statement mode. You can
ignore this parameter if you‟ve specified ACTION=READ.

INPUT=file                                                      (Optional)

Your terminal, or a sequential file of variable length records, which
contains answers to DMCCF program prompts. The default is $STDIN
(UNIX) or SYS$INPUT (VMS).

KD=file                                                         (Optional)

A valid Kernel Directory file that has been or will be created by DMCCF.
The default is $DM_KD1 (UNIX) or DM$KD? (VMS).

KD_PW=password                                                  (Optional)

A Kernel Directory password. When you create or update a Kernel
Directory, you must supply a password.


                                                       Communications  231
               MODE=DIALOG | GDD_STATEMENTS | KD_STATEMENTS(Optional)

               You can use DMCCF in either Dialog or Statement mode. In Dialog
               mode, you answer a series of questions; in Statement mode a set of
               statements from a file is processed by DMCCF. Statement mode is
               applicable for either a Kernel Directory (KD) file or a Global Database
               Directory (GDD) file. The default is Dialog mode.




232  Communications
OUTPUT=file                                                       (Optional)

Your terminal, or a standard output file which lists all error messages,
prompts, and program output. The default is $STDOUT (UNIX) or
SYS$OUTPUT (VMS).

PUT=file                                                          (Optional)

A file containing statements for either a KD or GDD, created by DMCCF,
corresponding to a given Kernel Directory or a given Global Database
Directory. To create a statement file, specify KD_STATEMENTS (for a
Kernel Directory), or GDD_STATEMENTS (for a Global Database
Directory) for the MODE parameter and supply a PUT file specification.

VF=file                                                           (Optional)

A valid vocabulary file which contains the Communications Control
Facility‟s messages. The default file is $DM_VOC (UNIX) or DM$VOC
(VMS).

Description
DMCCF creates, updates, and reads the BASIS communications files.
These include the Communications Control File (CCF), Global Database
Directory (GDD) file and the Kernel Directory (KD) file.

The purpose of the GDD is to indicate which Kernel (Kernel set and
Authority Database) is in control of each global database. A global
database is a database that is available to users on remote nodes. The
GDD contains one entry per global database. Each entry lists the Global
Database Primary Name and the Global Database Alias. Entries also
specify which Kernel to use when processing the requests related to the
global database.

The purpose of the KD is to indicate on which nodes a Kernel may be
running. This is accomplished by storing a search list of Node names and
Communications Control File




                                                         Communications  233
               (CCF) names for each Kernel. The KD is divided into the Kernel Name
               Table and the CCF Name Table. Every unique entry in the Kernel Name
               Table points to an entry in the CCF Name Table.

               In order to update the two different tables of the KD, two different formats
               are used with the ADD/KD, PUT/KD, and DELETE/KD commands. In
               the discussion of commands and parameters which follows, keep in mind
               that Format 1 is used to update the Kernel Name Table. Format 2 is used
               to update the CCF Name Table.

               The MODE parameter lets you select how you will communicate with
               DMCCF, either interactively or through a file of statements.




234  Communications
Dialog mode is best for small updates or corrections. In Dialog, you select
choices from a series of menus and answer the prompts. You can also
request help by entering a question mark (?) at the prompt. All DMCCF
features are available through Dialog Mode, and it is the only way you can
change the CCF file. When you‟re in Dialog Mode, you can also switch to
Statement Mode.

In Statement mode you can create and update the GDD and the KD (but
not the CCF). You would use this when you‟re doing large creations or
updates. To use Statement mode, specify MODE=GDD_STATEMENTS
to process a file of GDD specific statements. Specify
MODE=KD_STATEMENTS to process a file of KD specific statements.
The GET parameter is how you specify the name of the file containing the
KD or GDD statements.

The passwords used with the DMCCF utility are Kernel passwords, not
user passwords. The only way to change Kernel passwords is to create a
new CCF file.

Statements
Three basic statements are used in the Statement File: ADD, PUT, and
DELETE. Each statement has a set of required parameters and values.
You can continue a statement with a plus sign (+) at the end of the line.
You put more than one statement on the same line by separating the
statements with a semicolon (;). A statement file can contain comments as
long as you preface the comment with an asterisk (*) in column 1.




                                                        Communications  235
               ADD/GDD
               The ADD/GDD Statement is used to add a new entry to the GDD. An
               entry with the specified alias cannot already exist in the GDD.

               ADD/GDD
                    ALIAS=alias,
                    DB=db_name,
                    KERNELNAME=kernel_name;

               The parameters for the ADD/GDD Statement are:

               ALIAS=alias                                                   (Required)

               The alias of the Global Database. Each entry in the GDD must be
               identified by a unique alias.

               DB=db_name                                                    (Required)

               The name of the Global Database. The controlling Kernel refers to the
               database by this name. To reduce confusion, the Global Database alias
               and name should be the same, if possible.

               KERNELNAME=kernel_name                                        (Required)

               The name of the Kernel controlling the Global Database.

               ADD/KD (Format 1)
               Format 1 of the ADD/KD Statement adds a new entry to the Kernel Name
               Table of the KD. An entry with the specified Kernel name and entry
               number cannot already exist in the KD.

               ADD/KD
                    KERNELNAME=kernel_name,
                    ENTRY=entry_number,
                    NODENAME=node_name,
                    CCFNAME=ccf_name,
                    KERNELNUMBER=kernel_number;



236  Communications
The parameters for the ADD/KD Statement (Format 1) are:

CCFNAME=ccf_name                                           (Required)

The name of an entry in the CCF Name Table.




                                                   Communications  237
               ENTRY=entry_number                                             (Required)

               The identifying number of the entry for the specified Kernel. Since each
               Kernel in the Kernel Name Table can have many entries, this parameter
               indicates which entry you‟re adding. Combining the Kernel Name and
               Entry number gives each entry in the Kernel Name Table a unique
               identifier.

               KERNELNAME=kernel_name                                         (Required)

               The name of the Kernel. Each Kernel has a unique Kernel Name.

               KERNELNUMBER=kernel_number                                     (Required)

               The Kernel number for the Kernel within the Kernel Set. Each member of
               a Kernel Set has a unique Kernel number.

               NODENAME=node_name                                             (Required)

               The name of the node on which the Kernel can execute.

               ADD/KD (Format 2)
               Format 2 of the ADD/KD Statement adds a new entry to the CCF Name
               Table of the KD. An entry with the specified CCF name cannot already
               exist in the KD.

               ADD/KD CCFNAME=ccf_name, CCFFD=ccf_fd;

               The parameters for the ADD/KD Statement (Format 2) are:

               CCFFD=ccf_fd                                                   (Required)

               The file descriptor of a CCF file.

               CCFNAME=ccf_name                                               (Required)

               The name of an entry in the CCF Name Table. Each entry in the table has
               a unique name.




238  Communications
DELETE/GDD
The DELETE/GDD Statement deletes an existing entry from the GDD.

DELETE/GDD ALIAS=alias;

The parameter for the DELETE/GDD Statement is as follows:




                                                   Communications  239
               ALIAS=alias                                                     (Required)

               The alias of the Global Database. Each entry in the GDD is identified by a
               unique alias.

               DELETE/KD (Format 1)
               Format 1 of the DELETE/KD Statement removes all entries for a Kernel
               from the Kernel Name Table of the KD.

               DELETE/KD KERNELNAME=kernel_name;

               The only parameter for the DELETE/KD Statement (Format 1) is:

               KERNELNAME=kernel_name                                          (Required)

               The name of the Kernel to be deleted from the Kernel Name Table. Each
               Kernel has a unique name.

               DELETE/KD (Format 2)
               Format 2 of the DELETE/KD Statement removes an entry from the CCF
               Name Table of the KD.

               DELETE/KD CCFNAME=ccf_name;

               The only parameter for the DELETE/KD Statement (Format 2) is:

               CCFNAME=ccf_name                                                (Required)

               The name of an entry in the CCF Name Table. Each entry in the table has
               a unique name.

               PUT/GDD
               The PUT/GDD command places a new entry in the GDD. If an entry with
               the specified alias already exists, the new entry replaces it. Otherwise, a
               new entry is added to the GDD.

               PUT/GDD
                    ALIAS=alias,


240  Communications
DB=db_name,
KERNELNAME=kernel_name;




                          Communications  241
               The parameters for the PUT/GDD Statement are as follows:

               ALIAS=alias                                                    (Required)

               The alias of the Global Database. Each entry in the GDD is identified by a
               unique alias.

               DB=db_name                                                     (Required)

               The name of the Global Database. The controlling Kernel refers to the
               database by this name. To reduce confusion, the Global Database alias
               and name should be the same, if possible.

               KERNELNAME=kernel_name                                         (Required)

               The name of the Kernel controlling the Global Database.

               PUT/KD (Format 1)
                Format 1 of the PUT/KD Statement places a new entry in the Kernel
               Name Table of the KD. If an entry with the specified Kernel Name and
               entry number already exists in the KD, the new entry replaces it.

               PUT/KD
                    KERNELNAME=kernel_name,
                    ENTRY=entry_number,
                    NODENAME=node_name,
                    CCF=ccf_name,
                    KERNELNUMBER=kernel_number;

               The parameters for the PUT/KD Statement (Format 1) are:

               CCFNAME=ccf_name                                               (Required)

               The name of an entry in the CCF Name Table.

               ENTRY=entry_number                                             (Required)

               The identifying number of the entry for the specified Kernel. Since each
               Kernel in the Kernel Name Table can have many entries, this parameter



242  Communications
indicates which entry you‟re adding or replacing. Combining the Kernel
Name and Entry number gives each entry in the Kernel Name Table a
unique identifier.

KERNELNAME=kernel_name                                       (Required)

The name of the Kernel. Each Kernel has a unique Kernel Name.




                                                     Communications  243
               KERNELNUMBER=kernel_number                                    (Required)

               The Kernel number for the Kernel within the Kernel Set. Each member of
               a Kernel Set has a unique Kernel number.

               NODENAME=node_name                                            (Required)

               The name of the node on which the Kernel can execute.

               PUT/KD (Format 2)
               Format 2 of the PUT/KD Statement places a new entry in the CCF Name
               Table of the KD. If the CCF already has an entry with that name, the new
               entry replaces it.

               PUT/KD CCFNAME=ccf_name, CCFFD=ccf_fd;

               The parameters for the PUT/KD Statement (Format 2) are:

               CCFFD=ccf_fd                                                  (Required)

               The file descriptor of a CCF file.

               CCFNAME=ccf_name                                              (Required)

               The name of an entry in the CCF Name Table. Each entry in the table has
               a unique name.

               Creating a Statement File from an Existing GDD or KD
               In addition to using a statement file to create or update a GDD or KD,
               DMCCF can create a statement file from an existing GDD or KD. You
               can then modify the resulting statements and use them as input for
               updating the GDD or KD.

               To create a statement file of the GDD, specify ACTION=READ,
               MODE=GDD_STATEMENTS, and supply a file specification for the
               PUT parameter.

               Use MODE=KD_STATEMENTS to create a statement file of the KD.



244  Communications
Examples
UNIX

1. To list the default parameters for DMCCF.
   $ dmccf \?
   The default command is:
   DMCCF INPUT=$STDIN, OUTPUT=$STDOUT, ACTION=READ,
   VF=$DM_VOC, CCF=$DM_CCF, KD=$DM_KD?, GDD=$DM_GDD?
   NORMAL TERMINATION - DMCCF

2. To create a new CCF named NEW.CCF containing one record. This
   might be used if you want to change the password used to start/stop the
   Kernel, or if you want to create a new CCF file because the other one
   was lost or damaged.
   $ dmccf action=create ccf=new.ccf
   DMCCF V5 R15 890921 [L1M]

   What do you want to do with the Communications
   Control File ?

          A.   Access   Communications Control File (CCF) in
               dialog   mode
          B.   Access   Kernel Directory (KD) in dialog mode
          C.   Access   Global Database Directory (GDD) in
               dialog   mode

          E.   Access Kernel Directory (KD) in statement
               mode
          F.   Access Global Database Directory (GDD) in
               statement mode

          Z.   Exit this program

       Enter a letter (A:C,E:F,Z)
       > a


       What do you want to do:
           A. Add a new record     B. Show a record
           C. Change a record      D. Delete a record
           E. Explain fields
           Z. Exit this action
       Enter selection (A:E,Z) > a
       Record number > 1
       Password > new
       Press RETURN to use the default value shown in
       parenthesis after the field name. Type END to use
       default values for remaining fields.
       Process name (dmka1_L1_k01) >



                                                       Communications  245
                       Hostile Environment Flag (0) >




246  Communications
   Communication buffer size (2048) >
    Max lines (32) >
    Protocol (1) >
    Control Module Image file ($DM_RUNDMK/dmka_L1) >
    Control Module Log file ($DM_RUNDMK/dmka1_L1.log) >
    User group name () > users


    What do you want to do:
        A. Add a new record     B.    Show a record
        C. Change a record      D.    Delete a record
        E. Explain fields
        Z. Exit this action
    Enter selection (A:E,Z) > z

    What do you want to do with the Communications
    Control File ?

       A.   Access   Communications Control File (CCF) in
            dialog   mode
       B.   Access   Kernel Directory (KD) in dialog mode
       C.   Access   Global Database Directory (GDD) in
            dialog   mode

       E.   Access Kernel Directory (KD) in statement
            mode
       F.   Access Global Database Directory (GDD) in
            statement mode

       Z.   Exit this program

    Enter a letter (A:C,E:F,Z)
    > z
   NORMAL TERMINATION - DMCCF

3. To modify an existing CCF to change an existing CCF parameter.
   Suppose you want to increase the Kernel working set size. Use
   DMCCF to change the value of this parameter in an existing CCF.
   $ dmccf action=update ccf=new.ccf
   DMCCF V5 R15 890921 [L1M]

   What do you want to do with the Communications
   Control File ?




                                                    Communications  247
                          A.   Access   Communications Control File (CCF) in
                               dialog   mode
                          B.   Access   Kernel Directory (KD) in dialog mode
                          C.   Access   Global Database Directory (GDD) in
                               dialog   mode

                          E.   Access Kernel Directory (KD) in statement
                               mode
                          F.   Access Global Database Directory (GDD) in
                               statement mode

                          Z.   Exit this program

                       Enter a letter (A:C,E:F,Z)
                       > a

                   What do you want to do:
                        A. Add a new record     B. Show a record
                        C. Change a record      D. Delete a record
                        E. Explain fields
                        Z. Exit this action
                    Enter selection (A:E,Z) > c
                    Record number > 1
                    Password >
                    Press RETURN to use the current value shown in
                    parentheses after the field name. Type END to use
                    current values for remaining fields selected.
                    Select fields to change:
                        A. Password                     B. Process name
                        C. Hostile environment flag     D. Comm buffer
                                                            size
                        E. Max lines                    F. Protocol
                                                            number
                        G. Image file specification     H. Log file
                                                           specification
                        I. User group name              J. Network
                                                            status flag
                        K. Network buffer size          L. Network max
                                                            lines
                        M. Network protocol

                        Z. No more changes
                    Enter selections (A:I,Z) > i
                    User group name (users) > ?
                   The UNIX Group name of the users who will be
                   accessing this Control Module.
                    User group name (users) $ALL




248  Communications
Select fields to change:
     A. Password                      B.    Process name
     C. Hostile environment flag      D.    Comm buffer
                                            size
     E.   Max lines                   F.    Protocol
                                            number
     G.   Image file specification    H.    Log file
                                           specification
     I.   User group name             J.    Network
                                            status flag
     K.   Network buffer size         L.    Network max
                                            lines
     M.   Network protocol

    Z. No more changes
Enter selections (A:I,Z) > z
Record changed


What do you want to do:
    A. Add a new record     B. Show a record
    C. Change a record      D. Delete a record
    E. Explain fields
    Z. Exit this action
Enter selection (A:E,Z) > b
Record number > 1
Record number.......................... 1
Record tag............................. DMCC
Control Module number.................. 1
Process name........................... dmka1_L1_k01
Hostile Environment Flag............... 0
Communication buffer size.............. 2048
Max lines.............................. 32
Protocol number........................ 1
Control Module Image file name.........
       $DM_RUNDMK/dmka_L1
Control Module Log file name...........
       $DM_RUNDMK/dmka1_L1.log
User Group............................. $ALL
Network status flag.................... 1
Network buffer size.................... 2048
Network max lines...................... 10
Network protocol number................ 1

What do you want to do:
     A. Add a new record     B.   Show a record
     C. Change a record      D.   Delete a record
     E. Explain fields
     Z. Exit this action
 Enter selection (A:E,Z) > z




                                                 Communications  249
                   What do you want to do with the Communications
                    Control File ?

                           A.   Password                    B.    Process name
                           C.   Hostile environment flag    D.    Comm buffer
                                                                  size
                           E.   Max lines                   F.    Protocol
                                                                  number
                           G.   Image file specification    H.    Log file
                                                                 specification
                           I.   User group name             J.    Network
                                                                  status flag
                           K.   Network buffer size         L.    Network max
                                                                  lines
                           M.   Network protocol

                           Z.   No more changes

                    Enter a letter (A:C,E:F,Z)
                    > z
                   NORMAL TERMINATION - DMCCF


               3a. To modify the /etc/services file to include the process name as defined
                   in the CCF. Suppose the process name in the CCF record is
                   "dmka1_v9_k01". Your site has decided that the TCP port for this
                   process is 2001. Add this line to the /etc/services file on all systems
                   that will run or access this kernel.
                   dmka1_v9_k01              2001/tcp            # BASIS kernel


               4. To create a new GDD named NEW.GDD using Dialog mode. For
                  instance, your site might want to set up some global databases. Use
                  DMCCF to create the GDD file.
                   $ dmccf action=create,gdd=new.gdd
                   DMCCF V5 R11 890623 [L1]

                   What do you want to do with the Communications
                   Control File?

                       A. Access   Communications Control File (DDF) in
                          dialog   mode
                       B. Access   Kernel Directory (KD) in dialog mode
                       C. Access   Global Database Directory (GDD) in dialog
                          mode

                       E. Access Kernel directory (KD) in statement mode
                       F. Access Global Database Directory (GDD) in
                          statement mode

                       Z   Exit this program



250  Communications
Enter a letter (A:C,E:F,Z)
> c




                             Communications  251
                   What do you want to do with the Global Database
                   Directory (GDD) :

                       A. Show a GDD entry       E. Change a GDD entry
                       B. Show all GDD entries   F. Delete a GDD entry
                       C. Explain fields         X. Exit this action
                                                    without updating GDD
                       D. Add a new GDD entry    Z. Exit this action and
                                                    update GDD

                   Enter a letter (A:F,X,Z)
                   > d
                   Enter Global Database Directory password
                   > new gdd_password
                   Enter the database alias (1:8 characters) or press
                   RETURN to exit this action
                   ADD> ajax
                   Enter the primary database name (1:8 characters)
                   ADD> ajax
                   Enter the kernel name (1:5 characters)
                   ADD> dmka1
                   Enter the database alias (1:8 characters) or press
                   RETURN to exit this action
                   ADD> inven2
                   Enter the primary database name (1:8 characters)
                   ADD> inven
                   Enter the kernel name (1:5 characters)
                   ADD> dmka2
                   Enter the database alias (1:8 characters) or press
                   RETURN to exit this action
                   ADD>
                   What do you want to do with the Global Database
                   Directory (GDD) :

                       A. Show a GDD entry       E. Change a GDD entry
                       B. Show all GDD entries   F. Delete a GDD entry
                       C. Explain fields         X. Exit this action
                                                    without updating GDD
                       D. Add a new GDD entry    Z. Exit this action and
                                                    update GDD

                   Enter a letter (A:F,X,Z)
                   > b

                   Sorting GDD entries ...

                   Database alias     Database primary name   Kernel Name
                   --------------     ---------------------   -----------
                   AJAX               AJAX                    DMKA1
                   INVEN2             INVEN                   DMKA2




252  Communications
    What do you want to do with the Global Database
    Directory (GDD) :

        A. Show a GDD entry          E. Change a GDD entry
        B. Show all GDD entries      F. Delete a GDD entry
        C. Explain fields            X. Exit this action
                                        without updating GDD
        D. Add a new GDD entry       Z. Exit this action and
                                        update GDD

    Enter a letter (A:F,X,Z)
    > z

    What do you want to do with the Communications Control File?

        A. Access   Communications Control File (CCF) in
           dialog   mode
        B. Access   Kernel Directory (KD) in dialog mode
        C. Access   Global Database Directory (GDD) in dialog
           mode

        E. Access Kernel directory (KD) in statement mode

    F. Access Global Database Directory (GDD) in
         statement mode

        Z. Exit this program

    Enter a letter (A:C,E:F,Z)
    > z
    NORMAL TERMINATION - DMCCF

Note:     You‟ll need to edit the setdmsite.sh to put this new GDD into
effect.
5. Add a new entry into an existing GDD and change an existing GDD
   using Dialog mode. For example, a database named INVEN has been
   rebuilt and is now called PARTS. Update the GDD to reflect this new
   database name.
    z
    $ dmccf action=create,gdd=new.gdd
    DMCCF V5 R11 890623 [L1]

    What do you want to do with the Communications
    Control File?
      A. Access Communications Control File (CCF) in
         dialog mode
      B. Access Kernel Directory (KD) in dialog mode
      C. Access Global Database Directory (GDD) in dialog
         mode

        E. Access Kernel directory (KD) in statement mode
        F. Access Global Database Directory (GDD) in



                                                          Communications  253
                          statement mode

                       Z. Exit this program




254  Communications
Enter a letter (A:C,E:F,Z)
> c

What do you want to do with the Global Database
Directory (GDD) :

  A. Show a GDD entry        E. Change a GDD entry
  B. Show all GDD entries    F. Delete a GDD entry
  C. Explain fields          X. Exit this action
                                without updating GDD
  D. Add a new GDD entry     Z. Exit this action and
                                update GDD

Enter a letter (A:F,X,Z)
> d
Enter Global Database Directory password
> gdd_password
Enter the database alias (1:8 characters) or press RETURN to
exit this action
ADD> cust
Enter the primary database name (1:8 characters)
ADD> cust
Enter the kernel name (1:5 characters)
ADD> dmkb1
Enter the database alias (1:8 characters) or press RETURN to
exit this action
ADD>

What do you want to do with the Global Database
Directory (GDD) :

  A. Show a GDD entry        E. Change a GDD entry
  B. Show all GDD entries    F. Delete a GDD entry
  C. Explain fields          X. Exit this action
                                without updating GDD
  D. Add a new GDD entry     Z. Exit this action and
                                update GDD

Enter a letter (A:F,X,Z)
> E
  1. The current value is shown in parentheses after
     the field name.
  2. Press RETURN to take the current value.




                                               Communications  255
                   Enter the database alias or press RETURN to exit this
                   action
                   CHANGE> inven2
                   PRIMARYDBNAM = (INVEN)
                   CHANGE> parts
                   KERNELNAME   = (DMKA2)
                   CHANGE>
                   Enter the database alias or press RETURN to exit this
                   action
                   CHANGE>

                   What do you want to do with the Global Database
                   Directory (GDD) :

                       A. Show a GDD entry        E. Change a GDD entry
                       B. Show all GDD entries    F. Delete a GDD entry
                       C. Explain fields          X. Exit this action
                                                     without updating GDD
                       D. Add a new GDD entry     Z. Exit this action and
                                                     update GDD

                   Enter a letter (A:F,X,Z)

                   > z

                   What do you want to do with the Communications
                   Control File?

                       A. Access Communications Control File (CCF) in
                          dialog mode
                       B. Access Kernel Directory (KD) in dialog mode
                       C. Access Global Database Directory (GDD) in dialog
                          mode
                       E. Access Kernel directory (KD) in statement mode
                       F. Access Global Database Directory (GDD) in
                          statement mode
                       Z. Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > z
                   NORMAL TERMINATION - DMCCF


               5a. To set up DMNAM on UNIX, either verify or create an /etc/services
                   entry for a TCP port for the kernel process name on all nodes. Sites
                   using NIS should perform the equivalent operation to the services
                   database.

               6. Create a new KD named new.kd using Dialog mode. Suppose your
                  site has decided to allow Kernel 1 to run on several nodes. Create a




256  Communications
KD to reflect this. Remember to also add the entry in the CCF Name
Table.
$ dmccf action=create,kd=new.kd
DMCCF V5 R11 890623 [L1]




                                                 Communications  257
                   What do you want to do with the Communications
                   Control File?

                       A. Access   Communications Control File (CCF) in
                          dialog   mode
                       B. Access   Kernel Directory (KD) in dialog mode
                       C. Access   Global Database Directory (GDD) in dialog
                          mode

                       E. Access Kernel directory (KD) in statement mode
                       F. Access Global Database Directory (GDD) in
                          statement mode

                       Z. Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > b

                   What do you want to do with the Kernel Directory (KD) :

                       A. Show a KD entry         E. Change a KD entry
                       B. Show all KD entries     F. Delete a KD entry
                       C. Explain fields          X. Exit this action
                                                     without updating KD
                       D. Add a new KD entry      Z. Exit this action and
                                                     update KD

                   Enter a letter (A:F,X,Z)
                   > d
                   Enter Kernel Directory password
                   > ________

                   Which table do you want to update

                       A. Kernel Name Table
                       B. CCF Name Table
                       Z. Exit this action

                   Enter a letter (A,B,Z)
                   > a
                   Enter the kernel name
                   ADD> dmka1
                   Up to 10 CCF search entries can be added to the
                   kernel name search list
                   CCF search entry #1
                   Enter the node name (1:16 characters) or press RETURN
                   to exit
                   ADD> nodea
                   Enter the CCF name (1:17 characters)
                   ADD> ccf1
                   Enter the Kernel number (1:9)
                   ADD> 1
                   CCF search entry #2
                   Enter the node name (1:16 characters) or press RETURN
                   to exit



258  Communications
ADD> nodeb
Enter the CCF name (1:7 characters)
ADD> ccf1

Enter the Kernel number (1:9)
ADD> 1
CCF search entry #3
Enter the node name (1:16 characters) or press RETURN to exit
ADD>

Which table do you want to update

  A. Kernel Name Table
  B. CCF Name Table
  Z. Exit this action


Enter a letter (A,B,Z)
> b
Enter the CCF name or press RETURN to exit this
action
ADD> ccf1
Enter the CCF file descriptor (1:80 characters)
ADD> $DM_RUNDMK/new.ccf
Enter the CCF name or press RETURN to exit this
action
ADD>

Which table do you want to update

  A. Kernel Name Table
  B. CCF Name Table
  Z. Exit this action

Enter a letter (A,B,Z)
> z

What do you want to do with the Kernel Directory (KD) :

  A. Show a KD entry       E. Change a KD entry
  B. Show all KD entries   F. Delete a KD entry
  C. Explain fields        X. Exit this action
                              without updating KD
  D. Add a new KD entry    Z. Exit this action and
                              update KD

Enter a letter (A:F,X,Z)
> b

Sorting KD kernel name entries ...




                                              Communications  259
                   Kernel name table entry

                   Kernel name       Entry #    Node name   CCF name   Kernel #
                   -----------       -------    ---------   --------   --------
                   DMKA1                1        nodea        CCF1        1
                                        2        nodeb        CCF1        1

                   Sorting KD CCF Name entries ...

                   CCF name table entries

                   CCF name           CCF file descriptor
                   --------           -------------------
                   CCF1               $DM_RUNDMK/new.ccf

                   What do you want to do with the Kernel Directory (KD) :

                       A. Show a KD entry         E. Change a KD entry
                       B. Show all KD entries     F. Delete a KD entry
                       C. Explain fields          X. Exit this action
                                                     without updating KD
                       D. Add a new KD entry      Z. Exit this action and
                                                     update KD

                   Enter a letter (A:F,X,Z)
                   > z

                   What do you want to do with the Communications
                   Control File?

                       A. Access   Communications Control File (CCF) in
                          dialog   mode
                       B. Access   Kernel Directory (KD) in dialog mode
                       C. Access   Global Database Directory (GDD) in dialog
                          mode

                       E. Access Kernel directory (KD) in statement mode
                       F. Access Global Database Directory (GDD) in
                          statement mode

                       Z. Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > z
                   NORMAL TERMINATION - DMCCF

               Note:     You may need to modify setdmsite.sh to put your new KD into
               effect.
               7. Update an existing KD using Dialog mode. Suppose Kernel 1 can only
                  run on NODEA and NODEB. Your site has decided to allow Kernel 2
                  to run on nodes NODEB and NODEC. Add new KD entries to do this.
                   $ dmccf action=update,kd=new.kd



260  Communications
DMCCF   V5   R11   890623   [L1]




                                   Communications  261
                   What do you want to do with the Communications
                   Control File?

                       A. Access   Communications Control File (CCF) in
                          dialog   mode
                       B. Access   Kernel Directory (KD) in dialog mode
                       C. Access   Global Database Directory (GDD) in dialog
                          mode

                       E. Access Kernel directory (KD) in statement mode
                       F. Access Global Database Directory (GDD) in
                          statement mode
                       Z. Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > b

                   What do you want to do with the Kernel Directory (KD) :

                       A. Show a KD entry         E. Change a KD entry
                       B. Show a KD entries       F. Delete a KD entry
                       C. Explain fields          X. Exit this action
                                                     without updating KD
                       D. Add a new KD entry      Z. Exit this action and
                                                     update KD

                   Enter a letter (A:F,X,Z)
                   > d
                   Enter Kernel Directory password
                   > kd.password

                   Which table do you want to update

                       A. Kernel Name Table
                       B. CCF Name Table
                       Z. Exit this action

                   Enter a letter (A,B,Z)
                   > a
                   Enter the kernel name
                   ADD> dmka2
                   Up to 10 CCF search entries can be added to the
                   kernel name search list
                   CCF search entry #1
                   Enter the node name (1:16 characters) or press RETURN
                   to exit
                   ADD> nodeb
                   Enter the CCF name (1:7 characters)
                   ADD> ccf1
                   Enter the Kernel number (1:9)
                   ADD> 2
                   CCF search entry #2
                   Enter the node name (1:16 characters) or press RETURN
                   to exit
                   ADD> nodec



262  Communications
Enter the CCF name (1:17 characters)
ADD> ccf1
Enter the Kernel number (1:9)
ADD> 2
CCF search entry #3
Enter the node name (1:16 characters) or press RETURN to exit
ADD>

Which table do you want to update

  A. Kernel Name Table
  B. CCF Name Table
  Z. Exit this action

Enter a letter (A,B,Z)
> z

What do you want to do with the Kernel Directory (KD) :

  A. Show a KD entry       E. Change a KD entry
  B. Show all KD entries   F. Delete a KD entry
  C. Explain fields        X. Exit this action
                              without updating KD
  D. Add a new KD entry    Z. Exit this action and
                              update KD

Enter a letter (A:F,X,Z)
> e

Which table do you want to update

  A. Kernel Name Table
  B. CCF Name Table
  Z. Exit this action

Enter a letter (A,B,Z)
> b
Enter the CCF name or press RETURN to exit this
action
CHANGE> ccf1
CCF_FD       = ($DM_RUNDMK/new.ccf)
CHANGE> $DM_RUNDMK/newer.ccf

Which table do you want to update

  A. Kernel Name Table
  B. CCF Name Table
  Z. Exit this action

Enter a letter (A,B,Z)
> z




                                              Communications  263
                   What do you want to do with the Kernel Directory (KD)
                   :

                       A. Show a KD entry         E. Change a KD entry
                       B. Show all KD entries     F. Delete a KD entry
                       C. Explain fields          X. Exit this action
                                                     without updating KD
                       D. Add a new KD entry      Z. Exit this action and
                                                     update KD

                   Enter a letter (A:F,X,Z)
                   > b

                   Sorting KD kernel name entries ...

                   Kernel name table entry

                   Kernel name      Entry #   Node name    CCF name    Kernel #
                   -----------      -------   ---------    ---------   --------
                   DMKA1               1        nodea         CCF1         1
                                       2        nodeb         CCF1         1
                   DMKA2               1        nodeb         CCF1         2
                                       2        nodec         CCF1         2

                   Sorting KD CCF Name entries ...

                   CCF name table entries

                   CCF name         CCF file descriptor
                   --------         -------------------
                   CCF1             $DM_RUNDMK/newer.ccf

                   What do you want to do with the Kernel Directory (KD)
                   :

                       A. Show a KD entry         E. Change a KD entry
                       B. Show all KD entries     F. Delete a KD entry
                       C. Explain fields          X. Exit this action
                                                     without updating KD
                       D. Add a new KD entry      Z. Exit this action and
                                                     update KD

                   Enter a letter (A:F,X,Z)
                   > z

                   What do you want to do with the Communications
                   Control File?

                       A. Access   Communications Control File (CCF) in
                          dialog   mode
                       B. Access   Kernel Directory (KD) in dialog mode
                       C. Access   Global Database Directory (GDD) in dialog
                          mode




264  Communications
     E. Access Kernel directory (KD) in statement mode
     F. Access Global Database Directory (GDD) in
        statement mode

     Z. Exit this program

   Enter a letter (A:C,E:F,Z)
   > z
   NORMAL TERMINATION - DMCCF

8. Create a new GDD using statement mode. You might want to create a
   GDD for four databases that are to be available to users on all nodes.
   The statement file named gdd1.dat contains the following:
   *
   * Add four entries to the GDD
   *
   ADD/GDD ALIAS=PAYROLL, DB=PAYROLL,     KERNELNAME=DMKA1;
   ADD/GDD ALIAS=ACCT,    DB=ACCT,        KERNELNAME=DMKA1;
   ADD/GDD ALIAS=HISTORY, DB=HISTORY,     KERNELNAME=DMKB1;
   ADD/GDD ALIAS=NEWS,    DB=NEWS,        KERNELNAME=DMKB2;

   $ dmccf action=create,gdd=new.gdd,mode=gdd_statements,\
     get=gdd1.dat,gdd_pw=password
   DMCCF V5 R11 890623 [L1]

   Updating the GDD from the statement file...
   GDD has been updated with statements from the
   statement file
   NORMAL TERMINATION - DMCCF

9. Update an existing GDD using statement mode. The statement file
   named gdd2.dat contains the following:
   *
   * Add one new entry and replace/add one entry to the
   * GDD
   *
   ADD/GDD ALIAS=BILLING, DB=BILLING, KERNELNAME=DMKB1;
   PUT/GDD ALIAS=ACCT,    DB=ACCT,    KERNELNAME=DMKB2;
   *
   * Delete one entry from the GDD
   *
   DELETE/GDD ALIAS=NEWS;
   $ dmccf action=update,gdd=new.gdd,\
     mode=gdd_statements,get=gdd2.dat,gdd_pw=password
   DMCCF V5 R11 890623 [L1]

   Updating the GDD from the statement file...
   GDD has been updated with statements from the
   statement file
   NORMAL TERMINATION - DMCCF




                                                       Communications  265
               10. Create a statement file named gdd.put from an existing GDD.
                   $ dmccf action=read,gdd=new.gdd,mode=gdd_statements,\
                     put=gdd2.dat
                   DMCCF V5 R11 890623 [L1]

                   Creating GDD entry statements file...
                   GDD entry statements file created
                   NORMAL TERMINATION - DMCCF

                   After running DMCCF, GDD.PUT contains the following:
                   PUT/GDD   ALIAS=ACCT,          DB=ACCT,       KERNELNAME=DMKB2;
                   PUT/GDD   ALIAS=BILLING,       DB=BILLING,    KERNELNAME=DMKB1;
                   PUT/GDD   ALIAS=HISTORY,       DB=HISTORY,    KERNELNAME=DMKB1;
                   PUT/GDD   ALIAS=PAYROLL,       DB=PAYROLL,    KERNELNAME=DMKA1;

               11. Create a new KD using statement mode. The statement file named
                   kd1.dat contains the following:
                   *
                   * Add entries to the Kernel Name Table
                   *
                   ADD/KD KERNELNAME=DMKA1,ENTRY=1,NODENAME=ndx, +
                          CCFNAME=CCFA,KERNELNUMBER=1;
                   ADD/KD KERNELNAME=DMKA1,ENTRY=2,NODENAME=ndy, +
                          CCFNAME=CCFA,KERNELNUMBER=1;
                   ADD/KD KERNELNAME=DMKA2,ENTRY=1,NODENAME=ndy, +
                          CCFNAME=CCFA,KERNELNUMBER=2;
                   ADD/KD KERNELNAME=DMKB1,ENTRY=1,NODENAME=ndz, +
                          CCFNAME=CCFB,KERNELNUMBER=1;
                   *
                   * Add entries to the CCF Name Table
                   *
                   ADD/KD CCFNAME=CCFA, CCFFD=$DM_RUNDMK/ccfa.ccf;
                   ADD/KD CCFNAME=CCFB, CCFFD=$DM_RUNDMK/ccfb.ccf;
                   ADD/KE CCFNAME=CCFC, CCFFD=$DM_RUNDMK/ccfc.ccf;

                   $ dmccf action=create,kd=new.kd,\
                     mode=kd_statements,kd_pw=password
                   DMCCF V5 R11 890623 [L1]


                   Enter the file name that contains the KD entry statements
                   >kd1.dat

                   Updating the KD from the statement file...
                   KD has been updated with statements from the
                   statement file
                   NORMAL TERMINATION - DMCCF




266  Communications
12. Update an existing KD using statement mode. The statement file
    named kd2.dat contains the following:
   *
   * Add one entry and add/replace one entry to the
   * Kernel Name Table
   ADD/KD KERNELNAME=DMKA2,ENTRY=2,NODENAME=ndz, +
          CCFNAME=CCFA,KERNELNUMBER=2;
   PUT/KD KERNELNAME=DMKB1,ENTRY=1,NODENAME=nda, +
          CCFNAME=CCFB,KERNELNAME=1;
   *
   * Delete DMKA2 from the Kernel Name Table
   *
   DELETE/KD KERNELNAME=DMKA2;
   *
   * Delete CCFC from the CCF Name Table
   *
   DELETE/KD CCFNAME=CCFC;

   $ dmccf action=update,kd=new.kd,mode=kd_statements,\
     get=kd2.dat,kd_pw=password
   DMCCF V5 R11 890623 [L1]
   Updating the KD from the statement file...

   KD has been updated with statements from the
   statement file
   NORMAL TERMINATION - DMCCF

13. Create a statement file named kd.put from an existing KD.
   $ dmccf action=read,kd=new.kd,\
     mode=kd_statements,put=kd.put
   DMCCF V5 R11 890623 [L1]

   Creating KD entry statements file...
   KD entry statements file created
   NORMAL TERMINATION - DMCCF

   After running DMCCF, kd.put contains the following:
   PUT/KD KERNELNAME=DMKA1, ENTRY=01,    NODENAME=ndx, +
          CCFNAME=CCFA,     KERNELNUMBER=1;
   PUT/KD KERNELNAME=DMKA1, ENTRY=02,    NODENAME=ndy, +
          CCFNAME=CCFA,     KERNELNUMBER=1;
   PUT/KD KERNELNAME=DMKB1, ENTRY=01,       NODENAME=nda,
          CCFNAME=CCFB,     KERNELNUMBER=1;
   PUT/KD CCFNAME=CCFA, +
          CCFFD=$DM_RUNDMK/ccfa.ccf;
   PUT/KD CCFNAME=CCFB, +
          CCFFD=$DM_RUNDMK/ccfb.ccf;




                                                      Communications  267
               14. Enable DMNAM for a particular Kernel on a node called node_X.
                   First, be sure that you have logged into the BASIS system account on
                   node_X; determined whether DMNAM is installed on your machine;
                   uncommented the line in setdmsite.csh and setdmsite.sh that sets up
                   the DM_PRIMARY_KERNEL environment variable; and used
                   stopdmk to stop the Kernel. (For more information, see “How to Set
                   up DMNAM on UNIX.”) Then run DMCCF with action=update and
                   set the Network Status Flag in the first CCF record to enable
                   DMNAM:
                   $ dmccf action=update [RETURN]
                   DMCCF V5 R25 910329 [L1F] P002         CS010

                   What do you want to do with the Communications Control Facility
                   ?

                       A.   Access Communications Control File (CCF) in dialog
                            mode
                       B.   Access Kernel Directory (KD) in dialog mode
                       C.   Access Global Database Directory (GDD) in dialog mode

                       E.   Access Kernel Directory (KD) in statement mode
                       F.   Access Global Database Directory (GDD) in statement
                            mode

                       Z.   Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > a [RETURN]

                   What do you want to do:
                       A. Add a new record     B. Show a record
                       C. Change a record      D. Delete a record
                       E. Explain fields
                       Z. Exit this action
                   Enter selection (A:E,Z) > c [RETURN]
                   Record number > 1 [RETURN]
                   Password >            The original password is PW.       [RETURN]

                   Press RETURN to use the current value shown in parentheses
                   after the field name. Type END to use current values for
                   remaining fields selected.
                   Select fields to change:
                       A. Password                    B. Process name
                       C. Hostile environment flag    D. Comm buffer size
                       E. Max lines                   F. Protocol number
                       G. Image file specification    H. Log file specification
                       I. User group name             J. Network status flag
                       K. Network buffer size         L. Network max lines
                       M. Network protocol




268  Communications
    Z. No more changes
Enter selections (A:M,Z) > j [RETURN]
Network Status Flag (0) > 1 [RETURN]




                                        Communications  269
                   Select fields to change:
                       A. Password                       B.   Process name
                       C. Hostile environment flag       D.   Comm buffer size
                       E. Max lines                      F.   Protocol number
                       G. Image file specification       H.   Log file specification
                       I. User group name                J.   Network status flag
                       K. Network buffer size            L.   Network max lines
                       M. Network protocol

                       Z. No more changes
                   Enter selections (A:M,Z) > z [RETURN]
                   Record changed

                   What do you want to do:
                       A. Add a new record     B. Show a record
                       C. Change a record      D. Delete a record
                       E. Explain fields
                       Z. Exit this action
                   Enter selection (A:E,Z) > z [RETURN]

                   What do you want to do with the Communications Control Facility
                   ?

                       A.   Access Communications Control File (CCF) in dialog
                            mode
                       B.   Access Kernel Directory (KD) in dialog mode
                       C.   Access Global Database Directory (GDD) in dialog mode

                       E.   Access Kernel Directory (KD) in statement mode
                       F.   Access Global Database Directory (GDD) in statement
                            mode

                       Z.   Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > z [RETURN]

                       NORMAL TERMINATION - DMCCF

                   For nodes on which the client software runs, you must run DMCCF to
                   update the Kernel entries in the Kernel Directory to point to the
                   appropriate node on which the server Kernel runs. Run DMCCF with
                   action=update, and access the Kernel Directory in dialog mode. Select
                   Change a KD entry and enter the password PW. Update the Kernel
                   Name Table, and enter the appropriate Kernel name. Choose the first
                   Kernel entry to modify, and change the NODENAME from
                   DM$LOCAL to the nodename of the node running the server Kernel.
                   Press RETURN for the remaining CHANGE> prompts and Exit the
                   action. Exit DMCCF via the update KD entry. The following sample



270  Communications
dmccf session shows how to set up a Kernel Directory entry with a
new node name:
$ dmccf action=update [RETURN]
DMCCF V5 R25 910329 [L1F] P002         CS010




                                                  Communications  271
                   What do you want to do with the Communications Control Facility
                   ?

                       A.   Access Communications Control File (CCF) in dialog
                            mode
                       B.   Access Kernel Directory (KD) in dialog mode
                       C.   Access Global Database Directory (GDD) in dialog mode

                       E.   Access Kernel Directory (KD) in statement mode
                       F.   Access Global Database Directory (GDD) in statement
                            mode

                       Z.   Exit this program

                   Enter a letter (A:C,E:F,Z)
                   > b [RETURN]

                   What do you want to do with the Kernel Directory (KD) :

                       A. Show a KD entry             E. Change a KD entry
                       B. Show all KD entries         F. Delete a KD entry
                       C. Explain fields              X. Exit this action without
                                                         updating KD
                       D. Add a new KD entry          Z. Exit this action and
                                                         update KD

                   Enter a letter (A:F,X,Z)
                   > e [RETURN]
                   Enter Kernel Directory password
                   >            The original password is PW.    [RETURN]

                   Which table do you want to update

                       A. Kernel Name Table
                       B. CCF Name Table
                       Z. Exit this action

                   Enter a letter (A,B,Z)
                   > a [RETURN]
                   Enter the Kernel name
                   CHANGE> DMKA1 [RETURN]
                   Up to 10 CCF search list entries can be modified
                   Enter the search entry number (1:10)
                   CHANGE> 1 [RETURN]
                   NODENAME     = (DM$LOCAL)
                   CHANGE>      Enter the host name of the node running
                                the server Kernel. [RETURN]
                   CCFNAME      = (CCFA)
                   CHANGE> [RETURN]
                   KERNELNR     = (1)
                   CHANGE> [RETURN]
                   Up to 10 CCF search list entries can be modified
                   Enter the search entry number (1:10)
                   CHANGE> [RETURN]
                   Enter the Kernel name



272  Communications
CHANGE>     [RETURN]

Which table do you want to update

   A. Kernel Name Table
   B. CCF Name Table
   Z. Exit this action

Enter a letter (A,B,Z)
> z [RETURN]

What do you want to do with the Kernel Directory (KD) :

   A. Show a KD entry                 E. Change a KD entry
   B. Show all KD entries             F. Delete a KD entry
   C. Explain fields                  X. Exit this action without
                                         updating KD
   D. Add a new KD entry              Z. Exit this action and
                                         update KD
Enter a letter (A:F,X,Z)
> z [RETURN]

What do you want to do with the Communications Control
Facility ?

   A.     Access Communications Control File (CCF) in dialog
          mode
   B.     Access Kernel Directory (KD) in dialog mode
   C.     Access Global Database Directory (GDD) in dialog mode

   E.     Access Kernel Directory (KD) in statement mode
   F.     Access Global Database Directory (GDD) in statement
          mode

   Z.     Exit this program

Enter a letter (A:C,E:F,Z)
> z [RETURN]

NORMAL TERMINATION - DMCCF

Finally, start the Kernel using startdmk and verify that the Kernel is up
by reviewing the log files in $DM_RUNDMK.

The following example shows the contents of
$DM_RUNDMK/dmka1_l1.log after a successful Kernel start:
DMK     V5 R266 910207 [L1F] P002 CS010
 I 1522 The number of lines in CCF does not match the Sysgen
         SIGNON_LIMIT.
 I 1522    The number of lines specified in CCF are used.
 I 1515 Kernel Number 01 started on Nov 26, 1996 at 15:16:20
 I 1515    with 32 IPC lines and 10 NET lines.




                                                     Communications  273
                   In the following example, the presence of the line beginning with SE
                   indicates an unsuccessful Kernel start:
                   DMK     V5 R266 910207 [L1F] P002 CS010
                    I 1522 The number of lines in CCF does not match the Sysgen
                            SIGNON_LIMIT.
                    I 1522    The number of lines specified in CCF are used.
                   SE 1505 COM startup error (DMSTAT=4101 ) in OPEN_KERNEL.
                   *** NET ERROR ***
                   Kernel Name =DMKA1 HOST status=H#1050A23F
                   HOST ERROR(1050A23F). Undefined network service.
                   Abnormal Termination of DMK on Nov 26, 1996 at 15:12:54

                   In this particular case, the Kernel is complaining that the network
                   service is undefined. This is a common error that occurs whenever the
                   /etc/services file has not been properly modified to include the BASIS
                   process name from the CCF. To correct this problem, check the
                   process name in the CCF using DMCCF. Then check that this name is
                   specified in /etc/services. A common mistake is confusing the
                   characters l (lowercase L) and 1 (one).


Automatic Kernel Failover (VMS Only)
               VMS

               In certain application environments, it is important that Kernel operations
               be available at all times. When a node of the cluster running the Kernel
               fails, Kernel operations need to be resumed as soon as possible on one of
               the remaining nodes. No manual intervention should be necessary to start
               the Kernel on another node. This capability is known as Automatic Kernel
               Failover and is available for VAX/VMS users. Do the following steps to
               set up Automatic Kernel Failover:
               1. Start the Kernel on one of the cluster nodes. This node will be the
                  primary node.
               2. Start the same Kernel on one or more additional nodes of the cluster.
                  The additional nodes are referred to as secondary nodes. These Kernel
                  starts are queued (using the VMS Distributed Lock Manager) awaiting
                  the completion of the Kernel on the primary node. Machine start-up




274  Communications
   procedures should be modified so that the primary node and the
   secondary nodes start the Kernel. Refer to the examples below.

When Kernel operations cease on the primary node because of node
failure, the first queued Kernel on a secondary node starts executing. All
necessary recovery is performed using the secondary node and Kernel
operations resume. The secondary node is now performing all Kernel
operations. Kernel operations on a secondary node start only when the
primary Kernel has terminated because of node failure. When Kernel
operations terminate but the node has not failed, Automatic Kernel
Failover is NOT activated. That is, a backup Kernel does not begin
executing.




                                                        Communications  275
               Automatic Kernel Failover relies on the shared file base of the cluster.
               The Kernel work files, ADB, etc. must be available to the backup Kernel
               so recovery can be performed. If the Kernel fails due to device failure of
               the Kernel's device, recovery cannot be performed and the backup Kernel
               won't execute.

               When Automatic Kernel Failover has taken place, programs (both BASIS
               and user programs) need to re-establish a connection with the Kernel by
               doing a SIGNON. Most BASIS programs need to be exited and re-entered
               to perform the SIGNON.

               Consider the following scenario:
                   1. A cluster contains nodes A, B, and C. Node A is considered the
                      primary node. Node B is used as a backup for node A and node C
                      is the final backup.
                   2. Kernel DMKA1 is started on node A. Subsequently, DMKA1 is
                      also started on nodes B and C.
                   3. Node A fails.
                   4. DMKA1 on node B takes over. All necessary recovery is
                      performed using node B. Application programs sign-on to
                      DMKA1 on node B.

               The benefit of using Automatic Kernel Failover is that the amount of time
               to recover from a failure is minimized. Manual intervention is not
               necessary after the failure. System startup procedures can be established
               so that the Kernel backup mechanism is always in effect. See the
               examples below.

               You can also use the DMCTLK utility to display the lock queue for a
               particular Kernel. The DMCTLK command looks like this:
                       DMCTLK {KERNEL=kernel_name}

                   where
                       kernel_name indicates the name of the Kernel. If no Kernel name
                       is specified, the lock queue for all Kernels whose names start with
                       the letters "DMK" is displayed.


276  Communications
The display is produced in the same order as the queue.

Examples of Automatic Kernel Failover in Use
1. In the following example, Kernel 1 (DMKA1) was started up on
   NODEA, NODEB, and NODEC. By typing out the Kernel's log files,
   we can see that the Kernel has started on NODEA, and is queued and
   waiting to run on NODEB and NODEC. Note that each Kernel job
   opens the same name output file so several versions of the file may
   need to be checked.




                                                          Communications  277
                   *** DM$RUNDMK:DMO01.DAT;-2 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******
                   Kernel DMKA1 starting up on node NODEA at 08:11:44 on 29-JUL-1987.
                   ******
                   I 1515 Kernel Number 01 started on Jul 29, 1987 at 08:11:54
                   I 1515 with 32 IPC lines and 10 NET lines.


                   *** DM$RUNDMK:DMO01.DAT;-1 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******
                   Kernel DMKA1 queued and waiting on node NODEB at 08:12:32 on 29-JUL-1987.
                   ******


                   *** DM$RUNDMK:DMO01.DAT;0 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******
                   Kernel DMKA1 queued and waiting on node NODEC at 08:12:42 on 29-JUL-1987.
                   ******

                   The DMCTLK utility can be also used to show the status of the
                   Kernels:
                   $ DMCTLK
                   DMCTLK V1 R0 870622

                   Kernel DMKA1     Release E1
                   Node             PID       Status
                   --------------- -------- ------
                   NODEA            20C01C8B Active
                   NODEB            20602227 Backup
                   NODEC            2040263F Backup
                   NORMAL TERMINATION - DMCTLK

                   If NODEA were to fail, Kernel DMKA1 would begin processing on
                   NODEB since it was started and queued before the Kernel on NODEC.
               2. In this example, NODEA has failed. The same Kernels started in the
                  previous example were running at that time. The same Kernel output
                  files could be typed out again:
                   *** DM$RUNDMK:DMO01.DAT;-2 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******




278  Communications
Kernel DMKA1 starting up on node NODEA at 08:11:44 on 29-JUL-1987.
******




                                                    Communications  279
                   I 1515 Kernel Number 01 started on Jul 29, 1987 at 08:11:54
                   I 1515    with 32 IPC lines and 10 NET lines.

                   Note: This is the output file from the Kernel that was running on
                   NODEA. There is no indication here that anything has happened since
                   its node failed.
                   *** DM$RUNDMK:DMO01.DAT;-1 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******
                   Kernel DMKA1 queued and waiting on node NODEB at 08:12:32 on 29-JUL-1987.
                   ******
                   ******
                   Kernel DMKA1 starting up on node NODEB at 08:56:25 on 29-JUL-1987.
                   ******
                   I 1550 Beginning recovery phase.
                   I 1551 Opening databases marked open in SSR.
                   I 1552 No transactions in progress.
                   I 1556 Updating the SSR.
                   I 1557 Closing databases that have no users.
                   I 1565 Database TOUR0 had no transactions in progress.
                   I 1565 Database DTOUR had no transactions in progress.
                   I 1559 Recovery setup phase finished.
                   I 1515 Kernel Number 01 started on Jul 29, 1987 at 08:56:38
                   I 1515    with 32 IPC lines and 10 NET lines.

                   Note:   The first backup Kernel automatically started up when NODEA
                   failed. A message is printed to the Kernel's output file when the
                   Kernel begins processing. The Kernel automatically recovers any open
                   DBs when it is started.
                   *** DM$RUNDMK:DMO01.DAT;0 ***

                   $ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
                   %SET-I-MODESET, process set to /DUMP
                   DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
                   ******
                   Kernel DMKA1 queued and waiting on node NODEC at 08:12:42 on 29-JUL-1987.
                   ******

                   The status of the Kernel on NODEC remains the same. The DMCTLK
                   utility reflects the new status:
                   $ DMCTLK
                   DMCTLK V1 R0 870622

                   Kernel DMKA1        Release E1
                   Node                PID          Status
                   ---------------     --------     ------
                   NODEB               20602227     Active
                   NODEC               2040263F     Backup
                   NORMAL TERMINATION - DMCTLK




280  Communications
Assume NODEA is now operational. NODEA is normally the primary
node for the Kernel because it is a faster machine. If the Kernel is
started on NODEA while it is currently running on NODEB and
queued on NODEC, it is queued after the Kernel on NODEC. In order
to get Kernel 1 back up on NODEA, the currently active Kernel must
be terminated. When a Kernel is terminated through DMSA or the
DM$:STOPDMK procedure, any Kernels that are queued
automatically terminate. So, to continue with the previous example,
the Kernel on NODEB is terminated. The log files contain the
following:
*** DM$RUNDMK:DMO01.DAT;-1 ***

$ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
%SET-I-MODESET, process set to /DUMP
DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
******
Kernel DMKA1 queued and waiting on node NODEB at 08:12:42 on 29-JUL-
1987.
******
******
Kernel DMKA1 starting up on node NODEB at 08:56:25 on 29-JUL-1987.
******
I 1550 Beginning recovery phase.
I 1551 Opening databases marked open in SSR.
I 1552 No transactions in progress.
I 1556 Updating the SSR.
I 1557 Closing databases that have no users.
I 1565 Database TOUR0 had no transactions in progress.
I 1565 Database DTOUR had no transactions in progress.
I 1559 Recovery setup phase finished.
I 1515 Kernel Number 01 started on Jul 29, 1987 at 08:56:38
I 1515    with 32 IPC lines and 10 NET lines.
I 1514 Kernel Termination requested on Jul 29, 1987 at 10:07:40
I 1514 by user SAUID (PID=20C01F16) from program DMSA
Normal Termination of DMK on Jul 29, 1987 at 10:14:38
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065511.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065512.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065513.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065514.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065515.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065516.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065517.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065518.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065519.DMT;1
deleted (352 blocks)
%DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065520.DMT;1
deleted (352 blocks)




                                                    Communications  281
                   %DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065531.DMT;1
                   deleted (352 blocks)
                   %DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065532.DMT;1
                   deleted (352 blocks)
                   %DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065533.DMT;1
                   deleted (352 blocks)
                   %DELETE-I-FILDEL, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]KU1065534.DMT;1
                   deleted (352 blocks)
                   %DELETE-I-TOTAL, 14 files deleted (4928 blocks)
                   %PURGE-I-NOFILPURG, no files purged




282  Communications
%PURGE-I-FILPURG, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]DMO01.DAT;56
deleted (80 blocks)
%PURGE-I-FILPURG, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]DMO01.DAT;55
deleted (12 blocks)
%PURGE-I-FILPURG, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]DMO01.DAT;54
deleted (12 blocks)
%PURGE-I-FILPURG, DEV$DMPROD:[DMROOT.RELE1.DM.RUNDMK]DMO01.DAT;53
deleted (8 blocks)
%PURGE-I-TOTAL, 4 files deleted (112 blocks)
$ EXIT
DMPROD job terminated at 29-JUL-1987 10:15:08.24

Accounting information:
Buffered I/O count: 4324          Peak working set size: 4096
Direct I/O count: 1777            Peak page file size: 3582
Page faults: 2310                 Mounted volumes: 0
Charged CPU time: 0 00:01:35.06   Elapsed time: 0 02:02:51.69

Note: This was normal termination of the Kernel; the Kernel performed
its normal file cleanup
*** DM$RUNDMK:DMO01.DAT;0 ***

$ IF F$MODE() .NES. "INTERACTIVE" THEN $ SET NOVERIFY
%SET-I-MODESET, process set to /DUMP
DMK V1 R147 870727 LIB(D625 S105 A151) [E1]
******
Kernel DMKA1 queued and waiting on node NODEC at 10:06:28 on 29-JUL-
1987.
******
******
Kernel DMKA1 canceled on node NODEC at 10:14:18 on 29-JUL-1987
prior to execution due to NORMAL termination of previous Kernel.
******
Normal Termination of DMK on Jul 29, 1987 at 10:14:18
$ EXIT
DMPROD job terminated at 29-JUL-1987 10:14:18.72

Accounting information:
Buffered I/O count: 113           Peak working set size: 968
Direct I/O count: 55              Peak page file size: 1633
Page faults: 645                  Mounted volumes: 0
Charged CPU time: 0 00:00:01.65   Elapsed time: 0 00:07:57.51

Note:When the Kernel was terminated on NODEB, it signaled to the
Kernel on NODEC that it should terminate also due to the termination
request.

The DMCTLK status shows:
$ DMCTLK
DMCTLK V1 R0 870622
No active Kernels at this time.
NORMAL TERMINATION - DMCTLK




                                                    Communications  283
                   At this time there are no active Kernels, so Kernel DMKA1 may be
                   started on NODEA again first, followed by NODEB and NODEC.
                   This returns the BASIS Kernel configuration to its "normal" state.




284  Communications
Initiating Automatic Kernel Failover
You should consider several items when you determine how you're going
to establish automatic Kernel Failover when a node is started in a clustered
environment. First, determine the PRIMARY and SECONDARY nodes.
These nodes may be determined by groupings of users, speed of machines,
general purpose of the machine itself, etc. Typically, it is better to have
users and their Kernel on the same machine. Second, decide how the
failover system is to be started. In general, the system startup procedure
calls or submits a procedure to start the Kernels.

From where should these procedures be executed?
[ ] In the cluster-wide startup procedure?
[ ] In the node-specific startup procedures?

Normally, all nodes in a cluster are never down at the same time. When
this is the case, if a startup procedure is executed from a node-specific
startup procedure, only when that node is restarted would the Kernel
startup procedure be executed. Or, if that node did not come up when the
whole cluster was rebooted, the Kernel would not be started. On the
other-hand, if the BASIS startup procedure is executed from the cluster-
wide startup procedure, anytime a node is booted, an attempt to restart the
Kernels is made.

Note that the BASIS environment should ALWAYS be established on
every node running BASIS. The environment is established by assigning
the DEV$DMPROD device and executing DM$:SETUPDM.COM. This
is done before the startup procedure is executed.

Once you decide how to execute the startup procedure, develop a
procedure for starting the Kernels in the configuration. The following is
an example of the procedure necessary to startup the Kernels used in the
previous examples. It was decided that this procedure would be submitted
from the primary node's startup procedure. In the event that the primary
node could not come up when the cluster was rebooted, the operators are
instructed to submit this procedure on one of the secondary nodes.
   $! TITLE:        STARTDM.COM
   $!



                                                        Communications  285
                   $! PURPOSE:      Procedure to start the BASIS Kernels in the cluster
                   $!
                   $! DIRECTIONS:   This procedure is submitted by the system startup
                   $!               procedure.
                   $!
                   $!
                   $!               SUBMIT/USER=DMPROD/NOPRINT/QUEUE=queue -
                   $!                  /LOG=DEV$DMPROD:[DMROOT.DM]STARTDM.LOG -
                   $!                  DEV$DMPROD:[DMROOT.DM]STARTDM.COM
                   $!
                   $! NOTES:        Before this proc runs, the BASIS environment should
                   $!               already be created; i.e., the system startup procedure
                   $!               should have already assigned the DEV$DMPROD device
                   $!               name, and executed SETUPDM.COM and INSTDMK.COM.
                   $!




286  Communications
   $!
   $!              This proc will setup the following Kernel
   $!              configuration:
   $!
   $!              DMKA1 - NODEA - primary BASIS Kernel
   $!              DMKA1 - NODEB - first backup BASIS Kernel
   $!              DMKA1 - NODEC - second backup BASIS Kernel
   $!
   $!
   $! Define BASIS commands and logicals for this process
   $!
   $ @DM$COMMANDS
   $!
   $! Startup Kernel 1 on the primary node
   $!
   $ SUBMIT /NOPRINT/QUEUE=NODEA_BATCH/LOG=DEV$DMPROD:[DMROOT.DM]   -
       STARTDMK.LOG/PARAM=A1 DM$:STARTDMK.COM
   $!
   $! Give the Kernel on NODEA enough time to get started
   $!
   $ WAIT 00:03:00
   $!
   $! Startup Kernel 1 on the first backup node
   $!
   $ SUBMIT /NOPRINT/QUEUE=NODEB_BATCH/LOG=DEV$DMPROD:[DMROOT.DM]   -
       STARTDMK.LOG/PARAM=A1 DM$:STARTDMK.COM
   $!
   $! Give the Kernel on NODEB enough time to get queued as first   backup
   $!
   $ WAIT 00:03:00
   $!
   $! Startup Kernel 1 on the second backup node
   $!
   $ SUBMIT /NOPRINT/QUEUE=NODEC_BATCH/LOG=DEV$DMPROD:[DMROOT.DM]   -
       STARTDMK.LOG/PARAM=A1 DM$:STARTDMK.COM
   $!
   $! That's it
   $!
   $ EXIT

As an alternative to this approach, assume that it does not matter where the
Kernel gets started, just as long as it is always available. The following
procedure could be submitted from the cluster-wide startup procedure,
which would allow it to be executed by any machine that gets booted in
the cluster. Note that with this implementation, the BASIS environment
could be setup in this proc prior to starting the Kernel.
   $! TITLE:        STARTDM.COM
   $!
   $! PURPOSE:      Procedure to start a BASIS Kernel on whatever node
   $!               this is executed from
   $!
   $! DIRECTIONS:   This procedure is submitted by the system Startup
   $!               procedure.
   $!
   $!
   $!               SUBMIT/USER=DMPROD/NOPRINT/QUEUE=queue -
   $!                 /LOG=DEV$DMPROD:[DMROOT.DM]STARTDM.LOG -
   $!                 DEV$DMPROD:[DMROOT.DM]STARTDM.COM



                                                        Communications  287
                   $!




288  Communications
   $! NOTES:       Before this proc runs, the BASIS environment should
   $!              already be created, i.e., the system startup procedure
   $!              should have already assigned the DEV$DMPROD device
   $!              name, and executed SETUPDM.COM and INSTDMK.COM.
   $!
   $!              If this procedure is being executed simultaneously on
   $!              another node in this cluster, whichever Kernel gets
   $!              a lock on the Kernel resource first will be the active
   $!              Kernel, the other will be queued.
   $!
   $!
   $! Define BASIS commands and logicals for this process
   $!
   $ @DM$COMMANDS
   $!
   $! Startup the Kernel
   $!
   $ STARTDMK A1
   $!
   $ EXIT

There is no perfect solution for setting up Automatic Kernel Failover.
There are many site-specific variations and needs. It is important to
determine your site's needs, and then implement a solution.




                                                        Communications  289

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:26
posted:7/27/2011
language:English
pages:151