edmiRemoteTraceServer

Operates the EDMinterface^ server trace facilities from a thin EDMclient. The EDMinterface^ server trace facilities is a powerful trace mechanism to assist EDMServer^ system administrators in a trouble shooting process, either by analyzing the trace output themselves, or by forwarding the trace to EPM support.
Several options for tracing may be specified. The resulting trace output will be in plain ASCII.
Running with the EDMinterface^ server trace active will normally reduce the performance of EDMinterface^ operations considerably. Users are therefore adviced to operate the system without tracing under normal conditions. The trace should be switched on, only in trouble shooting sessions. Currently there is no run-time option for tracing a single application server process. However, this feature is obtainable but requires a full remake the EDMserver^.
Header:
#include "sdai.h"
Prototype:
EdmiError edmiRemoteTraceServer(SdaiServerContext serverContextId,
                                 SdaiString        password,
                                 SdaiInteger       traceFunction,
                                 SdaiInteger       appServerClientId,
                                 SdaiInteger       options,
                                 SdaiInteger       maxTraceFileSize,
SdaiString traceFile,
SdaiString localFile,
SdaiString *hosts,
SdaiString *groups,
SdaiString *users,
SdaiString *cmd_code,
SdaiInteger *clientId);

Arguments:

serverContextId	Context identification, from edmiDefineServerContext
password	The password of the superuser. If the superuser is the specified calling user in the server context, then this password argument may be omitted. This command will be available for any user when the database is closed or when no thick EDMclients are connected to the _EDMserver^{_},
traceFunction	The _EDMinterface^_ server trace operation to perform. Available operations are: DEFINE_TRACE: Define _EDMinterface^_ server trace conditions. START_TRACE: Start _EDMinterface^_ server trace with the defined trace conditions STOP_TRACE: Stop _EDMinterface^_ server trace. CLOSE_TRACE: Stop _EDMinterface^_ trace and close the _EDMinterface^_ server trace file, if open. GET_SRV_TRACE_FILE: Read the server trace file(s) from the server and put them in the <localFile(s)>.
appServerClientId	The clientId of the EDMapplicationServer process to trace. At the moment there is no run-time option for tracing a single application server process. However, this feature is obtainable but requires a full remake the EDMserver^. When this parameter is set zero, the _EDMServer^_ will be traced. The clientIds of the EDMapplicationServer processes may be obtained by the _EDMSupervisor^_ commands Aux->WhoIsOn or RemoteSystems->Aux->WhoIsOn. See also Example 2 for how to obtain the clientIds of the EDMapplicationServer processes by use of the EDMInterface^ API fuctions. This parameter is only applicable in combination with the DEFINE_TRACE function.
options	See description of available options below. Options may be joined by using the bitwise OR operator
maxTraceFileSize	The maximum number of bytes in the <traceFile>. When this threshold value is exceeded, the trace file will be chopped. A zero value will disable the trace file chopping feature. Only a single trace file will be generated. When chopping a trace file, the first chop will be named <tracefile>. Any subsequent chops will be named TF_<no>_<tracefile>, where <no> is an increasing sequence number. This parameter is only applicable in combination with the DEFINE_TRACE function.
traceFile	Name of the _EDMinterface^_ server trace file. This parameter is only applicable in combination with the DEFINE_TRACE function.
localFile	The name of the file on the local file system to copy the server trace file(s) to. In case of multiple trace file chops, all files may be obtained by using the ALL_CHOPPED_FILES option. This parameter is only applicable in combination with the GET_SRV_TRACE_FILE function.
hosts	Currently not used.
groups	Currently not used.
users	Currently not used.
cmd_code	Currently not used.
clientId	Currently not used.

Option Description

SRV_TRACE_CMD	Trace the command messages sent from the client to the server.
SRV_TRACE_REPLY	Trace the reply messages sent back from the server.
SRV_TRACE_HEADER	Trace the command and reply headers
SRV_TRACE_BODY	Trace the command and reply bodies
SRV_TRACE_TO_STDOUT	Send the trace output to the terminal window in which the EDMserver^ was started.
SRV_TRACE_TO_FILE	Send the trace output to a file on the remote file system.
SRV_TRACE_ERRORS	Trace any erroneous client server communication
SRV_TRACE_VERBOSE	Trace events such as getting and releasing semaphores etc.
SRV_TRACE_TIME	Trace the time elapsed for execution of commands by the EDMserver^.
SRV_TRACE_FLUSH_ON	Flush the server trace after each printout. This ensures that all the trace information will be available even in case of unforeseen events like a server crash.
SRV_TRACE_FULL	This option is equivalent to : SRV_TRACE_CMD	SRV_TRACE_REPLY	SRV_TRACE_HEADER	SRV_TRACE_BODY	SRV_TRACE_TO_STDOUT	SRV_TRACE_ERRORS	SRV_TRACE_VERBOSE	SRV_TRACE_TIME	SRV_TRACE_FLUSH_ON
SRV_TRACE_BRIEF	Only the clientId, the sequence number and the command and reply names will be traced. Example output: #3 [53] CMD: Cmd_WhoIsOnServer #3 [53] REPLY: R_WhoIsOnServer #3 REPLY: completed.
SRV_TRACE_STDOUT_BRIEF	Same as for SRV_TRACE_BRIEF, but the trace will not be written to a trace file.
SRV_TRACE_ALL_SERVERS	Trace the main server as well as all connected EDMapplicationServer processes.
SRV_TRACE_ALL_CHOPPED_FILES	Read the specified trace file and all its chops from the server to the local file system. This option is only applicable in combination with the GET_SRV_TRACE_FILE function.

Returns:
A completion code of datatype EdmiError is the returned function value. The completion code has the following values:
Completion code = 0 : Operation successfully performed.
Completion code != 0: Error in operation. Completion code is an _EDMinterface^_ error code. Use edmiGetErrorText to get the error text corresponding to the error code.

Example:
/* Convert a model with brief
tracing to a single trace file */
EdmiError rstat;
SdaiServerContext myContext;
SdaiInteger nErr, nWrn, userStatus;
SdaiOptions options;

/* Define Remote Server Context */
rstat = edmiDefineServerContext("MyRemoteServerContext",
"Johnny", "Supervisor", "cf37ftr",
"TCP", "9090", "MyServerHost",
NULL, NULL, NULL, NULL, NULL, &myContext);

/* Define the tracing */
options = SRV_TRACE_BRIEF;
options |= SRV_TRACE_TO_FILE;
options |= SRV_TRACE_ALL_SERVERS;
rstat = edmiRemoteTraceServer(myContext, "xf667cx", DEFINE_TRACE,
0, options, 0, "myTrace.trc", NULL, NULL,
NULL, NULL, NULL, NULL);

/* Start tracing */
rstat = edmiRemoteTraceServer(myContext, "xf667cx", START_TRACE,
0, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL);

/* Convert a model */
rstat = edmiRemoteConvertModels(myContext, "DataRepository.MYMODEL_V1",
"MYSCHEMA_V1_TO_V2", "DataRepository.MYMODEL_V2",
NULL, NULL, "c:/temp/myschema_v1_to_v2.dia", 104857600,
"c:/temp/myschema_v1_to_v2.out", 0, NULL,
FULL_LOG | LOG_TO_FILE, &userStatus, &nWrn, &nErr, NULL, 2,
sdaiBOOLEAN, sdaiTRUE, sdaiINTEGER, 128);

/* Stop tracing */
rstat = edmiRemoteTraceServer(myContext, "xf667cx", STOP_TRACE,
0, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL);

/* Terminate tracing */
rstat = edmiRemoteTraceServer(myContext, "xf667cx", CLOSE_TRACE,
0, 0, 0, "myTrace.trc", NULL, NULL, NULL,
NULL, NULL, NULL);

/* Read the trace file from the
remote to the local file system */
rstat = edmiRemoteTraceServer(myContext, "xf667cx", GET_SRV_TRACE_FILE,
0, 0, 0, "myTrace.trc", "c:/tmp/myTrace.trc",
NULL, NULL, NULL, NULL, NULL);
. . .