Sheerpower®
A Guide to the Sheerpower Language


Previous Contents Index


Chapter 15
Data Structure Statements

This chapter explains the SheerPower data structure statements. One of the major features of SheerPower is its ability to perform database operations as part of the language. The data structure statements allow you to manipulate data structures in your own programs.

List of Data Structure Statements:

OPEN STRUCTURE
CLOSE STRUCTURE
EXTRACT STRUCTURE
REEXTRACT STRUCTURE
CANCEL EXTRACT
ADD STRUCTURE
DELETE STRUCTURE
INCLUDE
EXCLUDE
SORT
FOR EACH
ASK STRUCTURE
SET STRUCTURE
LOCK STRUCTURE
UNLOCK STRUCTURE
UNLOCK STRUCTURE: COMMIT
UNLOCK ALL: COMMIT

In all data structure statements, the word TABLE can be used interchangeably with STRUCTURE. For example:


  OPEN STRUCTURE 
  
is the same as 
  
  OPEN TABLE 

15.1 General Information

SheerPower's data management system stores data file information in structures. (Chapter 16, Database Setup tells how structures are created.) A structure file contains the following information:

In SheerPower, you address the structure file and not the dataset directly.

A SheerPower structure is made up of records and fields. A structure looks something like this:

Example 15-1 Data Structure DIAGRAM

 
                                       FIELDS 
 
                           /              |                \
                          /               |                 \
                         /                |                  \
                        /                 |                   \
                       /                  |                    \
 
      R          Client         Last name                  First name 
      E          Number                                  
      C       +---------+---------------------------+-------------------+ 
      O _____ |8|0|5|4|3|C|a|s|s| | | | | | | | | | |C|a|t|h|y| | | | | | 
      R _____ |8|0|5|4|2|B|r|o|c|k| | | | | | | | | |B|u|d| | | | | | | | 
      D       | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 
      S 
                                     positions 

In the above example, the records are the horizontal lines of information. In the CLIENT structure above, there is a record for each customer.

Each record consists of fields. For example, the customer records alone might contain a field for the customer's ID number, last name, first name, address, phone number, company name, etc. Each of these pieces of data is stored in its own field---the name field, address field, phone number field, etc. The fields appear as columns in the diagram above.

To reference a field, indicate the structure and the desired field. The field name is enclosed in parentheses.


        struc_name(field_name) 

struc_name is the name associated with the structure. field_name is the name of a field in the structure. SheerPower searches for the field specified in the current record and reads its contents.

Example 15-2 SheerPower structure

  open structure cl: name 'sheerpower:samples\client' 
  extract structure cl: key id = '80522' 
    print cl(last), cl(first) // print last and first 
                              // fields from the CL structure 
  end extract
  close structure cl 
  end
 
 
Errant             Earl 

The remainder of this chapter describes the data structure statements and how to use them.

15.2 OPEN STRUCTURE

FORMAT:


        OPEN STRUCTURE struc_name: NAME 'struc_filename' 
          [, ACCESS INPUT | OUTIN] [, LOCK] [, DATAFILE filename] 
          [, OPTIMIZE OFF] 

EXAMPLE:

Example 15-3 OPEN STRUCTURE

  open structure cl: name 'sheerpower:samples\client', & 
    access input, lock    
  extract structure cl 
    include cl(state) = 'CA' 
    exclude cl(phone)[1:3] = '619' 
    sort ascending by cl(last) 
  end extract
  print 'List of California clients by last name' 
  for each cl 
    print cl(first); ' '; cl(last), cl(phone) 
  next cl 
  close structure cl 
  end
 
 
List of California clients by last name 
Dale Derringer      (818) 223-9014 
Earl Errant         (408) 844-7676 

DESCRIPTION:

The OPEN STRUCTURE statement is used to open a data structure. The structure must be open in order to reference data in the structure (i.e. change field data, add or delete records). struc_name is a name (i.e. nickname) you assign to the structure. You use this name to refer to the structure within the program. The structure name must be unique within the program or program system. If the structure name is associated with another open structure, an exception is generated. The structure name must meet the requirements for variable names.

After the keyword NAME, is the file specification of the structure file being opened. (See Chapter 16, Database Setup for information on legal structure file names.) The file specification can be any valid string expression.

The ACCESS option tells SheerPower whether to open the structure for input (reading field data) or for input and output (reading, changing and adding field data). ACCESS input is the default open mode for structures, meaning, that if no ACCESS option is provided, SheerPower opens the structure for INPUT.

When SheerPower executes the OPEN statement, it searches for the structure file specified. SheerPower opens the structure and assigns it the structure name. If the structure file does not exist, an exception is generated.

15.2.1 ACCESS Option

The ACCESS option determines how you can access the structure.

The access options are:

15.2.2 LOCK Option

The LOCK option causes SheerPower to lock the structure from write access by others. As long as the structure is open, the structure cannot be modified by others. This can speed up SheerPower's structure statements (EXTRACTs especially). The particular effect depends on the file management system being used.

15.2.3 DATAFILE Option

The DATAFILE option overrides the default datafile as specified by the structure.

FORMAT:


        DATAFILE file_spec 

file_spec is the file specification of the data file you want to open. The file_spec can be any string expression.

15.3 CLOSE STRUCTURE struc_name

FORMAT:


        CLOSE STRUCTURE struc_name 

EXAMPLE:

Example 15-4 CLOSE STRUCTURE

  open structure cl: name 'sheerpower:samples\client' 
  extract structure cl 
    include cl(state) = 'CA' 
    exclude cl(phone)[1:3] = '619' 
    sort ascending by cl(last) 
  end extract
  print 'List of California Clients' 
  for each cl 
    print cl(first); ' '; cl(last), cl(phone) 
  next cl 
  close structure cl 
  end
 
 
List of California Clients 
Dale Derringer      (818) 223-9014 
Earl Errant         (408) 844-7676 

DESCRIPTION:

CLOSE STRUCTURE closes a structure from further access. Once the structure is closed, you cannot reference records or add them, and you cannot change field data. struc_name is the name associated with the structure, the name assigned with the OPEN statement.

You can use the statement CLOSE ALL to close all open structures and other files.

15.4 ADD STRUCTURE

FORMAT:


        ADD STRUCTURE struc_name 
              ---                    
          [LET] struc_name(field) = expr 
              --- 
        END ADD 

EXAMPLE:

Example 15-5 ADD STRUCTURE/END ADD - Add structure record

  open structure cl: name 'sheerpower:samples\client', access outin
  input 'Enter ID number': id% 
  input 'Enter last name': last$ 
  input 'Enter first name': first$ 
  input 'Enter state': state$ 
  input 'Enter phone': phone$ 
  add structure cl 
    print
    print 'Adding '; last$; ', '; first$ 
    let cl(id) = id% 
    let cl(last) = last$ 
    let cl(first) = first$ 
    let cl(state) = state$ 
    let cl(phone) = phone$ 
  end add        
  close structure cl 
  end
 
 
Enter ID number? 12233 
Enter last name? Jones 
Enter first name? Tom 
Enter state? NV 
Enter phone? 2345556161 
 
Adding Jones, Tom 


Previous Next Contents Index