CopyAttachments function

Syntax

CopyAttachments(URLSource, URLDestination [, FileRefRecords [, PreserveCase[, AllowLargeChunks]]])

Description

Use the CopyAttachments function to copy all files from one storage location to another. The files to be copied can be limited to those referenced in specific file reference tables.

To schedule a batch job to copy file attachments, you can use the COPYATTS Application Engine program, which can be executed from the Copy File Attachments (Batch) page. See System and Server Administration: Copy File Attachments (Batch) for more information.

Alternatively, you can use the Manage Attachment Repositories page to execute CopyAttachments directly in a synchronous manner. See System and Server Administration: Manage Attachment Repositories for more information.

Important:

Executing CopyAttachments directly in a synchronous manner may result in a timeout if the number of file attachments to be processed is large. Therefore, Oracle recommends that you use the batch processing interface instead.

CopyAttachments looks for the field ATTACHSYSFILENAME in the table that stores the file references. Oracle recommends that you include the FILE_ATTACH_SBR subrecord, which includes the ATTACHSYSFILENAME and ATTACHUSERFILE fields, in your record definition, not just the fields themselves.

CopyAttachments generates a list of all file attachments references, and then performs two operations on each file attachment. First, CopyAttachments calls GetAttachment to retrieve the file from your source location. Then, it calls PutAttachment to copy the attachment to your destination.

Note:

If the specified subdirectories do not exist this function tries to create them.

PeopleTools supports multiple types of storage locations. Additional information on using CopyAttachments with storage locations can be found in the PeopleTools: PeopleCode Developer's Guide:

See PeopleCode Developer’s Guide: Understanding File Attachment Storage Locations.

Parameters

Parameter Description

URLSource

Specify the source storage location of the files to be copied. This parameter can either be a URL identifier in the form URL .URL_ID, or a string.

Note: When the URLSource parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value.

See PeopleCode Developer’s Guide: Understanding URL Strings Versus URL Objects.

URLDestination

Specify the destination storage location for the files to be copied. This parameter can either be a URL identifier in the form URL .URL_ID, or a string.

Note: When the URLDestination parameter is specified as a string value, forward slashes (/) are required. Backward slashes (\) are not supported for a string value.

See PeopleCode Developer’s Guide: Understanding URL Strings Versus URL Objects.

FileRefRecords

Specify an array of record names each of which is associated with a table containing valid file references. By using this parameter, it is possible to explicitly specify which groups of file references will be considered during a call to CopyAttachments and, in this way, further restrict the scope of that call. If you do not specify this optional parameter, all the records that contain the FILE_ATTACH_SBR subrecord will be considered to have been implicitly specified (that is, every file at the specified source storage location that has some valid corresponding file reference will be copied).

Note: If you want to specify the PreserveCase parameter, the AllowLargeChunks parameter, or both and retain the default behavior of copying from all the records that contain the FILE_ATTACH_SBR subrecord, then specify an empty array as the value of the FileRefRecords parameter.

PreserveCase

Specify a Boolean value to indicate whether, when searching the source storage locations for the file specified by each file reference and when naming that file at the destination, its file name extension will be preserved or not; True, preserve the case of the file name extension, False, convert the file name extension to all lower case letters.

The default value is False.

Note: If you use the PreserveCase parameter, it is important that you use it in a consistent manner with all the relevant file-processing functions or you may encounter unexpected file-not-found errors.

AllowLargeChunks

Specify a Boolean value to indicate whether to allow large chunks.

If the value specified in the Maximum Attachment Chunk Size field on the PeopleTools Options page is larger than is allowed for retrieval, then the system breaks the file upload into the largest sized chunks allowed. If AllowLargeChunks is set to True, this behavior can be overridden so that it is possible for an end user to upload a file in chunks that are too large for the system to retrieve. If AllowLargeChunks is set to False, the system will use the largest size chunk that is allowed for retrieval, or the configured chunk size, whichever is smaller.

Note: If the chunks are too big to be retrieved, then any file retrieval built-in function, such as GetAttachment, will fail.

Note: The AllowLargeChunks parameter is only applicable when the storage location is a database record. It has no impact when the storage location is an FTP site or an HTTP repository, since attachments at those locations are never chunked.

See System and Server Administration: PeopleTools Options

This is an optional parameter.

The default value is False.

Returns

You can check for either an integer or a constant value:

Note:

Since file attachment references might not always point to real files in your source location (they might point to files in other locations, for example), file not found errors from the GetAttachment operation are ignored and not included in the CopyAttachments return code.

Note:

Because CopyAttachments is designed to work with multiple files, to track errors when using CopyAttachments set your PeopleCode trace to 2112 and your SQL trace to 15 so that errors will be written to the appropriate trace files.

Numeric Value Constant Value Description

0

%Attachment_Success

Files were copied successfully.

1

%Attachment_Failed

File copy failed due to an unspecified error.

The following are some possible situations where %Attachment_Failed could be returned:

  • Failed to initialize the process due to some internal error.

  • Failed due to unexpected/bad reply from server.

  • Failed to allocate memory due to some internal error.

  • Failed due to timeout.

  • Failed due to non-availability of space on FTP server.

  • Failed to close SSL connection.

  • Failed due to an unspecified error on the HTTP repository.

    If the HTTP repository resides on a PeopleSoft web server, then you can configure tracing on the web server to report additional error details.

    See PeopleCode Developer’s Guide: Enabling Tracing on the Web Server or Application Server.

3

%Attachment_FileTransferFailed

File copy failed due to an unspecified error during FTP attempt.

The following are some possible situations where %Attachment_FileTransferFailed could be returned:

  • Failed due to mismatch in file sizes.

  • Failed to write to local file.

  • Failed to store the file on remote server.

  • Failed to read local file to be uploaded

  • No response from server.

  • Failed to overwrite the file on remote server.

4

%Attachment_NoDiskSpaceAppServ

No disk space on the application server.

7

%Attachment_DestSystNotFound

Cannot locate destination system for FTP.

The following are some possible situations where %Attachment_DestSystNotFound could be returned:

  • Improper URL format.

  • Failed to connect to the server specified.

8

%Attachment_DestSysFailedLogin

Unable to login to destination system for FTP.

The following are some possible situations where %Attachment_DestSysFailedLogin could be returned:

  • Unsupported protocol specified.

  • Access denied to server.

  • Failed to connect using SSL Failed to verify the certificates.

  • Failed due to problem in certificates used.

  • Could not authenticate the peer certificate.

  • Failed to login with specified SSL level.

  • Remote server denied logon.

  • Problem reading SSL certificate.

9

%Attachment_FileNotFound

Cannot locate file.

The following are some possible situations where %Attachment_FileNotFound could be returned:

  • Remote file not found.

  • Failed to read remote file.

Example

&retcode = CopyAttachments(URL.UrlID, ftp://user:passwd@ftpaddress/");

Here is another example. 

&aRecs = CreateArray("HRATTS", "MFGATTS", "CRMATTS");  
&ret = CopyAttachments("ftp://user:pass@system/HR/", "record://HRARCHIVE", 
&aRecs);  
If (&ret = %Attachment_Success) Then 
   MessageBox(0, "Copy Archive Status", 0, 0, "Copy attachment archive succeeded"); 
Else 
   MessageBox(0, "Copy Archive Status", 0, 0, "Copy attachment archive failed"); 
End-If;

If you want to specify the PreserveCase parameter, the AllowLargeChunks parameter, or both and retain the default behavior of copying from all the records that contain the FILE_ATTACH_SBR subrecord, then specify an empty array as the value of the FileRefRecords parameter. For example: 

Local string &URL1 = "ftp://my_ftp_user:my_ftp_password@my_ftp_server.example.com";
Local string &URL2 = "record://PSFILE_ATTDET";
Local array of string &FileRefRecords = CreateArrayRept("", 0);
Local boolean &PreserveCase = True;
&ret = CopyAttachments(&URL1, &URL2, &FileRefRecords, &PreserveCase);

Considerations on Using PreserveCase with CopyAttachments

If the files to be copied were originally uploaded with the value of the PreserveCase optional parameter unspecified or explicitly specified as False, then CopyAttachments should be similarly invoked (with the value of PreserveCase unspecified or explicitly specified as False). On the other hand, if the files to be copied were originally uploaded with the value of the PreserveCase explicitly specified as True, then CopyAttachments should be similarly invoked (with the value of PreserveCase explicitly specified as True). If the files to be copied fall into both categories, then CopyAttachment will need to be run twice , once with the value of PreserveCase unspecified or explicitly specified as False, and then again with the value of PreserveCase explicitly specified as True.

Related Topics