cprfstart (start PRF daemon)
- Organization of this page
Format
cprfstart [-h] [-PRFID prf-identifier]
[-PrfTraceLevel prf-trace-collection-level[,[prf-trace
collection-level]...]]
[-PrfTraceCount prf-trace-file-count]
[-PrfTraceFileSize prf-trace-file-size]
[-PrfTraceBufferSize prf-trace-buffer-size]
[-PrfRemakeBuffer]
[-PrfNoBackUp [0|1]]
Function
This command starts the PRF daemon (cprfd). You must start the PRF daemon before starting other processes.
Once the PRF daemon starts, you must change the current directory to the following:
-
In Windows:
prf-trace-output-directory%PRFSPOOL%\utt\prf\prf-identifier\
-
In UNIX:
prf-trace-output-directory$PRFSPOOL/utt/prf/prf-identifier/
Arguments
- -h
-
Displays the command's usage.
- -PRFID prf-identifier
-
Specify the PRF identifier by using a character string that is 1 to 31 characters long. You can specify alphanumeric characters and underscores (_). Do not specify a character string that begins with TSC or tsc or with CTM or ctm. If this argument is omitted, the character string PRF_ID is assumed.
- -PrfTraceLevel prf-trace-collection-level[,[prf-trace-collection-level]...]
-
When -PrfTraceLevel is omitted, the information is output in Standard-level.
Specifies PRF trace collection levels, each as a 4-byte hexadecimal number (8-digit value). You can add 0x at the beginning of the 4-byte hexadecimal number, however, 0x will be ignored. You can specify multiple trace collection level values, corresponding to the index numbers (left to right), delimited by a comma (,). If a level value specification is to be omitted, do not specify any value. To omit specification of level values for all index numbers beginning after a specific index number, omit all the subsequent comma delimiters. To set the PRF trace collection level for index No. 1 to (1) and the PRF trace collection level for index No. 2 to (2), specify the arguments as (1),(2),....
The table below shows examples of PRF trace collection level specifications.
Table 4‒10: PRF trace collection level specification examples (cprfstart command) PRF trace collection level specification example
Option specification
Specify a PRF trace collection level for index No. 1
-PrfTraceLevel 0x44445555
Specify PRF trace collection levels for index Nos. 1 and 2
-PrfTraceLevel 0x44445555,0x55554444
Specify a PRF trace collection level for index No. 2
-PrfTraceLevel,0x55554444
Assignment of PRF trace collection levels at each functionality layer is explained here.
A PRF trace collection level is specified as an eight-digit hexadecimal number for each index. Each digit is allocated two functionality layers. When a hexadecimal number is expressed as a decimal number, the functionality layer allocated to the upper 2 bits is called the upper layer, and the functionality layer allocated to the lower 2 bits is called the lower layer.
The table below shows the functionality layers that are allocated to the upper and lower layers for each digit.
Table 4‒11: Specification values for collecting detail-level trace information (cprfstart command) Index
Digits
Upper layer
Lower layer
Index 1
Digit 1
Redirector
Web container
Digit 2
EJB container
JNDI
Digit 3
JTA
JCA container
Digit 4
DB Connector
RMI
Digit 5
SOAP Communication Infrastructure
uCosminexus TP1 Connector,
TP1/Client/J
Digit 6
TP1/Message Queue - Access
Cosminexus RM
Digit 7
OTS
(None)
Digit 8
CTM
(None)
Index 2
Digit 1
HCSC server
Standard output, standard error output, and user log
Digit 2
DI
Service Coordinator Interactive Workflow
Digit 3
HCSC Server (Object Access Adapter)
HCSC Server (File Adapter)
Digit 4
HCSC Server (Message Queue Adapter)
Cosminexus JPA
Digit 5
JAX-WS engine
JPA container
Digit 6
CosminexusJMS Provider functionality
TP1 inbound adapter
Digit 7
HCSC Server (FTP Adapter)
JavaMail
Digit 8
Java VM
JSF and JSTL
Index 3
Digit 1
Batch Application Execution Base
(None)
Index 4
Digit 1
CDI
(None)
Digit 3
(None)
Websocket
Index 5
Digit 1
JSF 2.2
(None)
Digit 2
JAX-RS 2.0
JavaBatch 1.0
Digit 3
Concurrency Utilities 1.0
(None)
Index 9
Digit 1
Elastic Application Data store
(None)
To specify a PRF trace collection level, decide whether to specify Standard, Detail, or Maintenance for the PRF trace collection level of the upper and lower layers for each digit, and specify it as a hexadecimal number. The table below shows the correspondence between combinations of PRF trace collection levels for the upper and lower layers with specification values.
Note that because the Maintenance level is used for collecting maintenance information when an error occurs, it should not be specified during normal operation.
Table 4‒12: Specification values for collecting Detail- or Maintenance-level trace information (cprfstart command) Upper layer
Lower layer
Specification value
Standard
Standard
0
Standard
Detail
1
Standard
Maintenance
2
Detail
Standard
4
Detail
Detail
5
Detail
Maintenance
6
Maintenance
Standard
8
Maintenance
Detail
9
Maintenance
Maintenance
a
Specification examples are shown below.
Table 4‒13: PRF trace collection level specification examples (cprfstart command) Index
Specification example
Explanation
Index 1
00000000
Acquires Standard-level trace information from each functionality layer of index 1.
00000004
Acquires Detail-level trace information only from CTM, and acquires Standard-level trace information from other functionality layers.
55555544
Acquires Detail-level trace information from each functionality layer of index 1.
a5565544
Acquires maintenance information from the redirector, Web container, and RMI, and acquires Detail-level trace information from other functionality layers.
Index 2
00000000
Acquires Standard-level trace information from each functionality layer of index 2.
40000000
Acquires Detail-level trace information only from HCSC server.
You can specify the control-level for RMI.
Specify the following values as the specification value (fourth digit of index one) of trace collection level to specify the control-level for RMI.
Table 4‒14: Specification value of the RMI control-level Upper layer
(DB Connector)
Lower layer
(RMI)
Specification value
Standard
Control
3
Detail
Control
7
Maintenance
Control
b
- -PrfTraceCount prf-trace-file-count
-
Specifies the number of trace files, as a value in the range 3 to 256. If this specification is omitted, 4 is set.
The PRF trace files are backed up during a normal stop and during a restart following a forced stop. If the total PRF trace file size is large, it might take a considerable amount of time to start and stop the PRF daemon because of the backup processing. Consequently, when Management Server is used to monitor processes, a timeout might occur if the monitoring time is set to the default value. If a timeout occurs, increase the monitoring time.
- -PrfTraceFileSize prf-trace-file-size
-
Specifies the maximum size (in kilobytes) of each PRF trace file, as a value in the range 1024 to 1048576. To set 1 megabyte as the file size, specify 1024. The actual file size may be slightly more or less than this value. The maximum difference will be 32 KB less than the value specified in -PrfTraceBufferSize. If this option is omitted, 8192 is set.
If you specify a value that is smaller than the default value of 8192, you must also specify a value smaller than the default value in -PrfTraceBufferSize.
If 0 is specified for the -PrfNoBackUp option, PRF trace files are backed up when the PRF daemon is being stopped normally and when the PRF daemon is being restarted after its previous forced termination. If the total PRF trace file size is large, it might take a considerable amount of time to start and stop the PRF daemon because of the backup processing. Therefore, if Management Server performs process monitoring with the settings in which 0 is set for the -PrfNoBackUp option in the cprfstart command, a timeout might occur with the default monitoring time settings. If a timeout occurs, increase the monitoring time.
- -PrfTraceBufferSize prf-trace-buffer-size
-
Specifies the size (in kilobyte) of the buffer to be allocated in the shared memory, as a value in the range 512 to 102400. In this you cannot specify a value greater than the value specified in -PrfTraceFileSize with this option. If this option is omitted, 8192 is set.
If the buffer area is insufficient, the KFCT26999-W message is displayed and the PRF trace might be omitted. Therefore, extend the buffer area until the message is no longer displayed.
- -PrfNoBackUp [0|1]
-
Specifies whether to take a back up of the PRF trace file when the PRF daemon starts and stops. If 0 is specified in the value, take the back up of the PRF trace file. Because the PRF trace file is copied, it might take time to start and stop the PRF daemon. After failure occurs, if the PRF trace file cannot be extracted until the PRF trace is wrapped, specify 0 in the value. Note that when Management Server is used, the snapshot log containing PRF trace files is collected automatically after failure.
If 1 is specified, do not take a back up of the PRF trace file. If a value is not specified, the operation is same as when 1 is specified.
The following is the relation between the timings for taking backup of the PRF trace file, availability of backup, and the PRFNoBackUp option:
Table 4‒15: Relation between the timing to take a backup of the PRF trace file, availability of backup, and the PRFNoBackUp option Execution Command
End condition of PRF daemon which has started previously
Backup of PRF trace file
-PrfNoBackUp 0
-PrfNoBackUp 1 (Default)
cprfstart
Normal end
No
No
Forceful end or abnormal end
Yes
No
cprfstop
Not dependent on end condition
Yes
No
cprfstop -Force
Not dependent on end condition
No
No
- -PrfRemakeBuffer
-
Re-creates the shared memory before restarting the PRF daemon. If the shared memory cannot be re-created, an error occurs.
Return values
- 0:
-
The PRF daemon started normally.
- 1:
-
Startup of the PRF daemon failed. The PRFSPOOL environment variable has not been set up.
- Other than the above:
-
An error occurred during command processing. Take the corrective action indicated in the output message, and then re-execute the command. The error message is output to the standard error output and a log file. For acquiring data, see 2.4.3 Correspondence Between Acquisition Methods and Investigation Methods in the uCosminexus Application Server Maintenance and Migration Guide.
Notes
-
You must set the PRFSPOOL environment variable. If it is not set, the command returns an error.
-
If you have to restart the PRF daemon, specify the same values in -PrfTraceCount and -PrfTraceFileSize as were set previously. Otherwise, when the PRF daemon is restarted without these options specified, the values that were being used during the previous session will not be inherited for the PRF trace file count and the PRF trace file size, so the default values will be used.
-
If the PRF daemon terminated abnormally and is then restarted, the trace collection level that was in effect when the PRF daemon terminated is inherited. Consequently, if the abnormal termination occurred after the trace collection level had been changed, a value that is different (changed value) from the trace collection level specified during the restart (the same value as was used during the previous session) is set. An example follows:
-
PRF daemon startup: cprfstart -PrfTraceLevel 0x00000001
-
Trace collection level change (0x00000001 → 0x0000000f)
-
PRF daemon abnormal termination
-
PRF daemon restart: cprfstart -PrfTraceLevel 0x00000001
In this case, the trace collection level following the restart is 0x000000f.
-
-
When the PRF daemon is restarted, the buffer that was used during the previous session is reused and the trace collection level is inherited. If the buffer size has been changed, the previous buffer is deleted and a new one is re-created. If another process is accessing the buffer, this re-creation process fails.
-
When the PRF daemon is restarted, the shared memory contents are dumped and the buffer is initialized. Maintenance information is created in the following directory:
-
In Windows:
%PRFSPOOL%\utt\prf\prf-identifier\spool\save\
-
In UNIX:
$PRFSPOOL/utt/prf/prf-identifier/spool/save/
-
-
In Windows, another PRF daemon with a PRF identifier that is different only in case from the active or starting PRF daemon (for example, aaa vs. AAA) cannot be started.
-
If the PRF daemon terminates abnormally, re-start only the PRF daemon.
-
The trace, collected from the period of abnormal termination of the PRF daemon until the PRF daemon re-starts, is destroyed.
-
If a big value is specified in -PrfTraceCount or -PrfTraceFileSize, the re-starting of the PRF daemon after the abnormal termination might take time.