          P ________________________________________________________________________________P ________________________________________________________________________________      
 Contributions P ________________________________________________________________________________P ________________________________________________________________________________  Q Submissions  to   this  newsletter  are  constantly  sought.    A submission can  Q be  an  article,  a letter to the Wombat Wizard, a technical  tip,  or anything   S of  interest  to  people  using  or considering  the  use  of  Datatrieve    or     Q any  4GL  product.  Submissions on magnetic media are preferred  but  almost any   type will be considered.  L Contributions for  the  newsletter  can  be sent to either of the following 
 addresses:  ; Editor, DATATRIEVE Newsletter       Joseph Gallagher, Ph.D. 6 c/o DECUS U.S. Chapter         Research Medical Center8 219 Boston Post Road, BP02         2316 East Meyer Blvd.5 Marlboro, MA  01752            Kansas City, MO  64132     P ________________________________________________________________________________P ________________________________________________________________________________       Table of Contents P ________________________________________________________________________________    > DECUS U.S. Chapter SIG Newsletters, Volume 3, No. 8, Apr. 19883 Wombat Examiner and 4GL Dispatch,   Volume 9, No. 8   :     DTR-2      -     Context Recognition in VAX Datatrieve#     DTR-22     -     The Story of P D     DTR-25     -     Documenting and Manupulating SYSGEN Parameters 2                                   using Datatrieve)     DTR-29     -     Wombat Wizard Errata           P ________________________________________________________________________________P ________________________________________________________________________________                  P ________________________________________________________________________________      % CONTEXT RECOGNITION IN VAX DATATRIEVE   @ Donna Brown and Sue Harris - Digital Equipment Corp., Nashua, NHP ________________________________________________________________________________       1  OVERVIEW   P This paper will describe context resolution within DATATRIEVE.  It explains the K impact context has on you as a DATATRIEVE user.  It covers how you specify  O context within DATATRIEVE as well as common pitfalls in the area of DATATRIEVE  H context.  It explores the internals of context resolution in DATATRIEVE.     2  WHAT IS CONTEXT?   M Context is described as the set of mechanisms by which DATATRIEVE recognizes  P field names and identifies target records for statements.  Changing the context N in which a DATATRIEVE statement executes can change the statement's outcome.  H This is why it is important for you to understand context's impact upon  DATATRIEVE statements.  L Context answers questions such as "which one" and "how many".  For example, J assume that the statement "MODIFY EMP_NUM" modifies employee numbers from N personnel records, such as those illustrated below.  We know that the EMP_NUM P field is changed, but which record is modified?  How many records are modified, N one or many?  These are the types of questions that DATATRIEVE resolves using  context.  1              ---------    ---------   ---------   6              | Harris|..  | Jones |.. | Brown |. . . .2              | 7544  |    | 7329  |   | 7542  |   /              |       |    |       |   |       | 2              ---------    ---------   ---------           DTR> MODIFY EMP_NUM       2.1  WHY IS CONTEXT IMPORTANT?  I The following sections describe the part context plays within DATATRIEVE.   
 2.1.1  Naming   P DATATRIEVE does not require that every identifier name used within a DATATRIEVE O session be unique.  The following example shows that two different records can  " contain fields with the same name:  @           DEFINE RECORD A USING           DEFINE RECORD B USING 2           01 TOP.                         01 TOP. E ---->            03 EMP_NUM  PIC XX.             03 EMP_NUM PIC 999.  J                  03 ADDRESS PIC X(30).;          03 SUPERVISOR PIC X(20).;  H Both records contain EMP_NUM fields.  To which field does the following  statement refer?      DTR> MODIFY EMP_NUM  N Because there are two fields named EMP_NUM, DATATRIEVE must take into account H factors other than the field name when deciding which field to modify.  P DATATRIEVE follows a set of conventions when deciding which field to act upon.  O These conventions are the rules of context resolution.  By understanding these  L rules, you will be better able to anticipate the behavior of the DATATRIEVE  statements you enter.    2.1.2  List Fields  R In the following FAMILY record, the field KIDS is defined with an OCCURS clause.  I Each FAMILY record thus contains a "LIST" of kids. This LIST can contain  K information pertaining to one kid up to ten kids, or the list may be empty.                   01 FAMILY. ;                 : 03 NUMBER_KIDS PIC 99 EDIT_STRING IS Z9.  I                   03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS.  "                      06 EACH_KID. B                         09 KID_NAME PIC X(10) QUERY_NAME IS KID. :  P The following diagram shows that for each FAMILY record there can be a variable M number of KIDS fields.  The first record contains 2 KIDS the second one kid,   etc.  <              ---------    ---------   ---------    -------- >              | Harris|..  | Jones |.. | Brown |..  | White|   <      . . . . | 02    |    | 01    |   | 03    |    | 02   | <              |  Bob  |    |  Betty|   |  Tom  |    |  Alex| <              |  Alice|    |       |   |  Dick |    |  Jen | <              |       |    |       |   |  Harry|    |      | ;              ---------    ---------   ---------    --------     P Context resolution becomes more complex when you use list records. Where a list I is involved, there are even more possible choices. Besides answering the  O question "which family" DATATRIEVE must also answer the question "which kid"?   I For example, the following PRINT statement refers to the list field KIDS.       DTR> PRINT ALL KIDS    P But, each record may have more than one KIDS field.  Which KIDS field should be O printed?  ALL occurrences of KIDS for a particular record?  ALL occurrences of  N all KIDS for all records?  We will look at these question in more detail in a  later section.  ' 2.1.3  Control Of DATATRIEVE Statements   O If you enter a statement or sequence of statements incorrectly, DATATRIEVE may  K not have enough information to determine which field a name in a statement  L refers to.  You can tell when this happens, because DATATRIEVE displays the  familiar message:   ;                 "<...> is undefined or used out of context"     P What happens if you do not correctly express the context of your statement, but L your statement can be interpreted in another context within your DATATRIEVE P session?  In this case, an error message will not be produced.  DATATRIEVE will N execute your statement, but in a different manner than you had intended.  The K results can be surprising and may even change data in ways that you do not  O expect. This is certainly not a desirable situation.  By understanding context  P resolution in DATATRIEVE and by specifying all context explicitly you can avoid  this type of accident.    ! 2.2  TYPES OF CONTEXT RECOGNITION   Q There are two levels of context recognition within DATATRIEVE. They are IMPLICIT  K context recognition and EXPLICIT context recognition.  Implicit means that  I context is implied by the environment in which a statement is executed.   K Explicit means that the context for a statement is entered as part of that  
 statement.              # 2.2.1  Implicit Context Recognition   M DATATRIEVE is sometimes said to be "context-sensitive".  This is because the  O meaning of a given DATATRIEVE statement varies depending on the environment in  P which it is executed.  This is an important aspect of the DATATRIEVE language.  H It gives power and flexibility not seen in third generation programming 
 languages.  *                                       NOTE  N       In this discussion, we are not referring to the mathematical linguistic R       concept of context-sensitive, as it applies to classification of grammars.  Q       We use this terminology (as well as "left context" and "right context") in _I       a more intuitive and informal way, as a method of highlighting and  ?       explaining a particular characteristic of VAX DATATRIEVE.n  O The following example shows how the environment set up by different DATATRIEVE nP commands causes the statement "PRINT XYZ" to produce different results.  In the J first example, a character string is printed.  In the second, a number is I printed.  And in the last example multiple fields of different types are b printed.  L         --------------------------    -------------------------------       E         | Context 1 (field):     |    |   Context 2 (variable):     |eE         | ====================== |    |=============================|oE         | DTR>READY DOMAIN1      |    | DTR>DECLARE XYZ PIC 9V9.    |_E         | DTR>SHOW FIELDS        |    | DTR>XYZ = 3.2               |_E         |       :                |    |                             | E         |                        |    |                             |_E         |  XYZ <Character string>|    |                             |eE         |                        |    |                             |uE         | DTR>FIND DOMAIN1       |    |                             |eE         | DTR>PRINT XYZ          |    | DTR>PRINT XYZ               |iE         |                        |    |                             | E         |      XYZ               |    |    XYZ                      | E         |                        |    |                             |_E         |  "ALF "                |    |    3.2                      |_E         |                        |    |                             |_E         --------------------------    -------------------------------N  0         ----------------------------------------0         |   Context 3 (domain):                |0         |======================================|0         | DTR>READY XYZ                        |0         | DTR>PRINT XYZ                        |0         |                                      |0         | Field1     Field2       Field3       |0         | 11       abc             .01         |0         | 22       def             .02         |0         | 33       ghi             .03         |3         |                                      |   s0         |      etc.                            |0         ----------------------------------------    P So you see, the output of "PRINT XYZ" can be greatly altered by the environment P in which it executes.  That environment is determined by the commands preceding O the statement "PRINT XYZ".  Implicit context recognition is at work in each of i these examples.h  Q The context-sensitive nature of DATATRIEVE has a number of implications.  One is fN that DATATRIEVE procedures are not compiled. The previous example illustrates Q why this is so.  Suppose "PRINT XYZ" were in a procedure.  What would it mean to nJ compile that procedure without knowing the datatype of XYZ?  Without even P knowing whether XYZ is the name of a domain, field or variable? The high degree Q of flexibility provided by DATATRIEVE limits the assumptions that can be made at 7 compilation time.   O Context sensitivity is also the reason that the distinction between "commands" -M and "statements" exists in DATATRIEVE.  Commands set up the context in which  Q statements execute.  Because of this, restrictions exist in the way commands can  L be used (see the VAX DATATRIEVE Reference Manual for a list of commands and O statements.) One restriction is that commands cannot be used within a compound hP statement.  In the following example, the REPEAT loop is a compound statement.  > The READY command within the REPEAT loop is therefore illegal:  (                   DTR> DECLARE XYZ LONG.                   DTR> REPEAT 5P                   CON>   BEGIN"                   CON>   PRINT XYZ<                   CON>   READY XYZ  ! this is NOT allowed!!!                   CON>   END  :                 "Expected statement, encountered "READY".     O If DATATRIEVE allowed commands within compound statements, the first iteration tQ of the above REPEAT loop would print the variable XYZ, and subsequent iterations  K would print the entire domain of XYZ.  Besides being confusing, this would o create technical difficulties.  M Enforcing a stable environment for a compound statement allows DATATRIEVE to  P make decisions about the type and size of the data being processed just once at P the start of processing of that compound statement.  If commands were permitted M inside of compound statements, then decisions about data type and size would TG have to be made during each iteration of a compound statement, thereby l increasing execution time.  J Context sensitivity also contributes a more "English-like" feeling to the Q DATATRIEVE language.  As in the English language, certain ambiguities can occur,  F but in DATATRIEVE these can be resolved through the context mechanism.  # 2.2.2  Explicit Context Recognitionl  M There may be times when you need to override implicit context recognition in oN DATATRIEVE in order to get the results you desire. You do this using explicit L context specification within your DATATRIEVE statements.  By using explicit P context specification as a general practice, you will be sure to always get the  data that you intend to.  L The example below shows a case where XYZ has two possible meanings. XYZ can K refer to either a variable or to a field within the domain DOMAIN1.  If no  = special direction is given, the variable XYZ will be printed.-              DTR> READY DOMAIN1o%            DTR> DECLARE XYZ  PIC 9V9.h            DTR> XYZ = 3.2e                  :            DTR> PRINT XYZs                   XYZa                   3.2n    N To print the field XYZ, DATATRIEVE must be instructed to obtain the value for Q XYZ from DOMAIN1.  This is done below using the clause "OF DOMAIN1".  This is an L( example of explicit context recognition.  $            DTR> PRINT XYZ OF DOMAIN1                    XYZ                  "ALF"    K Other methods of explicit context recognition will be discussed in a later l section.     3  Using DATATRIEVE Context   H Context recognition (both implicit and explicit) performs two different P functions within DATATRIEVE.  These functions are Target Record Identification, O which answers the question "how many", and Name Recognition, which answers the a question "which one".s    ! 3.1  Target Record Identificationi  Q Context determines which records will be the target of statements such as PRINT, hP MODIFY and ERASE.  That is, which records are printed, modified or erased.  How G does DATATRIEVE identify the target records for a particular operation?   P Target records for PRINT, MODIFY and ERASE statements are determined in part by N the form of the statement you enter.  The syntax of these statements provides Q three basic context specifications.  Specification of context in a statement can tL be implicit or explicit.  By implicit we mean that the target record is not N specified in the statement syntax, but is implied by the environment in which P the statement executes.  Explicit specification means that the target record is " specified in the statement syntax.  O The target of a PRINT, MODIFY or ERASE may be a single record, a collection of nK records, or a stream of records.  The syntax of a statement determines the aE number of records operated on.  That is, the syntax may imply either  1 single-record context or multiple-record context.   < These different options are shown in the following examples:  '     1.  IMPLICIT, SINGLE-RECORD CONTEXT   J         No context is specified; it is implicit.  Only one record will be           modified.  .                                   DTR> MODIFY   3     2.  PARTIALLY EXPLICIT, MULTIPLE-RECORD CONTEXTe  M         Context is expressed by the keyword "ALL" rather than by an explicit  P          RSE (record selection expression.) A group of records will be modified.  /                                  DTR> ERASE ALLt  )     3.  EXPLICIT, MULTIPLE-RECORD CONTEXTf  P         Context is detailed in the "OF RSE" clause.  A group of records will be           modified.  5                           DTR> MODIFY PRICE OF YACHTSh  , Each of these categories are detailed below.   3.1.1  Single-Record Context  G There are different ways to specify a single-record as the target of a EJ statement.  One is by means of a "selected record".  The SELECT statement M identifies one target record in a collection.  A record is selected by first bO forming a "collection" of records using the FIND statement and then choosing a bB particular record from that collection using the SELECT statement.  P In the example below, a collection of all of the YACHTS records is formed using Q a FIND statement.  The first record of the collection is then selected.  Since a  O target is not explicitly specified on the PRINT statement, the selected record   will be printed.  %                      DTR> FIND YACHTS_!                      DTR> SELECT |                      DTR> PRINT     O Another method of specifying single-record context is the FOR loop. A FOR loop  : identifies individual records of a record stream, in turn.  N It may seem that the FOR construct actually provides multiple-record context, K because it produces a stream of records. However, there is only one target >O record per iteration of a FOR loop.  The FOR construct allows you to work with  O many records at once, while dealing with each record individually.  Therefore, |N the single-record form of a statement is used within a FOR loop to operate on " the target record of the FOR loop.  R In the example below, all of the records from the YACHTS domain will be printed.  Q Notice that the single-record context form of the print statement is used within -
 the FOR loop.-  %                      DTR> FOR YACHTS -#                      CON>     PRINT     P What if two possible targets, one a selected record and one the target of a FOR 5 loop, are available at once?  Which one will be used?   K If more than one record qualifies as a target record, then DATATRIEVE will  Q always use the most recent context.  In the example below, the stream of records  O from the domain OWNERS will be printed, rather than the selected YACHTS record.   %                      DTR> FIND YACHTS                        DTR> SELECT%                      DTR> FOR OWNERS  #                      CON>     PRINT      3.1.2  Multiple-Record Context  O You can specify multiple record context in one of two ways.  One way is to use rP the keyword "ALL", without an RSE, on the command line.  When used in this way, Q ALL identifies all of the records in the current collection as the target of the  
 statement.  K In the example below, the FIND forms a collection containing the first two nQ records in the domain YACHTS.  The keyword ALL on the PRINT and ERASE statements pL specify both records in the current collection as targets.  After the ERASE J statement is executed, both of the records in the collection are erased.  9 Therefore, the second PRINT does not display any records.t            DTR> FIND FIRST 2 YACHTS         DTR> PRINT ALL    .                                         LENGTH-                                          OVER A          MANUFACTURER   MODEL     RIG    ALL   WEIGHT BEAM  PRICEw  A          ALBERG      37 MK II   KETCH   37    20,000  12  $36,951tA          ALBIN       79         SLOOP   26     4,200  10  $17,900e                DTR> ERASE ALL         DTR> PRINT ALL    Q You can also specify multiple record context using the "OF RSE" clause.  The "OF rM RSE" clause identifies a target record stream made up of records meeting the fP conditions set in the RSE.  In the example below, the "OF YACHTS" clause on the M MODIFY statement specifies that the record stream made up of all the records ZP from the YACHTS domain will be modified.  The result is that the PRICE field of ' every record in YACHTS is changed to 0.   -                   DTR> MODIFY PRICE OF YACHTS                     Enter PRICE: 0                   DTR>    N Contrast this with the single-record context produced by the FOR loop below.  O Each record is handled individually and you are prompted for a PRICE value for lP each record in the record stream. You should use extreme caution when utilizing L a multiple-record context technique (such as OF RSE) to avoid inadvertently K modifying all of the records in a domain at once when you actually want to s  modify the records individually.  .                   DTR> FOR YACHTS MODIFY PRICE(                   Enter PRICE: 33000    $                   Enter PRICE: 21000.                         etc. (for each record)       3.2  Name Recognition    Given a statement such as:             PRINT PRICEt    H DATATRIEVE must determine what is meant by PRICE.  Is PRICE a domain, a N variable, or a field?  If PRICE is a field, which domain is it from?  What if K more than one readied source has a PRICE field?  DATATRIEVE determines the lO answer to these questions through the process of name recognition.  DATATRIEVE r= uses two methods of name recognition:  implicit and explicit.n    3.2.1  Implicit Name Recognition  J DATATRIEVE keeps track of possible contexts using a stack.  A stack is an I internal data structure which is manipulated in such a way that the most oG recently added items are the first to be accessed (last on, first off.)o  Q DATATRIEVE uses the stack to resolve context.  When DATATRIEVE encounters a name YN in a DATATRIEVE statement, the stack is searched for that name.  If the stack K contains more than one entry for a particular name, the name from the most   recent context will be used.  Q In the example below, the FIND and SELECT statements make entries on the stack.   M When the PRINT statement is executed, DATATRIEVE looks for a context for the oP name TYPE.  Looking on the stack, the name TYPE is found to be a field from the  selected record.          DTR> READY YACHTS u&      DTR> FIND YACHTS WITH PRICE NE 0       DTR> SELECT FIRST n      DTR> PRINT TYPE    K In the example below, stack entries are again made as a result of FIND and eQ SELECT statements.  A stack entry for OWNERS is also made as a result of the FOR  R statement.  When the PRINT statement is executed, OWNERS is on top of the stack.  O The OWNERS record does not contain a PRICE field though.  So, DATATRIEVE looks tQ further down the stack until a reference to PRICE is found.  In this case, PRICE oQ is found in the selected YACHTS record.  That single PRICE field will be printed o) 18 times, once for each record in OWNERS.           DTR> FIND YACHTS       DTR> SELECT FIRST      DTR> FOR OWNERS      CON>     PRINT PRICEm    N What is the ordering on the stack?  What is meant by most recent or "closest" M context?  The answer to these questions is generally intuitive.  The diagram eI below outlines the arrangement of the stack.  The diagram shows that the sP environment set up by the statement currently being executed will be considered < before a selected record, a collection, or global variables.  A       TOP    ----------------------------------------------------sA              |                                                  |xA              |   Context blocks created by the statement:       |pA              |    ("innermost" blocks at top of stack)          |rA              |                                                  |eA              | RECORD STREAMS | LOCAL     | VERIFY  | VALID IF  |oA              |                | VARIABLES | (STORE) |           |gA              |                |           |         |           |pA              ----------------------------------------------------GA              |   CURRENT collection (if a SELECTed record)      |iA              ---------------------------------------------------- A              |   Named collections with SELECTed records        |PA              |   (in same order as SHOW COLLECTIONS display)    |AA              ----------------------------------------------------pA              |   Global variables                               | A              ----------------------------------------------------       BOTTOM     Q This diagram shows that context from the innermost statement is placed on top of  L the stack.  Innermost refers to the statement which is the most nested of a O group of statements.  In the example below, the innermost statements are those rQ within the compound statement under the FOR OWNERS statement.  The stack diagram sM shows that the context from the outer FOR YACHTS loop is placed on the stack  P followed by the context set up by the FOR OWNERS statement. The variable INNER1 G declared in the innermost statement is placed on top of the stack last.r                DTR> FOR YACHTS                       BEGINe.                       DECLARE OUTER1 PIC X(5).                        FOR OWNERS                           BEGINe3                           DECLARE INNER1 PIC 999V9.o&             ----------->  INNER1 = 2.2                           ENDi                       END     O This is what the context stack looks like at the time of the assignment of 2.2  
 to INNER1:                A       TOP    ---------------------------------------------------- A              |                                                  |mA              |            INNER1 context                        |nA              |        OWNERS context                            |oA              |        OUTER1 context                            |tA              |    YACHTS context                                | A              ----------------------------------------------------mA              |   CURRENT collection (if a SELECTed record)      |tA              ----------------------------------------------------sA              |   Named collections with SELECTed records        |rA              |   (in same order as SHOW COLLECTIONS display)    | A              ---------------------------------------------------- A              |   Global variables                               |dA              ----------------------------------------------------        BOTTOM    P DATATRIEVE actually uses two stacks to keep track of context.  The first stack, M the general context stack, keeps track of possible name resolutions for most rK DATATRIEVE statements.  The second stack, the update stack, keeps track of CQ fields which are possible targets for updates or assignments.  DATATRIEVE checks EP the update stack to ensure that you assign only to those fields that can accept M updates, that is, a field which is part of a record which is being stored or   modified, or a variable.  M The table below shows that a field will be placed on the update stack if the dP field is named in a STORE or MODIFY statement or is part of a record named in a J STORE or MODIFY statement, or if the field is a declared variable.  Local P variables and the targets of STOREs and MODIFYs remain on the update stack only < for the duration of the statements of which they are a part.  7                     CONTEXTS PLACED ON THE UPDATE STACKn    ?              CONTEXT TYPE         CONTEXT                 SCOPEhH          ---------------------------------------------------------------H          | STORE USING     |  TARGET OF STORE       |  STORE USING     |H          ---------------------------------------------------------------            UH          | MODIFY USING    |  TARGET OF MODIFY      |  MODIFY USING    |H          ---------------------------------------------------------------  H          | LOCAL VARIABLE  |  VARIABLE              |  BEGIN-END BLOCK |H          ---------------------------------------------------------------  H          | GLOBAL VARIABLE |  VARIABLE              |  ANY STATEMENT   |H          ---------------------------------------------------------------    Q The table above shows that a source referenced in a STORE statement is placed on dP the update stack.  The context for the source being stored is not placed on the P general context stack, however.  In the statement below for example, OLD_YACHTS Q is placed only on the update context stack.  NEW_YACHTS is placed on the general  P context stack.  So, even though both the source and destination records contain H BOAT fields, DATATRIEVE will be able to determine the correct domain by # referring to the appropriate stack.r                 DTR> FOR OLD-YACHTS8                       STORE NEW-YACHTS USING BOAT = BOAT    Q You may sometimes see the general context stack referred to as the Right context sI stack and the update context stack referred to as the Left context stack.d  P The ordering rules for the update stack are basically the same as those for the L general stack.  The difference is that fewer entries are made on the update H stack.  As shown below, only variable declarations and STORE and MODIFY , statements make entries on the update stack.    6                   ORDERING OF THE UPDATE CONTEXT STACK  A       TOP    ----------------------------------------------------tA              |                                                  |DA              |   Context blocks created by the statement:       |rA              |    (innermost blocks at top of stack)            |rA              |                                                  |iA              |     STORE   |   MODIFY    | LOCAL VARIABLES      | A              |             |             |                      |hA              ----------------------------------------------------cA              |   Global variables                               |eA              ----------------------------------------------------t      BOTTOMa    O The example below shows the ordering of both context stacks.  The state of the iR stacks at the time the of the STORE statement (indicated by the arrow) is shown.  J YACHTS is pushed onto both stacks when the FOR YACHTS MODIFY statement is M executed, and will remain on both stacks until the FOR loop ends.  OWNERS is TO pushed onto the the update stack each time the STORE statement is executed and tL is popped off when the store is completed.  The local variable NEW_MODEL is G placed on both stacks at the time it is declared and remains until the l termination of the FOR loop.  *               DTR> FOR YACHTS MODIFY USING                      BEGIN&                      PRICE = PRICE * 21                      DECLARE NEW_MODEL PIC X(10).W.                      NEW_MODEL = *."new model"(                      STORE OWNERS USING *          --------------> MODEL = NEW_MODEL                      END      1                  STACK CONTENTS AT TIME OF ASSIGNe  >            Left Context stack              Right Context Stack@          (Update Context stack)          (General Context Stack)  I      -------------------------      ------------------------------------- I      | OWNERS context        |      | NEW_MODEL context                 |oI      -------------------------      -------------------------------------eI      | NEW_MODEL context     |      | YACHTS  context                   | I      -------------------------      -------------------------------------lI      | YACHTS context        |      | Collections (with SELECTed record)|eI      -------------------------      ------------------------------------- I      | Global variables      |      | Global variables                  | I      -------------------------      -------------------------------------              3.2.2  Explicit Name Recognition  Q The previous section discussed how name recognition takes place automatically in |Q DATATRIEVE.  Now we will discuss how you can override DATATRIEVE's implicit name  N recognition by specifying the name explicitly.  There are two ways of forcing O name recognition. One is by using name qualification and the other is by using - context variables.   3.2.2.1  NAME QUALIFICATION   E Name qualification allows you to override the context established by -K DATATRIEVE's implicit name recognition.  This is done by providing a fully sM qualified name in a DATATRIEVE statement.  A fully qualified name includes a  M specification for the readied source (the domain name or database name), all  Q group fields of which the field is a part, and the field name itself.  A portion -L of the record definition for the record YACHT is shown below.  If a readied P domain called YACHTS references the record YACHT, then the fully qualified name 5 for the field MODEL is: YACHTS.YACHT.BOAT.TYPE.MODEL.   !                     RECORD YACHT p                     01  BOAT.n                         03  TYPE.9                           05  MANUFACTURER      PIC X(10)r1                               QUERY_NAME BUILDER.H2                           05  MODEL     PIC X(10).)                        03  SPECIFICATIONSh!                                 : !                                 :p    E You should use name qualification when DATATRIEVE's default implicit  Q qualification is not what you want.  For example, suppose that you want to print WP a list of yachts and for each yacht list all of the owners who own that type of % yacht.  You might try the following: N  B      DTR> FOR YACHTS FOR OWNERS WITH TYPE EQ TYPE PRINT TYPE, NAME    Q This will not produce the desired results, however.  The problem lies in the RSE  K "TYPE EQ TYPE".  The intent is to find owners with TYPE equal to TYPE from -L YACHTS.  But, since OWNERS is higher on the context stack than YACHTS, both Q references to TYPE in the RSE will resolve to OWNERS.  You must force DATATRIEVE  O to resolve one of the TYPEs to YACHTS.  You can do this by qualifying TYPE, as  O in the following example.  Note that TYPE does not have to be fully qualified,  $ just enough to determine uniqueness.  !                   DTR> FOR YACHTS-<                          FOR OWNERS WITH TYPE EQ YACHTS.TYPE1                                  PRINT TYPE, NAME-       3.2.2.2  Context Variables  P Name qualification can be used to differentiate between fields of the same name K from different domains.  But what if the duplicate names are from the same  M domain?  For example, suppose you want to print a list of builders who build  N boats of more than one kind of rig.  This requires comparing the RIG field of P one YACHTS record to the RIG field of another YACHTS record.  You might try the 
 following:                   DTR> FOR YACHTS J                 CON>     FOR YACHTS WITH BUILDER EQ BUILDER AND RIG NE RIG6                 CON>           PRINT BUILDER, RIG, RIG                 DTR>    N The problem again is that context resolves to the inner FOR loop. So, BUILDER Q will be compared to BUILDER from the same record and RIG will be compared to RIG pN from the same record.  Using the domain name will not help, because YACHTS is M the domain name in both cases.  So, how can you distinguish BUILDERS and RIG?e  Q You can use context variables to distinguish names from the same domain.  In the aQ following example, the context variable A is supplied for the outer FOR loop and dQ B for the inner FOR loop.  The context variables are then used within the RSE to p qualify BUILDER and RIG.  $                 DTR> FOR A IN YACHTSF                 CON>   FOR B IN YACHTS WITH B.BUILDER EQ A.BUILDER AND)                 CON>       B.RIG NE A.RIGT:                 CON>           PRINT BUILDER, A.RIG, B.RIG    Q A context variable is an artificial or "dummy" variable.  A context variable can  I be specified as part of an RSE and is valid only for the duration of the -O statement containing the RSE.  Use of a context variable is a form of EXPLICIT O context specification.  P Context variables can be useful in other situations also.  Earlier we mentioned L that the target of a STORE or MODIFY operation is placed only on the update L context stack, not the general context stack.  As a result, fields from the I record that is being updated cannot be used on the right hand side of an  T assignment.  For example, suppose you want to use previously entered values more    N than once, as in the example below.  The statement "FIELD3 = FIELD1 + FIELD2" M will cause DATATRIEVE to complain that FIELD1 is undefined.  This is because o) FIELD1 is found only on the update stack.o  *                    DTR> STORE DOMANE USING                     CON>    BEGIN5                    CON>    FIELD1 =  *."Field1 value"n5                    CON>    FIELD2 =  *."Field2 value" 3                    CON>    FIELD3 = FIELD1 + FIELD2h                    CON>    END@                    "FIELD1" is undefined or used out of context.    Q If you happen to have another selected record which contains fields named FIELD1 eQ and FIELD2, then FIELD3 will take its value from the FIELD1 and FIELD2 values of tM the selected record rather than the record being stored, producing different d results than you expected.  Q You can get around these problems by using a context variable.  In the following  N example, using the context variable Y has the effect of establishing an entry Q for DOMANE on the general context stack. This allows the values just entered for IF FIELD1 and FIELD2 to be used as the source of an assignment statement.  "      DTR> STORE Y IN DOMANE USING       CON>    BEGIN  (      CON>    FIELD1 =  *."Field1 value" (      CON>    FIELD2 =  *."Field2 value" *      CON>    FIELD3 = Y.FIELD1 + Y.FIELD2       CON>    END    L Context variables can also be used to avoid an exhaustive search on certain K CROSS lookups.  In the example below, BUILDER is a key for both OWNERS and  P YACHTS.  If no context variable is used, a keyed lookup will be done on BUILDER N from OWNERS.  The same is true if the context variable for the second source, P OWNERS (Z), is used in the RSE.  If the context variable for the second source, I YACHTS (Y), is used, then a keyed lookup will be done on both OWNERS and hP BUILDERS.  The moral of this example is:  when in doubt, use a context variable!  ?       DTR> FIND Y IN YACHTS CROSS Z IN OWNERS OVER BUILDER WITH               BUILDER = "ALBIN">       Performing EQL boolean on RMS key field Z.OWNERS.BUILDER?       DTR> FIND Y IN YACHTS CROSS Z IN OWNERS OVER BUILDER WITH                Z.BUILDER = "ALBIN">       Performing EQL boolean on RMS key field Z.OWNERS.BUILDER    ?       DTR> FIND Y IN YACHTS CROSS Z IN OWNERS OVER BUILDER WITHt               Y.BUILDER = "ALBIN"C       Performing EQL boolean on RMS key field Y.YACHTS.MANUFACTURERR>       Performing EQL boolean on RMS key field Z.OWNERS.BUILDER        $ 3.3  CONTEXT AND HIERARCHICAL FIELDS  P Hierarchical fields or lists are defined with an OCCURS clause in a record or a N view.  As mentioned earlier, context resolution becomes more complex when you L use list records.  Besides identifying a target record, you must identify a  particular list occurrence.t  N Unless otherwise stated, throughout the rest of this section "LIST" means any 5 hierarchical field, including those defined in views.-   3.3.1  General Techniques-  O You can think of a list as a "pseudo-domain" within a domain and list items as  H records within that pseudo-domain.  In the diagram below, the outer box O represents the FAMILIES domain, and the inner box represents the pseudo-domain  3 formed by the KIDS list within the FAMILIES domain.-  G         ---------------------------------------------------------------iG         | 01 FAMILY.                                                  |-G         |       :                                                     |bG         |    03 NUMBER_KIDS PIC 99.                                   |-G         |  --------------------------------------------------------|  |gG         |  | 03 KIDS OCCURS 0 TO 10 TIMES . . .                    |  | G         |  |    06 EACH_KID.                                       |  | M         |  |       09 KID_NAME PIC X(10).                          |  | . . .hG         |  |       09 AGE PIC 99.                                  |  |iG         |  |                                                       |  | G         |  ---------------------------------------------------------  |sG         ---------------------------------------------------------------p    K You must supply context for the pseudo-domain as well as the actual domain.n  F Some of the techniques to aid in target record identification include:  0     oo Use successive FIND and SELECT statements        oo Use nested FOR statements  6     oo Use the CROSS clause to "flatten" the hierarchy  ,     oo Use an inner print list specification  (     oo Use OF RSE clauses where possible  ,     oo Use the Context Searcher (SET SEARCH)  F Note that several of these techniques are also used for target record M identification.  This is because the techniques that are used on domains can  " also be applied to pseudo-domains.   3.3.1.1  Using FIND/SELECT  I One method of getting at records that are in the pseudo-domain is to use  & successive FIND and SELECT statements.  N First, lets look at an example of how you might naturally phrase a query on a O list field.  First you find and select a record from FAMILIES and then you try lQ to print out the fields KID_NAME and AGE. The example below shows that the PRINT i2 statement will fail because KID_NAME is undefined.  *                  DTR> FIND FAMILIES;SELECT-                  DTR> PRINT ALL KID_NAME, AGEO?                  "KID_NAME" is undefined or used out of contextc    Q Extra context must be provided to specify which item from the KIDS list is to be tN printed.  Use an extra FIND to form a collection of "pseudo-records" from the  KIDS pseudo-domain.t    +                  DTR> FIND FAMILIES; SELECTi                  DTR> FIND KIDS -                  DTR> PRINT ALL KID_NAME, AGE                        KIDa!                   NAME        AGE         l                  URSULA         7                  RALPH          3     3.3.1.2  Nested FORs  O The following is an example of an unsuccessful attempt to print items from the OM KIDS list using a FOR loop.  The statement fails because it does not specify M& which occurrence of the list to print.  "                  DTR> FOR FAMILIES,                  CON>    PRINT KID_NAME, AGE@                  "KID_NAME" is undefined or used out of context.    N In much the same way that you can access a pseudo-domain using an extra FIND, L you can access the pseudo-domain using an extra FOR loop.  In the following L example the inner FOR loop provides a record stream from the pseudo-domain, N providing context for KID_NAME and AGE.  A list of kid names and ages will be  printed.  "                  DTR> FOR FAMILIES"                  CON>     FOR KIDS1                  CON>         PRINT KID_NAME, AGE        3.3.1.3  Using CROSS  N The following is another example of a statement that does not provide context  for the KIDS list.  >           DTR> PRINT MOTHER, KID_NAME, AGE OF FIRST 1 FAMILIES9           "KID_NAME" is undefined or used out of context.n    Q The solution shown below is to use a CROSS clause to flatten the hierarchy.  The tN CROSS provides a stream of records that contain fields from both the FAMILIES D domain and the pseudo-domain providing context for KID_NAME and AGE.  D      DTR> PRINT MOTHER, KID_NAME, AGE OF FIRST 1 FAMILIES CROSS KIDS  +                    MOTHER     NAME      AGE   9                  ANN        URSULA       7               I        3.3.1.4  Inner Print Lists  H When accessing list fields through a PRINT statement, another option is R available to you.  That option is the use of the inner print list specification.  & The syntax of the inner print list is:  3                             {ALL print-list OF RSE}d  E The print statement below does not provide context for the KIDS list.e  >           DTR> PRINT MOTHER, KID_NAME, AGE OF FIRST 1 FAMILIES9           "KID_NAME" is undefined or used out of context.t    L The inner print list construct provides a way to specify context for a list I field.  Think of an inner print list as a print statement within a print  P statement which is used to access a pseudo-domain.  The example below shows the . inner print list portion of a print statement.  5                     ---------------------------------e5                     |    print-list                 |25                     |      -------------------------|d5                     |      | Inner print list      || 5                     |      |  -------------        ||U5                     |      |  | print-list|        || 5                     |      |  |           |        || H        DTR> PRINT MOTHER, ALL KID_NAME, AGE OF KIDS  OF FIRST 1 FAMILIES                          KID"             MOTHER     NAME    AGE  !          ANN          URSULA    7t!                       RALPH     3h    N This method is most useful when you want to print all of the occurrences of a Q list.  Note the difference in results from the previous CROSS example where only r the first KID was retrieved.  P When using inner print lists keep in mind that if the print list starts with an 7 inner print list, you need an additional "ALL" keyword:g  6                           ALL  {ALL print-list OF RSE}  N The following print statement is the same as the one in the previous example, ? but without the MOTHER print item.  It produces a syntax error.o  B           DTR> PRINT ALL KID_NAME, AGE OF KIDS OF FIRST 1 FAMILIES6           Expected end of statement, encountered "OF".    L The print statement below contains an additional ALL to properly denote the " beginning of the inner print list.    0                        -------------------------0                        | Inner print list      |0                        |  -------------        |0                        |  | print-list|        |0                        |  |           |        |E        DTR> PRINT ALL  ALL KID_NAME, AGE OF KIDS  OF FIRST 1 FAMILIES(               KIDR            NAME    AGE             URSULA    7e           RALPH     3,    O It is possible to define a list field within another list field. This is known eN as a nested list.  The definition below shows the list PET defined within the 
 list KIDS.  F         ______________________________________________________________G        |  01 FAMILY.                                                  |CG        |     03 PARENTS.                                              |"G        |        06 FATHER PIC X(10).                                  | G        |        06 MOTHER PIC X(10).                                  | G        |     03 NUMBER_KIDS PIC 99.                                   |HG        |    --------------------------------------------------------- |BG        |    |03 KIDS OCCURS 0 TO 10 TIMES DEPENDING ON NUMBER_KIDS. | |dG        |    |   06 EACH_KID.                                        | | M        |    |      09 KID_NAME PIC X(10).                           | | . . .rG        |    |      09 KID_AGE PIC 99.                               | |cG        |    |     -----------------------------------------------   | | G        |    |     |09 PET OCCURS 2 TIMES.                       |   | |eG        |    |     |   13  PET_NAME  PIC X(10).                  |   | |aG        |    |     |   13  PET_AGE   PIC 99.                     |   | | G        |    |     -----------------------------------------------   | |LG        |    --------------------------------------------------------| |hG        ________________________________________________________________-                                  -  L Such a record requires yet another level of context resolution. The example K below shows that an additional inner print list can be used to resolve the  % context for the list within the list.   ?                  -----------------------------------------------?                  |    print-list for selected record          | ?                  |      -------------------------------------||E?                  |      | inner-list for KIDS                |||?                  |      |            --------------------    ||h?                  |      |            |inner-list for PET|    || ?                  |      |            |                  |    || E    DTR> PRINT FATHER, ALL KID_NAME, ALL PET_NAME OF PET OF KIDS      -    E                  KID        PET                                      -E      FATHER      NAME       NAME                                     w   E      JIM        GARY       POP                                       dE                            SODA                                      mE                 SUE        MOUSE                                      E                            SHORTY                                    i     3.3.1.5  OF RSE Clausese  M There are cases when you want to find a record with a list item of a certain eC value, but you do not care which occurrence of the list meets your iN qualifications.  In other words, you want to find the records in which any of O the list items satisfy an RSE.  If you wanted to find all FAMILIES with one or rP more children over five years old, you might use the following FIND statement.  M The statement will fail, because even though you do not care which KIDS item eQ meets your qualifications, DATATRIEVE needs to know how to resolve the reference u to AGE.o  /                DTR> FIND FAMILIES WITH AGE GE 5 9                "AGE" is undefined or used out of context.I    P You cannot use inner print lists on anything but a PRINT statement, so what can P you do?  You can use successive FIND/SELECT statements, but another possibility  is to use an ANY boolean.t  P Since the ANY boolean includes an "OF RSE" clause, it allows you to get through J that extra pseudo-domain of KIDS as shown in the following FIND statement.  <                                           Boolean expression=                                        ---------------------- =                                        |  "inner"  RSE      | <                                        |  ------------------=                                        |  |                 | =                DTR> FIND FAMILIES WITH ANY KIDS WITH AGE GE 5 !                [10 records found]      3.3.2  Report Writer Techniquese  Q Referencing list fields in the Report Writer is more of a challenge because only RK a few of the techniques discussed in the previous section can be used from  N within the report writer.  To access lists from within the report writer, you  can use:  (     oo An inner print list specification  (     oo The Context Searcher (SET SEARCH)  %     oo CROSS to flatten the hierarchy   P The example below shows the inner print list technique being used inside of the / report writer.  A couple of points to note are:d  O     oo The inner print list is made up of KID_NAME and AGE as well as a column N         specification.  F     oo Use of the TOTAL function on the field AGE requires the OF RSE O         specification, but TOTAL of NUMBER_KIDS does not.  This is because AGE o5         is a list field and needs additional context.M               DTR> REPORT FAMILIESD              RW>  PRINT COL 1, MOTHER, COL 20, ALL KID_NAME, COL 40,              RW>  AGE OF KIDSaP              RW>  AT BOTTOM OF MOTHER PRINT TOTAL NUMBER_KIDS, TOTAL AGE OF KIDS              RW>  END_REPORT         3.4  The CONTEXT SEARCHERp  P Another method of providing the extra context needed for list fields is the use P of the CONTEXT SEARCHER.  In addition, the CONTEXT SEARCHER can provide context  for access through DBMS sets.   L The CONTEXT SEARCHER is activated by the SET SEARCH command.  The following O example shows the CONTEXT SEARCHER being used to automatically create an inner pQ print list for KIDS.  The print statement below is the same one that failed in a rL previous example. Note that DATATRIEVE displays an informative message when , context is resolved by the CONTEXT SEARCHER.             DTR> SET SEARCH ?           DTR> PRINT  MOTHER, KID_NAME, AGE OF FIRST 1 FAMILIES L           Not enough context. Some field names resolved by Context Searcher.                                            KIDs%                MOTHER     NAME    AGEt  $             ANN          URSULA    7$                          RALPH     3    O The CONTEXT SEARCHER also allows you to search DBMS records without specifying m set relationships explicitly.-  1 Consider the following DBMS record/set structure:   +                          ------------------ +                          | DIVISIONS      | +                          ------------------ )                            |           /\-)                            |            | ,                        CONSISTS_OF   MANAGES)                            |            | )                            \/           |K+                          ------------------ +                          | EMPLOYEE       | +                          ------------------     I The following example prints the division name associated with the first nP employee.  An EMPLOYEE record is selected and then the print statement accesses ; the associated DIVISION record through the CONSISTS_OF set..  *                 DTR> FIND FIRST 1 EMPLOYEE                  [1 record found]                 DTR> SELECTeD                 DTR> PRINT DIV_NAME OF DIVISION OWNER OF CONSISTS_OF      -$                 Division Name-------  !                 ENG BUILD ~& TEST     N In the following example the CONTEXT SEARCHER is used, so set access does not M need to be specified in the print statement.  Note that in this example, the  Q Context Searcher traverses the MANAGES set instead of the CONSISTS_OF set.  This iT is because the Context Searcher may use any of the paths available through a set    M structure.  You should exercise caution when using the CONTEXT SEARCHER with r1 DBMS because it may not choose the expected path.-  *            DTR> SET SEARCH                %            DTR> FIND FIRST 1 EMPLOYEE %            [1 record found]          D%            DTR> SELECT               S%            DTR> PRINT DIV_NAME       IN            Not enough context.  Some field names resolved by Context Searcher.              Division Name-------i              ENG STOCKROOM       4  COMMON MISTAKES AND PITFALLST  K When you see the following message, it means that DATATRIEVE does not have  ) enough context to do what you want it to._  >                   " <...> is undefined or used out of context"  M There are a number of possible causes for context problems.  Here is a check   list to consider:"       oo Check for misspellings(  ?     oo Check for duplicate names, especially from other sources   O     oo Does a referenced collection have a SELECTed record?  Check the CURRENT  %         as well as named collections.   K     oo Is a list involved (either from OCCURS or views)? Especially in the |O         Report Writer, you may need to use a CROSS to flatten lists, use inner  ,         print lists or the CONTEXT SEARCHER.  I     oo Does a STORE operation need to use a context variable in order to  %         reference just-stored values?_  ?     oo For DBMS sources, does a set name need to be referenced?-  N     oo Is there a FIND inside a compound statement?  This can sometimes cause K         unexpected results rather than an error message.  In the following AD         example, a YACHTS record will be printed even though a FIND ?         OWNERS/SELECT was done just before the PRINT statement.-  O                           READY YACHTS, OWNERS                                 -O                           FIND ALL YACHTS                                      _O                           BEGIN                                                rB                             FIND OWNERS ! Not supported           O                             SELECT      ! Not supported                        oO                             PRINT                                              -O                           END                                                                          5                     Note: A YACHTS record is printed!     O     oo Some query-names from records defined with RDO and CDDL are not handled  J         correctly by DATATRIEVE.  Those are CDDL records with query names N         containing a hyphen and RDO records containing a hyphen or lower-case P         letters. DATATRIEVE does not convert the hyphens and lower case letters Q         as it should, resulting in an undefined field name. This problem will be  C         corrected in a version of DATATRIEVE following version 4.1.   2        The example below illustrates this problem.                 CDDL:   #                  define record qph.                    tmpr structure.I                  date1 datatype is date query_name for dtr is "quad-one". $                  end tmpr structure.                   end qph record.                 DTR> show fields               QPHD                 TMPR'                 DATE1 (quad-one) <DATE>u               DTR> find qphd%               DTR> print all quad-ones=               "QUAD_ONE" is undefined or used out of context.     P     oo Check that all variables referenced in a procedure are declared.  Do not P         assume that a variable referenced in code which is branched around with O         a CHOICE or IF-THEN-ELSE statement does not need to be declared.  Even tP         if that code is never executed, it still must be compiled.  For example:               DTR> X = 0*             DTR> IF X = 1 THEN PRINT x + z4             "Z" is undefined or used out of context.    K     oo Context errors do not always result in an error message! Forgetting  L         about implicit context can also cause unexpected data results.  You J         would expect the example below to produce a context error message P         because context is not provided for KIDS.  But, it turns out that there Q         is a selected record with URSULA targeted as the KID.  Remember that the aN         general context stack also includes collections with selected records!              DTR> SET NO SEARCH 0            DTR> FOR FAMILIES PRINT KID_NAME, AGE              KID              NAME       AGE               URSULA        7            URSULA        7            URSULA        7            : (etc.)H    J     oo A CROSS of two collections from the same domain may give incorrect M         answers.  To avoid this problem ready the domain twice, once with an aL         alias and once without, and proceed as if you were dealing with two '         separate domains.  For example:     '            DTR> READY DOM, DOM AS EXTRAo(            DTR> FIND COLLECTION-A IN DOM*            DTR> FIND COLLECTION-B IN EXTRA,            DTR> FIND A IN COLLECTION-A CROSS#                   B IN COLLECTION-B           
 5  Summary  M The outcome of a DATATRIEVE statement is affected by the context in which it eN executes.  This makes DATATRIEVE a more powerful tool for you, because you do G not have to supply every detail of execution on a DATATRIEVE statement.   M Context resolution in DATATRIEVE can sometimes be confusing.  If you keep in oO mind how DATATRIEVE handles context, as described in this paper, you can avoid e( confusion and make context work for you.              O _______________________________________________________________________________D       The Story of 'P'  4 Mr. R, Oldest Seagoing Service, Washington, DC 20593O _______________________________________________________________________________   O I would like to call this article, "The Story of 'O'" but the old time sailors NL where I work tell me that letter has been taken. So I am going to call this K "The Story of 'P'".  I am a system manager/programmer/comic relief for the CM oldest sea-going service in the United States.  My boss has a secretary that tM works for him as well as handling overflow tasks for other division chiefs.  sH I'll call that secretary "P." in order to protect the innocent (and the O guilty).  There was a problem in the office that we could never find "P." when .K we needed her.  She would appear to play her boss against the other people FO that gave her work to do.  She would also take in-ordinate amounts of times to nM perform simple tasks.  After much coun-selling with no long term improvement  M my boss said something had to be done.  That's where I come in.  I looked at  L what information my boss needed and saw three items, the time 'P.' left her N desk, where 'P.' went, and when 'P.' returned to her desk.  The record defini-% tion I came up with looked like this:     #    DEFINE RECORD LOCATION_REC USING-    01  LOCATION_RECORD.         03 TIME_OUT USAGE DATE            EDIT_STRING IS X(20).-        03 TIME_IN  USAGE DATE|           EDIT_STRING IS X(20).         03 DESTIN   PIC X(70).     ;  < I then went ahead and defined the domain LOCATION like this:  :    DEFINE DOMAIN LOCATION USING CDD$TOP.APA.P.LOCATION_REC$        ON USER1:[APA.P]LOCATION.DAT;     7 Next I defined a file using something like the command:   ,    DEFINE FILE FOR LOCATION KEY = TIME-OUT ;  M Now I wanted to come up with two very simple procedures for 'P.' to use, one LL to say when she was leaving and one to use when she was back.  I wanted the M procedures to be "foolproof" as possible so I needed to make sure "P." could SN not be out to someplace without having returned from her last "adventure" and G that the time was recorded automatically.  Here is what I came up with:-   DEFINE PROCEDURE LEAVE N READY LOCATION SHARED WRITE 2 IF COUNT OF LOCATION WITH TIME_IN  = "" GT 0 THEN    BEGIN       PRINT " " sA      PRINT "   You must first log in from your last adventure !" .$      PRINT "   Please type:  BACK "       PRINT " " a   END ELSE N   BEGIN       STORE LOCATION USING       BEGIN s         TIME_OUT = "NOW" e&         DESTIN = *."your destination" 	      END      END t
 END_PROCEDUREd  M Now for when 'P.' returned, I needed to make sure she had first recorded her  N leaving and that time was recorded automatically. Here is what I came up with:   DEFINE PROCEDURE BACK * DECLARE TIC USAGE DATE EDIT_STRING X(20).  TIC = "now"  READY LOCATION SHARED 8 MODIFY IF COUNT OF LOCATION WITH TIME_IN = "" EQ 0 THEN  BEGIN    PRINT " " 3   PRINT "  You must first leave on an adventure !"  !   PRINT "  Please type:  LEAVE "     PRINT " " 	 END ELSE   BEGIN *   MODIFY LOCATION WITH TIME_IN = "" USING K   TIME_IN = "NOW" PRINT " Logged in.  Time is " | (FORMAT(TIC) USING X(20))t END 
 END_PROCEDURE   N Now my boss needed some way to to tell where 'P.' was.  The hard part of this L was deciding what to call it.  Since I think my boss had spent some time in P Matamoras, Mexico, we decided to call it "DONDE" which is Spanish for "Where".   Here's what I came up with:e   DEFINE PROCEDURE DONDE SET DICTIONARY CDD$TOP.APA.P READY LOCATION SHAREDR0 IF COUNT OF LOCATION WITH TIME_IN = "" EQ 0 THEN BEGINI! PRINT " Not logged out anywhere "R END ELSE BEGINc FOR LOCATION WITH TIME_IN = ""&     PRINT TIME_OUT(-), SKIP, DESTIN(-) END 
 END_PROCEDUREr  K I then set up symbols in LOGIN.COM for 'P.' and my boss.  They looked like:o  e1         BACK :== "''DTR32' ; :CDD$TOP.APA.P.BACK" 2         LEAVE:== "''DTR32' ; :CDD$TOP.APA.P.LEAVE"2         DONDE:== "''DTR32' ; :CDD$TOP.APA.P.DONDE"  o2 Datatrieve was defined as a symbol elsewhere like:   '         DTR*32 :== $SYS$SYSTEM:DTR32411l  K This went pretty good for the first day but then my boss said he wanted to  O know how long each trip lasted.  I told him, "I got five records out there and eG you are not going to destroy all my work by creating a new data file." E  0 He replied, "How are you going to do it then ?"   I I said, "Well, you could use that old favorite of Cobol programmers, Mr.  K REDEFINES.  You and I both know that a Datatrieve date field uses the same  N amount of space as a quad field.  So you take the date, convert it to a quad, I subtract the two dates as quads, and convert the resulting value back to  M minutes." "A value of '1' in a quad field is also known as a clunk.  But how  L many clunks are there in a minute ?" "That's trivia and I don't know know.  O But I do know that 17-NOV-1858 at 00:00:00.0 is equal to '0' clunks since time  L for all Datatrievers starts at that date.  I would suspect that if you take O the date 18-NOV 1858 at 00:00:00.0 you could put that in a variable with usage  L quad and see what it is in clunks and then divide by twenty-four to get the K number of hours and again by sixty to get the number of minutes." "And you  8 tell me that 17-NOV-1858 at 00:00:00.0 is not trivia ?"   0 So what I guess he did was something like this:       DTR> declare TIC usage date.n$         DTR> declare TIC usage date.$         DTR> declare TOC usage quad.,         DTR> TIC = "18-NOV-1858 00:00:00.00"         DTR> TOC = TIC         DTR> TOC = TOC / 24          DTR> TOC = TOC / 60_         DTR> print TOC(-)                     600000000u  r         DTR>   ! Because what I ended up with was:   >*         REDEFINE RECORD LOCATION_REC USING         01  LOCATION_RECORD.*                 03 TIME_OUT     USAGE DATE(                    EDIT_STRING IS X(20).3                 03 TIME_OUT_RED REDEFINES TIME_OUT. 2                   05  TIME_OUT_QUAD USAGE IS QUAD.*                 03 TIME_IN      USAGE DATE(                    EDIT_STRING IS X(20).1                 03 TIME_IN_RED REDEFINES TIME_IN. 1                   05  TIME_IN_QUAD USAGE IS QUAD.d*                 03 DESTIN       PIC X(70).G                 03 TOT_TIME COMPUTED BY (TIME_IN_QUAD - TIME_OUT_QUAD)/                  (600000000).  L The COMPUTED BY field works quite nicely at figuring up the time away.  The N reports we are now getting are too hard to believe and we have decided not to N share them with you. (Would you believe 'P.' was at the supply locker for 187  minutes?  I thought not!)   F We now are having a better time keeping track of 'P.' with the use of M Datatrieve.  I am happy, my boss is happy, and everyone except 'P.' is happy.e e            O _______________________________________________________________________________o      ? Documenting and Manipulating SYSGEN Parameters using DatatrieveS  @ B. Z. Lederman, WU World Communications, New York, NY 10004-2464O _______________________________________________________________________________S  I As a system manager, I have to keep track of the SYSGEN parameters on my CN system.  I also have to keep such files as MODPARAMS.DAT up to date, and with M various changes in VMS and layered products add the proper changes.  Part of  0 this process can be automated using Datatrieve.   L One of the things any system manager should do is save a copy of the SYSGEN & parameters.  This is done as follows:    $ SET DEFAULT SYS$SYSTEM $ MC SYSGENI SYSGEN> USE CURRENTT$ SYSGEN> SET /OUTPUT = PARAMS.28JAN88 SYSGEN> SHOW /ALL  SYSGEN> EXIT  K The output file can of course be named as you choose: I like to put on the sN date for reference.  Also, you should occasionally make such a record doing a H "SHOW /SPECIAL" in addition to "SHOW /ALL": but what I am doing here is N generating a change list, and since special parameters normally should not be N changed I'm not including them here.  A small section of this file looks like  this:    Parameters in use: ActiveoC Parameter Name  Current   Default   Minimum   Maximum Unit  Dynamic_  C --------------  -------   -------   -------   ------- ----  -------_C PFCDEFAULT           64        32         0       127 Pages       DtB KFILSTCNT            16         4         2       255 Slots       B GBLSECTIONS         400       128        20      4095 Sections    B GBLPAGES          20500      4096       512        -1 Pages       B GBLPAGFIL          2048      1024       128        -1 Pages       B MAXPROCESSCNT       128        72        12      8192 Processes   B PROCSECTCNT          32        32         5      1024 Sections    B MINWSCNT             20        20        10        -1 Pages       B PAGFILCNT             2         2         1        63 Files        ....  M The hard part comes in looking through all of the parameters on this listing eN and finding the ones that are not at default values. This is where Datatrieve F makes things easier.  A domain can be defined to read this text file:    REDEFINE RECORD TPARAMS_RECORD 01 TPARAMS_REC.A !r< ! Read in a "Raw" text file output of parameters from SYSGEN !s ! B. Z. Lederman !n     10 NAME PIC X(16).     10 CURRENT PIC X(18).f      10 SUBCUR REDEFINES CURRENT.1                               20 FILLER PIC X(8).'0                               20 RCUR PIC X(10).     10 DEFAULT PIC X(10).p     10 MINIMUM PIC X(10).      10 MAXIMUM PIC X(10)._     10 FILLER PIC X.     10 UNIT PIC X(12).     10 DYNAMIC PIC X.  ;   / REDEFINE DOMAIN TPARAMS USING TPARAMS_RECORD ONA     SYS$SYSTEM:PARAMS.28JAN88;  I The domain definition will have to be re-defined each time the file name iE changes, or you can use a logical name to point to the current file. D  K The above definition will allow you to read in the text as text: but a lot fM more can be done if the numeric parameters could be manipulated as numbers.  E< To do this, I define a matching domain with numeric fields:    REDEFINE RECORD PARAMS_RECORDL !o+ ! Write out "normalized" SYSGEN parameters.  !  ! B. Z. Lederman !h 01 PARAMS_REC.     10 NAME PIC X(16).2     10 CURRENT USAGE LONG EDIT_STRING ZZZ,ZZZ,ZZ9.2     10 DEFAULT USAGE LONG EDIT_STRING ZZZ,ZZZ,ZZ9.2     10 MINIMUM USAGE LONG EDIT_STRING ZZZ,ZZZ,ZZ9.2     10 MAXIMUM USAGE LONG EDIT_STRING ZZZ,ZZZ,ZZ9.     10 UNIT PIC X(12).     10 DYNAMIC PIC X.  ;C  9 REDEFINE DOMAIN PARAMS USING PARAMS_RECORD ON PARAMS.SEQ;   N Now all I have to do is move the data from one domain to the other. Since the L input is in a text file with a title, I want to elimiate the title lines: I O also don't want to move over any parameters which are text rather than numbers E' (such as QUORUM_DISK and SCSNODENAME):    % REDEFINE PROCEDURE CONVERT_PARAMETERS' ! > ! Convert SYSGEN parameters from text to "normalized" numbers.9 ! TPARAMS must first be defined to read the correct file.t( ! Only numeric parameters are converted. !E ! B. Z. Lederman !E
 READY TPARAMS)K DEFINE FILE FOR PARAMS;                       ! remember to purge old filesM READY PARAMS WRITE !E5 FOR TPARAMS WITH UNIT NE "Ascii", "Unit  Dynami", " "a5     STORE PARAMS USING PARAMS_RECORD = TPARAMS_RECORD 
 END_PROCEDURE   A Note that there are two blank spaces between "Unit" and "Dynami".   L Now, I can manipulate this record of my SYSGEN parameters as I please.  For O example, If I had multiple machines with different parameters I could define a  O separate domain for each machine and compare the two to see where they differ. eN  What I am most interested in now, however, is to generate a list of commands M for MODPARAMS.DAT which will restore my current system settings from the VMS C default settings.   # REDEFINE PROCEDURE PRINT_PARAMETERSW ! 7 ! Print out the normalized parameters in "ADD_" format.y# ! Values are current minus default.I !W ! B. Z. Lederman ! 1 FOR PARAMS WITH CURRENT NE DEFAULT SORTED BY NAMED#     PRINT "ADD_" | NAME ||| "=" |||NG                               (CURRENT - DEFAULT) ON *."TT or filespec"T
 END_PROCEDURE.  > The portion of the output from this procedure looks like this:   ADD_ACP_DINDXCACHE = 24; ADD_ACP_DIRCACHE = 118 ADD_ACP_HDRCACHE = 70n ADD_ACP_MAPCACHE = 16e ADD_ACP_QUOCACHE = -64 ADD_BALSETCNT = 63 ADD_BORROWLIM = 518  ADD_DEADLOCK_WAIT = -8 ADD_FREEGOAL = 455 ADD_FREELIM = 87 ADD_GBLPAGES = 16404 ADD_GBLPAGFIL = 1024 ADD_GBLSECTIONS = 272r  O and so on.  While this file is not completely ready to use as it is (the ASCII  I parameters must be re-inserted, and some parameters may be better off as lO absolutes as, for example, ACP_QUOCACHE which I am setting to zero as we don't nO use quotas), it is certainly very much easier to have Datatrieve search all of qN the parameters and find out which ones have changed than to have to do it all N by hand.  And, it saves a lot of typing to have Datatrieve output the changes ; in the form where they are ready to go into MODPARAMS.DAT. u  M It would also be possible to move the ASCII parameters into a separate file, oK or make the record definition a little more elaborate and have them in the  E same file.  But there aren't many of them, and I don't change system hN parameters very often, so I consider the process to be sufficiently useful in  it's present form. i n            P ________________________________________________________________________________  D Errata for Wombat Wizard's column, February 1988, Volume 3, Number 6P ________________________________________________________________________________  / The second paragraph on page DTR-5 should read:C  < ------------------------------------------------------------P A VAX Date is measured in units called "klunks."  Each klunk is 100 nanoseconds O long (0.1 microseconds), so there are 10,000,000 or 10**7 klunks in a second.   O The VAX date is a number of klunks since a base time, and is stored in the VAX  N as a quadword (four 16-bit words, or 64 bits).  The VAX base time (the "zero" K time) is the same as the base time for the Smithsonian Astrophysical time,  P midnight on November 17, 1858.  The VAX Date for that time is a quadword with a P value of zero.  For each second since that time, the quadword is incremented by O 10,000,000, and each day is represented by an additional number of klunks that   can be computed by the formula  P klunks/day          =  24  hours/day  *  60  minutes/hour  * 60 seconds/minute * 10,000,000  % klunks/second      = 864,000,000,000  < ------------------------------------------------------------  5 The next to last paragraph on page DTR-6 should read:n  < ------------------------------------------------------------N In this example, 10**7 klunks were added to a quadword, yielding a date (plus & time) one second later.  However, ... < ------------------------------------------------------------        3                              See you in Cincinatti!t    