Automating Processes Using Import and Batch Commands

This chapter covers the following topics:

Updating Models by Importing Files

Instead of performing tasks using the Strategic Network Optimization graphical user interface, you can automate processes using import and batch commands. Using import commands, you can build and change supply chain models and data without using the graphical user interface. Using batch commands, you can automate processes such as solving models and producing reports.

Import File Format

You can quickly build or change a model by importing an import file, which is a text file of import commands. You can use import files to:

An import file consists of a series of import commands in a text file. The text file can have any name. For consistency, Oracle recommends saving import files with the .imp file extension.

You can also import gzip files. These files have a .imp.gz extension and are automatically decompressed when they are imported.

You can create import files using a text editor or word processing package that saves documents in text format.

To make an import file easier to troubleshoot, group similar commands together. For example, group all commands that add nodes to a model in the import file. Ensure that commands for creating model components appear before commands that refer to the model components. For example:

Blank lines can appear anywhere in an import file.

Standard Import Command Syntax

You can include import commands in import files in two formats: standard import command syntax and tabular import command syntax. Standard import command syntax is useful if you need to import many different types of data or if you only need to update a few data fields. Tabular import command syntax is useful if you are updating a large amount of data.

You can include both standard import command and tabular formats in the same import file.

You can use the same import commands to add or change model components. For example, you can use the addnode command to add a node or to change data in an existing node. The standard import command syntax is:

import_command <symbolic_tag1> data1 <symbolic_tagx> datax

where:

Together, a symbolic tag and its data value are called a symbolic tag data pair. If you do not specify a symbolic tag pair for a new model component, the default data field value is used. Symbolic tag data pairs can appear in any order. For example, the following two commands are equal:

addnode <name> Mynode <type> Storage
addnode <type> Storage <name> Mynode

Use quotation marks to group together data that contains spaces, tabs, or commas. This rule applies to both arithmetic and text expressions. For example, the data Apple Storage requires quotation marks because of the space between the two words, but the data AppleStorage does not require quotation marks because it contains no spaces.

Each standard import command appears on one continuous line. A hard line break must appear after each standard import command, but it cannot appear within a command. Long commands can wrap around a page one or more times. Spaces can appear anywhere in a line, even before a command.

Tabular Import Command Syntax

The tabular import command syntax is:

$begintable <import_commandshared_data> <symbolic_tag1> <symbolic_tagx> 
data1...datax data1...datax 
$endtable 

where:

Import Commands

Using Import commands, you can add, change, or delete components of models. You can also change the view of a model and add messages.

You can use the same import commands to add or change model components. For example, you can use the addnode command to add a node or change data in an existing node.

The following table lists model components, import command functions, and the import commands:

Model Component Import Command Functions Import Commands
Node Add or change a node. addnode
  Add or change a node with associations. addnodewithassoc
  Delete a node. deletenode
  Delete a node with associations. deletenodewithassoc
  Add a node to a structural set. addnodetoset
  Add a node to a user set. addnodetouserset
  Connect nodes with an arc. connectnodes
  Create an arc to connect associated nodes with common attach points. connectnodeswithassoc
  Rename a node. renamenode
  Add or change a node with associations to a structural set. addnodetosetwithassoc
  Add or change a node with associations to a user set. addnodetousersetwithassoc
Attach Point Add or change an attach point. addattach
  Add or change an attach point to a node that is associated. addattachwithassoc
Arc Add or change an arc. addarc
  Delete an arc. deletearc
  Delete an arc that connects two nodes that are associated with each other. deletearcwithassoc
  Add an arc to a structural set. addarctoset
  Add an arc to a user set. addarctouserset
  Connect nodes with an arc. connectnodes
  Create an arc to connect associated nodes with common attach points. connectnodeswithassoc
  Add or change an arc with associations. addarcwithassoc
  Add an arc with associations to a structural set. addarctosetwithassoc
  Add an arc with associations to a user set. addarctousersetwithassoc
Commodity Add or change a commodity. addcommodity
  Rename a commodity. renamecommodity
  Duplicate a commodity. addcommodity
  Define a planning unit of measure for a commodity. Use the <planningUom> tag with the addcommodity command.
Commodity Groups Create a commodity group. addcommoditygroup
  Add a commodity to a commodity group. addcommoditytogroup
  Delete a commodity group. deletecommoditygroup
  Remove a commodity from a commodity group. removecommodityfromgroup
Period Groups Create a period group. addperiodgroup
  Add a period to a period group. addperiodtogroup
  Removes a period from a period group. removeperiodfromgroup
  Delete a period group. deleteperiodgroup
Period Group Levels Create a period group level. addperiodgrouplevel
  Delete a period group level. deleteperiodgrouplevel
Time Period Add or change a time period. addperiod
  Delete a time period. deleteperiod
Sets Add an arc to a structural set. addarctoset
  Add an arc to a user set. addarctouserset
  Add a node to a structural set. addnodetoset
  Add a node to a user set. addnodetouserset
  Block a structural set. blockset
  Unblock a set. unblockset
  Display customized help for a set. setinfotext
  Display a title for a set. setinfotitle
  Add a node with associations to a structural set. addnodetosetwithassoc
  Add an arc with associations to a structural set. addarctosetwithassoc
  Add a node with associations to a user set. addnodetousersetwithassoc
  Add an arc with associations to a user set. addarctousersetwithassoc
Unit of Measure Add a unit of measure to the global list of units of measure addUom
  Add an alternative unit of measure to a commodity addUomToCommodity
  Delete a unit of measure from the global list of units of measure. deleteUom
  Delete an alternative unit of measure from a commodity. deleteUomFromCommodity
  Rename a unit of measure in the global list. renameUom
View or Appearance Set the appearance of the graphical display. addroot
  Create or change a user-defined view in a symbolic file. addview
  Align nodes in a block. formatgraph
Messages Display a message during the import. echo
  Display customized help for a set. setinfotext
  Display a title for a set. setinfotitle
  Add a message for a model. usrmessage
Reports Create a new report group in the Model Workspace tree structure. addreportgroup
  Adds a group to an existing report group. addreporttogroup

Changing Model Components Using Import Commands

You can use the same import commands to add or change model components. For example, you can use the addnode command to add a node or to change data in an existing node.

To update existing data, enter only the symbolic tag data pairs for the data that you want to update. Data in these symbolic tag data pairs is then updated. Data to which the import file does not refer is not changed.

The data in an import command can include arithmetic expressions that change current data values. For example, the expression <min>x*20, in which x is the existing value, means that the updated minimum value is twenty times the existing value.

The following examples show standard import commands and their equivalent tabular import commands.

Adding Commodities

Suppose that you want to add three commodities named Marshmallow, Gingerbread, and Shortbread to your store's stock. These commodities are usually shipped in cases, so the planning unit of measure is a case.

Standard import:

addcommodity <name> "Marshmallow" <planningUom> "case"
addcommodity <name> "Gingerbread" <planningUom> "case"
addcommodity <name> "Shortbread" <planningUom> "case"

Tabular import:

$begintable addcommodity <name> <planningUom>
"Marshmallow" "case"
"Gingerbread" "case"
"Shortbread" "case"
$endtable

Adding Nodes

You want to add three nodes of different types and set their x and y coordinates.

Standard import:

addnode <name> "Blueberry" <type> Working <x> 696 <y> 84
addnode <name> "PackApple" <type> Process <x> 1433 <y> 90
addnode <name> "Package" <type> Supply <x> 367 <y> 271

Tabular import:

$begintable addnode <name> <type> <x> <y>
Blueberry Working 696 84
PackApple Process 1433 90
Package Supply 367 271
$endtable

Updating Values

You want to update the Maximum value for several arcs. The arcs all use the commodity Strawberry and flow into the Strawberry Fudge Process node.

Standard import:

addarc <commodity> Strawberry <from> StrawberryMachine1
<to> StrawberryProcess <max> 120
addarc <commodity> Strawberry <from> StrawberryMachine2 <to>
StrawberryProcess <max> 150
addarc <commodity> Strawberry <from> StrawberryMachine3 <to>
StrawberryProcess <max> 140

Tabular import:

$begintable 'addarc <commodity> Strawberry <to>
StrawberryProcess' <from>
<max> StrawberryMachine1 120
StrawberryMachine2 150
StrawberryMachine3 140
$endtable

You could also use the following tabular format:

$begintable addarc <from> <to> <commodity> <max> 
StrawberryMachine1 StrawberryProcess Strawberry 120 
StrawberryMachine2 StrawberryProcess Strawberry 150 
StrawberryMachine3 StrawberryProcess Strawberry 140 
$endtable

Creating and Changing a Model Using Tabular Import

In this example, a pancake plant packages two types of pancakes: Apple and Plain. Packages are supplied to the supply chain network, the two types of pancakes are packaged, and the packaged pancake mix is shipped to the demand source. One case of Apple pancakes uses 5 packages and takes 2 hours to package. One case of Plain pancakes uses 10 packages and takes 1 hour to package. The process has 50 hours available each month. Each month has a limit of 250 Packages that are available. Demand for Apple and Plain is as follows:

  January February
Apple 10 25
Plain 5 15

To model this supply chain network, you must create the following model components:

Creating a Model Using Tabular Import

You can use the following import file to create the model:

# This is the import file for pancake.imp

$begintable addperiod <name>
January
February
$endtable

$begintable addcommodity <name> <planningUom>
"Package" "pallet"
"Time" "hours"
"Apple" "crate"
"Plain" "pallet"
$endtable

$begintable 'addnode <type> Supply' <name> <max> <x> <y>
"Package Supply" 250 1000 2000
$endtable

$begintable addattach <node> <commodity> <in>
"Package Supply" Package False
$endtable

$begintable 'addnode <type> Process' <name> <x> <y>
"Process Apple" 2000 1000
"Process Plain" 2000 2000
$endtable

$begintable addattach <node> <commodity> <in> <quantity>
"Process Apple" Package True -5
"Process Apple" Time True -2
"Process Apple" Apple False 1
"Process Plain" Package True -10
"Process Plain" Time True -1
"Process Plain" Plain False 1
$endtable

$begintable 'addnode <type> Machine' <name> <max> <x> <y>
"Pack Machine" 50 1000 1000
$endtable

$begintable addattach <node> <commodity> <in>
"Pack Machine" Time False $endtable

$begintable 'addnode <type> Demand' <name> <period> <min> <max> <x> <y>
"Apple Demand" January 10 10 3000 1000
"Apple Demand" February 25 25 3000 1000
"Plain Demand" January 5 5 3000 2000
"Plain Demand" February 15 15 3000 2000
$endtable

$begintable addattach <node> <commodity> <in>
"Apple Demand" Apple True
"Plain Demand" Plain True
$endtable

$begintable addarc <from> <to> <commodity>
"Package Supply" "Process Apple" Package
"Package Supply" "Process Plain" Package
"Pack Machine" "Process Apple" Time
"Pack Machine" "Process Plain" Time
"Process Apple" "Apple Demand" Apple
"Process Plain" "Plain Demand" Plain
$endtable

addnodetoset DEMAND "Apple Demand"
addnodetoset DEMAND "Plain Demand"
blockset DEMAND

Changing a Model Using Tabular Import

If a model changes, you can update it using tabular import. For example, in this supply chain network, the demand has changed:

Data January February
Apple 25 10
Plain 10 10

To update the model, you can create and import the following file:

$begintable 'addnode <type> Demand' <name> <period> <min> <max> <x> <y>
"Apple Demand" January 25 25 3000 1000
"Apple Demand" February 10 10 3000 1000
"Plain Demand" January 10 10 3000 2000
"Plain Demand" February 10 10 3000 2000
$endtable

Importing Files

To import a file:

  1. Do one of the following:

    • If you are creating a new file, select New from the File menu in the Strategic Network Optimization window.

    • If you are updating a model, select Open from the File menu in the Strategic Network Optimization window. In the Open window, select a model file and then click Open.

  2. From the File menu, select Import.

  3. In the Import window, select an import file and click Open.

    If the model name does not appear in the Files area, click directories in the Directories list until you locate the directory in which the file is saved.

  4. When the import is complete, save the model.

By default, Strategic Network Optimization populates the Files of type field with *.imp. To import a gzip file, select *.imp.gz from the Files of type drop-down list. When a .imp.gz file is imported, it is automatically decompressed.

Automating Processes Using Batch Mode

You can automate many Strategic Network Optimization processes using batch mode. Batch mode enables you to perform tasks such as solving models and producing reports by using a batch script or at a command line prompt instead of the graphical user interface. Users usually run batch commands from batch scripts rather than typing them on a command line.

You can use batch mode to take advantage of overnight operations. For example, you could run a script at 6:00 PM each day to load a model, import data, solve the model, and generate reports overnight.

Typically, users build the structure of a Strategic Network Optimization model using the graphical user interface, batch mode to update data in the model, and use the graphical user interface to view results.

Batch Script Format

A batch script is a text file that contains a series of batch commands. The text file can have any name. You can create batch scripts using a text editor or word processing package that saves files in text format. Each batch command should appear on a separate line in a batch script.

Example

The following batch script contains commands to load a model, import data, run a solve, apply a report query and export the data to Excel:

symloadfile /user/.../filename.sym
import /user/.../...
solve
applysmartgraph
export to excel

Note: Commands require absolute paths.

For brief descriptions of commands, use the help batch mode command.

File Commands

The following table describes file commands:

Command Description
importfilename.imp or .imp.gz Imports a file. The default format is .imp. To import a compressed gzip file, use the .imp.gz extension.
symloadfilefilename .sym or .sym.gz Loads a file. The default file format is .sym. To load a compressed gzip file, use the .sym.gx extension.
symdsavefilename .sym or symsave —gzip.sym.gz Saves a file.

Model Commands

The following table describes model commands:

Command Description
addcurrency Uses import files to update the Currency Table.
addriskstrategy Adds a risk type in the Risk Registry.
addroot Sets the appearance of the graphical display and is an alternative to using the View menu.
addUom Adds a unit of measure to the Units of Measure list.
addUomToCommodity Adds an alternative unit of measure to a commodity.
deletecurrency Uses import files to delete a currency from the Currency Table.
deleteriskstrategy Deletes a risk type from the Risk Registry.
deleteUom Deletes a unit of measure from the Units of Measure list.
deleteUomFromCommodity Deletes an alternative unit of measure from a commodity. fix Sets Fix fields to Yes for nodes and arc within a set.
fix Sets Fix fields to Yes for nodes and arc within a set.
formatgraph filename Does a Format Contents of Block on the block name. If you do not specify a block name, it formats the top-level view.
modelprofile Prints the model name, the model size, the number of arcs, nodes, commodities and periods, solver details and an estimated number of variables and constraints by node type and arc.
renameUom Renames a unit of measure in the Units of Measure list.
setstringlength Specifies the maximum number of characters that can be used in a node name.
showlonelynodes Prints the names and node types of all lonely nodes in the model.
unfix Sets Fix fields to No for nodes and arcs in one set or in an entire model.

Publish Commands

The following table describes publish commands:

Command Description
addprofile Creates a profile that can be published.
changeprofile Modifies a profile's information.
deleteprofile Deletes a profile.
publishprofile Publishes a profile to a .csv, .xml, or .smart file.

Solver Commands

The following table describes solver commands:

Command Description
cplexdump Creates either an MPS file, which provides the objective functions and constraints in a column format, or an LP, which provides the objective function and constraints in algebraic form.
cvreport Reports on the results of the solve.
detailedreport Used after a model is solved to view a detailed cost, profit, or risk adjusted cost report that shows the distribution of costs or profits by node type.
discardbasis Discards the solver basis.
generate Creates the cplex.lp file for a model.
memtest Displays the total amount of memory on the system that is available to Strategic Network Optimization. The command takes a while to run as it scrolls the amount, displayed in both bytes and Megabytes.
problemstats Displays information about unscaled infeasibilities in model data.
restorebaseline Restores the baseline.
setbaseline Sets the baseline.
setsolveralgorithm Specifies the type of linear program used in a solve.
solutionquality Displays information about the maximum reduced-cost infeasibility, the maximum bound infeasibility, and the sensitivity of the model data.
solve Solves models or parts of models.
solvereport Used after solving a model to view a summary cost, profit, or risk adjusted cost report of the solve.
solverlog Directs Strategic Network Optimization to write the number of solver iterations in each stage of a solve to the lxsolve.log file, which is stored in the current working directory.

Report Query Commands

The following table describes report query commands:

Command Description
applysmartgraphs filename.smart Applies the active report queries and stores the results in filename.smart. If you do not specify an output file, the results are stored in the file $HOME/linx.smart.
exportsmartgraph filename.smt filename.csv Exports data extracted from a model by the report query file (filename.smt) to a comma separated value file. Report queries must be applied before they are exported (report queries are applied by using the applysmartgraphs command).
inactivateallsmartgraphs Deactivates all report queries.
loadsmartgraph filename.smt Loads a report query.
unloadsmartgraph filename.smt Unloads a report query.
unloadsmartgraphs Unloads all report queries.

Scenarios and Events Commands

The following table describes Scenarios and Events commands:

Command Description
addscenario Creates a scenario.
addeventchange Adds replace criteria to a scenario.
addscenarioendscript Adds an end script file to a scenario.
addeventimport Adds an import file to a scenario.
addeventmatch Adds find criteria to a scenario.
addscenariosmart Associates a report with a scenario.
addscenariosolveres Stores solve results with a model after a scenario runs, if the model is saved.
addscenariostartscript Adds a start script file to a scenario.
addscenarioview Adds an existing view to a scenario.
deletescenario Deletes a scenario.
duplicatescenario Duplicates a scenario. The duplicated scenario has all the same attributes and associations as the original. However, a duplicated scenario is not updated when changes are made to the original.
runscenario Runs a scenario.
selectscenario Saves the scenario file.

User Interface Commands

The following table describes user interface commands:

Command Description
addmenubutton Adds customized menus for running batch scripts to the Strategic Network Optimization interface by using the linx.startup file.
copyright Hides the splashscreen that appears when Strategic Network Optimization starts.
removemenubutton Deletes a menu option.
returnfromui Returns the user to batch mode from interface mode.
ui Starts the user interface.

General Commands

The following table describes general commands:

Command Description
! Runs the specified shell command. For example, on UNIX, ! ls displays a directory listing. This command is useful for running scripts.
? Displays information about a command that you specify. If no command is specified, the system displays information about all batch commands.
< Reads commands from the specified file and returns to the command line when finished. Can be nested.
> Prints output to the specified file. > stderr displays output on the screen.
>> Appends output to the specified file.
coredump <y/n> In UNIX, if coredump is on, a core file is created when the application terminates unexpectedly.
echo Displays a message in a window when a file is imported.
exit Stops execution of scripts, regardless of how many scripts are running.
help Displays brief help on the specified command. If you do not specify a command, it displays help on all of the batch commands.
panicsave <y/n> If panicsave is on, a backup of the model called linxsave.sym is performed when a controlled termination of the application occurs.
quit Quits the current script.
record Records each noncomment batch command that Strategic Network Optimization runs.
timestamp Displays the total number of seconds that have elapsed since January 1, 1970.
verbose y Prints each command before it is run.
verbose n Turns off verbose mode.

Running Batch Scripts or Batch Commands

Strategic Network Optimization batch scripts or batch commands can be run in Windows or UNIX.

To run a batch script or batch commands in Windows:

  1. Do one of the following:

    • From the Start menu, select Programs, Oracle Supply Chain Planning, Strategic Network Optimization x.x, Strategic Network Optimization Console.

    • From a DOS prompt, run the sno.bat file from the SNO\vers_x.x\bin directory.

  2. At the command prompt, do one of the following:

    To run a Procedure
    Batch script Enter the following:
    <batchscript

    where batchscript is the name of a batch name. For example, to run a batch file named SNObatch.file, enter:
    <SNObatch.file
    Batch command Enter a batch command.

To run a batch script or batch commands in UNIX:

  1. Create an environment variable as follows:

    export 
    variable =/install_path/SNO/vers_x.x/bin/LXx.x

    where variable is a variable name, install_path is the directory for the application, and x.x is the Strategic Network Optimization version that you want to run. You can save this line in your profile so that the variable is set up every time that you log in.

  2. Do one of the following:

    To run a Procedure
    Batch script At a command prompt, enter:
    $variable<batchscript

    where:
    $variable is the variable that you created in step 1, and batchscript is the name of a batch script.
    For example, if you create the variable SNOBATCH in step 1 and a batch file named SNObatch.file, you would enter:
    $SNOBATCH < SNObatch.file
    Batch commands At a command prompt, enter:
    $variable commands 

    where: $variable is the variable you created in step 1, and commands are batch commands. Separate commands with spaces and enclose commands in quotation marks if they contain spaces.
    For example, if you create the variable SNOBATCH in step 1, you can enter:
     $SNOBATCH symloadfile coffee.sym solve symsave coffee.sym exit 

    This command loads the coffee.sym model, solves it, saves it, and then exits from batch mode.

Running Batch Commands at Startup

You can set up a file called linx.startup in your home directory that automatically runs batch commands when you start Strategic Network Optimization. The linx.startup file can specify files to load or other actions to perform whenever you start Strategic Network Optimization. The location of linx.startup must be present in the path specified in the HOME environment variable.

For example, if you save the following linx.startup file in your home directory, the system loads and solves the cookies.sym model every time that you start Strategic Network Optimization:

symloadfile /sno/models/cookies.sym solve 

You can use almost all batch commands in a linx.startup file except for the following:

User-Defined Menu Scripts

A startup script must be run before the Strategic Network Optimization is launched. The startup script can contain environment variables that can be used in user-defined menus. For example, you can specify paths in linx.startup. The location of linx.startup must be present in the path specified in the HOME environment variable. For example, the following command in linx.startup:

addmenubutton Oracle_Menu|Analysis /Oracle/Supply_Chain_Planning/
sno_weekly/Supply_Chain_Analysis/
Run_Analysis.script

could be shortened to:

addmenubutton Oracle_Menu|Analysis $SNO/Run_Analysis.script

if $SNO in the startup script points to /Oracle/Supply_Chain_Planning/sno_weekly/Supply_Chain_Analysis. Similarly, a user-defined menu script can use the environment variables specified in a startup script. For example, you could use the following command:

import $SNO_RISK_PROCUREMENT/risk_procure_1.imp

if $SNO_RISK_PROCUREMENT,in the startup script points to /Oracle/Supply_Chain_Planning/Risk_Strategies.