castran

Retrieves or updates information on CICS transactions or batch programs (limited functions). Its primary use is to enable and disable transactions, but it can be used to alter other values such as the TWA size or timeout values, and to display the status of transactions. It can also perform a PHASEIN or NEWCOPY on CICS programs that are defined in the PPT.

The NEWCOPY option loads a new copy of the specified program only if it is not currently in use; otherwise, it will fail. The PHASEIN option loads a new copy even if the program is currently running. Where this is the case, the previously loaded copy remains until it is no longer in use. All requests that occur after the reload use the new copy.

Note: castran can also be invoked from within a JCL by writing a simple COBOL program to call it.

Syntax:

castran [/res-name] [/mprototype:host:WebServiceport] [/fserver-name]
    [/ttrans-id]
    [/e{e|d}]
    [/s{y|n|a}]
    [/g{y|n}]
    [/j{d|a}]
    [/d{y|n}]
    [/loutput-log]
    [/wTWA-size]
    [/qinput-timeout]
    [/xrunaway-timeout]
    [/ydeadlock-timeout]
    [/pprogram-name]
    [/nprogram-name]
    [/vbatch-program-name]
    [/uuserid]
    [/apassword]
    [/cgroup]

Syntax to issue multiple commands from a command file:

castran [/res-name] [/mprototype:host:WebServiceport] [/fserver-name] /iinput-script-file

Parameters:

/res-name

Name of the enterprise server to connect to. Defaults to ESDEMO.

Note: When calling this utility from JCL or from a WEB service (that is, when you are running the utility within a SEP) you cannot use the /r option to connect to the server. Where this is the case, you must use the /m or /f options to connect to the server.

or:

/mprototype:host:WebServiceport

Location of the Web Services and J2EE listener for the enterprise server you want to connect to. For example, /mtcp:localhost:9003

or:

/fserver-name

Name of the enterprise server to connect to. This differs from the /r option, in that it performs a lookup to locate the Web Service for the enterprise server.

[-iinput-script-file]

The input script file which will contain a list of commands to run. Any comment line in the scriptfile must have # in column 1.

[-ttrans-id]

Four byte transaction ID.

[-e{e|d}]

Set the Enable status for the specified transaction:

Setting	Description
e or no value	Enable
d	Disable

[-s{y|n|a}]

Output the full transaction status for the specified transaction.

Setting	Description
y or no value	Display
n	Suppress
a	Display details for all transactions in PCT irrespective of the transaction id specified using the /t option

[-g{y|n}]

Set the Upper Case Translation status for the specified transaction.

Setting	Description
y or no value	UC Translation
n	No UC Translation

[-j{d|a}]

Set the Screen status for the specified transaction.

Setting	Description
d or no value	Default
a	Alternate

[-d{y|n}]

Set the Transaction Dump status of the specified transaction.

Setting	Description
y	Transaction Dump
n or no value	No Transaction Dump

[-loutput-log]

The file to which the output from the command is written. The default is to standard output.

[-wTWA-size]

Set the TWA Size {0..32767} for the specified transaction.

[-qinput-timeout]

Set the Input Timeout for the specified transaction.

Setting	Description
s or no value	System default
0..408000	Timeout value in hundredths of a second

[-xrunaway-timeout]

Set the Runaway Timeout for the specified transaction.

Setting	Description
s or no value	System default
100..270000	Timeout value in hundredths of a second

[-ydeadlock-timeout]

Set the Deadlock Timeout for the specified transaction.

Setting	Description
s or no value	System default
0..408000	Timeout value in hundredths of a second

[-pprogram-name]

Issue a PHASEIN for the specified program. Please note: this is unrelated to any transaction id specified with the /t option.

[-nprogram-name]

Issue a NEWCOPY for the specified program. Please note: this is unrelated to any transaction id specified with the /t option.

[-vbatch-program-name]

Issue a NEWCOPY for the specified non-CICS program. Please note: this is similar to issuing a CNCL for a CICS program, in that the latest copy will be loaded upon the next invocation.

[-uuserid]

Authorization User ID

[-apassword]

Authorization Password

[-cgroup]

Authorization Group (Optional)

Note: Options /r, /m, /f are alternative ways of identifying the enterprise server that you want to connect to.

Return Codes:

0	Success
4	Invalid flag/Duplicate flag(s)
12	Transaction ID not found in PCT/Program not found in PPT/Incorrect user ID or password
15	Region not running/invalid command

Dependencies:

You must have started the enterprise server before you can issue a castran command.

Comments:

Multiple usage of the same parameter type, results in only the first occurrence being use. All others will be ignored.

Exceeding the maximum value for TWA size or any of the timeout options, will result in the maximum value being set.

You can use a dash (-) instead of a forward slash (/) to indicate command options.

Script files must contain a transaction ID or program name on each line (except for comments), but cannot contain region names; that is, all commands in a file relate to one region, which is specified in the initial castran call. If a path or filename contains spaces, it should be enclosed in quotation marks. For example:

castran /rESDEMO /i"c:\input scripts\my script.txt"

In order to use castran with an Enterprise Server that has security enabled, you must ensure that all resource definitions are up to date. You can do this by issuing the following command:

caspcupg /r<server name> /dp=<dfhdrdat path>

Examples:

To disable a CICS transaction called ACCT and display its status on a region called ESDEMO:

castran /rESDEMO /tACCT /ed /sy

To alter the TWA size and turn off UC Translation for ACCT in a secure region:

castran /rESDEMO /uSYSAD /aSYSAD /w255 /gn /tACCT

To perform multiple operations by using an input script:

castran /rESDEMO /imultiple_cmds.txt

Where multiple_cmds.txt contains the following lines:

# multiple castran commands
/tACCT /ed 
/tAC01 /ee /ja 
/nACCT00