PL/I-80TM USER'S GROUP DISK #2 This is the second disk in the PL/I-80 User's Group (PLUG) Library. It includes two sets of programs: o An Inventory Control and Point-of-Sale System o Several useful utilities and subroutines The inventory control system is used as a case study in the advanced PL/I-80 programming session of the Digital Research Independent Software Vendor (ISV) Seminar. The utilities include copy with query, file erase with query, a directory FCB counting program, filename parsing routines, a hexadecimal PL/I input routine, hexadecimal dump routines and a program chaining facility. Also included is the PL/I direct I/O package supporting direct CP/M BDOS calls from PL/I programs and similar packages for direct MP/MTM calls and direct BIOS calls. All these programs are described in detail below. 1. ISV Inventory and Point-of-Sale System This program performs four principal functions: o Data Base Creation (CREATE.PLI) o Data Base Modification (UPDATE.PLI) o Point-of-Sale (SALE.PLI) o Report Generation (REPORT.PLI) Each of these functions are performed by a particular module designed to be an overlay for the program. The desired function is selected from a menu displayed by the root menu module. The menu module interacts with the operator to select one of the special-purpose modules create, update, sale, or report. These modules, in-turn, access the data base to perform their actions. The format of data base records is defined and stored on disk in the separate definition file "DEF.DAT". There can be upto 32 fields where each field is up to 16 characters in length, defined by the start and finish columns in the definition. The definition file is a stream file which can be created using any CP/M editor such as ED.COM. The first record (line) in the definition file is the sales tax in percent, for example, if the sales tax is 6%, this line would be 6.0 (a decimal(4,2) format). Each additional record (line) in the definition file defines a field and has the following format: ,,, where is a character string upto 16 characters long 1 PLUG DISK # 2 Program Descriptions is one of the following: 0 = principal key field 1 = quantity field 2 = price field 3 = unknown field is the first column of the field in the 128 byte record (columns are 1 to 128) is the last column of the field in the record An index to the data base is maintained in a stream file named "KEY.DAT". This is a list of keys to the data base where the first key corresponds to the first record in the data base, the second key to the second record, and so on. At the start of the program the keys are read by the routine setkey and a linked list is built in memory. When a record is to be accessed the linked list is searched linearly for the desired key and the record is read using random I/O. The files in the inventory system are described below. ACCESS.OVL The overlay generated from ACCESS.PLI. ACCESS.PLI This module provides primitives for record access and update. ATTRIB.DCL This include file contains the replace statement determining the maximum number of fields per record, maximum field size and record size. The structure defining a DEF.DAT record is also declared. COMP.SUB The submit which compiles the inventory system. CREATE.OVL The overlay for CREATE.PLI. CREATE.PLI This module creates a data base. DATA.DAT The data base file. DEF.DAT The data base definition. IO.PLI This module contains "primitives" used for I/O by the various modules. KEY.DAT The data base keys by which the data base is accessed. The keys are kept in the same order as their corresponding records in the data base. KEY.DCL This declaration include file defines the linked list of keys kept in memory for data base access. 2 PLUG DISK # 2 Program Descriptions LINK1.SUB This submit links the overlay system. LINK2.SUB This submit links the system as one COM file. MENU.COM The root module for the overlay system. MENU.PLI The root module source containing the function menu. REPORT.OVL The overlay for REPORT.PLI. REPORT.PLI This module displays the contents of the data base. SALE.OVL The overlay for SALE.PLI. SALE.PLI This module creates an invoice (on disk) and updates the data base. SETDEF.OVL The overlay for SETDEF.PLI. SETDEF.PLI This module reads and validates the data base definition (DEF.DAT) and checks for the presence of price and quantity fields used by the SALE module. SETKEY.OVL The overlay for SETKEY.PLI. SETKEY.PLI This module reads the KEY.DAT file and builds the linked list of keys in memory. UPDATE.OVL The overlay for UPDATE.PLI. UPDATE.PLI This module performs data base update. 2. Useful utilities and subroutines. These routines include several useful CP/M utilities and subroutines for inclusion in larger programs. They are individually described below. ADUMP.PLI entry (ptr,fixed(15)); This routine displays a hex dump of any variable or data in memory providing a useful debugging tool. Two parameters are passed: (BASE_PTR, NUMBER_OF_BYTES) BASE_PTR is a pointer to the first byte to be dumped (i.e. the variable). NUMBER_OF_BYTES is the length of the data to be dumped. 3 PLUG DISK # 2 Program Descriptions ADUMP displays the actual address of each 16 bytes dumped. AODUMP.PLI entry (ptr,fixed(15)); This routine is the same as ADUMP described above, except that both the address and offset from the BASE_PTR are displayed for each 16 bytes dumped. CH1.PLI This program tests the chaining routine CHAIN.ASM. CH1 is invoked with the command: CH1 where is the COM file which is to be chained to. If is omitted CH1 prompts for a file name and parses it using the routine FPARSE.PLI (also on this disk). CH2.PLI This program chains to CH1.COM. If CH1 is invoked with the command "CH1 CH2" it will start a loop in which CH1 and CH2 chain to each other. The two programs will continue to chain until a '^S' is typed to stop them. After stopping the chaining with '^S', type '^C' to abort the test or 'S' to restart it. CHAIN.ASM entry (char(12)); This routine relocates itself to the top of the transient program area (TPA). It then loads a COM file and executes it. The FCB of the file to be loaded must be passed as a char(12) variable, (see the examples CH1.PLI and CH2.PLI). An 'undefined file' condition is signaled with the message "Bad Chain Attempt", if the file cannot be successfully opened. CHAIN.SUB A submit file to generate CH1.COM and CH2.COM. COPY.PLI This program is a file copying utility. COPY is invoked with the command: COPY where is the destination drive or a filename, and is the source filename which can contain the wildcard characters '?' and '*'. The source and destination arguments must be separated by spaces. The destination must be a drive other than the source drive if the source is ambiguous (i.e. contains wildcards). In a wildcard filename the character '?' matches any character in the same position in the file name or type and the character '*' matches any character or characters for the rest of the file name or type. If a wildcard specification is used, COPY prompts for the confirmation of each matching file before any copying is done. The following are 4 PLUG DISK # 2 Program Descriptions valid responses: Y - adds the filename to the list of files to be copied N - skips the file and displays the next matching file ^C - aborts the program ^Z - copies the files already approved When all matching files have been displayed the copying begins. As each file is copied a period is displayed. Striking any key will produce the prompt: 'Abort ? (Y/N)'. The invocation 'COPY HELP' displays the command syntax. COPY.SUB A submit file to generate COPY.COM. DIOMOD.DCL The declaration include file for PLIDIO.ASM, the direct interface to the BDOS used by several programs on this disk. (see the LINK-80TM manual pp. 43-57) DUMPTEST.PLI This program tests the ADUMP and ODUMP and AODUMP hexadecimal dump routines. DUMPTEST prompts for which procedure to test, ADUMP.PLI, ODUMP.PLI, or AODUMP.PLI. It then prompts for the address from which the dump is to start and the number of bytes to dump (length). The address must be entered as four hexadecimal digits (leading zeros included), and the length of the dump as a decimal number between 0 and 32767. DUMPTEST.SUB This submit file generates DUMPTEST.COM. ERAQ.PLI This program is a file deleting utility which works similarly to COPY.PLI described above. ERAQ is invoked with the command: ERAQ where is any valid CP/M filename and may contain the wildcard characters '?' and '*' described above (see COPY.PLI). If includes wildcard characters, all matching files are displayed for user confirmation before any files are deleted. The confirmation process is identical to that described for COPY.PLI. When all matching files have been displayed the approved files are deleted. A period is displayed for each file deleted. Striking any key will produce the prompt: 'Abort ? (Y/N)'. The invocation 'ERAQ HELP' displays the command syntax. ERAQ.SUB A submit file to generate ERAQ.COM. 5 PLUG DISK # 2 Program Descriptions FCB.DCL An include file declaring a file control block used by some programs on this disk. (see LINK-80 manual pp. 68 & 69) FCBS.PLI This program displays the number of FCBs being used in the directory for each user number and displays any "garbage" FCBs with user numbers greater than 15. FCBS.COM is invoked with one of the commands: FCBS FCBS FCBS HELP where is any CP/M drive and any valid CP/M filename. The can include the wildcard characters '?' or '*' (see COPY.PLI). If FCBS is invoked with a file name, a count of all matching FCBs is performed. "FCBS HELP" lists the command options. FPARSE.PLI entry (ptr, ptr, fixed(7)); This routine parses an unambiguous (no wildcard characters) filename into a CP/M file control block (FCB). FPARSE is called with three parameters: (SOURCE_PTR, DEST_PTR, RET_CODE) SOURCE_PTR is a pointer to a character string (NOT a character varying) containing one of more file names separated by commas or commas and spaces. It is important that the character string is not empty, does not contain just a comma or just spaces. It must not be a character varying string. If more than one file name exists in the string, SOURCE_PTR is set to point to the next filename upon return to the calling routine. DEST_PTR is a pointer to the FCB to be filled. RET_CODE is an integer which will be set to: 0 if successful and more files exist in the source string (in this case SOURCE_PTR will be set to the next filename) 1 if successful and no more files exist 2 if unsuccessful, i.e. an invalid filename HEXBIN.PLI entry(char(8) varying) returns (fixed(15)); This function converts two hexadecimal digits into a binary fixed value between 0 and 255. The string passed must contain only uppercase characters. 6 PLUG DISK # 2 Program Descriptions HEXTEST.PLI This is a test program for HEXBIN.PLI. The program accepts hexadecimal and displays the equivalent decimal number. HEXTEST.SUB This submit file generates HEXTEST.COM. MPMCALLC.PLI This is the second half of a test program for MPMDIO.ASM. The first half is in the file MPMCALLS.PLI. MPMCALLS.PLI This is the first half of a test program for MPMDIO.ASM. The program exercises all the MP/M function calls supported by MPMDIO. This program must be run in a non-banked MP/M system. Refer to the listing for additional comments and documentation. MPMCALLS.SUB This submit file generates MPMCALLS.COM. MPMDIO.ASM This provides a direct interface to MP/M for PL/I-80 programs. Similar to PLIDIO.ASM, which provides a direct interface to the BDOS. Read the source code for additional comments. MPMDIO.DCL This is an include file which declares the entry points for MPMDIO.ASM. ODUMP.PLI entry (ptr,fixed(15)); This routine is the same as ADUMP described above, except that only the offset from the base_ptr is displayed for each 16 bytes dumped. PARSE.PLI entry (ptr,ptr,fixed(7)); This routine is the same as FPARSE.PLI described above, except that the filename can contain the wildcard characters '*' or '?'. (see COPY.PLI). PLIBIOS.ASM This module provides primitives for direct bios disk read and write calls. Direct bios calls should only be used in system programs which must access the disk by track and sector, e.g. a track copy program. The FCBS program on this disk uses this module. PLIBIOS has the following entry points (declared in PLIBIOS.DCL): declare seldsk entry (fixed(7)) returns(ptr), settrk entry (fixed(15)), setsec entry (fixed(15)), rdsec entry returns(fixed(7)), wrsec entry returns(fixed(7)), sectrn entry (fixed(15), ptr) returns(fixed(15)); Warning: DO NOT attempt to use these calls under MP/M or CP/NET operating systems. 7 PLUG DISK # 2 Program Descriptions PLIBIOS.DCL The declaration include file for PLIBIOS.ASM. PLIDIO.ASM This module provides primitives for direct BDOS calls. It is used by several programs on this disk. The entry points and uses of PLIDIO are illustrated in the LINK-80 manual on pages 43 to 77. PTEST.PLI This program tests the PARSE and FPARSE file parsing routines. It may be invoked in two ways: PTEST PTEST , , ... In either case PTEST prompts for which procedure to test, PARSE.PLI or FPARSE.PLI. In the first case the program also prompts for the filenames to be parsed. The filenames must be separated by commas. Spaces are ignored. PTEST.SUB This submit file generates PTEST.COM. 8