The KeyValue class defines an actual key value. Every key value has a key definition associated with it. This class provides methods for manipulating the key value and for inquiring the attributes of the associated key description.
A KeyValue object can be used to select a record in an indexed-sequential file using this key.A KeyValue object is serializable can thus be used for Remote Method Interfaces (RMIs).
Constructors
When a KeyValue object is generated, the key value is filled with the user’s data. This data can be specified as a byte array or string. If the user specifies no data or the data specified is shorter than the key, the complete key value is padded with null bytes or blanks. If the data is longer than the key, only as much data is transferred as will fit in the key.
If the user specifies the data as a string but specifies no encoding for converting text to data, the system-dependent standard encoding (in BS2000 the default value is OSD_EBCDIC_DF04_1) is used.
Methods for manipulating the key value
The setValue() methods fill the key with the specified user data. If the user specifies no data, the entire key value is filled with null bytes. If the data is shorter than the key, the rest is filled with a filler byte. The filler byte can be supplied by the user, otherwise a null byte is used. If the data is longer than the key, only as much data is transferred as will fit in the key.
The setStringValue() methods fill the key with the converted data of the specified string. If the user specifies no data, the entire key value is filled with blanks. If the data is shorter than the key, the rest is filled with blanks. If the data is longer than the key, only as much data is transferred as will fit in the key.
If no encoding for converting text to data was specified by the user, the system-dependent standard encoding (in BS2000 the default value is OSD_EBCDIC_DF04_1) is used.
The getValue() methods are used to return the key value of a key. The key value is either transferred to a buffer provided by the user or returned as a copy of the value. As the key value is therefore always copied, this means that manipulations on the result returned have no influence on the object from which the value originates. If the value in the object is to be modified, the setValue() method must subsequently be used.
With the getStringValue() methods, the key value of a key is returned converted into a string. If no encoding for converting text to data was specified by the user, the system-dependent standard encoding (in BS2000 the default value is OSD_EBCDIC_DF04_1) is used.
Methods for determining the key attributes
The getPosition() method returns the position of the key field in a record.
The getLength() method returns the length of the key field.
The getKeyDescriptor() method returns the key definition associated with the key value.