This section describes how to use the Object-Maint series of models to generate the modules required for an object-maintenance process. The following topics are covered:
Note:
For more information on object-oriented development, see
Overview
of Object-Oriented Development.
The following diagram shows the components of an object-maintenance process:
Within this hierarchy, the object-maintenance dialog program is not concerned with the internal structure of the files (which is hidden by the PDA), nor the implementation of the data actions (which is hidden by the object subprogram).
The following table lists the modules required to maintain a maintenance object and the models used to generate each module:
| Module | Model used to Generate |
|---|---|
| Object-maintenance subprogram | Object-Maint-Subp or Object-Maint-Enhanced-Subp
model
Note: |
| Object-maintenance dialog program | Object-Maint-Dialog model |
| Object-maintenance dialog subprogram | Object-Maint-Dialog-Subp model |
To maintain an object, such as add a new record or modify an existing one, an object-maintenance dialog invokes an object-maintenance subprogram.
To implement an object-maintenance process using the Object-Maint
models
Define the files and relationships in the Predict data dictionary.
Identify the object, the integrity between objects, and the automatic rules that apply to each object. For more information, see Define Natural Construct Objects.
Create the subprogram using the Object-Maint-Subp model.
This subprogram updates all entities within the object. Subprograms generated by the Object-Maint-Subp model contain the full range of integrity checks (as defined by the Predict relationships) and object semantics, whether they are in the form of Predict automatic rules or object manipulation within user exits.
The Object-Maint-Subp model also creates the parameter data areas (PDAs) for the object: the object PDA and the restricted PDA. The object PDA contains fields to store all occurrences of attributes defined in the object. This PDA is the only part of the object that is exposed to the rest of the application (for update purposes only). The restricted PDA stores information that is used internally by the subprogram. The values in this PDA must only be altered by the subprogram.
Create maps to input values for the object (if a dialog program invokes the object).
Use the Map model or Natural Map editor to create the maps, which extract fields from the object PDA.
Create the object-maintenance dialog program or subprogram using the Object-Maint-Dialog or Object-Maint-Dialog-Subp model.
This module provides the user interface to the object.
The following sections describe the Object-Maint models in the order they are implemented.
This section describes the Object-Maint-Subp and Object-Maint-Enhanced-Subp models, which generate object-maintenance subprograms and corresponding PDAs. The generated subprograms update all entities within an object and contain a full range of integrity checks (as defined by Predict relationships) and object semantics (in the form of Predict automatic rules or object manipulation within user exits). The main difference between these models is that the Object-Maint-Enhanced-Subp model can generate large fields in the object PDA as dynamic fields. This allows long fields to occupy only the space required to pass the data to the database view. For example, one customer may require 1000 characters for delivery instructions and another customer only requires 50 characters. In the first case, 1000 characters will be placed in the parameter data area (PDA) and in the second case only 50 characters will be placed in the PDA.
The Object-Maint-Enhanced-Subp model allows you to take advantage of larger field sizes available in Natural and in the databases. In the past, an alphanumeric field in Natural was restricted to a length of 253 characters. To accommodate larger fields, you had to create an array of strings with a length of less than 254 characters each. This meant that words in a note, for example, may have been split across strings. Using this model, you can specify larger string sizes in the files and in Natural to allow the entire note to fit in one string. The model can also generate code to truncate trailing blanks, which can needlessly increase the amount of data going into the PDA, and generate an error message when a user enters data into a field that is longer than what the database expects.
This section covers the following topics:
An object is built from a primary entity and its child entities (sub-entities), which are defined in Predict with entity relationships. An instance (object value) of the object consists of occurrences (records) of the constituent entities. Depending on the update constraint type specified, the following interpretations of null occurrence are adopted:
For update constraint type C (Cascade), an entity record is set to null if its key suffix value is set to null. An exception to this occurs when the length of the key for the child entity is equal to the length of the key for its parent entity (there is no suffix, for example). In this case, a record is set to null if all non-key attributes are null.
For update constraint type L (suffix is a line number) and type N (renumbered suffix), an entity record is set to null if all the non-key attributes are set to null.
Each instance of the object can be represented by an object instance hierarchy tree, where the occurrence of the primary entity forms the node at the root of the tree and each occurrence of its child entities forms a node at a lower level. A null occurrence of an entity within the object does not correspond to any node of the hierarchy tree. With this representation, the following properties can be observed:
Each non-null occurrence of an entity must correspond to a non-null occurrence of its parent entity; if an entity occurrence is set to null, so are all the occurrences of its child entities. This property of existence can be seen as a downward propagation from parent to child. If a record is set to null during an update, that record and all its child records are deleted.
The attributes (field values) of an entity occurrence can propagate downward to those of its child entities. This type of propagation can be seen while traversing a pre-order tree. When a node is encountered for the first time, it can take on the attributes of its parent node. (To implement this propagation, refer to the V0-entity-name and V1-entity-name subroutines in the UPDATE-EDITS user exit.)
The attributes of an entity occurrence can propagate upward to those of its parent entity. This type of propagation can be seen while traversing a post-order tree. When a node is encountered for the last time, the entity occurrence can contribute to the attributes of its parent since all of its attributes (and its child attributes) are already processed. (To implement this propagation, refer to the V2-entity-name subroutine in the UPDATE-EDITS user exit.)
Tip:
An instance of an object can be referred to as an instance of a
class.
Consider an insurance policy object defined with the following entity relationships:
An object instance consisting of a policy with two inquiries and two vehicles, where the first vehicle has two coverages and the second has three, can be represented by the following object hierarchy tree:
This object hierarchy tree can be equally represented by the following diagram, which illustrates the pre-order and post-order traversing of a tree:
In this diagram, the V0 and V1 on the left side or bottom of each node represent the V0-entity-name and V1-entity-name subroutines; the V2 on the right side of the node represents the V2-entity-name subroutine for the corresponding entity. In this example, the following subroutines are involved:
V0-INS-POLICY and V1-INS-POLICY V2-INS-POLICY V0-INS-VEHICLE and V1-INS-VEHICLE V2-INS-VEHICLE V0-INS-COVERAGE and V1-INS-COVERAGE V0-INS-INQUIRY and V1-INS-INQUIRY
Each node corresponding to an occurrence of the INS-COVERAGE and INS-INQUIRY entities does not have any child nodes and is called a leaf (of the tree). While traversing the object instance hierarchy tree, the first time a leaf is encountered is also the last time. Therefore, a leaf does not have a V2-entity-name subroutine.
The Object-Maint-Subp model generates PERFORM-subroutine statements that allow attributes to propagate with the V0-, V1-, or V2-entity-name subroutines.
The following example shows PERFORM statements generated by the Object-Maint-Subp model:
*PROCESS INS-POLICY *FOR EACH POLICY: PERFORM V0-INS-POLICY PERFORM INS-POLICY-PREDICT-VERIFICATIONS (Check Predict automatic rules for INS-POLICY) PERFORM V1-INS-POLICY *PROCESS INS-VEHICLE *PROCESS INS-INQUIRY PERFORM V2-INS-POLICY *PROCESSING FOR THE INS-POLICY *PROCESS INS-VEHICLE *FOR EACH VEHICLE: PERFORM V0-INS-VEHICLE PERFORM INS-VEHICLE-PREDICT-VERIFICATIONS (Check Predict automatic rules for INS-VEHICLE) PERFORM V1-INS-VEHICLE *PROCESS INS-COVERAGE PERFORM V2-INS-VEHICLE *PROCESSING FOR THE INS-VEHICLE *PROCESS INS-COVERAGE *FOR EACH COVERAGE: PERFORM V0-INS-COVERAGE PERFORM INS-COVERAGE-PREDICT-VERIFICATIONS (Check Predict automatic rules for INS-COVERAGE) PERFORM V1-INS-COVERAGE *PROCESSING FOR THE INS-COVERAGE *PROCESS INS-INQUIRY *FOR EACH INQUIRY: PERFORM V0-INS-INQUIRY PERFORM INS-INQUIRY-PREDICT-VERIFICATIONS (Check Predict automatic rules for INS-INQUIRY) PERFORM V1-INS-INQUIRY *PROCESSING FOR THE INS-INQUIRY
The Object-Maint-Subp model uses the CDAOBJ2 data area, which contains parameters that are common to all object-maintenance subprograms. For example:
1 CDAOBJ2
*
* This data area contains all
* parameters that are common to
* OBJECT-MAINT-SUBPrograms.
*
2 INPUTS
3 #FUNCTION (A15) /* GET, NEXT, UPDATE, DELETE,
* /* STORE, EXISTS, INITIALIZE
* /* Other User Defined Functions.
4 #CLEAR-AFTER-UPDATE (L) /* Initialize object variables
* /* after a successful UPDATE,
* /* DELETE or STORE.
4 #RETURN-OBJECT (L)
4 #ET-IF-SUCCESSFUL (L) /* Commit the record updates
4 #USE-ISN (L)
/* If the OBJECT was
/* generated with the
/* condition code
/* GET-BY-ISN and
/* this flag is true the
/* GET-OBJECT and
/* HOLD-OBJECT subroutines
/* will retrieve the
/* record by ISN
4 #IGNORE-HELD-ID-CHECK (L) /* Can be used to ignore
* /* the HELD-ID check;
* /* This check can be
* /* ignored if hash locking
* /* is used
4 #BACKOUT-ISSUED (L) /*when true the Object Maint issued a backout transaction
2 OUTPUTS
4 #OBJECT-CONTAINS-DERIVED-DATA (L)
4 #EXISTS (L) /* Requested object exists.
|
- Conditional END OF TRANSACTION (ET) Statement
The Object-Maint-Subp model supports a conditional END OF TRANSACTION (ET) statement. When client and server components are on different platforms, the ET logic is not easily transmitted across the network. To make this process simpler and more automated, the Object-Maint-Subp model generates a conditional ET statement that is controlled by two logical variables: #UPDATE-PERFORMED and #ET-IF-SUCCESSFUL.
Both variables must be set to True before an ET is performed. The #UPDATE-PERFORMED variable is internally set in the object-maintenance subprogram (depending on the method that was requested). The #ET-IF-SUCCESSFUL variable is set by the callers of the subprogram and passed across different platforms via the CDAOBJ2 data area.
If both components reside on the same platform:
The object-maintenance dialog modules can continue to issue the ET as before (by default, the dialog module issues the ET)
or
The object-maintenance subprogram can perform the ET
The following conditional statement is generated:
IF #UPDATE-PERFORMED AND CDAOBJ2.#ET-IF-SUCCESSFUL THEN END OF TRANSACTION END-IFNote:
If upgrading a generated object-maintenance subprogram from Natural Construct V3 to version 4 or higher, you must also regenerate the calling dialogs. The order of generation is important; first regenerate the object-maintenance subprograms and then regenerate the dialog modules.- GET-BY-ISN Option
The Natural Construct administrator can set up the Object-Maint-Subp model to generate code that retrieves data by ISN for Adabas files. This functionality allows a GET BY ISN statement to be converted into a CALLNAT to the object-maintenance subprogram. The GET BY ISN code is only executed if:
CDAOBJ2.#USE-ISN is set to True
ObjectName.OBJECT-ISN has a value
the NEXT or FORMER actions are not being used
If an object is generated with the GET-BY-ISN condition code and the #USE-ISN field set to True, the GET-OBJECT and HOLD-OBJECT subroutines retrieve the record by ISN.
Notes:
- To determine whether the GET-BY-ISN condition code is set, see Determine Which Condition Codes are Set in Common Model Specifications and Development Tasks.
- For information on using the Adabas ISN as a unique primary key for maintenance, see Use *ISN as the Unique Primary Key for Maintenance in Understanding Natural Business Services.
The Object-Maint-Subp model generates the followiong object and restricted PDAs:
This PDA allows data to be transferred between an object-maintenance subprogram and the object-maintenance dialog program or subprogram, and/or any other programs that invoke the object-maintenance subprogram.
The following example shows a PDA generated by the Object-Maint-Subp model:
15:06:58 ***** E D I T DATA ***** 13-10-16
Library: SYSCSTDE Name: ORDERPDA PARAMETER DBID: 18 FNR: 4
Command: > +
I T L Name F Leng Index/Init/EM/Name/Comment
- - - -------------------------------- - ---- -------------------------------
1 ORDER /* Object Name
2 ORDER-NUMBER N 6 /*
2 ORDER-AMOUNT P 13.2 /*
2 ORDER-DATE N 8 /*
2 ORDER-CUSTOMER-NUMBER N 5 /*
2 ORDER-WAREHOUSE-ID A 3 /*
2 INVOICE-NUMBER N 6 /*
2 ORDER-TIMESTAMP T /*
2 C#DELIVERY-INSTRUCTIONS N 3 /* Counter Field
2 DELIVERY-INSTRUCTIONS A 60 (1:20)
*
2 C#NCST-ORDER-HAS-LINES N 3 /* Counter field
2 NCST-ORDER-HAS-LINES (1:30) /* NCST-ORDER-LINES
3 LINE-NUMBER N 2 /*
3 ORDER-PRODUCT-ID A 6 /*
3 LINE-DESCRIPTION A 40 /*
3 QUANTITY P 9 /*
3 UNIT-COST P 7.2 /*
3 TOTAL-COST P 9.2 /*
*
3 C#NCST-LINE-HAS-DISTRIBUTION N 3 /* Counter field
3 NCST-LINE-HAS-DISTRIBUTION (1:10) /* NCST-ORDER-DISTRIBUTION
4 DIST-LINE-NUMBER N 2 /*
4 DIST-NUMBER N 2 /*
4 ACCOUNT A 9 /*
R 4 ACCOUNT /* REDEF. BEGIN : ACCOUNT
5 COST-CENTER A 2 /*
5 ACCT A 4 /*
5 PROJECT A 3 /*
4 DIST-AMOUNT P 9.2 /*
*
1 ORDERPDA-ID N 6 /* Object identifier
R 1 ORDERPDA-ID /* REDEF. BEGIN : ORDERPDA-ID
2 STRUCTURE /* To allow MOVE BY NAME
3 ORDER-NUMBER N 6 /* |
The Object-Maint-Subp model also generates the restricted object PDA. The generated object-maintenance subprogram uses the restricted object PDA to store information that is used across multiple applications. An example of such information is the Adabas ISNs (Internal Sequence Numbers) of all entities within an object when the object is read. In this way, the entities can be easily retrieved for an Update action. The actual contents of the restricted PDA are only used internally by the generated object-maintenance subprograms.
For more information, see Define Object Relationships in Predict and Support for Predict Automatic Rules.
Note:
An object-maintenance subprogram has no user-interface component.
For more information, see
Parameters
for the Object-Maint-Subp Model. To see a sample
subprogram, refer to ORDERN in the Natural Construct
demo system.
If a Natural object contains a FIND statement that must be converted to an object-maintenance subprogram, you can create a new data access function and code the FIND statement in user exits. To accommodate this functionality, and the GET BY ISN data access statement, certain code has been placed in subroutines. This allows the same code to be executed — regardless of the access method. These subroutines are:
HOLD-PRIMARY-RECORDS-FOUND (when the data is accessed with a hold)
GET-PRIMARY-RECORDS-FOUND (when the data is accessed without a hold)
NO-PRIMARY-RECORDS-FOUND
For examples of these subroutines, refer to the GET-OBJECT and HOLD-OBJECT routines.
An object-maintenance subprogram generated by the Object-Maint-Subp model stores a "before" image of data (for example, what an order looked like before a user made changes). The before image is kept on the database and is re-requested before an update is performed.
To do this, the code must be generated with the hash-locking feature. Logical variables are then stored as Alpha format in the local data area to process the hashed values. All data has to hash to the same value as when the data was requested. If it does, then the data has not changed.
Note:
For information about hash locking, see
Hash-Locking
Option.
Tip:
As the local data area is populated with the original data, you can
use this data in your own logic.
An object consists of a primary entity and all its child entities (sub-entities). Each entity is processed in the following order:
Pre-editing checks, which consist of all the edit checks done before the child or children of the current entity are processed.
Processing, during which the current entity is updated, added, or deleted.
Post-editing checks, which consist of all the edit checks done after the child or children of the current entity are processed.
This section covers the following topics:
The generated subprogram performs automatic validation using information stored in Predict. It checks for:
The uniqueness of a key, if required
Foreign referential constraints (inter-object relationships)
Predict automatic rules
Cardinality constraints for Predict relationships
In Adabas files, Natural Construct processes each entity in the following order:
Performs pre-edit checks.
Processes all children.
Performs post-editing checks.
Adds, updates, or deletes the entity.
In non-Adabas files (VSAM, DB2, DL1/IMS), Natural Construct processes each entity in the following order:
Performs pre-edit checks on the current entity.
Adds or updates the entity.
Processes all children of the entity.
Performs post-edit checks.
Note:
For VSAM, DB2, or DL1/IMS files with a primary key, if the key for
an entity is updated to a new value, the record with the new key value is added
before the child records are processed and the record with the old key value is
deleted after the child records are processed. Otherwise, the key is updated as
usual.
Performs pre-edit checks on the current entity.
Processes all children of the entity.
Deletes the entity.
Note:
For relational database and DL1/IMS files with referential
integrity rules (Predict type R relationships)
defined for intra-object relationships with type C (Cascade) constraint type,
the DELETE statement is generated only at the primary level. The DBMS handles
the cascading delete through all child records.
This editing is performed before the children of the current entity are processed. Natural Construct creates pre-editing subroutines (called EDIT-OBJECT for the primary entity and E-entity-name for sub-entities) and executes them in the following order:
Builds the key for the current entity.
Ensures the uniqueness of the key (if required).
Executes the V0-entity-name subroutine within the UPDATE-EDITS user exit.
Enforces the Predict automatic rules.
Executes the V1-entity-name subroutine within the UPDATE-EDITS user exit.
Enforces the Restricted Update for Insertion (RUI) rules.
Enforces the Restricted Update (RU) rules (if the entity is greater than level 1).
Executes the D-entity-name subroutine within the DELETE-EDITS user exit.
Enforces the Restricted Delete (RD) rules.
This editing is performed by the V2-entity-name subroutine after the children of the current entity are processed. Natural Construct generates the PERFORM V2-entity-name statement in the following subroutines:
CHECK-AND-UPDATE-OBJECT (for the primary entity)
C-entity-name (for the sub-entity)
Post-editing allows the upper level to maintain some desired redundancy. For example, an insurance policy requires a premium for each vehicle insured under the policy. For performance reasons, the policy has a redundant field called POLICY-TOTAL-PREMIUM. You can determine the total premium by looking at the primary entity for the object; you do not have to go through all the vehicle entities.
This section describes different uses for user exits supplied for the Object-Maint-Subp model. The following topics are covered:
In addition to a conditional END OF TRANSACTION (ET) statement, the Object-Maint-Subp model offers user exits called BEFORE-ET, BEFORE-ET-PROCESSING and AFTER-ET-PROCESSING. These exits provide the same capabilities for the ET statement in the object-maintenance subprogram as are available in dialog modules. The following conditional statement and user exits (if requested) are generated:
**SAG DEFINE EXIT BEFORE-ET
* Any special processing before an ET, where this code will be executed
* whether an ET is issued or not.
**SAG END-EXIT
IF #UPDATE-PERFORMED AND CDAOBJ2.#ET-IF-SUCCESSFUL THEN
IF #UPDATE-PERFORMED AND CDAOBJ2.#ET-IF-SUCCESSFUL THEN
**SAG DEFINE EXIT BEFORE-ET-PROCESSING
/* Any special processing before an ET.
**SAG END-EXIT
END OF TRANSACTION
**SAG DEFINE EXIT AFTER-ET-PROCESSING
/* Any special processing after an ET.
**SAG END-EXIT
END-IF
For information about these user exits, see BEFORE-ET, BEFORE-ET-PROCESSING and AFTER-ET-PROCESSING in Natural Construct Generation.
You can specify additional edit checks within the UPDATE-EDITS user exit and additional referential integrity checks within the EXTENDED-RI-CHECKS user exit. The UPDATE-EDITS user exit contains validation subroutines that execute edit checks at different points during the processing of an entity. You can create subroutines for each entity within an object.
The UPDATE-EDITS user exit contains the following validation subroutines:
| Subroutine | Description |
|---|---|
| V0-entity-name | Executed during the pre-editing phase, before the Predict automatic rules are checked and the children of the current entity are processed. |
| V1-entity-name | Executed during the pre-editing phase, after the Predict automatic rules are checked and before the children of the current entity are processed. |
| V2-entity-name | Executed during the post-editing phase, after the Predict automatic rules are checked and all children of the current entity are processed. |
The EXTENDED-RI-CHECKS user exit contains the following validation routine:
| Subroutine | Description |
|---|---|
| V-relationship-name | Executed during the pre-editing phase, after the Predict automatic rules are checked and after the V1-entity-name subroutine for the current entity is executed. |
For more information about these validation subroutines and user exits, see Object Instance Hierarchy Tree and UPDATE-EDITS and EXTENDED-RI-VIEWS in Natural Construct Generation.
The Object-Maint-Subp model has two specification panels: Standard Parameters and Additional Parameters. This section describes these panels. The following topics are covered:
Note:
For information about creating an object-maintenance process, see
Design Methodology in Natural Construct
Generation.
The following example shows the first specification panel, the Standard Parameters panel:
CUOBMA Object-Maint-Subp Subprogram CUOBMA0
Jan 25 Standard Parameters 1 of 2
Module ............. MCUST2N_
System ............. DEMO____________________________
Title .............. Object Title_____________
Description ........ Object description_____________________________________
for..._________________________________________________
_______________________________________________________
_______________________________________________________
Message numbers .... X
Hash locking ....... _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
right help retrn quit right main |
The fields in the upper portion of this panel are similar for all models. For a description of these fields, see Common Fields on the Standard Parameters Panel in Common Model Specifications and Development Tasks. For information on the hash-locking option, see Hash-Locking Option.
The following example shows the second specification panel, the Additional Parameters panel:
CUOBMB Object-Maint-Subp Subprogram CUOBMB0
May 28 Additional Parameters 2 of 2
Predict view ............. ________________________________ *
Primary key .............. ________________________________ *
Hold field ............... ________________________________ *
Object description ....... ____________________
Generate Source Object
Object PDA ............... ________ * _ C421 C421
Restricted PDA ........... ________ * _ C421 C421
Object name .............. ________________________________
Next action prefix ....... _
Log file suffix .......... ________
Trace relationships ...... _
Enhanced DB2 timestamp ... _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
main help retrn quit left userX main |
Tip:
If the Predict view is blank and there is a value in Object PDA, you
can enter the name of another PDA (which must be generated by Natural Construct
and available in the current library) in Object PDA to populate the Predict
view, Primary key and Object name fields with the values from this PDA.
The fields on this panel are:
| Field | Description |
|---|---|
| Predict view | Name of the Predict view. A file definition for this view must exist in Predict. Predict type N (Natural Construct) relationships relating to the primary file are processed by the generated object-maintenance subprogram. Relationships defined with a cascading delete constraint are maintained as part of the object; relationships defined with a restricted delete constraint are used by the object-maintenance subprogram to implement referential constraints. |
| Primary key | Name of the key in Predict for the primary file. This key becomes the primary key to access the view for maintenance. The key can be a descriptor, superdescriptor, or subdescriptor. If the key does not exist in the specified Predict file, an error message is displayed. |
| Hold field | Name of the field used to logically protect
the record against intervening update or delete actions. Because an
object-maintenance subprogram does not use the record-holding facilities of the
DBMS to lock records during a GET operation, a hold field must exist
in the primary file for the object. Valid data types are:
Note: |
| Object description | Object description used in messages. If you specify "Person", for example, messages are displayed as "Person not found" and "Person displayed". |
| Object PDA | Name of the parameter data area (PDA) used in conjunction with the object-maintenance subprogram. For more information, see Object PDA. |
| Restricted PDA | Name of the restricted PDA used in conjunction with the object-maintenance subprogram. For more information, see Restricted PDA. |
| Generate | If a generated PDA is not found in the steplib chain, this field is marked and protected. Natural Construct will generate the PDA. |
| Source | Name of the first library in which the source
code for the module is found. The source code for the module may exist in
multiple libraries in the Natural steplib chain.
If the source code resides in the current library, regenerating it will execute a STOW command and overwrite the previous version. |
| Object | Name of the first library in which the object
code for the module is found. The object code for the module may exist in
multiple libraries in the Natural steplib chain.
If the object code resides in the current library, regenerating it will execute a STOW command and overwrite the previous version. Note: |
| Object name | Name of the level 1 structure used to qualify
the fields in the object PDA. (It is easier to identify the source of these
attributes if the PDA name is used for this purpose.) The object name should be
kept to a reasonable length.
Note: |
| Next action prefix | If the primary key is compound or redefined
into various components, supply a value to limit the number of prefixed
components confined on the Next action. This allows the subprogram to maintain
objects with a common prefix value.
For example, if the primary key is made up of Company + Account + Division and you do not want the Next action to span the Division values, specify "2". Specify "1" if the Next action is to be limited to the current Company value. |
| Log file suffix | If you want to log objects, you have to create
a log file corresponding to each entity within the object. The name of the log
file is the name of the object file concatenated with the suffix specified
here. For example, if the object consists of the NCST-ORDER-HEADER and
NCST-ORDER-LINES entities and you specify "-LOG",
the log file names are NCST-ORDER-HEADER-LOG and NCST-ORDER-LINES-LOG.
The following fields are required in the log file that corresponds to the header entity in the object:
In the log files corresponding to the sub-entities in the object, only the LOG-ACTION field is required. Note: |
| Trace relationships | When this field is selected, Natural Construct displays the relationships it has accepted or rejected. During the generation process, all accepted and rejected relationships are displayed with a message indicating the type of relationship. |
| Enhanced DB2 timestamp | When this field is selected, the time value is retrieved from DB2. A "SELECT CURRENT TIMESTAMP" statement will be generated to obtain a precise timestamp value. Otherwise, the time value is retrieved from Natural's time system variable. |
The Natural Construct administrator can change optimistic record locking from the default timestamp method to the hash-locking method. When the hash-locking method of record locking is specified, the Hold field is not available on the Additional Parameters panel. Instead, an Object LDA field is displayed, showing the name of the object local data area generated for the object-maintenance subprogram. For example:
CUOBMB Object-Maint-Subp Subprogram CUOBMB0
Jan 13 Additional Parameters 2 of 2
Predict view ............. NCST-ORDER-HEADER_______________ *
Primary key .............. ORDER-NUMBER____________________ *
Object description ....... ORDER_______________
Generate Source Object
Object PDA ............... ORDERPDA * X SHDEMO SHDEMO
Restricted PDA ........... ORDERPDR * X SHDEMO SHDEMO
Object name .............. ORDER___________________________
** Object LDA is generated when Object PDA is generated
Object LDA ............... ORDERNH_ * SHDEMO SHDEMO
Next action prefix ....... _
Log file suffix .......... ________
Trace relationships ...... _ |
The hash-locking method retains the functionality of the object-maintenance subprogram. The only difference is that it checks all the object data, not just the timestamp, to ensure there have been no intervening modifications.
If the hash-locking method was specified:
An object LDA is generated
The generated code contains the #HASH-RETRIEVE and #HASH-DATABASE fields in the restricted PDA and will reference a Natural user exit called USR4011N
The following example shows the User Exits panel for the Object-Maint-Subp model:
CSGSAMPL OBJECT-MAINT-SUBP Subprogram CSGSM0
Aug 27 User Exits 1 of 1
User Exits Exists Sample Required Conditional
-------------------------------- -------- ---------- -------- ------------
_ NAT-DOCS X
_ CHANGE-HISTORY Subprogram
_ PARAMETER-DATA Example
_ EXTENDED-RI-VIEWS
_ LOCAL-DATA Example
_ START-OF-PROGRAM Example
_ SELECT-STATEMENT Subprogram X
_ USER-DEFINED-FUNCTIONS Example
_ BEFORE-ET Example X
_ BEFORE-ET-PROCESSING Example
_ AFTER-ET-PROCESSING Example
_ PROCESS-ERROR-MESSAGE
_ ERROR-MESSAGE-PDAS
_ END-OF-PROGRAM Example
_ BEFORE-STORE Example
_ AFTER-STORE
_ AFTER-GET Example
_ BEFORE-DELETE X
_ AFTER-INIT Example
_ UPDATE-EDITS Subprogram
_ DELETE-EDITS Subprogram
_ AFTER-GET-EDITS Subprogram
_ EXTENDED-RI-CHECKS Subprogram
_ ADJUST-OBJECT-ID-IN-MSG Example
_ AFTER-UPDATE
_ OVERRIDE-MINIMUM Example
_ OVERRIDE-MAXIMUM Example
_ MISCELLANEOUS-SUBROUTINES Example
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
frwrd help retrn quit bkwrd frwrd |
Notes:
The following user exits are specific to the Object-Maint-Subp model:
The code in this exit is executed after the data is stored, but before the END TRANSACTION is issued. For example, it can be used in conjunction with Adabas TRS (Text Retrieval System). As TRS cannot invert a document index unless the document record exists, the code in this exit calls TRS to invert the document. In that way, the transaction can be backed out if there are any problems with TRS.
The code in this exit is executed after the data is updated, but before the END TRANSACTION is issued. For example, it can be used in conjunction with Adabas TRS (Text Retrieval System). As TRS does not have an update document index function, the code in this exit calls TRS to delete the document index and then calls TRS again to invert the document.
The code in this exit is executed before the data is deleted. For example, it can be used in conjunction with Adabas TRS (Text Retrieval System). TRS requires the document index to be deleted before the document record is deleted. The code in this exit can call TRS to delete the document index so the document record can be deleted.
The code in this exit is executed before the STORE command is issued. Use this exit when you want to change the primary key for an object (for example, when you want to generate a unique primary key number).
The Object-Maint-Enhanced-Subp model is similar to the Object-Maint-Subp model, except it supports the generation of large fields into the object PDA as dynamic fields. As with the Object-Maint-Subp model, this model has two specification panels: Standard Parameters and Additional Parameters. The majority of the fields on these panels are the same. This section describes the fields that are specific to the Object-Maint-Enhanced Subp model. The following topics are covered:
Notes:
The following example shows the first specification panel, the Standard Parameters panel:
CUDYMA OBJECT-MAINT-ENHANCED-SUBP Subprogram CUDYMA0
Feb 05 Standard Parameters 1 of 2
Module ............. SS______
System ............. CNDPRO__________________________
Title .............. Object ....______________
Description ........ This subprogram is used to perform object maintenance__
for..._________________________________________________
_______________________________________________________
_______________________________________________________
Message numbers .... _
Hash locking ....... _
Generate dynamic fields when length is greater than .... 25_
Return errors when data is truncated ................... X
Generate with large object (LO) fields ................. _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
right help retrn quit right main |
The fields in the upper portion of this panel are similar for all models. For a description of these fields, see Common Fields on the Standard Parameters Panel in Common Model Specifications and Development Tasks. For information on the hash-locking option, see Hash-Locking Option.
The following fields are specific to the Object-Maint-Enhanced-Subp model:
| Field | Description |
|---|---|
| Generate dynamic fields when length is greater than nnn (where nnn is a number less than 1000 and 0 indicates the data PDA contains the same lengths as the DDM) | Generates dynamic fields into the object PDA
when the size of the source field is larger than the number of characters
specified in this field. For example, if the specified cutoff length is 50 and
a field is defined in the DDM as alphanumeric 100, an (A) DYNAMIC field will be
generated into the object PDA instead of an (A100).
Notes:
|
| Return errors when data is truncated | Indicates whether the generated subprogram
returns an error message when an alpha dynamic field is larger than its source
database field and data in the field will be truncated.
For example, you may have a text field with a variable length for descriptive information that you want to set to 1000 characters. Since an alpha dynamic field can handle more than 1000 characters, you must decide what happens if the user enters more. One option is to let the user enter whatever they want and the subprogram will truncate any data over the limit when it stores it in the database. Another option is to generate error messages when the user exceeds the limit and/or to stop the processing. When the subprogram is generated with the truncation option, Construct will provide error messages and a user exit to define how to handle the error. Within this user exit, Construct generates a list of all affected fields (i.e., are alpha dynamic fields in the PDA but not in the file view) and allows you to change the value for ##RETURN-CODE or add an ESCAPE ROUTINE to continue with processing when an error occurs. Note: |
| Generate with large object (LO) fields | Indicates whether large object (LO) fields are maintained by the generated subprogram. |
The following example shows the second specification panel, the Additional Parameters panel:
CUDYMB OBJECT-MAINT-ENHANCED-SUBP Subprogram CUDYMB0
May 28 Additional Parameters 2 of 2
Predict view ............. ________________________________ *
Primary key .............. ________________________________ *
Hold field ............... ________________________________ *
Object description ....... ____________________
Generate Source Object
Object PDA ............... NEWOMSA_ * X
Restricted PDA ........... NEWOMSR_ * X
Object name .............. ________________________________
Next action prefix ....... _
Log file suffix .......... ________
Trace relationships ...... _
Enhanced DB2 timestamp ... _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
main help retrn quit left userX main |
The fields on this panel are identical to the fields on the Additional Parameters panel for the Object-Maint-Subp model. The only difference is that the Generate field is always marked for the Object PDA and Restricted PDA fields. These parameter data areas will always be generated or regenerated with the Object-Maint-Enhanced-Subp model, since the field definitions may change when dynamic fields are processed.
After generating the subprogram, you can edit generated source code that is not within user exits. For information about the protected lines in the generated source code, see the NaturalONE documentation (Using the Source Editor in Using NaturalONE).
The following example shows the User Exits panel for the Object-Maint-Enhanced-Subp model:
CSGSAMPL OBJECT-MAINT-ENHANCED-SUBP Subprogram CSGSM0
Aug 27 User Exits 1 of 1
User Exits Exists Sample Required Conditional
-------------------------------- -------- ---------- -------- ------------
_ NAT-DOCS X
_ CHANGE-HISTORY Subprogram
_ PARAMETER-DATA Example
_ EXTENDED-RI-VIEWS
_ LOCAL-DATA Example
_ START-OF-PROGRAM Example
_ SELECT-STATEMENT Subprogram X
_ USER-DEFINED-FUNCTIONS Example
_ BEFORE-ET Example X
_ BEFORE-ET-PROCESSING Example
_ AFTER-ET-PROCESSING Example
_ PROCESS-ERROR-MESSAGE
_ ERROR-MESSAGE-PDAS
_ END-OF-PROGRAM Example
_ BEFORE-STORE Example
_ AFTER-STORE
_ AFTER-GET Example
_ BEFORE-DELETE X
_ AFTER-INIT Example
_ UPDATE-EDITS Subprogram
_ DELETE-EDITS Subprogram
_ AFTER-GET-EDITS Subprogram
_ EXTENDED-RI-CHECKS Subprogram
_ ADJUST-OBJECT-ID-IN-MSG Example
_ AFTER-UPDATE
_ OVERRIDE-MINIMUM Example
_ OVERRIDE-MAXIMUM Example
_ PROCESS-TRUNCATION-ROUTINE Example X
_ MISCELLANEOUS-SUBROUTINES Example
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
frwrd help retrn quit bkwrd frwrd |
Most of the user exits for this model are identical to those for the Object-Maint-Subp model.
Notes:
The following user exit is specific to the Object-Maint-Enhanced-Subp model:
This user exit can be used in the generated subprogram to define truncation routines and error messages for alpha dynamic fields. It is a Conditional exit and available when the PDA for the subprogram contains alpha dynamic fields in the object PDA that represent fixed-length fields in the database.
When you select the PROCESS-TRUNCATION-ROUTINE user exit, the following code is generated into the exit:
Module ............. ModName Title .............. Object .... > > + ABS: X X-Y: _ S 5 L 1 All ....+....1....+....2....+....3....+....4....+....5....+....6....+....7.. 0010 DEFINE EXIT PROCESS-TRUNCATION-ROUTINE 0020 /* Start of PROCESS-TRUNCATION-ROUTINE user exit 0030 /* note that the ##RETURN-CODE can be changed or 0040 /* ESCAPE ROUTINE can be added so that one doesn't stop the program. 0050 END-EXIT
To allow processing to continue when a truncation error occurs, you can change the value for ##RETURN-CODE or add an ESCAPE ROUTINE.
The Object-Maint-Dialog model generates the dialog component (Natural program) of an object-maintenance process. The dialog component communicates with the user and invokes methods (data actions) implemented by the object-maintenance subprogram. To generate a complete maintenance process using Natural Construct’s object-oriented approach, the Object-Maint-Dialog model must be used in conjunction with the Object-Maint-Subp model (which also generates the object PDA and restricted PDA). The dialog program performs the following functions:
Executes all INPUT/OUTPUT functions:
input object data and actions executed on the object
mark fields in error and display error messages
Invokes the object-maintenance subprogram and passes it the object and action to be executed.
Supports left/right scrolling for multiple panels.
Controls up to four scroll regions on each panel. A region can also be scrolled simultaneously on two panels.
Displays information for related entities outside the object (sub-entities).
The following example shows a generated object-maintenance dialog (only the first panel is displayed):
Add Browse Clear Display Modify Next Purge
NCOMENT ***** ORDER SUBSYSTEM ***** NCOMEM11
Oct 28 - MAINTAIN ORDER ENTRIES - 1 more >
Action...........: __
Order Number.....: 111111 Invoice Number.....: 111111
*Customer Number..: 11111 QUAKER OATS
*Warehouse ID.....: 113 SOUTHERN DISTRIBUTORS LIMITED
Order Date.......: Order Amount: 1500.00
1_ ----- Product Information ------ 1_ Distribution Information
1 *Product....: 187361 /\ Account Amount
Quantity...: 10_______ 1 _________ ____________ /\
Cost/Unit..: 150.00 2 _________ ____________
Total......: 1500.00 3 _________ ____________
Description: CAT NUGGETS \/ 4 _________ ____________ \/
1_ Delivery Instructions (Scroll right for full screen)
1 /\
2 \/
Direct Command: _________________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
confm help retrn quit flip pref bkwrd frwrd left right main
Related information displayed. |
Notes:
This section covers the following topics:
In the Object-Maint-Dialog model example, there are three scroll regions:
Product Information (order lines entity).
Distribution Information (distribution entity).
Delivery Instructions (array within the primary entity).
Depending on where the user places the cursor, pressing PF7 (bkwrd) or PF8 (frwrd) scrolls through the data in each of the regions.
The Object-Maint-Dialog model has four specification panels: Standard Parameters, Additional Parameters, Scroll Region Parameters, and Related File Parameters. This section describes these panels. The following topics are covered:
Note:
For information about creating an object-maintenance process, see
Design Methodology in Natural Construct
Generation.
The following example shows the first specification panel, the Standard Parameters panel:
CUOMMA Object-Maint-Dialog Program CU--MA0
Sep 16 Standard Parameters 1 of 4
Module ............. ________
System ............. CST821S_________________________
Global data area ... CDGDA___ *
With block ......... ________________________________
Title .............. Object Dialog..._________
Description ........ This program is used to maintain the...________________
_______________________________________________________
_______________________________________________________
_______________________________________________________
First header ....... ________________________________________________
Second header ...... ______________________________________________________
Command ............ _
Message numbers .... _
Password ........... _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
right help retrn quit right main |
The fields on this panel are similar for all models. For a description of these fields, see Common Fields on the Standard Parameters Panel in Common Model Specifications and Development Tasks.
The following example shows the second specification panel, the Additional Parameters panel:
CUOMMB Object-Maint-Dialog Program CUOMMB0
Nov 19 Additional Parameters 2 of 4
Object maint subprogram .. ________ *
#ACTION field length ..... 1 Add ...... X Browse ... ________ *
Clear .... X Display .. X
Modify ... X Next ..... X
Purge .... X Former ... _
Window support ........... _
Push-button support ...... _
Mark cursor field ........ ________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
help retrn quit windw left right main |
The fields on this panel are:
| Field | Description |
|---|---|
| Object maint subprogram | Name of the subprogram invoked by the generated module. (Use the Object-Maint-Subp model to generate the subprogram.) The specified subprogram must exist in the current library. |
| #ACTION field length | Length of the action field. By default, the
length is "1" and all action fields except Former
are marked. If you do not want the generated dialog to perform a particular
action, deselect the corresponding action field. At least one action must be
selected.
The available actions are:
Notes:
|
| Window support | Indicates whether the output from the generated object-maintenance dialog is displayed in a window or on a panel (the default). |
| Push button support | Indicates whether actions on the generated dialog can be selected by cursor. |
| Mark cursor field | Name of the field on the map where the cursor is automatically placed by the generated dialog program. |
To change the default window settings for your object-maintenance
dialog
Press PF5 (windw) on the Additional Parameters panel.
The Window Parameters window is displayed. For a description of this window, see Change the Default Window Settings in Common Model Specifications and Development Tasks.
The following example shows the third specification panel, the Scroll Region Parameters panel:
CUOMMC Object-Maint-Dialog Program CUOMMC0
Sep 16 Scroll Region Parameters 3 of 4
Horizontal panels ................. 1
>> 1 Input using map .............. CDLAY___ *
Scrollable Regions 1 2 3 4
Total occurrences ............ ___ ___ ___ ___
Screen occurrences ........... ___ ___ ___ ___
Starting from ................ #ARRAY1 #ARRAY2 #ARRAY3 #ARRAY4
Scroll with panel ............ _ _ _ _
Top left ...... Line ......... ___ ___ ___ ___
Column ....... ___ ___ ___ ___
Bottom right .. Line ......... ___ ___ ___ ___
Column ....... ___ ___ ___ ___
Depth occurrences ............ ___
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
help retrn quit deflt bkwrd frwrd left right main |
The fields on this panel are:
| Field | Description |
|---|---|
| Horizontal panels | Number of horizontal panels. If the generated program requires more than one input panel to accept all values that are being maintained, specify the total number of panels in this field. By default, "1" is displayed. If you specify more than one panel, Natural Construct activates the left and right PF-keys in the generated program to allow left and right scrolling between panels. |
| >> 1 | If you specify more than one panel, you can
display the map specification fields for another panel by entering that panel
number in this field. By default, "1" is displayed.
The number specified in this field cannot exceed the number specified in the
Horizontal panels field.
Note: |
| Input using map | Name of the map for the current panel. If you
enter scroll region information, the specified map should contain array fields
that match the specified values.
You can create the maps using the Map model or the Natural Map editor. If you require scrolling regions, you can use the CDLAYMP1 layout map with the Map model. The Map model generates all of the required indexes to control scrolling. If you create the map in the Map editor, use the CDLAYOM1 layout map. Note: |
| Scrollable Regions | Number of the scroll region for the corresponding scroll specifications. You can define the specifications for up to four vertical scroll regions (consisting of vertical arrays) for each panel. |
| Total occurrences | Total number of scrollable lines required for the scroll region. The total occurrences value applies when the generated program includes a line scroll feature to scroll records in a secondary or tertiary file, or multiple-valued fields (MUs), or periodic groups (PEs). The program ensures that the values assigned to the array index values (#ARRAY1 through #ARRAY4) do not exceed the total occurrences value for each array. |
| Screen occurrences | If you specify a total occurrences value, specify the total number of lines displayed on the panel at one time. |
| Starting from | Starting index for each scroll region. Repeating fields in a scroll region must be indexed by #ARRAYn for scroll region n (where n = 1, 2, 3, or 4). |
| Scroll with panel | If you want to force a particular starting from value for a panel (so it has the same value as another panel), specify the panel number in this field. Each panel maintains its own current values for the Starting from field (#ARRAYn where n = 1, 2, 3, or 4). |
| Scroll region location | Location of the corresponding scroll region. A
scroll region is always rectangular and is defined by specifying the panel
coordinates of the top left and bottom right corners. In the generated dialog,
pressing the bkwrd and frwrd PF-keys positions the scroll regions backward and
forward.
When you specify the location of each scroll region, you make the generated program sensitive to the position of the cursor in an active scroll region. If the cursor is inside a defined region, pressing these keys moves the cursor to the base of the active scroll region and only that region is scrolled. If the cursor is not inside a defined region, pressing these keys scrolls all regions. Note: |
| Top left Line | Starting line number (vertical axis) for the scroll region. |
| Top left Column | Starting column number (horizontal axis) for the scroll region. |
| Bottom right Line | Ending line number (vertical axis) for the scroll region. |
| Bottom right Column | Ending column number (horizontal axis) for the scroll region. |
| Depth occurrences | To create scroll region with a third dimension,
specify the maximum depth occurrences value. For a calendar with the months and
days forming the first two dimensions (horizontal and vertical) and the year
forming the third dimension (depth), for example, you can specify
"3" to scroll up to three yearly tables of calendar
months and days, and within each yearly table, scroll vertically through the
days.
To allow the value of the #DEPTH variable to be changed, you can either place the #NEXT-DEPTH (P3) variable on the specified map or use PF-keys that you process in the AFTER-INPUT user exit. |
Tip:
You can think of a two-dimensional (2D) array as a collection of
many one-dimensional (1D) arrays. And you can think of a fixed instance of a
third dimension of a three-dimensional (3D) array as a 2D array. Therefore, a
vertical scroll region on the generated dialog can consist of 1D, 2D, or 3D
arrays.
This section covers the following topics:
If the object-maintenance map contains scrolling regions with one-dimensional arrays, you can retrieve the default values for the scroll region parameters by pressing PF5 (deflt). The values for the scroll region parameters are read from the specified map. The scroll regions must be indexed by #ARRAY1 through #ARRAY4.
Press PF7 (bkwrd) to display the scroll region specifications (Map name, Scroll region, etc.) for the previously-defined panel.
Press PF8 (frwrd) to display the scroll region specifications (Map name, Scroll region, etc.) for the next panel.
The following example shows the fourth specification panel, the Related File Parameters panel:
CUOMMD Object-Maint-Dialog Program CUOMMD0
Jun 21 Related File Parameters 4 of 4
>> _1 Predict Relationships ........ ________________________________ *
View Generation Options
User generated ........... _ Use relationship name .... _
Predict generated ........ _
Generate from map on panel _
Relationship Processing
New object displayed ..... _
Control variable modified ___________________________________
Related File Processing
MOVE BY NAME to .......... ________________________________________
PERFORM subroutine ....... ________________________________
IF found ... _
IF not found _
IF null .... _
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
help retrn quit bkwrd frwrd left userX main |
Use this panel to retrieve additional panel information. Specify the Predict relationships that relate foreign keys within the object to other tables and then define how you want Natural Construct to process the specified relationship.
The fields on this panel are:
| Field | Description |
|---|---|
| Predict Relationships | Name of the first relationship. You can define
up to 10 relationships. After defining the first, press PF8 (frwrd) to display
the specification fields for the next relationship; press PF7 (bkwrd) to return
to the previous relationship. If you specify a relationship, the program
performs file lookups (joins) on the file related to the object file in
Predict.
In each relationship, the cardinality of the object file must be N or CN, while the cardinality of the related file must be 1 or C. The update constraint type must be R (restricted update) and the delete constraint type can be blank or R. Only type N (Natural Construct) relationships are processed. Note: |
| View Generation Options | If you specify a relationship in the
Predict relationships field, indicate which fields
in the related file are placed in the local view used to retrieve foreign file
information. Indicate one of the following view creation options:
|
| Relationship Processing | To specify when relationship processing is
performed by the generated program, indicate one or both of the following
processing options:
|
| MOVE BY NAME to | To copy the lookup data to another structure, specify the name of the structure. |
| PERFORM subroutine | To perform other processing for each file
lookup, specify the name of the subroutine in this field (the subroutine is
defined in the AFTER-LOOKUP-SUBROUTINE user exit) and mark one of the following
options:
|
Note:
If the object field defined by the relationship is within an array,
the control variable must be defined with an asterisk (*) notation on the map;
the occurrence that triggered the subroutine is given in the #I1
variable.
You can use the following variables with maps for object-maintenance programs or subprograms:
| Variable | Format | Definition | Description |
|---|---|---|---|
| #PROGRAM | A8 | Output | Name of the program that invoked the map. |
| #HEADER1 | A60 | Output | First heading for the program. |
| #HEADER2 | A58 | Output | Second heading for the program. |
| #LEFT- PROMPT | A9 | Output | For programs with more than one panel, this variable indicates the number of panels to the left of the current panel. If the current panel is the leftmost panel, this variable contains the current date. |
| #RIGHT- PROMPT | A9 | Output | For programs with more than one panel, this variable indicates the number of panels to the right of the current panel. If the current panel is the rightmost panel, this variable contains the current time. |
| #ACTION | A1 | Modifiable | Action applied to the current object occurrence. |
| #VAL-ACT | A18 | Output | List of available actions. |
| #DIRECT- COMMAND | A60 | Modifiable | Indicates support for direct command processing. |
| #HPARM | A65 | Output/Nondisplay | Key to Natural Construct’s passive help file for the current program (system name concatenated with program name). Place this variable on the map and pass it to the CD-HELPR helproutine. |
| #NEXT-ARRAY | P5 | Modifiable | Current panel number. Users can change the value in this field to reposition to the specified panel. This field is used for programs with more than one panel. |
| #ARRAY1 | N7 | Array Index | Index for fields in scroll region 1 that are scrolled by pressing PF7 (subtract lines-per-panel from #ARRAY1) or PF8 (add lines-per-panel to #ARRAY1). Also see #NEXT-ARRAY1. |
| #NEXT- ARRAY1 | P5 | Modifiable | Index of the first displayed occurrence of the fields in scroll region 1. Users can change the value in this field to reposition scroll region 1 to the specified panel number. This field is used for panels that support scroll region 1. |
| #ARRAY2 | N7 | Array Index | Similar to #ARRAY1, except it indexes the fields in scroll region 2. |
| #NEXT- ARRAY2 | P5 | Modifiable | Similar to #NEXT-ARRAY1, except it indexes scroll region 2. |
| #ARRAY3 | N7 | Array Index | Similar to #ARRAY1, except it indexes the fields in scroll region 3. |
| #NEXT- ARRAY3 | P5 | Modifiable | Similar to #NEXT-ARRAY1, except it indexes scroll region 3. |
| #ARRAY4 | N7 | Array Index | Similar to #ARRAY1, except it indexes the fields in scroll region 4. |
| #NEXT- ARRAY4 | P5 | Modifiable | Similar to #NEXT-ARRAY1, except it indexes scroll region 4. |
| #DEPTH | N7 | Array Index | Index for fields that are scrolled whenever the #NEXT-DEPTH value changes. By default, no PF-key is assigned to alter the value of #DEPTH. However, this can be achieved through user exit processing. |
| #NEXT- DEPTH | P3 | Modifiable | Indicates support for third-dimension scrolling. By default, this field indicates the current depth level. Users can change this value to reposition to a different depth level. |
| #LIN | P3 | Output | Single-dimension array containing sequential numbers (starting from 1). The occurrences of this array match the value of the highest upper bounds specified for any scroll region. This array can be placed on the panel whenever you want to show the current scroll index value beside a scroll region. |
| #KD-LINE1/
#KD-LINE2/ #KD-LINES(*) |
A79 | Output | Names of the available actions or alternate
PF-key display formats (supplied in CDDIALDA). Place them either at the top of
the map or at the bottom immediately above the standard PF-key lines.
To use the Push Button feature, include the #KD-LINES-CV control variable and the '00V(NP'02 dynamic attribute. To display the push buttons in red, use '00VRE(NP'02. The CDLAYOM2 layout map provides push button support. |
| #BKWRD-LAB1
#BKWRD-LAB2 #BKWRD-LAB3 #BKWRD-LAB4 #FRWRD-LAB1 #FRWRD-LAB2 #FRWRD-LAB3 #FRWRD-LAB4 |
A2 | Output | Enable backward/forward scrolling push buttons
(supplied in CDKEYLDA). Place them on the map(s) next to the fields where you
want to enable backward/forward scrolling.
Include reverse video display among the push button attributes. |
The following examples show the User Exits panel for the Object-Maint-Dialog model:
CSGSAMPL Natural Construct CSGSM0
Dec 19 User Exits 1 of 1
User Exit Exists Sample Required Conditional
-------------------------------- -------- ---------- -------- ------------
_ NAT-DOCS X
_ CHANGE-HISTORY Subprogram
_ PARAMETER-DATA Example X
_ LOCAL-DATA
_ START-OF-PROGRAM
_ BEFORE-INPUT
_ BEFORE-STANDARD-KEY-CHECK Example
_ AFTER-INPUT
_ AFTER-OBJECT-CALL Example
_ AFTER-GET Example
_ AFTER-SCREEN-CLEAR Example
_ END-OF-PROGRAM Example
_ SELECT-ADDITIONAL-ACTIONS Example
_ SET-PF-KEYS Example
_ ADD-ACTION-PROCESSING X
_ BROWSE-ACTION-PROCESSING X
_ BEFORE-BROWSE-CALLNAT X
_ AFTER-BROWSE-CALLNAT X
_ CLEAR-ACTION-PROCESSING X
_ DISPLAY-ACTION-PROCESSING X
_ MODIFY-ACTION-PROCESSING X
_ NEXT-ACTION-PROCESSING X
_ FORMER-ACTION-PROCESSING X
_ PURGE-ACTION-PROCESSING X
_ COPY-ACTION-PROCESSING X
_ ADDITIONAL-ACTIONS-PROCESSING
_ BEFORE-ET-PROCESSING Example
_ AFTER-ET-PROCESSING Example
_ REINPUT-SCREEN
_ AFTER-LOOKUP-SUBROUTINES Subprogram
_ MISCELLANEOUS-SUBROUTINES Example
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
frwrd help retrn quit bkwrd frwrd |
Notes:
The Object-Maint-Dialog-Subp model generates a dialog component (Natural subprogram) of a maintenance process, similar to the object-maintenance dialog program described in the preceding section. The only difference between the two is that the action in the object-maintenance dialog subprogram is controlled by the calling program.
A browse-select program, for example, can call an object-maintenance dialog subprogram and pass it the #ACTION parameter (specifying the action to be performed). When this happens, certain attributes on the map used by the object-maintenance dialog subprogram are modified by two control variables the model generates. These variables define the display attributes of the map, according to the #ACTION parameter:
| #ACTION Parameter | Control Variable | Attribute |
|---|---|---|
| Display, Purge | #KEY-CV
#SCR-CV |
Locked
Locked |
| Modify | #KEY-CV
#SCR-CV |
Locked
Open |
| Add, Copy | #KEY-CV
#SCR-CV |
Open
Open |
The control variables generated by the Object-Maint-Dialog-Subp model are:
| Variable | Associated With |
|---|---|
| #KEY-CV | Key fields for the object data used on maps. |
| #SCR-CV | All other fields for the object data used on maps. |
| #PROTECT-CV | Action field. Since programs generated with the Object-Maint-Dialog and Object-Maint-Dialog-Subp models generally use the same map, this control variable protects the Action field for the subprogram. |
The following example shows a generated object-maintenance dialog subprogram:
NCOSELN ***** ORDER SUBSYSTEM ***** NCOSEM11
May 30 - MAINTAIN ORDER ENTRIES - 1 more >
*Action (A,D,M,P,C): D Order Number: 90008_
*Customer Number....: 22222 KENT VETERINARY CLINIC
*Warehouse ID.......: 638 WATERLOO WAREHOUSING LTD.
Invoice Number.....: 333331
Order Date.........: 13/10/21 Order Amount: 229898.50
1_ ----- Product Information ------ 1_ -- Distribution Information --
1 *Product....: 333333 Account Amount
Quantity...: 500______ 1 676767676 3233.00_____
Cost/Unit..: 50.00 2 676767678 90.00_______
Total......: 25000.00 3 989898989 80.00_______
Description: OATS AND BARLEY CE 4 789078900 89.00_______
1_ Delivery Instructions (Scroll right for full screen)
1 TO BE DELIVERED TO SHIPPING/RECEIVING IF BEFORE 5:00 PM,
2 ELSE TO NIGHT DROP-OFF.SSS
Direct Command: _________________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF
help retrn quit flip bkwrd frwrd left right ma
Order 90008 displayed successfully. |
This section covers the following topics:
Note:
To see the specifications for this example, refer to the NCOSELN
subprogram in the Natural Construct demo
system.
The specification panels for the Object-Maint-Dialog-Subp model are similar to the panels for the Object-Maint-Dialog model, with one exception. The Additional Parameters panel for the Object-Maint-Dialog-Subp model contains the Multiple action support field. If this field is specified, the generated subprogram allows users to perform multiple actions in succession.
Note:
For information about the parameters on these panels, see
Parameters for the
Object-Maint-Dialog Model.
The User Exits panels for the Object-Maint-Dialog-Subp model are identical to the User Exits panels for the Object-Maint-Dialog model. For information about these panels, see User Exits for the Object-Maint-Dialog Model.