goolx

README

Overview

Disclaimer: This project is not endorsed or affiliated with ASPEN Inc. This library is currently untested.

goolx is an unofficial Go wrapper around ASPEN's Oneliner API. It can be utilized to create programs which interact with Oneliner through the provided API functions. Additionally, it provides helper functions for common analysis tasks.

The goal of this module is to provide generic unopinionated abstractions for fault analysis. These functions can be used as a building block for useful fault analysis application development.

This library is in Version 0.x.x, and may have breaking API changes during development.

Installation

It is required users of this Go module have authorized licenses for the underlying ASPEN software. Obtaining this third-party software is outside the scope of this README.

The module can be installed using the following go get command.

go get -u github.com/readpe/goolx

This library is only designed for use on Windows 386 architecture. To properly build, ensure your GOOS and GOARCH environment variables are set appropriately:

GOOS=windows
GARCH=386

Usage Example

import (
	"fmt"
	"log"

	"github.com/readpe/goolx"
	"github.com/readpe/goolx/olxapi"
)

func main() {
	c := goolx.NewClient()
	defer c.Release() // releases api dll at function return

	// Print the olxapi info.
	info := c.Info()
	fmt.Println(info)

	// Load a oneliner case into memory.
	err := c.LoadDataFile("system.olr")
	if err != nil {
		log.Fatal(err)
	}

	// Loop through all buses in case using NextEquipment iterator.
	buses := c.NextEquipment(olxapi.TCBus)
	for buses.Next() {
		hnd := buses.Hnd()

		// Get bus data
		b, err := goolx.GetBus(c, hnd)
		if err != nil {
			log.Println(fmt.Errorf("could not get bus data: %v", err))
			continue
		}
		fmt.Printf("found bus %s %fkV with handle: %d", b.Name, b.KVNominal, b.HND)
	}
}

Acknowledgements

Thanks to ASPEN Inc. for providing the Python API which inspired the development of this module.

Documentation

Index

• Constants
• type Bus
  • func GetBus(c *Client, hnd int) (*Bus, error)
• type Client
  • func NewClient() *Client
  • func (c *Client) BuildNumber() (int, error)
  • func (c *Client) EquipmentType(hnd int) (int, error)
  • func (c *Client) FindBus(name string, kv float64) (int, error)
  • func (c *Client) FindBusNo(n int) (int, error)
  • func (c *Client) GetData(hnd int, tokens ...int) Data
  • func (c *Client) Info() string
  • func (c *Client) LoadDataFile(name string) error
  • func (c *Client) NextEquipment(eqType int) HandleIterator
  • func (c *Client) NextEquipmentByTag(eqType int, tags ...string) HandleIterator
  • func (c *Client) ReadChangeFile(name string) error
  • func (c *Client) Release() error
  • func (c *Client) SaveDataFile(name string) error
  • func (c *Client) Version() (string, error)
• type Data
  • func (d *Data) Scan(dest ...interface{}) error
• type HandleIterator
• type NextEquipment
  • func (n *NextEquipment) Hnd() int
  • func (n *NextEquipment) Next() bool
• type NextEquipmentByTag
  • func (n *NextEquipmentByTag) Hnd() int
  • func (n *NextEquipmentByTag) Next() bool

Examples

• Data.Scan

Constants

const (
	KiB = 1 << (10 * 1)
	MiB = 1 << (10 * 2)
)

Byte size constants

Types

type Bus

type Bus struct {
	HND       int     // ASPEN Oneliner equipment handle
	Name      string  // BUSsName
	KVNominal float64 // BUSdKVnominal
	Number    int     // BUSnNumber
	Area      int     // BUSnArea
	Zone      int     // BUSnZone
	Tap       int     // BUSnTapBus
	Comment   string  // BUSsComment (aka Memo field)
}

Bus represents a bus equipment data structure. This does not represent all fields from ASPEN model, future fields may be added as needed.

func GetBus

func GetBus(c *Client, hnd int) (*Bus, error)

GetBus retrieves the bus with the given handle using the provided api client. Data is Scanned into a new bus object and returned if no errors.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a new goolx api client.

func NewClient

func NewClient() *Client

NewClient returns a new goolx Client instance.

func (*Client) BuildNumber

func (c *Client) BuildNumber() (int, error)

BuildNumber parses the build number from the olxapi.dll info function.

func (*Client) EquipmentType

func (c *Client) EquipmentType(hnd int) (int, error)

EquipmentType returns the equipment type code for the equipment with the provided handle

func (*Client) FindBus

func (c *Client) FindBus(name string, kv float64) (int, error)

FindBus returns the bus handle for the given bus name and kv, if found

func (*Client) FindBusNo

func (c *Client) FindBusNo(n int) (int, error)

FindBusNo returns the bus with the provided bus number. Or returns 0 and an error if not found.

func (*Client) GetData

func (c *Client) GetData(hnd int, tokens ...int) Data

GetData returns data for the object handle, and all parameter tokens provided. The data for each token can be retrieved using the Scan method on the Data type. This is similar to the Row.Scan in the sql package.

func (*Client) Info

func (c *Client) Info() string

Info calls the OlxAPIVersionInfo function, returning the string

func (*Client) LoadDataFile

func (c *Client) LoadDataFile(name string) error

LoadDataFile loads *.olr file from disk

func (*Client) NextEquipment

func (c *Client) NextEquipment(eqType int) HandleIterator

NextEquipment returns an EquipmentIterator type. The EquipmentIterator will loop through all equipment handles in the case until it reaches the end. This is done using the Next() and Hnd() methods. Note: ASPEN equipment handle integers are not unique and are generated on data access. Therefore care should be taken when using handle across functions or applications. It is recommended to use the handle immediately after retrieving to get unique equipment identifiers.

func (*Client) NextEquipmentByTag

func (c *Client) NextEquipmentByTag(eqType int, tags ...string) HandleIterator

NextEquipmentByTag returns a NextEquipmentTag type which satisfies the HandleIterator interface.

func (*Client) ReadChangeFile

func (c *Client) ReadChangeFile(name string) error

ReadChangeFile reads *.chf file from disk and applies to case

func (*Client) Release

func (c *Client) Release() error

Release releases the api dll. Must be called when done with use of dll.

func (*Client) SaveDataFile

func (c *Client) SaveDataFile(name string) error

SaveDataFile saves *.olr file to disk

func (*Client) Version

func (c *Client) Version() (string, error)

Version parses the version number from the olxapi.dll info function.

type Data

type Data struct {
	// contains filtered or unexported fields
}

Data represents data returned via the GetData method.

func (*Data) Scan

func (d *Data) Scan(dest ...interface{}) error

Scan copies the data from the matched parameter token into the values pointed at by dest. The order of the destination pointers should match the parameters queried with GetData. Will return an error if any parameters produced an error during GetData call. Data will not be populated in this case.

Example

var busHnd int
api := NewClient()
data := api.GetData(busHnd, olxapi.BUSsName, olxapi.BUSdKVP)

// Scan loads the data into the pointers provided populating the Bus structure in this example.
bus := Bus{}
data.Scan(&bus.Name, &bus.KVNominal)

type HandleIterator

type HandleIterator interface {
	Next() bool
	Hnd() int
}

HandleIterator is a iterator interface for equipment handles.

type NextEquipment

type NextEquipment struct {
	// contains filtered or unexported fields
}

NextEquipment is an equipment handle iterator for getting the next equipment handle of the provided type. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextEquipment) Hnd

func (n *NextEquipment) Hnd() int

Hnd returns the current equipment handle, Next() must be called first.

func (*NextEquipment) Next

func (n *NextEquipment) Next() bool

Next retrieves the next equipment handle of type. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.

type NextEquipmentByTag

type NextEquipmentByTag struct {
	// contains filtered or unexported fields
}

NextEquipmentByTag is an equipment handle iterator for getting the next equipment handle of the provided type with the listed tags. The Next() method will retrieve the next handle if available and populate it for access by Hnd(). If Next() returns false, then there was an error or the list was exhausted. Once the iterator is exhausted it cannot be reused.

func (*NextEquipmentByTag) Hnd

func (n *NextEquipmentByTag) Hnd() int

Hnd returns the current equipment handle, Next() must be called first.

func (*NextEquipmentByTag) Next

func (n *NextEquipmentByTag) Next() bool

Next retrieves the next equipment handle of type. Returns true if successful, and false if not. Hnd() should not be used if Next() is false. This can be used in for loops.