Stream 13 Usage


Here is the conversation flow of data set transfer.

Receiver Comments Receiver Messages       Sender Messages        Sender Comments
    <-S13F1R The entity that posses the data set indicates to the receiver that the dataset is available for transfer or that it should be transferred.
The receiver replies with ACKC13 code of 0 if he intends to receive the data set.   A code 0 reply can be sent in any case since there is no error condition to be indicated. S13F2->    
If there are currently no active transfers,  the receiver might send S13F9R to be at the known state of no active open dataset transfers.  A host is supposed to send this message to S13 aware equipment during initialization. [S13F9R->]


[<-S13F10]
The sender could/should act as if S13F9 was received whenever an HSMS SECS connection is broken.  If the other party sends S13F9R, a reply is sent.
For a new open the receiver sends the Open message with the CKPNT data item value set to 0, and his own HANDLE value as a unique logical identifier.   In a recovery situation, the receiver can supply the CKPNT value from the last successful read. S13F3R->    
    <-S13F4 The sender associates the HANDLE value with the transfer context and tells the receiver a suitable record length or maximum read size.
The receiver makes read requests until a non-zero ACKC13 is received.   The value 8 is the successful end-of-data indication.  Other non-zero values are errors.   In the event of disconnection, the receiver can save the partial data, and use the latest CKPNT value to resume the transfer after the connection is recovered.  If the transfer ends in error, with a healthy connection, its not clear that the CKPNT or retrying would do any good.  

Conceptually the receiver is in a loop, reading data until done.  However, asynchronous inputs such as alarms and event reports continue to be sent and received.  You are better off coding the "loop" as asynchronous actions to be performed when receiving the next S13F6 reply, or receiving a failure indication.  You should keep the transaction data in a known place so that you can clean-up or recover if disconnected or aborted.
S13F5R ->    
    <-S13F6 The sender writes the requested data to each request.  The sent CKPNT value indicates where the next READ should start if the data set were to be re-opened after this transfer succeeded.  It's ok to send both the last data and the code 8 end-of-data return code in the same reply.   At the end-of-file or error, the CKPNT value is set to 0xffff. Any additional read requests will get code 8 and no data. 
After exiting from the loop, the receiver closes the open dataset.   S13F7R->    
    <-S13F8 After seeing the close, any subsequent read requests would be sent code 6 instead of code 8.

Other comments:

The method can be used to transfer data sets that exceed the the maximum message size of SECS or HSMS.   HSMS uses a 4 byte message length coding so this has not been much of an issue.

Unlike file system transfers that you could do with operating system level commands such as scp or ftp, there is no provision for meta data such as filename, file ownership, create and access times, access permissions, etc.  The DSNAME is not required to be suitable as a file name.

You should be somewhat skeptical about the checkpoint feature being correctly implemented.  This is the kind of feature that may not be properly tested, even if there were no design issues such as the dataset being modified between transfer sessions.  I would not use or trust data if received in more than one session using the checkpoint feature, unless there was a separate means of validation such as a CRC checksum.  I would not bother to code recovery logic using the checkpoint feature unless there was a clear case for its value.