ph_traceon PowerHome formula function
Description
Initiates a tracing session within PowerHome 
Syntax
ph_traceon ( )
ph_traceon ( as_filename, as_label, ai_clocktype, ai_options )
Argument Description
as_filename String (Optional). The full path and filename to save the trace results to. If set to an empty string "", PowerHome will default create the trace file in the current directory (typically c:\powerhome) with a filename of "phtrace_yyyymmddhhmmss.pbp" where yyyymmddhhmmss is the current date and time
as_label String (Optional). An optional user defined label to be stored at the top of the trace file. If set to empty string "", PowerHome will default use a label of "Start Trace yyyymmddhhmmss" where yyyymmddhhmmss is the current date and time
ai_clocktype Integer (Optional). The clock type to use during the trace. Valid values are 0 for none, 1 for clock, 2 for process, and 3 for thread. Using values of 1, 2, or 3 will cause clock and timing information to also be written to the trace file. Storing clock info can be expensive in terms of efficiency and may not always be necessary to solve certain problems 
ai_options Integer (Optional). The options to use for the tracing session. Values are added together to achieve the desired mode of operation with each value specifying a particular operation type to store in the trace file. Valid values are 1 for Object Create/Destroy, 2 for Routine, 4 for Line, 8 for User, 16 for SQL, 32 for Error, and 64 for Garbage Collection
Return value
Integer. Returns 0 if the trace session is successfully initiated. Returns 1 if the trace file cannot be created/opened. Returns 2 if the trace fails to initialize 
Usage
Use this function to initiate a tracing session for PowerHome. The tracing and profiling functionality within PowerHome consists of three functions. The ph_traceon( ) function allows you to define and start a trace session. The ph_traceoff( ) function allows you to terminate a trace session. The ph_tracemsg( ) function allows the user to insert a user defined message into the trace file. 

If the overload for this function without parameters is used. It will use the default value for as_filename and as_label. The clocktype will be 1 and the options will be 10 (Routine and User)

Tracing is not something a user would typically do on his own. The resulting trace file is not human readable and must be decoded by the developer using the PowerBuilder development environment in which PowerHome was written in. Tracing will usually be initiated at the developers request to help a user track down problems or issues they may be having

Examples
The following examples demonstrate typical syntax/usage for this function.
• ph_traceon("","",0,46) - Returns 0 if successful. This example uses the default values for the filename and label and specifies no timing values to be saved. The trace session will log all routines that are executed and all lines within a routine. It will also log User messages (ph_tracemsg) and errors that occur