Write to SNADS File Server Object (QZDWTFSO) API

The Write to SNADS File Server Object (QZDWTFSO) API has four operations that can be used to write to an FSO. The first two operations, write and terminate write, are required to completely write to an FSO. The write operation copies the data from the caller's buffer into the file server object. This operation may be called multiple times to write all the data. The terminate write operation must be done after all the writes are completed. This operation closes the file server object and makes the FSO available to other processes to read it.

The two optional operations are suspend write and resume write, both of which are supported only by the SNADS general file server. These operations can be used to suspend the writing of a SNADS general FSO and then return to writing (resume) at a later time. These operations could be used in conjunction with the initiate read location operation.

An example of the usage of these operations follows. When data is being sent from one system to another, the sender on the source side is reading the file server object and the receiver is writing the data received into a new FSO on the target side. If the communications connection goes down during the middle of this data transmission, the receiver issues the suspend write operation. When the communications connection comes back up, the sender starts reading again using the initiate read location operation (part of the Read SNADS File Server Object (QZDRDFSO) API), and the receiver starts writing again using the resume write operation.

There are two types of file server objects that the QZDWTFSO 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. There are four SNADS general file server write operations and two DIA file server write operations provided by this API.

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. 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 only be 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 APIs. After a chain of FSOs is created, this chain is still referred to by one file server object handle.

The following paragraphs describe each of the SNADS general file server write operations.

Write

The write operation copies the contents of the caller's buffer to the file server object. If the data being written is greater than 16MB, the write operation automatically creates new file server object spaces and chains them together. The caller may call the write operation multiple times to write all the data.

Terminate Write

Once this operation is called, no other write operations can be done on the specific file server object. Also, the file server object cannot be read or have an access ID assigned to it until the terminate write operation completes.

Suspend Write

The suspend write operation allows the caller to temporarily suspend the writing of an object. This operation does not assign an access ID to the file server object, nor does it increment the objects usage count.

Resume Write

The resume write operation does the setup needed to resume writing into a file server object. It is similar to the create file server object API since it needs to be called only once before write operations can be done. The caller of this operation must pass in the starting position of where to continue writing in the file server object. This number is based on how many bytes were written when the suspend write operation was called.

Note: The resume write operation also checks the system storage threshold to make sure there is enough room for the rest of the data to be written.

DIA File Server

The DIA file server provides a means for SNADS to save the data object portion of an OfficeVision distribution request. The DIA file server objects are of 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 only be 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 following sections describe each of the DIA file server write operations.

Write

The write operation copies the contents of the caller's buffer to the DIA document object. If the data being written is greater than 16MB, the write operation automatically creates new spaces and chains them together. The caller may call the write operation multiple times to write all the data.

Terminate Write

When the caller completes writing the entire document, the terminate write operation must be called to save the distribution tracking object. The DIA document will also be closed. The DTO and the document are not available to other processes until this operation is called. Once this operation is called, no other write operations can be done on the specific file server object. Also, the file server object cannot be read or have an access ID assigned to it until the terminate write operation completes.

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. The value of this parameter should be taken from the FSO handle that was returned on the call to the Create SNADS File Server Object (QZDCRFSO) API.

Operation requested

INPUT; BINARY(4)

The operation requested is used by the QZDWTFSO API to determine which operation, write, terminate write, suspend write, or resume write, the caller is requesting. Valid values for this parameter are as follows:

Write	5
Terminate write	6
Suspend write	7
Resume write	8

File server object data length

OUTPUT; BINARY(4)

The total length of the file server object that has been written. This parameter is returned on the terminate write, suspend write, and resume write 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 resume write function is to resume writing in the FSO. This parameter is ignored on the write, terminate write, and suspend write functions. Valid values for this parameter are as follows:

1 through the current file server object data length

Buffer area

INPUT; CHAR(*)

The data that the caller wants to write into a file server object.

Bytes provided in buffer area

INPUT; BINARY(4)

The number of bytes of data in the buffer area that are to be written to the file server object. Valid values for this parameter are as follows:

1 byte through 16 megabytes

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