Design overview

What is a builder (DFHBS*)?

A builder is responsible for all the actions that can occur on a particular subcomponent of the TCTTE. The term subcomponent means a separately obtained area of storage which is referenced from the TCTTE or a collection of fields in the TCTTE that are logically associated with one another. General terms sometimes used instead of subcomponent are object or node. For example, the NIB descriptor, LUC extension, and BMS extension are all considered to be subcomponents.

Builder parameter set (BPS)

Each time a calling module invokes DFHZCQ for INSTALL, it supplies a builder parameter set (BPS). The BPS describes the device to be defined. The device-type is determined by matching attributes in the BPS with a table of definitions, DFHTRZYT, in module DFHTRZYP.

A BPS consists of a fixed-length prefix, a bit map preceded by its own length, an area for fixed-length parameters preceded by its own length, and three variable-length parameters, BIND, USERID, and PASSWORD. Each variable-length parameter has a 1-byte length field.

TCTTE creation and deletion

This topic starts by describing the structure of the main components involved in the process of creating and deleting TCTTEs. Figure 17 is in two halves: the top half shows those components that can initiate the process of collecting all the necessary data or parameters that go toward fully defining a TCTTE, and the bottom half is concerned with how to go about creating the TCTTE after it has the full set of parameters. Thus, all the processes are aiming for the same common interface. This topic deals first with the top-level processes that are activated to create or delete TCTTEs; for the time being, assume that after returning from the DFHZCQ interface a TCTTE has been created. (For a more detailed description, see DFHZCQ and TCTTE generation.)

Figure 17. Top-level view of the components participating in TCTTE creation
 This is a technical drawing showing the components participating in TCTTE creation, and the relationships between them.

Component overview

DFHTCRP

The DFHTCRP program is responsible for reestablishing the TCTTEs that were in existence in the previous run. There are conceptually three stages of processing in this module:

  1. Initialize DFHZCQ. Initialize DFHAPRD. If START=COLD, terminate.
  2. Reestablish TCTTEs that were saved on the CICS® catalog. If START=WARM, terminate.
  3. Call DFHAPRDR to forward-recover in-flight TCTTEs from the system log, if an emergency restart is being performed.

DFHAMTP

The DFHAMTP program is used as part of INSTALL processing. It calls DFHTOR, then DFHZCQ.

DFHZATA and the CATA transaction

CATA is a transaction that is initiated by the logon exit and causes DFHZATA to run. It is passed the CINIT which is used to deduce the parameters which must be passed to DFHZCQ in order to create a TCTTE.

DFHZTSP

The terminal sharing program, DFHZTSP, is used by transaction routing for devices of all types, exclusively so for non-APPC devices.

DFHZCQ

The DFHZCQ program supports the INSTALL and DELETE interface that results in the TCTTE being created or deleted. It relies on its callers to supply the complete set of parameters that are to be used to create the TCTTE; that is, it is not responsible for determining parameters for the TCTTE.

DFHBS* builder programs

The builders are responsible for creating the TCTTE. The parameters given to DFHZCQ are passed on to the builders. They extract the parameters and set the relevant fields in the TCTTE.

DFHTBS

The DFHTBS program is an interpreter that uses a pattern given to it by DFHZCQ to drive the whole TCTTE creation or deletion process according to certain rules.

DFHAPRDR

The DFHAPRDR program is the orchestrator of the commitment of TCTTE creation or deletion. It is responsible for driving DFHTBSS and DFHTONR for syncpoints, during cold start and also for recovering in-flight creates or deletes from the system log during emergency restart. It is called by the Recovery Manager, DFHTCRP and DFHAMTP during start-up and directly from DFHTBS (to roll-back an atom).

DFHTBSS

The DFHTBSS program is responsible for logging forward recovery records and for updating the catalog as a result of the request initiated by DFHZCQ and actioned by DFHTBS. It is driven by DFHAPRDR.

DFHTONR

The DFHTONR program is responsible for logging forward recovery records and for updating the catalog for install or delete requests for TYPETERMS. It is driven by DFHAPRDR.

DFHZGTA

DFHZGTA is the module called by DFHBS* and DFHZTSP (for remote system entry sessions) to add or delete index entries for TCTTE entries. It maintains locks on terminal namespaces, and handles calls to TMP to add, quiesce, delete, unlock and unquiesce entries. It is driven at syncpoint or rollback for an atom by DFHAPRDR.

DFHZCQ and TCTTE generation

This topic describes how a TCTTE gets built and deleted. You need to understand at least one method by which a builder parameter set (BPS) is created; for example, CEDA INSTALL or AUTOINSTALL. A BPS contains all the values necessary for the creation of a TCTTE.

Figure 18 gives a more detailed view of the main components involved in the INSTALL process.

Figure 18. Major active components in the INSTALL process
 This technical drawing illustrates the major active components in the install process.
The four-stage process

In summary, the process consists of four stages:

  1. Collecting the parameters together.
  2. Creating the storage for the TCTTE and copying the parameters. Note however, that at the end of this stage, a TCTTE has effectively been built. It is still unknown to the rest of the CICS system, that is, the TCTTE name has not been exposed. The modules involved here are DFHTBSB and DFHBS*.
  3. Producing a recovery record. This is done at syncpoint processing time in the DFHTBSS module. This stage is usually called Phase 1 syncpoint.
  4. Writing or updating the catalog. Again, this is done in DFHTBSS and is called Phase 2 syncpoint. It is at about this stage that the TCTTE name becomes exposed and known to the rest of CICS.

What is DFHZCQRT?

DFHZCQRT is an array of "patterns" where each pattern defines a list of builders that need to be called in order to create this particular type of TCTTE, that is, a pattern is equivalent to a type of terminal. The array entry consists of two parts: information that is private to DFHZCQ, and the pattern that is interpreted by DFHTBS.

What does DFHTBSBP do?

The pattern entry is passed to DFHTBSBP (via DFHTBSB) after it has been found by DFHZCQIS. DFHTBSBP calls each builder identified by the pattern in sequence to create the object for which the builder is responsible. Note that DFHTBSBP knows nothing about the TCTTE; DFHTBSBP merely follows a set of simple rules. It keeps an audit trail of each builder that is called.

What is the RRAB used for?

The audit trail kept by DFHTBSBP is implemented by obtaining a Resource definition Recovery Anchor Block (RRAB) that has some user storage attached to it. As DFHTBSBP calls each builder to perform an action, it adds an "action element" to the RRAB. (See What is syncpointing?) The address of the RRAB for a UOW is held in the ‘APRD’ recovery manager slot, which ensures that DFHAPRDR will be called at syncpoint. The RRAB stores the action blocks in two types of chains, one for actions that are not part of a named resource definition 'atom' and one for actions that are part of a named atom. This later type are chained off a Resource definition Action Name block (RABN). Also held in the RRAB is an indicator set by DFHTOR if DFHTONR should be called at syncpoint (if a typeterm has been installed), and a chain of Resource Definition Update Blocks (RDUB).

What is a resource definition 'atom'?

Certain resource definitions must be installed or deleted as a single set. These definitions are called a resource definition 'atom'. CICS installs the members of a RDO group as individual resource definitions, which can fail without causing the other resources to fail except for these atoms, which bear the name of the logical set of definitions. For example:

A connection and its associated sessions
is named for the connection
A pool of terminals
is named for the pool of terminals

What is a Resource definition Atom Name block (RABN)?

The RABN is only created for those atoms of resource recovery that are named. It holds the name of the atom, a chain of action elements for the atom, and the recovery outcome of the atom (whether it failed and was backed out, or succeeded and should be committed). DFHTBSB uses the RABN to decide if a session definition should not be installed because the install of the parent connection has already failed, for example. In our auto-install example, if the definition being installed is a parallel connection, there will be a RABN for it from which the action elements are chained.

What is a Resource Definition Update Block (RDUB)?

The RDUB is a record of locks held by a UOW against names in three namespaces:

  1. Termids and Sysids
  2. Netnames
  3. Unique ids (Composed of the Netname of a Terminal Owning Region followed by a period ‘.’ followed by the Termid or Sysid in that TOR)

During the installation, deletion, or replacement of a TCTTE definition the builders DFHBS* obtain locks by calling DFHZGTA. These locks guarantee exclusive or shared access to names in these namespaces. Exclusive access is used to prevent another task from installing another definition with the same name, netname or unique-id while this UOW is trying to install or delete (an action which may have to be reversed). Shared access is used to block another task from deleting an entry that a definition that this task is updating (for example, a system definition name may be locked by a remote terminal definition that refers to it).

RDUBs also exist on a global chain so that other UOWs can easily find out if a particular lock is held.

What is syncpointing?

When DFHTBSBP has exhausted the list of builders, it returns to its caller. Similarly, DFHZCQIS returns to its caller, which could have been autoinstall. However, there is still an audit trail that is attached to the RRAB. It is only when the calling task terminates or issues DFHSP USER or EXEC CICS SYNCPOINT that the next two stages occur.

Syncpoint processing consists of two phases. The first phase (prepare phase) requires the resource manager to write a forward-recovery record to the log. Thus, if the second phase (commit phase) fails to write to the catalog, this recovery record can be used to forward-recover the action on an emergency restart.

DFHTBS

The DFHTBS program is an interpreter that uses a pattern given to it by DFHZCQ to drive the whole TCTTE installation or deletion process according to certain rules.

DFHAPRDR

DFHAPRDR is invoked by recovery manager if the ‘APRD’ RM slot is non-zero. This slot contains the address of the RRAB for this UOW if any resource definition has taken place. It is also called by DFHTBS directly if an atom needs to be rolled-back or to commit an atom during Cold Start. DFHAPRDR examines the RRAB and chooses whether to call DFHTBSS, DFHTONR and DFHZGTA for each phase of syncpoint or individual atom commitment.

If either DFHTBSS or DFHTONR have records to log/catalog, DFHAPRDR calls the recovery manager to request that a record is written to the catalog noting that a forget record will be written once syncpoint completes. The purpose of this call is that if CICS should fail between the start of syncpoint phase 2 and the end, on an emergency restart recovery manager will call DFHAPRDR with the log records for this UOW so that they can be re-applied to the catalog, and the TCTTE entry or entries can be re-built.

DFHTBSS

The DFHTBSS program is responsible for performing the correct recovery actions for each atom and UOW at syncpoint (or during the rollback of an individual atom). It writes forward recovery records to the system log and updates the catalog during phase 1 and phase 2 of syncpoint respectively. It is directly driven by DFHAPRDR.

The purpose of the builder (DFHBS*) modules is to build a TCTTE, TCTSE, and TCTME and its associated control blocks. A TCTTE is built for terminals only; a TCTSE and TCTME are built for both LU6.1 with MRO and LU6.2 single sessions; all three are built for LU6.2 parallel sessions. DFHTBSS is invoked by DFHAPRDR with a parameter list that indicates whether this call is for an individual atom or for syncpoint and which phase is in force. For phase 1, it uses the action blocks audit-trail to recall each builder. It asks each builder to supply the address and length of the subcomponent so that it can create a single record containing a copy of each component as a list; that is, the first part of the record contains a copy of the object created by the first builder in the sequence, the second part contains a copy of the object created by the second builder, and so on until the audit trail list is finished. This record is then written to the system log as a forward recovery record.

When DFHTBSS is reentered for the second phase (again a parameter on the call by DFHAPRDR), it uses the record created in the first phase as the record that is written to the catalog. During this stage, each builder is called to tidy up after the object for which it is responsible; for example, for the TCTTE itself, it puts the TCTTE in service.

Again note, DFHTBSS only implements a set of rules.

DFHTONR

DFHTONR is responsible for writing catalog records for TYPETERMs. It is called by DFHAPRDR.

DFHZGTA

DFHZGTA is the module that is called by DFHBS* modules to add index entries for TCTTE entries so that they can be located quickly either by DFHZLOC, DFHZGTI or in VTAM® exit code. It calls DFHTMP services. It obtains and releases locks using the RDUB blocks, and at syncpoint is responsible for releasing all TMP locks and unquiescing any TMP entries that were quiesced by DFHBS* modules.

Summary

Example of an autoinstall

Consider the following: a terminal operator has logged on to the system and is being autoinstalled. The CATA transaction is responsible for collecting together the parameters required for the DFHZCQ INSTALL.

The process continues from the point where the DFHZCQ INSTALL is issued from CATA:

  1. A call has been made to cause an install to occur. DFHZCQ ensures that other related modules are already loaded.
  2. DFHZCQ calls the install-specific module (given in the parameter block passed to DFHZCQ)
  3. DFHZCQIS performs various checks on the parameters passed by the caller of DFHZCQ.
  4. DFHZCQIS finds a pattern in DFHZCQRT that matches with information given in the parameters.
  5. DFHZCQIS calls DFHTBS with the pattern and parameters.
  6. DFHTBS routes the request to DFHTBSB; it is omitted from further discussions.
  7. DFHTBSB checks that a valid pattern has been passed.
  8. DFHTBSB creates the RRAB which gets attached to the APRD Recovery Manager slot.
  9. DFHTBSB calls the next builder as defined by the pattern.
  10. Each builder (DFHBS*) creates its section of the TCTTE.
  11. DFHTBSB adds an action element to the RRAB giving information about this particular builder.
  12. Steps 9, 10, and 11 are repeated until the pattern is finished.
  13. DFHTBSB tidies up the RRAB and returns.
  14. DFHTBS returns.
  15. If the return code was 'OK', DFHZCQIS returns the address of the hidden TCTTE.
  16. DFHZCQ returns.
  17. The caller continues until DFHSP USER is issued or the task terminates.
  18. DFHAPRDR invokes DFHTBSS with the RRAB indicating phase 1.
  19. DFHTBSS examines the RRAB to determine phase.
  20. Using the action elements created in step 11, DFHTBSS recalls each builder asking for information to be saved on the recovery log.
  21. Each builder (DFHBS*) returns the address of the object built in step 10.
  22. Using these addresses, DFHTBSS builds the recovery record.
  23. DFHTBSS writes the recovery record to the system log.
  24. DFHTBSS saves the stored version for the next phase.
  25. DFHTBSS returns.
  26. Recovery Manager calls all other resource managers that have a part to play in the process; it knows this because there are addresses in the RM slots for this UOW.
  27. DFHTBSS is called for phase 2. It reuses the in-storage version of the recovery record to write to the catalog.
  28. DFHTBSS returns.

Patterns, hierarchies, nodes, and builders

Patterns were introduced in the previous topic. This topic examines in detail what they look like. To achieve this, several terms have to be explained.

What is a hierarchy?

In this context, "hierarchy" is another word for tree. The structure of the TCTTE can be thought of as a tree: at the top node is the TCTTE itself, containing pointers to lower-level nodes.

Figure 19 shows the master node as the TCTTE, with subnodes connected to it (BMS extension, special features extension, and so on).

Figure 19. TCTTE structure
 This figure illustrates the structure of the TCTTE. The TCTTE is shown as a master node, with pointers to the subnodes "BMS extension", "Special features extension", "LUC systems extension", and "NIB descriptor extension".

As a result of this structure, it can be seen that the creation process must follow several rules. For example, the storage for the master node has to be obtained before pointers to subnodes are saved in it.

What is a pattern?

The objective of a pattern is to reflect or represent the hierarchy as described above. Figure 20 outlines the shape of a pattern. For each of the nodes in Figure 19, there is a pattern. Starting with the TCTTE (the master node), there is a master pattern. B1offset references the subpattern for the BIND image node; B2offset references the subpattern for the BMS extension node; B3offset and B4offset reference the subpatterns for user area and SNTTE subnodes respectively. In total, there are five patterns: the master pattern and four subpatterns--so what is meant by pattern above was really a collection of patterns.

Figure 20. Pattern structure
 The pattern contains a pattern name, builder address, and offsets "B1offset", "B2offset", to "Bnoffset".

Note that each pattern contains the address of a builder, so we could represent the TCTTE structure as:

Figure 21. Patterns and subpatterns
 The master pattern refers to the master builder, DFHBStz. The master pattern also refers to subpatterns, and each subpattern refers to a sub-builder. The sub-builders are DFHBStzb, DFHBStb, DFHBSto, DFHBStc and DFHBSts.

The purpose of the builders

The purpose of the builders is to centralize the major functional code for creation and deletion of the nodes associated with the TCTTE. Figure 20 and Figure 21 show how the patterns refer to the builders; the pattern is exploited by the DFHTBS* code to activate the relevant builder function. For example, DFHTBSBP, when given a pattern, extracts the address of the builder and invokes the BUILD function belonging to the builder.

How does DFHTBSBP do its work?

First, you must examine more closely the structure of a builder in Figure 22.

Figure 22. The builder stub
 This is a technical drawing showing the structure of a builder.

Remember that the pattern references a builder. In fact, it references a stub, the first word of which points to a table (BSH_EP_TABLE), and is followed by code that is responsible for enacting the entry as required by the caller. For example, if the caller wanted to call BUILD, a call would be made to the stub with value 1. The stub would extract the offset to the build code from the BSH_EP_TABLE, and perform the call.

Thus, making a call from DFHTBS* to DFHBS* is relatively simple: all that is needed is the function number (1 for BUILD, 2 for DESTROY, ...), a call to the stub, and the pattern.

Summary

The DELETE process

By examining the hierarchy (see Figure 19), you can see that there are certain rules that have to be established. Firstly, you should check that the TCTTE and its subcomponents are quiesced, that is, there is no activity in progress. And secondly, and perhaps more obviously, the top node must not be the first object to be freed. From this, you can derive two basic rules, or "functions", that must be supplied by any DFHBS*:

UNREADY
For all nodes associated with the master node. Ensures that no activity is occurring; for example, that a CLSDST is not in progress. It must also achieve exclusive ownership of the object; for example, ZGTA QUIESCE ensures no locates on the given TCTTE succeed and that no other UOWs can install another similarly named object until syncpoint. Further, it initiates the ZGTA DELETE which does a TMP DELETE to remove the entry.
DESTROY
Lower objects first. (See What about the "lower objects first" rule?:) Frees the storage belonging to the node.

What about the "lower objects first" rule?

Figure 23 tries to add meaning to the descriptions of the UNREADY and DESTROY functions. As each builder is called (as determined by the master pattern), DFHTBSD records an audit trail of called builders. However, the audit trail is managed slightly differently for the delete process, to guarantee order of processing by DFHTBSS at phase 2 time. For further information, see Completing the process description.

Figure 23. Major active components in the DELETE process
 This is a technical drawing showing the components in the DELETE process and their relationship to each other.

Example of a reinstall

  1. CEDA reads the CSD and converts the definition into a builder parameter set (BPS).
  2. CEDA issues a DFHZCP INSTALL passing the BPS.
  3. Using the resource type code in the BPS, DFHZCQIS searches the DFHZCQRT table for the associated pattern.
  4. DFHZCQIS calls DFHTBSB passing the BPS and the pattern.
  5. DFHTBSB checks the pattern and creates a resource definition recovery action block (RRAB) for the audit trail.
  6. Using the pattern, DFHTBSB calls the CHECKSET entry point of the associated builder.
  7. The master builder does a DFHZGTI LOCATE to check whether the TCTTE already exists.
  8. A TCTTE is found to exist, so the builder issues DFHZCP DELETE passing the address of the old TCTTE.
  9. When a TCTTE is created, its position within the DFHZCQRT table is saved in the TCTTE. DFHZCQDL uses this value to find the pattern associated with this TCTTE.
  10. DFHZCQDL calls DFHTBSD passing the object to be deleted and the pattern.
  11. DFHTBSD extends the audit trail so that information about this delete can be recorded.
  12. DFHTBSD calls the UNREADY entry of each builder.
  13. Each builder (DFHBS*) checks whether its part of the TCTTE is being used (and vetoes the UNREADY if it is). It calls ZGTA QUIESCE and ZGTA DELETE to lock and remove the index entries.
  14. DFHTBSD updates the audit trail for each called builder.
  15. DFHTBSD returns.
  16. DFHZCQDL returns.
  17. The master builder checks the return code (that is, that no builder vetoed the UNREADY).
  18. The master builder returns.
  19. DFHTBSB checks the return code and recalls each builder at the BUILD entry point passing the BPS.
  20. Each builder obtains some storage and copies the parameters from the BPS. It uses ZGTA ADD calls to lock and add index entries
  21. DFHTBSB tidies up the RRAB and returns.
  22. DFHZCQIS records the position within DFHZCQRT that enables DFHZCQDL to find the pattern.
  23. DFHZCQIS Returns.
  24. CEDA checks the return code and issues DFHSP USER.
  25. Note:
    At this stage there are two TCTTEs: the old one that was UNREADY and the new one.
  26. CEDA calls: DFHTBSS is entered for the first time (phase 1). The audit trail consists of two parts (A and B). Part A contains the list of builders involved with the UNREADY; part B contains the list of builders that created the new TCTTE.
  27. CEDA writes a recovery record to the system log for Part A indicating that a delete is about to take place in phase 2.
  28. CEDA creates a recovery record from Part B which represents the new TCTTE to be built.
  29. CEDA calls each builder asking for its subcomponent (FLATTEN).
  30. DFHZQIX returns an address and length.
  31. CEDA concatenates each subcomponent into the recovery record.
  32. CEDA writes the recovery record to the system log.
  33. CEDA returns (end of phase 1).
  34. CEDA reenter for phase-2 processing.
  35. CEDA processes Part A, calling the DESTROY entry for each builder.
  36. Each builder frees its part of the old TCTTE.
  37. CEDA processes Part B of the audit trail.
  38. CEDA writes the recovery record to the catalog.
  39. CEDA calls the READY entry point for each builder on the audit trail.
  40. Each builder does any tidying up that needs to be done.
  41. CEDA returns.

Completing the process description

To complete the description of the creation and deletion process, two further functions must be described: CONNECT and READY.

CONNECT

Figure 19 shows the TCTTE hierarchy. All that has happened at build time is that the separate parts of the TCTTE have been obtained. Access to these subcomponents is achieved by referencing pointers that are held in the TCTTE. So the CONNECT builder entry point is used to join the subcomponent to the TCTTE.

READY

The READY builder entry point is provided to enable any final tidying up that may be required at the end of the build process. For example, if the TCTTE has the AUTOCONNECT option, a SIMLOGON is initiated from this entry point. In general, this entry point is rarely used.

The creation/deletion state machine

Figure 24 shows the symmetry between the various builder functions.

Figure 24. Create/delete state diagram
 The states shown are as follows: State 1 -- TCTTE visible. State 2 -- TCTTE hidden and vetoed. State 3 -- TCTTEs hidden. State 4 -- (Partial) TCTTEs and vetoed. State 5 -- Nothing. The builder functions to move between pairs of states are as follows: State 1 to States 2 or 3, UNREADY. States 2 or 3 to State 1, READY. State 3 to State 5, DESTROY. State 5 to State 3, BUILD and CONNECT. State 4 to State 5, DESTROY. State 5 to State 4, BUILD.

The starting point can be either state 5 (installing a TCTTE) or state 1 (deleting a TCTTE). Thus, if several TCTTEs had been successfully built, but the last one resulted in an error, we would end up in state 4. If it were not for the last one, we would have ended up in state 3. So the caller is returned an error response, and issues a DFHSP ROLLBACK. This causes DFHTBSS to call the DESTROY function of the builders for all elements on the audit trail--even for those that were "successfully" built in this atom, or UOW. Thus, an install of a atom can be perceived as one complete unit. During the DESTROY process, if the atom is being rolled-back, the builders call ZGTA QUIESCE and ZGTA DELETE to remove index entries for the new TCTTE. Likewise during the READY process, if a delete is being rolled back, the builders call ZGTA ADD to re-instate index entries for the TCTTE.

The hierarchy and its effect upon the creation process

Summary so far

This topic now looks in greater detail at how the control of the builder calling process is implemented. To do that, you need to understand in greater detail the structure of the hierarchy, and the way the DFHTBS components interpret that structure.

Figure 25. A general hierarchy
 Node 1 has subnodes 2 and 3. Subnode 2 has further subnodes, 4, 5 and 6. Subnode 3 has further subnodes, 7, 8, 9 and 10.

Figure 25 shows a more general hierarchy. Node 1 can be considered as a master node: it is at the top of the tree and has two subnodes (2 and 3). However, you could say that node 2 and its subnodes are also a tree: node 2 is the master node, and nodes 4, 5, and 6 are the subnodes. Similarly, with node 3: it has subnodes 7, 8, 9, and 10.

The DFHTBS components exploit the idea that a tree consists of a node with trees below it. In fact, DFHTBSBP uses recursion to access the tree of patterns.

Recursion

This topic demonstrates how recursion is used to process a much simpler structure than that given in Figure 25. The example shown in Figure 26 is for the DFHTBSP program, which has the following parameters:

Input:
PATTERN, HIGHERNODE, and BUILDER
Inout:
AUDITTRAIL
Output:
NODE and RESPONSE.

The following list outlines the flow in DFHTBSBP. The step references refer to steps in this list.

  1. Add and initialize an action to the AUDITTRAIL (this is used later in steps 5 and 11).
  2. Using parameter PATTERN, find the address of the associated builder.
  3. Call the builder stub with function number 1 (for BUILD) with the following parameters:
    Input:
    HIGHERNODE and BUILDER
    Output:
    NODE.
  4. The builder uses the BUILDER parameters to create its specific object. Storage is obtained and the parameters are copied into it.

  5. Check that the response from the build is ‘OK’.
  6. Copy the address of the output parameter NODE into the AUDITTRAIL action.
  7. Process all the subpatterns that may be attached to your pattern
  8. Get the next subpattern Pn.
  9. Call DFHTBSBP with the following parameters:
    Input:
    Pn, NODE, and BUILDER
    Inout:
    AUDITTRAIL
    Output:
    SUBNODE and SUBRESPONSE
    Note:
    In this step, you call yourself again, passing NODE. At the next level of recursion, this appears as HIGHERNODE.
  10. Stop when the last pattern is processed.
  11. Call the builder stub with function number 5 (for CONNECT) with the following parameters:
    Input parameters:
    NODE
    Inout parameters:
    HIGHERNODE
  12. The builder’s CONNECT entry point now places the address as given by NODE into an offset of HIGHERNODE.

  13. Finally, place the address of the pattern into the AUDITTRAIL action.

Simple recursion example

Figure 26. Simple example showing recursion
 The figure shows the use of recursion to process an example structure, as explained in the text above.

Consider the following simplified version of the hierarchy as given in Figure 26. The step references refer to steps in the list in the topic Recursion.

  1. Start with pattern P1. Call its associated builder (step 3). This creates node N1.
  2. All the patterns below P1 are processed, the first of which is P2.
  3. Call DFHTBSBP passing P2, N1, BUILDER parameters, and others:
    1. Using the passed pattern (now P2), call the builder. This creates node N2.
    2. Process all patterns below P2; there are no subpatterns, so steps 6 through 9 in topic 6 are not performed.
    3. Call the CONNECT entry of the builder, passing higher node N1 and the node just created, N2. This makes N1 point to N2.
    4. Return to caller.
  4. Get the next pattern, P3.
  5. Call DFHTBSBP passing P3, N1, BUILDER parameters, and others:
    1. Using the passed pattern (now P3), call the builder. This creates node N3.
    2. Process all patterns below P3; there are no subpatterns, so steps 6 through 9 in topic 6 are not performed.
    3. Call the CONNECT entry of the builder passing in higher node N1 and the node just created N3. This makes N1 point to N3.
    4. Return to caller.
  6. Last pattern processed (step 10).
  7. Call the builder associated with P1 to connect node N1 to HIGHERNODE. (This is zero because there is no higher node. Usually, a master builder’s CONNECT function either does nothing or adds the TCTTE name and address into the table management tables.)

ROLLBACK

What happens when an error occurs during the install process? An example of this would be when one TCTTE within a group is still in service when a CEDA COPY command is being processed for the group with the REPLACE option specified. Example of a reinstall shows such a replace operation. The builders for the existing TCTTE are called (UNREADY) in order to check that the DELETE (FREEMAIN) can proceed. Thus, the audit trail refers to all called builders.

If the "total vote" from all the UNREADY builder calls indicates OK, the build proceeds for the new TCTTE that is to replace the existing one. Thus, at the end of the process, the audit trail consists of a list of references to builders associated with the old TCTTE, and a list of references to builders for the new TCTTE (lists A and B).

Consider the case when the group contains definitions for three TCTTEs, and a VETO occurs for the last one. This means that there is an audit trail for A1, B1, A2, B2 for which there was success, and list A3 for the unsuccessful UNREADY for the third TCTTE.

The failure condition is returned to the caller (CEDA), which then issues a DFHSP ROLLBACK.

Recovery Manager invokes DFHAPRDR which in turn invokes the DFHTBSS module, with a parameter that indicates a rollback is required. Thus, the "A" lists are processed, and all the READY entry points of the builders are called. Then the "B" lists are processed, and the DESTROY builder entry is called to free the storage obtained for the supposedly new TCTTEs.

To summarize, the rollback operation for UNREADY is READY, and the one for BUILD is DESTROY.

Catalog records and the CICS global catalog data set

Overview

The fourth stage of the process is to produce a catalog record that is written to the CICS global catalog data set. This record is used on a subsequent restart to recreate the TCTTE, but in a different way from the "Build" process described above. A CEDA INSTALL means that the TCTTE lives across CICS restarts, avoiding the necessity of rerunning the install.

A RESTORE from the CICS catalog is a faster operation than a CEDA INSTALL because there is no conversion of the CSD definition to a builder parameter set, and less I/O involved.

In summary, a catalog record is produced by recalling each of the builders asking for the address of the data that they want to be recorded on the catalog. Each subcomponent of the TCTTE is then copied and concatenated into one record, which is then written to the catalog. This process is known as FLATTEN.

A CATALOG call is made when significant events change the state of a TCT entry which would be needed on a subsequent emergency restart. An example is the recording of the membername of a generic VTAM resource connection when a bind has occurred for the first time.

On the restart, the record is read from the catalog, and presented back to each of the original builders. Each builder performs a GETMAIN, and copies its section of the recovery record into the acquired storage. This process is known as UNFLATTEN.

At shutdown, auto-installed entries are removed from the catalog with an UNCATALOG call (if they were cataloged because AIRDELAY¬=0). This drives DFHTBS and the builders to produce similar records to those for a DELETE call, but only to take action to delete the catalog record. This is significantly more efficient than calling the builders to DELETE each entry, as the copy in storage is left untouched.

The key and the recovery record

When the build process in DFHTBSBP has finally finished, this module makes a call to the master builder at the MAKEKEY entry point. The builder produces a key that is used to index the associated recovery record. (See Figure 27.)

This information is placed on the audit trail so that it can be picked up by DFHTBSS. It consists of two parts:

  1. Information that allows access to the catalog
  2. The recovery record header.

Figure 27. The recovery record
 The figure shows a recovery record, containing the following information: overall length; token length; a token; the total length of the recovery record; the length of the pattern name; the pattern; the length of the key; and the key.

More about the audit trail

Figure 28 shows the layout of an audit trail. Internally it is known as an action block, which consists of action elements. As each builder is invoked by DFHTBSBP or DFHTBSDP, an action element is appended to the action block. Each element has a reference to a pattern (PATT). This is to allow DFHTBSS to enter the associated builder at the READY or DESTROY entry points.

CCRECP contains the address of the recovery record header. Only one of these is produced as a direct result of the MAKEKEY call to the master builder. All other action elements have their CCRECP set to zero.

Figure 28. Action block and action elements (audit trail)
 This is a technical drawing showing an audit trail, or action block, and its action elements.

DFHTBSS and the FLATTEN process

During phase-1 syncpoint processing, DFHTBSS searches the action elements for a nonzero CCRECP. On detection, it calls DFHTBSLP, passing the reference to the pattern as given in the action element.

The storage "segments" are returned to DFHTBSSP which extracts the address and length from each segment and copies them into the recovery record.

The RESTORE process

The recovery record header contains the pattern name which is used to find the master pattern in DFHZCQRT. This is then passed to DFHTBSR to drive the recovery process by calling each builder’s UNFLATTEN entry.

Each segment is extracted from the recovery record and is passed to the associated builder’s UNFLATTEN entry point. These routines usually obtain some storage and copy the segment into it.

[[ Contents Previous Page | Next Page Index ]]