Large Object field processing for non-FILEORG X'100' files

Overview

Model 204 Version 7.5 introduced the X'100' bit on the FILEORG parameter which provides for a variety of extended features, including a simpler syntax for adding, changing and deleting Large Object fields (fields with a BLOB or CLOB attribute). Without FILEORG X'100', working with Large Objects requires the use of a Universal Buffer. The Universal Buffer is a one-per-user, temporary storage area that automatically expands to accommodate its data contents.

This page describes the Universal Buffer syntax, which is deprecated for X'100' files but required for earlier-version files that use BLOB or CLOB fields. For LOB syntax used in X'100' files, see Data maintenance.

Data maintenance statements

Special processing necessary for non-FILEORG X'100' files with LOB fields is needed for:

Statement	Action
Add	Place a new field-value pair on a record.
Change	Alter the value of fields in a record.
Store Record	Add a new record to a Model 204 file.

Using For Each Record loops

Since the SOUL data maintenance statements handle one record at a time, the data maintenance statements are always part of a For Each Record loop. The data maintenance may involve a field-value pair for the field.

Data used in examples in this topic

Each statement is discussed separately on the pages that follow. To illustrate their usage, assume that the following two records have been stored:

VIN = A99999998E VIN = X99999999Z MAKE = FORD MAKE = FORD COLOR = GREEN COLOR = RED YEAR = 88 YEAR = 04 MODEL = FOCUS MODEL = MUSTANG

Adding Large Object fields

Use the following special syntax of the Add statement to add a Large Object field to a record:

Add lob-fieldname=Buffer,position,length [Reserve n [Bytes]]

Where:

• lob-fieldname specifies the field name of the Large Object data.

  Note: Subscripts are not valid on Add statements.

• Buffer specifies the Universal Buffer.
• position is a positive number specifying the offset of the first character in the buffer or Large Object data. If the position is set to a negative value, an error occurs. The position can be a %variable or a constant.
• length is a positive number specifying the length to move. The length can be a %variable or a constant.
• Reserve n specifies a positive number of bytes to reserve for the Large Object field value. The number of Reserve bytes is always greater than or equal to maximum length of Large Object.
• Bytes, optional, specifies that n applies to bytes.

Example

BEGIN IMAGE XYZ BUFF_DATA IS STRING LEN 200 END IMAGE IDENTIFY IMAGE XYZ * add LOB field with "CURRECn" to the records: FOR EACH RECORD * enter data into image item: %XYZ:BUFF_DATA = 'CURREC' WITH $CURREC * write image on the buffer: WRITE IMAGE XYZ ON BUFFER POSITION=1 MAXLEN=200 * add LOB field from buffer contents: ADD MY.LOB.FIELD=BUFFER,1,10 RESERVE 200 BYTES END FOR * print LOB data: FOR EACH RECORD * place LOB data into the buffer: BUFFER,1,200=MY.LOB.FIELD,1,200 * place contents of the buffer into image: READ IMAGE XYZ FROM BUFFER * print LOB data that has been placed into the buffer: PRINT VIN AND %XYZ:BUFF_DATA END

This request adds a Large Object field to each record containing the text CURREC followed by the internal record number and this output:

A99999998E CURREC0 X99999999Z CURREC1

Usage

For Large Object data, a compiler error is issued for Add (and Store) statements if the context to the right of the equal sign (=) is not a Buffer reference:

M204.0037: Invalid syntax

Changing Large Object fields

To change large object fields, use the Change statement with the following syntax:

Change lob-fieldname,position1,length To Buffer,position2,length[Reserve n [Bytes]]

• lob-fieldname specifies the name of the field
• position, position1 and position2 are positive numbers specifying the offset of the first character in the buffer or Large Object data. If position, position1, or position2 is set to a negative value, an error occurs. Any positions can be a %variable or a constant.
• length is a positive number specifying the length to move. The length can be a %variable or a constant. The source and target lengths must be equal.

  If position plus length minus one exceeds the current length of the LOB field, the intervening bytes are filled with binary 0. If the file has the FILEORG X'100' bit set, then any final length of the LOB field is allowed. Otherwise extending a LOB field requires that the final length must fit within the Reserve clause length specified when the LOB field was added.

  For example, if the buffer contains ABCDEFGHIJKL and the field is initially stored with:

  ADD LOB.FLD=BUFFER,1,3 RESERVE 500 BYTES

  The field would contain ABC. If it was subsequently changed as follows:

  CHANGE LOB.FLD,5,10 TO BUFFER,1,10

  The field would then contain ABC ABCDEFGHIJ with position 4 being a binary zero.

• To Buffer specifies the Universal Buffer. You can use Buffer only in conjunction with a Large Object field.

Example

BEGIN IMAGE XYZ BUFF_DATA IS STRING LEN 200 END IMAGE IDENTIFY IMAGE XYZ IN JUNK FOR EACH RECORD * place LOB data into the buffer: %XYZ:BUFF_DATA = 'This is the data for VIN ' WITH VIN * write image on the buffer: WRITE IMAGE XYZ ON BUFFER POSITION=1 MAXLEN=200 * change the LOB field to the contents of the buffer: CHANGE MY.LOB.FIELD,1,50 TO BUFFER,1,50 END FOR * print LOB data: FOR EACH RECORD * place LOB data into the buffer: BUFFER,1,200=MY.LOB.FIELD,1,200 * place contents of the buffer into image: READ IMAGE XYZ FROM BUFFER * print LOB data that has been placed into the buffer: PRINT VIN AND %XYZ:BUFF_DATA END

This code results in changing the large object field in each record to the text This is the data for VIN followed by the VIN field and this output:

A99999998E This is the data for VIN A99999998E X99999999Z This is the data for VIN X99999999Z

Usage

• If you issue a Change statement on a Large Object field to a record that does not contain the field, nothing happens. Unlike a non-Large Object field, a new occurrence of the field is not added to the record.
• Extending a LOB field requires that the final length must fit within the Reserve clause length specified when the LOB field was added.

  Note: You cannot change the number of Reserve bytes. Furthermore, facilities are not available to delete a portion of data or to insert data: for example, to replace 10 bytes with 25 bytes within Large Object data. When an attempt to insert or delete data is made the following error message is issued:

  M204.2693: SOURCE AND TARGET LENGTH MUST BE EQUAL

• All Large Object data implicitly has the contiguous characteristic. A SOUL procedure can store some amount of initial data and then extend the data up to the Reserve number of bytes with subsequent Change statements. For example:

  FR * add initial 10 bytes: ADD LOB.FLD=BUFFER,1,10 RESERVE 200 BYTES * add increments of 10 bytes at * positions 11, 21, 31, 41 * moving data from the buffer to the field FOR %X FROM 1 TO 4 %Y = %X WITH '1' CHANGE LOB.FLD,%Y,10 TO BUFFER,%Y,10 END FOR PAI PRINT 'LOBLEN' AND $LOBLEN(LOB.FLD) END

Storing Large Object fields

To store a Large Object (prior to Model 204 V7.5 or absent the X'100' FILEORG bit), LOB fields require the Universal Buffer and this Store Record syntax to access the buffer:

Store Record lob-name=Buffer,position,length [Reserve n [Bytes]] . . . End Store [label]

Where:

• lob-name specifies the field name of the Large Object field.

  Note: you cannot use subscripts on statements for any field type.

• Buffer specifies the Universal Buffer
• position is a positive number specifying the offset of the first character in the buffer. If the position is less than one, an error occurs. The position can be a %variable or a constant.
• length is a positive number specifying the length to move. The length can be a %variable or a constant.
• Reserve n specifies a positive number of bytes to reserve for the Large Object field value. The number of bytes is always greater than or equal to $LobLen.
• Bytes, optional, specifies that n applies to bytes.

Example

STORE RECORD NOVEL=BUFFER,%POSITION,%LENGTH [RESERVE n [BYTES]] AUTHOR_PIC=BUFFER,%POSITION2,%LENGTH2 END STORE

Usage

When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields — unless the field is preallocated. See Building a Large Object descriptor for a description of how to build a Large Object data descriptor.

The following compiler error is issued when the right side of the equal sign is expected to contain a Buffer expression and it does not:

M204.0037: Invalid syntax