Using Code Libraries

Solutions Framework provides a set of code libraries that can be used with apps and events. Many of these code libraries are used internally but can also be used when creating configuration libraries and apps to speed development.

Using the ALLOC Code Library

The ALLOC library provides utilities for working with the Manage Allocations App.

For more information on the Manage Allocations App, see the Solutions Implementer Guide.

ALLOC global variables

The ALLOC code library creates variables that are used internally, but can also be used within an app. These variables are initialized by procedure ALLOC\Init.lvpro.

Setting an allocation area

The ALLOC code library provides a utility for setting a data area in the LVAPP_Areas table. In the Longview Allocation Management app, this is used to set the source, target, pattern, and/or source offset.

This utility will:

• Display a form to select a symbol from each dimension, as defined by the available symbols in the ALLOC_<dimension> variables.
• Write the updated symbol selections to the LVAPP_Areas table. Symbol selections will be stored in the associated AREA_<dimension> variable.

To set an allocation area:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the ALLOC initialization procedure “ALLOC\Init.lvpro”
3. Set the RELID for the data area entry you want to write to (AREA_RELID)
4. Set the TYPE for the data area entry you want to write to (AREA_Type). For an allocation area, this would be one of the following:
• ALLOCSOURCE
• ALLOCTARGET
• ALLOCPATTERN
• ALLOCSOURCEOF
5. Set the Symbols available for selection for each dimension you want to write into the data area (ALLOC_<dimension>)
6. Run procedure ALLOC\SetArea.lvpro

Example:

Note: The “ALLOC\SetArea.lvpro” uses the “AREA\Write.lvpro” and “AREA\Retrieve.lvpro” procedures from the AREA code library.
For more information on these procedures, see "Using the AREA code library".

Setting an allocation exception area

The ALLOC code library provides a utility for setting an exception data area in the LVAPP_Areas table. In the Longview Allocation Management app, this is used to set the Source Exception and/or Target Exceptions.

This utility will:

• Display a form to select a symbol from each available dimension.

  Note:

  • Only dimensions where the corresponding source or target data areas contain symbols that are parents will be available for selection in an exception form.
  • If no source or target data areas are set, exceptions cannot be set.
  • If the source or target data areas only contain leaf level symbols, exceptions cannot be set.
  • If the source or target data areas are updated, this may update the source and target exceptions. For example, in the case where a source exception is no longer part of the source data area.
• Write the updated exception symbol selections to the LVAPP_Areas table. Symbol selections will be stored in the associated AREA_<dimension> variable.

To set an allocation exception area:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the ALLOC initialization procedure “ALLOC\Init.lvpro”
3. Set the RELID for the data area entry you want to write to (AREA_RELID)
4. Set the TYPE for the data area entry you want to write to (AREA_Type). For an allocation exception area, this would be one of the following:
   • ALLOCSOURCEEX
   • ALLOCTARGETEX
5. Run procedure ALLOC\SetExceptionArea.lvpro

Example:

Note: The “ALLOC\SetExceptionArea.lvpro” uses the “AREA\Write.lvpro” and “AREA\Retrieve.lvpro” procedures from the AREA code library.
For more information on these procedures, see “Using the AREA code library”

Using the AREA Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The AREA library provides utilities for retrieving, writing, deleting and duplicating entries in the LVAPP_AREAS table.

LVAPP_AREAS Overview

The LVAPP_AREAS app table is used for storing data area definitions. This app table is used in the Longview Allocations App. When creating this datatable, it must be named dtAreas in order to function with the AREA code library

Example:

Create DATATABLE dtAreas USING "Areas.lvdtd"

The LVAPP_AREAS app table consists of the following columns:

AREA global variables

The AREA code library creates a number of variables that are used internally, but can also be used within an app. These variables are initialized by procedure AREA_Init.lvpro, which is invoked by all procedures in the AREA library

Writing to LVAPP_AREAS

The AREA code library provides a utility for writing a data area of a specified type to the LVAPP_AREAS table.

To write to the LVAPP_AREAS table:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the AREA initialization procedure “AREA\Init.lvpro”
3. Set the RELID for the data area entry you want to write to (AREA_RELID)
4. Set the TYPE for the data area entry you want to write to (AREA_Type)
5. Set the Symbols for each dimension you want to write into the data area (AREA_<dimension>)

   Note: AREA_<dimension> is a RANGE variable that can accept a list of symbols for a dimension.

6. Run procedure AREA\Write.lvpro

Example:

Retrieving from LVAPP_AREAS

The AREA code library provides a utility for retrieving a data area of a specified type from the LVAPP_AREAS table into variables.

To retrieve from the LVAPP_AREAS table:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the AREA initialization procedure “AREA\Init.lvpro”
3. Set the RELID for the data area entry you want to retrieve (AREA_RELID)
4. Set the TYPE for the data area entry you want to retrieve (AREA_Type)
5. Run procedure AREA\Retrieve.lvpro

Example:

The variables AREA_<dimension> will be created and populated with symbols for each dimension in the specified data area.

Deleting an area from LVAPP_AREAS

The AREA code library provides a utility for deleting a data area of a specified type from the LVAPP_AREAS table.

To delete an area of a specified type from the LVAPP_AREAS table:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the AREA initialization procedure “AREA\Init.lvpro”
3. Set the RELID for the data area entry you want to delete (AREA_RELID)
4. Set the TYPE for the data area entry you want to delete (AREA_Type)
5. Run procedure AREA\DeleteArea.lvpro

Example:

Deleting a set of areas from LVAPP_AREAS

The AREA code library provides a utility for deleting a complete data area set of the same RELID from the LVAPP_AREAS table.

To delete a complete data area from the LVAPP_AREAS table:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the AREA initialization procedure “AREA\Init.lvpro”
3. Set the RELID for the data area entry you want to delete (AREA_RELID)
4. Run procedure AREA\DeleteRow.lvpro

Example:

Duplicating a set of areas in LVAPP_AREAS

The AREA code library provides a utility for duplicating a complete data area set of the same RELID within the LVAPP_AREAS table.

To duplicate a complete data area within the LVAPP_AREAS table:

1. Create and download the LVAPP_Areas table

   Note: The datatable must be named dtAreas.

2. Run the AREA initialization procedure “AREA\Init.lvpro”
3. Set the RELID for the data area entry you want to duplicate (AREA_RELID)
4. Set the Target ID of the new data area entry being created (AREA_TargetID)
5. Run procedure AREA\Duplicate.lvpro

Example:

Using the CJE Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The CJE library provides utilities for working with calculated journal entry events.

CJE global variables

The CJE code library creates a number of variables that are used internally but can also be used within a calculated journal entry event. These variables will only be referenced in a calculated journal entry event. These variables are initialized by procedure CJE\Init.lvpro, which is invoked by all calculated journal entry events. Additional information on these variables are provided beneath the table below.

CJE_Type

Used to store the type of the calculated journal entry. This variable is normally set in the Main Procedure of the calculated journal entry event. For more information, see Specifying the main procedure

Values for CJE_Type can be one of the following:

• CURRENTPERIOD: To create a calculated journal entry that adjusts balances in the current period.
• PPA: To create a calculated journal entry that adjusts balances in a prior period.
• RESTATEMENT: To create a calculated journal entry that restates balances in the current period or a prior period. Restatement journal entries are used for changes in accounting rules.
• FUTUREPERIOD: To create a calculated journal entry that adjusts balances in a future period.

Note: Only CURRENTPERIOD and PPA CJE Types are configured to be handled by the calculated journal entry event. The use of RESTATEMENT or FUTUREPERIOD CJE Types would require additional configuration to the calculated journal event.

CJE_ApplicationId

The application ID is the combination of:

• the application ID prefix specified in the calculated journal entry event settings.
  For more information, see Specifying calculated journal entry settings
• the entity name (see “CJE_EntityCode”)
• two digits for the creation year indicator
• two digits for the creation month indicator.

Note: The complete application ID name can have a maximum of 31 characters. If the entity name is too long and would cause the application ID to be over 31 characters, the entity name will be truncated in the application ID.

CJE_EntityCode

Used to store the entity name to be included in the calculated journal entry application ID. This variable is only used if Create a calculated journal entry by entity is checked in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings.

This variable is normally set in the Main Procedure of the calculated journal entry event.

For more information, see Specifying the main procedure

Note: The complete application ID name can have a maximum of 31 characters. If the entity name is too long and would cause the application ID to be over 31 characters, the entity name will be truncated in the application ID.

CJE_SubCategory

Used to store the subcategory to assign the calculated journal entry to. This is specified in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings

If you do not specify a value for this parameter, the calculated journal entry subcategory is set to Adjustment.

For more information on subcategories, see the Longview Application Administrator Guide.

CJE_JEDesc

Used to store the calculated journal entry description. This is specified in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings.

CJE_JENotes

Used to store any detailed notes for the Calculated Journal Entry. This is an optional parameter. The notes field can have a maximum of 1280 characters, including spaces. This is specified in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings.

CJE_IsFinancial

Used to Specify if the journal entry is financial. This is specified in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings.

CJE_IsShared

Used to Specify if the journal entry is shared. This is specified in the calculated journal entry event settings.

For more information, see Specifying calculated journal entry settings.

CJE_IsPostRequired

Used to determine the conditions under which a calculated journal entry should be posted (ie: When the debit/credit value is not zero). Variable CJE_IsPostRequired should be set to 1 when posting is required and set to 0 when posting is not required. This is normally done within the SetValues procedure.

For more information, see Specifying the set values procedure.

CJE_Status

Used to store the current status of the journal entry. Valid return values are:

• 0 - Does not exist
• 1 - No Status
• 2 – Posted
• 3 – Validated
• 4 – Errors
• 5 - Review

Using the CORE Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The CORE library provides general utilities for use with apps or events.

CORE global variables

The CORE code library creates and sets a number of variables that are used internally, but can also be used within an app. In most cases these variables will only be directly referenced in a free form app or configuration library. These variables are initialized by procedure CORE\Init.lvpro, which is invoked by all Apps and Events.

Using the get dimension index utility

The get dimension index utility allows you to determine the index of a specific dimension in the database. The index number is stored in the CORE_DimensionIndex variable and is 0-based to align with naming conventions of attributes in the database.

To use the get dimension index utility:

1. Write the following code in a procedure document:

Set VARIABLE CORE_Dimension = "<dimensionName>"

Run PROCEDURE CORE\GetDimensionIndex.lvpro

2. The index will be returned in the CORE_DimensionIndex variable
3. If the dimension name is invalid the CORE_DimensionIndex variable will be set to the value -1

Using the get resource string utility

The CORE code library contains a utility to retrieve a resource string from a resource file (.lvres). This utility is useful for retrieving a message in the user’s language and you are unable to simply use the resource token [[RESOURCE,Source,Name]].

To use the get resource string utility:

1. Set the properties of the CORE_Resource object:

   Set PROPERTY CORE_Resource.Name = "Message1"

   Set PROPERTY CORE_Resource.Source = "Messages"

   Set PROPERTY CORE_Resource.Args = "Argument1|Argument2"

   Run PROCEDURE "CORE\GetResourceString.lvpro"

   Note: CORE_Resource.Args is optional and is used to pass values into the message.

2. The message will be retrieved from the resource file and stored in the CORE_Rresource.Message property.

Note: Use of resource args:Resource args are used to replace tokens in the message with actual values. Tokens are specified in the resource using {n} where n is the index of the argument.

Using the example above:

The resource file (Messages.lvres) would contain:

Using the on close utility

The CORE code library contains an on close utility that is useful in cases where no user input is expected, i.e. for a read-only data table or data area view. The on close utility allows the user to close an App using the familiar X in the top right corner of a window or the X in a tab.

Note: For cases where user input is expected the utility CORE\OnClose.lvpro should not be used.

To use the on close utility:

1. Before the Show command write the following code:

   OnClose "CORE\OnClose.lvpro"

Using the pattern retrieval utility

If patterns ate being used your app, either standalone or in conjunction with the pattern spread tool, you can use the pattern retrieval utility to assist you. The procedure CORE\CreatePatternsLVDSP.lvpro is used to create a data spec named Patterns that can be used to create a data area specification to retrieve patterns. The main requirement for using this utility is to create a RANGE variable named patternTimePeriodList that will hold the time periods to retrieve patterns for.

In additional the utility procedure VIEW\SetPatternPeriods.lvpro can be used to populate this variable for an existing data area.

The full set of template code for pattern retrieval can be inserted using template Patterns_Retrieve to insert the required procedure code.

To insert the template pattern retrieval code:

1. Click in the code editor of a procedure document.
2. Type TEMPLATE_P.
3. Select TEMPLATE_Patterns_Retrieve from the list and press Enter.
4. The following code is inserted:

   TEMPLATE_Patterns_Retrieve

   //Download Patterns

   If SymbolExists(DATABASE, [[SYSTEM,SGPAccountsDimension,DBDEFAULT]],

   "[[SYSTEM,SGPAccountsDimension,DBDEFAULT]]" + "_Patterns")

     //Create dataspec for pattern periods

     Create VARIABLE patternPeriodList AS RANGE

    

     //Determine pattern periods from data area

     Set VARIABLE CORE_DataAreaName = "daMain"

     Run PROCEDURE "VIEW\SetPatternPeriods.lvpro"

    

     //Create and download data area

     Run PROCEDURE "CORE\CreatePatternsLVDSP.lvpro"

     Create DATAAREA daPattern USING "Patterns"

     Download daPattern

     Unload "Patterns"

   END If

Using the rollup model

Depending on the nature of an App or Event it may be required at some point to perform a full rollup of a data area. The CORE code library contains a generic model to perform this operation: Rollup.lvmod.

To execute rollup on a data area:

1. Write the following code

   Run MODEL "CORE\Rollup.lvmod" ON <DataAreaName>

Using the view file utility

During the execution of an App you may have the requirement to display a file to the user. The view file utility opens the specific file is the default program configured in Windows.

For example a “.txt” file may open in Notepad, while a “.csv” file might open in Excel.

To open a specified file:

1. Write the following code:

   Set VARIABLE CORE_FileName = "<FileName>"

   Run PROCEDURE "CORE\ViewFile.lvpro"

2. The specified file is opened in the user’s default program for the file type

Using the DATA Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The DATA library provides data related utilities for working with app or event.

Converting a data spec document to a data report input file

There may be times when a data report is a convenient and efficient way to extract data from the database. Configuring a data report input file can be complicated. The DATA code library contains a utility to convert a data spec document to a data report input file.

To convert a data spec document to a data report input file:

1. Create a data report header file, specifying the data to output

   PARENT #data to output: LEAF, PARENT, LEAF_AND_PARENT, VALIDATION, CTA

   BOTH #data types to output: UNADJUSTING, BOTH

2. Create a data report footer file, specifying the output settings:

   Y #Expand time periods as columns in output: Y, N

   4 #Number of decimals in output

   , #field separator in output

   "[[VARIABLE,outputFileName]]" #output file

   Note: For further information on data report input files, see “Creating the ASCII input file for basic database reports” In the Longview Developer’s Guide.

3. Create a data spec

4. Write the following code in a procedure document:

   //Parse data spec into a datareport

   Set VARIABLE CORE_FileName = "DATA.lvdsp"

   Run PROCEDURE "DATA\DspToDR\ParseDsp.lvpro"

   Note: This will generate a document named DataReportBody containing the dimension information in the specified data spec document

5. Write the following code in a procedure to complete and execute the data report:

   Create VARIABLE dataReportFileName AS STRING

   Create VARIABLE outputFileName AS STRING

    

   //Generate and execite data report

   Set VARIABLE dataReportFileName = "$CORE_LogPath$\DataReport.txt"

   Set VARIABLE outputFileName = "$CORE_LogPath$\Output.txt"

    

   Create DOCUMENT "$dataReportFileName$"

   Write "$dataReportFileName$" FILE "DataReportH"

   Write "$dataReportFileName$" FILE "DataReportBody" APPEND

   Resolve "DataReportF" "$dataReportFileName$" APPEND

   Save "$dataReportFileName$"

    

   Unload "$dataReportFileName$"

   Unload "DataReportBody"

   DataReport "$dataReportFileName$" "$outputFileName$"

Using the create trial balance utility to fill in custom dimensions

The DATA code library contains a utility to fill in the custom dimensions for a trial balance query dynamically based on system settings.

To create a document containing the custom dimensions:

1. Write the following code in a procedure document:

   Run PROCEDURE "DATA\CreateTBLVDSP.lvpro"

   Note: The procedure will create documents in memory containing specifications for the custom dimensions, as follows

   Document	Attribute	Hierarchical Specification
   TBSrc	ASCFD<?>Source	#0
   TBTrg	ASCFD<?>Target	#99
   TBSrcDetail	ASCFD<?>Source	#99
   TBSrcLeaf	ASCFD<?>Source	###

2. Use the Write command to create a data spec document for all dimensions by appending one of the above documents to a data spec containing the standard dimensions.

Using the EXP Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The EXP library provides utilities for working with export specs in an app or event.

EXP global variables

The EXP code library creates and sets a number of variables that are used internally, but can also be used within an app. In most cases these variables will only be directly referenced in a free form app or configuration library. These variables are initialized by procedure EXP\Init.lvpro, which would need to be called within an app in order to use the variables.

Using the export handling procedure

The export handling procedure provides standard error handling and validation for export processes. The export handling procedure performs the following steps:

1. Initializes Exp.IsValid to 1
2. Executes procedure Export.lvpro (app or event specific procedure)
3. Performs error handling as follows:
   1. If non-export related error (like a syntax error, or missing file), reports error. EXP.IsValid = 0
   2. If export related error, where MaxErrors setting is exceeded: reports error, and allows user to access import log and error file. EXP.IsValid = 0.
      1. The log file will be parsed into an object property name EXP.Status, and a summary message provided in string variable EXP_SummaryMessage.
   3. If no error, but export errors less than or equal to MaxErrors setting, provides a message, allowing the user to review errors. EXP.IsValid = 0.
      1. The log file will be parsed into an object property named EXP.Status, and a summary message provided in string variable EXP_SummaryMessage.

To use the export handling procedure:

1. Set property EXP.FileName to the name of the file to be created.
2. Set property EXP.ErrorFileName to the export error file.
3. Set property EXP.LogFileName to the export log file.
4. Create a procedure named Export in the app or event. This procedure will execute the Run Export command.
5. Type the following code (in the calling procedure):

   The EXP.Status object is described below:

   Variable[.Property] Name	Type	Initial Value
   EXP.Status.Elapsed	STRING
   EXP.Status.Filtered	NUM	0
   EXP.Status.MaxError	NUM	0
   EXP.Status.Read	NUM	0
   EXP.Status.Rejected	NUM	0
   EXP.Status.Result	NUM	0

Using the FORM Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The FORM library provides utilities for working with forms in an app.

Generating a symbol selection form

You can use the FORM code library to generate a form to select symbols from one or more dimensions. The symbol selector requires that you setup variables to define what dimensions selections will be made from and any options related to the dimensions. This process will also create the target variables for the symbol selectors, if they do not exist. The variable name will be the name of the dimension the symbol selector is used for.

To generate a symbol selector:

1. Create a string list variable named selectDimensionList
2. Set selectDimensionList to the names of the dimensions to select
3. For each dimension, set options.
4. Execute procedure FORM\SelectSymbols
5. Check the user response

   Note: If no symbol selection is required, the variable FORM_ButtonClicked will be set to OK. No symbol selection is required in a case where: all the required target variables exist, and the variables all have a value. This allows for seamless integration with symbol selection defined in Longview Client.

Example: 

To set options for a dimension:

1. Restrict symbols: Create and set a RANGE variable named <Dimension>Symbols;
2. Default selection: Create and set a STRING or RANGE variable named <Dimension>Default; ability to select multiple leaf

   Note: Use a RANGE variable if the options will allow multiple selections and you want to set a default with multiple symbols selected.

3. Selection options: Create and set a STRING variable named <Dimension>Options. Define the options using 1 or 0 as follows:
   1. 1 to indicate a selection is required
   2. 1 to indicate the user may select a leaf symbol
   3. 1 to indicate the user may select a parent symbol
   4. 1 to indicate the user may select a read-only symbol
   5. 1 to indicate the user may select multiple symbols

   Note: The default option if not specified is "11000" (select is required and user may select a leaf symbol).

4. Attribute filter: Create and set a STRING variable named <Dimension>Filter.

Example, with options

This example creates a symbol selection form for: time periods, with the ability to select a single leaf time period and entities with the ability to select multiple leaf entities with USD as the functional currency.

Example with options:

Generating symbol selection controls

You can use the FORM code library to generate controls to select symbols from one or more dimensions that can be appended to an existing form. This allows you to use the code library to create the symbol selectors for use in a custom form.

Using the generator also creates the target variables for the symbol selectors, if required.

To generate symbol selection controls:

1. Follow all the steps outlined to generate a symbol selection form up to the execute step.
2. Execute procedure FORM\GenerateSymbolSelectors.
3. Add the form generated to an existing form
4. Show the form and check the user’s selection.

Example

This example shows appending symbol selection to an existing form named Main.

Example:

Using the ICON Code Library

The solutions framework provides a library of icons that can be used in apps.

Note:

• Some icons have been deprecated. These icons have been replaced with an equivalent icon from the new set of icons for backwards compatibility, but should not be used going forward.

• The icons used come from Remix Icon - Open source icon library.
  If you need additional icons you can download them from the link above. Icons used in toolbars should have the following properties:

  • Size: 24px

  • Color: #546176

Using the IMP Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The IMP library provides utilities for working with import or export specs in an app or event.

IMP global variables

The IMP code library creates and sets a number of variables that are used internally, but can also be used within an app. In most cases these variables will only be directly referenced in a free form app or configuration library. These variables are initialized by procedure IMP\Init.lvpro, which would need to be called within an app in order to use the variables.

Using the create import spec utility

The create import spec utility is used to create an import spec that will import a file where each record in the file contains an exact match for symbol sin each dimension. The utility supports both records with single value field or multiple value fields. The import spec document created will be named ImportSpec.

To create an import spec for records with a single value field:

To create an import spec for records with multiple values fields (sample assumes time periods):

To create an import spec for records with a single value, but targeting a different symbol for one dimension (sample assumes time periods):

Using the import handling procedure

The import handling procedure provides standard error handling and validation for import processes. The import handling procedure performs the following steps:

1. Initializes IMP_IsValid to 1
2. Executes procedure Import.lvpro (app or event specific procedure)
3. Performs error handling as follows:
   • If non-import related error (like a syntax error, or missing file), reports error. IMP_ISValid = 0
   • If import related error, where MaxErrors setting is exceeded: reports error, and allows user to access import log and error file. IMP_IsValid = 0
   • If no error, but import errors less than or equal to MaxErrors setting, provides a message, allowing the user to review errors and choose to proceed with upload. IMP_IsValid = 0 (user clicks No), IMP_IsValid = 1 (user clicks Yes).

To use the import handling procedure:

1. Create a procedure named Import in the app or event. This procedure will execute the Run Import command.

2. Type the following code (in the calling procedure):

   Run PROCEDURE IMP\Init.lvpro

   Run PROCEDURE IMP\OnImport.lvpro

   If $IMP_IsValid$

   ...

   END If

Using the LOG Code Library

The solutions framework provides tools for logging messages to a file to track execution at a summary level and to provide additional tracking during debugging. Usually this is used in conjunction with events to create the event log file but can also be used in apps.

Using logging tools

Logging tools provide several different ways to write information to the log file. The log file is stored in memory until logging is complete or an error occurs.

The log file is stored in the following location:

• For apps with Re-use file for log and history unchecked:

  Documents\Longview\<Longview Identifier>\logs\<AppName>\<Date: yyyyMMdd>_<Time: hhmmss>\

• For apps with Re-use file for log and history checked:

  Documents\Longview\<Longview Identifier>\logs\<App Name>\

Starting the log file

Before logging can occur, the log file must be started. The following will be written to the log file when it is started:

1. The date and time the log was started
2. The framework version
3. For apps the following additional information is written:
   • The app version
   • The template type
   • The template version

To start the log file use the following command:

Run PROCEDURE "LOG\Start.lvpro"

Note: When debug mode is enabled the log is started as some debug items also write information to the log file.

Ending the log file

The log file is completely in memory until it is ended. The date and time the log ended will be written to the log file.

Note: In the case of an error the log file is saved to disk. If the error terminates the process the log file will not contain the end date and time.

To end the log file use the following command:

Run PROCEDURE "LOG\End.lvpro"

Note: When debug mode is enabled the log is ended at the end of the process

Logging messages

You can write messages to the log file.

To write a single message to the log file, use the following commands:

To write multiple messages to the log file, use the following commands:

Inserting blank lines into the log

For readability it is often desirable to leave blank lines in the log file.

To insert a blank line in the log file, use the following command:

Run PROCEDURE "LOG\BlankLine.lvpro"

Logging variable values

You can write the value of a variable or property to the log file. This can be useful for debugging purposes and also to track what is being executed in events.

To log the value of one or more variables, use the following commands:

Appending a file to the log

You can append the contents of an existing file to the log. This can be useful when there is a complex set of information to be logged that is easier to create as a document that to use the primitive log utilities. Use the Save command to save dynamic document to disk prior to using the append file utility.

Note: The file to append must exist on the local disk.

To append the contents of a file to the log:

1. Write the following code in a procedure document:

   Set VARIABLE CORE_FileName = "$CORE_LogPath$\FileToAppend.txt"

   Run PROCEDURE "LOG\AppendFile.lvpro"

Using the SYM Code Library

The solutions framework provides a number of code libraries that can be used when developing apps and events. The SYM library provides utilities for working with symbols in application framework.

Resolving a lock specification

The SYM code library provides a utility for resolving a lock specification for a dimension. This utility is useful for automating the task of locking a subset of a query. For example, in an input app that allows the user to use input tools, restricting the lock to cover only symbols that can be modified is essential.

To resolve a lock specification:

1. Set the dimension to resolve the lock specification for (CORE_Dimension)
2. Set the query spec for the dimension ($CORE_Dimension$Query)
3. Set the excluded symbols ($CORE_Dimension$Exclude)
4. Run procedure SYM\ResolveLockSpec.lvpro
5. Use the variable $CORE_Dimension$LockSpec for the symbol in the lock spec for the specified dimension

Example:

The variable ACCOUNTSLockSpec will be created and populated with symbol specifications for locking the query area with the specified exclusions.

Working with multiple lock specifications in a single dimension

In some cases you may be working with multiple lock specs and require different subsets of symbols for each lock spec for the same dimension. In this case you will need to create your own variable to hold the specification for each lock spec. Use the ListAppend function to populate the specific variable after executing SYM\ResolveLockSpec.lvpro.

Example:

Note: Using ListAppend with the CORE_EmptyList effectively copies the list into another variable.