How to use GENERIC jobs

I wanted to expand on the earlier discussion on GENERIC jobs.

The v12.x documentation offers no explanation whatsoever of how to use Generic jobs. To learn a bit more, we have to go back to the v11.2 documentation. There, the page on Generic jobs tells how to specify the agent where a generic job should run: using the &AGENT# variable¹. How does one set the &AGENT# variable?

After several tests, I could not find a way to make Generic jobs work by setting the &AGENT# variable¹ in the pre-process of the generic job. The Generic job will switch correctly to the specified agent only if the &AGENT# variable has been set earlier, during the activation phase of task execution.

The following ways of setting the variable work OK:

• Object variable &AGENT# in Variables & Prompts of the generic job;
• Prompt set variable &AGENT# in prompt set added to Variables & Prompts of the generic job;
• Object variable &AGENT# in the task properties of the generic job within its parent workflow;
• Object or script variable &AGENT# in the calling task, if the generic job is executed via ACTIVATE_UC_OBJECT with the PASS_VALUES option; or
• Input variable &AGENT# read from the prompt/read buffer using the :READ command:
  • when passed to the job via a parameter in an EXEC VARA, or
  • when passed to the job via the set using:PUT_PROMPT_BUFFER in the calling task,
    if the generic job is executed via ACTIVATE_UC_OBJECT.

The following ways of setting the variable do not work:

• Script variable &AGENT# in the pre-process of the job (via :SET command);
• Job attribute HOST in the pre-process of the job (via :PUT_ATT command);
• Curly-brace-style VARA object reference in object variable&AGENT# in Variables & Prompts of the generic job²; or
• Predefined system or object variable in object variable&AGENT# in Variables & Prompts of the generic job³.

Notes:

1. The v11.2 release notes also mentions the &OVERWRITE_AGENT# variable, but provides no explanation how the two variables differ. (Acomment by Jennifer_Jinhong_34 suggests that the latter variable is related to ARA.) My testing revealed that one can specify the agent where a generic job should run using either the &AGENT# variable or the &OVERWRITE_AGENT# variable. If both are set, &OVERWRITE_AGENT# takes precedence.
2. Yes, I actually tried this. I created an EXEC VARA to look up the agent name dynamically. Neither this nor looking it up from a static VARA worked. The following error appeared:
   

   U00000009 '{UC4.RESOLVE_AGENT_GROUP.VARA_EXEC,,1}': Access denied

   Interestingly, VARA object references were correctly resolved in other object variable values— just not in &AGENT# or &OVERWRITE_AGENT#.
3. I also tried passing the agent name via the &ARCHIVE_KEY1# predefined variable. This resulted in
   

   U00007074 Error during generation. A Job object of the type GENERIC may only change to an OS-platform job.

   It seems that variable resolution is simply not performed on the contents of the &AGENT# and &OVERWRITE_AGENT# object variables.