1 | File server object handle | Input | Char(32) |
2 | Operation requested | Input | Binary(4) |
3 | File server object data length | Output | Binary(4) |
4 | File server name structure | Input | Char(68) |
5 | Resume position | Input | Binary(4) |
6 | Buffer area | Input | Char(*) |
7 | Bytes provided in buffer area | Input | Binary(4) |
8 | Bytes available in buffer area | Output | Binary(4) |
9 | Error code | I/O | Char(*) |
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.
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:
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:
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.
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.
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 |
The total length of the file server object being read. This parameter is returned on the initiate read and the initiate read location functions.
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 |
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
A buffer area defined by the caller. It is used by the read operation to store the data that is being read.
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
The number of actual bytes of data that was read into the buffer area.
The structure in which to return error information. For the format of the structure, see Error code parameter.
Message ID | Error Message Text |
---|---|
CPF24B4 E | Severe error while addressing parameter list. |
CPF3A09 E | System error. |
CPF3A1A E | Location in file server object not valid. |
CPF3A1B E | File server object operation not valid. |
CPF3A1C E | File server object request not valid. |
CPF3A1D E | Limit of number of open file server objects exceeded. |
CPF3A1E E | End of data reached in file server object. |
CPF3A15 E | File server object not found. |
CPF3A17 E | Permanent server error. |
CPF3C90 E | Literal value cannot be changed. |
CPF3CF1 E | Error code parameter not valid. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API Introduced: V3R6
[ Back to top | Office APIs | APIs by category ]