Using the DCDIAG command, you dynamically control BCAM and DCAM traces.
Use of this command is reserved for system developers, systems engineers, and diagnostics engineers.
DCDIAG switches one or more traces on or off and initializes a security task which writes the information produced onto a disk.
The activation of a trace only takes place if the corresponding producing function unit is registered with the trace function.
The command is also permitted if the BCAM is not active. In this way, traces can be activated even before the communication system is started up.
If the trace entries are being saved to a file because of a MODE=SAVE, note that there can only be one such file at any time to which all trace entries are written.
BS2000 console | BS2000 SDF command | Command/SOF file | SNMP management | Parameter service |
x | x | x | x |
List of valid command sources
DCDIAG | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<trace-name>
Identifies the trace(s) which are to be switched on or off and/or saved.
<trace-name> can be a fully or partially qualified name. When a partially qualified name is specified, the DCDIAG command refers to all traces with the specified qualification. The other operands are valid for each individual trace of the group. Specification of a name is mandatory with MODE=INIT/SAVE/HOLD/STOP/FREEZE/UNFREEZE.
With MODE=OPEN/CLOSE/DUMP-FROZEN, this operand is not evaluated.
trace-name is used for the purposes of coordination between originator (system function) and console (=DCDIAG command).
When MODE=SHOW this operand is optional; it can be specified as the initial string of the name.
For this reason, the trace names must be centrally managed and made known. Up to present the following names have been defined as binding for trace control users:
Name | Meaning |
CRYPT.COM | for the CRYPTO-ADM trace and the user interface trace |
CRYPT.PORT.<port-name> | for the CRYPTO-PORT traces |
DCM.BCAM.ADM | for the ADM trace |
DCM.BCAM.BASIC | for the distribution trace of the Port or Network Layer |
DCM.BCAM.BUF | for the buffer management trace |
DCM.BCAM.CON | for the CONHAND trace |
DCM.BCAM.EXIT | for the exit trace |
DCM.BCAM.FILE | for the file trace |
DCM.BCAM.INTERFACE | for the INTERFACE trace |
DCM.BCAM.IPSEC | for the IPSEC trace of BCAM |
DCM.BCAM.LOC | for the TRAHAND trace for local connections |
DCM.BCAM.LOOPBACK | for the LOOPBACK trace |
DCM.BCAM.MAP | for the mapping trace |
DCM.BCAM.MGMT | for the management trace |
DCM.BCAM.NET | for the global BCAM network trace |
DCM.BCAM.PORT.<line-name> | for the BCAM-PORT traces |
DCM.BCAM.A-PORT.<aggregation-name> | for the BCAM-PORT link aggregation traces |
DCM.BCAM.G-PORT. <devicename> | for the BCAM-PORT VLAN device traces |
DCM.BCAM.V-PORT<line-name> | for the BCAM-PORT VLAN line traces |
DCM.BCAM.SM2 | for the BCAM-SM2 trace |
DCM.BCAM.SNMP | for the SNMP trace |
DCM.BCAM.TRANS | for the TRAHAND trace for remote connections |
DCM.BCAM.TSAP | for the TSAP management trace |
DCM.DCAM.TRC.1 | for the DCAM trace for manipulative macros |
DCM.DCAM.TRC.2 | for the DCAM OPEN/CLOSE trace |
DCM.DCAM.TRC.3 | for the DCAM message trace |
DCM.DCAM.TRC.4 | for the DCAM connection trace |
DCM.DCAM.CBT | for the DCAM trace control block |
DCM.INFO | for the INFO trace of the DCM information services |
IPSEC.COM | for the IPSEC subsystem trace |
ONETSTOR.COM | for the ONETSTOR subsystem trace |
TIAM.COM | for the TIAM subsystem trace |
VTSU.B.COM | for the VTSU-B subsystem trace |
List of the DCAM trace names
The qualifiers have the following meaning:List of the DCAM trace names
<port-name>
Name of a crypto port:
<line-name>
Name of the line (corresponds to LINE-NAME in SHOW-LINE and SHOW-LINE-ATTRIBUTES and SHOW-VLAN-LINE)
<device-name>
Name of the device (corresponds to DEVICE-NAME in SHOW-VLAN-DEVICE)
MODE=...
Function to be executed.
Each of the functions defined with MODE= consists of a number of different individual actions. There are basically ten such actions:
Number | Action | Explanation |
1 | Single initialization | The trace function notes that entries may be made in the trace with the specified name(s) for a logon period. |
2 | Permanent initialization | The trace function notes that entries may be made in the trace with the specified name(s) for the duration of the current trace session. |
3 | Switch on | If the associated originator has logged on, the trace function gives permission to write entries to his/her trace. |
4 | Save | The trace function notes that the entries of the trace with the specified name(s) are to be saved, and saves them to a file. |
| 5 | Switch off | The trace function cancels the “Switch on” and “Save” actions. |
6 | Single stop | The trace function cancels the “Single initialization” action. |
7 | Permanent stop | The trace function cancels the “Permanent initialization” action. |
8 | Open | The trace function opens a save file. |
9 | Close | The trace function closes any open save file. |
10 | List | The trace function lists all traces logged by BCAM. The current state (RUNNING/STOPPED) is also displayed. |
11 | Freeze | The trace function prevents entries from being made in the trace. |
12 | Unfreeze | The trace function reverses the freeze and permits entries to be made in the trace again. |
13 | Save frozen traces | The trace function saves all frozen traces in a file. |
Actions of the trace function
The following actions are performed by the trace function for the individual MODE specifications:
MODE=INIT
Action 2 (Permanent initialization) is canceled,
Action 4 (Save) is canceled,
Action 1 (Single initialization) is performed,
Action 3 (Switch on) is performed.
MODE=SAVE
Action 2 (Permanent initialization) is canceled,
Action 1 (Single initialization) is performed,
Action 8 (Open) is performed,
Action 4 (Save) is performed,
Action 3 (Switch on) is performed.
MODE=OPEN
Action 9 (Close) is performed,
Action 8 (Open) is performed.
MODE=CLOSE
Action 9 (Close) is performed.
MODE=HOLD
Action 1 (Single initialization) is canceled,
Action 4 (Save) is canceled,
Action 2 (Permanent initialization) is performed,
Action 3 (Switch on) is performed.
MODE=STOP
Action 5 (Switch off) is performed,
Action 4 (Save) is canceled,
Action 1 (Single initialization) is canceled.
MODE=SHOW
Action 10 (List) is performed.
MODE=FREEZE
Action 11 (Freeze) is performed.
MODE=UNFREEZE
Action 12 (Unfreeze) wird durchgeführt.
MODE=DUMP-FROZEN
Action 13 (Save-Frozen) wird durchgeführt.
BUFNUM=...
Dynamically controls the number of trace buffers to be allocated to the specified trace.
The operand can accept values 1-256. If BUFNUM is not specified or if BUFNUM=0 is specified, the current number of trace buffers is not changed.
If the volume of messages is very large BUFNUM=256 should be selected in order to avoid gaps in the trace.
If BUFNUM exceeds or falls below its limiting value, the respective limiting value is assumed.
BUFNUM=*unchanged
The number of trace buffers remains unchanged.
Default: 2
BUFNUM=<integer 1..256>
The number of trace buffers is set to the specified value.
BUFLEN=...
Dynamically changes the length of the trace buffer.
BUFLEN can accept values from 4096 to 28672 bytes. If BUFLEN is not specified or if BUFLEN=0, the current length of the trace buffer is not changed.
The trace function internally optimizes the length of the trace buffer to multiples of 4096 bytes. The buffers contain a 56-byte “buffer header”. The actual available buffer length is reduced by this value.
If BUFLEN exceeds or falls below its limiting value, the respective limiting value is assumed.
BUFLEN=*unchanged
The length of the trace buffer remains unchanged.
Default: 4096
BUFLEN=<integer 4096..28672>
The length of the trace buffer is set to the specified value.
FILE-NAME=...
Defines the name of the save file.
If the save file is not assigned a name, the backup is placed in the file S.DCTRAC.SAV.<yyyyhhmmss> (Julian date + time). In this case, the specification of the size (FILE-SIZE) or number (#FILES) has no effect.
FILE-NAME= *unchanged
The name of the save file remains unchanged.
FILE-NAME=<filename 1..49>.<integer 1..999>
The specified file name is used for the save file.
This file name is automatically extended with a suffix (integer 1 - 999). On opening a new file, the suffix n is incremented by 1 until the value defined with #FILES is reached. On reaching this value, the oldest respective file in each case is deleted thereafter.
FILE-SIZE=...
Defines the size of the save file.
This operand is only evaluated if the FILE-NAME is specified.
When the file reaches its specified size, it is closed and the next save file is opened. The trace function records the number of occupied PAM pages in the save file cyclically at the user interface.
FILE-SIZE= *unchanged
The size of the save file remains unchanged.
FILE-SIZE=<integer 512..16384>
Size of the save file in PAM pages.
#FILES=..
Defines the number of save files, provided FILE-NAME is specified.
#FILES= *unchanged
The number of save files remains unchanged.
#FILES=<integer 1..2..99>
The specified number of save files are used.
If #FILES=1 is set then the save operation is performed to the file S.DCTRAC.SAV.yyy.hhmmss (Julian date + time). In this case the specification of the size (FILE-SIZE) or name (FILE-NAME) has no effect.
If no file name is specified or if #FILES=1 is set then the save is automatically performed to S.DCTRAC.SAV.yyyhhmmss. If you only want to have one save file you should therefore set #FILES=1. This process is therefore suitable for switching a backup with a limited file size to one with an unlimited file size.
Command logging
For reasons of compatibility, the processing acknowledgment is supplied in news BCA0763 if it is positive and in news BCA0762 if it is negative, followed by the message NBR0740. In addition, for positive acknowledgments, the messages BCA0330 and BCA0632 may also appear.
A description of the error messages that can be issued during command processing is provided in the table below.
Command return codes
(SC2) | Maincode | Meaning |
| CMD0001 | Command successfully processed |
| BCA0633 | DCDIAG aborted |
| BCA0764 | Command not accepted for processing |
| BCA0768 | Syntax error in command |
| BCA0777 | Interface used at ... supplies return code ... |
Examples
In the example traces are enabled (on the console or under TSOS), specifically the Management and Adm traces in order to record a potential error situation. The traces are evaluated and written to a trace file within ASTRID. The control blocks and tables are output from BCAM to a text file.
To enable ADM and MGMT traces:
/DCDIAG DCM.BCAM.ADM
/DCDIAG DCM.BCAM.MGMT
To reproduce a potential error situation and subsequently freeze the trace:
/DCDIAG DCM.BCAM.ADM,MODE=FREEZE
/DCDIAG DCM.BCAM.MGMT,MODE=FREEZE
ASTRID enables the trace file and the control blocks to be dumped. For example, the diagnostic tool TEDDY can be used to evaluate the trace file. The trace file contains the entries for the ADM and MGMT traces. The information for the control blocks is then contained in the text file:
/ASSIGN-SYSLST ASTRID.TXT
/START-ASTRID
DCM
RS
FILE
TRC (ADM,MGMT),INFO=*SAVING-FILE
END
/ASSIGN-SYSLST *PRIMARY