24.8 Using SQLcl with APEXlang

Use the SQLcl command line tool to export, import, and validate APEXlang applications.

Exporting and Importing APEXlang Apps with SQLcl

You can also export, import, and validate your APEX apps in APEXlang using the SQLcl command line.

To export an app in APEXlang format, connect to your workspace’s parsing schema, use the apex export command, and indicate the application id and export type of apexlang. 

SQL> apex export -applicationid 104 -exptype apexlang

To import an APEXlang application with SQLcl, connect to your workspace’s parsing schema, use apex import, and indicate the input to load as a path to a directory or zip file: 

SQL> apex import -input /Users/smuench/Downloads/employees

Importing an APEXlang app always validates it first, so any errors or warnings appear as with apex validate below. If no errors are detected, SQLcl proceeds. If the import is successful, you’ll see: 

SQL> apex import -input /Users/smuench/Downloads/employees
        
Importing application ID: 104 into workspace: DIVEINTOAPEX

Import successful.

Validating an APEXlang Application with SQLcl

To validate an APEXlang application in SQLcl without importing it, connect to your workspace’s parsing schema, use apex validate, and indicate the input to verify as a path to a directory or zip file: 

SQL> apex validate -input /Users/smuench/Downloads/employees

You’ll see Validation successful, otherwise any errors or warnings appear in the SQLcl console.

For example, suppose you edit the pageItem P3_EMPNO section of the p00003‑employee.apx page to introduce three typos as shown below and save the file:

  1. @employee -> @employe (remove the trailing e)
  2. number -> numbe (remove the trailing r)
  3. primaryKey -> primaryKe (remove the trailing y) 
page 3 (
 ⋮
   pageItem P3_EMPNO (
        type: hidden
        layout {
            sequence: 10
            region: @employe      <-- 1 --
            slot: regionBody
        }
        source {
            formRegion: @employee
            column: EMPNO
            dataType: numbe       <-- 2 --
            queryOnly: true
            primaryKe: true       <-- 3 --
        }
        security {
            sessionStateProtection: checksumRequiredSessionLeve
        }
    )
 ⋮
)

The errors display immediately in the VS Code Problems panel, and apex validate shows them as follows in SQLcl: 

SQL> apex validate -input /Users/smuench/Downloads/employees
        
APEXLang Compile Errors:

File: pages/p00003-employee.apx
Line: 123
Column: 12
Type: LOV_NOT_FOUND
Error: Invalid LOV required parameter: source - dataType (string)
Valid parameters are:
-bfile
-blob
-boolean
-clob
-date
-intervalDayToSecond
-intervalYearToMonth
-number
-rowid
-sdoGeometry
-timestamp
-timestampWithLocalTimeZone
-timestampWithTimeZone
-varchar2

File: pages/p00003-employee.apx
Line: 117
Column: 12
Type: REFERENCE_NOT_FOUND
Error: Reference not found: @employe

File: pages/p00003-employee.apx
Line: 125
Column: 12
Type: INVALID_PROPERTY
Error: Invalid property: primaryKe

To collect any errors or warnings for later reference, use the SQLcl spool command to capture the console output into a file. 

SQL> spool employees_errors.log
        
SQL> apex validate -input /Users/smuench/Downloads/employees

APEXLang Compile Errors:

File: pages/p00003-employee.apx
Line: 123
Column: 12
Type: LOV_NOT_FOUND
Error: Invalid LOV required parameter: source - dataType (string)
 ⋮
SQL> spool off

Metadata-Driven Validation

The APEXlang compiler knows which APEX components are available as well as what properties and child components each one has. It validates property values, nested components, and constraints on when each applies. For example, one type of region component like an interactiveReport has nested column definitions, but a form type region doesn’t. Similarly, a chart type region has a zoomAndScroll property, but a classicReport does not.

Page Designer has always reacted dynamically to show and hide appropriate properties and child components. Now the APEXlang compiler leverages the same details to strictly validate your app components and pages.

This information about APEX's app metadata is called meta-metadata (MMD). Over time, it will grow to reflect new APEX features, so each app stores the current APEX meta-metadata version used to export it. This lets the APEXlang compiler validate app files correctly. It also ensures SQL Developer offers accurate code completion in VS Code.

Your app’s .apex/apexlang.json file records this MMD version. It’s important this version remain unchanged until a future APEX version might export your app with a new value. Do not modify it by hand. 

{
  "mmdVersion" : "26.1.0+3102"
}

Validating APEXlang Without a Connection

While importing an APEXlang application requires access to your workspace's parsing schema, you can validate an APEXlang application without a connection. For example, if you run SQLcl with the /nolog option to avoid a login, you can still run apex validate to compile your application and report errors and warning, if any. This can be useful to validate an application you have downloaded from an APEX instance without direct SQLNet connectivity, or useful for an AI coding agent to discover its own errors to fix them autonomously.

For example, if you are in the root directory of an APEXlang application you want to validate, you can do the following, using the dot (.) to represent the current directory as the input to validate. 

$ sql /nolog
SQL> apex validate -input .
APEXLang Compile Errors:
File: pages/p10020-dashboard.apx
Line: 499
Column: 4
Type: DUPLICATED_COMPONENT
Error: Duplicated component within parent scope. For properties:
identification.buttonName: VIEW_ACTIVITY_BY_USER

File: pages/p10020-dashboard.apx
Line: 526
Column: 4
Type: DUPLICATED_COMPONENT
Error: Duplicated component within parent scope. For properties:
identification.buttonName: VIEW_ACTIVITY_BY_USER

Parent topic: Working with APEXlang