Buckets Explained

Last edited: December 15, 2003 08:06 AM

In Version 4.00 a new feature was added to accommodate many data storage and manipulation needs. This feature is not however for the weak stomached.  Because of its power and flexibility, this feature is complex to use, and requires a programming aptitude. I will attempt to best describe the features and their use. Any un-answered questions resulting from this document may be posted to me on the BBS, at which time I will gladly reply.

The purpose of a Bucket file is to allow long and short term storage of information. Think of a Bucket file as a big chalkboard, with rows and columns. Each row and column can hold a single letter or number. Bucket
files give you the ability to store and retrieve (Get and Put) variables into the file of your choice, at the row and column you specify. You also have the ability to determine the width of your Get and Put actions.

Bucket files will be stored in the DATA directory, as a child of the operational directory, where TouchNet files are stored. You may define and use as many of these files as you wish. They are named with DOS naming conventions, and the .BUK extension. A sample filename would be ‘TEMP.BUK’!

Bucket files are restricted to 200 columns of 32000 rows. These are numbered starting with 1, as 1-200 and 1-32000. They are addressed with these variables:
    Bucket Name the 8 character filename. (Do not add an extension, .BUK will be automatically added for you.)
    Bucket Row the row for the next Get/Put operation.
    Bucket Col the column for the next Get/Put operation.
  Bucket Width How many characters to Get or Put. If 0, the length of the variable will be used. IE: Word 1 would be 6.

Operations on Bucket files, are done using the Get and Put instructions. The ‘Put variable in Bucket’ instruction will allow you to specify a variable, and will Place it in the bucket file (Named by ‘Bucket Name’) at the Row and Column specified by the above mentioned variables. If the ‘Bucket Row’ variable is equal to 0, the variable will be appended to the bottom of the file, and ‘Bucket Row’ will be set to the new Row number. If there are currently 3 rows, the information will be placed on row 4. This is useful for building a list, such as a database.

The ‘Get variable from Bucket’ instruction will retrieve from a bucket file, at the specified Row and Column, and for the specified Width, and place the contents in the variable you supply. It works just as the Put instruction. If the ‘Bucket Row’ variable is equal to 0, the ‘Bucket Row’ variable will be set to the last row in the file, and that row will be read.

An Additional instruction available for use with Buckets would be the ‘Search Bucket’ Instruction. When building this instruction, the Stylist will be prompted for the Variable to find a match on. The search will begin in the ‘Bucket Name’ File, at the ‘Bucket Row’ and ‘Bucket Col’. If a match is found, the result is returned in ‘Bucket Row’. If a match is not found, ‘Bucket Row’ will contain 0. In a bucket file with 32000 Rows, the search can take as long as 5 seconds on a slow computer. The stylist would want to place a window on the screen to inform that a search
is taking place.

Here is a sample chain that demonstrates the use of these variables. The example does not illustrate a real life situation, but merely the usage of the functions. The applications are limited by your imagination. This
chain will load the sentence ‘This is from a Bucket’ into Memo 1.
Word 1= This
Word 2= is
Word 3= from
Bucket Name= Test
Bucket Row= 1
Bucket Col= 1
Put- Word 1
Bucket Col= 6
Put- Word 2
Bucket Col= 9
Put- Word 3
Word 1= a
Word 2= Bucket
Bucket Col= 14
Put- Word 1
Bucket Col= 16
Put- Word 2
Bucket Col= 1
Get- Memo 1

While this would be a silly use of the feature, here are some possible uses for buckets:

  1. Daily inventory counter for a few items.
  2. For storage of other information that the customer database does not accommodate. You could use the Bucket as a Parallel database, by using the CUS:Record variable as the Row counter in your bucket to access other information.
  3. A method for combining Strings of characters or words as in the example above. Also for extracting a portion of a Memo string etc. If this is done on a multi-node setup, special caution should be used as to avoid using the same Bucket Name on other workstations, so that possible conflicts don’t arise. This could be done by setting Bucket Name equal to Node Name.
  4. Recording special information to be processed by a custom module for reports.
  5. Temporary storage of variables, in the event that you need more than are available, or need information to be preserved from order to order, as well as on other Workstations.

Revisions

9/26/95

    If the first character of the bucket name is an exclamation point(ex: !LOCAL) then the bucket will be written to the local Z: ramdrive instead of the DATA directory on the server. This allows you to use a standard bucket name without worrying about multiple workstations overwriting each others data and  speeds up read/writes as the server is not accessed. Be careful to design the bucket so that it doesn’t get bigger than the space available in the ramdrive.