GetAttachment function

Syntax

GetAttachment(URLSource, DirAndSysFileName, DirAndLocalFileName[, LocalDirEnvVar[, PreserveCase]])

Description

Use the GetAttachment function to download a file from its source storage location to the file system of the application server. The file system of the application server includes any directories accessible from the application server including those on local disks as well as on network shares.

Note:

All directories that are part of the destination full path name must exist before GetAttachment is called. The GetAttachment function will not create any directories on the application server's file system.

Additional information that is important to the use of GetAttachment can be found in the PeopleTools: PeopleCode Developer's Guide:

Parameters

Parameter Description

URLSource

A reference to a URL. This can be either a URL identifier the form URL.URL_ID, or a string. This (along with the DirAndSysFileName parameter) indicates the file's source location.

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.

DirAndSysFileName

The relative path and file name of the file at the storage location. This is appended to URLSource to form the full URL where the file will be transferred from. This parameter takes a string value.

Note: Because the DirAndSysFileName parameter is appended to the URL, it also requires forward slashes (“/”). Backward slashes (“\”) are not supported for this parameter.

DirAndLocalFileName

The name, relative path name, or full path name of the destination file on the application server. This parameter takes a string value. If you specify only a name or a relative path name for the destination file, the file will be placed in or relative to:

  • The directory indicated by the value of the environment variable specified by the LocalDirEnvVar parameter.

  • The directory indicated by the value of the TMP environment variable if the LocalDirEnvVar parameter has not been specified.

If you do not want to use the LocalDirEnvVar parameter or the value of the TMP environment variable in this way, you must specify a full path name as appropriate to the application server’s operating system.

LocalDirEnvVar

This optional parameter takes a string value.

If LocalDirEnvVar is specified, then its value will be prefixed to the value of the DirAndLocalFileName parameter to form the full path name of the destination file on the application server’s file system. With this parameter, you can avoid the need to hard-code the full path name.

If LocalDirEnvVar is not specified and the value of the DirAndLocalFileName parameter is already a full path file name, then that value will itself be used as the full path name that the downloaded file will have at its destination on the application server machine. If LocalDirEnvVar is not specified and the value of the DirAndLocalFileName parameter is not a full path file name, then the value of the TMP environment variable will be prefixed to the value of the DirAndLocalFileName parameter to form the full path name that the downloaded file will have at its destination on the application server machine.

Note: In order to use the optional parameter PreserveCase, you must pass some value for LocalDirEnvVar. If you want to use the default behavior of LocalDirEnvVar and also use PreserveCase, you can specify "" (the empty string) for LocalDirEnvVar. Then the function behaves as if no value is specified. In this situation, if you wish to use the TMP environment variable, it must be explicitly specified.

Note: Do not specify LocalDirEnvVar if you use an absolute path for the DirAndLocalFileName parameter.

PreserveCase

When searching for the file specified by the DirAndSysFileName parameter, PreserveCase specifies a Boolean value to indicate whether the case of its file name extension is preserved: True, preserve the case, False, convert the file name extension in DirAndSysFileName to all lowercase letters.

The default value is False.

For a particular file, use the same value for this parameter that was used when the file was originally uploaded.

Warning! 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.

This is an optional parameter.

Returns

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

Numeric Value Constant Value Description

0

%Attachment_Success

File was transferred successfully.

1

%Attachment_Failed

File transfer failed due to 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 transfer failed due to 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.

  • 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

The following downloads the file, HRarchive/NewHire/11042000resume.txt, from the FTP server to c:\NewHires\resume.txt on the application server machine. 

&retcode = GetAttachment("ftp://anonymous:hobbit1@ftp.ps.com/HRarchive/", ⇒
"NewHire/11042000resume.txt", "c:\NewHires\resume.txt");

File System Considerations

If you are uncertain which type of file system the file is going to be transferred to, either a UNIX or Windows system, you should simply specify a file name for the DirAndLocalFileName parameter and either explicitly set the LocalDirEnvVar parameter or accept its default value, which is “TMP” (indicating that the value of the TMP environment variable will be used).

The following code example works for Windows systems, but not UNIX systems: 

&retcode = GetAttachment(&FTPINFO, &SOURCEFILENAME, "c:\temp\resume.doc");

The following code example works for Unix systems, but not Windows systems: 

&retcode = GetAttachment(&FTPINFO, &SOURCEFILENAME, "/tmp/resume.doc");

The following two examples work for both Windows and Unix systems: 

&retcode = GetAttachment(&FTPINFO, &SOURCEFILENAME, "resume.doc"); 

&retcode = GetAttachment(&FTPINFO, &SOURCEFILENAME, "resume.doc", "PS_CFG_HOME");

WARNING:

If the effectively specified target directory that is to ultimately contain the downloaded file on the application server is a UNC (Universal Naming Convention) share, an error will occur and GetAttachment will fail to download the file.

You cannot use a share as the target directory—that is, as the ultimate destination—to download a file onto an application server using GetAttachment. However, you can use a subdirectory of a UNC share as the target directory.

For example, if a directory similar to the following were the target directory, GetAttachment would fail:

\\server_name\share_name

However, the following subdirectory of the same UNC share could be used with GetAttachment:

\\server_name\share_name\temp

Related Topics