Run the Gateway from the Command Line

Command Line parameters override the values set in the project configuration but don't change the project setting values.

At the command line, type the following:

"C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway For SmartPlant 3D\AVEVA.NET.Gateways.SG3D.exe" <-cp> <-lp> <-op> <-extcp> <-trnsfcp> <-ldrcp ><-EXTPT> <-EXTNM> <-EXTMD> <-EXTRT> <-EXTFL> <-to> <-MA> <-CONTEXT>

where the parameters are listed as follows:

Notes:

• Logging Functionality: When you run the Gateway from command prompt, all processing messages are directed to the log file. This allows you to use the command line in batch mode, without waiting for the Gateway to complete the execution.

  Prior to project execution (such as command line parameters validation logs or project configuration file load logs) Gateway messages are logged in the default log location:

  C:\Users\<username>\AppData\Roaming\AVEVA\AVEVA NET Gateway for SmartPlant 3D\Logs\3DDataGateway_Log_<GUID>.txt

  During project execution, Gateway messages are then logged in the project log file as defined either in the command prompt (see below) or in the configuration file.

• Any optional parameter used at the command line takes priority over the equivalent configuration in the project file. This is done without overwriting the value in project configuration file. Using these command line parameters means you can re-use the same configuration to extract data from the same model using different filters or UIDs without having to create separate Gateway project configurations.

• The Gateway validates the command line syntax and the contents of configuration files. If any errors are detected, processing will be terminated and the relevant message will be displayed on the console.

Examples:
The following examples assume that the Gateway is installed in the default directory "C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D" and the Gateway project location is "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1.xml."

• Running project as it is.

  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  @echo on
  call "%GATEWAY%\%APP%" -CP "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1.xml"
  @echo off
  echo Completed
  @echo on
  

  The example above shows how to run the Gateway project from the command line. The project will be executed as it is defined in the configuration files via the UI.

  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  @echo on

  C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1.xml

  call "%GATEWAY%\%APP%" -CP "A1.xml"
  @echo off
  echo Completed
  @echo on
  

  This example differs from the previous one in how the path of the project is passed to the Gateway. In this example, it uses a relative path to the current directory.

• Changing the output path at runtime.

  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  @echo on
  cd "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1.xml
  call "%GATEWAY%\%APP%" -CP "A1.xml" -OP "NewOutputFolder"
  @echo off
  echo Completed
  @echo on

  Parameter -OP is used to override output path defined in the Gateway project "A1". Note that the new path is provided relative to the current directory, so the final output folder:

  "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1\NewOutputFolder"

• Changing the log path at runtime.

  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  @echo on
  cd "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -LP "Logs_new\001"
  @echo off
  echo Completed
  @echo on
  

  This example differs to the previous one by using the -LP parameter to change the location of the log files. The backslash symbol used in the path tells the Gateway to create a folder if it doesn’t exist. The new folder location will be:

  "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1\Logs_new\001"

• Working with extraction mode.

  
  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  cd "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1"
  echo Initialize... %TIME%
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTMD "NEW" -EXTPT -OP "C-NW"
  echo Finished "New" at %TIME%, return code %errorlevel%
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTMD "UPDATE" -EXTPT -OP "C-UP"
  echo Finished "Update" at %TIME%, return code %errorlevel%
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTMD "EXISTING" -EXTPT -OP "C-EX"
  echo Finished "Existing" at %TIME%, return code %errorlevel%
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTMD "blablabla" -OP "C-EX"
  echo Finished "blablabla" at %TIME%, return code %errorlevel%
  echo Completed
  @echo on
  

  The above example shows how to control the extraction mode. The same project is run four times with different extraction modes. Different processing times are required for each mode:

  • NEW: The Gateway generates an intermediate file and produces the output files.

  • UPDATE: to the Gateway updates an existing intermediate file with only the items that have changed since the last time it was created or updated, and then generates the output files.

  • EXISTING: The Gateway only produces output files from the contents of the existing intermediate file.

  • Error: the last call uses an invalid option and the Gateway will log an error and return an execution code other than 0 (0 means success that is described in the following Exit Codes section).

• Changing the extraction name (which changes the name of the output files) and the location of intermediate files.

  
  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  @echo on
  cd "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTPT "MYPATH" -EXTNM "MYNAME"
  @echo off
  echo Completed
  @echo on
  

  The above example shows how to change the location of the intermediate files (-EXTPT extraction path) and how to change the name of the output files by changing the extraction name (-EXTNM). Path values can be provided either in absolute or relative form. This example uses relative form so the path will be generated in the current directory. If the extraction name contains symbols like slash or backslash then subfolder(s) will be created for intermediate and output files. If in the above example, the extraction name is expressed as -EXTNM "MY/NAME\AA" then the output file will be AA.xgl and will be placed in a subfolder NAME of subfolder MY of the output folder defined in the project. For example, if the output folder defined in the project is "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1\Output" then the name of the output graphical file would be "C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1\Output\MY\NAME\AA.xgl".

• Creating output on basis of selected items.
  

  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  cd C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1
  @echo on
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/1/1}" -EXTNM "A01U11"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/1/2}" -EXTNM "A01U12"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/2/1}" -EXTNM "A02U01"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/2/2}" -EXTNM "A02U02"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/2/3}" -EXTNM "A02U03"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTRT "{/2/4}" -EXTNM "A02U04"
  @echo off
  echo Completed
  @echo on
  

  This example extracts data as defined by the configured SmartPlant model. Extracted items are defined by the -EXTRT parameter and the name of the output file is defined by the -EXTNM parameter. Notation like {/1} means that the entire first system is going to be extracted, {/1/1} means all items of the first member of the first system are extracted, {/1/2} means all items of the second member of the first system are extracted, etc. There is no depth limit, so {/3/2/2/1} is still valid. As the result of execution of the above example, a set of graphical files will be created:

  
  A01U11.xgl – with content of unit 11 of area 1
  A01U12.xgl – with content of unit 11 of area 1
  A02U01.xgl – with content of unit 1 of area 2
  A02U02.xgl – with content of unit 2 of area 2
  A02U03.xgl – with content of unit 3 of area 2
  A02U04.xgl – with content of unit 4 of area 2
  

  @echo off

  echo Running gateway...

  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D

  set APP=AVEVA.NET.Gateways.SG3D.exe

  cd C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1

  @echo on

  call "%GATEWAY%\%APP%" -CP "TEST-A001.xml" -EXTRT "{/2/1} {/2/2}" -EXTNM "A02(U01+U02)"

  @echo off

  echo Completed

  @echo on
  

  This example produces output file that contains all graphical items from two systems {/2/1} and {/2/2}.

  Notes:

  • If more than one system is going to be exported then the identifiers must be separated with the space character, for example: "{/2/1} {/2/2} {/2/3}".

  • Identifier {root} can be used to export the entire content of the model, but this is not recommended, especially for big models.

  • If the UID of the system to be extracted is known then it may be used instead of the "{/2/1}" notation, for example: "{00033458-0000-0000-6903-030071496404}".

  • By default space items are not extracted even if selected explicitly by identifiers. To enable the extraction of space items special instruction ({NS}) must be passed together with identifiers, for example: -EXTRT "{NS} {/8}".
    

    The following script returns all of the items of the {root} object of a plant named "Madison2018", from which you can determine the identifiers in the {/1/1} level.

    
    @echo off

    echo Getting information...

    set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D

    set APP=x86\svcS3d.exe

    echo Members of {root}

    call "%GATEWAY%\%APP%" -Checkout -OpenPlant "Madison2018" -GetMembers "{root}"

    @echo on
    

• Creating output on basis of a selected filter defined in the SmartPlant project.
  

  @echo off
  echo Running gateway...
  set GATEWAY=C:\Program Files\AVEVA\AVEVA NET Gateways\Gateway for SmartPlant 3D
  set APP=AVEVA.NET.Gateways.SG3D.exe
  cd C:\Users\<username>\Gateway for SmartPlant 3D Projects\A1
  @echo on
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTFL "Madison2018_MDB||My Filters||Area01||ALL" -EXTNM "A01/ALL"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTFL "Madison2018_MDB||My Filters||Area02||ALL" -EXTNM "A02/ALL"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTFL "Madison2018_MDB||My Filters||Area03||ALL" -EXTNM "A03/ALL"
  call "%GATEWAY%\%APP%" -CP "A1.xml" -EXTFL "ALL" -EXTNM "ANY/ALL"
  @echo off
  echo Completed
  @echo on
  

  This example shows how to use filters. The above four calls are using different filters named in the same way. The first three calls are providing the exact path to the filter that is going to be used in the extraction. The fourth call will run the first found filter named "ALL" so might be none from the above - this method is recommended only for filters where the user is sure they have unique names, otherwise the full path to the filter should be provided. Full path of the filter should be preceded with the name of the model database that the filter will work on. This name can be easily discovered in the UI of the Gateway. In the below screenshot, this name is just a name of the root element from the ‘Filter Selection’ tab page.

  
  

  Notes:

• You need to fill all mandatory fields in the configuration file, such as project name and project path.

• If the project configuration file is incorrect, the command line prompt throws an exception and the execution process is stopped.

  Example:

  Project paths, such as extractor config path, loader config path, transform config path, input path, log path and output path mentioned in the project configuration file must be valid. Otherwise, the execution of the configuration file stops.

  Output path scenarios are as follows:

  • If you provide an output path in the command line, then the provided path is the final output path. If you do not provide any output path, then the output path defined in the load configuration file is used.

  • If the output path provided by you is valid, then a check is conducted to determine whether the output path exists. If the output path does not exist, then a directory is created for the output files.

  • If you provide an invalid output path format, then the command line shows an exception message showing the invalid output path.

Exit Codes:

The following command line exit codes are defined for AVEVA.NET.Gateways.SG3D.exe.

Note: The exit code returned from the Gateway can be captured in the %errorlevel% variable when executed in batch mode.