home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / progm / dpl.zip / DDPL.DOC < prev    next >
Text File  |  1988-07-13  |  34KB  |  846 lines
  1.           ================================
  2.             Doug's Programming Language
  3.           ================================
  4.  
  5.                   TABLE OF CONTENTS
  6.  
  7.  
  8.                1. What's needed
  9.                     Hardware required.
  10.                     Programs you must supply.
  11.                     Installing the code on a hard drive.
  12.                     Compiling the sample programs.
  13.  
  14.                2. Basic program structure
  15.  
  16.                3. Data declarations
  17.                     Predefined global variables
  18.                     DEFINE declaration
  19.                     ENDREC declaration
  20.                     FILE declaration
  21.                     INTEGER declaration
  22.                     RECORD declaration
  23.                     SET declaration
  24.                     STRING declaration
  25.  
  26.                4. Executable Instructions
  27.                     CURSOR int,int
  28.                     CALL routine param-1 param-2 param-3 param-4
  29.                     CLOSE file
  30.                     DECODE string,integer
  31.                     ENCODE integer,string
  32.                     GOTO addr
  33.                     HSTOI integer,string
  34.                     IF...
  35.                     INKEY str,WAIT
  36.                     ITOBS string,integer,length
  37.                     ITOHS string,integer
  38.                     MATH EXPRESSIONS
  39.                     NOTE file,dd
  40.                     OPEN INPUT, file
  41.                     POINT file,dd
  42.                     READ file,string,length
  43.                     READB file,record
  44.                     RETURN
  45.                     STOP
  46.                     STRING CONCATENATION
  47.                     WRITE file,string
  48.                     WRITEB file,record
  49.  
  50.                5. Bibliography
  51.  
  52.  
  53. MS  DOS  and  Macro  Assembler,  aka,  MASM,  are  trademarks  of 
  54. Microsoft corporation.
  55.  
  56. Doug's Programming Language  -- DPL, Version 2.22
  57. Copyright (c) 1988 Douglas S. Cody, All rights reserved.
  58.  
  59.  
  60. .pa
  61.                     W h a t 's   N e e d e d
  62.  
  63.  
  64. Hardware Required.
  65.  
  66.      The minimal system configurable recommended to use DPL is:
  67.  
  68.           IBM PC or Compatible w/256k ram.
  69.           MS, PC DOS 2.0 or higher.
  70.           2 floppy disk drives.
  71.           Monochrome or CGA video adapter & monitor.
  72.  
  73.      The optimal system configurable recommended to use DPL is:
  74.  
  75.           IBM PC or Compatible w/640k ram.
  76.           MS, PC DOS 2.0 or higher.
  77.           1 floppy disk drive and a hard drive of
  78.           ten megabytes, or higher.
  79.           Monochrome, CGA, EGA video adapter & monitor.
  80.  
  81.  
  82.  
  83. Programs You Must Supply.
  84.  
  85.      In order to program,  assemble,  and run programs written in 
  86. DPL, the following programs must be made available:
  87.  
  88.      Microsoft MASM, MAKE, LINK, and LIB, versions 3.0
  89.      through 5.0.
  90.  
  91.      These  programs will have to be in the current directory  or 
  92. in the "PATH". See your DOS manual for setting "PATH"s.
  93.  
  94.  
  95.  
  96. Installing the Code on a Hard Drive.
  97.  
  98.      The DPL release diskette contains two batch files for moving 
  99. the  whole release to a target diskette or hard drive.  The first 
  100. batch file is called,  "MOVE.BAT".  It will copy all the core DPL 
  101. routines  and  support files to a given  drive\path.  The  second 
  102. batch  file is called,  "MOVEAPP.BAT",  and it contains  all  the 
  103. sample application routines,  programs,  and support files.  Each 
  104. batch file is invoked like the following example:
  105.  
  106.           C:\DPL>MOVE A:
  107.           C:\DPL>MOVEAPP A:
  108.  
  109.      The  parameter  following the batch file name indicates  the 
  110. target [drive][path] that the will receive the DPL files.
  111.  
  112. To create a backup of the release from drive A: to drive B:
  113.  
  114.      1. Install a blank, formatted diskette in drive B:
  115.      2. Install the DPL release diskette in drive A:
  116.      3. At the DOS prompt, type "A:" and the ENTER key.
  117.      4. Type "MOVE B:" and the ENTER key. All the core
  118.           routines, libraries & support files will be copied.
  119.      5. Type "MOVEAPP B:" and the ENTER key. All the application
  120.           routines, programs & support file will be copied.
  121.  
  122. To copy the release from drive A: to the hard drive, C:.
  123.  
  124.      1. If the current disk is not drive C, then type "C:"
  125.           and the ENTER key.
  126.      2. If the current disk is drive C, then type "CD\"
  127.           and the enter key.
  128.      3. Type "MKDIR DPL" and the ENTER key.
  129.      4. Type "CD DPL" and the ENTER key.
  130.      5. Install the DPL release diskette in drive A:
  131.      6. Type "A:" and the ENTER key.
  132.      7. Type "MOVE C:" and the ENTER key. All the core
  133.           routines, libraries & support files will be copied.
  134.      8. Type "MOVEAPP C:" and the ENTER key. All the application
  135.           routines, programs & support file will be copied.
  136.  
  137.  
  138.  
  139. Compiling the Sample Programs.
  140.  
  141. U S I N G   F L O P P Y   D I S K S
  142.  
  143.      For those of you using only two floppy disks, you'll want to 
  144. create  a special development diskette containing only the  files 
  145. needed to develop code.  The batch file named, "MOVEDEV.BAT" will 
  146. copy those files to a target drive. Follow the instructions below 
  147. to create this special disk:
  148.  
  149.      1. Install the DPL release diskette in drive A:
  150.      2. Install a blank, formatted diskette in drive B: 
  151.      3. At the DOS prompt, type "A:" and the ENTER key.
  152.      4. Type "MOVEDEV B:" and the enter key. All the required
  153.           files will be copied to this diskette.
  154.      5. Copy any DPL source files, such as, LIST.D, to drive B:
  155.  
  156.      Once  the development diskette is finished,  insert it  into 
  157. drive  A:.  Place  the diskette contain  Microsoft's  MASM.EXE  & 
  158. LINK.EXE into drive B:.  At the DOS prompt,  type "PATH=B:\;" and 
  159. the return key. This allows the Microsoft software to be found by 
  160. DOS  when  attempting to compile the DPL programs.  You  are  now 
  161. ready to compile some code.  The DPL sample program, "LIST.D" has 
  162. been  copied to the development diskette to allow you to practice 
  163. compiling.  To compile this program, type, "D LIST" and the ENTER 
  164. key. The  batch  file,   "D.BAT"  will  invoke  the  DPL  prepass 
  165. compiler, MASM, then LINK.
  166.      Once the compile is done, the DOS prompt will return.
  167.  
  168.  
  169.  
  170.  
  171.  
  172. U S I N G   H A R D   D R I V E
  173.  
  174.      If  you  are  using a hard disk drive,  you're in  the  best 
  175. development environment. This allows you to store all DPL code in 
  176. one  subdirectory,  and  all  the Microsoft  code  in  it's  sub-
  177. directory.  Place the path to the Microsoft software in the envi-
  178. ronment  PATH  by typing "PATH=\[MASM PATH]" at the  DOS  prompt. 
  179. Once this is done,  enter the DPL subdirectory,  and you're ready 
  180. to  work.  Assuming all the code has been installed in this  sub-
  181. directory,  type,  "D  LIST" and the ENTER key.  The batch  file, 
  182. "D.BAT"  will invoke the DPL prepass compiler,  MASM,  then LINK. 
  183.      Once the compile is done, the DOS prompt will return.
  184. .pa
  185.           B a s i c   P r o g r a m   S t r u c t u r e 
  186.  
  187. DPL is a macro language using high level language syntax for it's 
  188. instructions.  It does not limit the programmer from using native 
  189. 8088   code,   but  makes  programming  easier  by  automatically 
  190. declaring  segments and the program entrypoint.  Comments may  be 
  191. declared  in standard 8088 fashion by placing a semi-colon to the 
  192. left of the comment's body of text.  The basic program  structure 
  193. is as follows:
  194.  
  195.      PROG   NAME
  196.      ;
  197.      ; data goes here
  198.      ;
  199.      BEGIN  NAME
  200.      ;
  201.      ; code goes here
  202.      ;
  203.      ENDPGM NAME
  204.  
  205.      The keyword "PROG" declares the beginning of the program and 
  206. opens up the data segment.  The data segment will continue  until 
  207. the  keyword "BEGIN" is encountered.  Once "BEGIN" is found,  the 
  208. data segment is ended and the code segment will begin.  The  code 
  209. segment will be ended when the keyword "ENDPGM" is encountered at 
  210. the  end  of the source file.  In between the data and code  seg-
  211. ments, the stack segment is declared using a 256 word stack.
  212.      This main procedure is declared as a "FAR" procedure and  is 
  213. the entrypoint for the program.  Another valid way of declaring a 
  214. program  is using the keyword,  "SUBPGM" in lieu of "PROG".  This 
  215. will  give  the  program a public name as  well  as  declare  the 
  216. entrypoint to be a NEAR procedure.
  217.      The  NAME  of  the  program can be any  name,  but  must  be 
  218. declared  three times in the program.  The NAME declaration  must 
  219. follow the keywords, PROG, SUBPGM, BEGIN, and ENDPGM.
  220.      The  following  are two examples of  the  shortest  programs 
  221. written in DPL:
  222.  
  223.      Example #1          :    Example #2
  224.                          :
  225.      PROG      NAME      :    SUBPGM    NAME
  226.      ;                   :    ;
  227.      BEGIN     NAME      :    BEGIN     NAME
  228.      ;                   :    ;
  229.      ENDPGM    NAME      :    ENDPGM    NAME
  230.  
  231.     Since  DPL controls the segment declarations,  the program is 
  232. limited to 64k of code,  64k of data,  and 64k of stack  segment. 
  233. Other segments may be declared, but will be nested depending upon 
  234. location.  If  a segment is declared within the boundaries of the 
  235. "PROG/SUBPGM" and "BEGIN" statement, it will be nested within the 
  236. data segment.  Likewise,  if the segment is declared between  the 
  237. "BEGIN" and "ENDPGM" statement, it will be nested within the code 
  238. segment.
  239. .PA
  240.                D a t a   D e c l a r a t i o n s
  241.  
  242.      DPL  supports  simple data types,  but does  not  limit  the 
  243. programmer  from  building  other types.  The  basic  data  types 
  244. supported  are  16 bit integers and ASCIIZ strings.  The  16  bit 
  245. integers  are considered to be signed integers and therefore will 
  246. be manipulated appropriately. Files are supported which allow the 
  247. program  to address any disk file or logical device,  such as the 
  248. keyboard or screen.
  249.  
  250.  
  251. Predefined Global Variables
  252.  
  253.      DPL declares certain common variables for the programmer. As 
  254. of  this  revision,  the following  variables  are  automatically 
  255. declared:
  256.  
  257.      SET       STATUS,00      ; 16 bit integer which contains the 
  258.                               ; return result of various reads
  259.                               ; and writes.
  260.      SET       ZERO,00        ; A integer containing a zero value.
  261.      DEFINE    BEEP,07        ; ASCII Bell alarm (^G)
  262.      DEFINE    EJECT,12       ; ASCII Form Feed (^L)
  263.      SET       @DPLVER        ; Current version of DPL support
  264.                               ; routines
  265.      VIDPAGE   DB   ?         ; Current active video page
  266.      CRTFLAG   DB   ?         ; A byte indicating which video
  267.                               ; adapter is installed:
  268.                               ;   Monochrome    =  00
  269.                               ;   CGA card      =  01
  270.                               ;   EGA Mono emul =  02
  271.                               ;   EGA CGA emul  =  03.
  272.                               ; Bit 0 = Monochrome(0),CGA(1)
  273.                               ; Bit 1 = EGA(1)
  274.                               ; Bit 2 = VGA(not implemented yet)
  275.  
  276.    The  keyword,  "STATUS",  is  maintained by DPL to return  the 
  277. result  of any attempted read or write using DOS.  The  following 
  278. error codes are returned in STATUS from IO:
  279.  
  280. 0 = All okay                        10 = Invalid environment
  281. 1 = End of File encountered         11 = Invalid format
  282. 2 = File not found                  12 = Invalid access code
  283. 3 = Path not found                  13 = Invalid data
  284. 4 = No handle available, all used   14 = not used
  285. 5 = Access denied                   15 = Invalid drive specified
  286. 6 = invalid handle                  16 = Attempt to remove
  287. 7 = Memory control block destroyed       directory
  288. 8 = Insufficient memory             17 = Not same device
  289. 9 = Invalid memory block address    18 = No more files to be   
  290.                                          found                 
  291.  
  292. If  you have not noticed,  all the return codes,  except #1,  are 
  293. standard  DOS return codes.  Code #1 serves a  dual  purpose.  In 
  294. reads  and writes,  this value would indicate an EOF.  In opening 
  295. and  closing files,  it retains its original DOS  meaning.  Since 
  296. STATUS  is  just a 16 bit integer,  it may also be  used  by  the 
  297. programmer, for example, to hold a return code from a subroutine.
  298.  
  299.  
  300. D E F I N E  --  pre-initialized string declaration
  301.  
  302.      DEFINE    msg0,'This is the first message declared'
  303.      DEFINE    BEEP,07
  304.      DEFINE    ESC_SEQ,<1BH,'[31;40m'>   ; ANSI.SYS ESC sequence
  305.  
  306.    The  data  declaration,  "DEFINE"  allows  the  programmer  to 
  307. declare a string with a pre-initialized value.  This string  will 
  308. have it's maximum length determined by the length of the message. 
  309. The  second example above shows how to declare a one byte  string 
  310. using an ASCII control character value.  The length of the string 
  311. will  be  the data length + 1.  The  DEFINE  macro  automatically 
  312. provides a null byte as a string terminator.  This, and all other 
  313. data  declarations,  must  precede  the  "BEGIN"  statement.  The 
  314. maximum  length is determined by MASM's limitations.
  315.  
  316.  
  317. E N D R E C  --  End of record marker
  318.  
  319.           RECORD recname,length
  320.             STRING strname,length
  321.             INTEGER num
  322.           ENDREC recname
  323.  
  324.      The ENDREC declaration marks the end of the data record.  It 
  325. is  used  in  conjunction  with  the  RECORD  declaration.   This 
  326. statement  must  always be used to terminate a record  to  insure 
  327. correct memory allocation for the entire record.  This,  and  all 
  328. other data declarations, must precede the "BEGIN" statement.
  329.  
  330.  
  331. F I L E  --  Define a file device
  332.  
  333.      FILE     CONSL,     'CON'
  334.      FILE     PRT,       'LPT1',       A
  335.      FILE     AFILE,     'WORK.DAT',   A,   BUFFA
  336.      FILE     DSKFIL,    'WORK.DAT',   B
  337.      FILE     BFILE,     'WORK.DAT',   B,   BUFFB
  338.      FILE     RNDFIL,    'WORK.DAT',   R,   RKEY
  339.  
  340.      BUFFER    BUFFA,512
  341.      BUFFER    BUFFB,512
  342.      INTEGER   RKEY
  343.  
  344.    The  file declaration sets up a file declaration for accessing 
  345. DOS devices.  The declaration comes in five parts: 1) the keyword 
  346. FILE,  2)  the  internal  name of the device to be  used  by  the 
  347. program, 3) the external ASCIIZ string name given to DOS when the 
  348. file  is  opened,  4)  the  device class,  and 5)  a  buffer  for 
  349. sequential files,  or record KEY for random files.  The different 
  350. parts  are separated by commas.  The device class  indicates  the 
  351. type of data expected to be written or read from the device/file. 
  352. The  four  classes are "A" for ASCII,  "B" for  binary,  "R"  for 
  353. random access, and default for character devices (default assumes 
  354. variable length ASCII). The files classes, "A", "B", and default, 
  355. are   sequential   access  files.   Buffers  of  256  bytes   are 
  356. automatically declared for "A" and "B" file types. The programmer 
  357. may  declare different buffers for file classes "A" and  "B",  as 
  358. seen  in  the  above examples for "AFILE" and  "BFILE".  This  is 
  359. useful,  for  example  to speedup disk I/O  by  declaring  larger 
  360. buffers, thus requesting fewer reads from DOS.
  361.      NOTE!!!  The buffer size represents the largest single piece 
  362. of data which may be read from the file;  therefore,  in order to 
  363. read strings or records over 256 bytes in length,  the programmer 
  364. MUST  provide a buffer at least the size of the largest string or 
  365. record to be read from that file.
  366.      Random  access files have a KEY declaration.  The key  is  a 
  367. name of an integer to be used in record location calculations. To 
  368. access  a given record in a random file,  put the record location 
  369. number  into  the  key then read or write to the  file.  The  key 
  370. number  is similar in functionality to an  array's  subscript.  A 
  371. good  perspective  of a random file is to view it as an array  of 
  372. records,  where  the  key  is the subscript  to  the  array.  The 
  373. following  code segment shows how to read the 5th record  from  a 
  374. file:
  375.  
  376.      ;---------------< DATA VARIABLES >----------------
  377.  
  378.      FILE RFILE,'DATA.FIL',R,RKEY
  379.      INTEGER RKEY
  380.      ;
  381.      RECORD RREC,13
  382.        STRING STR,8
  383.        INTEGER NUM
  384.      ENDREC RREC
  385.  
  386.      ;---------------< CODE EXECUTION >----------------
  387.  
  388.      RKEY = 5
  389.      READB RFILE,RREC
  390.      
  391.      ;-------------< END CODE EXECUTION >--------------
  392.  
  393. The subscript to the file,  RKEY,  is set to the value of 5.  The 
  394. read or write can then be attempted by the program.
  395.  
  396.  
  397. I N T E G E R  --  16 bit integer declaration
  398.  
  399.      INTEGER num0
  400.  
  401.    The  integer  declaration  sets up a 16 bit word in  the  data 
  402. segment without a predefined value.  It is initialized to zero by 
  403. the macro statement.  This, and all other data declarations, must 
  404. precede the "BEGIN" statement.
  405.  
  406.  
  407. R E C O R D  --  File record declaration
  408.  
  409.           RECORD recname,length
  410.             STRING strname,length
  411.             INTEGER num
  412.           ENDREC recname
  413.  
  414.      This  declaration identifies the "recname" as the  beginning 
  415. of a data record. The above example shows how to declare a record 
  416. with  one  string  element and one integer  element.  The  ENDREC 
  417. statement must be added to terminate the record declaration.  See 
  418. the section on ENDREC. The length given in the RECORD declaration 
  419. is  the total length of all variable elements within the  record. 
  420. STRING  lengths  are  always are 1 greater  than  there  declared 
  421. length.  INTEGERS  are two bytes in length.  RECORDs declarations 
  422. may not be nested.  This,  and all other data declarations,  must 
  423. precede   the  "BEGIN"  statement.   See  the  section  on   FILE 
  424. declarations for more on record size limitations.
  425.  
  426.  
  427. S E T  --  16 bit integer declaration
  428.  
  429.      SET     ONE,1
  430.      SET     X99,99
  431.  
  432.    The  SET declaration sets up a signed 16 bit word with a  pre-
  433. defined value. It is identical to the INTEGER declaration, except 
  434. the programmer supplies an initial value to the word.  This,  and 
  435. all other data declarations, must precede the "BEGIN" statement.
  436.  
  437.  
  438. S T R I N G  -- Undefined string declaration
  439.  
  440.      STRING    name,length
  441.      STRING    wor_string,132
  442.  
  443.    The  STRING declaration allows the operator to declare a  null 
  444. string,  X  number of bytes in length.  The total length  of  the 
  445. string is the length + 1.  This, and all other data declarations, 
  446. must  precede  the "BEGIN" statement.  The maximum length may  be 
  447. up to 64k,  but remember,  DPL only provides ONE data segment  of 
  448. up  to  64k;  therefore,  such  a string would  fill  the  entire 
  449. segment.  See the section on FILE declarations for more on string 
  450. lengths.
  451. .pa
  452.          E X E C U T A B L E   I N S T R U C T I O N S
  453.  
  454.  
  455. C U R S O R  --  Move the video cursor.
  456.  
  457.      CURSOR     1,5
  458.      CURSOR     1,int
  459.      CURSOR     int,int
  460.      CURSOR     row,col
  461.  
  462.    This instruction moves the video cursor to the X/Y  coordinate 
  463. given  by the parameters.  The parameters may be either a numeric 
  464. literal or integer in any combination.  The valid rows are 0 thru 
  465. 24.  The valid columns are 0 thru 79. By moving the cursor out of 
  466. the valid ranges effectively makes the cursor disappear.
  467.  
  468.  
  469. C A L L  -- DPL call with parameter passing in registers.
  470.  
  471.      CALL     routine param-1 param-2 param-3 param-4
  472.      CALL     CALC 05 NUM
  473.  
  474.      The  DPL  pre-pass compiler examines each CALL statement  in 
  475. the source file looking for parameter passing to the  subroutine. 
  476. Parameters may be listed to the right of the subroutine name with 
  477. spaces  between  each one.  The parameters passed are  placed  in 
  478. registers  AX,BX,CX,DX  respectively.  1  - 4 parameters  may  be 
  479. passed to the subroutine.  NOTE:  Parameter passing is limited to 
  480. passing the ADDRESS of the variable,  NOT the actual value of the 
  481. variable.  This  differs with some common programming  languages, 
  482. such as C and PASCAL.  Since DPL does not maintain tight  control 
  483. over  variable  declarations,  it  does not know  the  difference 
  484. between  string  variable  names  and  integer  variable   names; 
  485. therefore,  it  applies a blanket rule of passing addresses only. 
  486. Literal   values  are  the  exception  and  are  passed  to   the 
  487. subroutine.  The  literal  values are limited  to  an  expression 
  488. resulting in a 16 bit value.
  489.  
  490.  
  491. C L O S E  -- Close a file.
  492.  
  493.      CLOSE     file
  494.  
  495.   This function closes a previously opened file.  If the file was 
  496. opened for output,  and end of file mark is written and the  file 
  497. is closed. All pertinent data is then entered into the directory.  
  498. If the file was opened for input, the file will be closed with no 
  499. changes to the directory.  Once a file is closed,  no more access 
  500. will  be allowed until it is reopened.  The appropriate DOS error 
  501. code will returned in STATUS.
  502.  
  503. .pa
  504. D E C O D E  --  Convert decimal ASCIIZ string to signed binary
  505.                  integer format.
  506.  
  507.      DECODE     integer,string
  508.  
  509.    DECODE  will convert a numeric ASCII string into a  signed  16 
  510. bit  integer  value.  The  value will be stored in  the  provided 
  511. integer.  The conversion will be made from left to right and will 
  512. continue  until a non numeric ASCII character or end of  line  is 
  513. encountered. Valid numeric ASCII characters fall within the range 
  514. of '0' - '9'.  A negative sign is allowed to the right or left of 
  515. the numbers. If a non-numeric value is encountered, A STATUS of 1 
  516. will be returned and the integer will be set to zero.
  517.  
  518.  
  519. E N C O D E  -- Convert signed binary integer to ASCIIZ
  520.                 decimal string.
  521.  
  522.      ENCODE     string,integer
  523.  
  524.    This  instruction  will convert a signed 16 bit value into  an 
  525. ASCIIZ string representation. The maximum length of the converted 
  526. string can be 6 characters,  therefore; the target string must be 
  527. a  minimum of 6 characters in order to protect against corrupting 
  528. memory  following the string.  The actual decimal  representation 
  529. created  by ENCODE may be less than 6 characters in  length.  Any 
  530. value over 32767 will be considered negative.
  531.   
  532.  
  533. G O T O  -- Unconditional jump.
  534.  
  535.      GOTO     addr
  536.  
  537.    The  GOTO command is converted into an 8088 'JMP' instruction. 
  538. The  range of the jump will be intra-segment,  unless the  target 
  539. address is a FAR type.  There will not be any check to see if the 
  540. target  address  can be reached by a short  jump.  This  form  of 
  541. optimization will normally be done by the assembler.
  542.  
  543.  
  544. H S T O I  -- Hex string to integer conversion.
  545.  
  546.      HSTOI     integer,string
  547.  
  548.    This  instruction will convert a HEX string into a  signed  16 
  549. bit binary value.  The conversion will operate from left to right 
  550. and  will end when a non-hex character ("0"-"9",  or "a"-"f")  or 
  551. end of line is encountered.
  552.  
  553.  
  554. I F  -- Conditional jump support for byte, word, or
  555.         string comparisons.
  556.  
  557.      IF BYTE   addr EQ addr GOTO addr
  558.      IF BYTE   addr LT addr CALL addr param param param param
  559.      IF BYTE   addr EQ addr RETURN
  560.      IF WORD   addr LE addr GOTO addr
  561.      IF WORD   addr NE addr CALL addr param param
  562.      IF WORD   addr EQ addr RETURN
  563.      IF STRING addr EQ addr GOTO addr
  564.      IF STRING addr NE addr CALL addr param param param param
  565.      IF STRING addr EQ addr RETURN
  566.  
  567.   The  DPL  IF statement gives the programmer the  capability  to 
  568. make complex comparison with ease.  The IF statements cover every 
  569. type of comparison and condition. A true result to the comparison 
  570. always  results in a change to the program counter.  The instruc-
  571. tion following the  comparison,  GOTO,  CALL,  or RETURN are  all 
  572. standard  DPL instructions.  See each section for details on  the 
  573. syntax of each of the instructions.
  574.   The  IF  statements allow a full range of tests to be made  for 
  575. integer  comparisons.  String comparisons are limited to "EQ"  or 
  576. "NE" tests. The following is a explanation of each comparison:
  577.  
  578.      NE - Not equal to
  579.      LT - Less than
  580.      LE - Less than or equal to
  581.      EQ - Equal to
  582.      GE - Greater than or equal to
  583.      GT - Greater than
  584.  
  585.  
  586. I N K E Y  --  Scan the keyboard for one character
  587.  
  588.      INKEY
  589.      INKEY     str
  590.      INKEY     str,WAIT
  591.      INKEY     ,WAIT
  592.  
  593.    This  instructions  uses the BIOS keyboard  interrupt  16H  to 
  594. retrieve  a typed key.  As the above examples  show,  the  target 
  595. string  is  optional.  The  returned value is stored  in  the  AX 
  596. register  upon  return from the BIOS call.
  597.      The  first  two examples will not stop the execution of  the 
  598. program,  whereas;  the  last two examples wait for a key  to  be 
  599. typed. The DPL keyword STATUS will be set to 1 if a key is found, 
  600. otherwise;  it  will  be set to 0.  The target string must  be  a 
  601. minimum of 2 bytes long. Two bytes will be returned from the BIOS 
  602. and  stored  in the string.  The first byte will be the  "normal" 
  603. key, such as the letter "A". In this case the second byte will be 
  604. reported as a binary zero.  The second byte reported is the  scan 
  605. code.  If  the  key was a function key,  the first byte  will  be 
  606. binary zero, and the second byte will be the scan code.
  607.  
  608. .pa
  609. I T O B S  --  Convert binary integer to Binary string 
  610.  
  611.      ITOBS     string,integer,length
  612.      ITOBS     string,0255h,8
  613.  
  614.    This  command converts a 16 bit integer into a string of  "0"s 
  615. and "1"s for a binary representation. The length of the string is 
  616. determined by the length declaration.  As an example, if just the 
  617. least  significant  byte of the 16 bit word is to  be  converted, 
  618. just give the instruction an 8 byte long length.  The integer may 
  619. be a address or a literal value.
  620.  
  621.  
  622. I T O H S  --  Convert binary integer to ASCII hex string
  623.  
  624.      ITOHS     string,integer
  625.      ITOHS     string,0256
  626.  
  627.     This  command will take a 16 bit integer value an create a  4 
  628. byte  hex string.  The target string must be a minimum of 4 bytes 
  629. in length, or a memory overrun will occur.
  630.  
  631.  
  632. M A T H -- DPL math routines for arithmetic and Boolean
  633.            expression evaluation
  634.  
  635.      result = int * 05 + int / 2 - 3 SHL 2 MOD 256
  636.  
  637.    DPL provides for signed 16 bit mathematical expressions with a 
  638. simple left to right evaluation.  The length of the expression is 
  639. limited  to  a maximum string of 132  characters.  The  following 
  640. mathematical operations are valid:
  641.  
  642.           *    Multiplication      /    Division
  643.           +    Addition            -    Subtraction
  644.           AND  Logical And         OR   Logical OR
  645.           XOR  Exclusive OR        SHL  Shift left
  646.           SHR  Shift Right         MOD  Remainder
  647.  
  648.  
  649. N O T E  -- Note the current file pointer.
  650.  
  651.      NOTE     file,dd
  652.  
  653.    This  instruction retrieves the current file pointer from  the 
  654. specified  file and stores it in the specified 32 bit  long  word 
  655. storage.  This  instruction is used in conjunction with the POINT 
  656. instruction  to  create  a  limited form  of  random  access  for 
  657. sequential  disk  files.   By  "NOTE"ing  a  file,   then  later, 
  658. "POINT"ing to it, data may be reread or rewritten.
  659.  
  660. .pa
  661. O P E N  -- Open a file
  662.  
  663.      OPEN     INPUT, file
  664.      OPEN     OUTPUT, file
  665.      OPEN     IO, file
  666.  
  667.    DPL  uses the DOS file handle method of file control.  When  a 
  668. file  is opened,  DOS returns a handle which will  be  associated 
  669. with that file until it is CLOSED.  The allowable modes of access 
  670. for files are INPUT, OUTPUT, or, IO.
  671.    In order to access any of the computers devices,  using a file 
  672. is the easiest method. The logical device for the screen/keyboard 
  673. ('CON')  may  be opened as INPUT,  OUTPUT,  or  IO.  The  printer 
  674. ('LPTx')  would be opened as OUTPUT.
  675.    If a disk file is opened as IO,  DPL attempts to open the file 
  676. without  resetting  the  file pointer.  This is done  so  not  to 
  677. destroy any data in the file.  If the file is not found, then DPL 
  678. will create the file.
  679.    If  a file is opened as OUTPUT,  DPL will open or  create  the 
  680. file,  then  reset the file pointer to the beginning of the file, 
  681. thus  clearing any data from the file.  When the file is  closed, 
  682. the  directory entry is modified to reflect the last update,  and 
  683. current size.
  684.    When reading files,  due to the sequential access  method,  it 
  685. may be necessary to start reading from the beginning. This may be 
  686. accomplished  by closing,  then re-opening the file.  This resets 
  687. the file pointers to the beginning of the file.
  688.   DPL provides for error codes to be returned to the  application 
  689. through  the  STATUS  integer.   This  integer  is  automatically 
  690. declared  by  DPL  and is set to the resulting MS-DOS  value  for 
  691. opening a file.  Consult an MS-DOS manual for the returned values 
  692. for Function 3Dh. These values will be returned in STATUS.
  693.  
  694.  
  695. P O I N T  --  Point to a location in the file.
  696.  
  697.      POINT     file,dd
  698.  
  699.      This  instruction  moves  the file pointer  to  a  specified 
  700. location in the file.  POINT is used in conjunction with the NOTE 
  701. instruction  to  create  a  limited form  of  random  access  for 
  702. sequential disk files.  POINT has an identical counterpart in the 
  703. C programming language, "LSEEK". By "NOTE"ing a file, then later, 
  704. "POINT"ing to it, data may be reread or rewritten. Applicable DOS 
  705. error codes are returned in STATUS.
  706.  
  707. .PA
  708. R E A D  -- Read a variable length ASCII string from an opened
  709.             file
  710.  
  711.      READ      file,string,length
  712.  
  713.    This command reads data from a device/file and places the data 
  714. in the string.  The maximum amount data read is determined by the 
  715. "length" in the statement.  The string may be shorter if an CR/LF 
  716. is  encountered  during  the read.  If an  error  occurs  in  the 
  717. attempted read, the DOS error code will be returned in STATUS.
  718.  
  719.  
  720. R E A D B  -- Read a fixed number of bytes from an opened file
  721.  
  722.      READB     file,record
  723.  
  724.    This command reads data from a device/file and places the data 
  725. in the record.  The maximum amount data read is determined by the 
  726. length of the record.  This instruction must be used to read from 
  727. "B"  and  "R" type of files.  The normal READ will  not  work  on 
  728. binary  and  random files.  If an error occurs in  the  attempted 
  729. read, the DOS error code will be returned in STATUS.
  730.  
  731.  
  732. R E T U R N  --  Subroutine return statement
  733.  
  734.      RETURN
  735.  
  736.    This statement is identical to the return statement in  native 
  737. 8088 code.  It may be used by itself,  or in an IF statement. The 
  738. following subroutine demonstrates it's use:
  739.  
  740.      SUB     PROC   NEAR
  741.           IF WORD FLAG EQ ZERO RETURN
  742.           .
  743.           .
  744.           RETURN
  745.      SUB     ENDP
  746.  
  747.  
  748. S T O P  -- Terminate the program's execution
  749.  
  750.      STOP
  751.      STOP     1
  752.      STOP     int
  753.  
  754.    This  instruction gives control back to DOS and also allows  a 
  755. completion  code  to be set in DOS.  The completion code  can  be 
  756. tested with the "ERRORLEVEL" DOS command.  Also,  the code can be 
  757. retrieved by another program from DOS. The code may be a literal, 
  758. or  integer  variable.  Just  the least significant byte  of  the 
  759. completion code will be returned to DOS.
  760.  
  761. .pa
  762. S T R I N G   C O N C A T E N A T I O N
  763.  
  764.      str0 $= str1 + str2 + str3 + str4 + str5
  765.  
  766.    DPL allows strings to be concatenated together and the  result 
  767. placed into a target string.  The syntax is almost identical to a 
  768. mathematical  expression except for two things:  1) Only the plus 
  769. sign  ("+") is allowed in the expression,  and 2) in lieu of  the 
  770. equal  sign,  a  special  equate symbol pair,  "$="  is  used  to 
  771. designate string concatenation.
  772.  
  773.  
  774. W R I T E  --  Write an ASCIIZ string to an opened file
  775.  
  776.      WRITE     file,string
  777.      WRITE     file,string,CR
  778.      WRITE     file,,CR
  779.  
  780.    This statement allows the programmer to write data out to  any 
  781. device/file.  If  the  keyword  CR  (as shown  in  the  last  two 
  782. examples) is given,  then a CR/LF will be appended to the output. 
  783. The  third example shows how a CR/LF can be accomplished  without 
  784. first  printing  a string.  If the programmer wants to  print  an 
  785. integer,  then the integer will first have to be converted into a 
  786. string, then printed.
  787.  
  788.  
  789. W R I T E B  --  Write a record to an opened file
  790.  
  791.      WRITEB    file,record
  792.  
  793.      This  instruction writes the contents of the record  out  to 
  794. the  given file.  This statement must be used to write to "B" and 
  795. "R" type of files.  The standard WRITE instruction will not  work 
  796. on binary and random files.  The appropriate DOS error codes will 
  797. be returned in STATUS. 
  798.  
  799. .pa
  800.                     B i b l i o g r a p h y
  801.  
  802.      The development of DPL has been evolving for over two years. 
  803. Admittedly,  the  direction  has  been on the basis  of  "I  need 
  804. this...",  and "wouldn't it be neat if...".  In other words,  its 
  805. the  product of creeping enhancement,  though the  integrity  has 
  806. been protected by my vision of creating a solid assembly language 
  807. development environment.  During the course of investigation  and 
  808. research,  I have read and studied many publications,  which have 
  809. had a direct influence on this endeavor.  The following is a list 
  810. of these publications:
  811.  
  812.  
  813. Borland International, Inc. TURBO C., 1987
  814.  
  815. IBM AT Technical Reference Manual. IBM Corp., 1985
  816.  
  817. IBM PC Technical Reference Manual. IBM Corp., 1983
  818.  
  819. Microsoft Macro Assembler. Microsoft, 1985
  820.  
  821. Osborne/McGraw Hill. Using TURBO C., 1988
  822.  
  823. Osborne/McGraw Hill. Advanced TURBO C., 1988
  824.  
  825. Duncan, Raymond. Advance MS-DOS. Microsoft Press, 1986
  826.  
  827. Coffron, James W. Programming the 8086/8088. SYBEX, 1983
  828.  
  829. Hyman, Michael I. Memory Resident Utilities, Interrupts,
  830.      and Disk Management with MS & PC DOS. MIS, 1986
  831.  
  832. Jourdain, Robert. Programmer's Problem Solver for the IBM
  833.      PC, XT & AT. Brady Communications Co. 1986
  834.  
  835. Kernighan, Brian W. & Ritchie, Dennis M. The "C"
  836.      Programming Language. Bell Telephone Labs, Inc. 1978
  837.  
  838. Norton, Peter. Programmer's Guild to the IBM PC.
  839.      Microsoft Press, 1985
  840.  
  841. Wadlow, Thomas A. Memory Resident Programming on the IBM PC.
  842.      Addison-Wesley Publishing Co., 1987
  843.  
  844. Young, Michael J. Performance Programming Under MS-DOS.
  845.      SYBEX, 1987
  846.