Name
Synopsis
Description
Basic Functions
Options
Hostname Syntax
Character Sets
NVT (ANSI) Mode
Toggles
Functions
File Transfer
Scripts
Passthru
Resources
See Also
Copyrights
Version
Returns 1 if there are events pending, 0 if not, <0 for an error.
The return codes from the above functions, and from other 3270 functions which return integers, are as follows. Note that all of the failure values are less than zero.
3270 functions which return character strings cannot block, so they return a non-NULL string for success, and a NULL string for failure.
The first part is the base model, which is either 3278 or 3279. 3278 specifies a monochrome 3270 display; 3279 specifies a color 3270 display.
The second part is the model number, which specifies the number of rows and columns. Model 4 is the default.
Note: Technically, there is no such 3270 display as a 3279-4 or 3279-5, but most hosts seem to work with them anyway.
The default model is 3278-4.
Some hosts are confused by the -E suffix on the terminal name, and will ignore the extra screen area on models 3, 4 and 5. Prepending an :s on the hostname, or setting the "lib3270.extended" resource to "false", removes the -E from the terminal name when connecting to such hosts.
The name can also be specified with the "lib3270.termName" resource.
[prefix:]...[LUname@]hostname[:port]
Prepending a p: onto hostname causes the connection to go through the telnet-passthru service rather than directly to the host. See PASSTHRU below.
Prepending an s: onto hostname removes the "extended data stream" option reported to the host. See -tn below for further information.
Prepending an n: onto hostname turns off TN3270E support for the session.
A specific LU name to use may be specified by prepending it to the hostname with an `@'. Multiple LU names to try can be separated by commas. An empty LU can be placed in the list with an extra comma.
On systems that support the forkpty library call, the hostname may be replaced with -e and a command string. This will cause lib3270 to connect to a local child process, such as a shell.
The port to connect to defaults to telnet. This can be overridden with the -port option, or by appending a port to the hostname with a colon `:'.
The default character set is bracket, which is useful for common IBM hosts which use EBCDIC codes 0xAD and 0xBD for the `[' and `]' characters, respectively.
If the host later negotiates to stop functioning in 3270 mode, lib3270 will return to ANSI emulation.
In NVT mode, lib3270 supports both character-at-a-time mode and line mode operation. You may select the mode with a menu option. When in line mode, the special characters and operational characteristics are defined by resources:
Mode/Character | Resource | Default |
Translate CR to NL | lib3270.icrnl | true |
Translate NL to CR | lib3270.inlcr | false |
Erase previous character | lib3270.erase | ^? |
Erase entire line | lib3270.kill | ^U |
Erase previous word | lib3270.werase | ^W |
Redisplay line | lib3270.rprnt | ^R |
Ignore special meaning of next character | lib3270.lnext | ^V |
Interrupt | lib3270.intr | ^C |
Quit | lib3270.quit | ^\ |
End of file | lib3270.eof | ^D |
The names of the toggles for use with the -set and -clear options are as follows:
Option | Name |
Monocase | monoCase |
Blank Fill | blankFill |
Track Cursor | cursorPos |
Trace Data Stream | dsTrace |
Trace Events | eventTrace |
Save Screen(s) in File | screenTrace |
Wraparound | lineWrap |
These names are also used as the first parameter to the Toggle function.
Return values are kept in a 10-element ring, so that up to ten lib3270 library calls may be used in the same expression.
Functions which take a timeout parameter specify the timeout in seconds. A value of 0 is used to wait indefinitely.
const char *sAsciiAll(l3h_t h) | return entire screen contents in ASCII |
const char *sAsciiFromCursor(l3h_t h, int length) | return screen contents at cursor in ASCII |
const char *sAsciiLine(l3h_t h, int row, int col, int length) | return screen contents in ASCII |
const char *sAsciiBlock(l3h_t h, int row, int col, int rows, int cols) | return screen region in ASCII |
const char *int AsciiField(l3h_t h) | return current field in ASCII |
int sXX_BLOCK()Attn(l3h_t h) | attention key |
int sBackSpace(l3h_t h) | move cursor left (or send ASCII BS) |
int sBackTab(l3h_t h) | tab to start of previous input field |
int aXX_BLOCK()Clear(l3h_t h) | clear screen |
int sCols(l3h_t h) | report screen size |
int aXX_BLOCK()Connect(l3h_t h, const char *host) | connect to host |
int aXX_BLOCK()CursorSelect(l3h_t h) | Cursor Select AID |
int sDelete(l3h_t h) | delete character under cursor (or send ASCII DEL) |
int sDeleteField(l3h_t h) | delete the entire field |
int sDeleteWord(l3h_t h) | delete the current or previous word |
int sXX_BLOCK()Disconnect(l3h_t h) | disconnect from host |
int sDown(l3h_t h) | move cursor down |
int sDup(l3h_t h) | duplicate field |
const char *sEbcdicAll(l3h_t h) | return entire screen contents in EBCDIC |
const char *sEbcdicFromCursor(l3h_t h, int length) | return screen contents at cursor in EBCDIC |
const char *sEbcdicLine(l3h_t h, int row, int col, int length) | return screen contents in EBCDIC |
const char *sEbcdicBlock(l3h_t h, int row, int col, int rows, int cols) | return screen region in EBCDIC |
const char *int EbcdicField(l3h_t h) | return current field in EBCDIC |
int aXX_BLOCK()Enter(l3h_t h) | Enter AID (or send ASCII CR) |
int sErase(l3h_t h) | erase previous character (or send ASCII BS) |
int sEraseEOF(l3h_t h) | erase to end of current field |
int sEraseInput(l3h_t h) | erase all input fields |
int sFieldEnd(l3h_t h) | move cursor to end of field |
int sFieldExit(l3h_t h) | clear to end of field and skip to next (5250 emulation) |
int sFieldMark(l3h_t h) | mark field |
int aHexString(l3h_t h, const char *hex_digits) | insert control-character string |
int sHome(l3h_t h) | move cursor to first input field |
int sInsert(l3h_t h) | set insert mode |
int sXX_BLOCK()Interrupt(l3h_t h) | send TELNET IP to host |
int aKey(l3h_t h, const char *keysym) | insert key keysym |
int sLeft(l3h_t h) | move cursor left |
int sLeft2(l3h_t h) | move cursor left 2 positions |
int sMonoCase(l3h_t h) | toggle uppercase-only mode |
int sMoveCursor(l3h_t h, int row, int col) | move cursor to (row,col) |
int sNewline(l3h_t h) | move cursor to first field on next line (or send ASCII LF) |
int sNextWord(l3h_t h) | move cursor to next word |
int aXX_BLOCK()PA(l3h_t h, int n) | Program Attention AID (n from 1 to 3) |
int aXX_BLOCK()PF(l3h_t h, int n) | Program Function AID (n from 1 to 24) |
int sPreviousWord(l3h_t h) | move cursor to previous word |
int sRedraw(l3h_t h) | redraw window |
int sReset(l3h_t h) | reset locked keyboard |
int sRight(l3h_t h) | move cursor right |
int sRight2(l3h_t h) | move cursor right 2 positions |
int sRows(l3h_t h) | report screen size |
const char *sSnapAscii... | report saved screen data (see sAscii) |
int sSnapCols(l3h_t h) | report saved screen size |
const char *sSnapEbcdic... | report saved screen data (see sEbcdic) |
int sSnapRows(l3h_t h) | report saved screen size |
int sSnapSave(l3h_t h) | save screen image |
const char *sSnapStatus(l3h_t h) | report saved connection status |
int aXX_BLOCK()SnapWaitOuput(int timeout) | wait for host output and save screen image |
const char *sStatus(l3h_t h) | report connection status |
int aXX_BLOCK()String(l3h_t h, const char *string) | insert string (simple macro facility) |
int aXX_BLOCK()SysReq(l3h_t h) | System Request AID |
int sTab(l3h_t h) | move cursor to next input field |
int sToggle(l3h_t h, option[,set|clear]) | toggle an option |
int sToggleInsert(l3h_t h) | toggle insert mode |
int sToggleReverse(l3h_t h) | toggle reverse-input mode |
int aXX_BLOCK()Transfer(l3h_t h, int argc, const char *argv[]) | file transfer |
int sUp(l3h_t h) | move cursor up |
*int aWait3270mode(int timeout) | wait for 3270 mode |
*int aWaitDisconnect(int timeout) | wait for host to disconnect |
*int aWaitInputField(int timeout) | wait for valid input field |
*int aWaitNVTMode(int timeout) | wait for NVT mode |
*int aWaitOutput(int timeout) | wait for more host output |
Because of the complexity and number of options for file transfer, the parameters to the aTransfer function take the unique form of option=value, and can appear in any order. The options are:
Option | Required? | Default | Other Values |
Direction | No | send | receive |
HostFile | Yes | ||
LocalFile | Yes | ||
Host | No | tso | vm |
Mode | No | ascii | binary |
Cr | No | remove | add, keep |
Exist | No | keep | replace, append |
Recfm | No | fixed, variable, undefined | |
Lrecl | No | ||
Blksize | No | ||
Allocation | No | tracks, cylinders, avblock | |
PrimarySpace | No | ||
SecondarySpace | No |
The option details are as follows.
\b | Left |
\f | Clear* |
\n | Enter* |
\pan | PA(n)* |
\pfnn | PF(nn)* |
\r | Newline |
\t | Tab |
\T | BackTab |
Note: The strings are in ASCII and converted to EBCDIC, so beware of inserting control codes.
There is also an alternate form of the aString function, aHexString, which is used to enter non-printing data. The argument to aHexString is a string of hexadecimal digits, two per character. A leading 0x or 0X is optional. In 3270 mode, the hexadecimal data represent EBCDIC characters, which are entered into the current field. In NVT mode, the hexadecimal data represent ASCII characters, which are sent directly to the host.
Resource | Default | Option | Purpose |
blankFill | False | -set blankFill | Blank Fill mode |
charset | bracket | -charset | EBCDIC character set |
charset.foo | Definition of character set foo | ||
dsTrace | False | -trace | Data stream tracing |
eof | ^D | NVT-mode EOF character | |
erase | ^H | NVT-mode erase character | |
extended | True | Use 3270 extended data stream | |
eventTrace | False | -trace | Event tracing |
ftCommand | ind$file | Host file transfer command | |
icrnl | False | Map CR to NL on NVT-mode input | |
inlcr | False | Map NL to CR in NVT-mode input | |
intr | ^C | NVT-mode interrupt character | |
kill | ^U | NVT-mode kill character | |
lineWrap | False | -set lineWrap | NVT line wrap mode |
lnext | ^V | NVT-mode lnext character | |
m3279 | (note 1) | -mono | 3279 (color) emulation |
monoCase | False | -set monoCase | Mono-case mode |
numericLock | False | Lock keyboard for numeric field error | |
oerrLock | False | Lock keyboard for input error | |
oversize | -oversize | Oversize screen dimensions | |
port | telnet | -port | Non-default TCP port |
quit | ^\ | NVT-mode quit character | |
rprnt | ^R | NVT-mode reprint character | |
secure | False | Disable "dangerous" options | |
termName | (note 2) | -tn | TELNET terminal type string |
traceDir | /tmp | Directory for trace files | |
traceFile | (note 3) | \-tracefile | File for trace output |
werase | ^W | NVT-mode word-erase character |
Note 1: m3279 defaults to False. It can be forced to True with the -model option.Note 2: The default terminal type string is constructed from the model number, color emulation, and extended data stream modes. E.g., a model 2 with color emulation and the extended data stream option would be sent as IBM-3279-2-E. Note also that when TN3270E mode is used, the terminal type is always sent as some type of 3278.
Note 3: The default trace file is x3trc.pid in the directory specified by the traceDir resource.
If more than one -xrm option is given for the same resource, the last one on the command line is used.
Modifications Copyright © 1993, 1994, 1995, 1996, 1997, 1999, 2000, 2001 by Paul Mattes.
Original X11 Port Copyright © 1990 by Jeff Sparkes.
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation.Copyright © 1989 by Georgia Tech Research Corporation, Atlanta, GA 30332.
All Rights Reserved. GTRC hereby grants public use of this software. Derivative works based on this software must incorporate this copyright notice.5250 Emulation Code Copyright © Minolta (Schweiz) AG, Beat Rubischon.