PeopleCode Built-in Functions and Language Constructs: M

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. A user can select multiple files at once. Use the AddAttachment function to upload a single file.

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 PeopleTools Browser Compatibility Guide (Oracle Support Document 704492.1) 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 Understanding File Attachment Storage Locations.

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

  See File Name Considerations.

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

  See Attachments with non-ASCII File Names.

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

  See Considerations When Attaching Text Files.

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

  See Restrictions on Invoking Functions in Certain PeopleCode Events.

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

  See Restricting the File Types That Can Be Uploaded or Downloaded.

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

  See Restricting the File Types That Can Be Uploaded or Downloaded.

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

  See Setting Up Virus Scanning.

• The HTML sanitizer can be enabled and configured to scan and sanitize specific HTML file types (specified by file extension) uploaded with the AddAttachment function.

  See Using the HTML Sanitizer.

You can use a file extension list to identify file types to accept or reject when using this function.

See Using Administration Utilities.

Parameters

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:

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:

Example

&retcode = MAddAttachment(URL.MYFTP, ATTACHSYSFILENAME, 4, &MyFileArray, &MySzArray, &MyRtrnCodeArray, 0, False, "Upload Attachments", False, True);

The following example demonstrates initialization of the arrays used to store the values returned by MAddAttachment:

&prompts = 2;
Local array of string &AttachUsrFiles;
&AttachUsrFiles = CreateArrayRept("", 0);

Local array of number &AttachSzs;
&AttachSzs = CreateArrayRept(0, 0);

Local array of number &AttachRtrnCds;
&AttachRtrnCds = CreateArrayRept(0, 0);

If Exact(Left(&URL_ID, 4), "URL.") Then
   &sum_rt_cd = MAddAttachment(@(&URL_ID), ATTACHSYSFILENAME, &prompts, &AttachUsrFiles, &AttachSzs, &AttachRtrnCds);
Else
   &sum_rt_cd = MAddAttachment(&URL_ID, ATTACHSYSFILENAME, &prompts, &AttachUsrFiles, &AttachSzs, &AttachRtrnCds);
End-If;

Syntax

MarkPrimaryEmailAddress(Type)

Description

Use the MarkPrimaryEmailAddress function to specify which email address is the primary email address for the current user. You can only have one primary email address per user.

Parameters

Returns

None.

Syntax

MarkWLItemWorked()

Description

Use the MarkWLItemWorked function to mark the current Worklist entry as worked using this function. This function works only if you’ve invoked a page from the Worklist. This function should be called only in Workflow PeopleCode. You can use the %WLName system variable to check whether the page has been accessed using a Worklist.

See SaveWithCustomData.

Parameters

None.

Returns

Returns a Boolean value indicating whether it executed successfully. The return value is not optional.

Example

This example, which would be in the WorkFlow event, checks to see whether a page check box MARK_WORKED_SW is selected, and if so, it marks the item in the worklist as complete:

If MARK_WORKED_SW = "Y" Then
   If MarkWLItemWorked() Then
   End-If;
End-If;

Syntax

Max(param_list)

Where param_list has the form

parameter1, parameter2 [, parameter3, . . . parameterN]

Description

Use the Max function to determine the maximum value in the parameter list. The type of every item in the parameter list must be compatible with the first parameter in the list.

For example, if the first parameter is a string and the second parameter is a number with value 123.456, the second parameter is converted to the string "123.456" before the comparison is performed.

If all the values in the parameter list are alpha characters, "Z" is greater than "A" so Max("Z", "A") returns "Z".

Parameters

Returns

The item in the list that has the maximum value.

Example

&RSULT = Max("A", "B", "C", "D", "E");

Syntax

MCFBroadcast(ClusterID,QueueID, ChannelID, AgentState, AgentPresence, Message, MessageSetNumber, MessageNumber, DefaultMessage, SecurityLevel, ImportanceLevel, SenderId, NameValueString)

Description

Use the MCFBroadcast function to broadcast a notification message. You can specify whether to send the message to agents, to a queue, or even system wide. This function is used with the MultiChannel Framework.

Parameters

Returns

None.

Example

The following example would broadcast a message to a specific logical queue:

MCFBroadcast("", "SALES", "", "", "Best of Luck!", "", "", "Default Message", "PRIV1", "URGENT", "Admin", "EffDate, 2005-10-25:12:00:45");

Syntax

MessageBox(style, title, message_set, message_num, default_msg_txt[, paramlist])

where paramlist is an arbitrary-length list of parameters of undetermined (Any) data type to be substituted in the resulting text string, in the form:

param1 [, param2]. . .

Description

Use the MessageBox function to display a message box window. This function combines dialog-display ability with the text-selection functionality of MsgGet, MsgGetText, or MsgGetExplainText. The style parameter selects the buttons to be included. title determines the title of message.

The remaining parameters are used to retrieve and process a message selected from the Message Catalog.

MessageBox can be used for simple informational display, where the user reads the message, then clicks an OK button to dismiss the message box. Use MessageBox as a way of branching based on user choice, in which case the message box contains two or more buttons (such as OK and Cancel or Yes, No, and Cancel). The value returned by the function tells you which button the user clicked, and your code can branch based on that value.

In the MessageBox dialogs, both the Message Text and the Description, that is, more detailed information stored in the Message Catalog, are included.

If MessageBox displays buttons other than OK, it causes processing to stop while it waits for user response. This makes it a "user think-time" function, restricting its use to certain PeopleCode events.

See MsgGet, MsgGetText, MsgGetExplainTextThink-Time Functions.

Parameters

Returns

Returns either a Number value or a constant. The return value is zero if there is not enough memory to create the message box. In other cases the following menu values are returned:

Example

Suppose the following string literal is stored in the Message Catalog as the message text:

Expenses of employee %1 during period beginning %2 exceed allowance.

The following is stored in the Explanation:

You do not have the authority to approve this expense. Only a director 
can approve this. 

Here %1 is a placeholder for the employee ID and %2 a placeholder for the expense period date. The following MessageBox call provides bind variables corresponding to these placeholders at the end of its parameter list:

MessageBox(0, "", 30000, 1, "Message not found.", BUS_EXPENSE_PER.EMPLID, BUS_EXPENSE_PER.EXPENSE_PERIOD_DT);

If the message severity is Error or Warning, the call would display a message box similar to this:

Suppose the following is stored in the Message Catalog as the message text:

File not found.

The following is stored in the Explanation:

The file you specified wasn't found. Either select retry, and specify a new file, or cancel.

Suppose this message had a Severity of message, and you used the %MsgStyle_RetryCancel, in the following code:

MessageBox(%MsgStyle_RetryCancel, "", 30000, 2, "Message not found.");

This is how the message displays:

If the message severity is of type Cancel, a critical message is displayed similar to the following:

Syntax

Min(param_list)

Where param_list has the form

parameter1, parameter2 [, parameter3, . . . parameterN]

Description

Use the Min function to determine the minimum value in the parameter list. The type of every item in the parameter list must be compatible with the first parameter in the list.

For example, if the first parameter is a string and the second parameter is a number with value 123.456, the second parameter is converted to the string "123.456" before the comparison is performed.

If all the values in the parameter list are alpha characters, "a" is less than "m", so Min("a", "m") returns "a".

Parameters

Returns

The item in the list that has the minimum value.

Example

&RES = Min(&A, Max(&B, &C, &D), "-20");

Syntax

Minute(timevalue)

Description

Use the Minute function to extract the minute component of a Time value.

Returns

Returns the minute part of timevalue as a Number data type.

Example

If &TIMEOUT contains "16:48:01" then the example sets &TIMEOUT_MINUTES to 48:

&TIMEOUT_MINUTES = Minute(&TIMEOUT);

Syntax

Mod(x, divisor)

Description

The Mod function is the modulus math function, which divides one number (x) by another (divisor) and returns the remainder.

Returns

Returns a Number equal to the remainder of the division of the number x by divisor.

Example

The example sets &NUM1 to 1 and &NUM2 to 0:

&NUM1 = Mod(10,3);
&NUM2 = Mod(10,2);

Syntax

Month(datevalue)

Description

Use the Month function to return the month of the year as an integer from 1 to 12 for the specified datevalue. The Month function accepts a date or DateTime value as a parameter.

Parameters

Returns

Returns a Number value from 1 to 12 specifying the month of the year.

Example

This example sets &HIRE_MONTH to 3:

&HIREDATE = DateTime6(1997, 3, 15, 10, 9, 20);
&HIRE_MONTH = Month(&HIRE_DATE);

Syntax

MsgGet(message_set, message_num, default_msg_txt[, paramlist])

where paramlist is an arbitrary-length list of parameters of undetermined (Any) data type to be substituted in the resulting text string, in the form:

param1 [, param2]. . .

Description

Use the MsgGet function to retrieve the Message Text text of a message from the Message Catalog and substitutes in the values of the parameters into the message text

You can access and update messages on the Message Catalog page (select PeopleTools, Utilities, Administration, Message Catalog). You can enter message text in multiple languages. The Message Catalog also enables you to enter more detailed description text about the message. The message_set and message_num parameters specify the message to retrieve from the catalog. If the message is not found in the Message Catalog, the default message provided in default_msg_txt is used. Message sets 1 through 19,999 are reserved for use by PeopleSoft applications. Message sets 20,000 through 32,767 can be used by PeopleSoft users.

The optional paramlist is a comma-separated list of parameters; the number of parameters in the list is arbitrary. The parameters are referenced in the message text using the % character followed by an integer corresponding to the position of the parameter in the paramlist. For example, if the first and second parameters in paramlist were &Fieldname and &Username, they would be inserted into the message string as %1 and %2. To include a literal percent sign in the string, use %%; %\ is used to indicate an end-of-string and terminates the string at that point. This is generally used to specify fixed-length strings with trailing blanks.

MsgGet prefixes the message with "[Message Set# and Message Error#]", so it can be processed by a user not conversant in the translated language.

Example

&MsgText = MsgGet(30000, 2, "Message not found");

Syntax

MsgGetExplainText(message_set, message_num, default_msg_txt[, paramlist])

where paramlist is an arbitrary-length list of parameters of undetermined (Any) data type to be substituted in the resulting text string, in the form:

param1 [, param2]. . .

Description

Use the MsgGetExplainText function to retrieve the Description text of a message from the Message Catalog and substitutes the values of the parameters in paramlist into the Description text. It returns the resulting message as a String data type.

You can access and update messages on Message Catalog page (select PeopleTools, Utilities, Administration, Message Catalog). You can enter messages in multiple languages.

Message sets 1 through 19,999 are reserved for use by PeopleSoft applications. Message sets 20,000 through 32,767 can be used by PeopleSoft users.

Unlike the MsgGet function, MsgGetExplainText returns the message without a message set and message number appended to the message.

Parameters

Example

Suppose the following Description text is stored in the Message Catalog:

A reference was made to a record.field (%1.%2) that is not defined within Application Designer.  Check for typographical errors in the specification of the record.field or use Application Designer to add the new field or record.

Here %1 is a placeholder for the record name and %2 a placeholder for the field name. If the record.field in error was MyRecord.Field5, the above would resolve as follows:

A reference was made to a record.field (MYRECORD.FIELD5) that is not defined within Application Designer.  Check for typographical errors in the specification of the record.field or use Application Designer to add the new field or record.

Syntax

MsgGetText(message_set, message_num, default_msg_txt[, paramlist])

where paramlist is an arbitrary-length list of parameters of undetermined (Any) data type to be substituted in the resulting text string, in the form:

param1 [, param2]. . .

Description

Use the MsgGetText function to retrieve the Message Text text of a message from the Message Catalog and substitutes the values of the parameters in paramlist into the message. It returns the resulting message as a String data type.

You can access and update messages on Message Catalog page (select PeopleTools, Utilities, Administration, Message Catalog). You can enter message text in multiple languages. The message_set and message_num parameters specify the message to retrieve from the catalog. If the message is not found in the Message Catalog, the default message provided in default_msg_txt is used. Message sets 1 through 19,999 are reserved for use by PeopleSoft applications. Message sets 20,000 through 32,767 can be used by PeopleSoft users.

The parameters listed in the optional paramlist are referenced in the message text using the % character followed by an integer referencing the position of the parameter in the function call. For example, if the first and second parameters in paramlist were &FIELDNAME and &USERNAME, they would be inserted into the message string as %1 and %2. To include a literal percent sign in the string, use %%; %\ is used to indicate an end-of-string and terminates the string at that point. This is generally used to specify fixed-length strings with trailing blanks.

Unlike the MsgGet function, MsgGetText returns the message without a message set and message number appended to the message.

Example

&MsgText = MsgGetText(30000, 2, "Message not found");