peoplecodeapi

MAddAttachment

Mon 01 January 2018

Syntax 

MAddAttachment(URLDestination, DirAndFilePrefix, Prompts, &UserFileArray, &ActualSizeArray, &DetailedReturnCodeArrayName [, MaxSize [, PreserveCase[, UploadPageTitle[, AllowLargeChunks[, StopOnError]]]]])

Description

Use the MAddAttachment function to upload one or more files from an end user specified location (local storage or cloud storage) to a specified storage location. The Prompts parameter specifies that maximum number of files that the end user can upload at one time. Use the AddAttachment function to upload a single file.

Important! It is the responsibility of the calling PeopleCode program to store the returned file names 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.

You cannot use a relative path to specify the file that is to be uploaded; you must use a full path. If end users experience problems in uploading files, ensure that they browse to the file they wish to upload rather than attempting to manually enter the full path name of the file. This problem can manifest itself differently depending on the browser used. For example, with some browser versions, the PeopleSoft page appears to be in an infinite “Processing” state. Information is available on working with different browsers.

See on My Oracle Support for more information.

Additional information that is important to the use of MAddAttachment 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 .

  • Because MAddAttachment is interactive, it is known as a “think-time” function, and is restricted from use in certain PeopleCode events.

    See .

  • You can restrict the file types that can be uploaded to or downloaded from your PeopleSoft system.

    See .

  • You can restrict the file types that can be uploaded to or downloaded from your PeopleSoft system.

    See .

  • Virus scanning can be performed on all files uploaded with the MAddAttachment function.

    See .

Parameters

Field or Control

Definition

URLDestination

A reference to a URL. This can be either a URL identifier in the form URL . URL_ID , or a string. This is the storage location to which the files in this invocation of MAddAttachment are transferred.

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

Note: Oracle recommends that you do not use a URL of the form file:// file_name with the PeopleCode file processing functions.

See .

DirAndFilePrefix

A directory and file name prefix. This is appended to the URLDestination to make up the full URL when the file is transferred to an FTP server or, when the file transferred to a database table, to make the file name unique.

Note: If the destination location is an FTP server, then it is very important whether the value passed into a call of MAddAttachment for the DirAndFilePrefix parameter ends with a slash or not. If the value for the DirAndFilePrefix parameter ends with a slash, then it will be appended to the value of the URLDestination and used to indicate the relative (to the configured root directory of the FTP server) path name of the directory in which the uploaded file will be stored. If the value for the DirAndFilePrefix parameter does not end with a slash, then the portion of it prior to its right-most slash will be appended to the value of the URLDestination and used to indicate the relative (to the configured root directory of the FTP server) path name of the directory in which the uploaded file will be stored, and the portion after the right-most slash will be prepended to the name of the file that will be created at the destination.

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

Prompts

Specifies the number of files that the end user will be prompted to upload as an integer.

&UserFileArray

Returns the names of the files on the source system as an array of strings.

Note: You can specify this parameter as a zero-length array of string. The array will be populated by MAddAttachment with the actual file names.

Note: The file name for each user-selected file cannot be greater than 64 characters.

&ActualSizeArray

Returns the file sizes in kilobytes for the uploaded files as an array of numbers.

Note: You can specify this parameter as a zero-length array of number. The array will be populated by MAddAttachment with the actual file sizes.

&DetailedReturnCodeArray

Returns the return code for each individual file attachment operation as an array of numeric constants.

Note: You can specify this parameter as a zero-length array of number. The array will be populated by MAddAttachment with the actual return codes.

MaxSize

Specify, in kilobytes, the maximum size of each file.

If you specify 0, it indicates “no limit,” so any file size can be uploaded. The default value of this parameter is 0.

Note: The system cannot check the size of the file selected by the end user until that file has been uploaded to the web server.

PreserveCase

Specify a Boolean value to indicate whether the case of the extension of the file to be uploaded is preserved or not at the storage location; True , preserve the case, False , convert the file name extension to all lowercase letters.

The default value is False.

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.

Note: MAddAttachment provides no indication of a conversion in the file name it returns.

UploadPageTitle

Specify a string value to be displayed in the title bar of the file attachment dialog box (as its title). This string should be simple text and contain no HTML elements. If no value is specified, the default value is “File Attachment.”

Note: In screen reader mode, the string value of the UploadPageTitle parameter is displayed in the body of the file attachment dialog box rather than as the title of the window.

Note: The parameter does not automatically handle localization issues. The string passed into the function is the exact string embedded in the page. You and your application are responsible for any translation issues.

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

This is an optional parameter.

The default value is False.

StopOnError

Specify a Boolean value to indicate whether to continue processing files when a system error is encountered.

If StopOnError is set to False, processing continues with the next selected file. If StopOnError is set to True, MAddAttachment terminates on the first system error encountered (for example, %Attachment_Failed, %Attachment_FileTransferFailed, and so on). No attempt is made to upload any of the remaining files. For each of the remaining files, a return code of %Attachment_Unprocessed is returned as the detailed return code.

This is an optional parameter.

The default value is False.

Returns

The MAddAttachment function returns one of the following summary return codes that you can check for either as an integer or as a constant value:

Numeric Value

Constant Value

Description

0

%Attachment_Success

The upload was successful if and only if the upload was not cancelled, at least one non-empty file name was specified by the user, and all the files specified with non-empty names were successfully uploaded.

1

%Attachment_Failed

Either the user cancelled the upload, the user specified no files to upload, or at least one of the specified files did not successfully upload.

In addition, the MAddAttachment function returns detailed return codes in the array specified by the &DetailedReturnCodeArray parameter. The array contains the number of elements specified by the Prompts parameter even if some files remain unprocessed or were not selected by the user. You can check for the detailed return codes either as integers or as constant values:

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 or 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 .

2

%Attachment_Cancelled

File transfer didn't complete because the operation was canceled by the end user.

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.

6

%Attachment_FileExceedsMaxSize

File exceeds maximum size, if specified.

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.

11

%Attachment_NoFileName

File transfer failed because no file name was specified.

12

%Attachment_FileNameTooLong

File transfer failed because name of selected file name is too long. Maximum is 64 characters.

20

%Attachment_Unprocessed

This file was not processed.

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

  1. This file was not processed due to an error in processing another file attachment.

  2. This file was not processed because the operation was canceled by the user.

13

%Attachment_ViolationFound

File violation detected by virus scan engine.

14

%Attachment_VirusScanError

Virus scan engine error.

15

%Attachment_VirusConfigError

Virus scan engine configuration error.

16

%Attachment_VirusConnectError

Virus scan engine connection error.

21

%Attachment_Rejected

File transfer failed because the file extension is not allowed.