SheerPower® 4GL
A Guide to the SheerPower Language
Previous Contents Index

DESCRIPTION:

ADD STRUCTURE adds a record to a structure. The ADD STRUCTURE statement begins the add block. struc_name is the name associated with the structure that the record is going to be added to. END ADD marks the end of the block.

When ADD STRUCTURE is executed, SheerPower executes the block of code between the ADD STRUCTURE statement and END ADD. This block of code with LET statements is used to put data into the fields.

LET assigns a value to the field specified. struc_name(field) specifies a field in the structure. expr is an expression. When SheerPower executes the LET statement, it evaluates the expression and assigns the value of this expression to the field specified. END ADD writes out the new record.

15.4.1 CANCEL ADD

FORMAT:


        CANCEL ADD

EXAMPLE:

Example 15-6 CANCEL ADD - Cancel adding a structure record 

  open structure cl: name 'sheerpower:samples\client', access outin
  add structure cl 
    input 'Client ID': cl(id) 
    if  _exit  then cancel add
    input 'Last name': cl(last) 
    if  _exit  then cancel add
    input 'First name': cl(first) 
    if  _exit  then cancel add
    print 'Adding client' 
  end add
  end
 
 
Client ID? 14422 
Last name? White 
First name? exit

DESCRIPTION:

CANCEL ADD immediately transfers control to the next statement after the END ADD statement, without adding any of the current record to a structure.

This statement can be used only within an ADD block---that is, between an ADD STRUCTURE and an END ADD pair of statements.

15.4.2 EXIT ADD

FORMAT:


        EXIT ADD

EXAMPLE:

Example 15-7 EXIT ADD - Exit when adding a structure record 

  open structure cl: name 'sheerpower:samples\client', access outin
  add structure cl 
    input 'Client ID ': cl(id) 
    input 'Last name ': cl(last) 
    input 'First name': cl(first) 
    input 'Contact   ': cl(contact) 
    if  _exit  then exit add
    input 'Salesman  ': cl(salesman) 
    input 'Mother    ': cl(mother) 
    input 'Comment   ': cl(comment) 
  end add
  print 'Client added' 
  end
 
 
Client ID ? 11111 
Last name ? Hollerith 
First name? Herman 
Contact   ? exit 
Client added

DESCRIPTION:

EXIT ADD transfers control immediately to the corresponding END ADD statement and ADDS the record to the structure.

This statement is useful when you want to add a record but do not have all the data. You can enter data into the first few fields and skip the rest of the fields.

15.5 DELETE STRUCTURE

FORMAT:


        DELETE STRUCTURE struc_name

EXAMPLE:

Example 15-8 DELETE STRUCTURE - Delete structure record 

  open structure cl: name 'sheerpower:samples\client', access outin
  add structure cl 
    input 'Client ID ': cl(id) 
    input 'Last name ': cl(last) 
    input 'First name': cl(first) 
    input 'Contact   ': cl(contact) 
    input 'State     ': cl(state) 
  end add
  print 'Client added' 
  delay  
  extract structure cl 
    include cl(state) = 'PA' 
  end extract
  // delete all clients from Pennsylvania 
  for each cl 
    print 'Deleting '; cl(first); ' '; cl(last) ;'...'; 
    delete structure cl 
    print 'record deleted' 
  next cl 
  close structure cl 
  end
 
 
Client ID ? 87433 
Last name ? Shores 
First name? Sandy 
Contact   ? 8435557373 
State     ? PA 
Client added 
Deleting Sandy Shores...record deleted

DESCRIPTION:

DELETE STRUCTURE deletes the current record from the specified structure. struc_name is the structure name associated with the structure that the record is going to be deleted from.

15.6 LOCK | UNLOCK STRUCTURE

FORMAT:


        [LOCK | UNLOCK] STRUCTURE struc_name

EXAMPLE:

Example 15-9 LOCK/UNLOCK STRUCTURE 

  open structure cl: name 'sheerpower:samples\client', access outin
  extract structure cl 
    include cl(state) = 'CA' 
  end extract
  for each cl 
    print
    print cl(first); ' '; cl(last) 
    lock structure cl   // give us exclusive access 
    line input default cl(phone), prompt 'Enter new phone ': phone$ 
    if  _exit  then exit for 
    cl(phone) = phone$ 
    unlock structure cl // put the record out to disk 
                        // and release it 
  next cl 
  close structure cl 
  end
 
 
 
Keith Kent 
Enter new phone 6199675021 
 
Paul Johnson 
Enter new phone EXIT

DESCRIPTION:

LOCK/UNLOCK STRUCTURE can be used to lock or unlock the data record currently being accessed. SheerPower automatically locks and unlocks data when you work with it. LOCK and UNLOCK override SheerPower's automatic locking features allowing you to do it manually.

LOCK STRUCTURE locks the data currently being accessed, giving the program exclusive access to the current record. No one else can access the data until it is unlocked.

UNLOCK STRUCTURE unlocks the current record or data. The record is put to disk (if needed) and can again be accessed by others.

struc_name is the structure name associated with the structure.

15.6.1 UNLOCK STRUCTURE: COMMIT | UNLOCK ALL: COMMIT

FORMAT:


        [UNLOCK] STRUCTURE struc_name: COMMIT 
        [UNLOCK] ALL: COMMIT

EXAMPLE:

Example 15-10 UNLOCK STRUCTURE: COMMIT 

  unlock structure payroll: commit

EXAMPLE:

Example 15-11 UNLOCK ALL: COMMIT 

  unlock all: commit

DESCRIPTION:

COMMIT tells both ARS and the underlying operating system to write all cached data to disk. Using UNLOCK ALL with COMMIT causes the data on all structures in the program to be written to disk.

15.7 EXTRACT STRUCTURE

FORMAT:


        EXTRACT STRUCTURE struc_name 
                ---  block of code 
          [INCLUDE | EXCLUDE] cond_expr 
          [SORT [ASCENDING | DESCENDING] BY expression] 
                --- 
        END EXTRACT

EXAMPLE:

Example 15-12 EXTRACT STRUCTURE - Extracting records from a structure 

  open structure cl: name 'sheerpower:samples\client' 
  print 'List of Clients' 
  print
  extract structure cl 
    print cl(first); ' '; cl(last), cl(phone) 
  end extract
  close structure cl 
  end
 
 
List of Clients 
 
Earl Errant         (408) 844-7676 
Al Abott            (202) 566-9892 
Bud Brock           (218) 555-4322 
Cathy Cass          (619) 743-8582 
Dale Derringer      (818) 223-9014 
Fred Farmer         (305) 552-7872

DESCRIPTION:

When SheerPower does an extract, it examines each record in the structure. For each record, SheerPower executes the code between the EXTRACT STRUCTURE and END EXTRACT statements. For instance, here is a structure with client information: 


              ID #     LAST       FIRST      CITY      STATE  PHONE 
            +------+-----------+--------+--------------+--+----------+ 
            |80543 |Cass       |Cathy   | San Diego    |CA|6197438582| 
            |80542 |Brock      |Bud     | Duluth       |MN|2185554322| 
            |80522 |Errant     |Earl    | Monterey     |CA|4088447676| 
            |80561 |Derringer  |Dale    | Los Angeles  |CA|8182239014| 
            |80531 |Abott      |Al      | New York     |NY|2025669892| 
            |80573 |Farmer     |Fred    | Miami        |FL|3055527872|

EXTRACT creates a list of clients. The above program example extracts information from each record in the structure and displays each client's name and phone number.

When SheerPower does an extract, it examines each record of the structure in order. If the KEY option is specified, only those records with a key matching the KEY expression are examined. For each examined record, the following is done:

  1. Each INCLUDE and EXCLUDE statement is checked in turn. The examined record is not extracted if an INCLUDE statement evaluates to FALSE, or an EXCLUDE statement evaluates to TRUE.
  2. If any SORT specifications are given, a sort key is built using the SORT expression as the key. If no SORT specifications are given, the record is immediately extracted.
  3. When all records have been examined, the sort keys, if any, are sorted.

SheerPower then builds a list of extracted records. This list can be accessed later with a FOR EACH loop. You can have up to 16 sort keys and 32 extract criteria.

Previous Next Contents Index