File Server Objects

There are i5/OS^(TM) system considerations, actions, or functions that might be performed that could affect file server objects.

Following are some system considerations related to how the internal file server objects are used by the file server object APIs.

• All file server objects created using the FSO APIs are stored in the QUSRSYS library. If that library is ever cleared, all file server objects are deleted.
  
  
• All file server objects are permanent system objects. They are not deleted due to a system IPL (normal or abnormal) or due to a normal installation of i5/OS.
  
  
• All file server objects are owned by the QSNADS user profile. To determine the amount of space used by the system for file server objects, you can display the amount of storage owned by the QSNADS user profile.
  
  
• To manage the existence of a file server object, you would use the assign and revoke access ID APIs. However, if these APIs are not used, there is no protection on the file server object (see Assign and Revoke APIs Example). If someone issues the Reclaim Storage (RCLSTG) command and there is no protection on a file server object, that file server object will be deleted.
  
  
• File server objects cannot be saved. When you perform a save of the system, file server objects currently existing on that system are not saved. File server objects that were created on one system cannot be restored on another system.

File Servers Supported by FSO APIs

The following sections talk about the two file servers that are supported by the FSO APIs. These file servers are programs that are called by the APIs to perform specific operations. Both file servers have the same interface. To indicate which file server program should be used by the API, you pass in the name of the file server on the API call.

Note: Only one file server can be used for any one file server object. For example, to manipulate file server object A, you cannot use the DIA file server to create the object and then the SNADS general file server to write data to the object. Only one of the file servers may be used to do both operations. Likewise, if file server object A was created using the DIA file server, the DIA file server must be used to read the object later.

SNADS General File Server

The SNADS general file server is used to create objects (called SNADS general file server objects (FSOs)) which are simply a stream of bytes. When this type of FSO is created, no data conversions take place and the only information in the FSO is the data itself. For example, the SNADS general file server is used by object distribution to store data for files or spooled files.

DIA File Server

The DIA file server is used to create DIA FSOs. These objects are used by OfficeVision^(R) and can consist of more information than just the data. Examples include the subject, origination date, expiration date, and priority. This additional information is stored in the IDP (interchange document profile) in the document that comes right before the actual document data.

The data in a DIA document are the actual contents of an OfficeVision note, message or document. The data in a DIA FSO can take on several different formats that include final format text (FFT), revised format text (RFT), or PC file format. See the Document Interchange Architecture: Technical Reference, C23-0781-01, for more details on DIA.

Assign and Revoke APIs Example

Within SNADS there are several jobs that work with an MSF message. When an MSF message has a file server object attached to it, each job must secure its usage of the FSO by assigning an access ID to that FSO.

1. When the first job has assigned an access ID and completed its work on the MSF message, it passes the message to the next job.
   
   
2. The next job assigns an access ID for itself, but also revokes the access ID of the previous job.
   
   
3. The last job to work with the MSF message never actually assigns an access ID to the FSO, but it does revoke the access ID of the previous job.

When all access IDs to an FSO have been revoked, the file server object is deleted.

How Usage Counts Are Used

The SNADS general file server uses a usage count to keep track of the use of a file server object. The usage count indicates how many MSF messages are referencing the object. For example, as an MSF message (that refers to an attachment) flows through SNADS, the MSF message is processed by several different jobs. These jobs may each make copies of the MSF message to change some of the distribution data. The attachment, or file server object, could then be referred to by more than one MSF message at a time. For each reference, the Assign SNADS File Server Object Access ID (QZDASNID) API should be called to increment the usage count by one. As each job finishes its processing of the distribution, it calls the Revoke SNADS File Server Object Access ID (QZDRVKID) API. This decrements the usage count by one. When the usage count becomes zero, the file server object is destroyed.

The assigning and revoking operations for DIA documents follows the same methodology as the SNADS general file server. The usage count for DIA documents is stored in the distribution tracking object (DTO) for the document. After the usage count has been decremented by calling the QZDRVKID API, the document and DTO are deleted if they are eligible for deletion.