xcicsctl (UNIX/Linux)

On UNIX/Linux system, an XCICS region can be easily controlled using the xcicsctl shell script, which provides an user friendly interface for the most frequently used administrative tasks.

-c	console mode
-v	verbose mode
-i	immediate mode for shut
-h	hard mode for report (just system report)
-s	soft query for status (uses xcicsadm to determine application status)
-f<file>	uses <file> configuration
-j<file>	execute the start-up job
-9	forces kill to invoke signal 9 (SIGKILL)
-t	skips transient data erasure on cold start

0	success
1	error on options
2	configuration error
8	network busy
9	application already active

When the application starts as a background process, no information log is displayed on the console terminal and the operator may close the shell used to enter the xcicsctl command. In this case, the information log will be written on the lastlog file in the logs directory (LOG_PATH if defined in the XCICS profile or $HOME/logs).

WARNING: if XCICS is started up as foreground process, every interruption sent to terminal will kill the application

start	cold start up application
warmstart	warm start up application
stop \| shut	shutdown application
status	briefly inquiry application status
reload	forces engines re-generation
reconfigure	forces xcics reconfiguration
kill	terminate all application processes by signal 15
report	report information about application

The first starting process is CXMAIN, which initializes the application environment.

To startup XCICS, after the configuration and tables files have been created, type at the shell prompt:

During the initialization phase CXMAIN loads the environment variables and reads the configuration file in order to create a temporary file named “CX_<application_name>” in the HOME directory. This file contains all information relevant to the XCICS execution environment such as PID number, Queue identifiers and other information. It will be deleted by CXMAIN at the end of the session.

The terminal where the xcicsctl shell has been executed operates as the XCICS console for the current session, so that messages displayed by all running transactions or informing the operator on the normal/abnormal processing, error messages and notifications are collected on this terminal.

All what is displayed on the XCICS console will be also saved in the session log file, whose name is “xcicslog.<datetime>”.

Different opportunities are available to choose whether or not a message is to be displayed on the console and/or on the session-log file, or if it must simply be ignored. Such a directive is memorized in the first byte ( ocb - output control byte -) of each message record on the standard xlikeMsg message file.

No input is needed except the interrupt key to abort the XCICS session, only in the case that it is not possible to use any normal XCICS shutdown procedures.

It is possible to customize the message file, through adding user messages, deciding which message to activate or simply translating the messages in other languages. User messages will be displayed using the standard output routine “XlikeMsg” contained in the XCICS libraries. This routine may also be used by other UNIX processes which desire to send a message to the XCICS console or to store it in the session-log file.

During startup, CXMAIN may display information, warning or error messages, caused by wrongly defined or unavailable resources. In this eventuality, depending on the reason and weight of the error, XCICS will continue the loading or it terminates its execution. A complete list of all messages that may be output on the XCICS console with their meaning, can be found in paragraph 1.5.

If no severe error occurs, the initialization phase terminates when the following message appears:

In case that a previous session was terminated due to a system crash or a power failure, XCICS can fail while starting up. In such a case it is advisable to perform a warm restart by means of the -w:

which executes a dummy cleaning of its communication areas, and forces XCICS to start up.

In the online procedure, the XCICS system can be terminated normally by a terminal session (XCLIENT) with administration authorization, by entering the administrator reserved transaction code “SHUT”.

In this case, you are requested to confirm the session close request by the question:

If 'Y' or 'y' is replied, the XCICS session specified application will be closed.

If -y is specified to xcicsctl no confirmation is required, and XCICS is automatically closed. This option is useful when XCICS has to be closed automatically.

N.B.: Please consider that XCICS will be terminated in both cases : online procedure and command line IMMEDIATELY. This has for consequence that eventual transactions still "in flight" are closed and rollbacked.

In case you have more than one XCICS application running on your server, you will have more than one XCICS configuration files, located in different directories. The xcicsctl will close the application pointed by the xcics.conf associated to the path of directories in which you are currently working.

To control if a certain XCICS application is currently active and running, enter :

XCICS should never been killed, but if operator needs to shut XCICS immediatly, the kill command provides killing for each XCICS process.

Due to different reasons (i.e. refresh copies of programs loaded with CALL), XCICS engines may be restarted. When a restart is invoked, XCICS immediatly respawns free engines, and schedules the respawn of busy engines, that will be restarted as soon as they complete the currently running transaction.

In order to change entries above, user only have to update its configuration file, and issue the "reconfigure" command.

When a reconfigure is invoked, XCICS reloads its configuration, immediatly respawns free engines, and kill busy engines and backround task, in order to avoid transaction corruption.