Attachment Error Handling

Transfer Errors: Queue versus Point-To-Point

When sending a message to a message queue, all of the 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 they are fetched by a user. If an error occurs while you send the attachments to the queue, then neither the message nor the attachments are delivered to the queue. In this scenario, the return code from _SEND_ or _SENDLIST_ is set to _SEATTXF. This error indicates 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, then 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_ or _SENDLIST_ is 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, then the current attachment transfer is terminated, but the transfer continues with the next attachment in the attachlist. If any errors are encountered, then the return code from _ACCEPT_ATTACHMENT_ is set to _SWATTXF. This is only a warning indicating that one or more errors occurred during attachment transfer.

Attachment Error Codes

List of Attachment Error Codes

To review what was mentioned above, a specific return code is 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 is updated. An additional named item, RC, is 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 a 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 has the following named items:

Named item ATTACH_ID has a value of 1.
Named item OUTLIB has a value of "NOEXIST."
Named item OUT has a value of "A."
Named item RC has a value of 81.

The error code list maps the return code of 81 into output library is nonexistent. Similarly, when the sender returns from the _SEND_ or _SENDLIST_, the attachlist parameter is 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 is updated with the RC named item to reflect that the attachment transfer failed.

Named item LIBNAME has a value of "SASUSER."
Named item MEMNAME has a value of "NAMES."
Named item TYPE has a value of "DATASET."
Named item RC has a value of 81.

Again, the error code list maps the return code of 81 into output library is nonexistent.