DO

Runs a block of Perl on the Clarive server and stores what the block evaluated to into a stash variable. It holds no nested ops; the code is the whole of it.

The op is deprecated. It still runs and existing rules are unaffected, but it appears struck through and marked DEPRECATED in the palette, and Server CODE is where new code belongs. That op keeps the block's value the same way this one does and takes JavaScript as well as Perl.

Among the code ops that remain, the differences are narrow. CODE runs a block and keeps nothing. This op runs a block and keeps its value. EVAL keeps the value too but catches errors first, then fails the job with its own wrapper around the message.

Fields

Code

The Perl to run. It is the only field this op has.

The editor is the in-page code editor. Internet Explorer gets a plain text box instead. There is no size limit worth worrying about, but a block long enough to need scrolling is a sign it should be a rule of its own.

This field takes code, not a template. ${bar} is not expanded here; it is read as Perl. Reach into the stash directly instead, as $$stash{bar}.

The code is pasted into the rule as written, and the rule is assembled and compiled in one piece before any of it runs. A syntax error here, or a variable you forgot to declare, stops the whole rule before its first op, including the ops sitting above this one. The message you get is the Perl compiler's, and it points at a line number in the assembled rule rather than at this op, so working out which block broke means matching the text of the error against the code you typed.

Where the value goes

The block's value is whatever its last evaluated statement produced. It lands in the stash under the name you put in Return Key, on the op's Options tab, not on this form.

Leave Return Key empty and the value is discarded. The code still runs, which is the usual reason to leave it empty.

Return Key has to be a single unbroken word. Surrounding spaces are trimmed, but a key with a space inside it matches nothing and the value is dropped exactly as if the field had been empty. No warning marks the difference.

The value is taken in scalar context. A block whose last statement is a list gives you the number of elements, not the elements. Finish with a reference when you want the list itself:

my @bars = grep { /^myapp/ } @{ $$stash{candidates} || [] };
\@bars;

Variables you declare with my inside the block belong to the block and are gone afterwards. To keep more than one value, write them into the stash yourself, or return a hash reference and read its parts with dotted names.

Failure

Errors are not caught. A block that dies stops the job right there, with the message the code produced. Wrap the op in TRY statement and CATCH statement when that should be survivable, or set Error Handling on the Options tab to trap or ignore it.

Inside a job the op appears in the log as a step entry at debug level, carrying the name the op has in the rule tree and nothing more. What the block printed and what it returned are never recorded. Log what matters yourself, with LOG Message after it.

The block runs on the server under the user the rule is running as, with no sandbox around it. Anything the rule can reach, the block can reach.

Combining with other ops

SET VAR and SET EXPR cover most of what people write short blocks for. Reach for code only when neither does.

Branch on the result with IF var condition THEN, or walk it with FOREACH CI when the block returned a list of resources.

Examples

Count something and branch on the count afterwards.

Code
  my $n = @{ $$stash{changesets} || [] };
  $n;

Return Key (Options tab)   changeset_count

Build a value out of several stash entries and keep it as one string.

Code
  join '-', $$stash{project_lc}, $$stash{bl}, $$stash{version};

Return Key (Options tab)   release_tag