kc_tac_str - Transaction codes of local services

The data structure kc_tac_str is defined for the object type KC_TAC. In the case of KC_GET_OBJECT, UTM returns the following information in kc_tac_str:

• properties of a transaction codes or a TAC queue

• statistical information on the load on the service

• the current state of the transaction code or TAC queue

  
  

Only the fields tc_name, admin, qlev, q_mode, q_read_acl, q_write_acl and state are of any significance to the evaluation of the information of TAC queues (tac_type='Q').

Transaction codes can be created dynamically with KC_CREATE_OBJECT, deleted with KC_DELETE_OBJECT or modified with KC_MODIFY_OBJECT

mod 1	Data structure kc_tac_str
-	char tc_name[8];
-	char program[32];
x(GPD)	char lock_code[4];
x(GID)	char state;
-	char tacclass[2];
-	char admin;
-	char call_type;
-	char exit_name[32];
-	char qlev[5];
-	char tac_type;
-	char real_time_sec[5];
-	char cpu_time_msec[8]; (only on BS2000 systems)
-	char dbkey[8]; (only on BS2000 systems)
-	char runprio[3]; (only on BS2000 systems)
-	char api;
-	char satadm; (only on BS2000 systems)
-	char satsel; (only on BS2000 systems)
-	char tacunit[4];
-	char tcbentry[8]; (only on BS2000 systems)
-	char in_queue[5];
x(GIR)	char used[10];
x(GIR)	char number_errors[5];
x(GIR)	char db_counter[10];
x(GIR)	char tac_elap_msec[10];
x(GIR)	char db_elap_msec[10];
x(GIR)	char taccpu_msec[10];
-	char deleted;
-	char pgwt;
-	char encryption_level;
x(GPD)	char access_list[8];
-	char q_mode;
x(GPD)	char q_read_acl[8];
x(GPD)	char q_write_acl[8];
-	char nbr_dputs[10];
-	char nbr_ack_jobs[10];
x(GPD)	char dead_letter_q;
x(GIR)	char nbr_ta_commits[10];
x(GIR)	char number_errors_ex[10];
-	char in_queue_ex[10];
x(GIR)	char taccpu_micro_sec[10];

¹   The contents of the field can be modified with KC_MODIFY_OBJECT; see "obj_type=KC_TAC"

The fields in the data structure have the following meanings:

tc_name
	Contains the name of the transaction code or TAC queue whose properties UTM returns. The name is up to 8 characters long.
program
	Contains the name of the program unit assigned to this transaction code. For TAC queues, blanks are returned.
lock_code
	Contains the lock code assigned to the transaction code (access protection). Only users/clients who possess the corresponding key code may call this transaction code. The key code must be contained both in the key set assigned to the user ID and in the key set assigned to the LTERM partner via which the user/client is to connect to the application. The lock_code can contain a number between '0' and '4000'.  In KC_CREATE_OBJECT, the maximum value that can be contained by lock_code is the maximum value defined using the KEYVALUE operand of the KDCDEF statement MAX.  '0' means there is no lock code (i.e. the transaction code is not protected by a lock code). If you want to change the lock code, a key set must not be entered in the access_list field. This parameter is not permitted for TAC queues. In this case, blanks are returned.
state
	Specifies whether the TAC or the TAC queue is enabled or disabled:
	'Y'	TACs: The transaction code is not disabled. It is available after the application has been started. It is available until it is explicitly disabled or deleted. TAC queues: Writing and reading is permitted.
	'N'	TACs: The transaction code is disabled. The lock state='N' means that UTM will not accept any more jobs for this TAC. If the transaction code is a KDCS program unit with call_type='B', then the transaction code is disabled if it is a service TAC (first TAC of a service). If it is a follow-up TAC in a service, however, it is not disabled. Follow-up TACs (call_type='N') cannot be disabled with state='N'. TAC queues: Reading is permitted, writing not.
	'H'	(HALT) TACs: The transaction code is completely disabled. The corresponding program unit will not be started anymore by UTM when it is called with this transaction code. For the transaction code of a KDCS program unit, this means that it is disabled if it is a service TAC and if it is a follow-up TAC in an asynchronous or dialog service. If the transaction code is a service TAC no jobs are accepted for it. If this TAC is called as a follow-up TAC, then the service is aborted (internal PEND ER with 74Z). Asynchronous jobs that have already been placed in the message queue of the TAC for temporary storage before the lock are not started. They remain in the queue until the TAC is released or is set to state='N'. TAC queues: Neither reading nor writing is possible.
	'K'	(KEEP) TACs: This value can only occur in conjunction with asynchronous transaction codes, that are at the same time service TACs (call_type='B'or 'F'). UTM accepts jobs for this transaction code. However, instead of being processed, they are simply entered in the job queue for that transaction code. They are processed when you change the status of the transaction code to 'Y' or 'N'. TAC queues: writing is permitted, but reading not.
	You can disable or release a transaction code or a TAC queue while programs are running.
tacclass
	Contains the TAC class assigned to the transaction code. tacclass contains a number between 1 and 16 or blanks. The numbers signify:
	1 - 8	dialog TAC classes
	9 - 16	asynchronous TAC classes
	If UTM returns blanks in tacclass, then the following is true: No TAC classes were created during the KDCDEF generation or the transaction code in tc_name is a dialog TAC (tac_type='D') that is not assigned to any TAC class.
admin
	When tac_type='A' or 'D', specifies the privileges a user or client requires in order to be able to call this transaction code or a service that contains this transaction code as a follow-up TAC. When tac_type='Q', admin indicates the authorization a user or client needs in order to access this TAC queue.
	'Y'	TACs: This transaction code can only be called by a user who has administration privileges. TAC queues: Only a user with administration privileges can write messages to and read messages from this queue.
	'N'	No administration privileges are required for this TAC or TAC queue.
	'R'	(READ) No administration privileges are required for this TAC or TAC queue. The program unit belonging to the transaction code can use all the functions of KDCADMI that read the application data.
	In addition, the access rights to the TAC (tac_type='A' or 'D') can be limited by means of a lock code or an access list. If it is a TAC queue (tac_type='Q'), it is possible to restrict the access rights by means of the parameters q_read_acl and/or q_write_acl.
call_type
	Specifies if a service (for example the first TAC of a service) is being started with the transaction code or if the transaction code is a follow-up TAC in a service.
	'B'	(BOTH) A service can be started with the TAC. The TAC can also be a follow-up TAC in a service, however.
	'F'	(FIRST) A service can be started with the transaction code.
	'N'	(NEXT) The transaction code can only be a follow-up TAC in a service. It can only be disabled with state='H'.
exit_name
	Contains the name of the event exit VORGANG assigned to this TAC.
qlev ( queue level)
	For asynchronous transaction codes (tac_type='A') or queues (tac_type='Q'), qlev specifies the maximum number of messages allowed in the message queue for this transaction code or in the TAC queues. If this control value is exceeded, how openUTM responds depends on the value in the q_mode field. UTM does not take into account the messages created for the queue until the end of the transaction. The number of messages specified for a message queue in qlev can therefore be exceeded if several messages are created for the same queue in a single transaction.
tac_type
	Specifies if jobs sent to this transaction code will be processed in the dialog or asynchronously or whether a TAC queue was generated.
	'D'	This transaction code is a dialog TAC, i.e. jobs sent to this transaction code will be processed in the dialog with the job-submitter.
	'A'	This transaction code is an asynchronous transaction code. When calling this transaction code, an asynchronous job is created that is temporarily stored in the message queue of the transaction code. The job is processed separately from the job-submitter.
	'Q'	A TAC queue was generated. A message can be written to such a queue with a DPUT call and read from the queue with a DGET call.
real_time_sec
	Contains the maximum amount of real time in seconds that a program unit may use if it is started via this transaction code. If the program unit runs longer, then UTM aborts the service and outputs a UTM message. real_time_sec='0' means that the real time used by the program unit will not be monitored.
cpu_time_msec (only on BS2000 systems)
	Contains the maximum CPU time in milliseconds that the program unit with this transaction code may use while processing. If the program unit runs longer, then UTM aborts the service and outputs a UTM message. The value '0' means that the time will not be monitored for the program unit started via this transaction code.
dbkey (only on BS2000 systems)
	dbkey is only relevant if the program unit belonging to the transaction code makes database calls and if the database system is linked to UTM.  dbkey contains the database key that UTM passes from the program unit to the database system in a database call. The format of the key depends on the database system used. The key is a maximum of 8 characters long.  dbkey is only supported for UDS at the present. The value dbkey='UTM' will result in the value of the start parameter DBKEY being passed to the database (see the openUTM manual “Using UTM Applications on BS2000 Systems”; start parameters).
runprio (only on BS2000 systems)
	Contains the run priority setting of the BS2000 system for the transaction code. This run priority will be assigned to the UTM process in which the corresponding program unit runs. In this manner you can utilize the scheduling mechanism of the BS2000 system for run-time control of UTM program unit runs. The run priority does not have any influence, however, on the point in time at which UTM starts a program unit. When a program unit is started, UTM attempts to set the run priority of the current process to the value in runprio. If the run priority generated is not compatible with the JOIN entries of the corresponding user ID, then the run priority of the current process is not changed. UTM outputs the corresponding K message. If the maximum number of runprio values allowed for the user ID and the job class are different, then the value most favorable for the user is allowed to be used. If there are no JOIN entries, then the run priority specified in runprio is used. After the end of a program unit run, UTM sets the run priority back to the original value unless the run priority was changed again during the program unit run with the CHANGE TASK PRIORITY command. In this case, the run priority that was set externally will be maintained after the end of the program unit run. If runprio ='0', then no specific run priority is generated for this transaction code.
api ( application programming interface)
	Specifies which programming interface is used by the program unit belonging to the transaction code.
	'K'	KDCS
	'C'	CPI-C
	'X'	XATMI
satadm (only on BS2000 systems)
	Specifies if UTM SAT administration privileges are required to call the transaction code.
	'Y'	The TAC may only be called by users, clients or partner applications that are permitted to carry out administration operations on the SAT logging within the application (UTM SAT administration privileges).
	'N'	The transaction code may also be called by users, clients and partner applications that do not have UTM SAT administration privileges.
satsel (only on BS2000 systems)
	Specifies which events SAT will log during the corresponding program unit run (TAC-specific setting). One requirement for logging is that SAT logging is enabled for the application (kc_max_par_str.sat='Y'). See also the openUTM manual “Generating Applications” and openUTM manual “Using UTM Applications on BS2000 Systems” for more information on SAT logging.
	'B'	(BOTH) Both successful and unsuccessful events are logged.
	'S'	(SUCCESS) Only successful events are logged.
	'F'	(FAIL) Only unsuccessful events are logged.
	'N'	(NONE) No TAC-specific type of SAT logging is defined.
tacunit
	Contains the number of accounting units charged for each call of the transaction code in the accounting phase of UTM Accounting.  The accounting units are added to the accounting unit counter of the user ID that called the transaction code.
tcbentry (only on BS2000 systems)
	Contains the name of the KDCDEF control statement TCBENTRY in which the TCB entries assigned to this TAC are collected.
in_queue
	Only contains data for asynchronous TACs.  Specifies how many asynchronous messages are temporarily stored in the message queue of the transaction code that must still be processed by the corresponding program unit. If this number of messages is greater than 99999, then the number is not displayed in full. You should therefore use the field in_queue_ex (see "kc_tac_str - Transaction codes of local services") since larger numbers can be entered in full here.
used
	Specifies the number of program unit runs processed in all with this transaction code since the used counter was last reset. You can reset the counter to 0 using KC_MODIFY_OBJECT. In UTM-S applications used is automatically rest to 0 only in regenerations with KDCDEF and in each update generation with KDCDEF/KDCUPD. In UTM-F applications the used counter is automatically reset to 0 when the application is started.
number_errors
	Specifies how many of the program unit runs started with this transaction code terminated with errors since the number_errors counter was last reset to 0. You can reset the counter to 0 using KC_MODIFY_OBJECT. In UTM-S applications number_errors is automatically rest to 0 only in regenerations with KDCDEF and in each update generation with KDCDEF/KDCUPD. In UTM-F applications the number_errors counter is automatically reset to 0 when the application is started. If the number of program unit runs is greater than 99999, then the number is not displayed in full. You should therefore use the field number_errors_ex (see "kc_tac_str - Transaction codes of local services") since larger numbers can be entered in full here.
db_counter
	Contains the average number of database calls from a program unit started using this transaction code since the db_counter counter was last reset to binary 0. db_counter is always 0 for database link via the XA interface. You can reset the counter to 0 using KC_MODIFY_OBJECT.
tac_elap_msec
	Contains the average runtime of the program units started using this transaction code since the tac_elap_msec counter was last reset (elapsed time); specified in milliseconds. You can reset the counter to 0 using KC_MODIFY_OBJECT.
db_elap_msec
	Contains the average time needed for processing database calls in program unit runs using this TAC; specified in milliseconds. db_elap_msec considers all database calls made since the counter was last reset. db_elap_msec is always binary 0 for database link via the XA interface. You can reset the counter to 0 using KC_MODIFY_OBJECT.
taccpu_msec
	Contains the average CPU time in milliseconds needed to process this transaction code in the program unit. The value corresponds to the CPU time needed by UTM plus the CPU time used by the database system; specified in milliseconds. taccpu_msec considers all program unit runs since the counter was last reset to 0.You can reset the counter to 0 using KC_MODIFY_OBJECT.
deleted
	Specifies whether or not the transaction code or the TAC queue was deleted from the configuration.
	'Y'	The transaction code or the TAC queue was deleted but the name is disabled. You cannot generate a new transaction code or a new TAC queue with this name.
	'N'	The transaction code or the TAC queue was not deleted.
pgwt
	Only contains a value if your application processes jobs to the TAC classes using priority control, i.e. only if the KDCDEF generation contains the TAC-PRIORITIES statement. pgwt specifies, whether blocking calls (e.g. PGWT) can be processed in a program unit run started for this transaction.
	'Y'	Blocking calls are allowed.
	'N'	Blocking calls are not allowed.
encryption_level
	Only relevant for service TACs (call_type='F'or 'B') encryption_level specifies, whether messages for this transaction code must be encrypted or not.
	'N'	(NONE) Message encryption is not required. A client can start a service using this transaction code, even if the client does not encrypt the input message. The output message to the client is only encrypted if the relevant input message from the client was encrypted also.
	'2'	(Level 2) The input message has to be encrypted using the AES algorithm in order to access this transaction code.
	'5'	(Level 5) only for Unix, Linux and Windows Systems To access this transaction code, you must encrypt the input messages with the AES-GCM algorithm. If encryption_level = '2' or '5' is specified, a client can only start a service through this transaction code if the client meets one of the following prerequisites: The client is a “trusted” client (see kc_pterm_str or kc_tpool_str field encryption_level). A “trusted” client can start a service through the transaction code, even if the input message is not encrypted. The client has encrypted the input message to the transaction code with at least the specified encryption level. If a “not trusted” client does not encrypt the first input message or does not encrypt it to the required level or if the client does not support encryption, no service is started. All output messages to a not trusted client are encrypted. If the transaction code is started using service concatenation, the first input message from the client does not need to be encrypted. If the transaction code is called without user data or if it is started through service concatenation, then the client must be able to encrypt data. openUTM encrypts all output dialog messages to the client and expects all consequent input messages from a not trusted client to be encrypted in multistep services.
access_list
	Contains the name of a key set that describes the access rights of users to this transaction code. It is not permitted to specify access_list with TAC queues. access_list and lock_code must not have the same values. A user can only access the transaction code when the key set of the user, the key set of the LTERM partner by means of which the user is signed on and the key set specified by means of access_list contain at least one key code in common. You can remove data access control by filling access_list with blanks. If neither access_list nor lock_code contains a value, any user can access the transaction code.
q_mode (queue mode)
	Defines how openUTM responds when a queue already contains the maximum number of messages and the queue level has thus been reached.
	'S'	UTM rejects any further jobs.
	'W' (only when tac_type='Q')
		UTM accepts further jobs but deletes the oldest messages in the queue.
q_read_acl (only when tac_type ='Q')
	Indicates the rights (name of a key set) required by a user in order to be able to read and delete messages from this queue. A user can only have read access to this TAC queue if the key set of the user and the key set of the logical terminal by means of which the user is signed on each contain at least one key code that is also contained in the displayed key set. If q_read_acl does not contain a value, all users can read and delete messages from this queue.
q_write_acl (only when tac_type='Q')
	Indicates the rights (name of a key set) required by a user in order to be able to write messages to this queue. A user can only have write access to this TAC queue if the key set of the user and the key set of the logical terminal by means of which the user is signed on each contain at least one key code that is also contained in the displayed key set. If q_write_acl does not contain a value, all users can write messages to this queue.
nbr_dputs
	Number of pending time-controlled jobs for this TAC whose start point has not yet been reached.
nbr_ack_jobs
	Number of pending acknowledgment jobs for this TAC that have not yet been activated.
dead_letter_q
	Specifies whether a queued message should be retained in the dead letter queue if it was not processed correctly and it has not been redelivered.
	'Y'	Errored queued messages are backed up in the dead letter queue. dead_letter_q ='Y' is not permitted for KDCDLETQ, KDCMSGTC, all interactive TACs and asynchronous TACs with CALL=NEXT.
	'N'	Errored queued messages are deleted if they are not redelivered.
nbr_ta_commits
	Number of program unit runs for this TAC which have successfully completed a transaction. You can reset the counter to 0 using KC_MODIFY_OBJECT.
number_errors_ex
	See number_errors in "kc_tac_str - Transaction codes of local services".
in_queue_ex
	See in_queue in "kc_tac_str - Transaction codes of local services".
taccpu_micro_sec
	Contains the average CPU time in microseconds taken to process this transaction code in the program unit. This corresponds to the CPU time consumed by UTM plus the CPU time required by the database system. taccpu_micro_sec takes account of all program runs since the counter was last reset.You can use KC_MODIFY_OBJECT to reset the counter to 0.