gsinit
Purpose
Initializes the GSL subroutines.
C Syntax
int gsinit_ (buffer, size, save_restore, f_grant, f_retract, fildes)
int *buffer, *size, *save_restore;
int (*f_grant) ( ), (*f_retract) ( );
int *fildes;
FORTRAN Syntax
INTEGER function gsinit (buffer, size, save_restore, f_grant, f_retract, fildes)
INTEGER buffer (*), size, save_restore, fildes
EXTERNAL f_grant, f_retract
Pascal Syntax
FUNCTION gsinit_ (
VAR buffer: ARRAY [0..k] of INTEGER;
VAR size, save_restore, f_grant, f_retract, fildes: INTEGER
): INTEGER [PUBLIC|;
Description
The gsinit subroutine initializes the GSL. It allocates
any private storage required, and sets attributes to the
default values where necessary. It also forces the
virtual terminal of the application to Monitor Mode and
sets up the signal processing routines for the SIGRETRACT
and SIGGRANT signals, and optionally, the SIGMSG signal.
Parameters
buffer Defines the Monitor Mode input ring
buffer to be used by the GSL input
functions. buffer must be word aligned
and at least 128 bytes long. For
output to a printer or plotter device,
set the buffer parameter to -1. (In C,
buffer is a pointer to an integer con-
taining the value -1. In Pascal, it is
a variable containing the value -1.)
size Defines the length of buffer in bytes.
Depending on the value of size, gsinit
performs the following actions:
size=0 The GSL ignores the buffer
parameter and does not
provide input support.
The application must
provide a means for
receiving input events and
can use the read system
call or set up its own
ring buffer mechanism.
The IBM 5081 Display
Adapter requires a ring
buffer for input events.
If you do not define a
buffer (that is, if size=0
and buffer is not
defined), the GSL defines
a buffer to be used only
by GSL for the IBM 5081
Display Adapter. If you
define a ring buffer after
this point, the IBM 5081
Display Adapter GSL will
not work.
size<128 The gsinit subroutine does
not initialize the GSL.
sizeY128 The GSL establishes the
virtual terminal linkage
to the input ring buffer
provided by the applica-
tion and provides input
support and sets up a
SIGMSG signal catcher.
save_restore Determines whether to save the display
frame buffer and adapter states.
If save_restore is non-zero, the GSL
saves the current contents of the
display frame buffer as well as the
current adapter state when the virtual
terminal must become inactive and
restores both the frame buffer contents
and adapter state when it becomes
active.
If save_restore is zero, the GSL saves
only the adapter state and assumes that
the application either saves the frame
buffer or reconstructs it in some
fashion.
f_grant Sets up processing of the SIGGRANT
signal. If f_grant is non-zero, it is
assumed to be the address of an appli-
cation supplied function, and the GSL
calls the function as part of the
SIGGRANT signal handling. If
save_restore is non-zero, the applica-
tion function is called before the
frame buffer is restored.
f_retract Sets up processing of the SIGRETRACT
signal. If f_retract is non-zero, it
is assumed to be the address of an
application supplied function, and the
GSL calls the function as part of the
SIGRETRACT signal handling.
fildes Determines where output is directed.
The output device is specified by one
of the following:
o The value -1, which specifies
standard output.
o A file descriptor returned by a
creat, open, dup, or fcntl system
call.
o A null-terminated character string
up to 11 characters long, which
names an environment variable
defining a printer or plotter
device. In this case, the value of
the buffer parameter must be -1.
(See -- Heading id 'gslhard'
unknown --.)
(In C, fildes is a pointer to a file
descriptor, an integer, or a character
string. In Pascal, it is a variable
containing one of these values.)
If the initialization process is unsuccessful, the
virtual terminal is not placed in Monitor Mode and invo-
cation of any other GSL routines will cause unpredictable
results.
For printers or plotters, if initialization is unsuc-
cessful, the application can either terminate or re-drive
the initialize function with a valid character string as
a means of correcting the problem.
For Pascal, the application must declare the arrays
passed as being fixed length and declare the routine as
accepting arrays of that length; that is, the k in the
routine declaration must be a constant.
Pascal cannot directly provide the address of a routine.
An assembler function may be used to derive the address
of a routine passed to the GSL.
The f_grant and f_retract routines supplied by the appli-
cation are called on the signal level and must return.
These application routines must not use either setjmp or
longjmp subroutines.
The GSL supports use of the sdb symbolic debugger by
redirection to a supplied file descriptor. If two
virtual terminals are open and the GSL application runs
on one, the application may get the file descriptor for
the second and supply that descriptor at GSL initializa-
tion. The GSL directs its output to the second virtual
terminal while sdb directs its output to the first;
either is activated in the standard manner.
The user routine called at SIGGRANT can be called before
gsinit returns to the application.
Return Value
GS_SUCC Successful.
GS_HBUS Cannot access hardware bus.
GS_ADPT Invalid display type.
GS_FONT Cannot access default font.
GS_RING Buffer too small.
GS_HDCP Invalid file descriptor for hard copy output.
GS_HDLK Unable to create lock file.
GS_HDIM Insufficient memory.
GS_HDDB Device is busy.
GS_HDNA Physical device not attached.
GS_HDMG Maximum number of graphics devices open.
GS_HDIF No system inter process communication buffers
left.
GS_HDSF The fork system call failed.
GS_HDGO Specified graphics device already open.
GS_HDGN Specified graphics device does not exist.
GS_HDGU Specified graphics device driver is unknown.
Related Information
In this book: -- Heading id 'gslhard' unknown --.