vs
Class VmsStruct

java.lang.Object
  vs.VmsStruct

public class VmsStruct

extends java.lang.Object

Access a byte array as a VMS system structure.

This class, together with FieldDescriptor allows Java programs to access byte arrays as if they were BLISS structures.

The following Java code allocates an RMS FAB block and sets the block length and types fields.

 VmsStruct fab = new VmsStruct(new byte[FAB.FAB$S_FABDEF]);

 fab.put(FAB.FAB$B_BID, FAB.FAB$C_BID);
 fab.put(FAB.FAB$B_BLN, FAB.FAB$C_BLN);
 

The equivalent BLISS code is shown here. The VmsStruct constructor is similar to the BLOCK attribute.

 local
     fab : block[FAB$S_FABDEF, byte];

 fab[fab$b_bid] = FAB$C_BID;
 fab[fab$b_bln] = FAB$C_BLN;
 

See Also:

FieldDescriptor

Constructor Summary

VmsStruct(byte[] target)
Assigns the specified byte array to a new object.

VmsStruct(int size)
Allocates the target byte array internally.

Method Summary

long	get(FieldDescriptor f) Read a value from the structure.
byte[]	get(FieldDescriptor f, int length) Fetches an array of bytes from this VmsStruct beginning at the location specified by f for length bytes.
byte[]	getTarget() Return the byte array referenced by this VmsStruct.
void	put(FieldDescriptor f, int length, byte[] buffer, int beginIndex, int endIndex, boolean fill, byte fillByte) Writes the data specified by buffer into this VmsStruct at the position described by f.
void	put(FieldDescriptor f, int length, java.lang.String buffer) This method writes the data specified by buffer into this VmsStruct at the position described by f.
void	put(FieldDescriptor f, long val) Writes a value to the structure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VmsStruct

public VmsStruct(byte[] target)

Assigns the specified byte array to a new object.

This constructor assigns a caller allocated byte/ array as the target storage of this object.

Parameters:

target - byte array to be used by the VmsStruct calls to fetch and store data.

VmsStruct

public VmsStruct(int size)

Allocates the target byte array internally.

This constructor makes it simpler to allocate a new VmsStruct object by allocating the byte array for the caller.

Parameters:

size - size of the target storage.

Method Detail

getTarget

public byte[] getTarget()

Return the byte array referenced by this VmsStruct.

Returns:

the underlying byte array

put

public void put(FieldDescriptor f,
                long val)

Writes a value to the structure.

The field described by f is used to determine where to write val in the structure. Only the field described in f is modified. If the contents of val are greater then val is truncated to fit. No indication of truncation is given.

For fields larger than can be described by a FieldDescriptor refer to the other put methods mentioned below.

Parameters:

f - a FieldDescriptor detailing the area to be updated.

val - the value to be stored.

See Also:

put(FieldDescriptor, int, String), put(FieldDescriptor, int, byte[], int, int, boolean, byte)

put

public void put(FieldDescriptor f,
                int length,
                java.lang.String buffer)

This method writes the data specified by buffer into this VmsStruct at the position described by f. No more than length bytes will be altered. In the case where the length of buffer is shorter than length the area will be zero filled.

Please note that only the index field of f is ignored.

Parameters:

f - a FieldDescriptor object that describes the location to be written. Only the index field is used.

length - the maximum number of bytes to be written, starting from f.

buffer - a String object to be copied into the VmsStruct.

put

public void put(FieldDescriptor f,
                int length,
                byte[] buffer,
                int beginIndex,
                int endIndex,
                boolean fill,
                byte fillByte)

Writes the data specified by buffer into this VmsStruct at the position described by f. No more than length bytes will be altered. In the case where the length of buffer is shorter than length the remaining bytes can be filled with fillByte if fill is true.

Please note that only the index field of f is ignored.

Parameters:

f - a FieldDescriptor object that describes the location. to be written. Only the index field is used.

length - the maximum number of bytes to be written, starting from f.

buffer - the byte array to be copied into this VmsStruct.

beginIndex - the beginning index of buffer, inclusive.

endIndex - the ending index of buffer, exclusive

fill - this flag indicates whether or not fillByte should be used to fill any remaining bytes not filled by buffer.

fillByte - the character to be used to fill any remaining bytes.

get

public long get(FieldDescriptor f)

Read a value from the structure.

f is used to reference a location in the structure that is read and returned. No more than the storage specified in f is ever returned. Values are sign extended (or not) to a long value depending on the values in f.

For areas larger than those that can be described by a FieldDescriptor see the other get method mentioned below.

Parameters:

f - a FieldDescriptor specifying where to fetch the value from.

Returns:

long value containing the contents of the structure at the described position.

See Also:

get(FieldDescriptor, int)

get

public byte[] get(FieldDescriptor f,
                  int length)

Fetches an array of bytes from this VmsStruct beginning at the location specified by f for length bytes. This method is useful when it comes to extracting structures or text from within structures.

The following example retrieves the device identification field from a NAM block.

 String devnam = new String(nam.get(NAM.NAM$T_DVI,
                                    NAM.NAM$S_DVI),
                            1,
                            nam.get(NAM.NAM$T_DVI,
                                    1)[0]);
 

Please note that only the index field of f is ignored.

Parameters:

f - a FieldDescriptor object that describes the location to fetch the bytes from.

length - total number of bytes to be fetched

Returns:

a byte array containing the bytes fetched.