KC_SYSLOG - Administer the system log file

Using KC_SYSLOG you can administer the system log file SYSLOG during operation. The extent of the functions available to you to administer SYSLOG is determined by whether SYSLOG was created as a simple file or as a file generation group (BS2000 systems) or file generation directory (Unix, Linux and Windows systems). The abbreviation FGG (File Generation Group) is used hereafter to refer to both file generation directories and file generation groups.

See also the openUTM manual “Generating Applications” and the relevant openUTM manual “Using UTM Applications” in relation to SYSLOG.

The following functions are available to you, irrespective of whether SYSLOG is maintained as a simple file or as an FGG:

• Write the content of the UTM-internal message buffer to SYSLOG.

  This function is useful if the SYSLOG file, which was created as a simple file, is to be evaluated during operation. All UTM messages with the destination SYSLOG that have been generated by UTM up to this time are then taken into account in the evaluation.

  If SYSLOG was created as an FGG, the following applies:
  When SYSLOG switches over to the next file generation, UTM automatically writes the UTM message buffer to the “old” SYSLOG file generation before switching.

• Have information about the SYSLOG file displayed.

You can also use the following functions if SYSLOG was created as an FGG:

• Activate and deactivate automatic SYSLOG size control.

  Automatic size control means that UTM automatically switches SYSLOG over to the next file generation of the SYSLOG FGG as soon as the size of the current SYSLOG file generation exceeds a certain control value.

• Modify the control value for size monitoring.

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

SYSLOG size control can even be activated if SYSLOG was not generated with KDCDEF.

Procedure when switching SYSLOG to another file generation

Before switching over to a new file generation, UTM writes the UTM messages still stored in the internal UTM message buffer to the old file generation. All UTM messages generated before switching over are thus written to the “old” SYSLOG. UTM ensures that UTM messages generated after the switch-over time (successful execution of the KC_SYSLOG call) are no longer written to the “old” SYSLOG file generation.

The following should be noted in UTM applications on BS2000 systems:

• It is possible that the old file generation may not be available immediately after switchover (i.e. successful processing of the KC_SYSLOG call). The old file generation may still be kept open for a relatively long period by UTM processes, e.g. because the processing of a program unit which was started before the switchover has not yet been concluded and no UTM message with the UTM message destination SYSLOG has yet been written from the associated process.

• Using subopcode1=KC_INFO, you can enquire which SYSLOG file generations have already been closed by all UTM processes. These are all file generations that have a generation number of less than lowest_open_gen (see kc_syslog_str on "KC_SYSLOG - Administer the system log file").

Period of validity / transaction management / cluster

The call is not subject to transaction management. It takes immediate effect, and the operations initiated by the call will already have been performed when control is returned to the program unit. The call cannot be rolled back.

Modifications to the SYSLOG file size threshold remain in effect until the end of the application run.

If the base of the SYSLOG FGG is within the valid range for the SYSLOG FGG (between the first and last file generation), UTM initially logs in the base file generation in the next application run. If the base is outside the valid range, UTM creates a new file generation for logging as of the next start. The base is specified in the data structure kc_syslog_str in the base_gen field.

The following applies in UTM cluster applications (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. The size monitoring persists 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.

KDCSLOG ("KDCSLOG - Administer the SYSLOG file")

Data to be supplied

Function of the call	Data to be entered in the
	parameter area 1	identification area	selection area	data area
Provide information about SYSLOG	subopcode1: KC_INFO data_lth: Length of the data area for the return from UTM	——	——	—— (when the call is made you must pass the pointer to a data area for the returns from UTM (kc_syslog_str).)
Set or modify the control value for automatic size control	subopcode1: KC_CHANGE_SIZE data_lth: length of the data in the data area	——	——	Data structure kc_syslog_str with the new control value
Switch SYSLOG over to the next file generation of the FGG	subopcode1: KC_SWITCH data_lth: 0	——	——	——
Modify the control value for automatic size control and switch SYSLOG over to the next file generation of the FGG	subopcode1: KC_SWITCH_AND_ CHANGE data_lth: Length of the data in the data area	——	——	Data structure kc_syslog_str with the new control value
Write UTM message buffer to SYSLOG	subopcode1: KC_WRITE_BUFFER data_lth: 0	——	——	——

¹ The operation code KC_SYSLOG must always be specified in the parameter area.

Parameter settings
Parameter area
Field name	Content
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_SYSLOG
subopcode1	KC_INFO / KC_CHANGE_SIZE / KC_SWITCH / KC_SWITCH_AND_CHANGE / KC_WRITE_BUFFER
id_lth	0
select_lth	0
data_lth	Length of the data structure / length of the data area / 0
Identification area
—
Selection area
—
Data area
Data structure kc_syslog_str / —

KDCADMI call

KDCADMI (&parameter_area, NULL, NULL, &data_area)
KDCADMI (&parameter_area, NULL, NULL, NULL)

Data returned by UTM
Parameter area
Field name	Content
retcode	Return codes
data_lth_ret	Length of the data supplied in the data area
Data area
Data structure kc_syslog_str

subopcode1
	You must specify the operation UTM is to perform in the subopcode1 field. You can specify the following subopcodes:
	KC_WRITE_BUFFER
		All UTM messages output with a SYSLOG message destination and which are still stored in the UTM-internal message buffer are immediately written to the current SYSLOG file. If the buffer is empty, the call has no effect.
	KC_INFO	Specify if UTM is to return information about the SYSLOG file or SYSLOG FGG. In this case, you must specify in the data_lth field the length of the data area which you are making available to UTM to pass the information. For the KDCADMI call you must pass the pointer to this data area.
	You may specify the following values for subopcode1 only if SYSLOG was created as an FGG.
	KC_CHANGE_SIZE
		Specify whether you want: to modify the control value for automatic size control. You must pass the threshold in the data area. to activate automatic size control. To do this, pass a control value of > ‘0' in the data area. to deactivate automatic size control. To do this, pass the control value ‘0' in the data area.
	KC_SWITCH
		Specify whether UTM is to switch the SYSLOG file over to the next file generation. If this file generation does not yet exist, UTM creates it.
	KC_SWITCH_AND_CHANGE
		Corresponds to a combination of the functions of KC_CHANGE_SIZE and KC_SWITCH. Using KC_SWITCH_AND_CHANGE you can switch SYSLOG over to the next file generation and simultaneously modify the control value for automatic size control. UTM ensures in this case that either both operations are performed successfully or neither is performed; i.e. only if SYSLOG switching was successful does UTM set the new control value. If UTM cannot switch over to the following file generation, the control value is not modified. Size control is suspended and UTM ignores the new control value. Size control can be reactivated only by a subsequent successful switch-over attempt (repeated KC_SYSLOG call). If a new control value was not specified, UTM carries over the “old” control value.
data_lth
	Specify the following in the data_lth field. for subopcode1=KC_INFO: the length of the data area to which UTM is to return the information. When calling KDCADMI, you must pass the pointer to the data area to UTM. for subopcode1= KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE: the length of the data in the data area which you are passing to UTM. Pass the data structure kc_syslog_str with the new size control value in the data area. for subopcode1= KC_SWITCH or KC_WRITE_BUFFER: data_lth =0. When calling KDCADMI you must specify the null pointer for &data_area.
Data area
	The information which you must specify in the data area is determined by subopcode1: subopcode1=KC_WRITE_BUFFER or KC_SWITCH: You must not pass any data to UTM in the data area. subopcode1=KC_INFO: You may not pass any data to UTM in the data area. You must, however, make a data area available to UTM to which it can return the requested information. subopcode1=KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE: You must pass the data structure kc_syslog_str with the new control value to UTM in the data area. Specify the control value in the size_control_utmpages field. The value is specified as the number of UTM pages. Permitted values are between 0 and 231-1 (specified as char). However, UTM automatically replaces values of between ‘1' and ‘99' with ‘100'.  By using size_control_utmpages = '0' you deactivate automatic size control. You must complete the remaining fields of kc_syslog_str with binary zeroes. kc_syslog_str is described in chapter "KC_SYSLOG - Administer the system log file".
retcode
	UTM writes the return code for the call to the retcode field. In addition to the return codes listed in section "Return codes", the following codes may also occur:

Main code = KC_MC_OK

The call was processed without errors.

Subcodes:

KC_SC_MIN_SIZE

For subopcode1 = KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE:
While the size control value was indeed modified, the value specified in size_control_utmpageswas too low (< 100). The minimum control value of 100 UTM pages was thus set.

KC_SC_BUFFER_EMPTY

For subopcode1 = KC_WRITE_BUFFER:
The UTM message buffer is empty and is thus not written to SYSLOG.

KC_SC_SWITCHED

The UTM message buffer could not be written to SYSLOG until SYSLOG had been switched to a new file generation.

Main code = KC_MC_REJECTED

The call was rejected by UTM.

Subcodes:

KC_SC_NO_FGG

The requested operation cannot be performed as SYSLOG was not created as an FGG.

KC_SC_NO_INFO

The operation cannot be performed.

KC_SC_NO_GLOB_CHANG_POSSIBLE

Only in UTM cluster applications:
No global administration changes are possible since the generation of the node applications is not consistent at present.

Main code = KC_MC_DATA_INVALID

A field in the data structure in the data area contains an invalid value.

Subcodes:

KC_SC_INVALID_MOD

For subopcode1 = KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE:
The size control value specified in size_control_utmpages is invalid (number too high or no number or not printable). The control value has thus not been modified.

KC_SC_DATA_MISSING

For subopcode1 = KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE:
No size control value was specified in size_control_utmpages. The control value has thus not been modified and (for KC_SWITCH_AND_CHANGE) SYSLOG has not been switched.

KC_SC_DATA_NOT_NULL

For subopcode1 = KC_CHANGE_SIZE or KC_SWITCH_AND_CHANGE:
A field that cannot be set in the data structure kc_syslog_str, was not supplied with binary zeros.

Maincode = KC_MC_RECBUF_FULL

Subcode:

KC_SC_NO_INFO

The buffer containing the restart information is full (see openUTM manual “Generating Applications”, KDCDEF control statement MAX, parameter RECBUF).

Maincode = KC_MC_REJECTED_CURR

The call cannot be processed at present.

Subcode:

KC_SC_INVDEF_RUNNING

Only in UTM cluster applications:
An inverse KDCDEF is currently running, i.e. the job cannot be processed at present.

data_lth_ret 

data_lth_ret contains the lengths of the data which UTM returns to the data area.

• for subopcode1=KC_INFO returns the information about SYSLOG in the data area (kc_syslog_str). data_lth_ret != 0 applies.

• If the length in data_lth_ret is less than the data area provided (data_lth), the content of the data area is only defined in the length data_lth_ret.

• for subopcode1 != KC_INFO data_lth_ret = 0 applies 

Data area 

Where subopcode1=KC_INFO, UTM returns the data structure kc_syslog_str with information about SYSLOG to the application in the data area. The data structure has the following fields:

struct kc_syslog_str

char file_name[54];

char curr_size_utmpages[10];

char curr_size_kbyte[10];

char curr_size_percent[3];

char fgg;

char last_switch_ok;

char size_control_engaged;

char size_control_suspended;

char size_control_utmpages[10];

char size_control_kbyte[10];

char start_gen[4];

char curr_gen[4];

char lowest_open_gen[4];

char base_gen[4];

char first_valid_gen[4];

char last_valid_gen[4];

The data structure fields have the following meanings:

file_name
		Name of the current SYSLOG file or file generation in which logging is currently being performed.
curr_size_utmpages
		Contains the current size of the SYSLOG file or file generation in which logging is currently being performed. The size is specified as the number of UTM pages occupied by the file or file generation.
curr_size_kbyte
		Contains the current size of the SYSLOG file or file generation in which logging is currently being performed. The size is specified in kbytes.
curr_size_percent
		If automatic size control is activated, curr_size_percent contains the percentage utilization of the SYSLOG file relative to the specified size control value. If size control has been suspended by UTM or deactivated by means of administration functions, utilization of the SYSLOG file can exceed 100%. In this case, UTM returns blanks in curr_size_percent. If size control has not been defined (either by generation or by means of administration functions), UTM fills curr_size_percent with blanks.
fgg		Indicates whether SYSLOG was created as an FGG or as a simple file.
	'Y'	SYSLOG was created as an FGG.
	'N'	SYSLOG was created as a simple file
All the following items of information are only relevant if SYSLOG was created as an FGG. If SYSLOG was created as a simple file, the following fields will not contain any relevant information.
last_switch_ok
		States whether UTM’s last attempt to switch over to the next file generation executed without errors. This relates only to switching attempts within the current application run. The following values are possible:
	'Y'	The last switch attempt executed without errors.
	'N'	An error occurred during UTM’s last switch attempt. UTM could not switch to the next file generation.
	' '	(Blank) No switch attempt has yet been made in the current application run or SYSLOG was not created as an FGG.
size_control_engaged
		States whether automatic size control is activated. The following values are possible:
	'Y'	Size control is activated
	'N'	Size control is deactivated
size_control_suspended
		States whether automatic size control has been suspended by UTM.
	'Y'	The last attempt to switch over to another file generation failed. Size control has, accordingly, been suspended. UTM no longer attempts to switch over to the next file generation even if the defined size control value is exceeded. Remedy:  You can explicitly attempt to switch the SYSLOG. If switching proceeds without error, size control is reactivated by UTM.
	'N'	Size control is not suspended.
size_control_utmpages
		Contains the control value set for automatic size control. The control value is output as the number of UTM pages. size_control_utmpages = '0' means that size control is deactivated. For subopcode1 = KC_CHANGE_SIZE and KC_SWITCH_AND_CHANGE, pass the new size control value in size_control_utmpages. Minimum value: '0' Maximum value: 231 -1 (specified as char) If you specify size_control_utmpages = '0', automatic size control is deactivated. UTM automatically replaces values between ‘1' and ‘99' with ‘100'.
size_control_kbyte
		Contains the control value set for automatic size control. The control value is output in kilobytes. For very large thresholds, the kilobyte value is not displayed (e.g. for 231 kb). size_control_kbyte = 0 means that the kilobyte value cannot be displayed because it is too high or that high size control is deactivated.
start_gen		Contains the number of the first SYSLOG file generation written by UTM in the current application run.
curr_gen		Number of the file generation in which UTM is currently logging data.
lowest_open_gen
		Contains the number of the oldest SYSLOG file generation which is still kept open by an application process.
base_gen		Generation number of the defined base for the SYSLOG FGG.
first_valid_gen
		Number of the first valid file generation of the SYSLOG FGG. On BS2000 systems, this corresponds to the specification FIRST-GEN from the SHOW-FILE-ATTRIBUTES command.
last_valid_gen
		Generation number of the last valid file generation of the SYSLOG FGG. On BS2000 systems, this corresponds to the specification LAST-GEN from the SHOW-FILE-ATTRIBUTES command.