CP/M/CPM_CDROM.iso/simtel/sigm/vols200/vol200/vlib.hlp

Text File | 1994-07-13 | 11KB | 390 lines

Introduction - VLIB
Clear Screen - CLS
Erase to EOL - EREOL
Goto XY ------ AT/GOTOXY
Initialization VIDINIT/Z3VINIT
Print -------- GXYMSG/VPRINT
Standout Mode  STNDOUT/STNDEND
Term Init ---- TINIT/DINIT
:Introduction to VLIB

     VLI┬ i≤ ß librar∙ oµ utilit∙ routine≤ whicΦ i≤ designeΣ ì
t∩á suppor⌠ screeε manipulatioε unde≥ thσ ZCPR│ environment«  ì
Usinτá VLI┬ anΣ thσ ZCPR│ Termina∞ Capabilitie≤á Datßá File≤ ì
(Z3TCAP)¼á thσá ZCPR│á programme≥ caε creatσ codσá whicΦá i≤ ì
transportablσá betweeεá ZCPR│ system≤ tha⌠ caε adap⌠á itselµ ì
readil∙ t∩ ß variet∙ oµ moderε terminals«á  Fo≥ example¼ thσ ì
VFILE╥ filσ manipulatioε utilit∙ caε bσ moveΣ froφ onσ ZCPR│ ì
systeφ t∩ anothe≥ witΦ ß totall∙ differen⌠ terminal¼á anΣ a≤ ì
lonτá a≤ tha⌠ seconΣ systeφ i≤ installeΣ witΦ ßá Z3TCA╨á fo≥ ì
it≤á particula≥ terminal¼á VFILE╥ wil∞ continuσ t∩á functioε ì
exactl∙ a≤ i⌠ diΣ oε thσ origina∞ systeφ witΦ it≤ particula≥ ì
terminal.

     Al∞á VLI┬ routine≤ makσ usσ oµ thσ Z3TCA╨ entr∙á storeΣ ì
iε thσ 2nΣ halµ oµ thσ ZCPR│ Environmen⌠ Descriptor.

     Iε general¼ ß utilit∙ whicΦ use≤ VLI┬ i≤ alway≤ oµ thi≤ ì
general structure:


                     General VLIB Usage

          ...
          ext  tinit,dinit,z3vinit ;VLIB init routines
          ex⌠  ..«                 ;othe≥ VLIB routines
          ...
          lxi  h,z3env   ;get Z3 environment ptr
          call z3vinit   ;init Z3 environment and VLIB
          call tinit     ;init terminal for VLIB work
          ...
          <code containing VLIB routine calls>
          ...
          call dinit     ;deinit terminal when done
          jmp  0         ;warm boot (or return)
          ...


     A≤á illustrateΣá above¼á thσá genera∞ step≤á whicΦá arσ ì
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

:Clear Screen Routine

VLIB Routine: CLS

Function:
     Clear the terminal screen

Inputs: None
Outputs:
     A=0 and Zero Flag Set (Z) if function not available
     A=0FFH and NZ if clear screen sequence issued
Registers Affected: PSW
Side Effects: Screen is Cleared
Special Error Conditions: None
Examples of Use:
     ext  cls  ;reference routine
     ...
     CALL CLS  ;clear screen
     ...

:Erase to End of Line Routine

VLIB Routine: EREOL

Function:
     Erasσá thσ curren⌠ linσ froφ thσ curso≥ positioε t∩ thσ ì
end of the line

Inputs: None
Outputs:
     A=0 and Zero Flag Set (Z) if function not available
     A=0FFH 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
     ...

:Cursor Positioningè
VLIB Routine: AT

Function:
     Positioεá a⌠á ro≈ anΣ columε identifieΣ a⌠á thσá returε ì
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
Example of Use:

          ext  at        ;reference
          ...
          CALL AT
          DB   12,25     ;ROW 12, COLUMN 25
          ...


VLIB Routine: GOTOXY

Function:
     Positioεá thσá curso≥ a⌠ thσ ro≈ (containeΣ iεá H⌐á anΣ ì
columε (containeΣ iε L⌐ indicated¼á wherσ thσ homσá positioε ì
is H=1 and L=1 (upper left corner of screen)

Inputs: H=Row, L=Column
Outputs:
     A=0 and Zero Flag Set (Z) if function not available
     A=0FFH and NZ if cursor motion sequence issued
Registers Affected: PSW
Side Effects: Cursor is positioned
Special Error Conditions:
     I⌠ i≤ recommendeΣ tha⌠ thσ las⌠ columε oε thσ screeε i≤ ì
no⌠áá referenceΣáá witΦá GOTOX┘á sincσá man∙á screen≤áá wil∞ ì
automaticall∙á wra≡á arounΣ t∩ columε ▒ oµá thσá nex⌠á 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
     ...

:Initialization of VLIB

VLIB Routine: VIDINIT

Function:
     Se⌠á thσá pointe≥ t∩ thσ Z3TCA╨ entr∙ fo≥á thσá desireΣ ì
terminal

Inputs: HL contains the address of the Z3TCAP entry
Outputs: None
Registers Affected: None
Side Effects: Pointer VIDPTR is set
Special Error Conditions:
     Iε initializinτ VLI┬ routines¼ thσ programme≥ MUS╘ als∩ ì
se⌠á thσá globa∞á pointe≥á ENVPT╥á t∩á poin⌠á t∩á thσá ZCPR│ ì
Environmen⌠á Descripto≥á becausσ thσ dela∙ routine≤ iεá VLI┬ ì
usσá somσá Environmen⌠á Descripto≥á values¼á likσá processo≥ ì
speed«á  VIDINI╘á i≤á provideΣ iε additioεá t∩á forcinτá thσ ì
programme≥ t∩ se⌠ ENVPT╥ iε orde≥ t∩ givσ thσ programme≥ thσ ì
flexibilit∙ oµ usinτ ß Z3TCA╨ entr∙ whicΦ i≤ no⌠ thσ samσ a≤ ì
that provided in the ZCPR3 Environment Descriptor.

Examples of Use:

     ext  envptr,vidinit ;reference pointer and routine
     ...
     lxi  h,z3env   ;address of ZCPR3 Environment Descriptor
     shld envptr
     lxi  h,z3env+80H    ;address of Z3TCAP in descriptor
     call vidint
     ...


VLIB Routine: Z3VINIT

Function:
     Se⌠ thσ pointe≥ t∩ thσ ZCPR│ Environmen⌠ Descripto≥ anΣ ì
thσ followinτ Z3TCA╨ entry

Inputs: HL contains the address of the ZCPR3 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
     ...
     lxi  h,z3env   ;address of ZCPR3 Environment Descriptor
     call z3vinit
     ...

:Print Routines

VLIB Routine: GXYMSG

Function:
     Positioεá a⌠á thσá indicateΣá row/columεá anΣá prin⌠á ß ì
message¼á whicΦá ma∙á optionall∙ contaiε thσá standou⌠á modσ ì
begiεá characte≥ (1⌐ anΣ standou⌠ modσ enΣ characte≥ (2⌐á t∩ ì
invokσá standou⌠ modσ anΣ enΣ standou⌠ modσ iε thσ middlσ oµ ì
thσá message«á  Al∞á parameter≤ arσ passeΣ a≤ iεá thσá PRIN╘ ì
routinσ oµ SYSLI┬ a⌠ thσ returε address«  Thσ genera∞ synta° ì
of use is:

          ext  gxymsg         ;reference
          ...
          call gxymsg         ;call routine
          db   row,column     ;row and column numbers
          db   'message'      ;normal message text
          dΓ   1,'standou⌠ message',▓   ;standou⌠ message
          db   0              ;end of message indicator
          < code follows >

Inputs: None
Outputs: None
Registers Affected: None
Side Effects: Message is Printed at Coordinates
Special Error Conditions: None
Examples of Use:
          ext  gxymsg
          ...
          call gxymsg
          db   5,10      ;row 5, column 10
          db   'Hello '       ;"Hello " is printed normally
          db   1,'World',2    ;"World" is printed standout
          db   0
          ...



VLIB Routine: VPRINT

Function:
     Prin⌠á ßá message¼á whicΦá ma∙ optionall∙á contaiεá thσ ì
standou⌠á modσá begiε characte≥ (1⌐ anΣá standou⌠á modσá enΣ ì
characte≥á (2⌐ t∩ invokσ standou⌠ modσ anΣ enΣ standou⌠ modσ ì
iε thσ middlσ oµ thσ message«á  Al∞ parameter≤ arσ passeΣ a≤ ì
iε thσ PRIN╘ routinσ oµ SYSLI┬ a⌠ thσ returεá address«á  Thσ ì
genera∞ synta° oµ usσ is:

          ext  vprint         ;reference
          ...
          call vprint         ;call routine
          db   'message'      ;normal message text
          dΓ   1,'standou⌠ message',▓   ;standou⌠ 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
          ...
          call vprint
          db   'Hello '       ;"Hello " is printed normally
          db   1,'World',2    ;"World" is printed standout
          db   0
          ...

:Standout Mode

VLIB Routine: STNDOUT

Function:
     Begiε Standou⌠ Modσ - fo≥ somσ terminals¼á thi≤ wil∞ bσ ì
reverse video, and for others this will be dim

Inputs: None
Outputs:
     A=0 and Zero Flag Set (Z) if function not available
     A=0FFH and NZ if standout sequence issued
Registers Affected: PSW
Side Effects: Standout Mode is begun on terminal


Special Error Conditions:
     Iεá al∞á cases¼á a≤á par⌠á oµá thσá Z3TCA╨á definition¼ ì
enterinτá Standou⌠á Modσá anΣ leavinτ Standou⌠ Modσá d∩á no⌠ ì
causσ an∙ position≤ oε thσ screeε t∩ bσ occupied«  Curso≥ i≤ ì
NOT moved.
     I⌠á i≤ recommendeΣ tha⌠ extensivσ curso≥ motioε i≤á no⌠ ì
donσá betweeε STNDOUT/STNDEN─ call≤ (ie¼á don'⌠ usσá GOTOXY⌐ ì
sincσ thσ effect≤ oµ doinτ thi≤ arσ no⌠ generalizeΣ fo≥á al∞ ì
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 >


VLIB Routine: STNDEND

Function:
     Terminatσ Standou⌠ Modσ - resumσ norma∞ screeε display

Inputs: None
Outputs:
     A=0 and Zero Flag Set (Z) if function not available
     A=0FFH 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)

:Terminal Initialization and Deinitialization

VLIB Routine: TINIT

Function:
     Initializσ thσ user'≤ termina∞ fo≥ late≥ processinτá b∙ ì
VLIB routines

Inputs: None
Outputs: None
Registers Affected: None
Side Effects: Terminal may be reprogrammed
Special Error Conditions:
     TINIT¼á a≤ ß rule¼ shoulΣ bσ issueΣ righ⌠ afte≥ settinτ ì
u≡ thσ environmen⌠ pointer≤ anΣ beforσ an∙ oµ thσ othe≥ VLI┬ ì
routines are called.
     DINIT is the complement routine.


Examples of Use:

     ext  envptr,vidinit ;reference ptr and init routine
     ext  tinit,dinit    ;reference routines
     ...
     lxi  h,z3env        ;set up environment pointers
     shld envptr
     lxi  h,z3env+80H
     call vidinit
     call tinit          ;initialize terminal
     ...
     < body of code >
     ...
     call dinit          ;deinitialize terminal
     jmp  0              ;exit


VLIB 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)