Starting Flows With CMRUN

In this section:

How to:

Reference:

The CMRUN program is a standalone program for initiating flows. It also allows you to specify values for user-defined variables. CMRUN is provided with DataMigrator for z/OS, most UNIX systems, IBM i, OpenVMS, and Windows NT/2000/XP. It may be called from an z/OS job stream, a UNIX shell script, or a Windows shortcut or command file.

After a flow is run with CMRUN, a return code tells the calling program whether the flow executed successfully. For details on these return codes, see CMRUN Return Codes.

For example, on Windows, CMRUN is called from the DataMigrator installation directory, which is by default:

drive:\ibi\srv77\home\bin\cmrun.exe

Note: An iWay communication file (odin.cfg) must be configured for the DataMigrator Server.
Top of page
x
Syntax: How to Start Flows With CMRUN
CMRUN Server=server, [User=userid [,Password=password]] [,x=ddname], Request=request [,Appname=appname] [,Wait=minutes] [,I=seconds]
  [,V=variable]  [,B=begin] [,E=end]  [,Multi= Y|N]

where:

server

Is the name of the DataMigrator Server. This value is required.

userid

Is a valid user ID for the server. It is required for a secured server.

password

Is the password associated with the user ID. This is required for a secured server.

ddname

Is the location of the external password.

request

Is the name of the flow, up to 32 characters long.

appname

Is the application directory where the flow is located.

minutes

Is the number of minutes the server waits for a flow to complete. The default is 0, which specifies not to wait.

seconds

Is the number of seconds the server waits before checking if the flow has completed. The default is 15 seconds.

variable

The syntax for the local variable parameter for the aforementioned operating systems: 

variable="VAR1=value1, VAR2=value2..."]

The syntax for the global variable parameter differs for different operating systems:

For MVS:

variable="&&VAR1=value1, &&VAR2=value2..."]

For Windows:

variable=\"&&VAR1=value1, &&VAR2=value2...\"]

For UNIX:

variable=\"\&\&VAR1=value1, \&\&VAR2=value2...\"]

where:

&&VAR1, &&VAR2

Are the names of the variables.

value1, value2

Are the values assigned to the variables.

begin

Is the record to start loading at. This is not available for flat files.

end

Is the maximum number of records to retrieve from the server.

multi

Indicates if multiple instances of the flow can run at one time. The default is YES which means multiple instances can be run at one time. NO means only one instance can run at a time. If the flow is running and an attempt is made to submit a second instance, it fails with an error message:

ICM (18997) Request app/name did not start: another instance already

Note: A parameter may be abbreviated as its initial letter. Parameters must be separated by a comma and space. Syntax may vary for different operating systems. Check the examples for specifics.

Example: Sample CMRUN Batch File for Windows NT/2000/XP

Before calling CMRUN on Windows NT/2000/XP, you must set up the environment. The following are examples using the default file locations: 

set EDAHOME=C:\ibi\srv77\home
set EDACONF=C:\ibi\srv77\cln
set EDACS3=C:\ibi\srv77\cln\etc\odin.cfg
set PATH=C:\ibi\srv77\home\bin;%PATH%

The following is an example of a Windows batch file that calls CMRUN: 

cmrun s=chkserv, u=edachk, p=pass, r=test, w=5, v=\"&&v1=x,&&v2=y\"
if errorlevel 20 goto rc20
if errorlevel 16 goto rc16
if errorlevel 12 goto rc12
if errorlevel  8 goto rc8
if errorlevel  4 goto rc4
echo Request OK
goto end
:rc20
  echo (20) Request timed out
  goto end
:rc16 
  echo (16) Request failed in execution
  goto end
:rc12
  echo (12) Request not found
  goto end
:rc8
  echo (8) iWAY API Error
  goto end
:rc4
  echo (4) Invalid input parameter
:end
Example: Running a Flow Using CMRUN Without Waiting for Completion

In the following example, CMRUN is called and DataMigrator does not wait for the procedure to complete: 

Run ( 1) Connecting to 'demo' as 'dm'
Run ( 2) DataMigrator Server: Version 7, Release 7
ICM (18774) Deferred request decode created
ICM (18762) Job ID: 2002-11-13-18-37-28cmrpip000007_loopback
Example: Running a Flow Using CMRUN and Waiting for Completion

In the following example, CMRUN is called and DataMigrator waits for the procedure to complete. The procedure is executed successfully. 

Run ( 1) Connecting to 'demo' as 'dm'
DataMigrator Server: Version 7, Release 7

At completion, the following messages display:

ICM (18762) Job ID: 2002-11-14-09-41-29t3rp3648_00000001
ICM (18763) Request demo complete

In the following example, CMRUN is called and DataMigrator waits for the procedure to complete. The request fails.

Run ( 1) Connecting to 'demo' as 'dm'
DataMigrator Server: Version 7, Release 7

When the request fails, the following messages display:

ICM (18762) Job ID: 2002-11-13-18-37-28t3rp232_00000002
ICM (18764) Request decode failed; RC = 350
Example: Sample CMRUN Shell Script for UNIX

The following is an example of UNIX shell script that calls CMRUN: 

#!/bin/ksh
export EDAHOME=/home/ibi/srv77/home
export EDACONF=/home/ibi/srv77/dm
export SHLIB_PATH=$EDAHOME/bin:/usr/lib:/lib
export EDACS3=$EDACONF/etc/odin.cfg
$EDAHOME/bin/cmrun.out s=EDASERV, r=runtest, u=edachk, password=pass,
   w=10, b=2, e=5, v=\"\&\&v1=x,\&\&v2=y\"
Example: Sample CMRUN Shell Script for SUN Solaris

The following is an example of SUN Solaris shell script that calls CMRUN: 

#!/bin/ksh
export EDAHOME=/home/ibi/srv77/home
export EDACONF=/home/ibi/srv77/dm
export LD_LIBRARY_PATH=$EDAHOME/bin:/user/lib:/lib
export EDACS3=$EDACONF/etc/odin.cfg
$EDAHOME/bin/cmrun.out s=EDASERV, r=runtest, u=edachk, password=pass,
   w=10, b=2, e=5,v=\"\&\&v1=x,\&\&v2=y\"
Example: Sample CMRUN Shell Script for AIX

The following is an example of AIX shell script that calls CMRUN: 

#!/bin/ksh
export EDAHOME=/home/ibi/srv77/home
export EDACONF=/home/ibi/srv77/dm
export LIB_PATH=$EDAHOME/bin:/user/lib:/lib
export EDACS3=$EDACONF/etc/odin.cfg
$EDAHOME/bin/cmrun.out s=EDASERV, r=runtest, u=edachk, password=pass,
   w=10, b=2, e=5, v=\"\&\&v1=x,\&\&v2=y\"
Example: Sample CMRUN Batch File for USS

The following is an example of JCL that calls CMRUN from USS: 

//CMRUN JOB (CMRUN),CLASS=A,MSGCLASS=Q,MSGLEVEL=(1,1),
// NOTIFY=DMUSER
//*
//* This JCL can be used to run DataMigrator jobs
//* You will need to provide the following information under
//* the EDAPARM DDname
//* U= Defaults to current userid
//* P= Password of above userid
//* R= Name of DataMigrator flow to run
//* W= Wait time
//*********************************************************************
//CMASAP EXEC PGM=CMRUN
//STEPLIB DD DISP=SHR,DSN=qualif.SRV77.HOME.LOAD
//EDAPARM DD *
S=LOOPBACK, USER=edachk, p=passwd, R=request1, APPNAME=baseapp, W=1,
 V="&&VAR1='abc',&&VAR2=123" 
//EDAENV DD *
EDACONF=home/ibi/srv77/dm
EDAHOME=home/ibi/srv77/home
EDACS3=home/ibi/odin.cfg
EDACS3=home/ibi/odin.cfg
PATH=/bin
//SYSIN DD DUMMY
//STDOUT DD SYSOUT=A
//STDERR DD SYSOUT=A
//SYSPRINT DD SYSOUT=A
Example: Sample CMRUN Code for OpenVMS

The stand-alone program for initiating requests can be used on OpenVMS. The following is an example of a command procedure that calls CMRUN. 

$ SET NOON
$ szParms = "''p1' ''p2' ''p3' ''p4' ''p5' ''p6'"
$ CMRUN   = "$" + f$trnlnm("EDAHOME") - "]" + ".BIN]cmrun.exe"
$ CMRUN 'szParms
Example: Sample CMRUN Code for IBM iSeries

The following is an example of a shell script that calls CMRUN on IBM iSeries:

#!/bin/qsh
export EDAHOME=home/ibi/srv77/home
export EDACONF=home/ibi/srv77/dm
export EDACS3=home/ibi/odin.cfg
export PATH=/bin
export SHELL=/bin/sh
liblist -a srv77 
home/ibi/srv77/home/bin/cmrun.out s=EDASERV, r=request1, u=edachk, 
p=pass, APPNAME=baseapp, w=60

where:

srv77

Is the library name for edahome provided during installation
Top of page
x
Reference: CMRUN Return Codes

When a flow is completed, CMRUN sets a return code that can be viewed in the calling environment. These codes are listed and described in the following table:

Code

Description

0

The value of the 0 code depends on the Wait parameter setting:

  • If set to zero, the request was submitted successfully.
  • If set to a number greater than zero, the request completed successfully.

4

Invalid input parameter.

8

iWay API returned an error.

12

Request submission failed because the flow was not found, was incomplete, or the user was not authorized.

16

The request failed during execution. This return code may occur only when the Wait parameter is set to a number greater than zero.

20

The request timed out. This return code may occur only when the Wait parameter is set to a number greater than zero.

A return code of 8 indicates that the iWay API returned an error. This error message is displayed by CMRUN. The most common errors are:

Code

Description

-7

Unable to initialize Connector.

This status code indicates that the API was either unable to find or unable to read the communications configuration file. Check that the location of the correct configuration is the first one accessible using the PATH, and ensure that the contents are readable and correct

-9

Unable to connect to server.

This return code generally indicates either that the server or communications resources are unavailable, or that there is an error in the configuration. Ensure that the resources indicated in the Connector configuration file are correct and available. Ensure that the server name indicated is correct and that it matches the service name on the server (for non-UNIX servers). Ensure that you can ping the host if TCP/IP is the protocol. Check to see if a connection to the server is possible from an alternate client. If this is successful, either the client configuration is incorrect or the communications resources are not available from that location. If this is not successful, ensure that the server is up and running and that it is not in an error state.

-12

Data receive failure.

This status code indicates that a problem was encountered while the client was attempting to receive data from the server after an initial successful connection. Check the server status after receiving this error and check that the communications resources are intact. A -12 may occur for a specific request or for specific data retrieval.

-17

Invalid user ID or password.

This status code indicates that a connect attempt was made to a secure server and that the user ID and/or password details supplied were not authorized for that server. A -17 may also occur if the user ID and password do not pass security exit checks set up on the server.

Note: Some servers are case-sensitive.

-20

Expired password.

This status code is issued if a user attempts to connect to the server and the password is expired.

A flow may fail during connection to the server or while being run. For details on the problems that may cause a failed flow, see Problems, Errors, and Troubleshooting.

Top of page
x
Specifying an External Password

On z/OS, CMRUN allows you to supply the server password from an external data set that can be RACF or Top Secret. An X parameter specifies the ddname of an external data set (which must then be allocated) that contains the password.

The data set containing the password should contain a single line with the password. The password is case-sensitive and is terminated by the first blank space so the password cannot contain blanks. It should be allocated with an LRECL=80 and RECFM=FB.
Example: Specifying an External Password With SYSIN

The following provides an external password. 

//CMRUN   EXEC PGM=CMRUN
//EDAPARM DD *
S=server, U=user, R=request, W=10, X=//DD:PASSWD
/*
//PASSWD, DD DSN=qualif.PASSWORD.DATA,DISP=SHR
iWay Software