# gizmodel/sql/catalog/routine

Stored routines and triggers as the catalog keeps them: one text per object (Engine.setObject), written by the parser from CREATE FUNCTION, PROCEDURE or TRIGGER in any dialect and read back by the binder (which inlines functions, proc.giz) and the session (which runs the rest).

```gizlang
import * as Routine from "gizmodel/sql/catalog/routine";
```

## Types

### `Param`

```gizlang
type Param = { name: string; ty: string; mode: string; default: string; }
```

A parameter: its name ("" when unnamed, then $n), declared type, mode (in, out, inout) and
default expression text.

- `name`: `string`
- `ty`: `string`
- `mode`: `string`
- `default`: `string`

### `Routine`

```gizlang
type Routine = { kind: string; name: string; params: Vec<Param>; returns: string; columns: Vec<Param>; language: string; body: string; strict: bool; attrs: string; }
```

kind: function or procedure. returns: the declared result type ("" for none, "trigger",
"setof T", or "table" with `columns`). language: sql, plpgsql or plsql. body: its source. strict: a NULL argument
makes the result NULL without a run (RETURNS NULL ON NULL INPUT). attrs: the other attributes, one
"key=value" a line (Parser.routineAttr: volatile, secdef, leakproof, parallel, cost, rows, body, set:NAME).

- `kind`: `string`
- `name`: `string`
- `params`: `Vec<M170.Param>`
- `returns`: `string`
- `columns`: `Vec<M170.Param>`
- `language`: `string`
- `body`: `string`
- `strict`: `bool`
- `attrs`: `string`

### `Trigger`

```gizlang
type Trigger = { name: string; table: string; timing: string; events: Vec<string>; columns: Vec<string>; row: bool; when: string; func: string; body: string; language: string; mode: string; args: Vec<string>; oldTable: string; newTable: string; }
```

`enabled`: it fires (ALTER TRIGGER ... DISABLE stops it).

- `name`: `string`
- `table`: `string`
- `timing`: `string`
- `events`: `Vec<string>`
- `columns`: `Vec<string>`
- `row`: `bool`
- `when`: `string`
- `func`: `string`
- `body`: `string`
- `language`: `string`
- `mode`: `string` — When it fires, as pg_trigger.tgenabled: O unless session_replication_role is replica, R only then, A always, D never.
- `args`: `Vec<string>`
- `oldTable`: `string`
- `newTable`: `string`

### `AggregateDef`

```gizlang
type AggregateDef = { sfunc: string; stype: string; initcond: string; hasInit: bool; finalfunc: string; args: Vec<string>; }
```

A user-defined aggregate (CREATE AGGREGATE) as the session folds it: SFUNC and STYPE, INITCOND (`hasInit`),
FINALFUNC ("" for none) and the argument types (none for name(*)).

- `sfunc`: `string`
- `stype`: `string`
- `initcond`: `string`
- `hasInit`: `bool`
- `finalfunc`: `string`
- `args`: `Vec<string>`

## Functions

### `routineText`

```gizlang
function routineText(r: Routine): string
```

Routine R as the catalog stores it.

Effects: fail, alloc.

### `routineOf`

```gizlang
function routineOf(text: string): Routine
```

The first routine stored under a name (routinesOf lists every overload).

Effects: fail, alloc.

### `triggerText`

```gizlang
function triggerText(t: Trigger): string
```

The triggers of one table are one object (the session reads them once per statement).

Effects: fail, alloc.

### `modeFires`

```gizlang
function modeFires(mode: string, replica: bool): bool
```

Whether a trigger of MODE fires in a session whose session_replication_role is REPLICA or not.

### `triggerOf`

```gizlang
function triggerOf(text: string): Trigger
```

The trigger that the stored TEXT holds.

Effects: fail, alloc.

### `triggersOf`

```gizlang
function triggersOf(text: string): Vec<Trigger>
```

The triggers that the stored TEXT holds.

Effects: fail, alloc.

### `triggersText`

```gizlang
function triggersText(ts: Vec<Trigger>): string
```

Triggers TS as the catalog stores them.

Effects: fail, alloc.

### `cloneModeText`

```gizlang
function cloneModeText(text: string, name: string, mode: string): string
```

The "trigger mode" text of a partition with clone NAME set to MODE, or back to its parent's for "".

Effects: fail, alloc.

### `inOnly`

```gizlang
function inOnly(p: Param): bool
```

Whether `p` only takes a value in (IN, or VARIADIC: the rest of the arguments as an array).

### `callParams`

```gizlang
function callParams(r: Routine): Vec<Param>
```

The parameters a call passes, in order: a PostgreSQL function's IN, INOUT and VARIADIC ones; all of a procedure's
and of a PL/SQL or T-SQL function's (its caller passes a variable for each OUT one).

Effects: fail, alloc.

### `routinesOf`

```gizlang
function routinesOf(text: string): Vec<Routine>
```

The routines that the stored TEXT holds.

Effects: fail, alloc.

### `routinesText`

```gizlang
function routinesText(rs: Vec<Routine>): string
```

Routines RS as the catalog stores them.

Effects: fail, alloc.

### `takesCall`

```gizlang
function takesCall(text: string, n: i64): bool
```

Whether one overload of `text` takes a call with `n` arguments.

Effects: fail, alloc.

### `overload`

```gizlang
function overload(text: string, n: i64): Routine
```

The overload a call with `n` arguments takes: one with exactly n input parameters, else one whose defaults or
VARIADIC parameter fill the gap, else the first (its errors name the mismatch). n < 0 takes the first.

Effects: fail, alloc.

### `overloadFor`

```gizlang
function overloadFor(text: string, args: Vec<Expr>): Routine
```

The overload a call with ARGS takes: as `overload`, but an overload whose array parameters are where the array
arguments are comes first (embed(text, text) and embed(text, text[])).

Effects: fail, alloc.

### `overloadAmbiguity`

```gizlang
function overloadAmbiguity(text: string, args: Vec<Expr>): string
```

"function f(types) is not unique" when the overload overloadFor takes for `args` and another one that takes as many
arguments by its defaults have the same types there (PostgreSQL's 42725); "" when it is unique.

Effects: fail, alloc.

### `shownTypes`

```gizlang
function shownTypes(ts: Vec<string>): string
```

Argument types as PostgreSQL prints them in "function f(...) does not exist".

Effects: fail, alloc.

### `shownWithMod`

```gizlang
function shownWithMod(t: string): string
```

Type T as format_type shows it, with its modifier: numeric(10,4).

Effects: fail, alloc.

### `signature`

```gizlang
function signature(ps: Vec<Param>): string
```

The input parameter types of `ps`, as DROP FUNCTION f(types) and overloads compare them.

Effects: fail, alloc.

### `routineKey`

```gizlang
function routineKey(r: Routine): string
```

The name and signature that key routine R's call counts (pg_stat_user_functions).

Effects: fail, alloc.

### `typesKey`

```gizlang
function typesKey(ts: Vec<string>): string
```

Types `ts` as signature writes them: each by its key, comma-separated.

Effects: fail, alloc.

### `typeKey`

```gizlang
function typeKey(ty: string): string
```

The key of the type TY in a signature: lower case, without pg_catalog.

Effects: fail, alloc.

### `aggregateEntries`

```gizlang
function aggregateEntries(text: string): Vec<string>
```

The catalog text of an aggregate's overloads: each is "signature\u0003options", "\u0004" between them.

Effects: fail, alloc.

### `aggregateDef`

```gizlang
function aggregateDef(text: string, arity: i64): AggregateDef
```

The overload of `text` (aggregateEntries) that takes `arity` arguments, else the first.

Effects: fail, alloc.

### `attrOf`

```gizlang
function attrOf(attrs: string, key: string): string
```

The value of attribute `key` of a routine's attrs, "" when it has none.

Effects: fail, alloc.

### `withAttr`

```gizlang
function withAttr(attrs: string, line: string): string
```

Attrs with `line` applied: it replaces the line of its key. "reset:NAME" drops the setting NAME, "reset:" all.

Effects: fail, alloc.

