Natural Basics Class

University of Arkansas, Fayetteville
Computing Services
W. David Wimberly

January 1992


Table of Contents


Introduction


Day 1


Day 2


Day 3


Day 4 and 5


Day 6


Figures

  1. ADACMP control statements defining file EMPLOYEES
  2. Natural program used to generate Adabas buffers
  3. User control block
  4. Adabas format buffer
  5. Adabas record buffer
  6. Adabas search buffer
  7. Adabas value buffer
  8. EMPLOYEES Data Definition Module
  9. UAF's PDB7004 dictionary report
  10. Sample cross-reference report
  11. Data Area Editor screen
  12. PGMORDER from UAEXPG

Introduction

The Natural Basics Class is intended to provide the necessary training for an individual to begin to develop simple Natural programs. These programs would be for the purpose of data access and reporting. An advanced class is available and required for individuals that will be designing applications and developing data maintenance programs.

Class topics

The following topics are covered in the Basic's class:

This class does not address Natural ISPF, Natural Process, Adabas TPF, or Natural OS/2.

Prerequisites

Individuals attending this class should meet the following prerequisites:

Materials

In order to participate in the class and use Natural on an ongoing basis, attendees will also need the following:

The handouts

These class handouts are provided as an outline of the material to be covered and a supplement to the Natural Reference Manual. The intent is to provide insight and perspective to the product and its application at the university, which cannot be easily gleaned from the manual. An effort has been made not to repeat information that is available in the Reference Manual. The handouts must be used in conjunction with the reference manual, which provides the most detail description and syntax for commands and statements. The handouts do not cover all commands, statements or options, but only those thought to be most useful.

Format

The January 1992 class will meet each morning for six days in room 118. The six PCs will use TELNET to access the A System where they will execute a common session using CVIEW. Each PC will "see" what is displayed on the other five and any PC may be used for input. In this manner the instructor and the class participants will interact with Natural. The class is intended to be interactive with questions and discussion encouraged. Assignments will be made for work to be completed out of class and discussed in the following session. Plan to demonstrate to the class your solutions to the assignments.


Day 1

The first day of the Natural Basics Class will not address Natural directly, but will build a foundation for understanding Natural. The general topics covered include:


UAF's A/Z-System Environment

The first step toward using Natural is to understand the operational environment in which it is available. Natural is only available on the Z-System and only executes there under IBM's MVS operating system.


MVS

MVS is IBM's primary operating system for the business community. There are several versions of this operating system available, with the university currently running MVS/SP. MVS is primarily a batch operating system, designed to execute programs from start to finish in an unattended mode with all inputs previously defined. MVS supports multi-tasking, multiple programs executing concurrently, and multi-processing, multiple program instructions executing concurrently. The administrative MVS/SP system operates on UAFSYSZ underneath IBM's VM (Virtual Machine) operating system with the ID UAFMVS1. (It is entirely possible to have multiple MVSes operating beneath VM and each would need a unique name.)

The VM operating system provides many advantages, some of which are the ability to define virtual devices to MVS. In this manner, MVS programs can think physical devices such as printers, card readers, and terminals are attached when they are not. It also allows a great deal of flexibility in attaching real devices such as disks and tape drives. These virtual devices are the primary means used to interface with MVS: jobs are initiated by sending JCL to the MVS virtual reader, reports are printed by routing MVS virtual print to the VM printer, and online access is provided by dialing in to virtual MVS ports.

MVS programs are executed within jobs, a collection of programs executed in sequence to perform some common purpose. IBM's Job Control Language, JCL, is used to define and control the execution of these programs as well as to define the inputs and outputs used by the programs being executed.

One component of MVS that is commonly referenced is VSAM, the Virtual Storage Access Method. This is an IBM product that provides file and record management facilities. It is the replacement for ISAM and is often used to perform data base type management functions. VSAM is heavily integrated into the MVS/SP operating system and is a required component. It is no real competitor to Adabas, but since it is an IBM standard it is widely used. Several of the university's packaged applications use VSAM as their file access method, most significantly the MSA systems.


CICS

IBM's Customer Information Control System, CICS, has evolved as the primary facility used to provide online terminal communication, or teleprocessing, with MVS. CICS is like a big kludge since MVS was originally designed as, or at least evolved from, a batch operating system. Its size and complexity is tremendous. CICS is used to provide timesharing like facilities for interactive transaction processing.

CICS is really just one program that executes as one step of a batch job. Rather than running start to finish and then stopping however, it continues to execute until instructed to shutdown via operator commands. In this manner, it is always there and waiting for anyone wanting to use one of its applications. To gain access, users DIAL to access one of the terminal communication ports assigned to CICS. CICS then takes over and requires authorization for the access by an ID/password signon procedure. This ID further defines what applications a user can access within CICS.

Applications must be written explicitly for CICS and must conform to many rules and regulations laid down by CICS. In turn CICS: controls user access to the application, performs multi-tasking (similar to MVS) allowing multiple users to execute concurrently, manages storage such that the application programs needed for each user are loaded to memory when needed, and performs all VSAM file accesses and updates. Some of our CICS applications are MSA, LMS, and SAFARI. We are in the process of migrating the execution of Natural from CICS to Adabas HPE/TPF. Three CICS jobs are normally executing within MVS: CICSPROD where production applications reside, CICSTEST/CICSTST1 where applications are developed and tested with test data. CICSTEST and CICSTST1 share processing responsibilities for our test systems and communicate with each other via IBM's Multiple Region Option (MRO). In the future we may have to go to two production CICS regions as well.

Note: CICS is an extremely large and complex product and this description provides only a very high level introduction.


ADABAS

Adabas is a data base management system. It provides facilities for efficiently storing, updating, deleting and retrieving large volumes of data. These services are provided to other programs on a request basis. Adabas, like CICS, is executed as one step of an MVS batch job. Once started, it continues to run until instructed to shut down. It idly sits and waits for requests to access or update data within the files that have been defined to it.

Adabas also provides multi-tasking, the ability to service many requests for data concurrently. Communication between application programs and Adabas is via a special SVC, Supervisor Call, that is installed within MVS. Each call contains a great deal of information describing what service is desired. The specific service is identified by an Adabas command Id. After processing the command, Adabas returns via the SVC a return code and other information as appropriate. One measure of how much work Adabas is being asked to do can be obtained by merely looking at the number of Adabas commands processed. Traditionally we have had two ADABAS jobs executing within MVS: ADAPROD where production files reside and ADATEST for test data. Recently we have begun migrating ADATEST to execute under Adabas HPE. Eventually we hope to run both ADAPROD and ADATEST under Adabas HPE.


Adabas HPE/TPF

Two relatively new products the university has acquired are Adabas HPE and Adabas TPF. HPE stands for High Performance Environment while TPF stands for Transaction Processing Facility. HPE merely provides an environment (one region) for Adabas and Natural (executing under TPF) to execute. This provides significant performance advantages because the cross-memory services operations typically required for the application (Natural) to communicate with the data base (Adabas) create a great deal of overhead. These are not required when both components are operating within the same address space. TPF also provides a more efficient multi-tasking environment for Natural to execute in over CICS. A small communication link is left in CICS where screen handling is still performed, but the execution of Natural programs and all data base activity can now take place under HPE.


Natural ISPF/Process

Natural ISPF and Natural Process are additional products that are provided by Software AG. Their use is not covered in this class. They are mentioned here to provide a complete description of our "Natural" environment. Natural process is a set of hooks into the MVS operating system that allow access to and alteration of components that normally would not be possible via CICS or TPF. This includes sequential files, partion data sets, job queues, and other parts of MVS. These are made available to Natural programs as VIEWS similar to the way data base files are accessed. Natural ISPF is an alternate Natural development and execution environment which makes use of Natural Process. It offers a TSO like editor, multiple session manager, macro generation facility, a workpool where sequential output can be directed, and data management functions similar to those available under TSO ISPF.


Batch jobs

There are many tasks that cannot be performed online through CICS and there are many that are better not executed online. Some CICS/TPF restrictions (without Natural Process) include their inability to access sequential data sets, to print directly to VM printers, to sort large files, to execute large programs and to execute system utilities. On the other hand, there are many tasks which do not require an online terminal and are best executed unattended at a scheduled time. Programs with these requirements are executed in batch MVS using JCL to control their execution. These jobs are the ones typically being referred to in discussions regarding MVS batch.

Computing Services manages the Z-system resources with the following priority scheme:

Business Days 8am - 5pm

  1. Production online
  2. Development and testing online
  3. Essential batch production
  4. Development and testing batch
  5. Other batch production

Non-prime shifts, week-ends and holidays

  1. Batch production
  2. All online
  3. Development and testing batch

Given this philosophy, mass update functions, data extracts, and reports are encouraged to be performed in batch during non-prime hours, preferably on a scheduled basis. All require a batch job and JCL to control that execution. Operations can then control the execution of these jobs and thus balance the system load, which is not possible with online access.


VM/CMS

IBM's VM is the primary operating system for the A and Z systems. Several tasks run under VM in addition to MVS. The university provides a very general purpose online access to the A-system though CMS, IBM's Conversational Monitor System. This is a time sharing system where each CMS user appears to have an entire computer available, again through the use of virtual devices such as card readers, printers, and disks.

CMS is currently used primarily for e-mail, file management, and a primary interface with MVS for applications developers. It is not used as the platform for executing administrative applications since its file sharing capabilities are hampered by the independent view of the world offered each user. Natural developers use CMS to prepare batch job inputs, setup JCL, and to review batch job output produced by MVS.

Online access to UAFMVS1 on the Z system is via VM on the A system. All communication connections and software necessary for online access is attached to the A system. From the VM logon screen users are required to invoke a VTAM (Virtual Terminal Access Method) session which communicates via a channel to channel adapter to VTAM on the Z system and then to UAFMVS1.


Terminal access

All online access to the A-system uses IBM's 3270 type terminal communication protocol. This protocol employs a block mode, screen transfer of data to and from the host. Input is sent to the system by pressing a program attention key, either ENTER, PF1-24, Clear, or PA1-3. No further input can be made until the A-system responds with a new screen display and the keyboard is unlocked.

Screens are composed of fields of various lengths and each field is preceded by an attribute byte or character that describes the characteristics of that field. At a minimum each field can be protected (no data can be entered into the field) or un-protected (data may be entered at that location). Additionally fields may appear in the default intensity or they may displayed intensified (bright). Variations of 3270 terminals also allow other field characteristics such as color, reverse video, blinking, etc.

The university supports two forms of 3270 access to the A/Z-system: Network TCP/IP access via PCs or Macintoshes executing TELNET 3270 terminal emulation software and Lee Data terminals or PCs equiped with Lee Data communication boards. FTP Corporation's TELNET is available and normally used for CICS access from PCs. FTP's product offers many features including: the ability to assign different colors to fields according to their protection status and intensity, the ability to alter the background color for fields, and remapping of the default PC keyboard to 3270 key assignments. Lee Data terminals are very fast and designed as 3270 replacements so keyboards are designed for that purpose. PCs with Lee Data communication boards use fixed PC keyboard to 3270 assignments. You should spend the necessary time to become familiar with your terminal configuration and operation so that you can work effectively on the mainframe.


ADABAS

Adabas is one of several products the university has purchased from Software AG. Natural and Predict are two other primary products that are also provided by this company. The acronym ADABAS stands for "the Adaptable DAta BAse System". ADABAS is not required to use Natural, but at our installation it is a key and critical component which should be understood. This is because with business applications the input and output processing is the bottleneck and not CPU time. Therefore, to use Natural effectively you must use Adabas effectively. This translates to efficiently in most cases. This discussion will examine how Adabas works so that efficiency considerations can be understood and applied in application design.


Overview

This section includes definitions for many terms that are used with ADABAS and Natural. Some of these differ from those used by other data base management systems and can therefore make learning Adabas difficult if not properly understood. The following discussion uses these terms to describe relationships that exists between many of the components of ADABAS.

The university has two Adabas data bases, each identified by a unique DBID (data base ID or number): ADATEST is #1 and ADAPROD is #6. Each data base can manage data for 255 separate files. Each file may contain up to 16.7 million records with each record containing up to 500 predefined fields of information. Each record of an Adabas file is assigned an ISN, or Internal Sequence Number, that uniquely identifies that record to Adabas.

Adabas is a field oriented data base. All accesses to Adabas must be accompanied by a list of the fields on which the requested action is to be performed. Records created without specified values for all fields will have a null value assigned to those fields. All Adabas records are compressed according to field compression options and stored in this compressed format. In this manner, new fields can be added to an existing file without affecting programs currently in use and without restructuring the data.

Several other attributes are required to be defined for each field. The most significant is the format and length which defines the type of data that will be stored and its maximum size/precision. There are also two special field types that make Adabas non-relational but provide unique features. These are MUs and PEs. An MU is a multiple occuring field which may have from 0 to 191 values or occurrences per record. A PE is a periodic group field which defines a group of fields which may have from 0 to 99 occurrences.

Random access to records contained within Adabas files is provided by ISN or by indexes, known to Adabas as descriptors. Each file may have many descriptors, which may be created or deleted at any time without affecting the base file (no unload/reload required). Descriptors may be defined as unique, in which case Adabas will not allow an add or update if it would result in the same descriptor value on two records. Descriptor values are stored in an inverted list along with a count of the number of records that contain that value and the ISNs of those records. If a descriptor is derived from a field contained within a periodic group, then the inverted list also contains the PE occurrence within the record that contains that value (the same descriptor value may then be present in the inverted list many times, once for each different PE occurrence).


The FDT

Adabas maintains information about each file within its file description table or FDT, maintained as part of the data base. The FDT is built as a result of the data compression and load utilities which are used to initially define a file and load data. The control statements for the ADACMP program provide the information for the FDT and contain attribute definitions for the fields contained within the file. Figure 1 contains the control statements used to define the EMPLOYEES demonstration file provided by Software AG. This file will be used throughout the class.

Figure 1. ADACMP control statements defining file EMPLOYEES


ADACMP COMPRESS
ADACMP FILE=030
ADACMP FNDEF='01,AA,8,A,DE'                  PERSONNEL-ID
ADACMP FNDEF='01,AB'                         FULL-NAME
ADACMP FNDEF='02,AC,20,A,NU'                 FIRST-NAME
ADACMP FNDEF='02,AE,20,A,DE'                 NAME
ADACMP FNDEF='01,AD,20,A,NU'                 MIDDLE-NAME
ADACMP FNDEF='01,AF,1,A,FI'                  MAR-STAT
ADACMP FNDEF='01,AG,1,A,FI'                  SEX
ADACMP FNDEF='01,AH,6,U,DE'                  BIRTH
ADACMP FNDEF='01,A1'                         FULL-ADDRESS
ADACMP FNDEF='02,AI,20,A,NU,MU'              ADDRESS-LINE
ADACMP FNDEF='02,AJ,20,A,DE,NU'              CITY
ADACMP FNDEF='02,AK,10,A,NU'                 ZIP
ADACMP FNDEF='02,AL,3,A,NU'                  COUNTRY
ADACMP FNDEF='01,A2'                         TELEPHONE
ADACMP FNDEF='02,AN,6,A,NU'                  AREA-CODE
ADACMP FNDEF='02,AM,15,A,NU'                 PHONE
ADACMP FNDEF='01,AO,6,A,DE'                  DEPT
ADACMP FNDEF='01,AP,25,A,DE,NU'              JOB-TITLE
ADACMP FNDEF='01,AQ,PE'                      INCOME
ADACMP FNDEF='02,AR,3,A,NU'                  CURR-CODE
ADACMP FNDEF='02,AS,5,P,NU'                  SALARY
ADACMP FNDEF='02,AT,5,P,NU,MU'               BONUS
ADACMP FNDEF='01,A3'                         LEAVE-DATA
ADACMP FNDEF='02,AU,2,U'                     LEAVE-DUE
ADACMP FNDEF='02,AV,2,U,NU'                  LEAVE-TAKEN
ADACMP FNDEF='01,AW,PE'                      LEAVE-BOOKED
ADACMP FNDEF='02,AX,6,U,NU'                  LEAVE-START
ADACMP FNDEF='02,AY,6,U,NU'                  LEAVE-END
ADACMP FNDEF='01,AZ,3,A,DE,NU,MU'            LANG
ADACMP PHONDE='PH(AE)'                       PHONETIC-NAME
ADACMP SUPDE='H1=AU(1,2),AV(1,2)'            LEAVE-LEFT
ADACMP SUBDE='S1=AO(1,4)'                    DEPARTMENT
ADACMP SUPDE='S2=AO(1,6),AE(1,20)'           DEPT-PERSON
ADACMP SUPDE='S3=AR(1,3),AS(1,9)'            CURRENCY-SALARY

These control statements are very cryptic as is all direct communication with Adabas, thank goodness for Natural. The FNDEF parameters used with ADACMP define the following field attributes:

Level

The level number is used for field grouping. Fields with a level number of 2 or greater are considered part of the immediately preceding group. This technique is used to define the periodic groups previously mentioned and basic group fields (FULL-NAME is an example). A group field can be used to reference a series of consecutive fields. The basic group fields are not used when accessing Adabas from Natural and impose limitations for adding new fields (fields cannot be added to a group without unloading a file, reformating the data, and reloading). For these reasons the use of group fields, other than PEs, is discouraged.

Name

All fields are known to Adabas by a two character name. Fortunately Natural provides a separate view of Adabas files that permits the use of 32 character field names. The Adabas name for the first field in the EMPLOYEES file is AA (the meaningful name PERSONNEL-ID to the right is only a comment).

Length

Identifies the standard length of the field in bytes. Adabas may actually store a compressed field smaller or larger than this length. Fortunately Natural does not allow creating field values larger than their standard length.

Format

The possible field formats, or data types, and the maximum length allowed for each is:

A Alphanumeric, 253 bytes
B Binary, 126 bytes
F Fixed point or integer, always 4 bytes
G Floating point, either 4 or 8 bytes
P Packed decimal, 15 bytes
U Unpacked decimal or zoned numeric, 29 bytes

Options

The following are definition options that may be specified for Adabas fields.

DE Identifies the field as a descriptor or indexed field.
UQ Identifies the field as a unique descriptor.
FI Specifies that the field should not be compressed but will always be stored with its standard length. This is useful for 1 and 2 byte fields and fields which always have a full length value. It should not be used for MU fields or fields contained within PE groups.
NU Indicates that null values for the field are to be suppressed. This allows for improved compression but also means that no descriptor value will be created when the field value is null. See "Adabas data compression" for additional information.
MU Indicates that this is a multiple value field. AI, ADDRESS-LINE, is an example.
PE Identifies the group name and the start of a periodic group. Field AW, LEAVE-BOOKED, is an example of a PE group field.

Other ADACMP parameters are used to define special types of fields and descriptors, which are always derived from previously defined fields. These are normally listed last and include:

HYPDE

Hyper-Descriptor: a very special type of index whose type and index values are determined by the user. Hyper-descriptors require a user written algorithm be coded in assembly language and this subroutine linked into Adabas.

PHONDE

Phonetic descriptor: a special index built from alphabetic fields to allow the selection of records which contain similar phonetic values. Phonetic descriptors are not allowed on PE group elements.

SUBDE

Subdescriptor: an index built from a subset of another field.

SUBFN

Subfield: a portion or subset of another field that can be read as a normal field. Subfields are not permitted when adding or updating records.

SUPDE

Superdescriptor, a descriptor built from several other fields, either in part or in total. A maximum of five fields may be used to construct a superdescriptor.

SUPFN

Superfield, a field composed of several fields, portions of fields, or combinations thereof which may be read as a normal field. Like subfields, superfields are not permitted when adding or updating records.

The ADACMP control statements used to define a file do not have to be coded manually. The Predict data dictionary is used to define all of the Adabas files used at the university and provides a utility to generate the ADACMP definitions. The field names appearing on the right of Figure 1 are comments which were placed there by Predict.


Adabas datasets

Adabas manages the data, indexes and control information for its files using standard MVS, or OS, datasets. The following three physical datasets are used by each Adabas data base.

  1. Data Storage

    This file contains all the data records for the Adabas files managed by an Adabas data base. The file is physically organized by data blocks, each of a predefined fixed size (ours are 4820 bytes). Each data block contains data records for one or more records of a given Adabas file. The data blocks are not required to be in any particular sequence or order. Generally though, since space is usually allocated and data loaded in one step, data blocks tend to be grouped by file with data records occuring in the sequence they were loaded.

  2. Associator

    The associator contains the information required to access records in the data base. This includes the FDTs, space management tables, the address converter for each file and the inverted list for each descriptor. The address converter is a key factor in Adabas's efficiency and flexibility (perhaps we should say adaptability). It maps a logical record address, the ISN, to a physical record address, the data block which contains that ISN. This scheme allows data records to be moved between blocks (required when a record expands and there is not room in the current block) with only the address converter having to be updated, not every descriptor that points to the record.

  3. Work

    The work data set is just that, space available for temporary use by Adabas. Some commands require extensive use of the work data set and are therefore more resource intensive, they cause Adabas to do more I/O which may affect all users.

A subset of records and fields from the EMPLOYEES file, as they might appear in data storage are shown in Table 1. The address converter for these records would appear as shown in Table 2. The inverted list for NAME is Table 3 and the inverted list for DEPARTMENT (a subdescriptor of DEPT) is Table 4.

Table 1. Data storage for EMPLOYEES

Data Block ISN PERSONNEL ID FIRST-NAME NAME DEPT BIRTH
234 1 11400316 WILLI BEUSE MARK29 390509
2 11400314 ERHARD BECKER SALE47 540707
13 11300307 JAN TAMELING SALE37 590328
235 4 11400312 INGRID SCHMID MARK19 540308
5 11400310 MARGARETHE GROTH MARK29 540623
6 11400307 JOSEFA LEYRER COMP28 410407
236 7 11400304 MARIAN RACKMANN COMP28 541209
9 11300319 SULEYMAN YALCIN SALE37 580819





237 10 11300316 GABRIELE KANTE SALE47 540809
11 11300315 GUDRUN FRIESE SALE37 560504
12 11300314 GITTA MOHRDIEK SALE17 390912
298 8 11400303 MARTIN WALLINGER COMP28 460921












Table 2. Address converter for EMPLOYEES

ISN Index (not stored) Data Block
1 234
2 234
3 ^
4 235
5 235
6 235
7 236
8 298
9 236
10 237
11 237
12 237
13 234

Table 3. NAME inverted list

NAME Record Count ISNs
BECKER 1 2
BEUSE 1 1
FRIESE 1 11
GROTH 1 5
KANTE 1 10
LEYRER 1 6
MOHRDIEK 1 12
RACKMANN 1 7
SCHMID 1 4
TAMELING 1 13
WALLINGER 1 8
YALCIN 1 9


Table 4. DEPARTMENT inverted list

DEPARTMENT Record Count ISNs
COMP 3 6,7,8
MARK 3 1,4,5
SALE 6 2,9,10,11,12,13

Adabas data compression

Adabas stores all data records in a compressed format as a variable length string of bytes. This compression is transparent to the user since Adabas automatically compresses the data coming in and uncompresses it going out. Generally the physical representation of the compressed data does not need be known and only a brief description is provided here.

The first two fields stored for each data record are its length and its ISN. The remaining fields are organized in the sequence specified in the FDT with the compression option specified there. Fixed length fields occupy the length specified and should generally be used for fields of only 1 or 2 bytes. Compressed fields are always preceded by the length of the field. There are two options available for compressed fields. Fields defined with the default compression option will always require at least two bytes, one for the length and one for a value even if null. Null suppressed fields are represented by a special null value indicator when they are null and consecutive null values are represented by an empty field count. No storage is used for null values that occur at the end of the record. In this manner a string of null values can be stored using very little space. The following steps are taken to compress values:

  1. Trailing spaces are removed from alphanumeric fields
  2. Leading zeroes are removed from numeric and packed fields
  3. Numeric fields are converted to packed decimal
One more important point is that null values of null suppressed fields are not placed in the inverted list.

MU fields and PE goups are always preceded by an occurrence count which identifies how many occurrences of the field or group of fields is present. MU fields and fields contained within a periodic group should almost always be defined as null suppressed. Adabas will always squeeze out null value occurrences of an MU by rolling up values in later occurrences. It also reduces the occurrence count for the MU. However the same is not true for PEs. If all field values within a PE occurrence are null and you wish to move subsequent occurrences up to fill in, this task must be done manually by the programmer and the record updated. This is commonly referred to as positionality, which is maintained for PEs but not for MUs.

The compressed size of a data record cannot exceed the blocksize of data storage. The uncompressed size of a data record is limited to 10,000 bytes.


Adabas data access commands

Adabas data is accessed by requesting the data base to execute or service an Adabas command. All Adabas commands are internally represented by two character codes, but have common names by which they are discussed below. All commands except the GET may be executed repeatedly to sequentially process individual data base records. A separate call is made for each command with Adabas remembering where it was within the file and returning a special code when the end of file or ending search criteria is reached.

Read physical

Read physical is Adabas command L2. It accesses records in the order that they physically occur within data storage. This is the most efficient way to access all data records since it does not require access to indexes or to the address converter.

Read logical

The read logical or read by descriptor is Adabas command L3. It is used to read a file in logical sequential order based on the ascending sequence of the value for a given descriptor. Access is required to the inverted list, then to the address converter, and then to data storage. A starting search value may be specified, in which case reading begins with that or the next greater descriptor value on the inverted list.

The read logical is a very useful command. It can be used to select specific records and to process records in sequence of the descriptor, acting as a "free sort". This command cannot be used on phonetic descriptors or descriptors contained within, or derived from a field within, a periodic group.

Get ISN

The Get ISN is Adabas command L1, which is used to read a single record from data storage by providing its ISN. This is the most efficient and direct way to access a single record. Access is made to the address converter and to data storage. Unfortunately it is not common to know the ISN of the record desired.

Note: There is a Natural program statement READ BY ISN which is implemented using a special option of the Adabas L1 command. It is used to access records sequentially in ISN sequence. A starting ISN may be specified and that record or the record with the next higher ISN is returned. The read can be terminated at any time.

Find

The find, Adabas command S1, creates a list of ISNs for the records which satisfy a given search criteria. The search criteria may be constructed using a single descriptor or several descriptors connected by logical operators. Adabas resolves the query by using the inverted lists, no access to data storage is required. The find also returns the number of records that met the criteria (the number of ISNs in the list). The list of ISNs meeting the criteria is almost always written to Adabas's work data set, which may also be used to resolve the query. Complex Finds can be very resource intensive since they may tie up Adabas for extended times while it is resolving the query.

Note: The Natural FIND NUMBER statement is equivalent to the Adabas S1 command while the FIND statement has a special extension. The Natural FIND takes the ISN list created and uses the L1 command with the GET NEXT option to sequentially retrieve those records. Since the ISN list is always in ISN sequence, so are the records returned.

Histogram

The Histogram is Adabas command L9 which is used to read descriptor values. It also provides a count of the number of records which contain that value. Like the read logical, a starting search value may be specified and processing begins with the first descriptor value equal to or greater than the search value. Values are returned in ascending sequence. The histogram is very efficient since it only requires access to the inverted list. The histogram is commonly misunderstood and generally under-utilized.


Interface to Adabas

All application programs interact with Adabas via a call sequence. Each Adabas call is accompanied by parameter areas used to communicate the intended request to Adabas and to pass the results back from Adabas. A brief statement about the most common of these control areas (buffers) follow. Samples of each area are included and were generated by the Natural program shown in Figure 2.

Figure 2. Natural program used to generate Adabas buffers


************************************************************************
* Program:  READEMPS
* Author :  W. David Wimberly
* Written:  12-20-91
* Updated:  mm-dd-yy, person & change description
*
* Remarks:  Describe purpose and use of the program.
*
************************************************************************
*
DEFINE DATA LOCAL
1 E-V VIEW OF EMPLOYEES
  2 PERSONNEL-ID
  2 FIRST-NAME
  2 MIDDLE-I
  2 MIDDLE-NAME
  2 NAME
END-DEFINE
*
READ (5) E-V BY PERSONNEL-ID = '1000000000'
  DISPLAY PERSONNEL-ID FIRST-NAME MIDDLE-I NAME
END-READ
END

User Control Block

The user control block, also refered to as the Adabas control block, contains the most basic information about the request. Some of the fields passed here include: the Adabas command to be processed, the file number to be operated on, Adabas's response (return) code, an optional ISN, and lengths of other buffers used with the call. Figure 3provides an example of this buffer.

Figure 3. User control block


 10:55:53                  *****  A D A L O G  *****                    20/12/91
                              - Snapshot Report -
 
        0 C1D5D3F302200101011E00000000034E00000000 *ANL3??????    ?+    *
       20 00000000002D0045000C000A0000C8E5C1C1BBCA *     ?   ? ?  HVAA  *
       40 4040404000620045000000000000000000000000 *     ß             *
       60 000000000000000000000000000003B100000000 *              ?     *
       80 4040404040404040404040404040404040404040 *                    *
      100 4040404040404040404040404040404040404040 *                    *
      120 4040404040404040404040404040404040404040 *                    *
      140 4040404040404040404040404040404040404040 *                    *
      160 4040404040404040404040404040404040404040 *                    *
 
 Command Code : L3           Command ID  : ????         File Number  : 011E
 Response Code: 0000         ISN         : 0000034E     ISN Low Limit: 00000000
 FB Length    : 002D         RB Length   : 0045         SB Length    : 000C
 VB Length    : 000A         IB Length   : 0000         Com. Option 1: H
 Com. Option 2: V            Additions 1 : AA           Additions 2  :  ß 
 Additions 3  :              Additions 4 :              Command Time : 000003B1

Format Buffer

The format buffer contains a list of the fields, with their format and length, that are being input or output with the call. The actual field values will be contained in the Record Buffer but the format buffer provides the layout of how those values are formatted and what fields are present. Adabas will only operate on the fields specified in the format buffer and doesn't worry about other fields present in the record. This is yet another key to Adabas's flexibility/adaptability. Figure 4provides an example of this buffer.

Figure 4. Adabas format buffer


 10:55:53                  *****  A D A L O G  *****                    20/12/91
                              - Snapshot Report -
 
        0 C1C16BF0F0F86BC16BC1C36BF0F2F06BC16BC1C4 *AA,008,A,AC,020,A,AD*
       20 6BF0F0F16BC16BC1C46BF0F2F06BC16BC1C56BF0 *,001,A,AD,020,A,AE,0*
       40 F2F06BC14B404040404040404040404040404040 *20,A.               *
       60 4040404040404040404040404040404040404040 *                    *
       80 4040404040404040404040404040404040404040 *                    *
      100 4040404040404040404040404040404040404040 *                    *
      120 4040404040404040404040404040404040404040 *                    *
      140 4040404040404040404040404040404040404040 *                    *
      160 4040404040404040404040404040404040404040 *                    *

Record Buffer

The record buffer contains the data values used with the command, these are input values for a store or update and output values returned by Adabas with data access commands. The contents of the record buffer must correspond with the layout provided in the format buffer. Figure 5provides an example of this buffer.

Figure 5. Adabas record buffer


 10:55:53                  *****  A D A L O G  *****                    20/12/91
                              - Snapshot Report -
 
        0 F1F0F0F0F0F0F0F1E68993938981944040404040 *10000001William     *
       20 4040404040404040C4C481A58984404040404040 *        DDavid      *
       40 404040404040404040E6899482859993A8404040 *         Wimberly   *
       60 4040404040404040404040404040404040404040 *                    *
       80 4040404040404040404040404040404040404040 *                    *
      100 4040404040404040404040404040404040404040 *                    *
      120 4040404040404040404040404040404040404040 *                    *
      140 4040404040404040404040404040404040404040 *                    *
      160 4040404040404040404040404040404040404040 *                    *

Search Buffer

The search buffer specifies the fields, and their format and length, that are to be used as the search criteria with a read logical, histogram or find command. The search buffer for the find command can be very complex since it can also contain AND/OR logic and value ranges. The fields specified in the search buffer provide the layout to how the Value Buffer is formatted. Figure 6provides an example of this buffer.

Figure 6. Adabas search buffer


 10:55:53                  *****  A D A L O G  *****                    20/12/91
                              - Snapshot Report -
 
        0 C1C140406BF0F1F06BC16B4B4040404040404040 *AA  ,010,A,.        *
       20 4040404040404040404040404040404040404040 *                    *
       40 4040404040404040404040404040404040404040 *                    *
       60 4040404040404040404040404040404040404040 *                    *
       80 4040404040404040404040404040404040404040 *                    *
      100 4040404040404040404040404040404040404040 *                    *
      120 4040404040404040404040404040404040404040 *                    *
      140 4040404040404040404040404040404040404040 *                    *
      160 4040404040404040404040404040404040404040 *                    *

Value Buffer

The value buffer contains the values for the fields specified in the search buffer. The value buffer has a similar relationship to the search buffer as the record buffer does to the format buffer. Figure 7provides an example of this buffer.

Figure 7. Adabas value buffer


 10:55:53                  *****  A D A L O G  *****                    20/12/91
                              - Snapshot Report -
 
        0 F1F0F0F0F0F0F0F0F0F040404040404040404040 *1000000000          *
       20 4040404040404040404040404040404040404040 *                    *
       40 4040404040404040404040404040404040404040 *                    *
       60 4040404040404040404040404040404040404040 *                    *
       80 4040404040404040404040404040404040404040 *                    *
      100 4040404040404040404040404040404040404040 *                    *
      120 4040404040404040404040404040404040404040 *                    *
      140 4040404040404040404040404040404040404040 *                    *
      160 4040404040404040404040404040404040404040 *                    *


Adabas utilities

There are numerous Adabas utilities that are used by the Data Base Administrator to manage the data base. These utilities are not available to application developers and should never be used without guidance and supervision by the DBA. They are mentioned here to provide a thorough understanding of Adabas and its operation.

ADACMP

Compresses and decompresses files for Adabas.

ADADBS

Performs many miscellaneous functions such as space management, adding and deleting files, emptying files, releasing descriptors, etc.

ADADCK

Validates the lengths of records in data storage.

ADAINV

Used to create the inverted list for a new descriptor.

ADALOD

Loads compressed records to a file and may also be used to mass update or delete records.

ADAORD

Reorders or restructures data base space.

ADAREP

Provides status and detail reports regarding the data base.

ADARES

Provides data base restart facilities to be used following system failure.

ADASAV

Used to save and restore individual file or data base components.

ADAICK

Checks the internal index structure, the address converter and the inverted list for consistency.

ADAVAL

Validates that data storage is consistent with the descriptor values in the inverted list.


Further reading

This is only a brief summary of the information available about Adabas. Most of the reference material available is very detailed, but may be of further use. Additional Adabas reference material includes: Adabas 5 Concepts and Facilities, Adabas 4 Concepts and Facilities class handouts, Adabas Command Reference Manual, Adabas Programming Reference Data, and other technical manuals (Utilities, DBA & Operations Reference, Messages, and Implementation Guide). There is also a book published by WH&O regarding Adabas.


Day 2

The second day of class is spent providing more overview and foundation material for building a base of understanding for using Natural. The topics addressed are:

  1. A brief look at Predict, what it is and how it is used at the university.
  2. A discussion of the Natural environment that is used to develop Natural programs and to execute the resulting applications.
  3. An introduction and orientation to the Natural Reference Manual, the Natural programmer's best friend.
  4. Presentation of the various Natural objects or entities that are managed within Natural.

Predict

Predict is the data dictionary marketed by Software AG. A data dictionary is an application where information about applications and their data is maintained. Predict is written in Natural and resides within the Natural library SYSDIC. Predict is primarily used to describe files and the data elements contained within files. Some knowledge and understanding of Predict is beneficial to anyone developing Natural programs. However, only project leaders or lead analyst responsible for application design need to be able to directly use Predict. This should only be done in cooperation with the Data Dictionary Administrator (Carl Mathews) and in line with the Predict Usage Guidelines (available on request).


DDEs

The objects that are managed by Predict are referred to as data definition entities or DDEs. This terminology allows specific reference to the definitions contained within Predict versus the physical item being described. A great deal of information can be maintained within Predict for each type of entity. Some of the common Predict entities are:

DDE

Description

File

This is the primary object of concern for any data dictionary, since it represents a basic collection of related data. Predict can be used to describe many different types of files: VSAM, sequential, conceptual, DB2 and of course Adabas. Files are discussed in more detail in "Files and DDMs".

Element

Predict defines the fields of a file as data elements, or elementary elements. All elements must be associated with (defined on) a Predict file. Each element name must be unique for that file.

Data Base

A data base can be a physical entity like an Adabas data base or it can be a conceptual grouping of related files. Files are related to data bases. Our Adabas files are associated with our test Adabas data base on the test system.

Keyword

Keywords must be predefined but may then be associated with any other Predict entity and are useful for classifying and retrieving those entities.

Verification Rule

Verification rules are definitions of specific validations that should be performed prior to acceptance of input data. They may be conceptual or tied explicitly to certain data elements. In Natural they are refered to as processing rules, specifically as free rules or automatic rules when they are stored on Predict.

There are many other Predict entities that are not as crucial to our use of Natural. These include applications, programs, modules, users, etc.


Files and DDMs

Predict allows the definition of many types of physical files: Adabas, VSAM, and sequential are the ones used at the university. Based upon these physical files, Predict also allows the definition of logical views of Adabas and VSAM files. These logical views, also referred to as user views, are a defined subset of the elements which are contained on the physical file. Another type of Predict file is conceptual. Conceptual files are just that, a place to define elements at a conceptual or design level, prior to making decisions about the physical representation of the data. Conceptual files are the only type that should be manipulated by individuals outside the Dictionary Administrator's area. All files must have a unique file name on Predict.

Natural accesses Adabas and VSAM files through an interface called a Data Definition Module or DDM. The DDM provides a logical view and description of a file to the Natural program and programmer. Some of the advantages of this interface are:

DDMs are generated by Predict from file definitions, either physical files or user views. The DDM is what is known and used by Natural in utilities, security definitions, and at program compilation time. On the other hand, much of our analysis and documentation is performed using the Predict file entities. Due to the DDM generation step, it is possible to stage the implementation of file changes by first making and reviewing those changes as they appear on Predict prior to regenerating the DDM. The DDM for the EMPLOYEES file as displayed by the Natural LIST command is available in Figure 8.

Figure 8. EMPLOYEES Data Definition Module


 DB:    1 File:   30 - EMPLOYEES                        Default Sequence:
TYL  DB  NAME                             F LENG  S D   REMARKS
---  --  -------------------------------- - ----  - -  ------------------------
  1  AA  PERSONNEL-ID                     A    8    D
         HD=PERSONNEL/ID
G 1  AB  FULL-NAME
  2  AC  FIRST-NAME                       A   20  N
  2  AD  MIDDLE-I                         A    1  N
  2  AE  NAME                             A   20    D
  1  AD  MIDDLE-NAME                      A   20  N
  1  AF  MAR-STAT                         A    1  F
         HD=MARITAL/STATUS
  1  AG  SEX                              A    1  F
         HD=S/E/X
  1  AH  BIRTH                            N  6.0    D
         HD=DATE/OF/BIRTH
         EM=99/99/99
G 1  A1  FULL-ADDRESS
M 2  AI  ADDRESS-LINE                     A   20  N
         HD=ADDRESS
  2  AJ  CITY                             A   20  N D
  2  AK  ZIP                              A   10  N
         HD=POSTAL/ADDRESS
  2  AK  POST-CODE                        A   10  N
         HD=POSTAL/ADDRESS
  2  AL  COUNTRY                          A    3  N
G 1  A2  TELEPHONE
  2  AN  AREA-CODE                        A    6  N
         HD=AREA/CODE
  2  AM  PHONE                            A   15  N
         HD=TELEPHONE
  1  AO  DEPT                             A    6    D
         HD=DEPARTMENT/CODE
  1  AP  JOB-TITLE                        A   25  N D
         HD=CURRENT/POSITION
P 1  AQ  INCOME
  2  AR  CURR-CODE                        A    3  N
         HD=CURRENCY/CODE
  2  AS  SALARY                           P  9.0  N
         HD=ANNUAL/SALARY
M 2  AT  BONUS                            P  9.0  N
G 1  A3  LEAVE-DATA
  2  AU  LEAVE-DUE                        N  2.0
         HD=LEAVE/DUE
  2  AV  LEAVE-TAKEN                      N  2.0  N
P 1  AW  LEAVE-BOOKED
  2  AX  LEAVE-START                      N  6.0  N
         HD=LEAVE/START
         EM=99/99/99
  2  AY  LEAVE-END                        N  6.0  N
         HD=LEAVE/END
         EM=99/99/99
M 1  AZ  LANG                             A    3  N D
         HD=LANG/SPOKEN
  1  PH  PHONETIC-NAME                    A   20    P
  1  H1  LEAVE-LEFT                       B    4    S
         HD=LEAVE/REMAINING
  1  S1  DEPARTMENT                       A    4    S
         HD=SECTION
  1  S2  DEPT-PERSON                      A   26    S
  1  S3  CURRENCY-SALARY                  A   12    S

There are several standards that have been adopted regarding the university's use of Predict, which are documented in the "Predict Usage Guidelines". Many of these apply to files and elements and primarily involve extended comments and descriptions. In order to provide accurate and complete documentation for our files, a custom report program was developed that incorporates use of these standards. This dictionary report is named PDB7004 and should always be used to generate element listings of our files. Sample output from this report is provided in Figure 9.


SYSDIC menus

Predict's menus are structured by function, entity and then action. The primary functions are Maintenance, Retrieval, and Generation. The submenus for those functions identifies the entities that can be maintained, retrieved or generated. Maintenance functions are where add, change and deletion actions are performed. Generation is where the ADACMP control cards and DDMs previously mentioned are generated from file definitions. The retrieval functions are for inquiry and reporting of Predict definitions. Some familiarity with the operation of this application will be beneficial to any future use.

Figure 9. UAF's PDB7004 dictionary report


PDB7004-1             University of Arkansas, Fayetteville              Page   1
08/20/90                    Predict Data Dictionary                     15:23:20
         Element definitions for file: APPLICATION (U-51)
 
File comments: Application information used by the Natural Secured Menus
               Architecture and managed by the NSM Maintenance System.
 
Ty L        File & Field names        F  Size S D           Comments
-- - -------------------------------- - ----- - - ------------------------------
 
   1 APPLICATION-ID                   A   8.0 N U Natural application identifier
       DB=AA                                      and library name.  Must be
       HD=Application/ID                          defined to Natural Security
                                                  and appropriate programs
                                                  cataloged in the library.
 
   1 APPLICATION-NAME                 A  40.0 N   Descriptive name of a Natural
       DB=AB                                      application.  This field is
       HD=Application Name                        maintained in mixed case.
 
   1 MAIN-MENU-COMMAND-ID             A   4.0 N   The COMMAND-ID for the main
       DB=AC                                      menu of a Natural application
       HD=Main/Menu/Command                       which utilizes the Natural
                                                  Secured Menus Architecture
                                                  (NSM-A).  This command is
                                                  automatically invoked for a
                                                  user entering the applica-
                                                  tion.
 
   1 APPLICATION-PREFIX               A   2.0 N   The two character prefix used
       DB=AD                                      on all entities associated
       HD=Appl/Prefix                             with the application: files,
       EM=^^XX                                    programs, jobs, etc.
 
   1 APPLICATION-LOCK                 A   1.0 N   A flag indicating whether the
       DB=AE                                      application is available for
       HD=Appl/Lock                               use or not.  Values are:
       EM=^X                                        L = Locked and unavailable
                                                    U = Unlocked and available
 
   1 DATE-NOTICE                      P   7.0 N   The date that the current
       DB=AF                                      application notice is to be
       HD=Notice/Date                             effective and available (may
                                                  be a future date or zero if
                                                  there is no notice, Natural
                                                  date format).


Predict's ACM

Another portion of Predict that is closely linked with Natural is the Active Cross-reference Module or ACM. This facility automatically maintains cross-reference data identifying what Natural objects use which data and vice-versa. This information is captured when objects are compiled or cataloged (Natural's term). Predict provides facilities to allow analysis of this cross-reference data across applications. Natural also provides commands to analyze cross-reference data within a single application. Natural's cross-reference facilities and Predict's ACM both use the same data source even though references and documentation employ different terminology, which may be confusing. Sample output from the cross-reference is available in Figure 10 which shows which Natural objects reference the field APPLICATION-OWNER. See "Natural libraries and programs" for more information about Natural objects and applications. See "UAF utilities" for information on the internally developed utility UAOCROSS which front ends Natural and Predicts menus.

Figure 10. Sample cross-reference report


  11:04:23            *****   P  R  E  D  I  C  T   *****               91-12-20
  Library: NSM-MS          -    Views and Fields   -      DBnr:     1 Fnr:     6
  Command: FIELD APPLICATION-OWNER (*) REF PROG * (*) USAGE *         Page:    1
 
 ----------------------------------------------------------------------------
 View:     1 APPLICATION
 ----- Field  --------------------- referenced in program  ------ Usage  ----
 
     1 APPLICATION-OWNER                        1 L:NSLAU         Defined
                                                2 L:NSLVS         Defined
                                                3 P:NSOA          Update
                                                4 P:NSOALR        Update
                                                5 P:NSOAN         Update
                                                6 P:NSOAU         Read
                                                7 P:NSOVS         Read
 
 ***** END OF LIST *****


The Natural Environment


The Natural Nucleus

The Natural nucleus is the core set of programs that provide the functions and features of Natural. Online it provides these services to multiple users at the same time by managing space and control information for each user separatly. Although only one user can execute at a time, Natural maintains the data for a number of users in memory and allows execution to alternate between these threads. Data for inactive users is rolled out to disk until they are ready to execute or until system resources are available. The same functions that are available online are also provided by the Natural nucleus in batch, although they are provided for each batch job separately.

Natural is highly parameterized allowing internal control values to be altered selectively from user to user. These parameters have system assigned default values, but can be overridden at the initiation of a Natural session and sometimes during a session. These NATPARMS provide a great deal of flexibility, as will be seen later.

Natural is much like an operating system in that it supports the execution of commands, utilities, and Natural programs. In this manner it supports both the development environment where Natural applications are built and tested and the production environment where those systems are executed. Natural command level use is reserved for individuals responsible for the development and management of Natural programs. User's of production applications do not need access to Natural commands since Natural programs maintain complete control over their session. This is the mode of operation for our production systems where production user IDs are restricted from access to Natural command level via a Natural parameter.


Natural libraries and programs

Natural programs are stored logically within libraries (also referred to as applications) on a special Adabas file, referred to as a Natural System file. These can be compared to a PC: a program is like a file, a library is like a directory, and the system file is like a hard disk.

Programs are created and saved using the Natural program editor. Programs must be compiled before they are executed. Natural maintains the source version and the object version of a program separately, although they are both identified by the same name. The way they are used is the distinguishing factor, only the source can be edited and only the object can be executed. The terminology is confusing because these are only two of several entities that are collectively referred to as Natural Objects. See "Natural objects" for more information.

Although Natural programs are compiled, the result is not 370 assembly language but operation codes and arguments that are interpreted at execution time by Natural. The first step required to execute a Natural program is for Natural to load the program from Adabas to the Buffer Pool. This a reserved area from which all programs are executed. If a program already resides in the buffer pool, it does not have to be reloaded. Additionally, Natural programs are reentrant so that only one copy of a program needs to be in the buffer pool even though multiple users are executing it at the same time. This is accomplished by Natural maintaining the program data separate from the program code.

A program can be executed by just entering its names as a Natural command. The program must reside in the current library or in the "steplib" defined for that library. Natural has a special library, SYSTEM, which is the default steplib for all libraries and the only one currently used at the university. Utility programs and other Natural objects that need to be shared across libraries are placed on SYSTEM.


User buffers

Natural manages a great deal of data for each active user. This data is grouped into buffers according to its use. The most significant buffers are:

E-Size

The extended buffer is used primarily to hold source programs during editing and global data during program execution (used almost exclusively for online applications).

U-Size

The user buffer contains program data, the variable contents which are specific for each user.

The current and maximum size of these buffers can be displayed with the BUS (Buffer Usage Statistics) command.

Support systems

There are several support systems that are integral to our use of Natural. Some of these are marketed by Software AG as separate products and some are merely collections of utility programs placed in functional libraries. All are written partially, if not completely, in Natural. Predict is one example while Natural Security is another. Natural Security allows us to place very specific restrictions on users, libraries and files. Common restrictions include what libraries a user can access, what files can be accessed from a library, whether a file can be updated, and whether a user is allowed command level within a library. Libraries which start with SYS are system libraries maintained by Software AG and are primarily for use by Natural Administrators and DBAs.


User Identification

A signon process is required to access and use Natural. This allows Natural to identify the user and enforce the appropriate restrictions regarding that user's access, as defined in Natural Security. The signon requires identification of the user's Natural ID, Natural Password, and the library to be accessed. However, Software AG has provided a way for this procedure to be bypassed and for a user to be automatically signed on. We use this auto-logging online since all users must first signon to CICS and there is no reason to require two authorizations of the user's identity. The Natural ID is provided in a parameter passed from CICS, the password is not required, and the library defaults to LOGON (an internally developed application) which requests the user specify what library they wish to access. This results in users having Natural Passwords but not knowing what they are since they are never required. This is not a problem except for Natural developers who commonly need to execute Natural in batch, where your ID and password must be provided. The Natural Security Administrator can set your password initially. To change it the auto-logging process must by by-passed by invoking Natural with the CICS command:
NATL AUTO=OFF
A menu will then be displayed where the library to be accessed, your ID, password and an optional new password can be entered.

System files

Adabas files are used as the repository for much of the information used by Natural. As mentioned previously, Natural programs are stored on such a file. These files which are required for the operation of Natural are called Natural System Files. The primary system files and their purpose follow. The acronyms used to identify them are commonly used and are also Natural parameters which specify the DBID and file number to be used. The university maintains at least two sets of these files, one for the test environment and one for production.

File

Purpose

FNAT

This file contains the SYSxxx libraries and programs as delivered by Software AG. We do not modify these programs. As such, when a new product release is provided this file can be completely reinitialized.

FUSER

This is the system file where user written programs and libraries reside. All program changes and compiles are recorded within this Adabas file.

FSEC

This is the security file where all Natural Security definitions are stored. This data is segregated due to its confidential nature.

FDIC

This is the dictionary file where all Predict definitions are maintained. DDMs and cross-reference data are also stored here.


Natural Secured Menus

The Natural Secured Menus (NSM) Architecture is both an approach for designing and developing online Natural applications and a collection of tools and facilities to assist in that endeavor. Most Natural applications developed at the university use the NSM Architecture. It has been designed to provide:

NSM is a data driven architecture. The data used by NSM is maintained through the NSM Maintenance System, Natural application NSM-MS. Complete information about NSM is available within the "NSM Architecture Functional Specifications" and the "NSM Maintenance System Functional Specifications".


Online Help Facilities

Standard field and screen help routines were developed for use by all Natural on-line applications. These routines provide sophisticated help facilities in a consistent and uniform manner, yet are extremely simple to implement. They are not intended to address all possible needs, however they do offer powerful features in an easy to use fashion and do meet most requirements. Features of these facilities include:

Complete documentation for these routines is available within the paper "UAF's Standard Natural Online Help Facilities".


Accessing Natural

Online access to Natural is provided through CICS. A user must be issued a CICS ID with authorization to access Natural. Separate documentation is available describing the CICS signon procedure. Once Natural is invoked, all users are automatically placed in the LOGON application. This Natural application has only one screen, which provides user and system identification information and allows selection of another Natural application to be used.

Development activities require Natural command level access. The CLEAR key can be used to terminate the automatic execution of the application if necessary, and if permitted. Natural command level can be in two forms:

Use of these two forms can be toggled with the command MAINMENU.

Batch access to Natural requires authorization to execute MVS batch jobs, which requires a job card (reserved for Computing Services personnel) or access to special job submission procedures. Batch Natural is most easily invoked using the NATURAL proc and requires entry of your Natural ID, Natural password, and the Natural library to be logged onto (a logon is required in batch just as it is online). The following are special DDs (data definitions) that may be used with batch Natural:

DDname

Purpose

CMSYNIN

The source for standard or console input provided to Natural. Signon information and commands are provided here.

CMPRINT

The destination for standard or console output from Natural. Input commands and data are echoed here and any output to report 0.

CMPRTnn

The destination for reports as identified within Natural programs by the same two digit number, nn.

CMWKFnn

The definition of sequential files which may be used for input or output with Natural programs (required for use with the READ WORK and WRITE WORK statements).


The Natural Reference Manual

The Natural 2 Reference Manual is essential for anyone that will be developing Natural programs and applications. As its name indicates, it is a reference document and should not be read front to back as a way to learn Natural. A familiarity with the organization and layout of the manual will be a great aid in its use.

The most recent version of the manual will include Update Series III dated June 1989. Unfortunately many of the update pages were printed on the wrong side of the page and most manuals have been improperly updated. Missing pages will be the most significant problem. The university has permission to copy Software AG documentation. Computing Services maintains the original manual and all update packets issued for the manual. Attempts have been made to control the issuance of these manuals and Computing Services has traditionally supplied copies to users at Printing Services' costs. This procedure does not appear to be working however. A new manual corresponding to Natural 2.2 is expected in early 1992.


Organization

The Natural 2 Reference Manual (NRM) is divided into six chapters. A very good summary of these chapters is provided in the Introduction, page 1 of the manual. Page numbering elsewhere in the manual uses the notation of chapter - page, i.e. 1-1. Further comments about the chapters follows:

Chapter 1

Many essential facts are covered in this general information chapter, some of which are rather detailed and complex. Page 1-1 defines the syntax symbols used throughout the manual, which is is essential to understand. You may skim this chapter initially, reread it after you are somewhat familiar with Natural, and reference detail specifications provided here throughout your days of using Natural.

Note: Please ignore pages 1-8 and 1-9 since the constructs presented there are confusing and not currently used at the university.

Chapter 2

This is the Natural program statement reference section, organized alphabetically by program statement. It constitutes the bulk of the manual. The alphabetical organization means it is convenient to look up specific statements. Initially as you contemplate a task, it may be beneficial to scan the table of contents for this chapter where all statements are listed.

Note: Page 2-1 defines the Operand Definition Table which is used to document the operands used with Natural statements and statement clauses. Even though it is introduced in Chapter 2, this format is used within Chapter 1.

Chapter 3

System variables and system functions are defined here in two separate groups. You will have to scan the list provided within the chapter since these are not included in the table of contents. Again, an alphabetical organization is used although the complete chapter only requires a few pages.

Chapter 4

This chapter documents the Natural commands used by developers to manage Natural objects and the environment. Note that the editor commands are not included here, but are in chapter 6. There is some overlap between commands which can be issued from within and outside the editor, this can be confusing.

Chapter 5

Terminal control commands are documented here. This is a very new and strange concept for most people. Functions provided by these commands can be very sophisticated and need to be well understood by application developers.

Chapter 6

This chapter documents the three different (but similar) editors provided as part of Natural. The type of object being edited determines which editor is invoked. By and far one of the most confusing parts of Natural is the map editor, a subject of the Advanced Natural Class.

Note: Not all statements or options apply to our environment since they are available for use with "add on" products. The manual usually includes special "Notes" when a special product or non-standard environment is required. As an example see the COMPOSE statement on page 2-50.


Structured vs Report Mode

Natural version 2, which we use, incorporated significant changes over version 1. The changes were so significant Software AG chose to rename Natural as Natural 2 (not everyone follows this convention). To remain compatible with the previous version of their product, and yet still provide new features and a more modern syntax for the language, there are now two modes that you can code in: structured or reporting. The manual includes alternate documentation for the syntax of each mode and notes regarding restrictions applicable to the mode. The Natural Basics Class deals only with structured mode programming and Computing Services discourages the use of reporting mode.


Other Natural documentation

Additional documentation is available to assist in learning and using Natural. The following are published by Software AG: Natural 2 Concepts and Facilities Manual, Natural 2 Programmer's Guide, Natural 2 Error Messages Manual, Natural 2 Reference Data Card. and Natural 2.2 Planning Guide. Computing Services also has a few copies of texts from WH&O that resemble the reference manual, the programmers guide, and one titled "Natural Tips and Techniques".


Natural objects

A "Natural object" is a an entity stored on a Natural system file (either FNAT or FUSER). These entities are normally created using Natural's editors and other system commands. All Natural objects have an eight character name which must be unique within a library. Computing Services uses the following naming convention for Natural objects created for production applications: aatuuuuu. The aa is the standard two character application area prefixed assigned to the application, the t identifies the type of object (these type codes are identified below), and the uuuuu is a unique name or acronym representing the purpose of the object.

The term object refers to two different concepts within Natural and therefore can be misleading. A Natural program is an example of a Natural object, except there are actually two versions of a program. The program statements as entered by a programmer and the compiled version of the program generated by Natural when the program is cataloged. These are commonly referred to as the source object (or source module) and the object module, respectively. Both are separate Natural objects even though they share the same name. There are other Natural objects besides programs, some of which may also be compiled and therefore have a corresponding object module. The types of Natural objects are defined below.

Object

Description

Program

A collection of Natural program statements which can be executed directly. The standard type identifier in the name is an O for online programs and a B for batch programs.

Data area

The definition of a collection of Natural variables which is created and maintained separate from the program(s) that use them. Data areas can be used for many purposes and are a form of modular programming. There are three different types of data areas:

  • Global data areas (GDAs) are used to define global variables, variables whose values are available to any program which references that data area. The values of these variables remain static even while separate programs are executed. Global data areas are almost exclusively used for the development of online applications. The type identifier for GDAs is G.
  • Local data areas (LDAs) are used as a way of centrally defining local variables. A local variable is a variable which can only be used within the program for which it is defined. With an LDA, those definitions can be used by multiple programs without having to be entered to each. The type identifier for LDAs is L.
  • Parameter data areas (PDAs) define the data which is passed to and from NATURAL subprograms. These parameter values are then available to both the calling program and the subprogram. PDAs are not required for calling subprograms, but again provide a means of defining these variables once for use in multiple locations. The type identifier for PDAs is A.

Copycode

A segment of source code that is brought into another program at compilation time. Its point of inclusion is identified with the INCLUDE statement. This is a method of maintaining code that performs a specific function in one location while using it in multiple programs. The type identifier for copy code is C.

Map

Preformatted and defined screen images which are invoked by name from a program. Maps are created and maintained with the map editor. The type identifier for maps is M.

Subprogram

A collection of program statements that are compiled but which cannot be executed directly. Subprograms must be called from other programs using the CALLNAT statement. The parameter data areas mentioned previously are used by subprograms. The type identifier for subprograms is N.

Subroutine

As a Natural object, subroutines are similar to subprograms except that no parameters are passed by the calling program. To invoke a subroutine the PERFORM statement is used. Subroutine names may also be 32 characters, Natural somehow relates the 32 character name "performed" to the eight character object stored on the system file. Subroutines may also be defined internally within another Natural program, in which case no additional Natural object is created. There has been little use found for external subroutines. The type identifier for subroutines is S.

Helproutine

A special type of subprogram that is invoked when a user requests help during data input. Help may be requested by pressing a PF-Key assigned that function or by entering a ? in a field. Helproutines are discussed in the advanced class. The type identifier for helproutines is H.

Text

An object type that may be used for storing any textual information desired. Use of text objects has been minimal. One application has been for the maintenance of JCL which can then be submitted to MVS from Natural. The type identifier for text is T although J has also been used for JCL.

Macro

A special type of Natural program which when executed, results in the generation of some other object, typically JCL or any type of program. Macros may only be defined and cataloged within Natural ISPF although they may be executed from Natural. The type identifier for Macros is Z.


Day 3

The third day is spent learning to operate within Natural, the environment (versus Natural the language). The most important Natural commands are covered and the basics of the Natural program editor and Natural data area editor are covered.


Natural Commands

The Natural system commands are documented in chapter 4 of the Natural Reference Manual. These commands can be executed in response to the Natural "NEXT" prompt or in the command line provided on Natural's menus. They may be executed in batch as well as online. There are a few points about the Natural online environment that may be beneficial.

  1. Natural reserves one line of the screen as its message area or message line. This line will contain prompts, information, or all too ofter error messages. It is normally positioned at the top of the screen but may be relocated by the user.
  2. When a program or utility has queued up more output for the screen than is currently displayed, the message line will contain the word MORE. The ENTER key will cause the next screen to be displayed.
  3. When the logical page size output by a program exceeds the physical page size of your screen, Natural will display VVVV in the message line. The ENTER key will cause the remainder of that logical page to be displayed by jumping the screen up the number of lines required.
  4. Throughout Natural's menus and systems, the universal quit command is a period. By entering a period you will generally back up one level or menu.

Within the lists of commands that follow, an alias or short name for a command (if available) is indicated by the portion of the command presented in uppercase. The command must normally be abbreviated to this alias or the full command name entered. For example, E or EDIT is used to enter the Natural editor and is presented here as Edit.


Environment commands

These environment commands are used to manipulate or provide information about the Natural session.

FIN

Terminates your Natural session and returns you to the CICS menu.

GLOBALS

Used to alter Natural parameter values. The most common use is to switch the mode of a program from report to structured. This would be done within the editor with the command:

GLOBALS SM=ON

HELP

Natural has extensive help facilities with a vast store of information and documentation available. Some information is only available through online help. Besides the HELP command, try a ? whenever you need assistance. Also the direct command ? nnnn where nnnn is a Natural error number will provide information on that specific error.

LOGON

Used to logon to another Natural library or application. This command should not be confused with our LOGON application, which is essentially used for the same purpose.

PROFILE

Displays the users Natural Security profile.

SYSPROF

Displays the Natural system files that are being used.

UPDATE

A nifty switch which can be used to tell Natural that even though a program does an update, not to effect the update on the data base. It can be used to make trial runs of update programs without affecting anything.


Execution commands

There are two ways to execute a Natural program.

pgm-name

Any compiled program can be executed by entering the program name as a command. The cataloged version of the program, or object module, must reside in the current library or the defined steplib.

RUN

Compiles a program and then executes it without writing the object module to the system file. The compiled code is written directly to memory and executed from there. The RUN command will expand the contents of global variables whose name starts with & prior to the compilation. In this manner programs can be written dynamically by altering the values assigned to global variables. This is a topic for advanced Natural programmers.


Object management commands

The following direct commands are used to manage and obtain information about Natural objects. Many of these commands operate on an argument list which may contain an object name, the initial characters of the object name followed by *, or just an asterisk designating all objects. Many of these functions are available from the Development menu when Natural's menu structure is being used.

CATALL

This is a mass catalog function which can take any or all objects for a library and recatalog them.

Edit

Invokes the editor appropriate for the object currently held in the work area or the program editor by default. If an object name is provided with the command, the object is read into the work area and the editor invoked. Caution, no warning is provided if the object previously in the work area had been changed but not saved.

List

All Natural objects can be listed with this command including views (Natural's DDMs). The argument list can include an object type specification preceding the object name or wildcard. Types are identified by one character codes: V for views, P for programs, S for subroutines, etc. There are some very nice options with the LIST command like a cross-reference showing all lines containing a string and a search feature. See SUBMIT under "UAF utilities" for better alternatives for generating hardcopy source listings.

LIST COUNT

Provides counts of the number of objects in different statuses.

LIST DIR

Provides detail directory information about an object, both the source and the cataloged versions. Data such as the date of last modification, user that last updated the object, and the Natural version used for the update.

LIST XREF

Provides access to Natural's cross-reference information through an elaborate menu system. See UAOCROSS under "UAF utilities" for a simpler alternative.

PURGE

Deletes the specified source object from the Natural system file. If a wildcard specification is used, a list of qualifying objects is provided and those to be deleted may be marked. A corresponding object module may remain on the system file and can continue to be executed. Use the SCRATCH command to delete both source and objects forms of a Natural object.

SCAN

Provides a global scan function which can be used to search any or all source objects for a given string. Replacement values can also be used.

SCRATCH

Deletes the specified object from the Natural system file, both the source object and the object module.

STRUCT

This command is not in the manual. It can be used to establish parameters that will be used by the STRUCT command within the program editor or it can restructure a program. However, its primary use is to display a program with various structure comments added. This is very helpful in seeing where loops and open constructs are terminated.

UNCATalog

Delete an object module from the system file. The source, if present, is not affected.


Editor commands

The following commands are primarily for use within the Natural editors and most apply to all three editors. Some of the commands may also be issued from outside an editor. Perhaps this is the reason these are documented in chapter 4 and not chapter 6. All deal with Natural objects and the edit work area (remember E-Size).

CATalog

Compiles and creates an object module for the source object currently in the work area.

Check

Performs a syntax check on the source object in the work area.

CLEAR

Clears the edit work area. No warning is provided if the source in the work area has been changed but not saved.

READ

Reads the specified source object into the edit work area and if in an editor, invokes the proper editor for the object.

RENUMber

Reassigns the program line numbers in even increments.

SAVE

Saves the contents of the edit work area to the Natural system file using the current object name.

SCan

Searches the workarea for a specified string and optionally performs a replacement. A window of options is displayed when the SCAN command is entered with no arguments.

STOW

Combines the CAT and SAVE commands. The source is not saved unless the catalog is successful.


Terminal control commands

Terminal control commands are documented in chapter 5 of the Natural Reference Manual. These commands may be used to perform a wide variety of special purpose functions. They may be entered on any screen at any time, as long as there is an input field large enough to accept their value. They must be entered in the first position of an input field, but may actually spill over into several fields. All other inputs or modifications made during the same screen I/O are ignored (the screen will be refreshed and appear as it was prior to that I/O). A few of the most useful terminal control commands are:

%%

This is like the escape key, it interrupts the execution of the current program and returns the user to command level if permitted. The CLEAR key normally performs this same function.

%l, %u

These two commands control the translation of lower case input characters to upper case.

%w

Sets and controls windows. There are numerous additional parameters that are used with the %w command.

%*

Suppresses the display of the following input characters. This should always be used in batch preceding the entry of your password so that it is not echoed on the console output (CMPRINT).

A great deal of time can be spent studying and contemplating uses for these terminal control commands. They can also be issued directly by a program using the Natural statement SET CONTROL.


UAF utilities

There are several Natural utility programs that have been developed locally that are helpful to a Natural developer. They are only briefly described here but are easily executed and available for experimentation.

Utility

Description

BANNER

Selectively clears the work area and writes a program banner with the standard heading comments to the work area. This command should be executed from within the program editor.

COMPARE

Provides a menu of options for comparing Natural objects and Predict entities.

COPY

A facility that allows objects from other libraries to be copied to the current library. Modules from production can be copied to test.

SUBMIT

Provides a menu of batch jobs that may be submitted from Natural. These include source listings, listings with cross-references, the standard dictionary report PDB7004, and generic Natural jobs.

SPOOL

Spools a listing of an object to a remote printer from an online CICS session. This is the quickest and easiest way to get a listing of a Natural object.

PUNCH

Sends a Natural object from CICS to a CMS ID as a punch file.

UAOCROSS

Provides a menu of options for obtaining cross-reference information in a simpler manner than using Predict or LIST XREF.

These utilities are Natural programs residing on the SYSTEM library and thus available from all other libraries.


Natural editors

Three editors are provided with Natural. The map editor is used with maps and covered in the advanced class. The data area editor is used to edit GDAs, LDAs and PDAs. All other objects are maintained with the Natural program editor.


Program editor

The program editor is documented on page 6-4 of the NRM. Some general facts about the program editor include:

Line commands

The following commands are entered by overtyping the text of the object and must be entered in the first position of the field. They cannot be entered from a blank line. Line commands take precedence over changes made within the line during the same screen I/O. In other words, your changes will be lost unless you press enter before typing your "." command.

.c(n)

Makes n copies of the line where this command was entered.

.cx,.cx-y

Copies a marked line or a marked range of lines from one location to another.

.d

Deletes the line containing this command.

.i(n)

Temporarily inserts 10 blank lines, or n lines, following or preceding the line containing the ".i". Remaining blank lines will be removed after the next ENTER.

.i(obj,l,n)

Reads n lines from the object specified beginning with physical line l of the object and inserts it into the work area. Note that the line location to be inserted is not Natural's line number, which is normally incremented by 10 for each line, but is the physical line number.

.j

Joins the next line to the end of the line marked with ".j"

.l

Forgets any changes made on the current line and restores the line to its status as of the last screen I/O.

.mx,.mx-y

Moves a marked line or marked group of lines to follow (or precede) the line containing this command (dependant on the direction indicator).

.p

Attempts to make the line containing the .p the top displayed line within the editor. If there are not enough lines to make the line the top line, the last page of the file is displayed.

.s

Splits the line at the postion of the cursor.

.x,.y

Marks a line or a range of lines which will be used in combination with another command. The .x marks the beginning and .y the end of the range.

Edit commands

The following commands, in addition to those listed in "Editor commands", may be issued from within the editor.

BOT/++

Go to the bottom of the object.

DX/DX-Y

Deletes the line or range of lines marked.

LET

Forgets all changes made on the current screen and restores the screen to its status as of the last screen I/O.

PROFILE

Displays a screen of editor profile settings which can be altered and saved. This is very useful since you can assign PF-Keys to commands you are comfortable with and save considerable time editing. You must save the profile using your Natural ID and these will be set for all future edit sessions. The profile of another user may be read and modified for your use.

SCan

Used to scan and or replace a string. With no argument provided, a screen of options is displayed. The command SC = repeats the last scan operation.

SET TYPE

Used to change the type of object being edited, i.e. program to subprogram.

SHIFT

Will shift a marked block of lines + (right) or - (left) the number of spaces indicated.

SHIFT +2

STRUCT

Adds and removes indentation so that the program has a standard structure. The structure of a program is critical to readability and maintenance.

TOP/--

Go to the top of the object.

./Quit

Terminates the editor and returns to the Natural development menu.

+/-

Page forward or backward.

+nn/-nn

Moves forward or backward the specified number of lines.

+H/-H

Postion forward or backward a half page (very useful).


Split screen feature

All of the editors have a split screen viewing capability where another object can be displayed on a portion of the screen. There are provisions within each editor for accessing information contained in other objects.

Invoking split screen

Different commands are used to invoke the split screen editor depending upon the type of object to be displayed.

S D Display a data area in the split screen, either a GDA, LDA or PDA.
S P Display a program, or other object maintained by the program editor, in the split screen.
S V Display a file view (DDM) in the split screen.

Object positioning

The following commands are used to reposition the lines displayed in the split screen.

S +/-

Page forward or backward in the split screen.

S ++/--

Go to the first or the last page of the object in the split screen.

S +nn/-nn

Go forward or backward nn lines within the object.

S SC value

Scan for the specified value within the split screen object.

Terminating split screen

S E Closes the split screen.

Natural data area editor

The data area editor is very different from any other editor. This is due to its purpose of maintaining element definitions and the fact that its screen is oriented to the attributes of data variables. All data used by a structured mode program must be explicitly defined and data areas provide a convenient method of doing this. All types of data areas may be edited: GDAs, LDAs, and PDAs. The data area editor is addressed on page 6-16 of the NRM.

The information maintained by the data area editor corresponds with the attributes that may be defined for variables with the Natural statement DEFINE DATA. Some attributes are the same as those observed in file views: level, name, format and length, and edit mask. Additionally, initial values may be assigned for variables with the INIT clause. Arrays require a dimension specification which is the same as the number of MU or PE elements to be accessed. Many element attributes are specified free form in the last column displayed by the data area editor. An example of the data area editor screen is shown as Figure 11.

Figure 11. Data Area Editor screen


11:57:31                *****  E D I T  DATA  *****                    01/02/92
Library: DW85047   Name: DEA      LOCAL                      DBID:   1 FNR:   6
Command:                                                                  > +
I T L Name                             F Leng  Index/Init/EM/Name/Comment
- - - -------------------------------- - ---- -------------------------------
  *
  V 1 EMPLOYEES-VIEW                          EMPLOYEES
    2 PERSONNEL-ID                     A    8
  G 2 FULL-NAME
    3 FIRST-NAME                       A   20
    3 MIDDLE-I                         A    1
    3 NAME                             A   20
    2 C*ADDRESS-LINE
  M 2 ADDRESS-LINE                     A   20 (1:5)
    2 CITY                             A   20
    2 ZIP                              A   10
    2 POST-CODE                        A   10
    2 COUNTRY                          A    3
  *
    1 #LOCALS

Data accessed from files (DDMs) may also be defined in the data area. Any subset of the fields from the DDM may be included, however changes to most field attributes are not allowed. You should always change the number of occurrences of MU and PE fields to meet your needs. You are not allowed to copy or move elements of the resulting view. Views are indicated by a V in the Type column and the view (DDM) name in the last column. Views must be defined in the data area using the .v line command mentioned later.

Another special type within the data area editor is a field redefinition, which will have an R in the Type column. Redefinitions are a way of assigning one or more new names to an area of data and new attributes such as format, length, and array structure. An understanding of the internal data representation for Natural data types is required to use the REDEFINES. Group fields or structures (elements which are defined at level 1 followed by level 2 elements) can be redefined, providing broad capabilities. Copy and move operations are also restricted for field redefinitions.

Most of the program editor commands work the same within the data area editor: CLEAR, CHECK, SAVE, STOW, READ and SET TYPE G/L/P. Most line commands and line operation commands are also operable. even though they must be entered in the Type, Level and possibly the Name fields, this results in a strange and awkward feel. There are line command restrictions in dealing with view elements and redefinitions since these are special types. The following line commands are unique to the data area editor:

.f(file)

Includes a file definition from Predict. This would be useful for sequential files whose definition has been made to Predict. It would normally not be used for VSAM or Adabas files.

.r

Redefines a variable. Actually it opens new lines where the variable redefinition can be entered.

.v(view)

Provides a list of the elements from the specified DDM where they can be checked off if desired in the view. The view definition is then created within the data area. The name of the view defaults to 'ddmname-VIEW' but can be altered, allowing the same file to be used more than once. Once created, the elements of the view can be expanded by re-executing the '.v(ddm)' on the view definition line.

.*

Creates an internal count variable for view elements which are PE groups or MU fields. The lines before, during and after this specification would appear as:

 M 2 ADDRESS-LINE                   A 20      (1:5)
 
 . * ADDRESS-LINE                   A 20      (1:5)
 
   2 C*ADDRESS-LINE
 M 2 ADDRESS-LINE                   A 20      (1:5)
See the NRM page 1-11 for more information.

l(n)

Pulls n definitions from line l of a view (DDM) displayed in the split screen.


Day 4 and 5

After three days of introduction, orientation, background and overview you finally reach the meat of the class: how to write Natural code. Basically two days are spent covering the Natural language, the basic program statements used to write Natural programs. Before jumping in though, an important review is made of chapter 1 of the NRM and the syntax and some basic concepts of the language are presented. The two days are conclude with discussions regarding Natural parameters, system functions and system variables.


Natural program statements

Specific statements used in the Natural language are reviewed in this section. Not all statements have been included for this introduction to the language. Statements have been grouped according to function since the Natural Reference Manual lists them alphabetically. Some code examples are provided as well as references to programs in the UAEXPG library which use the particular statement.


General information

Chapter 1

Prior to examining the specific statements of the Natural language, the general information contained in Chapter 1 of the NRM should be reviewed. Familiarity is needed with the following information discussed there:

Free form syntax

Natural programs are free form, in that statements may start anywhere on a line and span many lines. To acommodate this, the compiler must recognize keywords such as the language statements and other required words. This frequently means that the compiler will detect an error but point to the wrong line. Always examine the statements before and after the line indicated to be in error.

Many Natural statements have numerous key words and clauses. Often many of these are optional. When all optional words are provided the statements tend to read more like English. The programmer's tendency however is to use only the required words to construct statements, or only a few more than necessary.

Procedural nature

Natural programs are mostly procedural. Execution flows from top to bottom sequentially. Several statements initiate loops where one or more statements are executed iteratively. There are however, some statement constructs which are not procedural but whose execution is triggered by some event. The location of these statements can usually vary with some constraints. Statements of this nature include:

ON ERROR
DEFINE SUBROUTINE
AT ...
WRITE TITLE

Statement blocks

Many statements control or affect blocks of one or more other statements. In structured mode Natural all of these blocks must be explicitly delineated by a statement terminating clause, which can be found in the manual but have not always been included within examples. Further, there is a standard convention to indent those statements contained with these affected blocks to improve readability and maintenance of programs.

IF #STATE = 'TX'
  WRITE 'TEXAS'
END-IF

Scope

There is a concept of scope (availability of data variables) within Natural that is logical but not well documented. A variable from a view can be referenced with its unqualified name within the processing loop of the data access statement for the view. If there are multiple loops with the same element name occuring within the views of both loops, then reference to the variable from the outer loop must be qualified (view-name.element-name). All references may be qualified, and this is often the best approach. For this reason it is highly recommended that all view names be short to minimize typing.

It is not apparent from the manuals that elements from any view can be referenced at any time if qualified. References and use of this storage area is not restricted to within active processing loops. Null values are assigned to these variables at program initiation and when no record is found by a FIND.

A problem can occur when view elements are redefined using a variable name which is also defined elsewhere. The redefined element is not qualified since it is being used within a data access loop, however the element being referenced can be the duplicate value. The solution is qualification of variable references using the view or level 1 name.


Variable definition

DEFINE DATA

All variables used in structured mode programs must be defined in a DEFINE DATA statement. A program may contain only one DEFINE DATA statement and it must be the first statement of the program. The types of definitions allowed correspond with those made in the data area editor. If a data area is being used by a program, it must be specified in the DEFINE DATA statement.

DEFINE DATA
  GLOBAL USING GLOBDATA
  LOCAL  USING LOCDATA
  LOCAL
  1  E-V VIEW OF EMPLOYEES
     2  PERSONNEL-ID
     2  NAME
  1  #WORK-VARIABLE        (N6)
END-DEFINE

Views used by the data base access statements FIND and READ are not permitted to contain super-descriptors, sub-descriptors or hyper-descriptors. This is because these views are used by Natural to construct the Adabas format buffer and record buffer. Since these special descriptors do not occur on the Adabas file (they are only contained within the inverted lists) values for them cannot be returned by these data access statements. On the other hand, to use the HISTOGRAM statement a view must be constructed that only contains the descriptor being accessed. More information about these statements can be found under "Data base access".

The ability to redefine a field to be another format or length can be extremely useful. Natural's redefinition capability is very flexible, but often times misunderstood. An example is provided below involving a data structure in an array.

Given:
 
1  #DATA (A5/1:3) INIT <'AAA11' 'BBB22' 'CCC33'>
 
Which of the following results in #A(3) = 'CCC'?
 
1  REDEFINE #DATA           1 REDEFINE #DATA
   2  #A  (A3/1:3)            2 REDATA   (1:3)
   2  #N  (N2/1:3)              3 #A    (A3)
                                3 #N    (N2)
The right hand REDEFINE is the correct answer. #A(3) from the left hand definition will result in the value 'BB2' and a data exception if you tried to perform a numeric operation on #N(1) or #N(2).

Note: There is an almost universal convention that the names of local program variables (versus view elements) always start with a #. This is not required, but is generally adhered to at UAF.

Reference: DDAEX1, DDAEX2, DDAEX3, DDAEX4.


Data manipulation

RESET

Assigns the null value to a field or group of fields. Therefore this statement can operate on data of any type and mix these types within the statement. The INITIAL clause may be used to reset the variable value to its INIT value versus the null value.

RESET INITIAL #COUNTER #STATE E-V

ASSIGN

Assigns a value to one or more fields.

ASSIGN #A = 'ABC'
ASSIGN #A = #B = 'ABC'
Reference: ASGEX1S.

MOVE

Moves a constant or the value from a variable to one or more variables. There are four special forms of the MOVE statement:

  1. MOVE ROUNDED - Causes the value to be rounded. Both operands must be numeric.
  2. MOVE BY NAME - Moves individual fields contained in a data structure (group field) to another data structure, independent of their position in the structure provided they share the same elementary names.
  3. MOVE EDITED - Moves any type field to or from an alphanumeric field using a specified edit mask. This is one of the few ways to convert data from one data type to another.
  4. MOVE JUSTIFIED - used to cause the data being moved to be left or right justified within the receiving field.
MOVE 'ABC' TO #A
MOVE EDITED *TIMX (EM=MM/DD/YY^HH:II:SS AP) TO #DATE-TIME-STRING
Reference: MOVEX1, MOAEX1, MOVENAME, MOVEDATE, MOVEEDIT.

COMPUTE

Performs arithmetic operations. The field(s) specified to the left of the '=' will contain the result of the arithmetic operation. The arithmetic operations may consist of numeri constants, numeric data base fields, or numeric user-defined variables. Expression operators are: () ** * / + -

COMPUTE A = (3 * 2) + (4 / 2) - 1
Reference: COMPUTE, CPTEX1S.

ADD

Adds a numeric value to a variable.

ADD 1 TO #COUNTER

COMPRESS

Combines the contents of two or more operands into an alphanumeric field. The resulting field may be defined with a blank, some other specific delimiter, or with no blanks between the fields. Packed fields may not be used with this statement. Numeric values are accepted and leading zeros are translated to blanks and stripped off.

COMPRESS FIRST-NAME INITIAL NAME INTO LONG-NAME /* John A Smith
 
COMPRESS FIRST-NAME INITIAL NAME INTO LONG-NAME
         LEAVING NO SPACE                       /* JohnASmith
 
COMPRESS FIRST-NAME INITIAL NAME INTO LONG-NAME
         WITH DELIMITER '/'                     /* John/A/Smith
Reference: CMPEX1S.

SEPARATE

Separates the content of an alphanumeric variable into two or more variables or multiple occurrences of an alphanumeric array. If a delimiter is not specified, separation occurs at blanks. If an array is specified, it is filled occurrence by occurrence with the separated values.

Note: This statement will cause an execution error if there are not enough receiving fields specified.

SEPARATE LONG-NAME LEFT JUSTIFIED    /* This would error out with
  INTO FIRST-NAME INITIAL LAST-NAME  /* 'Sue Ann Lively Long'
Reference: SEPEX1, SEPEX2.

EXAMINE

Scans the contents of an alphanumeric field or a range of occurrences within an array for a character string. The character string may be replaced, instances counted, the position of the string obtained, and/or the index of the occurrence obtained. The FULL option can make a significant difference in the results obtained, read the documentation carefully and review the sample program EXAMINE within UAEXPG.

EXAMINE #FIELD FOR '=' GIVING NUMBER #COUNT
EXAMINE #ARRAY(*) FOR 'X' GIVING INDEX #INDEX
Reference: EXAMINEF, EXAMINE, EXME1.

Console and report I/O

FORMAT

Specifies default input and output parameter settings for a NATURAL program. These override the default session settings. Statement and individual element parameter assignments will override the FORMAT settings. The most common usage is to specify the page size (PS) and line size (LS) to be in effect for a report. See the NATURAL SESSION PARAMETERS in chapter 1 of the Natural reference manual for more on parameters.

FORMAT ZP=ON             /* Print zeros for report 0, the console
FORMAT (3) PS=60 LS=132  /* 60 lines per page and 132 columns per line
   .
WRITE (ZP=OFF) NAME ADDRESS CITY BONUS   /* Print blanks for zeros
               SALARY (ZP=ON)            /* Print a zero
Reference: FMTEX1.

DEFINE PRINTER

Most often used to associate a logical report name with an internal program report number. This usage is highly recommended since it makes the program self documenting and it simplifies maintenance if the report needs to be assigned to a different DD in the JCL.

DEFINE PRINTER (SUMMARY=1)
DEFINE PRINTER (DETAIL=2)
 ...
WRITE (SUMMARY) TITLE ...

INPUT

Creates a formatted screen or processes a map for data entry. Maps must be predefined using the map editor, a topic of the advanced class. Everything done with maps and the map editor can also be done directly with the INPUT statement. As a result this can be an extremely complex statement. This class only examines simple features for the purpose of entering limited data, usually for report options in batch or simple data entry online.

INPUT 'Dept code:' #DEPT
      'Salary limit:' #SAL-LIMIT
Reference: FETEX1, IPTEX1, SM22, PROG001, PROG002, PUR-RT, REIEX1.

DISPLAY

Specifies the fields to be output as a report in column format. Column headings are automatically generated. Only one display statement per internal report should be used since the headings and spacing are determined by the first DISPLAY encountered. This is one of the more complex Natural statements due to the extensive number of options available. It is very powerful, yet may be very simple.

DISPLAY (ZP=OFF) 'ID' PERSONNEL-ID NAME SALARY(1) (EM=$ZZ,ZZ9)
Reference: SM23, SM24.

EJECT

Causes a physical page ejection. *LINE-COUNT is set to zero but *PAGE-NUMBER is not changed. EJECT does not cause the execution of an AT TOP OF PAGE, AT END OF PAGE, WRITE TITLE, or WRITE TRAILER to occur. One of the few applications for this statement is to create a blank page when duplex output is being produced, there are multiple reports and each should begin on the face of the page, and the last page of the report is an odd page number.

IF *PAGE-NUMBER(DTL-RPT) NE *PAGE-NUMBER(DTL-RPT) / 2 * 2
  EJECT (DTL-RPT)
  WRITE (DTL-RPT) 'This page intentionally left blank.'
END-IF

WRITE

Produces output in fixed format, each variable is output with a fixed size and a space is placed between variables. Some of the differences between WRITE and DISPLAY are:

  1. Line overflow is supported by WRITE. If the line width is exceeded fields are written on the next line. Fields or text elements are not split between lines.
  2. No column headings are created with WRITE.
  3. A range of values/occurrences for an array are output horizontally rather than vertically.
The NOTITLE clause is used to suppress page headings.
READ EMPLOY-VIEW
   WRITE PERSONNEL-ID NAME BIRTH-DATE
END-READ
Reference: WRTEX1, WRTEX2, WRTEX3, WRTEX4, WRTEX5, PROG002.

WRITE TITLE

Overrides the default page title (heading) with the output specified by this statement. The WRITE TITLE may only be specified once per report. By convention, the WRITE TITLEs should be specified before other executable statements within the program. Model WRITE TITLE statements are available on the system library which conform to the university's standard report heading format. RPTHD80 (for 80 column reports) and RPTHD132 may be included in a program using the '.i(obj)' command.

WRITE TITLE (2) 'EMPLOYEE REPORT'
Reference: WTIEX1.

NEWPAGE

Causes a report, or the screen, to advance to a new page. Conditions for executing the statement can be added to the syntax. If the NEWPAGE statement is not used then page advances are controlled by the lines output and the size of the page, parameter PS.

IF #OLD-CITY NE #NEW-CITY
   NEWPAGE (1) IF LESS THAN 10 LINES LEFT
END-IF
Reference: NWPEX1S.

PRINT

Produces output in free format, that is all but one space is removed from between output fields. Leading zeros for numeric values and trailing blanks for alphanumeric fields are suppressed. The WRITE statement on the other hand outputs fields in fixed format according to their length (normally the preferred method).

PRINT PERSONNEL-ID NAME
Reference: PRTEX1.

SKIP

Generates one or more blank lines on a report or the console.

IF #OLD-NAME NE #NEW-NAME
   SKIP (2) 3  /* Three blank lines output to report 2
END-IF
Reference: SKPEX1.

Data base access

FIND

Selects a set of records from ADABAS or VSAM files based upon search criteria consisting of fields defined as descriptors (keys). A processing loop is initiated unless the FIND NUMBER option is used. One option available is the IF NO RECORDS FOUND clause which can be placed within the processing loop. When this clause is used the loop is always entered, whether or not any records met the search criteria. Another special feature is the ability to RETAIN the ISN list created for use in a subsequent FIND. The following system variables are commonly used in conjunction with the FIND statement.

*COUNTER, number of times the FIND loop has been entered
*NUMBER, number of records that met the search criteria
*ISN, ISN of the current record within the FIND loop
FIND EMPLOYEES WITH NAME = 'SMITH'
   WRITE PERSONNEL-ID NAME
END-FIND
Reference: SM4, STRCT2, (No records found) SM7, FNDIFN, (Limit) SM5, (Multiple files) SM14, PRLOOP1, PRLOOP2, FNDMUL, (Qualified name) PRLOOP3A, (Statement numbers) PRLOOP3B, (Label reference) PRLOOP3, (Retain) SM9, FNDRET, (System Variables) SM6, FNDVAR, (Where) FNDWHE, (Find Number) SM8, DEMOLOOK, EMPLOOK.

READ

Reads records from ADABAS files in physical sequence, ISN sequence, or logical (descriptor) sequence. VSAM KSDS files can only be read in logical sequence. The READ is used to sequentially process records from a file. More about the three available sequences:

  1. Logical sequence - records are read in the order of the values of a selected descriptor. A starting and ending value may be specified, except for sub, super and hyper descriptors where no ending value is allowed. To terminate these reads without processing the remainder of the file an ESCAPE BOTTOM must be used to exit the loop.
  2. Physical sequence - records are read in the order they are physically stored on the Adabas work data set. If as much as 40% to 50% of the records are needed this will normally be the most efficient method of processing.
  3. ISN sequence - records are read in ISN order. ISN sequence will normally have little if any meaning and this form should only be used for specific purposes.

A WHERE clause may be used with the READ to restrict which records are actually passed to the program. The records not passed to the program are physically read from the data base and therefore incur processing overhead, use the WHERE clause judiciously. System variables which are available with the READ statement are:

*COUNTER, number of times the READ loop has been entered
*ISN, ISN of the current record within the READ loop
READ EMPLOY-VIEW BY NAME = 'SMITH'
   WRITE PERSONNEL-ID NAME
END-READ
Reference: REAEX1S, REAEX2.

HISTOGRAM

Reads descriptor values from the inverted list for regular descriptors, subdescriptors, super-descriptors or hyper-descriptors. The HISTOGRAM starts processing with the first value equal or greater than the search value specified. An ending value may also be specified. The descriptor values are returned in ascending sequence. The DEFINE DATA view-name used with the HISTOGRAM statement may only contain the indexed field name. The following system variables are useful:

*NUMBER, The number of data base records containing the value
*ISN, The number of the occurrence of the value if a PE
*COUNTER, Count of the number of descriptor values processed
  HISTOGRAM EMPLOY-VIEW CITY STARTING FROM 'M'
Reference: HSTEX1S, SM16, CALLSUB.

LIMIT

Limits the number of records processed with a FIND, READ, or HISTOGRAM. If the limit is reached, processing stops and a message may be displayed depending on the LE session parameter. This statement is very useful in testing to limit the data accessed and conserve system resources. The same thing may be accomplished by specifying a count directly on these statements, i.e. READ (10).

LIMIT 100
Reference: LMTEX1, SM20.

ACCEPT IF/REJECT IF

Used to further select records within a processing loop based upon specific logical criteria. The criteria is evaluated after the record has been read as a result of a FIND, READ, or HISTOGRAM and after the record has entered the processing loop. Records rejected as a result of this clause can still cause automatic breaks to be triggered, however those rejected records do not affect system functions (SUM, COUNT, etc.). An accept or reject is useful when the selection criteria is dependent upon a relationship between multiple fields. Warning: it is easier to debug a program if only one ACCEPT or REJECT statement is used per processing loop.

COMPUTE #TOT-INCOME = SALARY(1:5) + BONUS(1:5,1:10)
REJECT IF #TOT-INCOME GT 5000
Reference: SM17, SM18, SM19

ESCAPE

Interrupts the linear flow of execution of a processing loop or a routine (program, subprogram or subroutine). There are three forms available:

Note: An escape from a loop will affect the explicit statements being executed but does not affect the execution of automatic break processing and system functions. For this reason, use of the ESCAPE for record selection within the same loop where break processing or system functions are used should be avoided. Creating a separate loop with the SORT statement is one work around.

READ E-V BY DEPARTMENT = 'COMP'
:
  IF DEPARTMENT NE 'COMP'
    ESCAPE BOTTOM
  END-IF
:
END-ALL
SORT ...
Reference: ESCEX1S, ESCAPE.

GET

Reads the record with the specified Adabas ISN (Internal Sequence Number). This statement does not initiate a processing loop. Extreme caution must be exercised with the use of this statement due to the fact that an execution time error is caused when an invalid ISN is provided.

GT.
GET EMPLOY-VIEW #ISN
    ASSIGN NAME(GT.) = #NAME
Reference: GETEX1, HOLDLOG.

Sequential file processing

READ WORK FILE

Reads data from a sequential file and is therefore only available in batch. The work file to be read is identified by the work-file-number, which relates to the JCL data definition CMWKFnn, where nn and work-file-number are the same. The record to be read may be defined as a group variable with the fields of the record defined on sublevels (recommended) or every field may be defined on the READ WORK statement. The RECORD option should always be used for efficiency. The ONCE option may be used to step through a file, no processing loop is initiated. If ONCE is used, an AT END OF FILE clause must also be used to check for the end of file.

READ WORK FILE 1 RECORD #WORK-RECORD
  .
END-WORK
Reference: RWFEX1.

WRITE WORK FILE

Writes data to a sequential file in batch. Most comments under READ WORK similarly apply. No processing loop is created by the WRITE WORK.

WRITE WORK FILE 1 #WORK-RECORD
Reference: RWFEX1, WWFEX1.

Other loop initiating statements

The following statements initiate processing loops but are not associated with file access.

FOR

Initiates a processing loop using a numeric variable for control. The variable is specified with an initial value, an increment to be added to the variable with each subsequent execution of the loop, and a termination value.

FOR #INDEX 1 TO 25           /* STEP 1 is implied
    ASSIGN #ARRAY1(#INDEX) = #ARRAY2(#INDEX+2)
END-FOR
Reference: FOREX1S, PRLOOP4.

REPEAT

Initiates a processing loop, with or without a WHILE or UNTIL clause. If no logical condition is specified for the loop, the loop must be exited by an ESCAPE BOTTOM specified within the loop.

REPEAT UNTIL #COUNT > #LIMIT
  .
END-REPEAT
Reference: RPTEX1S, RPTEX2S.

SORT

The SORT statement is used to sort items into a required order. SORT can be used online but there is only a limited amount of work space available and this practice should be avoided since you will rarely know if it will succeed. Only one SORT statement may be used per program and causes the program to be executed in three phases:

  1. Statements before the SORT statement are executed and the data to be sorted is passed off to the sort utility.
  2. The sort utility completes the sort for all records provided.
  3. The statements after the SORT are executed in a loop, with the sorted data provided in the sequence specified.

The SORT statement initiates a new processing loop which requires that all previous loops be terminated with the END-ALL statement. If there are multiple nested loops active, this one statement terminates them all. The SORT loop itself is closed with the END-SORT statement. One to ten variables may be used as the sort criteria, each in either ascending or descending sequence. The USING clause specifies all associated data that is to be sorted. You must ensure that all necessary data is sorted, an item that should have been sorted but was not will be available in the sort loop but will maintain a fixed value, the value it had the last time through the loop preceding the SORT. Within the SORT loop, automatic break processing may be used with the sort key fields.

SORT BY DEPT DESCENDING LAST-NAME ASCENDING FIRST-NAME
     USING ADDRESS SALARY(*)
Reference: SM21, SRTEX1S, STRCT2.

Program control

DECIDE FOR

Conditionally executes statements based upon a linear evaluation of conditional expressions. Components include:

DECIDE FOR FIRST CONDITION
   WHEN SALARY(1) GT #MAX-WAGE
        PERFORM AUDIT-SALARY
   WHEN NOT TITLE-CD EQ #TITLE-LIST(*)
        PERFORM AUDIT-TITLE
   WHEN NONE
        PERFORM CLEAN-BILL-HEALTH
END-DECIDE
Reference: (FIRST CONDITION) DECEX1, DEDICEFR, (EVERY CONDITION) ADD-RT, DECEX1E.

DECIDE ON

Conditionally executes statements based upon a linear evaluation of the value contained in a variable. The conditions for DECIDE FOR are also true for DECIDE ON. A DECIDE ON would be used if one variable value is to be used to make a decision, while the DECIDE FOR would be used if more than one variable is to be used to make a decision.

DECIDE ON FIRST VALUE OF #CONTROL
   WHEN VALUE 'A'
        FETCH 'ADD-RT'
   WHEN VALUE 'D'
        FETCH 'DEL-RT'
   WHEN NONE
        REINPUT 'Invalid value entered'
END-DECIDE
Reference: DECEX2, DECIDEON.

IF

Controls the execution of a statement or a group of statements based upon a logical condition. Reference Chapter 1 of the Natural Reference Manual for the numerous forms a logical condition may take.

IF #A = #B
  ASSIGN #C = TRUE
ELSE
  ASSIGN #C = FALSE
END-IF
Reference: IFEX1S.

IF SELECTION

Tests either a sequence of alphanumeric fields to determine if more than one is non-blank, or an array of logical fields to determine if more than one is TRUE.

IF SELECTION NOT UNIQUE #MENU-OPTIONS(*)
   WRITE 'Only one option may be selected'
END-IF
Reference: IFSEL.

Break processing

AT BREAK

The statements specified with the AT BREAK statement are executed when any of the following occurs:

  1. The value of the control field specified in the at break statement changes.
  2. The value of the control field specified in a higher level break statement changes (see explanation below).
  3. All records in the outermost processing loop have been processed.

If more than one break processing statement is used within a processing loop, the break statements form a hierarchy of break levels independent of whether they are specified consecutively or interspersed. The first break statement represents the lowest control level break, and each additional break statement represents the next higher control level. A high level break forces breaks at all lower levels, but only as long as the breaks are specified in the inverse sequence. See the example below.

SORT CITY LAST-NAME FIRST-NAME USING ....
     AT BREAK OF FIRST-NAME
       .
     END-BREAK
     AT BREAK OF LAST-NAME
       .
     END-BREAK
     AT BREAK OF CITY
       .
     END-BREAK
END-SORT
A break on city causes an automatic break at LAST-NAME and FIRST-NAME, a break on LAST-NAME causes an automatic break on FIRST-NAME but not on CITY. It is recommended to make multiple breaks consecutive for ease of maintenance. Reference: HEADINGS, ATBEX1S, ATBEX2, ATBEX4, SM56, STRCT2, ATBEX5S, BREAK2, SM57.

AT END OF DATA

Specifies processing to be performed after the last record has been processed for a FIND, READ, HISTOGRAM, or SORT processing loop. It must be specified within the processing loop. System functions are available for totals. The statement will not be evaluated if the processing loop is not entered.

FIND EMPLOYEES WITH DEPT = 'MARK'
   AT END OF DATA
      DISPLAY TOTAL(LEAVE-DUE)
   END-ENDDATA
END-FIND

AT START OF DATA

AT START is used to perform processing immediately after the first record has been read. If the loop contains a WHERE clause, this condition will be true when the first record which meets the criteria is read.

AT START OF DATA
   RESET #COUNTER
END-START
Reference: ASDEX1S, SM60.

Transfer of control

CALLNAT

Calls a natural subprogram for execution. The subprogram name can be specified with a literal or may be contained within an alphanumeric field evaluated at execution time. If the parameters passed do not match in format and length with those expected by the subprogram, an error results.

CALLNAT 'NSNREADU' #USER-ID #USER-NAME

FETCH

Transfers control from the currently executing program to the specified program. The name of the program to be executed can be contained within a variable. If the FETCH RETURN form is used, execution will be returned to the currently executing program at the next sequential statement.

FETCH 'NSODISPA'

PERFORM

Invokes a Natural subroutine, which will return execution to the calling program. The subroutine to be performed must be defined with a DEFINE SUBROUTINE statement and may be an internal or external subroutine.

PERFORM SUB01
Reference: PEREX1S.

Other statements

DEFINE SUBROUTINE

Defines a Natural subroutine. Subroutines are invoked with a PERFORM statement. There are two types of subroutines:

DEFINE SUBROUTINE SET-PF-KEYS
:
END-SUBROUTINE
Reference: DSREX1S, DSREX2.

END

Marks the end of a natural program and required for all programs. No statements may follow an END statement. When END is encountered in a subprogram, control will be returned to invoking program.

INCLUDE

Specifies a Natural copycode object that is to be brought in to this program at compilation time.

INCLUDE NSCPFKEY

STOP

Instructs the program to cease execution and return to the Natural command environment. This is the same state achieved when the program reaches its END statement.

TERMINATE

Terminates the Natural session, optionally with a specified return code. Normally only used in batch when a program has been passed invalid options and there is no recourse.

INPUT 'Report option (A or B):' #OPTION
IF NOT #OPTION = 'A' OR = 'B'
  WRITE 'Invalid option entered:' #OPTION
   TERMINATE (1000)
END-IF
Reference: TEREX1.

Natural Session Parameters

The Natural parameters are documented on pages 1-48 thru 1-79 of the NATURAL reference manual. They may be used with certain NATURAL statements to control such factors as:
Report size and format
Screen size and format
Input/Output formating
Record limits
The session parameters may be set in various ways:

The effective parameter settings are evaluated in the inverse sequence as that listed above. The result is that element level specifications override everything else and the default parameters are used only when nothing else has been specified.

The following session parameters are most commonly used when generating reports either online or batch. There are other session parameters which are used mostly with maps, these are discussed in the advanced class.

AL

Alphanumeric length, defines the output length for an alpha- numeric field. This is a convenient way to output a large field in a smaller space.

EM

Edit Mask, specifies an output edit mask for a numeric or an alphanumeric field. Reference: EMMASK1, EMDATI, EMMASK2, SM31, SM32, SM32A.

ES

Empty Line Suppression, used to suppress the printing of empty lines generated in a display or write statement. Reference: DISEX2, SM23, SM24, SM35, SM36, SM37.

IS

Identical Suppress, used to suppress the printing of identical information down a column. Reference: SM30, SM33, SM34.

LS

Line Size, used to indicate the maximum number of characters permitted per line for NATURAL statements DISPLAY, INPUT, PRINT, and WRITE. Reference: SM44.

PS

Page Size, identifies the maximum number of lines per page for a report created with the DISPLAY/WRITE statement. Reference: SM44.

ZD

Zero Division Check, indicates the action to be taken if an attempt is made to perform a division operation in which the divisor is zero.

ON An error message will result if an attempt to divide by zero is made.
OFF A result of zero will be returned if an attempt to divide by zero is made.
GLOBALS ZD=OFF

ZP

Zero Printing, indicates how a numeric field with a zero value is to be printed.

OFF All numeric fields with a value zero will be suppressed, and blanks are printed.
ON All numeric fields with a value zero will have one zero printed.
WRITE PERSONNEL-ID SALARY(1) (ZP=OFF)
Reference: SM33 and SM34.

Natural System Functions

System Functions may be specified in a MOVE, ASSIGN, DISPLAY, or WRITE statement which follows an AT END OF PAGE, AT BREAK, or AT END OF DATA statement. The resulting value of most of the functions will be the same format and length as the field they reference.

AVER(field)

Contains the average of all values encountered during the processing loop. AVER is updated each time the processing loop is executed.

COUNT(field)

Count is incremented by 1 each time the processing loop is executed.

MAX(field)

Contains the maximum value encountered for the field.

MIN(field)

Contains the minimum value encountered for the field.

OLD(field)

Contains the value for the field from the previous record. This reference is required with the AT BREAK if you wish to reference field values for the previous group of records. This is because when the AT BREAK is executed the record causing the break has already been loaded, even though none of the procedural statements within the loop have yet been executed. This required use of OLD is very inconvenient and often erroneously omitted. To display a department and their total salary:
AT BREAK DEPARTMENT
  WRITE 'Dept:' OLD(DEPARTMENT) SUM(SALARY)
END-BREAK

SUM(field)

Contains the sum of all values encountered for the field specified. When SUM is used following an AT BREAK condition, it is reset after each break. Only values that occur between breaks are added.

TOTAL(field)

Contains the total of all values encountered for the field during the execution of the processing loop. Total is not reset to zero when an AT BREAK condition is satisfied. Reference: ATBEX3, ATBEX4, BREAK1, SM53, SM54.

Natural System Variables

System variables which identify system level information such as the device type, the user identity, line and page size, and program identity may be referenced. The variables are found on pages 3-1 thru 3-5 of the Natural reference manual. The {} used identify optional information.

*COUNTER {(r)}

Contains the number of times a processing loop initiated by a FIND, READ or HISTOGRAM statement have been entered. The statement reference is to the statement in which the processing loop was started. If (r) is not specified, *COUNTER represents the number of times the currently active processing loop has been entered. Reference: FNDVAR, SM6, SM15.

*DATU

Contains the current date in the format mm/dd/yy. This is used most frequently in the heading of a report or on a screen. Reference: SM32A.

*DATX

Contains the date in Natural's internal date format. This date value can be displayed in any format by using the desired edit mask.

*LINE-COUNT {(x)}

Contains the line number of the current line within the current page. The reference (x) is used to specify the report for which the current line number is being requested, if other than (0).

*NUMBER {(r)}

Contains the number of records which were selected as a result of a FIND or a HISTOGRAM statement.

*PAGE-NUMBER {(x)}

Contains the current value for page number. The reference (x) is used to specify the report for which the current page number is requested, if other than (0). This variable is initialized by NATURAL when the first FORMAT, WRITE, or DISPLAY statement has been issued, for the associated report. The value is incremented by 1 whenever a page fills as a result of a WRITE or DISPLAY statement or when a NEWPAGE statement is executed. Its value may be modified, perhaps reinitialized to one at department breaks so that each department's report will be numbered from 1.

*TIME

Contains the time of day in the following format hh:mm:ss.t. This is frequently used in the title heading for documentation as to when the job was executed. Reference: SM32A and DATETIME.

*TIMX

Contains the time in Natural's internal time format. The time value can be displayed in any format by using the desired edit mask.

Day 6

The last day of the Natural Basics class is spent looking at how Natural is used to develop reports. Various aspects of reporting statements, special techniques, standards and batch execution are covered.


Natural Reporting

This section might be thought of as "tips and techniques for reporting". It attempts to show how to pull the pieces together and begin to write basic Natural report programs. Some advanced concepts are also covered however, which will hopefully prompt the imagination to develop reporting solutions.


Recommended program order

There is a common form that many report programs can conform to. The basic statements used in reporting programs and their recommended order and organization are shown in Figure 12. This is a Natural program shell found on UAEXPG as PGMORDER.

Figure 12. PGMORDER from UAEXPG


0010 ************************************************************************
0020 * Program:  Pgm name
0030 * Author :  Author's name
0040 * Written:  mm-dd-yy
0050 * Updated:  mm-dd-yy, person & change description
0060 *
0070 * Remarks:  Demonstrates the recommended order of program components.
0080 *
0090 ************************************************************************
0100 *
0110 DEFINE DATA
0120   xxxxx USING xxxxxxx
0130   xxxxx USING xxxxxxx
0140   LOCAL
0150   ...
0160 END-DEFINE
0170 *
0180 DEFINE PRINTER ...
0190 FORMAT (x) ...
0200 WRITE (x) TITLE LEFT JUSTIFIED
0210   ...
0220 *
0230 * Initialization statements/option entry
0240 *
0250   ...
0260 *
0270 * Primary data access
0280 *
0290 READ/FIND ...
0300   ...
0310 END-ALL
0320 SORT RECORDS BY ...
0330              USING ...
0340 *
0350 * Group heading/control break processing
0360 *
0370   IF BREAK OF ...          | Repeat for each heading from
0380     ...                    | major to minor
0390   END-IF                   |
0400 *
0410 * Detail record processing
0420 *
0430   ...
0440 *
0450 * Group footing/control break processing
0460 *
0470   AT BREAK OF ...          | Repeat for each footing from
0480     ...                    | minor to major
0490   END-BREAK                |
0500 *
0510 * Grand totals
0520 *
0530   AT END OF DATA
0540     ...
0550   END-ENDDATA
0560 *
0570 END-SORT
0580 *
0590 WRITE (x) / 27T '*****  End of report *****'
0600 *
0610 * All internal subroutines
0620 *
0630 DEFINE SUBROUTINE ...      | Repeated as necessary
0640   ...                      |
0650 END-SUBROUTINE             |
0660 END

Basic reporting model

The HEADINGS program in UAEXPG can be used as a model for a simple reporting program. Data is accessed, sorted, and multiple sub-headings and sub-footings are produced. This program should be thoroughly studied and understood before proceding to other assignments. Of course real life reports will be much more difficult.


UAF standards

There are few standards required for writing Natural report programs. Standard formats have been defined for page headings. As previously mentioned, the code from RPTHD80 and RPTHD132 is available for inclusion in any program by anyone. Customization is required. One item you will notice included within these code segments is an end of report notification. It is a good practice to always produce an end of report message so there is never any doubt about whether a last page is missing.

It is also recommended to use report numbers with all the report output statements. Production reports should never be output to report number 0 since they would then appear on the CMPRINT sysout which includes the Natural signon, commands and input data. This information is normally retained at Computing Services separate from the user output. Another recommend technique is to assign names to your reports with the DEFINE PRINTER statement and reference that name rather than the report number.

DEFINE PRINTER (B-SUM=1)
FORMAT (B-SUM) ...
WRITE (B-SUM) TITLE ...

It is also good programming practice to edit any input options and terminate the program if they are invalid. Include a meaningful prompt on the INPUT statemnt used to read the report options. This may include format information required for the input. This prompt may keep you from being called in to solve a problem in the middle of the night.

INPUT 'Enter report date (mm/dd/yyyy):' #REP-DATE (EM=MM/DD/YYYY)
It is also suggested that the report options used be reported somewhere. These will typically fit into the page heading of the report (i.e. date ranges) but may warrant a report of their own. This reduces doubt about the options actually used to produce a given output.

Efficiency

A primary goal should be to develop programs that are efficient in their use of Adabas, which is our scarcest resource. It is extremely easy to develop reports that perform much more data base I/O than required. In batch these programs will tend to suck up tremendous resources and tie up Adabas, leaving little time for other jobs to get executed. Sometimes this requires additional programming effort (use of sequential work files) or special design considerations (addition of descriptors to facilitate data access). You may be asked to defend your program if our system monitors detect it being an Adabas abuser.

Specific techniques that can be used to make better use of system resources follow. However, the primary factor to developing efficient programs is: "Know thy data".

Adabas Prefetch

Prefetch is an option that lets Adabas access and return entire blocks of data at one time, reducing the required number of Adabas calls and associated overhead. It typically should be used when large numbers of records are being accessed sequentially from one file. If two files are being hit alternately or updates are being performed, it should generally be avoided. Prefetch can cause the total Adabas resource requirements to go up, so it should not be used indiscriminantly. The clock time required for execution is the simplest indicator for benchmarking programs with and without prefetch (always consider other system activities of course). Prefetch is invoked by including the PROC parameter PFETCH= on the Natural step.

JS010 EXEC NATURAL,SYS=PROD,PFETCH=

Super-descriptor range selection

The primary purpose of descriptors is to facilitate the necessary data base access required for online applications. Descriptors used for this purpose are often super-descriptors. Report programs can often take advantage of the presence of these descriptors to perform record selection. If the selection is based on the first component of the super-descriptor, a bit of programming can make use of this and avoid the creation of an additional descriptor or reading the entire file.

Reference: SUPER1, SUPER2.

Do lookups at breaks

Often multiple files must be accessed so that all necessary data can be referenced. This can cause a doubling effect in terms of the data base work required when the secondary file is accessed for each record returned from the primary file. This secondary file access can be reduced if the primary data can be sorted or read in sequence of the key to the secondary file and that access performed only when the key changes. The savings is in relation to the number of secondary keys compared to the number of primary records. Occasionally tremendous savings can be gained, other times it will not be worth the effort.

Reference: SUPER3A and SUPER3B.

Multiple reports

One technique for conserving resources is to produce multiple reports during one pass of the data. Natural supports the generation of serveral reports within one program (our shop provides parameters for up to six reports before overrides would have to be used). There are usually constraints to be dealt with and it does complicate a program, but significant savings can be realized using this technique. A related approach is to pass the data base file once and write the required information to a sequential work file. The work file can then be read and sorted by many programs much more efficiently than accessing the data base.

Reference: EXPLODE.

FIND ... SORTED BY

Never use the SORTED BY option of the FIND statement. This option is extremely resource intensive for ADABAS and should always be avoided. The SORT statement should be the normal technique for sorting data for batch reports.


DISPLAY/WRITE options

Useful options available for formatting report output include:

VERT/HORIZ
IS/ES
AL/NL
ZP
SG
IC='$'
'text' heading overrides
nT/nX
T*

Reference: SM35, HEADINGS, USERDEV, COUNT10.


Reporting techniques

Counting with 1's and 0's

A useful technique for generating summary reports which include sums and counts is to define sum or count fields representing the columns of the report. These fields are reset for each record accessed and then assigned values conditionally. For example if column 2 is a count of males, the count variable would be assigned a value of 1 if SEX = 'M'. All report output is then generated within an AT BREAK of whatever grouping desired and the OLD(sort-value) displayed along with the SUM(male-count).

Reference: COUNT10

Creating sort fields

Often users require reports to be output in strange sequences that do not directly correspond to the data. These reports can be accommodated by defining a sort field which is program set according to the users criteria. The values used can be meaningless: 10, 20, 30 or A1, A2, B1, B2, B3.

Reference: COUNT10A.

Exploding data

Occasionally it is desirable to process one record two or more times, usually to see it reported in multiple places. A record may also need to be processed two or more times selectively. This can be accomplished by initiating a nested loop with a FOR or REPEAT statement that is terminated by an END-ALL. The ESCAPE statement can be used within the loop to control conditional creation of records. (This works because a record is passed to the sort each time the END-ALL is encountered.)

Reference: EXPLODE.

Simulating multiple sorts

The technique for exploding data can also be used to simulate multiple sorts in one program. As you are aware, Natural only allows one SORT statement per program. If you wish to produce two reports from one set of data, each sorted differently, the typical approach would be to write two programs and read the data base data twice. This is a waste of Adabas resources. One solution is to develop an extract program that reads the data and writes it to a work file. The two report programs can then be coded to read the information from the work file. Another alternative is to simulate the two sorts within one program as follows:

  1. Define a local field, #REPORT (N1).
  2. Define a generic sort field large enough to contain the sort values for both reports, #SORT (A..)
  3. At the end of the data access loop, initiate a FOR #REPORT = 1 TO 2 to explode the data record and pass it twice to the sort.
  4. Within the FOR loop, conditionally assign #SORT the appropriate values based upon #REPORT.
  5. SORT BY #REPORT #SORT USING ... The using fields must include all elements needed for either the first or second report.
  6. Following the SORT, conditionally process the data:
    IF #REPORT = 1
      DISPLAY (RPT1) ...
    ELSE
      DISPLAY (RPT2) ...
    END-IF
    
  7. Break processing can also be included although it is slightly complicated by the additional sort field #REPORT and the generic sort field #SORT.

Dynamic PE/MU occurrence specification

If you happen to have to deal with large number of occurrences of PE or MU fields, you may want to dynamically establish which occurrences will be read with each data access. This is often best since very large record buffers are not efficient for Adabas or Natural. For example, an A72 MU field may allow storage of 100+ occurrences even though typically only a few are used. It is better to divide the occurrences into sets and process them in those groups, doing additional data base accesses for each group. To do this requires a data area similar to:
1 #OCC (I2)
1 f-VIEW VIEW OF file
2 C*text-field
2 text-field (#OCC:#OCC+9)
The variable #OCC is assigned 1, 11, 21 or whatever the first occurrence is for the set desired. The data access statement using this view will then return those 10 occurrences.

Note: The C*text-field will identify how many occurrences exist and allow the program to control how many sets are requested.


Debugging

Natural V2.1 provides very little assistance to the programmer in debugging. Version 2.2 will include facilities like break point setting and variable examination tools. The following are suggestions for aiding in this area.

Program correction

When Natural detects a compile error either during a CHECK, STOW or CAT it displays the line expected to contain the error and an error message. This program text line appears in Natural's message line, where it can be immediately modified. This is much faster than pressing ENTER and positioning to that line to make corrections via normal edit methods.

LIMIT/LT/(n)

It is usually simplest to debug programs by using limited quantities of test data, at least initially in unit testing. Natural provides several facilities for limiting the number of records that are processed.

LIMIT

The LIMIT statement can appear in a program and will restrict to the constant value specified the number of records accessed with a FIND, READ or HISTOGRAM.

LT

This is a session parameter which may be set at Natural initialization, by using the GLOBALS command, or via Natural Security. It has the same effect as the LIMIT statement except it applies universally to all programs.

(n)

A limit to the number of records accessed by FIND, READ and HISTOGRAM can also be specified explicitly for each statement. This is accomplished by using the (n) clause immediated after the statement. Actually the limit can also be a program variable set dynamically.

READ (#RD-LT) ...

Sprinkle WRITEs

One of the crudest methods of debugging, but the one most often used is to imbed WRITE statements within the program so that the flow of the program and variable values can be tracked. If you are developing online programs, it is usually best to use the INPUT statement specifying the variables as output elements.

Hex output

Often a program does not behave as you expected and there does not appear to be any reason. Possibly an IF test that logically cannot be evaluated the way it seems to be. In this circumstance, it is beneficial to display the affected variables in hex so there exact contents can be examined. Sometimes the data is not as it appears. This is easily done using the edit mask facility.

WRITE #FIELD1 (EM=HHHH) #FIELD2 (EM=HHHH)

HISTOGRAMs

The histogram statement is very useful for gaining a true understanding of descriptor values. Complex descriptors such as super-descriptors or descriptors derived from PE elements can sometime be a problem to use. To see exactly what is in the inverted list write a simple program to perform a histogram. Often the descriptor value will need to be output in hex to reveal its true contents. This process is also useful to debug a new descriptor that may not have gotten defined exactly as you wished.

OUTPUT SOURCE

Programs that produce output to reports 1-32 cannot normally be executed online. Since this is the standard for output for production reports, these programs typically have to be tested using batch. One way of allowing such programs to run online is by using the OUTPUT SOURCE option with the DEFINE PRINTER statement. This results in the report output being appended to the source work area. The first 72 bytes of that output can then be examined using the program editor. Before executing the program, be sure to CLEAR the work area so that the report output is not appended to the object currently in the work area.

DEFINE PRINTER (RPT-1=1) OUTPUT 'SOURCE'



Appendix A. UAEXPG Sample program library

Table 5 is a list of the sample NATURAL 2 programs that can be found in the Natural library UAEXPG. This list is in alphabetical order according to the function demonstrated by the sample program. Please be aware that some programs may not work. These are provided for demonstration and experimentation purposes. Do not change the programs within the UAEXPG library, they may be copied to personal libraries where altered versions may be saved.

Table 5. Example Natural programs in UAEXPG

Function Object Type
Accept ACREX1S Program
Accept / Reject ACREX2S Program
Accept / Reject SM17 Program
Accept / Reject SM18 Program
Accept / Reject SM19 Program
Add (Compute) ADDEX1 Program
Array Arithmetic ARRAY1 Program
Array Arithmetic ARRAY2 Program
Array Initialization ARAYINIT Program
Array Printing ARRAY1 Program
Array Processing ADDEX1 Program
Array Processing ARRAYE Program
Array Processing ARRAY1 Program
Array Processing ARRAY3 Program
Array Processing (MU/PE Groups) ARRAYD Program
Array Processing (MU/PE Groups) UPDMORE Program
Assign ASGEX1S Program
At Break HEADINGS Program
At Break ATBEX1S Program
At Break STRCT2 Program
At Break (Multiple Breaks) ATBEX5S Program
At Break (Multiple Breaks) BREAK2 Program
At Break (Multiple Breaks) SM57 Program
At Break (System Functions) COUNT10 Program
At Break (System Functions) ATBEX3 Program
At Break (System Functions) ATBEX4 Program
At Break (System Functions) BREAK1 Program
At Break (System Functions) SM53 Program
At Break (System Functions) SM54 Program
At Break /n/ ATBEX2 Program
At Break /n/ SM56 Program
At End of Data AEDEX1S Program
At End of Data SM58 Program
At End of Page AEPEX1S Program
At End of Page SM55 Program
At End of Page SM59 Program
At End of Page with Input AEPEX2 Program
At Start of Data ASDEX1S Program
At Start of Data SM60 Program
At Top of Page ATPEX1S Program
At Top of Page SM61 Program
Backout Transaction BOTEX1S Program
Before Break Processing BBPEX1 Program
Before Break Processing BREAK3 Program
Before Break Processing SM62 Program
C* GSAEX1 Program
C* UPDMORE Program
Call CALEX1 Program
Call CALEX2 Program
Call CALEX3 Program
Call File CFIEX1 Program
CallNat CALLNAT Program
CallNat CNTEX1 Program
CallNat CNTEX2 Program
CallNat PGM01 Program
CallNat SKYEX1 Program
Compress CMPEX1S Program
Compute COMPUTE Program
Compute CPTEX1S Program
Control Variable LCCMOD Program
Copy Code COPY1 Copycode
Copy Code COPY2 Copycode
Copy Code Program COPYPGM Program
Copycode COPYPGM Program
Date / Time Edit Masks DATETIME Program
Date / Time Edit Masks DATEMASK Program
Date / Time System Functions SM32A Program
Date Formatting DATEFORM Program
Decide For DECEX1 Program
Decide For DECIDEFR Program
Decide For HLPHOBBY Program
Decide For STRCT1 Program
Decide For (Every) ADD-RT Program
Decide For (Every) DECEX1E Program
Decide For (Every) PUR-RT Program
Decide For (Every) UPD-RT Program
Decide On DECEX2 Program
Decide On DECIDEON Program
Decide On (Every) DECEX2E Program
Decide On (Every) FETEX1 Program
Decide On (Every) SKYEX1 Program
Define Data DDAEX1 Program
Define Data (Arrays) DDAEX2 Program
Define Data (External) DATATWO Program
Define Data (Internal) CALLNAT Program
Define Data (Internal) DATAONE Program
Define Data (Subroutine) DDAEX4 Subroutine
Define Data (View Definition) DDAEX3 Program
Define Data Parameter (Internal) CALLSUB Program
Define Printer DPREX1 Program
Define Printer SM26 Program
Define Subroutine DSREX1S Program
Define Subroutine (External) DSREX2 Subroutine
Delete DELEX1S Program
Delete PUR-RT Program
Delete (Multiple Files) DELEX2S Program
Display (Give System Functions) DISEX2 Program
Display / Write SM23 Program
Display / Write SM24 Program
Display Vert SM35 Program
Display Vert As 'Text' SM36 Program
Display Vert As 'Text' Captioned SM37 Program
Divide DIVEX1 Program
Dynamic Source Creation FIND-EMP Program
Dynamic Source Creation PROC-EMP Program
Dynamic Source Creation RUNEX1 Program
Edit Masks EMMASK1 Program
Edit Masks (Date / Time) EMDATI Program
Edit Masks (Date / Time) DATETIME Program
Edit Masks (Date / Time) DATEFORM Program
Edit Masks (Date / Time) DATEMASK Program
Edit Masks (Date / Time) SM32A Program
Edit Masks (HEX) EMMASK2 Program
Edit Masks - Alphanumeric SM31 Program
Edit Masks - numeric SM32 Program
Eject EJTEX1 Program
End Transaction ETREX1S Program
End Transaction RESTART Program
End Transaction (with ET data) ETREX2 Program
Escape ESCAPE Program
Escape ESCEX1S Program
Examine EXAMINE Program
Examine EXMEX1 Program
Examine HLPHOBBY Program
Fetch (Calling Program) FETEX1 Program
Fetch (Fetched program) ADD-RT Program
Fetch (Fetched program) PUR-RT Program
Fetch (Fetched program) UPD-RT Program
Find SM4 Program
Find STRCT2 Program
Find (Cipher Clause) FNDCIP Program
Find (Coupled Files) FNDCPL Program
Find (Coupled Files) SM13 Program
Find (If No Records Found) FNDIFN Program
Find (If No Records Found) SM7 Program
Find (Limit) SM5 Program
Find (Multiple Files) FNDMUL Program
Find (Multiple files) PRLOOP1 Program
Find (Multiple files) SM14 Program
Find (Password) FNDPWD Program
Find (Password) FNDPW1 Program
Find (Retain) FNDRET Program
Find (Retain) SM9 Program
Find (Superdescriptor range) SUPER1 Program
Find (System Variables) FNDVAR Program
Find (System Variables) SM6 Program
Find (Where) FNDWHE Program
Find / Find PRLOOP2 Program
Find / Read (Qualified Names) PRLOOP3A Program
Find / Read (Statement Numbers) PRLOOP3B Program
Find / Read (Statement References) PRLOOP3 Program
Find Number SM8 Program
Find Number / Read DEMOLOOK Program
Find Number / Read EMPLOOK Program
For FOREX1S Program
For PRLOOP4 Program
For Loop ARRAY3 Program
Format FMTEX1 Program
Get GETEX1 Program
Get HOLDLOG Program
Get Same GSAEX1 Program
Get Same GSAEX1S Program
Get Transaction Data GTREX1S Program
Get Transaction Data RESTART Program
Global Criteria FIND-EMP Program
Global Criteria PROC-EMP Program
Global Criteria RUNEX1 Program
Global Data Area GDA01 Global
Global Data Area GDA1 Global
Global Data Area GLOBDATA Global
Global Data Area GLOBPGM Program
Global Data Area SUBGLOB Global
Global Data Area (Map Processing) DEMOVIEW Global
Header suppression SM29 Program
Header underline SM28 Program
Header width SM27 Program
Help Processing HELP01 Map
Help Processing HLPHOBBY Helproutine
Help Processing HLPMAP Map
Help Processing HLPMPGM Program
Help Processing HLPRTN Helproutine
Help Processing HLPSEX Helproutine
Help Processing HLPTEST Program
Histogram CALLSUB Program
Histogram HSTEX1S Program
Histogram SM16 Program
Identical suppress SM30 Program
Identical suppress SM33 Program
Identical suppress SM34 Program
If IFEX1S Program
IF BREAK OF HEADINGS Program
If is CHECKIS Program
If Selection IFSEL Program
Include INCEX1 Program
Input FETEX1 Program
Input IPTEX1 Program
Input PROG001 Program
Input PROG002 Program
Input PUR-RT Program
Input REIEX1 Program
Input SM22 Program
Input STRCT1 Program
Input Using Map ADD-RT Program
Input Using Map IPTEX2 Program
Input Using Map PROG001 Program
Input Using Map PROG002 Program
Input Using Map REIEX2 Program
Insert/Leading/Trailing SM30 Program
Integer Field INTEGER Program
Limit LMTEX1 Program
Limit SM20 Program
Local Data Area LDA01 Local
Local Data Area LDA02 Local
Local Data Area LOCDATA Local
Local Data Area PERSONVW Local
Local Data Area PERSONVW Local
Logical Condition Using Format LCCFMT Program
Logical Condition Using Logical Variable LCCLOG Program
Logical Condition Using Mask Option LCCMASK Program
Logical Condition Using Scan LCCSCAN Program
Logical Conditon Using Break HEADINGS Program
Logical Conditon Using Break LCCBRK Program
Logical Conditon Using Modified Field LCCMOD Program
Logical Field LOGICAL Program
Logical Variable EMLOGV Program
Map Processing DEMOMAP Map
Map Processing DEMOMAP1 Map
Map Processing DEMOMPGM Program
Map Processing DEMOPGM1 Program
Map Processing MAP001X Map
Map Processing MAP002X Map
Map Processing MAP003X Map
Map Processing MAP01 Map
Mathematical Functions MATHEX Program
Move All MOAEX1 Program
Move By Name MOVENAME Program
Move By Name SUPER3A Program
Move Edited DATEFORM Program
Multiple Reports per Program EXPLODE Program
Multiply MULEX1 Program
Newpage NWPEX1S Program
On Error ONEEX1 Program
On Error ONERROR Program
On Error RTYEX1S Program
Page Layout - Changing defaults SM45 Program
Page Layout - Default page layout SM44 Program
Page Layout - Line advance SM50 Program
Page Layout - Line advance SM51 Program
Page Layout - Line advance SM52 Program
Page Layout - Page advance SM49 Program
Page Layout - Page numbering SM48 Program
Page Layout - Titles and trailers SM46 Program
Page Layout - Titles and trailers SM47 Program
Parameter Data Area PDA02 Parameter
Passw PWDEX1 Program
Perform PEREX1S Program
Perform Break Processing BREAK4 Program
Perform Break Processing PBPEX1 Program
Position tabulation SM42 Program
Position tabulation SM43 Program
Print PRTEX1 Program
Read (Physical) REAEX1S Program
Read / Find REAEX2 Program
Read / Find combination SM15 Program
Read ISN SM3 Program
Read Logical SM2 Program
Read Logical via Superdescriptor SUPER2 Program
Read Physical SM1 Program
Read Work File RWFEX1 Program
Reinput PROG001 Program
Reinput PROG002 Program
Reinput PUR-RT Program
Reinput REIEX1 Program
Reinput SM22 Program
Reinput STRCT1 Program
Reinput with Attributes ADD-RT Program
Reinput with Attributes REIEX2 Program
Reinput with Attributes UPD-RT Program
Repeat RPTEX1S Program
Repeat STRCT1 Program
Repeat (While, Until) RPTEX2S Program
Report (Generated Online) PROG001 Program
Report (Generated Online) PROG002 Program
Report Notation SM25 Program
Reset RSTEX1 Program
Restartable Program RESTART Program
Retain FIND-EMP Program
Retry RTYEX1S Program
Return Code INTEGER Program
Run RUNEX1 Program
Scan Statment LCCSCAN Program
Select List Processing FIND-EMP Program
Select List Processing PROC-EMP Program
Select List Processing RUNEX1 Program
Separate SEPEX1 Program
Separate (Using an Array) SEPEX2 Program
Set Key DEMOMAP Map
Set Key DEMOMPGM Program
Set Key SKYEX1 Program
Settime STIEX1 Program
Sort HEADINGS Program
Sort EXPLODE Program
Sort SM21 Program
Sort SRTEX1S Program
Sort STRCT2 Program
Sort on User Defined Field COUNT10A Program
Store ADD-RT Program
Store SM22 Program
Store STOEX1 Program
Store STORE Program
Subprogram CALLSUB Program
Subprogram SPGM02 Subprogram
Subprogram UPD-SUB Subprogram
Subroutine PROGWSUB Program
Subroutine SUBR01 Subroutine
Subroutine (External) EXTSUB Subroutine
Subtraction SUBEX1 Program
Suspend Identical Suppress SISEX1 Program
Suspend Identical Suppress SISEX2 Program
SYSERR messages N2SYSERR Program
Terminate TEREX1 Program
Time / Date System Functions SM32A Program
Update Data Base Field HOLDLOG Program
Update Data Base Field UPD-RT Program
Update Data Base Field UPDEX1S Program
Update Data Base Field (MU/PE Groups) UPDMORE Program
User-supplied text SM38 Program
User-supplied text SM39 Program
User-supplied text SM40 Program
User-supplied text SM41 Program
Windows (Pop up) POPUP Program
Windows (Program) WINDOW Program
Write Using Map PROG002 Program
Write Using Map PROG002 Program
Write Work File SUPER3A Program
Write Work File RWFEX1 Program
Write Work File WWFEX1 Program
*COUNTER SM15 Program
*COUNTER SM6 Program
*COUNTER FNDVAR Program
*NUMBER SM15 Program
*NUMBER SM8 Program
*NUMBER FNDVAR Program
*NUMBER SM6 Program
*ISN SM15 Program
*ISN SM6 Program
*ISN FNDVAR Program

Appendix B. Assignments


Day 1

Name: _________________________

  1. What is the operating system under which the university runs Natural?
  2. What system software product(s) provides interactive timesharing like facilities for MVS?
  3. How many Adabas data bases do we have? How are they named?
  4. During prime working hours does batch production work have priority over online development and testing?
  5. Name a task which should not or could not be run under CICS? Why not?
  6. What key do you press on "your" keyboard to invoke the 3270 Clear key function?
  7. What is an attribute byte?
  8. What is ADABAS the acronym for?
  9. What is an Adabas feature that allows new fields to be easily added to an existing file?
  10. What data storage features make Adabas non-relational (non 3rd normal form)?
  11. What is the Adabas name for an index and where are these stored?
  12. How many Adabas files can be managed by one Adabas data base?
  13. What is Adabas's unique identifier for the EMPLOYEES file?
  14. What are the Adabas names for the two periodic groups defined on the EMPLOYEES file?
  15. What are the descriptors that have been defined on the EMPLOYEES file?
  16. What descriptor from the EMPLOYEES file cannot be used with an Adabas read logical statement?
  17. Provided data storage is as depicted in Table 1, how many data blocks must be read to retrieve all records with DEPT = 'MARK'?
  18. Provided data storage is as depicted in Table 1, what information would be returned from Adabas if a HISTOGRAM were performed on descriptor DEPARTMENT?
  19. What data compression option should always be used for fields of a periodic group?
  20. What is the most efficient Adabas command to verify the existence of a key value?
  21. Which buffer does Adabas place data into following a file access command?

Day 2

Name: _________________________

  1. What is SYSDIC?
  2. What is Predict's term for a field of information contained on a file?
  3. What is a DDM and how is it used?
  4. Where is cross-reference information stored and when is it created?
  5. What allows Natural to operate differently for one user than it does for another?
  6. Where are Natural programs stored? Where are they executed from? Where do they reside when they are being edited?
  7. What is FDIC?
  8. How are the Natural applications delivered by Software AG identified?
  9. What is the application framework that is used for the development of Natural applications at UAF?
  10. What key can be pressed (on the test system) to terminate the execution of a Natural program?
  11. What is auto logging?
  12. Where are system functions and system variables found in the Natural Reference Manual? What is the difference between these?
  13. Computing Services encourages the use of ____________________ mode Natural programs.
  14. What Natural object(s) would use a PDA?
  15. What information can be obtained from the name of a Natural object?

This page intentionally left blank.


Day 3

Name: _________________________

  1. What character is entered to quit out of most of Software AG's systems?
  2. What is the difference between executing a program by entering its name as a command versus issueing the RUN command?
  3. Use the ___________________ command to determine when an object was last compiled.
  4. Where is the source for a program placed while editing in Natural?
  5. What terminal control command will stop the execution of a Natural program which is equivalent to pressing the CLEAR key on the test system?
  6. What object management command(s) does Natural seem to be missing?
  7. Match the NATURAL command with the appropriate function. There may be more than one function per command.
    COMMANDS             FUNCTIONS
     
        __ CREATE           1) deletes source module
        __ SAVE             2) logs user off NATURAL
        __ PURGE            3) deletes object module
        __ UNCATALOG        4) stores work area as a source module
        __ CHECK            5) deletes work area
        __ FIN              6) forms a new object
        __ EDIT             7) moves source module to work area
        __ CLEAR            8) stores work area as an object module
        __ READ             9) confirms work area syntax
        __ SCRATCH
        __ STOW
        __ CATALOG
    
  8. Identify the use of each of the following edit line commands:
    .x
    .mx
    .cx-y
    .d
    .i(prog1,12,5)
  9. Logon to NATURAL and attempt to access the UAEXPG library.
  10. What is your Natural user ID?
  11. Modify and save your personal program editor profile.
  12. From the program editor, create a split screen with the EMPLOYEES view in it.
  13. Experiment entering text into the program editor and making changes to the text. Save the text as a Natural object.
  14. Create a local data area in a development library containing a view of the EMPLOYEES file.

Day 4

  1. Create programs to read 20 records from EMPLOYEES using the following three access methods:
    A)  READ BY ISN
    B)  READ LOGICAL BY PERSONNEL-ID
    C)  READ PHYSICAL
    
    Display personnel number, first name, last name, *ISN.
  2. Create a program that will read the EMPLOYEES file accessing only records with given DEPT which is entered at execution. Display the personnel number, first name, last name, job title and salary.
  3. Create a program to allow a city to be entered interactively and list the PERSONNEL-ID FIRST-NAME NAME ADDRESS-LINE (1-3) for the people within the file EMPLOYEES who have that value in their CITY field. Display a total count or a message indicating that there were no records for that city. Run the program for Boston, Madrid, Los Angelas, and Los Angeles.

Day 5

  1. Create a program that will display all the employees who speak French (LANG = FRE). Modify the program and add the qualification that COUNTRY is USA. Display personnel id, first and last name, city and country, and their first three languages.
  2. Access the VEHICLES file and find every employee whose vehicle make is BMW. Display the personnel number, first name, last name, make, model, and department for these employees. Have the output sorted by department, last name, and first name order.
  3. Display the personnel-id, first name, last name, vehicle make, and vehicle model, and vehicle registration number for all those persons in the department MGMT00. If the person does not have a vehicle display NO VEHICLE in the make column.
  4. Change the output within any of your previous programs from a DISPLAY to a WRITE and notice some of the differences between the two statements.

Day 6

  1. Access the employees file and find all those employees in department VENT00 thru VENT07 who have more than 20 hours of leave due. Display the personnel number, last name, department, and leave due for each person. For each department display the count, average, and total leave due for those employees selected. At the end of the program display a count, average, and total for the entire company.
  2. Create a system that will allow a department to be entered interactivly and then one of three possible output formats may be selected. The first format will display dept, personnel-id, last-name, birth, and salary. The second format will display last-name, first-name, city, phone, and zip. The third format display first-name, make, dept, and job-title. Use an INPUT statement in the main program to enter a code, and the search field. Then, display the data in a subroutine or subprogram. After displaying the data, allow the user to select another code and dept.