Attachment Error Handling

Transfer Errors: Queue versus Point-To-Point

When sending a message to a message queue, all attachments (along with the message) are transferred to the queue when the _SEND_ or _SENDLIST_ is invoked. The attachments are stored at the domain server until fetched by a user. If an error occurs sending the attachments to the queue, neither the message nor the attachments will be delivered to the queue. In this scenario, the return code from _SEND_/_SENDLIST_ will be set to _SEATTXF. This is an error indicating that neither the message nor the attachments were delivered because one or more errors occurred during attachment transfer.

When a message is sent using point-to-point messaging, only the attachment list, along with the message, is sent to the receiving side initially. The receiver is then responsible for determining, which, if any attachments should actually be transferred. Because the message is delivered to the receiver before any attachments are actually transferred, an error encountered during attachment transfer will not cause the _SEND_ to terminate. If an error is encountered, the current attachment transfer is terminated, but the remaining attachments selected to be received are sent to the receiving side. If any errors are encountered during attachment transfer, the return code from _SEND_/_SENDLIST_ will be set to _SWATTXF. This is only a warning indicating that the message was successfully sent, but one or more errors occurred during attachment transfer.

Accept Errors

When a message includes attachments, the receiver has the responsibility to determine which attachments are ultimately transferred, via the _ACCEPT_ATTACHMENT_ method. If an error is encountered during attachment transfer, the current attachment transfer is terminated, but the transfer continues with the next attachment in the attachlist. If any errors are encountered, the return code from _ACCEPT_ATTACHMENT_ will be set to _SWATTXF. This is only a warning indicating that one or more errors occurred during attachment transfer.

Attachment Error Codes

To review what was mentioned above, a specific return code will be set if an error is encountered during attachment transfer.

• when sending on a Cnction instance, _SWATTXF is returned
• when sending on a Queue instance, _SEATTXF is returned
• when accepting attachments on either a Queue or Cnction instance, _SWATTXF is returned

When one of these scenarios occurs, the attachlist parameter passed to these methods will be updated. An additional named item, RC, will be added to each separate attachment list. The value of RC will be a numeric return code that can be used to determine what caused the error for this particular attachment transfer. The defined return codes include the following:

   Input File Errors (error occurred on input file):
       Value   Meaning
       ----    --------------------
       20      general I/O error
       21      libname does not exist
       22      memname does not exist
       23      invalid or missing password
       24      invalid data set option value
       25      invalid data set option name
       26      general error parsing data set options
       27      error parsing where stmt
       28      bad physical filename
       29      file in use
       30      file does not exist
       31      invalid authorization for external file
       32      open failed for some reason other than 
	              mentioned above
       33      error obtaining Integrity Constraints 
	              information
       34      variable contains unsupported characters or 
	              is too long
       35      key name contains unsupported characters or 
	              is too long

   Output File Errors (error occurred on output file):
       Value   Meaning
       ----    --------------------
       80      general I/O error
       81      libname does not exist
       82      invalid or missing password
       83      bad physical filename
       84      file in use
       85      file does not exist
       86      invalid authorization for external file
       87      open failed for some reason other than 
	              mentioned above
       87      file already exists
       88      engine does not support read passwords
       89      engine does not support encryption

   General/Misc. Errors:
       Value   Meaning
       ----    --------------------
       1      Out of memory error
       2      Open of catalog by queue manager failed
       3      Read error (of catalog) encountered by queue 
	             manager
       4      Write error (of catalog) encountered by queue 
	             manager
       5      Index create failure
       6      Backwards compatibility error
       7      Only SQL views supported

Example

In the following example, one attachment is accepted into an non-existent library name:

   /* build one attachment list, att1 */
   att1 = makelist();
   rc = setnitemc(att1, 1, "ATTACH_ID");
   rc = setnitemc(att1, "NOEXIST", "OUTLIB");
   rc = setnitemc(att1, "A , "OUT");

   /* insert att1 into the main attachment list, alist */
   alist = makelist();
   alist = insertl(alist, att1, -1);

   /* accept the attachment */
   call send(obj, "_ACCEPT_ATTACHMENT_", alist, rc);

   /* if error, dump out attachment list to view rc */
   if (rc NE 0) then
      call putlist(alist, "Attachment 
	     list after accept:", 1);

After the accept method call, the attachment list alist will have the following named items:

• named item ATTACH_ID will have a value of 1
• named item OUTLIB will have a value of "NOEXIST"
• named item OUT will have a value of "A"
• named item RC will have a value of 81

The error code list maps the return code of 81 into output library is non-existent. Similarly, when the sender returns from the _SEND_/_SENDLIST_, the attachlist parameter will be updated with the RC named item to reflect that the attachment transfer failed.

   att1 = makelist();
   rc = setnitemc(att1, "SASUSER", "LIBNAME");
   rc = setnitemc(att1, "NAMES", "MEMNAME");
   rc = setnitemc(att1, "DATASET", "TYPE");
   attachlist = makelist();
   attachlist = insertl(attachlist, att1, -1);
   call send(cnctionObj, "_SEND_", msgtype, attachlist, 
      rc, "Message One");
   if (%sysrc(_SWATTXF) = rc) then do;
      call putlist(attachlist, "attachlist after send", -1);
   end;

Assuming that the attachment was accepted by the receiving side as shown above, the attachment list, attachlist, after the send will be updated with the RC named item to reflect that the attachment transfer failed.

• named item LIBNAME will have a value of "SASUSER"
• named item MEMNAME will have a value of "NAMES"
• named item TYPE will have a value of "DATASET"
• named item RC will have a value of 81

Again, the error code list maps the return code of 81 into output library is non-existent.