KDCSLOG - Administer the SYSLOG file

With KDCSLOG you can administer the system log file SYSLOG during runtime. You can perform the following activities:

• Switch automatic size monitoring of the SYSLOG on and off.

• Define or change the control value for size monitoring.

• Switch the SYSLOG file to the next file generation of the SYSLOG-FGG.

• Write the contents of the internal UTM message buffer to the SYSLOG file.

• Call for information about the properties of the SYSLOG file.

Effect in UTM cluster applications on Unix, Linux and Windows systems

The call applies globally to the cluster, i.e. the system log file SYSLOG is administered for each node application. Size monitoring extends beyond the current UTM cluster application run. Switching or writing of the buffer apply only to the current UTM cluster application run, i.e. to all the node applications that are currently running.

Period of validity of the change

The most recent control value set for size monitoring is also set after the next application start.

If the SYSLOG-FGG basis falls within the valid range of the SYSLOG-FGG (between the first and last file generations), openUTM first logs the basic file generation in the next application run. If the basis falls outside the valid range, openUTM opens a new file generation for the log.

---

KDCSLOG     { INFO | WRITE | SIZE=fg_size | SWITCH [ , SIZE=fg_size ] }

---

For administration using message queuing you must enter KDCSLOGA.

INFO	Information about the SYSLOG file or SYSLOG-FGG is displayed. For a description of the output, see the section following the operand description.
WRITE	All messages issued to message destination SYSLOG and still stored in buffer memory are written to the current SYSLOG file immediately. This function is useful if the SYSLOG file, opened as a simple file, is to be evaluated in run mode. All messages generated by openUTM up to this time which have SYSLOG as their destination are covered by this evaluation. However, to evaluate SYSLOG in run mode, it is better to open SYSLOG as an FGG. This enables you, before starting an evaluation, to switch over file generation with KDCSLOG SWITCH and to log all messages generated by openUTM up to this time. In other words, openUTM writes the message buffer to the “old” SYSLOG file automatically before it switches over.  However, the evaluation does not cover any of the messages generated after the switch time.
SIZE=fg_size	The KDCSLOG SIZE=fg_size command is only executed if SYSLOG was opened as an FGG. fg_size redefines the control value for automatic size monitoring of the SYSLOG file. For fg_size, enter the desired control value representing a number of UTM pages (e.g. SIZE=100 defines a control value of 100 times the size of a UTM page). fg_size >= 0 must be entered. If fg_size < 0 is entered, openUTM refuses to execute the command.  With fg_size=0 you can switch off automatic size monitoring. With fg_size > 0, automatic size monitoring is switched back on. Entries for fg_size between 1 and 99 are automatically replaced by 100. Values greater than 100 are accepted without changes as control values. Minimum value: 100  Maximum value: (231 -1)
SWITCH	Is only executed if SYSLOG was opened as an FGG.  KDCSLOG SWITCH prompts openUTM to switch the SYSLOG file to the next file generation. openUTM guarantees that no more messages are written to the old SYSLOG file generation once this command has been executed successfully. Before switching to a new file generation, openUTM continues writing messages stored in the internal message buffer to the old file generation. Please note the following points in UTM applications on BS2000 systems: Successful execution of a KDCSLOG SWITCH command by openUTM does not mean that you have immediate access to the new file generation. The old file generation can be kept open for an extended period of time by UTM processes, for example because the processing of a program unit started before the switch has not been completed and because no message with SYSLOG as its destination has yet been written by the relevant process. You can use KDCSLOG INFO as a query to find out which SYSLOG file generations have already been closed by all UTM processes, i.e. all file generations less than LOWEST-OPEN-GEN (see description of output in section "Output from KDCSLOG INFO" in chapter "Output from KDCSLOG INFO").
SWITCH,SIZE=fg_size
	Is only executed if the SYSLOG was opened as an FGG. With KDCSLOG SWITCH,SIZE=fg_size you can switch the SYSLOG to a new file generation and, at the same time, redefine the control value for automatic size monitoring of the subsequent file generations. To this end, openUTM guarantees either that both actions are performed successfully, or that neither is. In other words, openUTM only sets the new control value if the SYSLOG switch operation was successful. If openUTM is not able to switch to the next file generation, the control value does not change. Size monitoring is suspended and openUTM ignores the value specified for fg_size. Size monitoring cannot be reset until after a subsequent successful switch attempt (KDCSLOG SWITCH). If fg_size is not specified at this time, openUTM adopts the “old” value of fg_size as its control value. For further information about the function, restrictions and possible values of fg_size, see the description of the operands SWITCH and SIZE=fg_size.

Output from KDCSLOG INFO 

SYSLOG FILE NAME                filename
FILE GENERATION GROUP           fgg
LAST SWITCH                     last-switch
SIZE CONTROL                    control
CURRENT SYSLOG SIZE             csp UTM PAGE(S)   =  csk KB
SIZE CONTROL VALUE              scp UTM PAGE(S)   =  sck KB
SYSLOG FILE                     rel% FILLED
FILE GENERATIONS OF APPL        START-GEN           start-gen
                                LOWEST-OPEN-GEN     low-gen
                                CURRENT-GEN         curr-gen
FILE GENERATIONS                BASE-GEN            basis-gen
                                FIRST-GEN           first-gen
                                LAST-GEN            last-gen

Explanation of the output

SYSLOG FILE NAME

Name of the current SYSLOG file. If the SYSLOG was opened as an FGG, the generation number of the current file generation is displayed with it.

FILE GENERATION GROUP

Shows whether the SYSLOG was opened as an FGG or as a simple file.

YES
The SYSLOG was opened as an FGG.

NO
The SYSLOG was opened as a simple file.

LAST SWITCH

Only output if the SYSLOG was opened as an FGG.
LAST SWITCH indicates whether the last attempt by openUTM to switch to the next file generation executed without errors. The following values are possible:

SUCCESSFUL
The last switch attempt executed without errors.

FAILED
When openUTM last attempted to switch, an error occurred.
openUTM was unable to switch to the next file generation.

NONE
No switch attempt was made in the current application.

SIZE CONTROL

Only issued if the SYSLOG was opened as an FGG.
SIZE CONTROL indicates whether the automatic size monitoring function is switched on. The following values are possible:

ON
Size monitoring is switched on

OFF
Size monitoring is switched off

SUSPENDED
The last attempt to switch to another file generation failed (for LAST SWITCH, the word FAILED is displayed). For this reason, size monitoring is suspended.
Measure: you can try to switch SYSLOG again using KDCSLOG SWITCH. If the switch operation executes without errors, size monitoring is activated again automatically by openUTM.

CURRENT SYSLOG SIZE

Present size of the SYSLOG file/current file generation; issued in number of UTM pages (csp) and in kilobytes (csk).

All the following information is only issued if the SYSLOG was opened as an FGG.

SIZE CONTROL VALUE

Set size control value of the automatic size monitoring operation. The control value is issued in numbers of UTM pages (scp) and in kilobytes (sck). The kilobyte value is not displayed for very large control values (e.g. for 2³¹ KB).
If 0 is output as the SIZE CONTROL VALUE, size monitoring is switched off.

SYSLOG FILE .... % FILLED

Is output if the automatic size monitoring function is switched on. The value indicates the percentage of the SYSLOG file already used up relative to the defined size control value (SIZE CONTROL VALUE). If size monitoring has been suspended by openUTM, the SYSLOG file can actually be filled by more than 100%. When this occurs, the message SYSLOG FILE “>100% FILLED” is output.

START-GEN

Generation number of the first SYSLOG file generation written by openUTM in the current application run.

LOWEST-OPEN-GEN

Generation number of the oldest SYSLOG file generation still kept open by a process in the application.

CURRENT-GEN

Generation number of the file generation in which openUTM is currently keeping a log.

BASE-GEN

Generation number of the defined basis of the SYSLOG FGG.

FIRST-GEN

Generation number of the first valid file generation of the SYSLOG FGG.

On BS2000 systems, this is the same as the FIRST-GEN from the SHOW-FILE-ATTRIBUTES command.

LAST-GEN

Generation number of the last valid file generation of SYSLOG-FGG.

On BS2000 systems, this is the same as the LAST-GEN from the SHOW-FILE-ATTRIBUTES command.

Output from KDCSLOG WRITE

1. If openUTM is able to write the message buffer properly to the SYSLOG, openUTM issues the following message:

   **** SYSLOG BUFFER WRITTEN ****

2. If the message buffer for command processing is empty, the following message is issued:

   **** SYSLOG BUFFER IS EMPTY ****

3. If openUTM is not able to write the message buffer properly to the SYSLOG, the following message is issued:

   **** SYSLOG BUFFER NOT WRITTEN ****

Output from KDCSLOG SIZE=fg_size

1. When fg_size >= 0 is displayed, if the SYSLOG for the application was opened as an FGG, then the following form of text is issued:

          NEW   OLD
   SIZE   100   0    COMMAND ACCEPTED - MINIMUM SIZE TAKEN

   The additional text COMMAND ACCEPTED- MINIMUM SIZE TAKEN is only issued if a value of between 1 and 99 is entered for fg_size.

2. If the SYSLOG is not opened as an FGG, the following message is issued:

   COMMAND REJECTED - SYSLOG FILE IS NO FGG

Output from KDCSLOG SWITCH

1. If openUTM was able to switch the SYSLOG successfully, the following message is issued:

   *** SYSLOG SWITCH ACCEPTED ***

2. If the SYSLOG was not opened as an FGG, the following message is issued:

   *** SYSLOG SWITCH REJECTED - SYSLOG FILE IS NO FGG ***

3. If an error occurs during the switch operation, openUTM issues the following message:

   *** SYSLOG SWITCH REJECTED ***