GetEntitiesCP

The GetEntitiesCP method is part of sqac’s CRUD API and is used to retrieve existing rows of the specified entity from their related database table. Structs annotated with ‘sqac:’ tags are colloquially known as sqac entities, hence the parameter name ‘ents’.

The ents parameter must be a pointer to a slice declared using the go struct-type corresponding to the targeted database table. This method can be thought of as a flexible retrieval mechanism for one or more database records. Complex selections can be constructed through the use of the params and cmdMap parameters.

The call returns the slice pointer as well as the number of retrieved records and the standard go error type.

Parameters

Parameter Description
ents interface{} An empty slice declared to be of the go struct-type corresponding to the targeted database table. For example: depotRead := []Depot{} n, err := Handle.GetEntitiesCP(&depotRead, p, cm) A pointer to the depotRead slice should be passed into the method in the ents parameter. The method will populate the slice based on the records retrieved from the database thereby making the selected records available to the caller on completion of the method.
pList []GetParam A slice containing a list of parameters for use as SELECT criteria when retrieving the requested records from the database. Each record in the sqac.GetParam slice must contain a column-name from the target table, an operator and a value. See the example program below.
cmdMap map[string]interface{} The cmdMap parameter is used to provide additional instructions for use in the query. Supported commands include: count, orderby, asc, desc, limit and offset. Examples of the commands are shown in the subsequent sections.

CRUD GetEntitiesCP Simple Example

The following example illustrates reading all records from table “depot”:

// create a slice to hold records read from table "depot"
depotRecs:= []Depot{}

// call with no parameters and no commands
_, err := Handle.GetEntitiesCP(&depotRecs, nil, nil)

CRUD GetEntitiesCP pList Example

// create a slice to hold records read from table "depot"
depotRecs:= []Depot{}

// setup selection parameters
p := sqac.GetParam{
    FieldName:    "region",
    Operand:      "=",
    ParamValue:   "ON",
    NextOperator: "AND"
}
pa := []sqac.GetParam{}
pa = append(pa, p)

p.FieldName = "population"
p.Operand = ">"
p.ParamValue = 1000000
p.NextOperator = ""
pa = append(pa, p)

// call with parameters and no commands
_, err := Handle.GetEntitiesCP(&depotRecs, pa, nil)

CRUD GetEntitiesCP pList and cmdMap Example

// create a slice to hold records read from table "depot"
depotRecs:= []Depot{}

// setup selection parameters
p := sqac.GetParam{
    FieldName:    "region",
    Operand:      "=",
    ParamValue:   "AB",
    NextOperator: "AND"
}
pa := []sqac.GetParam{}
pa = append(pa, p)

p.FieldName = "population"
p.Operand = ">"
p.ParamValue = 50000
p.NextOperator = ""
pa = append(pa, p)

// create cmdMap - non-sensical, but shows what can be done
// set $orderby=name$descending$limit=3$offset=2
cm := make(map[string]interface{})
cm["orderby"] = "population"
cm["asc"] = nil   // no value required
cm["limit"] = 3
cm["offset"] = 2

// call with parameters and command map
_, err := Handle.GetEntitiesCP(&depotRecs, pa, cm)