Managing log files

Definition

When batch procedures or complex tasks are managed, it is important to generate log files that will be displayed after the operation is finished. In Sage X3 version 6, a set of sub-programs exists, named OUVRE_TRACE and ECR_TRACE....

In version 7, a new set of functions are implemented in the supervisor layer. They create and fill the same format of a log file, but they are more appropriate to use when working with classes and methods..

The ALOG Class

To create a log file, you must instantiate an 'ALOG' class. After this instance exists, different methods will allow you to write log files. They are all called by Fmet:

ASETNAME(FILE_NAME)

Defines the log file name. If this method is not used, the name will be "F" followed by an incremental number defined by '[C]NUMIMP' current pointer value.

Use this method after the instantiation or after using the 'ABEGINLOG' method. By default, the name is assigned if a call to the 'AGETNAME' method is performed, or if a flush of the write buffer is triggered. The flush is automatically performed when the write buffer is full, but can also be triggered by the 'AFLUSHLOG' method.

This method returns 0 if successful. If the name was already assigned, the return will be equal to '[V]CST_AERROR'.

AGETNAME()

Returns the file name used for the log files and assigns it by default ID if the assignment was not already completed.

ABEGINLOG(TITLE)

Starts the log creation process and sets up the title of the log file. 'TITLE' is a character string parameter. Returns 0.

APPENDLOG(FILENAME)

Reuses a log file which name is given to append further lines in the log. If the file sent does not exist, this method creates a new log.

APUTLINE(TEXT,STAT)

Creates lines in the log and writes them in the log file based on buffering conditions. The parameters are the following:

  • 'TEXT' is a character string array containing the lines to be written.
  • 'STAT' is an integer value that will have the following values:
    • '[V]CST_AWARNING' if the lines are warnings.
    • '[V]CST_AERROR' if the lines are errors.
    • Any other value (including 0) is considered as information. Returns 0.

AENDLOG()

Ends the log creation process, writes the log file on disk, and closes the file. Returns 0.

AFLUSHLOG()

Flushes the log file by writing the buffered log lines on disk. Make sure important lines are written if for any reason the process stops. It is not recommended to do it too frequently because it affects performance.

This method returns 0. The user parameter 'NBTRABUFF' defines the number of lines that are buffered before a periodic flush is performed.

APUTINSTERRS(CLASSINSTANCE)

'CLASSINSTANCE' is a class instance where errors are found. When errors are found during operations or methods of a class, the class business logic scripts must feed the error class associated with the class instance by using the ASETERROR method).

This method writes in the log file the detailed error messages found in the error class associated with the class instance.

APUTERRS(ERRCLASSINSTANCE)

'ERRCLASSINSTANCE' is an 'AERROR' error class instance. This method will write in the log file the content of the error class instance.

Example

# This program generates sales order
# Let's declare an instance pointer of a class called C_SALESORDER
# PARAMETERS is supposed to be an array of character strings used in the generation algorithm
# LOGFILE_NAME is returned
Subprog SALES_ORDER_GENERATION(PARAMETERS,LOGFILE_NAME)
Value Char PARAMETERS()(1..)
Variable Char LOGFILE_NAME()
Local Integer NBSUCCESS,NBFAILED
# Instantiate a class to generate the log
  Local Instance MYLOG Using C_ALOG
  MYLOG=NewInstance C_ALOG AllocGroup Null
# Open the log file
  OK=fmet MYLOG.ABEGINLOG("Sales order generation")
  LOGFILE_NAME=fmet MYLOG.AGETNAME
  OK=fmet MYLOG.APUTLINE("Parameter list",OK)
  OK=fmet MYLOG.APUTLINE("--------------",OK)
  OK=fmet MYLOG.APUTLINE(PARAMETERS,OK)
  OK=fmet MYLOG.APUTLINE("--------------",OK)
  For I=1 to NB_OF_ORDERS
    Local Instance MYOR Using C_SALESORDER
    MYOR=NewInstance C_SALESORDER AllocGroup Null
  # Let's fill the order properties
    MYOR.CUSTOMER=...
    MYOR.CREATION_DATE=date$
    MYOR.PAYMENT_CODE=...
    MYOR.AMOUNT=...
    # Let's fill the order lines
    For J=1 to NBLINES
      MYORD.LINE(J)=NewInstance C_ORDERLINE AllocGroup MYORD
      ...
    Next J
  # Let's create the order
    OK=Fmet MYOR.AINSERT
    If OK=[V]CST_AOK
        NBSUCCESS+=1
       # A log line explaining that the creation was successful
       OK=fmet MYLOG.APUTLINE("Sales order generation #"+MYOR.ORDNUM+" succeeded",OK)
    Else
       NBFAILED+=1
       # Error message
       OK=fmet MYLOG.APUTLINE("Sales order generation failed",OK)
       OK=fmet MYLOG.APUTLINE("Error detail",OK)
       OK=fmet MYLOG.APUTLINE("------------",OK)
       # Detail of the errors returned by the AINSERT method
       OK=fmet MYLOG.APUTINSTERRS(MYOR)
       OK=fmet MYLOG.APUTLINE("------------",OK)
       OK=fmet MYLOG.AFLUSHLOG
    Endif
    # Let's free the order instance
    FreeGroup MYOR
  Next I
  # Now the generation is ended
  OK=fmet MYLOG.APUTLINE(num$(NBSUCCESS)-"order(s) successfully created, "+num$(NBFAILED)-"order creation failed",OK)
  OK=fmet MYLOG.AENDLOG 
  FreeGroup MYLOG
  If func END_CONDITIONS()=[V]CST_ATRUE
    End
  Endif
  # There is an additional piece of script to execute
  # Let's finally reuse the same log file
  # Instantiate again a class to generate the log
  MYLOG=NewInstance C_ALOG AllocGroup Null
# Re-open the previous log file and append lines to it
  OK=fmet MYLOG.APPENDLOG(LOGFILE_NAME)
  Gosub CHECK_ORDERS : # This piece of code uses APUTLINE to append lines to the previous log
# Finally, close everything
  OK=fmet MYLOG.AENDLOG 
  FreeGroup MYLOG
End