Sterling Connect:Direct Server Run Task Service

Edit online

This is an overview of the Sterling Connect:Direct Server Run Task service:

System Name Sterling Connect:Direct® Server Run Task Service
Graphical Process Modeler (GPM) categories All Services, Applications > IBM > IBM® Sterling Connect:Direct
Description Executes a program or command synchronously to the remaining steps in a Process. The program or command can execute locally or on the remote Sterling Connect:Direct node. User programs can be run in different environments.
Business usage You want to execute a job on a mainframe. You can write a business process that uses the Run Task service to execute a script on a remote Sterling Connect:Direct node on the z/0S platform and then wait for the completion of the run task operation.
Usage example You execute a script that compresses and archives log files synchronously on a remote Sterling Connect:Direct Server.
Preconfigured? A Sterling Connect:Direct Server adapter must be configured before using this service
Requires third party files? No
Platform availability All supported Sterling B2B Integrator platforms
Related services The Sterling Connect:Direct Server Run Task Service works between a Sterling Connect:Direct Server Begin Session Service and a Sterling Connect:Direct Server End Session service,
Application requirements For information, search for Requirements.
Initiates business processes? No
Invocation The business process running this service must be started by a user with permission to issue the Run Task statement on the target Sterling Connect:Direct server.
Business process context considerations None
Returned status values
  • Success – Normal execution with the return parameters specified.
  • File not found Error – Specified file was not found.
  • Access to file denied Error – Specified file could not be accessed.
  • Unable to start file Error – Specified file could not be started.
  • Program Failure Error – Failure of the program to be executed by the specified file.
Restrictions None
Persistence level None
Testing considerations None

Implementing the Sterling Connect:Direct Server Run Task Service

To implement the service, complete the following tasks:

  1. Configure the Sterling Connect:Direct Server adapter to use with this service.
  2. Create a Sterling Connect:Direct Run Task service configuration.
  3. Configure the Sterling Connect:Direct Server Run Task.
  4. Use the service in a business process.

Sterling Connect:Direct Server Run Task Service Settings

To configure the Sterling Connect:Direct Server Run Task service, specify the following fields in the GPM.
Note: To execute a Run Task in an i5/OS environment, use only the SystemOpts field in your business process—not the Program field. For the HP NonStop environment, you must include both the pgm and SystemOpts fields.
Field Description
Program Specifies the operation to be performed in the remote environment. This field is optional depending on the platform where the operation will run. For more information, see the IBM Sterling Connect:Direct for Microsoft Windows documentation for the specific platform you are communicating with.

The valid values depend on the destination Sterling Connect:Direct server. For example, the valid values for Sterling Connect:Direct for Windows are:

  • pgm (filespec) specifies which .exe or .bat file to run.
  • cmd (command | parms) specifies a system command and any arguments that this command requires.
  • args (arguments) specifies the arguments passed to the program when it is started. These arguments are in the same format specified from the command prompt. This optional parameter is only valid when you specify pgm.
    Note: Do not use this field when the remote environment is i5/OS.

    For the HP NonStop environment, the Program parameter must include the operation to be performed.
SessionToken Identifies an established session between two Sterling Connect:Direct nodes. Required. Session integrity cannot be guaranteed if the session token is omitted.
SystemOpts Specifies either the program and its arguments or only the arguments passed to the program when it is started. This is field is optional depending on the platform where the operation will run. For more information, see the Sterling Connect:Direct documentation for the specific platform you are communicating with.

The valid values depend on the destination Sterling Connect:Direct server. For example, the valid values for Sterling Connect:Direct for Windows are:

  • pgm (filespec) specifies which .exe or .bat file to run.
  • cmd (command | parms) specifies a system command and any arguments that this command requires.
  • args (arguments) specifies the arguments passed to the program when it is started. These arguments are in the same format specified from the command prompt. This optional parameter is only valid when you specify pgm.
    Note: Do not enclose the value specified for SystemOpts in double quotes.

    SystemOpts is the equivalent of Sysopts.

Parameters Passed from a Business Process to a Run Task Service

This table describes the parameters passed from the business process to the Sterling Connect:Direct Server Run Task service:

Field Description
Program Specifies the operation to be performed in the remote environment.
SessionToken Identifies an established session between two Sterling Connect:Direct nodes. Valid value is an XML structure that includes the following elements:
  • SessionId
  • ProcessNumber
  • ProcessName
  • SubmitDateTime
  • RemoteCDNodeName
  • RemoteUserId
  • RemotePasswd
  • PlexClass
  • MaxRestartRetries
  • RestartRetryInterval
  • ShortTermMaxRetries
  • ShortTermRetryInterval
SystemOpts Specifies either the program and its arguments or only the arguments passed to the program when it is started.
MaxTimeToWait Specifies a period of time the service should wait for the task to complete on the remote CD node before timing out. Valid value is in seconds. If not specified, the period to wait is used from the MaxSocketReadTimeout parameter value set in the Connect Direct Server adapter.

Parameter Passed from a Run Task Service to a Business Process

This parameter is passed from the Sterling Connect:Direct Server Run Task service to the business process:

Parameter Description
Status Indicates whether the remote job was executed.
Note: This does not address the success of the executed job. It only identifies if it was executed.

Business Process Example of the Run Task Service for Sterling Connect:Direct for UNIX

Each parameter's value and syntax is defined by the remote Sterling Connect:Direct platform and underlying operating system. When the remote platform operating system is UNIX/Linux, the command and its arguments, if any, are specified as the Program parameter value and in the same syntax that they would be entered at a shell prompt. For example, to execute the 'ls' command with the '-1' option (single column output) and send the output to a file called 'ls.out' locally on a UNIX/Linux host, type the following at a shell prompt:

$ ls -1 > ls.out

To specify this operation in the RunTask Service, assign the text to the RunTask Service Program parameter in the business process:

<assign to="Program">ls -1 /tmp &gt; ls.out</assign>
Note: The redirection operator (>) must be encoded (&gt;) to prevent XML processing errors.

Following is a business process for UNIX with the Program parameter:

<process name = "SampleRunTask">
  <sequence>
    <operation name="CD Server Begin Session Service">
…
    </operation>
    <operation name="CD Server Run Task Service">
      <participant name="CDServerRunTask"/>
      <output message="CDServerRunTaskServiceTypeInputMessage">
        <assign to="Program">ls -1 /tmp &gt; ls.out</assign>
	<assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="CD Server End Session Service">
…
    </operation>
  </sequence>
</process>

Business Process Example of the Run Task Service for Sterling Connect:Direct for Microsoft Windows

When a Sterling Connect:Direct for Microsoft Windows node receives a request to execute a task, the business process must specify whether or not the task requires a cmd shell to execute. Sterling Connect:Direct for Microsoft Windows defines a syntax for communicating this information. To execute a program, the pgm and args keywords are used:

<assign to="Program">pgm(\path\file.exe) args(arg1 arg2 arg3)</assign>
Note: The args keyword is only used when arguments are needed. The path is computed according to Sterling Connect:Direct rules. If the Program directory is defined for the submitting user on the remote node, the pgm value will be appended to its value prior to use.

To execute a Windows command:

<assign to="Program">cmd(command arg1 arg2 arg3)</assign>

The following business process demonstrates how to configure the Sterling Connect:Direct

 
RunTask Service:<process name = "SampleRunTask">
  <sequence>
    <operation name="CD Server Begin Session Service">
…
    </operation>
    <operation name="CD Server Run Task Service">
      <participant name="CDServerRunTask"/>
      <output message="CDServerRunTaskServiceTypeInputMessage">
<assign to="Program">cmd(dir 	mp &gt; 	mp\dir.out)</assign>
</output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="CD Server End Session Service">
…
    </operation>
  </sequence>
</process>

Run Task Service Parameter for Sterling Connect:Direct for z/OS

The SystemOpts parameter value is appended to the Program parameter value. Use this parameter when the remote node is Sterling Connect:Direct for z/OS®. In this case, the Program parameter value specifies the remote program name only. Any remote program parameters are specified using the SystemOpts parameter. Do not enclose values in double quotes. For information about the format of the SystemOpts parameter in Sterling Connect:Direct for z/OS, refer to the Sterling Connect:Direct Process Language Web Site.

The following example uses the data type of character in the parameter list:

<assign to="SystemOpts">C' ALLOC',C' DSN=CSDQA1.O.TESTFILE.SMS2',
C' DISP=(MOD,DELETE)',F'-1',C' UNALLOC',C' DSN=CSDQA1.O.TESTFILE.SMS2'
</assign>