casout

This utility enables you to interact with different enterprise server process types, such as IMS processes, MQ listeners, and printers.

Syntax:

casout {/res-name|/sprototype:host:port|/lservername}
       [/-process-ID]
       [/uuserid]
       [/ppassword]
       [/cgroup]
       [/z[userid]]
       [/gnumber]
       [/gnumber:reldd]
       [/doutput-dsn]
       [/iclasses]
       [/jjobnumber:step[:procstep]]
       [/jrestart]
       [/knumber]
       [/mnumber]
       [/fnumber]
       [/oStart]
       [/oStart:QM:Q[:listener-name]]
       [/oStop:listener-name]
       [/oDelete:listener-name]
       [/oList]
       [/oList:name]
       [/qmessage-classes] 
       [/eIMScommand]
       [/wmpr-name]
       [/nprinter-name]
       [/boutput-classes]
       [/xprinter-exit]
       [/tprocess-ID]
       [/v]
       [/ynumber:msg]
       [/#]
       [/@]
       [/%jnumber|/%tnumber]

Connection parameters

Important: You must include only one of the following connection options.
/res-name
Connect to the named enterprise server. Defaults to ESDEMO.
Restriction: 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 /s or /l options to connect to the server.
/sprototype:host:port
Use the specified URL to find the enterprise server to connect to, for example stcp:localhost:9003.
/lservername
Look up the specified server name to find the enterprise server to connect to.

The /r, /s and /l options are alternatives and are mutually exclusive.

On UNIX you can use a dash (-) before a parameter as an alternative to a forward slash (/).

Security parameters

Important: You must include these details when the specified enterprise server is secure.
/uuserid
Authorization user ID.
/ppassword
Authorization password.
/cgroup
The sign-on group to be used when running commands.
/z[userid]
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.

Categories

JCL parameters
/gnumber
/gnumber:reldd
Display all sysout for job number number, or retrieve the relative DD for job number number.
/doutput-dsn
Output DSN for sysout retrieval. The /d option must precede the /g option.
/iclasses
Start an initiator to run jobs of the named classes.
/jjobnumber:step:procstep
Restart the job at the specified step/procstep. The procstep is optional.
/jrestart
Used to restart jobs using advanced restart functionality. See Advanced Restart Functionality for details, syntax, and examples.
/knumber
Kill job number number.
/mnumber:class
Modify job number number to use the specified class.
/fnumber
Flush the output of job number number.
/ynumber:msg
Reply to job number number with message msg.
/@
Retrieve the list of all jobs waiting for input from the console.
/%jnumber
Lists all job steps for a specified job number, output in JSON format.
/%tnumber
Lists all job steps for a specified job number, output in table format.
MQ listener parameters
/oStart
Enable MQ listener support.
/oStart:QM:Q[:listener-name]
Start the MQ listener defined for the specified queue manager QM and queue Q. If you want to start a specific listener, include the listener-name. Otherwise, Enterprise Server automatically creates and generates a name for the listener using the following form:
z#nnnnnn

where nnnnnn is a generated number set initially to 000001, and incremented by 1 with the creation of each subsequent listener.

/oStop:listener-name
Stop the named listener.
/oDelete:listener-name
Delete the named listener.
/oList
Display details of all defined MQ listeners and writers.
/oList:name
Display details for the named listener or writer.
IMS parameters
/-process-ID
Use to stop and replace an IMS MPR with the same class.
/qmessage-classes
Start an IMS Message Processing Region for the specified classes.
/eIMScommand
Execute the specified IMS command.
/wmpr-name
Name of the IMS MPR to be used.
Printer parameters
/nprinter-name
Specifies the name of the physical device to be used by a new batch printer. This option is used with the /b and /x options.
/boutput-classes
Specifies the output classes to be handled by a new batch printer. This option is used with the /n and /x options.
/xprinter-exit
Specifies the name of the name of a printer exit to be associated with a new batch printer. Used with the /n and /b options.
Generic parameters
/tprocess-ID
Terminate the batch initiator, batch printer or IMS MPR that has the specified process ID.
/v
List all batch initiators, batch printers and IMS MPRs.
/#
List standard and transient SEPs.
Note: You can specify job numbers that have a maximum length of 7-digits.

Dependencies

  • You must have started the enterprise server before you can issue a casout command.
  • In order to successfully run the casout command, you must have execute permissions on the casout resource within the OPERCMDS resource class.
  • A number of security checks are performed in addition to the verification against casout under the OPERCMDS class.

    Depending on what options are used, checks are also performed to ensure that the user has access to a particular job - such as for restarting, modifying, or viewing datasets.

    The corresponding rules are under the JESSPOOL class. When trying to retrieve a dataset, additional checks are made for the particular dataset being accessed. This is also under the JESSPOOL class.

Examples

Starting an initiator for classes EFG on Enterprise Server JCLT:

casout /rJCLT /iEFG

Start a batch printer using the physical device "TestPrinter" for classes EFG on Enterprise Server JCLT:

casout /rJCLT /bEFG /n"TestPrinter"

Start a batch printer as in the previous example, but this time associate it with a printer exit (sampprnx):

casout /rJCLT /bEFG /n"TestPrinter" /xsampprnx

Start an IMS Message Processing Region for specified message classes:

casout /rJCLTT /q001

List standard and transient SEPs on Enterprise Server MYREG:

casout /rMYREG /#

Example list of returned standard and transient SEPs:

  PID       TYPE     TRAN
--------- --------- ------
    14076 SEP
    26180 SEP
    12412 SEP
      916 SEP
    26064 SEP       CEBR
    22058 Transient CSKL

Start a listener connected to the Queue Manager named CSQ1 listening on the IMSMQ.OQ queue with a listener name of BANKBRDG on Enterprise Server BANKDEMO:

casout /rBANKDEMO /oStart:CSQ1:IMSMQ.OQ:BANKBRDG

Stop the BANKBRDG listener on Enterprise Server BANKDEMO:

casout /rBANKDEMO /oStop:BANKBRDG

show all the listeners/writers, as shown in ESMAC, including the above-created listener

Return codes

When running casout from a command line, get the return code by running the following command:

echo %ERRORLEVEL% 
All functions
Code Description
0 Successful completion
Codes relating to job modification
Code Description
5 The job is actively processing, requeued
8 The job is not in the Output Hold status, or does not exist
8 The job is in the Output Hold status, requeued
8 The job is not in the Input Hold queue or does not exist for Release command
16 The job does not exist for Class command
99 You have attempted to invoke a sub-command that is not yet implemented
Codes relating to flushing jobs
Code Description
4 Job flushed
16 Job not flushed - see secondary error code returned in message
Codes relating to job output
Code Description
< 9 The job's log was retrieved
1 Job is in the Input Hold Queue
2 Job is being parsed for syntax
3 Job is in the Input Queue
4 Job is moving from Input Queue to "Actively processing"
5 Job is being processed
7 Job is complete and is in the Held Output status
8 Job is in the Complete queue, with an Output status
16 Invalid job number - you have attempted to retrieve sysout data for a non-existent job
16 Invalid job number or DD for job, retrieval request ignored
Codes relating to restarting jobs
Code Description
16 The job does not exist for restart
32 Restart processing is not turned on. You must set the ES_JES_RESTART environment variable in order to enable restart processing.
Codes relating to killing jobs
Code Description
16 The job is not active. Kill request ignored.
Codes relating to IMS command execution
Code Description
15 Commands must be preceded by a / (forward slash)
16 IMS command failed, no response from TMC
Codes relating to process termination
Code Description
8 SEP is not an initiator, printer, or IMS MPR
Codes relating to JES and IMS functions
Code Description
99 JES/IMS support is not enabled for the region, request rejected
Codes relating to security
Code Description
199 User specified is either not authorized to work with JCL or their password is not correct. Provide valid credentials.
Codes relating to connectivity
Code Description
15 Cannot connect to region. This might be because the region is not started, or the IP address or port are wrong.