Starting Flows With CMRUN

In this section:

How to:

Reference:

The CMRUN program is a stand-alone program for initiating flows. It also allows you to specify values for user-defined variables. It is usually called from an z/OS JCL job stream, a UNIX shell script, OpenVMS DCL, or a Windows shortcut or command file that sets up prerequisite environment values, as shown in the examples that follow. Samples of these scripts may also be found in the bin location of the server configuration as cmrun, (suffixed with the applicable platform extension for platforms that use directories). You can use these samples as the base to create your own scripts, as described below.

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=filename], 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 server ID of the user. This is required for password protected servers.

Note: On z/OS, the password is typically passed using the X= option.

filename

Is a physical file name, full or relative pathed, of a file containing the server user IS password. On z/OS, the value is not the direct dataset name, but a DD name issued in the z/OS CMRUN JCL to point at the dataset name.

request

Is the name of the flow, which can be 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:

Example 1:

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

Example 2:

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

Note: The CALL command should not be for executing a batch file when this syntax used, as CALL does not support caret ^ escape character.

For UNIX:

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

For System i:

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

For OpenVMS:

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 where loading starts. 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

Before calling the CMRUN executable on Windows, you must set up certain environment variables in order for the executable to run properly. This is typically done in batch files that in turn call the CMRUN executable. You can also set the variables at the machine level, or your DOS session, so they do not need to be directly included in any batch files that you create. Additionally, the PATH variable is often adjusted to avoid using the full path name of the CMRUN executable. The following is an example of how to set these variables, using the typical default file install and configure locations, in addition to setting the PATH variable:

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:

set EDAHOME=C:\ibi\srv77\home
set EDACONF=C:\ibi\srv77\cln
set EDACS3=C:\ibi\srv77\cln\etc\odin.cfg
%EDAHOME%\bin\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 HP UNIX (HPUX)

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 Linux and 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 JCL Batch File for USS Deployment

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

//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
PATH=/bin
//SYSIN DD DUMMY
//STDOUT DD SYSOUT=A
//STDERR DD SYSOUT=A
//SYSPRINT DD SYSOUT=A

Note: To enable traces for CMRUN, pass the -traceon parameter with EDAPARM ddname. For example:

//EDAPARM DD  *
-traceon
S=LOOPBACK, USER=edachk,, p=passwd,, R=request1, APPNAME=baseapp, W=60

As a result, the cmrun.trc and tscom3.trc files will be created in your USS user directory.



Example: Sample CMRUN JCL Batch File for PDS Deployment

The following is an example of JCL that calls CMRUN under PDS Deployment:

//CMRUN JOB (INFO),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
//* EDAPARM DDname
//* U=           Defaults to current userid
//* P=           Password of above userid
//* R=           Name of DataMigrator job to run
//* APPNAME=     Name of application directory for job (R=) above
//* W=           Wait time
//*
//CMASAP EXEC PGM=CMRUN,REGION=1024M
//STEPLIB DD DISP=SHR,DSN=EDAPORT.MVS.BP9999.P.HOME.LOAD
//EDACCFG DD DISP=SHR,DSN=E.MVS.BP9999.ETX.CFG
//EDAERR  DD DISP=SHR,DSN=E.MVS.BP9999.ETX.CFG
//        DD DISP=SHR,DSN=EDAPORT.MVS.BP9999.P.HOME.ERR
//CURFEX  DD DISP=NEW,UNIT=SYSDA,SPACE=(CYL,(1,1,10)),
//            DCB=(RECFM=VB,LRECL=2044,BLKSIZE=27998,DSORG=PO)
//EDAPARM DD  *
S=LOOPBACK, USER=EDAPORT, p=yyy, R=xxx, APPNAME=baseapp, W=1, MULTI=Y,
Variables="v1=x,v2=y"
//EDAENV  DD  *
EDACS3=//DD:EDACCFG(ODIN)
//SYSIN     DD  DUMMY
//STDOUT    DD  SYSOUT=*
//STDERR    DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//EDAPRINT  DD  SYSOUT=*

The following example shows an alternate way to code the EDAPARM DD section:

// PARM=('/,s=NODENAME', ...,V=\"v1=x,v2=y\"'),
// COND=(0,NE)

This allows for a condition test within the JCL. However, under this style of JCL, the double quotes also require escaping with a back slash so that the double quotes literally get passed to the called procedure.

Note: The back slashes are a JCL syntax requirement, and not an IBI requirement.



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
$ set process/privilege=all
$ set protection=(S:RWED,O:RWED,G:RE,W:RE)/DEFAULT
$ DEFINE EDAHOME R729999F:[R729999F.home]
$ DEFINE EDACONF r729999f:[r729999f.C.etx]
$ DEFINE EDACS3 r729999f:[r729999f.C.etx.etc]odin.cfg
$ cmrun := "$R729999F:[R729999F.home.bin]cmrun.exe"
$ cmrun S="LOOPBACK", USER="edachk", P="passwd", R="request1", APPNAME="baseapp", W="60"


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
liblist -a srv77
$EDAHOME/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 non z/OS platforms, the X= parameter is used to point to a physical file, full or relative pathed, that contains the password for the CMRUN execution, which is protected by operating system security (read only to owner). On the z/OS platform, JCL and the X= parameter are used to point to a DD name that points to an external dataset that contains the password, which in turn can be RACF or Top Secret protected.

The file, or z/OS dataset, containing the password should contain a single line with the server password of the user ID. Passwords are case-sensitive and terminated by the first blank space or the end of the line.

Note: A password cannot contain blank spaces.

On z/OS, the dataset may be variable or fixed length , but must be of a sufficient LRECL for the actual password. Releases prior to 7706M required the z/OS dataset to be specifically LRECL=80 and RECFM=FB, but this restriction has been lifted in a way that prior password datasets also remain usable as is.



Example: Specifying an External Password With SYSIN

The following is a snip of the z/OS JCL change that is required for using an external password.

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

iWay Software