Submitting a Process

The submit command makes Processes available for execution and enables the software to interpret the Process statements contained in the specified files.

Parameters specified in the submit command override the same parameters specified on the Process statement. There are no required parameters. However, if you do not specify a file name for the file parameter, the text of the IBM® Connect:Direct® Process must follow the submit command. Following are the parameters for the submit command:

Parameter Description Values
file The name of the Process file. The file name can include a path name indicating the location of the Process.

This parameter must be the first parameter.

file name including the path name
class The node-to-node session on which a Process can execute. A Process can execute on the class specified or any higher session class. The default class is specified as the sess.default parameter of the local.node record in the initialization parameters file. 1 | n

A numeric value from 1 to the value of maximum concurrent local node connections (sess.pnode.max). The default value is 1. The value cannot be greater than the maximum number of local sessions with primary control.

crc Determines if crc checking is performed. This parameter overrides settings in the initialization parameter, the network map, and the Process.
Note: The user must be assigned authority to change the crc settings in the user authority file.
on | off

on—Turns on crc checking.

off—Turns off crc checking. The default is off.

hold Determines if the Process is placed in the Hold queue.

When a Process is submitted with retain=yes or retain=call, IBM Connect:Direct ignores the hold parameter.

yes | no | call

yes—Specifies the Process is placed in the Hold queue in HI status until it is released by a change process command. A Process submitted with hold=yes is placed on the Hold queue even if you specify a start time.

no—Specifies that the Process executes as soon as resources are available. This is the default.

call—Specifies that the Process is held until a connection is established between the remote node and the local node. At that time, the Process is released for execution.

maxdelay How long the submit command waits for the submitted Process to complete execution. This parameter is useful when the command is issued by a shell script. When this parameter is specified, the script waits until the Process completes before it continues execution. The return code of the Process is stored in the $? variable if you are using the Bourne or Korn shell and in $status variable if you are using the C shell, which the shell script can use to test the results of Process execution. If you do not specify maxdelay, no delay occurs.

If the time interval expires, the submit command returns a warning status code and message ID to the issuing Process or CLI/API. The Process is not affected by the time interval expiration and executes normally.

unlimited | hh:mm:ss | 0

unlimited—Waits until the Process completes execution.

hh:mm:ss—Waits for an interval no longer than the specified hours, minutes, and seconds.

0—Waits until the Process completes execution. If you specify maxdelay=0, you get the same results as when you specify maxdelay=unlimited.

newname A new Process name that overrides the name in the submitted Process. A name up to 256 characters long
notify The user e-mail to receive Process completion messages. This parameter uses the rmail utility available in the UNIX System V mail facility to deliver the completion messages.
Note: IBM Connect:Direct does not validate the e-mail address or user ID supplied to the notify parameter. Invalid e-mail addresses and failed E-mail attempts are handled according to the local mail facilities configuration.
username@hostname or user@localhost
pacct A string containing information about the PNODE. Enclose the string in double quotation marks. pnode accounting data” up to 256 characters
pnodeid Security user IDs and passwords at the PNODE. The pnodeid subparameters can contain 1–64 alphanumeric characters. id , pswd

id—Specifies a user ID on the PNODE.

pswd—Specifies a user password on the PNODE.
If you specify pnodeid, you must also specify id. Identify the ID first and the pswd last.

prty The priority of the Process in the Transmission Control Queue (TCQ). A Process with a higher priority is selected for execution before a Process with a lower priority. The prty value does not affect the priority during transmission. 1–15, where fifteen is the highest priority. The default is 10.
retain Determines if IBM Connect:Direct retains a copy of the Process in the TCQ. IBM Connect:Direct assigns a Process number to the Process when it is placed in the retain queue. When it's time for a retained process to execute, a new process, which is a copy of the retained process, is created and assigned the next available process number and made available for execution.

If you specify a start time and set retain=yes, the Process remains in the Timer queue in HR status and is submitted at the appropriate interval. For example, when startt=(Monday,2:00), the Process runs each Monday at 2:00 AM. When startt=(,1:00), the Process runs daily at 1:00 AM. IBM Connect:Direct does not provide a way to run a Process hourly. To do this, you must use the UNIX cron utility.

If no start time is identified, you must issue a change process command to release the Process for execution. 
Do not code the startt parameter when you specify retain=initial.

yes | no | initial

yes—Specifies that the system retains the Process in the Hold queue in HR status after execution.

no—Specifies that the system deletes the Process from the TCQ after execution. This is the default.

initial—Specifies that the system retains the Process in the Hold queue in HR status for automatic execution every time the Process Manager initializes.

sacct Specifies accounting data for the SNODE. Setting this value in the submit statement overrides any accounting data specified in Process. snode accounting data” up to 256 characters. Enclose the string in double quotation marks.
snode Identifies the name of the secondary node. Setting this value overrides the snode value in the Process statement. The snode parameter is required either on the submit command or Process statement. name | host name | nnn.nnn.nnn.nnn or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;port name | nnnnn]]

name—Specifies the node name of the remote node. The secondary node name corresponds to an entry in the network map file.

host name—Specifies the name of the host computer where the remote IBM Connect:Direct node is running.

nnn.nnn.nnn.nnn or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn —Specifies the IP address of the remote node in IPv4 or IPv6 format: nnn.nnn.nnn.nnn (IPv4) or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn (IPv6).

[;port number |nnnnn]—Identifies the communications port. You can only use this parameter with the host name or IP address parameters. The nnnnn value is a decimal number from 1,024–65,535.

snodeid Specifies security user IDs and security passwords on the SNODE. The snodeid subparameters can contain one or more alphanumeric characters.

If IBM Connect:Direct finds that a Process has no snodeid parameter or defines a snodeid parameter and the initialization parameter proxy.attempt is set to y, then any password specified on the snodeid parameter is ignored. A proxy user record is a remote user record in the userfile.cfg, which corresponds to the user name specified on the snodeid parameter. If no proxy user record exists, the snodeid parameter must contain a valid user name and password for a UNIX user who has a corresponding local user record in the userfile.cfg file.

When proxy.attempt=n and no snodeid is defined, IBM Connect:Direct uses the submitting ID and node to find a Remote User Information record in the User Authorization Information file. If IBM Connect:Direct cannot find a match, then that user cannot send or receive files.

If the initialization parameters file parameter proxy.attempt is set to y, users are not required to specify a password for the snodeid parameter. This capability enables the id subparameter to contain a dummy user ID to be used for translation to a local user ID on the remote system. The use of a dummy user ID offers improved security because neither the sender nor the receiver are required to use an actual user ID.

Reserved keywords cannot be used in the snodeid field.

id [,pswd [,newpswd]]

id—Specifies a user ID on the SNODE.

pswd—Specifies a user password on the SNODE. If you specify id, you do not have to specify pswd. This capability enables the id parameter to contain a dummy ID to be used for translation to a local ID on the remote system.

newpswd—Specifies a new password value. On certain platforms, the user password changes to the new value on the SNODE if the user ID and old password are correct (refer to documentation on the specific platform). If the SNODE is a UNIX node, the password does not change.

If you specify pswd, you must also specify id. If you specify newpswd, you must also specify pswd. Type the values in the order of id, pswd, and newpswd.

startt Identifies the date, day, and time to start the Process. IBM Connect:Direct places the Process in the Timer queue in WS (Waiting for Start Time) status. The date, day, and time are positional parameters. If you do not specify date or day, a comma must precede time.

Do not code the startt parameter when you specify retain=initial.

[date | day | daily] [,hh:mm:ss [am | pm]]

date—Specifies the day (dd), month (mm), and year (yy), which you can code as mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00, which indicates midnight. The current date is the default.

day—Specifies the day of the week. Values are today, tomorrow, yesterday, monday, tuesday, wednesday, thursday, friday, saturday, and sunday.

hh:mm:ss [am | pm]—Specifies the time of day in hours (hh), minutes (mm), and seconds (ss). You can specify the hour in either 12- or 24-hour format. If you use 12-hour format, then you must specify am or pm. The default is the 24-hour format. The default value is 00:00:00, which indicates midnight. 
If you specify only the day value, the time defaults to 00:00:00. This means that if you submit a Process on Monday, with monday as the only startt parameter, the Process does not run until the following Monday at midnight.

daily - Schedules the process for daily execution at the specified time. If the specified time has already elapsed on the day the command is submitted, the process will be scheduled for the next day. If you leave this parameter blank, the process will be scheduled for daily execution. The only difference between the daily specification and leaving the parameter blank is that if the specified time has already elapsed on the day the command is submitted, the process will be submitted immediately, and then daily at the specified time thereafter.

&symbolic name 1

&symbolic name 2

&symbolic name n

Specifies a symbolic parameter assigned a value. The value is substituted within the Process when the symbolic parameter is encountered.

The value for the symbolic parameter must be in double quotation marks if it is a keyword or contains special characters. If you want to reserve the double quotation marks when the symbolic name is resolved in the Process, enclose the double-quoted string in single quotes, for example:

&filename = “‘filename with spaces'”

The symbolic name itself must not be a subset of any other symbolic name. (You cannot have, for example, a symbolic name called &param and another symbolic name called &parameter in the same Process.)

variable string 1

variable string 2

variable string n

The symbolic name cannot exceed 32 characters.

tracel Specifies the level of trace to perform for a Process. Tracing by Process can be turned on in the submit command or as part of the Process definition. level = 0 |1 | 2 | 4


level—Specifies the level of detail displayed in the trace output. The default is 4.

  • 0—Terminates the trace.
1—The basic level that provides function entry and function exit.
2—includes level 1 plus function arguments.
4—Enables a full trace. Basic diagnostic information, such as values of internal data structures at key points in the execution flow, are displayed.

file—Specifies the name of a file where the trace output is directed. If you do not specify a file name, the file is created in the IBM Connect:Direct working directory with the file name CMGR.TRC. The length of the name value is unlimited.

Scheduling IBM Connect:Direct Activity

IBM Connect:Direct places a Process in a queue based on the parameters that affect scheduling. You can specify scheduling parameters in the Process statement or the submit command.

Scheduling parameters are listed in the following section:

  • retain=yes|no|initial
  • hold=yes|no|call
  • startt=[([date|day] [, hh:mm:ss | [am | pm]])

The following table shows how scheduling parameters affect the logical queues.

Scheduling Parameter Queue Comments
None of the scheduling parameters specified Wait The Process remains in the Wait queue until IBM Connect:Direct establishes a session with the remote node. After a session is established, the Process moves to the Execution queue.
retain=yes Hold A copy of the Process executes once, unless you specify a startt parameter value. Specify a day or time or both for the Process to start.
retain=no Wait (if no other parameters are specified) The Process remains in the Wait queue until IBM Connect:Direct establishes a session with the remote node. The default is no.
retain=initial Hold A copy of the Process remains in the Hold queue and executes every time the Process Manager is initiated.
retain=yes and hold=no or hold=call Hold A copy of the Process remains in the Hold queue to be executed when released.
hold=yes Hold You can execute the Process by specifying the change process command with the release parameter.
hold=no Wait (if no other parameters are specified) The default for hold is no.
hold=call Hold The Process remains in the queue until the remote node starts a session with the local node or another Process starts a session with that remote node.
startt Timer When the scheduled day or time occur, the Process is moved to the Wait queue.

Each Process in the TCQ has an associated status value. Each status value has a unique meaning that is affected by the logical queue in which the Process is placed. Status values for each queue are shown in the tables in the following sections. You can use the select process command to examine that status of Processes in the TCQ. For example, the following command displays all Processes in the TCQ with execution status:

select process status=EX;

Example - Submit a Process That Runs Every Week

The following command submits the Process named payroll:

submit file=payroll retain=yes startt=monday pacct=“1959,dept-27";

Because retain=yes is specified in this sample, the Process is retained in the TCQ after execution. The Process starts next Monday at 00:00:00 and runs every Monday thereafter. Process accounting data is specified for the PNODE.

Example - Submit a Process with a Start Time Specified

The following command submits the Process named copyfil:

submit file=copyfil snode=vmcent startt=(01/01/2008, 11:45:00 am);

Because startt is specified, the Process executes on the first day of January 2008 at 11:45 a.m.

Example - Submit a Process with No File Value

The following command submits a Process without a file parameter value, but with the Process statements typed at the CLI command prompt:

Direct> sub do_copy process  snode=node1
step01 copy from (
            to   (
      pend ;
Process Submitted, Process Number = 5

Example - Submit a Process and Turn On Tracing

The following command submits the Process named copy.cdp:

submit file=copy.cdp tracel=4;

Because tracel is specified, an SMGR and COMM full trace is performed on the Process. Trace information is written to the default file SMGR.TRC.