Section IV
VLIB REFERENCE

ZCPR3: THE LIBRARIES

A Reference Manual
and
User's Guide
for
SYSLIB, Z3LIB, and VLIB

Written by
Richard Conn

Copyright 1986    Richard Conn

Thia Page Left Blank

ZCPR3: The Libraries VLIB

19. VLIB

CHAPTER OUTLINE

Clear Screen
CLS

Cursor Positioning
AT
GOTOXY

Erase to End of Line
EREOL

Initialization

VIDINIT
Z3VINIT

Print

GXYMSG
VPRINT

Standout Mode
STNDOUT
STNDEND

Terminal Initialization
TINIT
DINIT

19-1

ZCPR3: The Libraries VLIB VLIB

VLIB

VLIB is a library of utility routines which is designed to
support screen manipulation under the ZCPR3 environment.  Using
VLIB and the ZCPR3 Terminal Capabilities Data Files (Z3TCAP), the
ZCPR3 programmer can create code which is transportable between
ZCPR3 systems that can adapt itself readily to a variety of
modern terminals.   For example, the VFILER file manipulation
utility can be moved from one ZCPR3 system to another with a
totally different terminal, and as long as that second system is
installed with a Z3TCAP for its particular terminal, VFILER will
continue to function exactly as it did on the original system
with its particular terminal.

All VLIB routines make use of the Z3TCAP entry stored in the
2nd half of the ZCPR3 Environment Descriptor.

A utility which uses VLIB is always of this structure:

General VLIB Usage

ext  tinit,dinit,z3vinit ;VLIB init routines
ext  ...                 ;other VLIB routines

Ixi  h,z3env
call z3vinit
call tinit

get Z3 environment ptr

init Z3 environment and VLIB

init terminal for VLIB work

< code containing VLIB routine calls >

•  •  •

call dinit     ;deinit terminal when done
jmp  0         ;warm boot (or return)

As illustrated above, the general steps which are always
taken when using VLIB are as follows:

1.  Initialize Environment Pointers

- ENVPTR is ZCPR3 Environment Descriptor Addr

- VIDPTR sets Z3TCAP Entry Address

2.  Call Terminal Initialization Routine

- TINIT

3.  Call VLIB Routines as Desired

4.  Call Terminal Deinitialization Routine

- DINIT

19-2

ZCPR3: The Libraries VLIB VLIB

19.1. Clear Screen

Routine; CLS

Function;  Clear the terminal screen.

Inputs: None

Outputs:

A=0 and Zero Flag Set <Z) if function not available
A=OFFH and NZ if clear screen sequence issued

Registers Affected: PSW

Side Effects: Screen is Cleared

Special Error Conditions: None

Examples of Use:

ext  cis  ;reference routine

•  •  •

CALL CLS  ;clear screen

19.2. Cursor Positioning

Routine: AT

Function:  Position at row and column identified at the
return address on the CRT screen.  The general syntax of usage
is:

ext  at        ;reference

•  •  •

call at

db   row,column     ;coordinates

< code follows >

Inputs: None

Outputs: None

Registers Affected: None

Side Effects: None

Special Error Conditions: None

Examples of Use:

ext  at        ;reference

•  •  •

CALL AT
DB   12,25     ;ROW 12, COLUMN 25

•  •  •

Routine: GOTOXY

Function:  Position the cursor at the row (contained in H)
and column (contained in L) indicated, where the home position is
H=l and L=l (upper left corner of screen)

Inputs: H=Row, L=Column

Outputs:

A=0 and Zero Flag Set <Z) if function not available
A=OFFH and NZ if cursor motion sequence issued

Registers Affected: PSW

Side Effects: Cursor is positioned

19-3

ZCPR3: The Libraries VLIB VLIB

Special Error Conditions:

It is recommended that the last column on the screen is
not referenced with GOTOXY since many screens will automatically
wrap around to column 1 of the next line, possibly advancing the
screen image undesirably.

Examples of Use:

ext  gotoxy    ;reference routine

• • •

LXI  H,101H    ;position to row 1/col 1

CALL GOTOXY

• • •

MVI  H,24      ;position to row 24
MVI  L,79      ;position to column 79
CALL GOTOXY

19.3. Erase to End of Line

Routine: ERBOL

Function:  Erase the current line from the cursor position
to the end of the line.
Inputs: None
Outputs:

A=0 and Zero Flag Set (Z) if function not available

A=OFFH and NZ if ereol sequence issued
Registers Affected: PSW
Side Effects: Erase to End-of-Line occurs
Special Error Conditions: None
Examples of Use:

ext  ereol     ;reference routine

•  •  •

CALL EREOL     ;erase to end-of-line

19.4. Initialization

Routine: VIDINIT

Function:  Set the pointer to the Z3TCAP entry for the
desired terminal.

Inputs: HL contains the address of the Z3TCAP entry

Outputs: None

Registers Affected: None

Side Effects; Pointer VIDPTR is set

Special Error Conditions:

In initializing VLIB routines, the programmer MUST also
set the global pointer ENVPTR to point to the ZCPR3 Environment
Descriptor because the delay routines in VLIB use some
Environment Descriptor values, like processor speed. VIDINIT is
provided in addition to forcing the programmer to set ENVPTR in
order to give the programmer the flexibility of using a Z3TCAP
entry which is not the same as that provided in the ZCPR3
Environment Descriptor.

19-4

ZCPR3; The Libraries VLIB VLIB

Examples of Use:

ext  envptr,vidinit ;reference pointer and routine

•  •  •

Ixi  h,z3env   ;address of ZCPR3 Environment Descriptor
shid envptr

Ixi  h,z3env+80H    ;address of Z3TCAP in descriptor
call vidint

•  •  •

Routine: Z3VINIT

Function;   Set the pointer to the ZCPR3 Environment
Descriptor and the following Z3TCAP entry.

Inputs; HL contains the address of the Env Descriptor

Outputs: None

Registers Affected; None

Side Effects: Pointers ENVPTR and VIDPTR are set

Special Error Conditions:  None

Examples of Use:

ext  z3vinit ;reference pointer and routine

•  •  •

Ixi  h,z3env   ;address of ZCPR3 Environment Descriptor
call z3vinit

•  •  •

19.5. Print

Routine; GXYMSG

Function:  Position at the indicated row/column and print a
message, which may optionally contain the standout mode begin
character (1) and standout mode end character (2) to invoke
standout mode and end standout mode in the middle of the message.
All parameters are passed as in the PRINT routine of SYSLIB at
the return address.  The syntax of use is:

ext  gxymsg

•  •  •

call gxymsg

db   row, column

db   'message'

db   1,'standout

db   0

< code follows >

;reference

;call routine
;row and column numbers
;normal message text
message',2   ;standout message
;end of message indicator

Inputs: None

Outputs: None

Registers Affected: None

Side Effects: Message is Printed at Coordinates

Special Error Conditions: None

Examples of Use:

19-5

ZCPR3: The Libraries VLIB VLIB

ext  gxymsg

•  •  •

call gxyrosg

db   5,10      ;row 5, column 10

db   'Hello '       ;"Hello " is printed normally

db   1,'World',2    ;"World" is printed standout

db   0

Routine; VPRINT

Function:  Print a message, which may optionally contain the
standout mode begin character (1) and standout mode end character
(2) to invoke standout mode and end standout mode in the middle
of the message.  All parameters are passed as in the PRINT
routine of SYSLIB at the return address.  The general syntax of
use is:

ext  vprint         ;reference

•  •  •

call vprint         ;call routine

db   'message'      ;normal message text

db   1,'standout message',2   ;standout message

db   0              ;end of message indicator

< code follows >

Inputs: None

Outputs: None

Registers Affected: None

Side Effects: Message is Printed

Special Error Conditions: None

Examples of Use:

ext  vprint

• • •

cat 1 vprint

db   'Hello '       ;"Hello " is printed normally

db   1,'World',2    ;"World" is printed standout

db   0

19.6. Standout Mode

Routine; STNDOOT

Function:   Begin Standout Mode - for some terminals, this
will be reverse video, and for others this will be dim.
Inputs: None
Outputs:

A=0 and Zero Flag Set (Z) if function not available
A=OFFH and NZ if standout sequence issued
Registers Affected: PSW

Side Effects: Standout Mode is begun on terminal
Special Error Conditions:

In all cases, as part of the Z3TCAP definition,
entering Standout Mode and leaving Standout Mode do not cause any
positions on the screen to be occupied.  Cursor is NOT moved.

19-6

ZCPR3: The Libraries VLIB VLIB

It is recommended that extensive cursor motion is not done
between STNDOUT/STNDEND calls (ie, don't use GOTOXY) since the
effects of doing this are not generalized for all terminals and
may not be desirable in some cases.

Note: See STNDEND for the complement of this function.

Examples of Use:

•»

ext  stndout,stndend

• • •

call stndout

•  •  •

< all screen output is now in Standout Mode >

•  •  •

call stndend

•  •  •

< all screen output is back to normal >

Routine: STNDEND

Function:   Terminate Standout Mode - resume normal screen
display.

Inputs: None

Outputs:

A=0 and Zero Flag Set (Z) if function not available
A=OFFH and NZ if standend sequence issued

Registers Affected: PSW

Side Effects: None (see notes for STNDOUT)

Special Error Conditions: None (see notes for STNDOUT)

Examples of Use: (see notes for STNDOUT)

19.7. Terminal Initialization and Deinitialization

Routine: TINIT

Function:   Initialize the user's terminal for later
processing by VLIB routines.

Inputs: None

Outputs: None

Registers Affected: None

Side Effects: Terminal may be reprogrammed

Special Error Conditions:

TINIT should be issued right after setting up the
environment pointers and before any of the other VLIB routines
are called.

DINIT is the complement routine.

Examples of Use:

19-7

ZCPR3: The Libraries VLIB VLIB

ext  envptr,vidinit ;reference ptr and init routine

ext  tinit,dinit    ;reference routines

• • •

Ixi  h,z3env        ;set up environment pointers

shid envptr

Ixi  h,z3env+80H

call vidinit

call tinit          ;initialize terminal

•  •  •

< body of code >

•  •  •

call dinit          reinitialize terminal
jmp  0              ;exit

Routine: DINIT

Function:  Deinitialize the terminal.

Inputs: None

Outputs: None

Registers Affected: None

Side Effects: None

Special Error Conditions: (see notes on TINIT)

Examples of Use: (see notes on TINIT)

19-8