Read SNADS File Server Object (QZDRDFSO) API

The Read SNADS File Server Object (QZDRDFSO) API has four operations that can be used to read an FSO. The three required operations are initiate read, read, and terminate read. The initiate read operation opens up an existing file server object that is based on the information given to it by the caller. Once this operation is called, the read operation can be used to read the data contained in the file server object. The read operation can be called multiple times to read all the data. After all read operations are completed, the terminate read operation must be issued to close the file server object.

The optional operation provided on the QZDRDFSO API is initiate read location. This operation can be used to start reading the file server object at a specific location.

The QZDRDFSO API operates on SNADS general file server objects and DIA file server objects. The interface to both of these types of objects is essentially the same.

SNADS General File Server

The SNADS general file server provides a means for SNADS support to save the data object portion of a distribution request. The general file server stores objects in a byte stream format. No transformations are done to the data when it is written into or read out of a general file server object. The SNADS general file server objects are owned by QSNADS and are stored in the QUSRSYS library.

The SNADS general file server can support objects up to 4 gigabytes. Each file server object space can be only 16MB large, but the SNADS general file server has the capability of chaining file server objects together. If the amount of data is greater than 16MB, the SNADS general file server creates as many file server object spaces as necessary and then chains them together. This function is transparent to the caller of the SNADS general file server routines.

The SNADS general file server read operations are as follows:

Initiate Read

The initiate read operation does the setup necessary to read the general file server object. This includes finding the object specified by the object handle in the input parameters. This operation must be the first called before any of the other read operations can be used for the specific file server object. The initiate read operation only needs to be called once in the sequence of read operations.

Read

The caller of the read operation must specify what object is to be read, where to put the data that is read, and how much data is to be read. If the amount of actual data is less than the size of the caller's buffer space (that is, where the data will be read in), the read operation reads as much data as it can and then returns. Because a space can be a maximum of 16MB, the caller's buffer space should be no more than 16MB, and the caller should not request more data than 16MB to be read. If the object being read is larger than 16MB, the caller must call the read operation more than once to read all the data. If more than one read is done, the SNADS general file server read operation keeps a marker in the data (offset inside the object) so that on subsequent read operations, the read operation knows where to start reading.

Terminate Read

The terminate read operation does the cleanup processing after you have completed reading the data in the file server object. After this operation is called, the file server object may still exist, but an initiate read operation must be done to read the file server object again.

Initiate Read Location

The initiate read location operation is similar to the initiate read operation, but allows a caller to set up a general file server object to begin reading at a specified location rather than at the beginning of the object. This operation also needs to be called only once in the sequence of read operations. The caller of this operation must pass in the resume position of where to continue reading the file server object. This number is based on how many bytes were read when the terminate read operation was called.

DIA File Server

The DIA file server provides a means for SNADS support to save the data object portion of an OfficeVision distribution request. The DIA file server objects are of the type *DTO (distribution tracking object), are owned by the QDOC user profile, and are stored in the QUSRSYS library.

The DIA file server can support objects up to 2 gigabytes. Each file server object space can be only 16MB large, but the DIA file server has the capability of chaining file server objects together. If the amount of data is greater than 16MB, the DIA file server creates as many file server object spaces as necessary and then chains them together. This function is transparent to the caller of the DIA file server routines.

The DIA file server read operations are as follows:

Initiate Read

The initiate read operation does the setup necessary to read the DIA distribution tracking object. This includes finding the object specified by the object handle in the input parameters. This operation must be the first operation called before any of the other read operations can be used for the specific file server object.

Read

The caller of the read operation must specify what document object is to be read, where to put the data that is read, and how much data is to be read. If the amount of actual data is less than the size of the caller's buffer space (that is, where the data will be read in), the read operation reads as much data as it can and then returns.

Because a space can be a maximum of 16MB, the caller's buffer space should be no more than 16MB, and the caller should not request more data than 16MB to be read. If the document object being read is larger than 16MB, the caller must call the read operation more than once to read all the data. If more than one read operation is done, the DIA file server read operation keeps a marker in the data (offset inside the object) so that on subsequent read operations, the read operation knows where to start reading.

Terminate Read

The terminate read operation should be called when you have completed reading the document. This operation closes the document object.

Authorities and Locks

API Public Authority

*EXCLUDE

Required Parameter Group

File server object handle

INPUT; CHAR(32)

The necessary linkage to the file server object is contained in this parameter. This parameter must be specified on all file server read operations. The value of this parameter should be taken from the file server object handle that was returned on the call to the Create SNADS File Server Object (QZDCRFSO) API.

Operation requested

INPUT; BINARY(4)

The operation the caller is requesting. Valid values for this parameter are as follows:

Initiate read	1
Read	2
Terminate read	3
Initiate read location	9

File server object data length

OUTPUT; BINARY(4)

The total length of the file server object being read. This parameter is returned on the initiate read and the initiate read location functions.

File server name structure

INPUT; CHAR(68)

The file server name (either DIA or SNADS) and the server name length.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Length of file server name
4	4	CHAR(64)	File server name

The length of the file server name is the number of bytes in the file server name defined by the SNADS architecture. Valid values for length of the file server name are as follows:

4	SNADS general file-server name
4	DIA file-server name

The file server name is the name value defined by the SNADS architecture for the file server that is to be used. The only file servers available with this API are the SNADS general file server and the DIA file server. Valid values for file server name:

'21F0F0F6'X	SNADS general file-server name
'20F0F0F1'X	DIA file-server name

Resume position

INPUT; BINARY(4)

The place where the initiate read location operation is to resume reading in the FSO. This parameter is ignored on the initiate read, read, and terminate read operations. Valid values for this parameter follow:

1 through the current file server object data length

Buffer area

INPUT; CHAR(*)

A buffer area defined by the caller. It is used by the read operation to store the data that is being read.

Bytes provided in buffer area

INPUT; BINARY(4)

The number of bytes of data that can be read into the buffer area. Valid values for this parameter are as follows:

1 byte through 16 megabytes

Bytes available in buffer area

OUTPUT; BINARY(4)

The number of actual bytes of data that was read into the buffer area.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Messages

API Introduced: V3R6