Computer Corporation of America
|
 Feedback
Search CCA:
   
USA CCA
Rocket
Customer Support
CCA Company
CCAPRINT: A Newsletter for Model 204® and System 1032® Users
May 22, 2008
     
System 1032: Updating Attributes Printer-friendly version
Model 204: Defining and Storing Large Objects in V6R1.0, Part II Printer-friendly version

 

System 1032
USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.

Updating Attributes
By Tym Stegner

TymIn a long-running application, it sometimes becomes necessary to update the data schema to evolve the application for changing needs. The first thought of many maintainers is to simply modify attribute(s) as needed, only to discover that there are situations where the MODIFY ATTRIBUTE command may not be appropriate.

This article provides an overview of the capabilities of the MODIFY ATTRIBUTE command. Then, using a customer question, I examine restructuring an attribute and user considerations of attribute modification.

Examining the MODIFY ATTRIBUTE Command
As described in the October, 2004 CCAPrint article, "Attribute Qualities", aspects of attribute definition fall into three categories, namely: structural, usage, and index.

Structural qualities include the data type, an optional range, the precision--in short, qualities that control how the attribute value is physically stored. Usage and index qualities cover all the other qualities of an attribute, such as a prompt, a comment, a title, a format, and the like.

The MODIFY ATTRIBUTE command operates only upon nonstructural qualities of an attribute. You cannot use it to change the data type or the range of an attribute, nor the other structural qualities.

Splitting One Attribute into a Group of Attributes
When a customer posed the following question, I realized that a simple MODIFY ATTRIBUTE command can not be used because the customer wanted to restructure the attribute in question.

Question: "How difficult is it to redefine a dataset so the following attribute:

Attribute TELEPHONE Text 14

Is redesigned to be the following:

Attribute TELEPHONE Group of
      SEVEN_DIGITS Text 7
      EXTENSION Text 4
      AREA_CODE Text 3
    End_Group

What are the major items one should be aware of and concerned with?"

Answer: System 1032 does not have a REDEFINE command. The MODIFY command is the closest System 1032 comes to such functionality. However, the MODIFY command is not appropriate for the type of update requested. First it is not possible to change a data type. Second, in this case the data underneath the original attribute name must be restructured, including the addition of two more attributes.

Converting and Adding Attributes to the Dataset
To address this question, first we must create a new version of the dataset, using a modified DMD from the dataset's current DMD. Once the new dataset is created, we can plan on how to move the data into the new structure.

To create a new version of the dataset in-place, you can use the following technique. (Note that the $ indicates a VMS command, not a System 1032 command)
  1. Create a copy of the dataset’s DMD.
    1032> SHOW ON newDS.DMD DS DEFINITION
  2. Edit this DMD to change the definition of the TELEPHONE attribute to the customer’s requirement.
  3. Rename the original dataset to allow creation of a new version.
    $ RENAME original.DMS original.OLD-DMS
  4. Create the new version of the dataset.
    1032> CREATE DS original DESCRIPTION newDS.DMD
  5. Open the old dataset using an ALIAS to access the data.
    1032> OPEN DS original AS newname IN original.OLD-DMS -READONLY

Remember that only unique names of datasets can be opened at the same time. Using an OPEN AS command allows the old and new versions of the dataset to be accessible simultaneously.

Data Translation
As a result of this update you cannot directly DUMP the data from the old dataset to the new--you must use an intermediate file, as the data must be read differently for the new dataset. An attempt to perform the DUMP from the original dataset to the new version will completely ignore the TELEPHONE attribute, as the data types do not match.

To begin, the old dataset’s data should be dumped to a flat file, using the default Record Descriptor (RD), or another available RD containing all the attributes to be preserved. The DMO file type tells us this data was output from a dataset:

1032> SET DS newname
1032> DUMP DATA_OUTPUT original.DMO RD $DEFAULT_RD

Note that the new telephone group data is not in the same order as the old telephone text field. This will have to be addressed using the RD created for the LOAD process.
Original data for the TELEPHONE attribute is a 14-character text string, likely the standard telephone number string of (aaa) ttt-nnnneeee (omitting special characters), where:

As a 14-character string the TELEPHONE attribute values are stored as:

aaatttnnnneeee

The new, group attribute has the area code broken out, and trailing the main number, but specified as three different attributes as follows:

tttnnnn/eeee/aaa

Therefore, while the original RD entry might have been as follows:
 

FIELD TELEPHONE TEXT LENGTH 14

The new RD entries will have to accommodate the changed definition of the attribute.

Record Design
TOne school of thought in dataset design is to arrange the attributes of a dataset to exactly match the order of the data values in the input file specification. The other school of thought arranges the attributes in the order that are of best use to the application, and then uses a customised RD to read the data values from the input file into the appropriate attributes.

As System 1032 matches the RD fields to the attributes via primary name, either approach is as efficient as the other.

The RD used for matching the exact order of the data values generally uses the LENGTH quality to pick up the data values.

However, in this case, the order of the new atttributes does not match the original order of the data value. This can be addressed either by using the COLUMN quality of FIELD, as follows. (The column values assume the TELEPHONE value begins in the first position in the input record.)

Field SEVEN_DIGITS Text Column 4 10
Field EXTENSION Text Allow End_Spaces Column 11 14
Field AREA_CODE Text Column 1 3

Or the fields of the RD itself can be re-arranged to pick up the data values in the appropriate order:

Field AREA_CODE Text Length 3
Field SEVEN_DIGITS Text Length 7
Field EXTENSION Text Allow End_Spaces Length 4

Procedure Considerations
A caveat to the dataset restructuring lies with any compiled procedures that utilize the old definition of the TELEPHONE attribute. These procedures are not going to work correctly, due to the restructuring.

While the TELEPHONE attribute name still exists, it is now a totally different data type (GROUP instead of TEXT 14). This fact alone will frustrate the expectations of compiled references to the attribute. Attempts to run a compiled procedure on the new dataset expecting the old definition of TELEPHONE will likely throw %S1032-E-BADTCREF errors, or similar, for the very reason that the attribute structures are different between the two versions of the dataset.

For these procedures to correctly operate upon the revised dataset, any references to the TELEPHONE attribute must be updated to the new definition and the procedures and libraries must be recompiled using the new dataset.

In Summary
In this article, we explained how to restructure an attribute and the data it describes by converting a single attribute into a group of three totalling the same space in the record. After determining that this task was not appropriate for the processing capabilities of the MODIFY ATTRIBUTE command, we began by defining a copy of the existing dataset and working from that to create the new group attribute. We then complete the restructuring by transferring the data from the old dataset to the new version, and updating any compiled procedures referencing the old attribute definition.

 

Model 204
USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.

Defining and Storing Large Objects in V6R1.0, Part II
By James Damon



Now that you have created and initialized a file with Table E (see CCAPRINT, April 2008) and set ESIZE > 20, you are ready to start defining, storing, retrieving and updating large objects. This article discusses the new file management facilities and User Language statements required to define and process large objects.

Defining a Large Object
V6R1.0 supports two types of large objects: character and binary, CLOB and BLOB, respectively. Currently, these two types are functionally identical. No ASCII to EBCDIC translation, or vice versa, is performed on CLOBs. In V6R1.0, any translation, if required, is the responsibility of the application. BLOBs, on the other hand, will always be stored or retrieved with no translation.

You can define a CLOB or BLOB with the DEFINE command, similar to the following:

DEFINE FACULTY.XMLDOC (CLOB OCCURS n)
DEFINE FACULTY.JPG    (BLOB OCCURS n)

Any other attributes associated with a large object are meaningless and the following M204.0411 error message will be issued:

DEFINE FACULTY.JPG (BLOB ORDERED CHARACTER OCCURS n)
M204.0411: CONFLICTING ATTRIBUTES: BLOB AND ORDERED CHARACTER

Finding a Large Object
As you might deduce from this restriction, you cannot find a large object by looking for data in the large object itself (the IS PRESENT clause, however, is supported), but instead by looking for other fields in the record that contains the large object. For example, you might have a file with the following fields defined:

DEFINE FACULTY.XMLDOC (BLOB OCCURS 1)
DEFINE FACULTY.JPG    (BLOB OCCURS 1)
DEFINE FACULTY.ID     (ORD CHAR OCCURS 1 LEN 6)
DEFINE FACULTY.SSN    (ORD CHAR OCCURS 1 LEN 9)
DEFINE FACULTY.DEPT   (ORD CHAR OCCURS 1 LEN 20)

You would locate a faculty member’s picture with the following User Language request which also retrieves the picture and moves it into the universal buffer:

BEGIN
PROF: FD FACULTY.ID=123456
      END FIND
      FOR 1 RECORD IN PROF
       %LEN = $LOBLEN(FACULTY.JPG)
       BUFFER,1,%LEN = FACULTY.JPG,1,%LEN
       ...
      END FOR  
END

Large Objects and the Universal Buffer
Access to a large object is provided through the universal buffer. Whenever a user references the universal buffer, one is allocated dynamically to that user. Each universal buffer is allocated at an initial size of UBUFSZ bytes and is dynamically expanded as required, up to two gigabytes. This expansion occurs automatically with no action required by the application. The universal buffer is released and the storage is freed when the user logs out.

Data is placed in the universal buffer with any of the following User Language statements:

Data is retrieved from the universal buffer with either of these User Language statements:

Storing a Large Object
A large object is stored in a record using data residing in the universal buffer with something like that below. You would generally (or always to ensure finding the record) also store an ordered field by which to locate the large object, as in this case with the field FACULTY.ID:


STORE RECORD
  FACULTY.ID = 123456
  FACULTY.XMLDOC = BUFFER,position,length
END STORE

The following example shows how to store a long string of text as a large object. To let you see the large object, I have used character data from the first 450-plus bytes of a plot summary of Moby Dick on Wikipedia1. The data could just as easily be a .jpg, .doc, .wav or any other character or binary data that you have acquired from an: 


IN LOBFILE DEFINE SUMMARY  (BLOB)
IN LOBFILE DEFINE SOURCE   (ORD)
IN LOBFILE DEFINE AUTHOR   (ORD)
IN LOBFILE BEGIN
IMAGE SUMMARY
  ARRAY OCCURS 15
    TEXT IS STRING LEN 50
  END ARRAY
END IMAGE
PREPARE IMAGE SUMMARY
%SUMMARY:TEXT(1)='Aiming to join a whaling crew, Ishmael heads for N'
%SUMMARY:TEXT(2)='antucket, the older of the two U.S. centers of the'
%SUMMARY:TEXT(3)=' whaling industry.  Time problems force him to sto'
%SUMMARY:TEXT(4)='p for the night in the new, more powerful whaling '
%SUMMARY:TEXT(5)='center of New Bedford, Massachusetts.  Lacking mon'
%SUMMARY:TEXT(6)='ey, he lodges at the Souter Inn.  The innkeeper, P'
%SUMMARY:TEXT(7)='eter Coffin, puts him in a room with the mysteriou'
%SUMMARY:TEXT(8)='s tattooed cannibal, Queequeg, a harpooner.  Despi'
%SUMMARY:TEXT(9)='te Ishmael''s initial reservations, the two become'
%SUMMARY:TEXT(10)='friends.  ...’
WRITE IMAGE SUMMARY ON BUFFER POSITION 1
STORE RECORD
  AUTHOR   = MELVILLE
  SOURCE   = WIKIPEDIA
  SUMMARY  = BUFFER,1,500
END STORE
END

At this point the large object has been stored in Table E. The locator for that large object, the large object descriptor, has been stored in the Table B record in the field named SUMMARY. The Table B record also contains the fields AUTHOR and SOURCE.

Table B Large Object Descriptor
The large object descriptor, in the field SUMMARY, has the following format:

Description

Bytes

Reserved

0-2
First Table E page no. 3-6
$LOBLEN (float) 7-14
$LOBRESERVE (float) 15-22
Reserved 23-26

Since a large object occupies contiguous pages in Table E, the starting Table E page number plus the length of the large object provide the information required to retrieve it.

Coming Attractions
In the next article in this series, I will review the facilities available for retrieving, updating, printing and deleting large objects as well as the tools available for reorganizing files containing large objects.

1. Moby-Dick. (2008, May 20). In Wikipedia, The Free Encyclopedia. Retrieved 16:34, May 21, 2008, from http://en.wikipedia.org/w/index.php?title=Moby-Dick&oldid=213788535


Copyright © 2008 Computer Corporation of America.
All right reserved. Published in the United States of America.


Contact CCA Webmaster
 Copyright 2008