API reference¶

import "github.com/D-Modem/go3270"

const (
    PlaneBlue  byte = 1
    PlaneRed   byte = 2
    PlaneGreen byte = 4
)

var (
    ErrNoDFT       = errors.New("the terminal does not do DFT file transfer")
    ErrDFTProtocol = errors.New("DFT file transfer: unexpected reply")
    ErrDFTAborted  = errors.New("the transfer was cancelled at the terminal")
)

var Debug io.Writer

var ErrNo3270 = errors.New("couldn't negotiate telnet options for tn3270")

var ErrTelnetError = errors.New("telnet or 3270 protocol error")

var ErrUnknownTerminal = errors.New("unknown terminal type")

func AIDtoString(aid AID) string

func DFTBufferSize(dev DevInfo) int

func DFTMessage(conn net.Conn, timeout time.Duration, msg string) error

func ImagePicture(x, y int, planes ...Bitmap) ([]byte, error)

func ImagePictures(x, y int, o PictureOptions, planes ...Bitmap) ([][]byte, int, error)

func ReadRecord(conn net.Conn, timeout time.Duration) ([]byte, error)

func ReceiveFileDFT(conn net.Conn, dev DevInfo, w io.Writer, maxBytes int64, timeout time.Duration) (int64, error)

func RunTransactions(conn net.Conn, dev DevInfo, initial Tx,
    data any) error

func SendFileDFT(conn net.Conn, dev DevInfo, r io.Reader, timeout time.Duration) (int64, error)

func SetCodepage(cs Codepage)

func ShowScreenNoResponse(screen Screen, values map[string]string,
    crow, ccol int, conn net.Conn) error

func UnNegotiateTelnet(conn net.Conn, timeout time.Duration) error

func WriteStructuredFields(conn net.Conn, fields ...[]byte) error

type AID byte

const (
    AIDNone  AID = 0x60
    AIDEnter AID = 0x7D
    AIDPF1   AID = 0xF1
    AIDPF2   AID = 0xF2
    AIDPF3   AID = 0xF3
    AIDPF4   AID = 0xF4
    AIDPF5   AID = 0xF5
    AIDPF6   AID = 0xF6
    AIDPF7   AID = 0xF7
    AIDPF8   AID = 0xF8
    AIDPF9   AID = 0xF9
    AIDPF10  AID = 0x7A
    AIDPF11  AID = 0x7B
    AIDPF12  AID = 0x7C
    AIDPF13  AID = 0xC1
    AIDPF14  AID = 0xC2
    AIDPF15  AID = 0xC3
    AIDPF16  AID = 0xC4
    AIDPF17  AID = 0xC5
    AIDPF18  AID = 0xC6
    AIDPF19  AID = 0xC7
    AIDPF20  AID = 0xC8
    AIDPF21  AID = 0xC9
    AIDPF22  AID = 0x4A
    AIDPF23  AID = 0x4B
    AIDPF24  AID = 0x4C
    AIDPA1   AID = 0x6C
    AIDPA2   AID = 0x6E
    AIDPA3   AID = 0x6B
    AIDClear AID = 0x6D
)

type Bitmap struct {
    Color Color // Blue, Red, Pink, Green, Turquoise, Yellow or White
    Rows  []string
}

func DitherBitmaps(img image.Image, p Palette) []Bitmap

type Codepage interface {
    // Decode converts a slice of EBCDIC bytes into a UTF-8 string.
    Decode(e []byte) string

    // Encode converts a UTF-8 string into a slice of EBCDIC bytes.
    Encode(s string) []byte

    // ID returns the name of this codepage. Usually a numeric string like
    // "037" or "1047", but could also be a name such as "bracket" if IBM has
    // not assigned a number to the particular codepage.
    ID() string
}

func Codepage037() Codepage

func Codepage1026() Codepage

func Codepage1047() Codepage

func Codepage1140() Codepage

func Codepage1141() Codepage

func Codepage1142() Codepage

func Codepage1143() Codepage

func Codepage1144() Codepage

func Codepage1145() Codepage

func Codepage1146() Codepage

func Codepage1147() Codepage

func Codepage1148() Codepage

func Codepage1149() Codepage

func Codepage1160() Codepage

func Codepage273() Codepage

func Codepage275() Codepage

func Codepage277() Codepage

func Codepage278() Codepage

func Codepage280() Codepage

func Codepage284() Codepage

func Codepage285() Codepage

func Codepage297() Codepage

func Codepage424() Codepage

func Codepage500() Codepage

func Codepage803() Codepage

func Codepage870() Codepage

func Codepage871() Codepage

func Codepage875() Codepage

func Codepage880() Codepage

func Codepage924() Codepage

func CodepageBracket() Codepage

type Color byte

const (
    DefaultColor Color = 0
    Blue         Color = 0xf1
    Red          Color = 0xf2
    Pink         Color = 0xf3
    Green        Color = 0xf4
    Turquoise    Color = 0xf5
    Yellow       Color = 0xf6
    White        Color = 0xf7
)

type DevInfo interface {
    // AltDimensions returns the number or rows and columns on the alternate
    // screen size.
    AltDimensions() (rows, cols int)

    // TerminalType reports the terminal-provided identification string. All
    // modern tn3270 clients will report one of the IBM-3278 models (-2, -3,
    // -4, or -5), or IBM-DYNAMIC if the alternate screen size isn't one of
    // the fixed sizes of the 3278 models. This string is purely
    // informational; the actual size of the alternate screen is available
    // from AltDimensions().
    TerminalType() string

    // Codepage is the Codepage interface that implements the EBCDIC
    // translation for the detected code page for the terminal, if supported.
    // This may be nil if the client code page is unknown. Whenever calling
    // the screen functions, always pass the value returned by this Codepage()
    // function in the ScreenOpts (nil is allowed to default to the global
    // default codepage).
    Codepage() Codepage

    // SupportsGE returns true if the client indicated it supports graphic
    // escape to code page 310.
    SupportsGE() bool

    // QueryReply returns the client's query reply with the given QCODE
    // (0x81 Usable Area, 0x85 Character Sets, 0xB0 Segment, ...), from the
    // QCODE byte on, or nil if the client sent none. The slice is a copy.
    QueryReply(qcode byte) []byte

    // QueryCodes lists the QCODEs of the query replies the client sent, in
    // ascending order.
    QueryCodes() []byte

    // CellSize is the size of the default character cell in pels, from the
    // Usable Area query reply (0, 0 if the client did not say).
    CellSize() (width, height int)

    // SymbolSets describes the client's character sets and its support for
    // loading programmed symbols (see LoadPS), from the Character Sets query
    // reply; nil if the client sent none.
    SymbolSets() *SymbolSets

    // SupportsVectorGraphics reports whether the client answered the query
    // with the Segment query reply (0xB0), or lists it in its Summary
    // reply, which means it takes graphics segments: vector graphics in
    // Object Picture structured fields.
    SupportsVectorGraphics() bool
    // contains filtered or unexported methods
}

func NegotiateTelnet(conn net.Conn) (DevInfo, error)

type Field struct {
    // Row is the row, 0-based, that the field attribute character should
    // begin at. When using the standard screen of 24 rows, Row must be 0-23.
    // When writing to the alternate screen, Row may be up to 1 less than the
    // number of rows on the screen.
    Row int

    // Col is the column, 0-based, that the field attribute character should
    // begin at. When using the standard screen of 80 columns, Col must be
    // 0-79. When writing to the alternate screen, Col may be up to 1 less
    // than the number of columns on the screen.
    Col int

    // Text is the content of the field to display.
    Content string

    // PositionOnly will use a Set Buffer Address (SBA) command to move the
    // cursor to the position, but not insert a new attribute byte. The only
    // properties of the Field that will apply if PositionOnly is true are:
    // Row, Col, Content, Name. Others will be silently ignored.
    PositionOnly bool

    // Write allows the user to edit the value of the field.
    Write bool

    // Autoskip causes protected (Write = false) fields to automatically be
    // skipped and the cursor should move to the next field upon encountering
    // this field. Autoskip is ignored on fields with Write = true.
    Autoskip bool

    // Intense indicates this field should be displayed with high intensity.
    Intense bool

    // Hidden indicates the field content should not be displayed (e.g. a
    // password input field).
    Hidden bool

    // NumericOnly indicates that only numbers may be entered into the field.
    // Very fiew 3270 clients support this, so you must always still validate
    // the input on the server side.
    NumericOnly bool

    // Color is the field color. The default value is the default color.
    Color Color

    // Highlighting is the highlight attribute for the field. The default value
    // is the default (i.e. no) highlighting.
    Highlighting Highlight

    // AttributeOnly will cause this "field" (which won't really be a new
    // field) to use the SA (Set Attribute) 3270 command to change the color
    // and highlighting of the text WITHOUT starting a new field. You can
    // create a field at Row 5, Column 10, with AttributeOnly true, and the
    // text will start in Roe 5, Column 10 and not skip a space to column 11
    // like a new field would when AttributeOnly is false.
    //
    // If AttributeOnly is true, the Write, Autoskip, Intense, Hidden, and
    // NumericOnly properties will have no effect. Only Highlighting and Color
    // will affect the output, and will both default to Default (e.g. default
    // highlighting and default color) if not specificed in this field.
    //
    // After using AttributeOnly to change color and highlighting, you may
    // need to explicitly use another AttributeOnly "field" to reset to
    // defaults, a regular (AttributeOnly = false) field may not end the
    // attributes. (See example1.)
    AttributeOnly bool

    // Name is the name of this field, which is used to get the user-entered
    // data. All writeable fields on a screen must have a unique name.
    // Protected fields may also have a name to populate them dynamically when
    // the screen is sent.
    Name string

    // CharSet is the local ID of the character set the field is shown in:
    // 0 for the default; a programmed symbol set's LCID (see LoadPS). It is
    // sent as an extended field attribute (SFE type 0x43), so it ends with
    // the field; with AttributeOnly, as a Set Attribute (SA type 0x43),
    // which lasts until another changes it (see DefaultCharSet).
    CharSet byte

    // DefaultCharSet, with AttributeOnly, sets the character set back to
    // the default (SA type 0x43, 0) for the characters after it.
    DefaultCharSet bool

    // Raw, if not nil, is sent as the field's content as it is, instead of
    // Content encoded in the code page: the code points of programmed
    // symbols (0x41 to 0xFE) in a CharSet field. Values in the values map do
    // not replace it.
    Raw []byte

    // KeepSpaces will prevent the strings.TrimSpace() function from being
    // called on the field value. Generally you want leading and trailing
    // spaces trimmed from fields in 3270 before processing, but if you are
    // building a whitespace-sensitive application, you can ask for the
    // original, un-trimmed value for a field by setting this to true.
    KeepSpaces bool
}

type FieldRules struct {
    // MustChange, when true, indicates that the value of the field MUST be
    // altered by the user -- if applied to a field with no starting value,
    // this makes the field a required field. If true on a field with a
    // starting value (either in the field's Content attribute, or with an
    // override in the initial values map), then the user must change
    // the value from the default.
    MustChange bool

    // ErrorText is the text displayed with the MustChange validation fails.
    // If ErrorText is the empty string, but MustValidation fails, an error
    // string will be constructed from the field name: "Please enter a valid
    // value for <fieldName>."
    ErrorText string

    // Validator is a function to validate the value the user input into the
    // field. It may be nil if no validation is required. The Validator
    // function is called *after* the MustChange logic, so if you wish to
    // fully handle validation, ensure MustChange is set to false.
    Validator Validator

    // Reset indicates that if the screen fails validation, this field should
    // always be reset to its original/default value, regardless of what the
    // user entered.
    Reset bool
}

type Highlight byte

const (
    DefaultHighlight Highlight = 0
    Blink            Highlight = 0xf1
    ReverseVideo     Highlight = 0xf2
    Underscore       Highlight = 0xf4
)

type IndFile struct {
    Get     bool     // GET: the host sends the file; PUT: the host receives it
    Name    string   // the host file name, as typed
    ASCII   bool     // ASCII (text) rather than binary
    CRLF    bool     // CR LF line ends
    Append  bool     // PUT appends to the host file
    Options []string // all the options, upper case
}

func ParseIndFile(s string) (*IndFile, bool)

type LoadPS struct {
    RWS   byte // the store: a loadable SymbolSet's RWS
    LCID  byte // the local ID to give it, 0x40 to 0xEF
    First byte // the first symbol's code point, 0x41 to 0xFE
    Clear bool // clear the store's other symbols

    // Format is the data format: 1 (a 9 by 16 cell: 2 bytes of the left
    // column, then 16 bytes of the other 8 columns, a byte a row) or 3
    // (rows of Width pels, top to bottom). Check SymbolSets.SupportsFormat.
    Format int

    // Width and Height of a format 3 cell: the client's slot size, unless
    // Extended.
    Width, Height int

    // Extended sends the extended form of Load PS, which tells the client
    // Width and Height (SymbolSets.Extended must be true).
    Extended bool

    // Plane is the plane of a triple-plane (color) set the symbols are
    // loaded into: PlaneBlue, PlaneRed or PlaneGreen; 0, all three (or a
    // single-plane set). A plane needs the extended form, which it implies.
    // A cell shows its planes' colors, added (blue and red make pink...),
    // where its color attribute is White (neutral, X'F7'), GA23-0059 4.5.
    Plane byte

    Symbols []Symbol
}

func (l LoadPS) StructuredField() ([]byte, error)

type Mix byte

const (
    MixOverpaint Mix = 2 // the color drawn replaces what was there
    MixXor       Mix = 4 // exclusive or: a blue and a red plane make pink
)

type Palette map[int]color.RGBA

func GraphicColors(d DevInfo) Palette

type PictureOptions struct {
    // Mix is how pels combine with what is drawn: MixOverpaint for an
    // image with a bitmap a color, each pel in one (exclusive or does not
    // combine blue with the other colors on IBM Personal Communications);
    // MixXor if 0.
    Mix Mix
    // Segment is the number of the first graphics segment (named "B001"
    // on): pictures sent together need segments of their own. 1 if 0.
    Segment int
}

type Response struct {
    // Which Action ID key did the user press?
    AID AID

    // Row the cursor was on (0-based).
    Row int

    // Column the cursor was on (0-based).
    Col int

    // Field values.
    Values map[string]string
}

func HandleScreen(screen Screen, rules Rules, values map[string]string,
    pfkeys, exitkeys []AID, errorField string, crow, ccol int,
    conn net.Conn, codepage ...Codepage) (Response, error)

func HandleScreenAlt(screen Screen, rules Rules, values map[string]string,
    pfkeys, exitkeys []AID, errorField string, crow, ccol int,
    conn net.Conn, dev DevInfo, codepage ...Codepage) (Response, error)

func ShowScreen(screen Screen, values map[string]string, crow, ccol int,
    conn net.Conn) (Response, error)

func ShowScreenOpts(screen Screen,
    values map[string]string, conn net.Conn,
    opts ScreenOpts) (Response, error)

type Rules map[string]FieldRules

type Screen []Field

type ScreenOpts struct {
    // If AltScreen is non-nil, the screen will be written to the "alternate"
    // screen size, which is the non-default (24x80) screen dimensions that
    // the terminal supports (although for many terminals, the alternate
    // screen is still just 24x80). If AltScreen is nil, the default (24x80)
    // mode will be used. Never switch between AltScreen and normal screen
    // (e.g. AltScreen = nil) unless NoClear is false. (That is, switching
    // between default and alternate screen size or back requires a screen
    // clear at the same time.) When AltScreen is nil, field positions in the
    // screen must be within the 24x80 screen (so rows 0-23 and cols 0-79),
    // when AltScreen is present, the field positions must be within the
    // dimensions of the DevInfo.AltDimensions() values.
    AltScreen DevInfo

    // Codepage is the Codepage implementation to use when sending text to the
    // client and translating incoming field text from the client. Typically
    // you should pass in the return value from DevInfo.Codepage() each time
    // to get the correct codepage that was detected when the client
    // connected. If nil, the global default code page (default 1047, but
    // changed with the SetCodepage() function) will be used. NOTE: providing
    // a DevInfo to ScreenOpts.AltScreen does _not_ automatically set this
    // value, you must set it explicitly on every call that accepts
    // ScreenOpts.
    Codepage Codepage

    // NoResponse will draw the screen and immediately return, without
    // waiting for any input data from the remote client.
    NoResponse bool

    // NoClear will send the data stream to the remote client without
    // clearing the screen first. Existing data will be overlayed with
    // the current screen.
    NoClear bool

    // CursorRow sets the row (0-indexed) to position the cursor after sending
    // the screen, when NoClear is false. When AltScreen is nil, maximum value
    // is 23; otherwise, maximum is 1 less than the number of rows in
    // AltScreen.
    CursorRow int

    // CursorCol sets the column (0-indexed) to position the cursor after
    // sending the screen, when NoClear is false. When AltScreen is nil,
    // maximum value is 79; otherwise, maximum is 1 less than the number of
    // columns in AltScreen.
    CursorCol int

    // PostSendCallback is a function that, if non-nil, will be called after
    // go3270 sends the datastream to the client, but before it blocks to
    // read the response (if NoResponse is true, the callback will still be
    // called before returning). If the function returns an error, then
    // the ShowScreenOpts() function will return the error instead of a
    // response. The value of CallbackData will be passed as the argument to
    // the function.
    PostSendCallback func(any) error

    // CallbackData is passed as the argument to the PostSendCallback
    // function.
    CallbackData any
}

type Symbol []string

type SymbolSet struct {
    RWS      byte // device specific ID: LoadPS.RWS for a loadable set
    LCID     byte // the local ID it has now (0xFF: none)
    Loadable bool
    Triple   bool // triple plane (color) set
    DBCS     bool
    // slot size, if the client gives one per set (0: SlotWidth/Height)
    SlotWidth, SlotHeight int
    CGCSGID               uint32 // character set and code page
}

type SymbolSets struct {
    // GraphicEscape: the alternate character set is reachable by GE.
    GraphicEscape bool

    // Loadable: the client takes the Load Programmed Symbols structured
    // field. It can only be used if Sets has a Loadable set, too.
    Loadable bool

    // Extended: the extended form of Load PS (with the cell size) is
    // supported.
    Extended bool

    // SizeMatch: a Load PS cell size must match the slot size exactly.
    SizeMatch bool

    // SlotWidth, SlotHeight: the default character slot, in pels.
    SlotWidth, SlotHeight int

    // Formats: bit i (counting from the most significant bit) set when Load
    // PS format type i is supported. See SupportsFormat.
    Formats uint32

    // Sets are the character sets the client has, in the order it gave.
    Sets []SymbolSet
}

func (s *SymbolSets) LoadableSets() []SymbolSet

func (s *SymbolSets) SupportsFormat(t int) bool

type Tx func(conn net.Conn, dev DevInfo, data any) (
    next Tx, newdata any, err error)

type Validator func(input string) bool

var IsInteger Validator = func(input string) bool {
    input = strings.TrimSpace(input)
    return isIntegerRegexp.MatchString(input)
}

var NonBlank Validator = func(input string) bool {
    return !(strings.TrimSpace(input) == "")
}