peoplecodeapi

PutAttachment

Mon 01 January 2018

Syntax 

PutAttachment(URLDestination, DirAndSysFileName, DirAndLocalFileName[, LocalDirEnvVar[, PreserveCase[, AllowLargeChunks]]])

Description

Use the PutAttachment function to upload a file from the file system of the application server to the specified storage location. 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: It is the responsibility of the calling PeopleCode program to store the specified file name for further use.

If a file exists at a particular place on a storage location and then another file with the same name is uploaded to that same place on that same storage location, the original file will be silently overwritten by the new file. If that is not the behavior you desire, it is recommended that you implement PeopleCode to guarantee the ultimate uniqueness of either the name of the file at its place on the storage location or the name of its place (the subdirectory) on the storage location.

Note: If the web server load-balances via Jolt session pooling, then it may be difficult to anticipate which application server machine will be expected to have the specified file.

Note: If the specified destination subdirectories do not exist at the storage location, this function tries to create them.

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

  • PeopleTools supports multiple types of storage locations.

    See .

  • Certain characters are illegal in file names; other characters in file names are converted during file transfer.

    See .

  • Non-ASCII file names are supported by the PeopleCode file attachment functions.

    See .

  • The PeopleCode file attachment functions do not provide text file conversions when files are attached or viewed.

    See .

Parameters

Field or Control

Definition

URLDestination

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

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 .

DirAndSysFileName

The relative path and file name of the file at the storage location. This is appended to URLDestination to form the full URL where the file will be transferred to. 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 source file on the application server. This parameter takes a string value. If you specify only a name or a relative path name for the source file, the file will be searched for 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.

Important! If a reference to the uploaded file is to be stored in a file reference table, then the PeopleCode that calls PutAttachment must restrict the length of the file name portion of the value of the DirAndLocalFileName parameter to 64 characters. Otherwise, that file name will be too long to be stored in that file reference table as a user file name.

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 source 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 of the source file on the application server. 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 of the source file on the application server.

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

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.

PreserveCase

Specify a Boolean value to indicate whether the case of the extension of the file specified in DirAndSysFileName is preserved at the storage location: True, preserve the case, False, convert the file name extension in DirAndSysFileName to all lower case letters.

The default value is False.

For a particular file, save the value specified for this parameter so that it may be used when later calling other file-processing built-in functions on this file.

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.

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.

The default value is False.

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

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 .

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.

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.