lib3270 Manual Page

Contents

Name
Synopsis
Description
Basic Functions
Options
Hostname Syntax
Character Sets
NVT (ANSI) Mode
Toggles
Functions
File Transfer
Scripts
Passthru
Resources
See Also
Copyrights
Version

Name

lib3270 - IBM host access library

Synopsis

#include "lib3270.h"
cc ... -l3270

Description

lib3270 allows a C program to open a telnet connection to an IBM host, then allows the program to control the host login session. It is derived from x3270(1), an X-windows IBM 3270 emulator. It implements RFCs 2355 (TN3270E), 1576 (TN3270) and 1646 (LU name selection), and supports IND$FILE file transfer.

Basic Functions

lib3270 is controlled by several basic access functions:
int open_3270(unsigned long flags, const char **options, l3h_t *handle_ret)
Initializes an instance of lib3270. flags can include NON_BLOCKING, which causes certain functions to operate in an asynchronous manner. options is a NULL-terminated array of option strings (see OPTIONS below). Returns a handle for use by other lib3270 functions.
int close_3270(lib327h_t h)
Terminates an instance of lib3270.
int poll_3270(l3h_t h)
Perform any pending I/O operations (without blocking) and return the status of any pending function.
int wait_3270(l3h_t h)
Wait for any pending function to complete and return its status.
const char *result_3270(l3h_t h, int *rcode)
Return the result of the last 3270 function. Its return code is returned in rcode. If the last 3270 function succeeded, the result is whatever output it produced. If it failed, the result is an error message.
int selectvals_3270(l3h_t h, int *nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval **timeout, struct timeval *timebuf)
Used in non-blocking mode to return information about pending I/O and timeout operations. All of the parameters can already contain values and will be correctly modified; otherwise they should be initialized to zero. File descriptors for lib3270's pending I/O operations are OR'ed into readfs, writefds and exceptfds; nfds is modified if one of those file descriptors equals or exceeds its value. If there is a lib3270 timeout pending and timeout already points to a non-NULL value which is greater than what lib3270 requires, that value is updated. If there is a lib3270 timeout pending and timeout is NULL, then it will be set to point to timebuf, and timebuf will be set to the correct value.

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.

L_OK (0)
Success.
L_FAIL
Function failed.
L_BLOCKED
lib3270 is operating in non-blocking mode, and the function has not yet completed.
L_NESTED
A function is already pending, and a new function was attempted.
L_BADHANDLE
The handle (l3h_t) parameter is invalid.

3270 functions which return character strings cannot block, so they return a non-NULL string for success, and a NULL string for failure.

Options

lib3270's initialization function understands the following options:
-charset name
Specifies an EBCDIC host character set. See CHARACTER SETS below.
-clear toggle
Sets the initial value of toggle to false. The list of toggle names is under TOGGLES below.
-model name
The model of 3270 display to be emulated. The model name is in two parts, either of which may be omitted:

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.

Model Number
Columns
Rows
2
80
24
3
80
30
4
80
43
5
132
27

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.

-mono
Forces 3278 emulation.
-oversize colsxrows
Makes the screen larger than the default for the chosen model number. This option has effect only in combination with extended data stream support (controlled by the "lib3270.extended" resource), and only if the host supports the Query Reply structured field. The number of columns multiplied by the number of rows must not exceed 16383 (3fff hex), the limit of 14-bit 3270 buffer addressing.
-port n
Specifies a different TCP port to connect to. n can be a name from /etc/services like telnet, or a number. This option changes the default port number used for all connections. (The positional parameter affects only the initial connection.)
-set toggle
Sets the initial value of toggle to true. The list of toggle names is under TOGGLES below.
-tn name
Specifies the terminal name to be transmitted over the telnet connection. The default name is IBM-model_name-E, for example, IBM-3278-4-E.

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.

-trace
Turns on data stream and event tracing at startup. The default trace file name is /tmp/x3trc.process_id.
-tracefile file
Specifies a file to save data stream and event traces into, overriding the default of /tmp/x3trc.process_id.
-tracefilesize size
Places a limit on the size of a trace file. If this option is not specified, or is specified as 0 or none, the trace file will be unlimited. If specified, the trace file cannot already exist, and the (silently enforced) minimum size is 64 Kbytes. The value of size can have a K or M suffix, indicating kilobytes or megabytes respectively.
-xrm "lib3270.resource: value"
Sets the value of the named resource to value. Resources control less common lib3270 options, and are defined under RESOURCES below.

Hostname Syntax

The full syntax for host is:
[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 `:'.

Character Sets

The -charset option or the "lib3270.charset" resource controls the EBCDIC host character set used by lib3270. Available sets include:

Charset Name
Code Page
Display Character Sets
apl
37
3270cg-1a
belgian
500
3270cg-1a 3270-cg1 iso8859-1
bracket
37
3270cg-1a 3270-cg1 iso8859-1
brazilian
275
3270cg-1a 3270-cg1 iso8859-1
finnish
278
3270cg-1a 3270-cg1 iso8859-1
french
297
3270cg-1a 3270-cg1 iso8859-1
german
273
3270cg-1a 3270-cg1 iso8859-1
icelandic
871
3270cg-1a 3270-cg1 iso8859-1
iso-hebrew
424
iso8859-8
iso-turkish
1026
iso8859-9
italian
280
3270cg-1a 3270-cg1 iso8859-1
norwegian
277
3270cg-1a 3270-cg1 iso8859-1
russian
880
koi8-r
solvenian
870
iso8859-2
thai
838
iso8859-11 tis620.2529-0
uk
285
3270cg-1a 3270-cg1 iso8859-1
us-intl
37
3270cg-1a 3270-cg1 iso8859-1

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.

NVT (ANSI) Mode

Some hosts use an ASCII front-end to do initial login negotiation, then later switch to 3270 mode. lib3270 will emulate an ANSI X.64 terminal until the host places it in 3270 mode (telnet BINARY and SEND EOR modes, or TN3270E mode negotiation).

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

Toggles

lib3270 has a number of configurable modes which may be selected by the -set and -clear options.
monoCase
If set, lib3270 operates in uppercase-only mode.
blankFill
If set, lib3270 behaves in some un-3270-like ways. First, when a character is typed into a field, all nulls in the field to the left of that character are changed to blanks. This eliminates a common 3270 data-entry surprise. Second, in insert mode, trailing blanks in a field are treated like nulls, eliminating the annoying `lock-up' that often occurs when inserting into an field with (apparent) space at the end.
lineWrap
If set, the ANSI terminal emulator automatically assumes a NEWLINE character when it reaches the end of a line.

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.

Functions

lib3270 supports the following functions. Functions which begin with s are synchronous (they can never return L_BLOCKED in non-blocking mode). Functions which begin with a are asynchronous (in non-blocking mode, they may return L_BLOCKED).

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

File Transfer

The aTransfer function implements IND$FILE file transfer. This function requires that the IND$FILE program be installed on the IBM host, and that the 3270 cursor be located in a field that will accept a TSO or VM/CMS command.

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.

Direction
send (the default) to send a file to the host, receive to receive a file from the host.
HostFile
The name of the file on the host.
LocalFile
The name of the file on the local workstation.
Host
The type of host (which dictates the form of the IND$FILE command): tso (the default) or vm.
Mode
Use ascii (the default) for a text file, which will be translated between EBCDIC and ASCII as necessary. Use binary for non-text files.
Cr
Controls how Newline characters are handled when transferring Mode=ascii files. remove (the default) strips Newline characters in local files before transferring them to the host. add adds Newline characters to each host file record before transferring it to the local workstation. keep preserves Newline characters when transferring a local file to the host.
Exist
Controls what happens when the destination file already exists. keep (the default) preserves the file, causing the aTransfer function to fail. replace overwrites the destination file with the source file. append appends the source file to the destination file.
Recfm
Controls the record format of files created on the host. fixed creates a file with fixed-length records. variable creates a file with variable-length records. undefined creates a file with undefined-length records (TSO hosts only). The Lrecl option controls the record length or maximum record length for Recfm=fixed and Recfm=variable files, respectively.
Lrecl
Specifies the record length (or maximum record length) for files created on the host.
Blksize
Specifies the block size for files created on the host. (TSO hosts only.)
Allocation
Specifies the units for the TSO host PrimarySpace and SecondarySpace options: tracks, cylinders or avblock.
PrimarySpace
Primary allocation for a file created on a TSO host. The units are given by the Allocation option.
SecondarySpace
Secondary allocation for a file created on a TSO host. The units are given by the Allocation option.

Scripts

The aString Function
The simplest method for scripting is provided via the aString function. The arguments to aString are one or more double-quoted strings which are inserted directly as if typed. The C backslash conventions are honored as follows. (Entries marked * mean that after sending the AID code to the host, lib3270 will wait for the host to unlock the keyboard before further processing the string.)
\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.

Passthru

lib3270 supports the Sun telnet-passthru service provided by the in.telnet-gw server. This allows outbound telnet connections through a firewall machine. When a p: is prepended to a hostname, lib3270 acts much like the itelnet(1) command. It contacts the machine named internet-gateway at the port defined in /etc/services as telnet-passthru (which defaults to 3514). It then passes the requested hostname and port to the in.telnet-gw server.

Resources

Certain lib3270 options can be configured via resources. Resources are defined by -xrm options. The definitions are similar to X11 resources, and use a similar syntax. The resources available in lib3270 are:

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.

See Also

x3270(1), s3270(1), c3270(1), tcl3270(1), pr3287(1), telnet(1), tn3270(1)
Data Stream Programmer's Reference, IBM GA23-0059
Character Set Reference, IBM GA27-3831
RFC 1576, TN3270 Current Practices
RFC 1646, TN3270 Extensions for LUname and Printer Selection
RFC 2355, TN3270 Enhancements

Copyrights

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.

Version

lib3270 3.2.19
This HTML document and the accompanying troff document were generated with a set of write-only m4 macros and the powerful vi editor.
Last modified 18 June 2002.