isclib

package module
v2.2.2+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 15, 2020 License: Apache-2.0 Imports: 19 Imported by: 11

README

isclib

Latest Tag CLA assistant Build Status Go Report Card GoDoc

Go library for interacting with InterSystems Corporation products like Caché, Ensemble, and IRIS Data Platform

It provides methods for determining if ISC products are installed and for interacting with instances of them

Some example code can be found in the GoDocs

Documentation

Overview

Package isclib facilitates managing and interacting with ISC products

A simple example of checking for available ISC commands 

package main

import (
    "github.com/ontariosystems/isclib"
)

func main() {
    if isclib.AvailableCommands().Has(isclib.CControlCommand) {
        // perform actions if Cache/Ensemble is installed
    }

    if isclib.AvailableCommands().Has(isclib.IrisCommand) {
        //perform actions if Iris is installed
    }
}

You can get access to an instance, find information about the instance (installation directory, status, ports, version, etc.) and perform operations like starting/stopping the instance and executing code in a namespace

A simple example of interacting with an instance by ensuring the instance is running and then printing the version 

	package main

	import (
		"bytes"
		"fmt"

		"github.com/ontariosystems/isclib"
	)

	const (
		c = `MAIN
 	write $zversion
 	do $system.Process.Terminate($job,0)
 	quit

	`
	)

	func main() {
		i, err := isclib.LoadInstance("docker")
		if err != nil {
			panic(err)
		}

		if i.Status == "down" {
			if err := i.Start(); err != nil {
				panic(err)
			}
		}

		r := bytes.NewReader([]byte(c))
		if out, err := i.Execute("%SYS", r); err != nil {
			panic(err)
		} else {
			fmt.Println(out)
		}
	}

Index

Constants

View Source 
const (

	// DefaultImportQualifiers are the default ISC qualifiers used for importing source
	DefaultImportQualifiers = "/compile/keepsource/expand/multicompile"
	// CacheDatName is the common name for a Cache database file
	CacheDatName = "CACHE.DAT"
	// IrisDatName is the common name for a Iris database file
	IrisDatName = "IRIS.DAT"
)

Variables

View Source 
var (
	// ErrTooManyRecursiveDirs is an error signifying too many ** are included in the glob pattern
	ErrTooManyRecursiveDirs = errors.New("the glob must contain at most one **")
	// ErrMissingPathSeparator is an error signifying a missing path separator in the glob pattern
	ErrMissingPathSeparator = errors.New("there must be a path separator between ** and file pattern")
	// ErrPathAfterRecursiveDirs is an error signifying that additional path information is included after the ** in the glob pattern
	ErrPathAfterRecursiveDirs = errors.New("a ** must only be used as the last portion of the path before the file pattern")
	// ErrWildcardInDirectory is an error signifying that a wildcard has been included in the directory part of the glob pattern
	ErrWildcardInDirectory = errors.New("the directory portion of the glob must not contain *")
)
View Source 
var (
	// ErrLoadFailed is an error signifying that the loading of the source code failed
	ErrLoadFailed = errors.New("load did not appear to finish successfully")
)
View Source 
var FS = afero.NewOsFs()

FS is a wrapper for the file system

Functions

func CControlPath added in v0.0.4 

func CControlPath() string

CControlPath returns the current path to the ccontrol executable

func CSessionPath added in v0.0.4 

func CSessionPath() string

CSessionPath returns the current path to the csession executable

func ExecuteTemporaryDirectory added in v1.0.0 

func ExecuteTemporaryDirectory() string

ExecuteTemporaryDirectory returns the directory where temporary files for ObjectScript execution will be placed. "" means the system default temp directory.

func IrisPath 

func IrisPath() string

IrisPath returns the current path to the iris executable

func IrisSessionCommand 

func IrisSessionCommand() string

IrisSessionCommand returns the current string for the iris session command

func SetCControlPath added in v0.0.4 

func SetCControlPath(path string)

SetCControlPath sets the current path to the ccontrol executable

func SetCSessionPath added in v0.0.4 

func SetCSessionPath(path string)

SetCSessionPath sets the current path to the csession executable

func SetExecuteTemporaryDirectory added in v1.0.0 

func SetExecuteTemporaryDirectory(path string)

SetExecuteTemporaryDirectory sets the directory where temporary files for ObjectScript execution will be placed. Passing "" will result in using the system default temp directory.

func SetIrisPath 

func SetIrisPath(path string)

SetIrisPath sets the current path to the iris executable

func SetIrisSessionCommand 

func SetIrisSessionCommand(path string)

SetIrisSessionCommand sets the current string for the iris session command

func ToggleZSTU added in v1.2.0 

func ToggleZSTU(cpfFilePath string, onOrOff bool) (originalValue bool, err error)

ToggleZSTU ensures that the cpf file at the path provided has the ZSTU setting set to true or false based on the provided boolean value. It also returns the original value for the ZSTU

Types

type Commands 

type Commands uint

Commands represents the ISC command lines that are available 

const (
	// CControlCommand indicates that the ccontrol command is available
	CControlCommand Commands = 1 << iota
	// CSessionCommand indicates that the csession command is available
	CSessionCommand
	// IrisCommand indicates that the iris command is available
	IrisCommand
	// NoCommand indicates the none of the ISC command lines are available
	NoCommand Commands = 0
)

func AvailableCommands 

func AvailableCommands() Commands

AvailableCommands returns a Commands bitmask indicating which ISC command lines are available

func (*Commands) Clear 

func (c *Commands) Clear(command Commands)

Clear updates the list of available commands to remove the provided command

func (Commands) Has 

func (c Commands) Has(command Commands) bool

Has returns a boolean indicating whether the requested command is marked as available

func (*Commands) Set 

func (c *Commands) Set(command Commands)

Set updates the list of available commands to include the provided command

type Dat 

type Dat struct {
	Path       string
	Permission string
	Owner      string
	Group      string
	Exists     bool
}

Dat holds information that pertains an existing ISC database

type ImportDescription added in v0.0.5 

type ImportDescription struct {
	Dir         string
	FilePattern string
	Recursive   bool
	Qualifiers  string
}

ImportDescription holds information needed for constructing a valid ISC $SYSTEM.OBJ.ImportDir command

func NewImportDescription added in v0.0.5 

func NewImportDescription(pathGlob string, qualifiers string) (*ImportDescription, error)

NewImportDescription creates and returns a new import description based on the provided glob pattern and ISC qualifiers

func (*ImportDescription) String added in v0.0.5 

func (i *ImportDescription) String() string

String returns an ISC $SYSTEM.OBJ.ImportDir command as a string

type Instance 

type Instance struct {
	// Required to be able to run the executor
	SessionPath string `json:"-"` // The path to the session executable
	ControlPath string `json:"-"` // The path to the control executable

	// These values come directly from qlist
	Name             string         `json:"name"`             // The name of the instance
	Directory        string         `json:"directory"`        // The directory in which the instance is installed
	Version          string         `json:"version"`          // The version of Caché/Ensemble/Iris
	Status           InstanceStatus `json:"status"`           // The status of the instance (down, running, etc.)
	Activity         string         `json:"activity"`         // The last activity date and time (as a string)
	CPFFileName      string         `json:"cpfFileName"`      // The name of the CPF file used by this instance at startup
	SuperServerPort  int            `json:"superServerPort"`  // The SuperServer port
	WebServerPort    int            `json:"webServerPort"`    // The internal WebServer port
	JDBCPort         int            `json:"jdbcPort"`         // The JDBC port
	State            string         `json:"state"`            // The State of the instance (warn, etc.)
	Product          Product        `json:"product"`          // The product name of the instance
	MirrorMemberType string         `json:"mirrorMemberType"` // The mirror member type (Failover, Disaster Recovery, etc)
	MirrorStatus     string         `json:"mirrorStatus"`     // The mirror Status (Primary, Backup, Connected, etc.)
	DataDirectory    string         `json:"dataDirectory"`    //  The instance data directory.  This might be the same as Directory if durable %SYS isn't in use
	// contains filtered or unexported fields
}

An Instance represents an instance of Caché/Ensemble/Iris on the current system.

func InstanceFromQList 

func InstanceFromQList(qlist string) (*Instance, error)

InstanceFromQList will parse the output of a qlist into an Instance struct. It expects the results of a qlist for a single instance as a string. It returns the parsed instance and any error encountered.

func LoadInstance 

func LoadInstance(name string) (*Instance, error)

LoadInstance retrieves a single instance by name. The instance name is case insensitive. It returns the instance and any error encountered.

func (*Instance) DatInfo 

func (i *Instance) DatInfo() (map[string]Dat, error)

DatInfo will parse the instance's CPF file for its databases (CACHE.DAT, IRIS.DAT). It will get the path of the InterSystems DAT file, the permissions on it, and its owning user / group. The function returns a map of Dat structs containing the above information using the name of the database as its key.

func (*Instance) DetermineISCDatFileName 

func (i *Instance) DetermineISCDatFileName() string

DetermineISCDatFileName returns the filename of the InterSystems DAT files used by the instance

func (*Instance) DetermineManager added in v0.0.4 

func (i *Instance) DetermineManager() (string, string, error)

DetermineManager will determine the manager of an instance by reading the parameters file associated with this instance. The manager is the primary user of the instance that will be able to perform start/stop operations etc. It returns the manager and manager group as strings and any error encountered.

func (*Instance) DetermineOwner added in v0.0.2 

func (i *Instance) DetermineOwner() (string, string, error)

DetermineOwner will determine the owner of an instance by reader the parameters file associate with this instance. The owner is the user which owns the files from the installers and as who most Caché processes will be running. It returns the owner and owner group as strings and any error encountered.

func (*Instance) DeterminePrimaryJournalDirectory added in v1.3.0 

func (i *Instance) DeterminePrimaryJournalDirectory() (string, error)

DeterminePrimaryJournalDirectory will parse the ISC instance's CPF file for its primary journal directory (CurrentDirectory).

func (*Instance) DetermineSecondaryJournalDirectory added in v1.3.0 

func (i *Instance) DetermineSecondaryJournalDirectory() (string, error)

DetermineSecondaryJournalDirectory will parse the ISC instance's CPF file for its secondary journal directory (AlternateDirectory).

func (*Instance) Execute 

func (i *Instance) Execute(namespace string, codeReader io.Reader) (string, error)

Execute will read code from the provided io.Reader and execute it in the provided namespace. The code must be valid Caché ObjectScript INT code obeying all of the correct spacing with a MAIN label as the primary entry point. Valid INT code means (this list is not exhaustive)...

  • Labels start at the first character on the line
  • Non-labels start with a single space
  • You may not have blank lines internal to the code
  • You must have a single blank line at the end of the script

It returns any output of the execution and any error encountered.

func (*Instance) ExecuteAsCurrentUser added in v0.0.2 

func (i *Instance) ExecuteAsCurrentUser() error

ExecuteAsCurrentUser will configure the instance to execute all future commands as the current user. It returns any error encountered.

func (*Instance) ExecuteAsManager added in v0.0.4 

func (i *Instance) ExecuteAsManager() error

ExecuteAsManager will configure the instance to execute all future commands as the instance's owner. This command only functions if the calling program is running as root. It returns any error encountered.

func (*Instance) ExecuteAsUser added in v0.0.2 

func (i *Instance) ExecuteAsUser(execUser string) error

ExecuteAsUser will configure the instance to execute all future commands as the provided user. This command only functions if the calling program is running as root. It returns any error encountered.

func (*Instance) ExecuteString added in v0.0.2 

func (i *Instance) ExecuteString(namespace string, code string) (string, error)

ExecuteString will execute the provided code in the specified namespace. code must be properly formatted INT code. See the documentation for Execute for more information. It returns any output of the execution and any error encountered.

func (*Instance) ExecuteWithOutput added in v0.0.6 

func (i *Instance) ExecuteWithOutput(namespace string, codeReader io.Reader, out io.Writer) error

ExecuteWithOutput will read code from the provided io.Reader and execute it in the provided namespace while writing any output to the provided io.Writer.

func (*Instance) ImportSource added in v0.0.5 

func (i *Instance) ImportSource(namespace, sourcePathGlob string, qualifiers ...string) (string, error)

ImportSource will import the source specified using a glob pattern into Caché with the provided qualifiers. sourcePathGlob only allows a subset of glob patterns. It must be in the format /p/a/t/h/**/*.xml 

/p/a/t/h/ is the import directory
you have have at most one **
after the ** you must have only a file pattern
To import a single file it would be /a/b/c/file.xml

qualifiers are standard Caché import/compile qualifiers, if none are provided a default set will be used It returns any output of the import and any error encountered.

func (*Instance) LicenseKeyFilePath 

func (i *Instance) LicenseKeyFilePath() string

LicenseKeyFilePath returns the file path to the license key for the instance

func (*Instance) ReadParametersISC added in v0.0.4 

func (i *Instance) ReadParametersISC() (ParametersISC, error)

ReadParametersISC will read the current instances parameters ISC file into a simple data structure. It returns the ParametersISC data structure and any error encountered.

func (*Instance) SessionCommand 

func (i *Instance) SessionCommand(namespace, command string) *exec.Cmd

SessionCommand will return a properly configured instance of exec.Cmd to run the provided command (properly formatted for session) in the provided namespace.

func (*Instance) Start 

func (i *Instance) Start() error

Start will ensure that an instance is started. It returns any error encountered when attempting to start the instance.

func (*Instance) Stop 

func (i *Instance) Stop() error

Stop will ensure that an instance is started. It returns any error encountered when attempting to stop the instance.

func (*Instance) Update 

func (i *Instance) Update() error

Update will query the the underlying instance and update the Instance fields with its current state. It returns any error encountered.

func (*Instance) UpdateFromQList 

func (i *Instance) UpdateFromQList(qlist string) (err error)

UpdateFromQList will update the current Instance with the values from the qlist string. It returns any error encountered.

func (*Instance) WaitForReady 

func (i *Instance) WaitForReady(ctx context.Context) error

WaitForReady waits indefinitely for an instance to be up and ready for use

func (*Instance) WaitForReadyWithInterval 

func (i *Instance) WaitForReadyWithInterval(ctx context.Context, interval time.Duration) error

WaitForReadyWithInterval waits for an instance to be up and ready for use or until the interval is exceeded

type InstanceStatus 

type InstanceStatus string

An InstanceStatus represents one of the various status associated with Caché/Ensemble instances. 

const (
	// InstanceStatusUnknown represents a blank/unknown instance status.
	InstanceStatusUnknown InstanceStatus = ""

	// InstanceStatusRunning represents a running instance.
	InstanceStatusRunning InstanceStatus = "running"

	// InstanceStatusInhibited represents an instance that is up but sign-ons have been inhibited due to an issue.
	InstanceStatusInhibited InstanceStatus = "sign-on inhibited"

	// InstanceStatusPrimaryTransition represents an instance that is up but the primary mirror member is being determined.
	InstanceStatusPrimaryTransition InstanceStatus = "sign-on inhibited:primary transition"

	// InstanceStatusDown represents an instance that is down.
	InstanceStatusDown InstanceStatus = "down"

	// InstanceStatusMissingIDS represents an instance that is up but missing a non-critical (but expected) information file.
	InstanceStatusMissingIDS InstanceStatus = "running on node ? (cache.ids missing)"
)

func (InstanceStatus) Down 

func (iis InstanceStatus) Down() bool

Down will return true if the instance status represents a fully down instance.

func (InstanceStatus) Handled 

func (iis InstanceStatus) Handled() bool

Handled will return true when this status is a known and handled status.

func (InstanceStatus) Ready 

func (iis InstanceStatus) Ready() bool

Ready will return true if the status represents an acceptably running status.

func (InstanceStatus) RequiresBypass 

func (iis InstanceStatus) RequiresBypass() bool

RequiresBypass returns true when a bypass is required to stop the instance

func (InstanceStatus) Up 

func (iis InstanceStatus) Up() bool

Up will return true if status represents any up status (even unclean states like sign-on inhibited)

type Instances 

type Instances []*Instance

Instances represents a collection of Caché/Ensemble instances

func LoadInstances 

func LoadInstances() (Instances, error)

LoadInstances returns a listing of all Caché/Ensemble instances on this system. It returns the list of instances and any error encountered.

func (Instances) Update 

func (instances Instances) Update() error

Update will query the underlying instances and update the Instance fields with their current values. It returns any error encountered.

type ParametersISC added in v0.0.4 

type ParametersISC map[string]ParametersISCGroup

ParametersISC represents the contents of the parameters ISC file

func LoadParametersISC added in v0.0.4 

func LoadParametersISC(r io.Reader) (ParametersISC, error)

LoadParametersISC will load the parameters contained in the provided reader It returns the ParametersISC data structure and any error encountered

func (ParametersISC) Value added in v0.0.4 

func (pi ParametersISC) Value(identifiers ...string) string

Value will, given a set of identifiers making up a parameter key, return the single value at that key Identifiers can be... 

the full key (group.name)
the group, name as two separate parameters
A single parameter representing the name of a parameter in the "" group

It returns the value if a single value exists for the key or "" if it does not

func (ParametersISC) Values added in v0.0.4 

func (pi ParametersISC) Values(identifiers ...string) []string

Values will, given a set of identifiers making up a parameter key, return the values at that key Identifiers can be... 

the full key (group.name)
the group, name as two separate parameters
A single parameter representing the name of a parameter in the "" group

It returns the values at that key or an empty slice if it does not exist

type ParametersISCEntry added in v0.0.4 

type ParametersISCEntry struct {
	// The group for this entry (the portion of the key before the .)
	Group string

	// The name of this entry (the portion of the key after the .)
	Name string

	// The values for this entry
	Values []string
}

ParametersISCEntry represents a single entry from the parameters ISC file

func (ParametersISCEntry) Key added in v0.0.4 

func (pie ParametersISCEntry) Key() string

Key returns the full group.name key for this element

type ParametersISCGroup added in v0.0.4 

type ParametersISCGroup map[string]*ParametersISCEntry

ParametersISCGroup represents a group of related parameters from the ISC file

type Product 

type Product uint

Product represents a particular ISC product 

const (
	// Cache is the ISC product Cache
	Cache Product = iota
	// Ensemble is the ISC product Ensemble
	Ensemble
	// Iris is the ISC product IRIS Data Platform
	Iris
	// None indicates that there are no ISC products
	None Product = 0
)

func ParseProduct 

func ParseProduct(product string) Product

ParseProduct parses a string representing a ISC product into a Product. The default for unknown strings is Cache.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.