Using the R Process Definition Type

The R language, an offshoot of S, is a statistical and graphics language with a long heritage. It is in widespread use around the world. It runs on all three major platforms - Microsoft Windows, Linux and macOS.

note

You must assign at least one process server to run R processes in order to use the process definition type.

Overriding the interpreter.

The standard interpreter used is that that you get by calling R. On Microsoft Windows, if the R binary is not on the path it will be located via the registry.

This should work fine on all platforms, but if it doesn't you can override it using the following:

• JCS_INTERPRETER_R - parameter used to override default, can be set to value allowed by InterpreterWhitelist_R.
• InterpreterWhitelist_R - process server parameter that takes a regex expression matching all interpreters you want supported. Use.* to allow any. On Microsoft Windows a common setting would be C:/Program Files/R/.*/R.exe to allow any version to be used.
• LocalInterpreter_R - process server parameter used to set default.

Variables and Parameters

• Parameters to the process definition are manipulated in the R source simply as if they are scalars or vectors, using the standard syntax. The customer script runs in a fresh environment so there is no clash with objects names used by the platform-agent runner.
• The R language has knowledge of data-types. String, Character and Numeric parameters are translated to their equivalent R datatype.
• Array parameters are, obviously, supported in R, and converted to vectors.

note

Date, Time, DateTime and DateTimeZone (array) parameters are translated to POSIXlt parameters. As R cannot perform calculations on POSIXlt values that are not in its local timezone, any DateTimeZone values are all translated to the local timezone.

This means that you cannot transfer the time zone of a parameter to a R variable; it will be converted to the corresponding date-time in the local time zone of the host system. Out parameters will keep the timezone created for them.

Error Handling

If your script code exits with an error this is correctly reflected in the server, and output parameters are set as far as they were already set. Do note that the R process sets.Last and options(error) to accomplish this, so if you override these then output parameters will not be set if the process aborts with an error or quits without calling.Last.

Character set

On Microsoft Windows, the character set used for the script and the parameter transfer is the 'local' default character set of the Windows OS. This can be the standard 1252 codepage for most Windows systems, or any other codepage set as the default on the system.

On UNIX (for example Linux and macOS) the character set is the character set set for the network-processor. The default may be 'C' or some other setting that does not recognise every character required. On these systems we recommend setting the LANG environment variable to a UTF-8 character set, for example en_US.UTF-8.

Examples

Parameters

The following shows how to pass numeric (N1), string (S1) and date (D1) parameters to and from R scripts:

N1    = N1 + N1                             # Add number to itself
S1    = paste(S1, S1)                       # Concatenate string
D1    = D1 - as.difftime(30, units="days")  # Deduct 30 days from D1

# Create a new DateTimeZone output array with 2 different timezones
POUTDTZ = as.POSIXlt(character(0))
POUTDTZ[1] = as.POSIXlt("2023-09-28 01:00:00", tz="WET")
POUTDTZ[2] = as.POSIXlt("2111-11-11 01:00:00", tz="EET")

# Create a new Numeric output array with 7 elements (and one 'not available' value)
PNUMARR=c(1,2,3,4,5,NA,7)

# Create a new String output array with 6 elements (one of which is 'not available')
POUTSTR=c("You", "would", "like", NA, "to", "know")

Error Out

The following example shows you how to return a non-zero exit code resulting in the process going into Error:

quit(status = 5)

See Also

• Platform Agent Process Definition Types