═══ 1. V7NL Licensing Terms and Restrictions ═══ (C) Copyright 1993, Jim Dailey, FidoNet 1:106/202, ALL RIGHTS RESERVED. THE V7NL.DLL, IS AND WILL REMAIN THE INTELLECTUAL PROPERTY OF JAMES DAILEY. BECAUSE V7NL IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY AND WILL ONLY GUARANTEE THAT V7NL WILL TAKE UP SPACE ON YOUR DISK. V7NL IS OFFERED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF V7NL, AND THE ACCURACY OF ITS ASSOCIATED DOCUMENTATION, IS WITH YOU. SHOULD V7NL OR ITS ASSOCIATED DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. A LICENSE TO FREELY USE V7NL IS GRANTED TO ALL NON-COMMERCIAL USERS. IF YOU RUN A SUBSCRIPTION BBS, OR RUN A BBS IN SUPPORT OF YOUR BUSINESS, YOU ARE REQUIRED TO MAKE A ONE TIME $100 DONATION TO A CHARITY THAT SUPPORTS ABUSED CHILDREN. YOU MAY DISTRIBUTE V7NL.DLL WITH YOU APPLICATION. IF YOUR APPLICATION IS A COMMERCIAL APPLICATION OR A SHAREWARE APPLICATION YOU ARE REQUIRED TO MAKE THE ONE TIME DONATION. DONATIONS ARE TO BE MADE ON BEHALF OF FIDONET. YOU MAY POST V7NL FOR DOWNLOADING FROM YOUR BBS, OR DISTRIBUTE V7NL THROUGH FIDONET FILE DISTRIBUTION SYSTEMS UNDER THE FOLLOWING CONDITIONS: 1. YOU ARE NOT TO MODIFY THE ORIGINAL DISTRIBUTION FILE INCLUDING RE-ARCHIVING THE DISTRIBUTION FILE. 2. YOU ARE NOT TO REVERSE ENGINEER, MODIFY IN ANYWAY ANY FILE IN THE DISTRIBUTION ARCHIVE. 3. YOU ARE NOT TO SELL OR CHARGE A FEE FOR V7NL. IF YOU RUN A SUBSCRIPTION BBS, V7NL IS TO BE FREELY AVAILABLE FOR DOWNLOAD OR NOT AVAILABLE AT ALL. 4. YOU ARE PROHIBITED FROM CHARGING FOR THE DISTRIBUTION OF V7NL. Special Thanks to: Vince Perriello - for giving us BINKLEY Term The Opus development team of Wynn Wagner III and Doug Boone. FidoNet - a major contributor to global communciations. IBM for OS/2 (all versions). Last but not least - all those who took the time to file request and test V7nl for me, and to send me your comments, suggestions, and bug reports. ═══ 2. Introduction ═══ The V7NL.DLL, is a 32 bit dynamic link library that provides an API to access a FidoNet version 7 nodelist. The DLL give the application programmer the ability to: 1. Findfirst/Findnext processing to search the node list. This can be done using a complete or partial nodenumber, or a complete or partial SysOp name. 2. Random processing of nodes. An example would be a mail editor application that had a distribution list. The application can open the nodelist once, individually read each node extracting or saving the required information, then closing the nodelist. 3. Nodelist maintenance. Your application can add new nodes, update existing nodes, or delete existing nodes. ═══ 3. Version 7 Nodelist Format ═══ The Version 7 nodelist is divided into 3 seperate components: Node Index An index containing an entry for every node in the nodelist. SysOp Name Index An index containing at least one entry for each SysOp in the node list. Typically, most node list compilers by default will place a SysOp's name in the index once. Most, also allow duplicate entries if explicitly requested in their configuration files. There can never be duplicate entries all pointing to the same DAT file record A node index entry and a SysOp index entry can and do point to the same record. DAT file A file containing the detailed information for each node. Each index entry contains a pointer in the form of an offset into the DAT file, for it's detailed information. The data structure of the index components are organized into a hierarchial called a B_tree. Each node or "entry" in the tree is composed of 2 parts: a "key" part and a "data" part. The data part is where the information is stored. The "key" part in the node index is made up of a node number. The length of the key for a normal node is 6 bytes and for a point node is 8 bytes. Duplicate entries in the node index are not allowed. In the SysOp index, the key is a SysOp name of the format, Last name, followed by a comma (,), followed by a space, followed the first name. The SysOp index can and does contain duplicate keys, however each entry's "data" part contains a different value. The "data" part in the index is an offset into the node list DAT file. Once a node's entry is located in the index, the offset is used to find and read the nodes information from the DAT file. ═══ 4. Programming considerations ═══ ═══ 4.1. General Information ═══ V7NL.DLL is a 32 bit Dynamic Link Library, compiled with IBM's C Set++. When compiling your programs, you MUST compile with structure packing on single a byte boundary. Note: OS/2 v2.0+ is required for V7NL.DLL. ═══ 4.2. V7NL Callable Function Groups. ═══ ═══ 4.2.1. Initialization and termination. ═══ The 2 initialization and termination functions are: V7Initialize This function initializes and prepares the V7NL.DLL for processing. It must be called once and only once, prior to makeing any subsequent function calls. V7Finish The function is called when your nodelist processing is complete. Memory allocated during the initialization call is free. ═══ 4.2.2. FindFirst/Findnext Processing. ═══ The FindFirst/Findnext is similiar to findfirst/findnext processing when searching for a list of files that match a specified file mask. Two findfirst functions are available; one for searching the node index, and the other for searching the SysOp name index. When one of the findfirst functions is called, the matching index and the DAT file is opened and remains opened until the close function is called. V7FindFirstNode This function opens the node index and the DAT file, and retrieves the first record matching the search key. V7FindFirstSysOp This function opens the SysOp name index and the DAT file, and retrieves the first record matching the search key. V7FindNext This function retrieves the next record matching your search key. This function is called repeatdly until, there are no more records matching the initial search key. V7FindClose This function terminates the findfirst/findnext process. The node list files that are open are closed and IO buffers are freed. ═══ 4.2.3. Node List Maintenance. ═══ The maintenance functions allow you to update an existing node, add a new node, or delete a node. These function will open the required index and DAT files, perform their function, then close the files. V7AddNode This function allows a program to add a new node to the node list. Optionally, an entry is added to the SysOp name index. V7UpdateNode This function allows you to update the information for an existing node. V7DeleteNode This function deletes a nodes information from the node index. If a matching entry is in the SysOp name index, it too is deleted. The information in the DAT file is not deleted. ═══ 4.2.4. Random Processing. ═══ Random processing is ideal for retireving information on nodes that can't be read using findfirst/findnext processing. It is ideal for a distribution list where the nodes are in many different nets. In random processing, the node index and DAT files are opened until processing is complete. V7OpenIndex Opens the node index for randome processing. V7ReadIndex Reads the information for a specific node using the node index opened by V7OpenIndex. V7CloseIndex Closes the node index and DAT file. ═══ 4.2.5. Misc. Processing ═══ The following function is when you need to find one node number. It will open the node index and DAT file, read the nodes record, then close the opened file. V7FindNode Obtain the information for a specific node. ═══ 4.3. Return Codes. ═══ Below are the return codes returned by the function in V7NL.DLL V7NL_SUCCESS Request was a success V7NL_NODEINDEX_OPENFAILED Open of the node index failed. V7NL_SYSOPINDEX_OPENFAILED Open of the SysOp index failed. V7NL_NODEDAT_OPENFAILED Open of the DAT file failed. V7NL_NODENUMBER_NOTFOUND Requested node number was not found. V7NL_SYSOPNAME_NOTFOUND Requested SysOp name was not found. V7Nl_NODEDAT_READERROR IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR Seek failed on DAT file. V7NL_FINDNEXT_END No more entries found matching the argument passed in either V7FindFirstNode or V7FindFirstSysOp V7NL_NODEDELETE_FAILED Deletion of an entry in the node index failed. V7NL_SYSOPDELETE_FAILED Deletion of an entry in the SysOp index failed. V7NL_ZONENUMBER_REQUIRED Zone number is required in the V7NODE record. V7NL_NETNUMBER_REQUIRED Net number is required in the V7NODE record. V7NL_NODENUMBER_REQUIRED Node number is required in the V7NODE record. V7NL_PHONENUMBER_REQUIRED Phone number is required in the V7NODE record. V7NL_SYSOPNAME_REQUIRED SysOp name is required in the V7NODE record. V7NL_MODMEMBAUD_LESSTHAN300 Modem Baud is less than 300. V7NL_MODEMBAUD_NOTMULTIPLE300 Modem Baud is not a multiple of 300. V7NL_NODEDAT_WRITEERROR IO Error writing to the DAT file. V7NL_NODEINDEX_UPDATEERR Error writing to the node index. V7NL_SYSOPINDEX_UPDATEERR Error writing to the SysOp index. ═══ 4.4. V7RCB - V7NL.DLL Request Control Block ═══ All functions that perform IO to either of the node list indexes and the DAT file require the application pass a V7NL Request Control Block It is the applications responsibility to ensure the V7RCB is correctly initialized. /*********************************************************************** * V7NL request control block *********************************************************************** */ typedef struct { PSZ pszIndexName ; /* path and name of node index */ PSZ pszSysOpIndex ; /* path and name of Sysop index */ PSZ pszDataName ; /* path and name of .DAT file */ PV7NODE pV7Node ; /* address of where to copy nodlist record */ WORD wLen ; /* length for find first node function 2 = search on Zone 4 = search on Zone + Net 6 = search on Zone + Net + Node 8 = search on Zone + Net + Node + Point */ UWORD V7Flags ; /* Flags */ PVOID pnlFh ; /* used by find first/next */ } V7RCB, *PV7RCB ; /* *********************************************************************** * Values for the "V7Flags" field *********************************************************************** */ #define V7_SYSOPDUP 0x0001 /* when adding entry to SysOp index duplicate entry is ok */ #define V7_SYSOPADD 0x0002 /* when adding an entry to the node index, add an entry to the sysop index also */ ═══ 4.5. V7NODE - Version 7 Nodelist Structure. ═══ The following is the format of the Version 7 nodelist record. /*********************************************************************** * structure of a fido net node. this structure is based primarily * on the NEWNODE structure of Opus CBCS *********************************************************************** */ typedef struct { WORD ZoneNumber ; /* *jbd* */ WORD NetNumber; WORD NodeNumber; UWORD Cost; /* cost to user for * message */ char SysopName[26] ; /* sysop *jbd* */ char SystemName[34]; /* node name */ char PhoneNumber[40]; /* phone number */ char MiscInfo[30]; /* city and state */ char Password[9]; /* necessarily null-terminated */ UWORD RealCost; /* phone company's charge */ short HubNode; /* node # of this node's hub * or point number if node is a point */ UWORD BaudRate; /* baud rate divided by 300 */ BYTE ModemType; /* RESERVED for modem type */ UWORD NodeFlags; /* set of flags (see below) */ ULONG ulOffset ; /* offset into DAT file */ } V7NODE, *PV7NODE ; /* *********************************************************************** * Values for the `NodeFlags' field *********************************************************************** */ #define B_hub 0x0001 /* node is a net hub 0000 0000 0000 0001 */ #define B_host 0x0002 /* node is a net host 0000 0000 0000 0010 */ #define B_region 0x0004 /* node is region coord 0000 0000 0000 0100 */ #define B_zone 0x0008 /* is a zone gateway 0000 0000 0000 1000 */ #define B_CM 0x0010 /* runs continuous mail 0000 0000 0001 0000 */ #define B_res1 0x0020 /* reserved by Opus 0000 0000 0010 0000 */ #define B_res2 0x0040 /* reserved by Opus 0000 0000 0100 0000 */ #define B_res3 0x0080 /* reserved by Opus 0000 0000 1000 0000 */ #define B_res4 0x0100 /* reserved by Opus 0000 0001 0000 0000 */ #define B_res5 0x0200 /* reserved for non-Opus 0000 0010 0000 0000 */ #define B_res6 0x0400 /* reserved for non-Opus 0000 0100 0000 0000 */ #define B_res7 0x0800 /* reserved for non-Opus 0000 1000 0000 0000 */ #define B_point 0x1000 /* node is a point 0001 0000 0000 0000 */ #define B_res9 0x2000 /* reserved for non-Opus 0010 0000 0000 0000 */ #define B_resa 0x4000 /* reserved for non-Opus 0100 0000 0000 0000 */ #define B_resb 0x8000 /* reserved for non-Opus 1000 0000 0000 0000 */ Note: The V7NL.DLL Version 7 nodelist structure is based closely on the Opus v1.20 Version 7 node list structure. The Opus v1.20 Version 7 node list structure is Copyright 1991 by Wynn Wagner III and Doug Boone. ═══ 5. V7NL Functions Calls. ═══ ═══ 5.1. V7AddNode ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function adds a node to the node index and it related * information to the nodelist .DAT file. Optionally, an * index entry is added to the SysOp index. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7rc = V7AddNode(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszSysOpIndex - Pointer to the name of the nodelist sysop index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. If you wish to add the SysOp name for the new node to the SysOp index you must turn on the V7_SYSOPADD flag in the V7Flags field. If you, allow duplicate SysOp names, the V7_SYSOPDUP flag must also be turned on. V7NODE with, at a minimum, the following fields initialized.: ZoneNumberZone number of the new node. NetNumberNet number of the new node. NodeNumberNode number of the new node. SysopNameName of the SysOp for the new node. PhoneNumberPhone number for the new node. ModemBaudModem baud rate for the new node. This value must be a multiple of 300. If the new node is a point, the HubNode must contain the point number and B_point flag in the NodeFlags field must be turned on. ═══ Return Values ═══ Return Values V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_SYSOPINDEX_OPENFAILED - Open of the SysOp index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. V7NL_ZONENUMBER_REQUIRED - Zone number is required in the V7NODE record. V7NL_NETNUMBER_REQUIRED - Net number is required in the V7NODE record. V7NL_NODENUMBER_REQUIRED - Node number is required in the V7NODE record. V7NL_PHONENUMBER_REQUIRED - Phone number is required in the V7NODE record. V7NL_SYSOPNAME_REQUIRED - SysOp name is required in the V7NODE record. V7NL_MODMEMBAUD_LESSTHAN300 - Modem Baud is less than 300. V7NL_MODEMBAUD_NOTMULTIPLE300 - Modem Baud is not a multiple of 300. V7NL_NODEDAT_WRITEERROR - IO Error writing to the DAT file. V7NL_NODEINDEX_UPDATEERR- Error writing to the node index. V7NL_SYSOPINDEX_UPDATEERR - Error writing to the SysOp index. ═══ Notes ═══ I can't think of anything at this time. ═══ Example ═══ #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszSysOpIndex = pszSysOpIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; . . < initialize V7NODE > . . V7rc = V7AddNode(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } } ═══ Related Functions ═══ V7FindNode V7DeleteNode V7UpdateNode V7DeleteSysOp ═══ 5.2. V7CloseIndex ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function closes the node index that was opened by * a previous call to V7OpenIndex ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ VOID V7CloseIndex(PV7RCB pV7rcb) ═══ Parameters ═══ V7RCB that was initialized prior to calling V7OpenIndex ═══ Return Values ═══ This functions does not return any values. ═══ Notes ═══ The V7RCB must have been initialized, and a call to V7OpenIndex prior to calling this function. ═══ Example ═══ #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rc = V7OpenIndex(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } . . < initialize V7NODE > < read a node list record > . . V7CloseIndex(&V7rcb) ; } ═══ Related Functions ═══ V7OpenIndex V7ReadIndex ═══ 5.3. V7DeleteNode ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function deletes a nodes entry from the node * index. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7DeleteNode(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. V7NODE with, at a minimum, the following fields initialized.: ZoneNumber- Zone number of the node to be deleted. NetNumber- Net number of the node to be deleted. NodeNumber- Node number of the node to be deleted. ulOffset - Offset to the nodes entry in the DAT file. If the node to be deleted is a point, then the HubNode field of the V7NODE record must contain the point number and the B_point in NodeFlags must be turned on. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_NODEDELETE_FAILED - Deletion of the entry in the node index failed failed. ═══ Notes ═══ The zone, net, and node numbers, and the value in the ulOffset of the V7NODE must match with the nodes index entry for a node to be deleted from the node index. If the node is a point, the point number is used as part of the index key. The deleted nodes information in the DAT file is NOT not deleted. ═══ Example ═══ In this example, a nodes entry is first read in order to get it's offset into the DAT file. If the read is successful, the nodes entry in the node index is deleted. #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rcb.wLen = 6 ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; V7node.NodeNumber = 202 ; /* read the nodes record to gets the offset of it's entry in the DAT file */ V7rc = V7FindNode(&V7rcb) ; /* if the record was found, then delete it */ if ( V7rc == V7NL_SUCCESS ) { V7rc = V7DeleteNode(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } } else { } } ═══ Related Functions ═══ V7FindNode V7AddNode V7UpdateNode V7DeleteSysOp ═══ 5.4. V7DeleteSysOp ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function deletes a sysop entry from the sysop * index. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7DeleteSysOp(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. V7NODE with, at a minimum, the following fields initialized.: Sysopname- SysOp name for the entry to be deleted. ulOffset - Offset to the nodes entry in the DAT file. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_SYSOPINDEX_OPENFAILED - Open of the node index failed. V7NL_SYSOPDELETE_FAILED - Deletion of the entry in the node index failed failed. ═══ Notes ═══ The SysopName and the ulOffset of the V7NODE must match with the SysOp index entry for an index to be deleted from the SysOp index. The deleted SysOp's information in the DAT file is NOT not deleted. ═══ Example ═══ In this example, a nodes entry is first read in order to get it's offset into the DAT file. If the read is successful, the SysOp entry in the SysOp index is deleted. #include #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rcb.wLen = 6 ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; V7node.NodeNumber = 202 ; /* read the nodes record to gets the offset of it's entry in the DAT file */ V7rc = V7FindNode(&V7rcb) ; /* if the record was found, then delete it's SysOp index entry */ if ( V7rc == V7NL_SUCCESS ) { V7rc = V7DeleteSysop(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } } else { } } ═══ Related Functions ═══ V7FindNode V7AddNode V7UpdateNode V7DeleteNode ═══ 5.5. V7FindClose ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function performs the close processing at the * end of findfirst/findnext processing * ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ VOID V7FindClose(pV7rcb) ; ═══ Parameters ═══ V7RCB that was initialized prior to calling V7FindFirstNode or V7FindFirstSysOp ═══ Return Values ═══ This function has no return values. ═══ Notes ═══ The V7RCB must have been initialized, and a call to V7FindFirstNode or V7FindFirstSysOp prior to calling this function. ═══ Example ═══ #include #include "v7nl.h" main() { V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; < initialize V7RCB > < findfirst/findnext processing> V7FindClose(&V7rcb) ; } ═══ Related Functions ═══ V7FindFirstNode V7FindFirstSysOp V7FindNext ═══ 5.6. V7FindFirstNode ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function reads the first matching node. It sets up * for subsequent find next calls to retrieve all nodes matching * the specified key. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7FindFirstNode(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. wLen - Length of the search key: o 2 - To search for all nodes matching ZoneNumber o 4 - To search for all nodes matching ZoneNumber + NetNumber o 6 - To search for all nodes matching ZoneNumber + NetNumber + NodeNumber V7NODE with the Zone, Net, and/or Node fields filled in as appropriate for the type of search desired. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. V7NL_NODENUMBER_NOTFOUND - Requested node number was not found. V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. ═══ Notes ═══ This function is the first function to be called when performing findfirst/findnext processing for a key of a partial node number. By creating a partial key of a Zone + Net, you can read all of the nodes in a particular net. ═══ Example ═══ This example shows the first step in findfirst/findnext processing using a partial node number as a key. #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rcb.wLen = 4 ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; /*********************************************** * read the first node in zone 1 net 106 *********************************************** */ V7rc = V7FindFirstNode(&V7rcb) ; } ═══ Related Functions ═══ V7FindFirstSysOp V7FindNext V7FindClose ═══ 5.7. V7FindFirstSysOp ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function finds the first SysOp entry in the SysOP * index that matches the full or partial name in * SysopName field of the V7NODE record. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7FindFirstSysOp(pV7rcb) ; ═══ Parameters ═══ V7RCB with the following fields initialized: pszSysOpIndex - Pointer to the name of the nodelist SysOp name index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. V7NODE with the SysopName primed with a full or partial SysOp name. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_SYSOPINDEX_OPENFAILED - Open of the SysOp index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. V7NL_SYSOPNAME_NOTFOUND - Requested SysOp name was not found. V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. ═══ Notes ═══ This function is the first function to be called when performing findfirst/findnext processing for a key of a full or partial SysOp name. ═══ Example ═══ This example finds the first entry in the SysOp index whose last name is Smith and whose first name begins with the letter J. #include #include "v7nl.h" main() { PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszSysOpIndex = pszSysOpIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; strcpy(V7node.SysopName, "J Smith") ; /*********************************************** * read the first matching SysOp *********************************************** */ V7rc = V7FindFirstSysOp(&V7rcb) ; } ═══ Related Functions ═══ V7FindFirstNode V7FindNext V7FindClose ═══ 5.8. V7FindNext ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This functions finds the next node that matches the * search argument that was passed in the initial findfirst * function call. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7FindNext(pV7rcb) ; ═══ Parameters ═══ A V7RCB that was initialized prior to calling either V7FindFirstNode or V7FindFirstSysOp ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. V7NL_FINDNEXT_END - No more entries found matching the argument passed in either V7FindFirstNode or V7FindFirstSysOp. ═══ Notes ═══ This function is a continuation of one of the findfirst functions. It continues reading records that match the original key until there are no more matches. ═══ Example ═══ This example shows the loop required to read all of the nodes in a net. #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rcb.wLen = 4 ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; /*********************************************** * read the first node in zone 1 net 106 *********************************************** */ V7rc = V7FindFirstNode(&V7rcb) ; /*********************************************** * process and read the remaining nodes *********************************************** */ while ( V7rc == V7NL_SUCCESS ) { < node record processing > V7rc = V7FindNext(&V7rcb) ; } } ═══ Related Functions ═══ V7FindFirstNode V7FindFirstSysOp V7FindClose ═══ 5.9. V7FindNode ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function reads the record for a specific. The * node index is used by this function. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7FindNode(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to an initialized nodelist record. V7NODE with, at a minimum, the following fields initialized.: ZoneNumberZone number of the node. NetNumberNet number of the node. NodeNumberNode number of the node. If the node is a point, the HubNode must contain the point number and B_point flag in the NodeFlags field must be turned on. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_SYSOPINDEX_OPENFAILED - Open of the SysOp index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. V7NL_NODENUMBER_NOTFOUND - Requested node number was not found. V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. ═══ Notes ═══ Nothing special to say about this function. It just reads a node's nodelist entry. ═══ Example ═══ This shows how to read a nodes nodelist entry. #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszSysOpIndex = pszSysOpIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; V7node.NodeNumber = 202 ; V7node.HubNode = 1 ; V7node.NodeFlags != B_point ; . /*********************************************** * read the node list entry for 1:106/202.1 *********************************************** */ V7rc = V7FindNode(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } } ═══ Related Functions ═══ Ain't none. ═══ 5.10. V7Finish ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This cleans up and free memory obtain by V7Initialize ************************************************************ */ #include #include "v7nl.h" VOID V7Finish(VOID) ; ═══ Parameters ═══ This one's easy. There are no parameters. ═══ Return Values ═══ There are no return values. ═══ Notes ═══ This function is called prior to terminating your program. ═══ Example ═══ #include #include "v7nl.h" main() { V7Initialize() ; . . . . V7Finish() ; } ═══ Related Functions ═══ V7Initialize ═══ 5.11. V7Initialize ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function initializes the DLL for node list processing ************************************************************ */ #include #include "v7nl.h" BOOL V7Initialize(VOID) ; ═══ Parameters ═══ This function has no parameters. ═══ Return Values ═══ TRUE - Initialization was successful FALSE - Initialization failed. ═══ Notes ═══ This function MUST must be called prior to calling any of the functions that access the nodelist. ═══ Example ═══ #include #include "v7nl.h" main() { V7Initialize() ; } ═══ Related Functions ═══ V7Finish ═══ 5.12. V7OpenIndex ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function opens the nodelist node index form * multiple random accesses ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7OpenIndex(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszDataName - Pointer to the name of the nodelist .DAT file. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. ═══ Notes ═══ This function must be called prior to callingV7ReadIndex. ═══ Example ═══ Open the nodelist node index. #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszDatName = pszNodeDat ; V7rc = V7OpenIndex(&V7rcb) ; } ═══ Related Functions ═══ V7ReadIndex V7CloseIndex ═══ 5.13. V7ReadIndex ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This function performs random reads on a nodelist that * was opened by V7OpenIndex ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7ReadIndex(pV7rcb) ; ═══ Parameters ═══ V7RCB that was initialized with a call to V7OpenIndex In addition field wLen must be initialized to the length of the search argument and pV7Node must contain a pointer to a V7NODE V7NODE with the zone, net, node fields initialized for the node whose record you want to read. If the node is a point, the HubNode must contain the point number and B_point flag in the NodeFlags field must be turned on. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODENUMBER_NOTFOUND - Requested node number was not found. V7Nl_NODEDAT_READERROR - IO error reading the DAT file. V7NL_NODEDAT_SEEKERROR - Seek failed on DAT file. ═══ Notes ═══ This function is for random reading through the nodelist. The main difference between this function and V7FindNode, is V7FindNode opens the node list, reads the record, then closes the nodelist. Using V7ReadIndex the index is opened by V7OpenIndex and remains open until V7CloseIndex is called. ═══ Example ═══ #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszSysOpIndex = "C:\\Nodelist\\Sysop.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszSysOpIndex = pszSysOpIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7rcb.wLen = 6 ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; V7node.NodeNumber = 202 ; V7rc = V7OpenIndex(&V7rcb) ; if ( V7rc == V7NL_SUCCESS ) { V7rc = V7ReadIndex&V7rcb) ; } V7CloseIndex(&V7rcb) ; } ═══ Related Functions ═══ V7FindNode ═══ 5.14. V7UpdateNode ═══ Function Syntax Parameters Return Values Notes Examples Related ═══ Function Syntax ═══ /************************************************************ * This updates a nodes entry in the node list. ************************************************************ */ #include #include "v7nl.h" V7RC V7rc ; /* return code from the DLL */ PV7RCB pV7rcb ; /* DLL IO request block */ V7NODE V7node ; /* V7 nodelist record */ V7rc = V7UpdateNode(pV7rcb) ; ═══ Parameters ═══ V7RCB: with the following fields initialized: pszIndexName - Pointer to the name of the nodelist node index. pszSysOpIndex - Pointer to the name of the nodelist sysop index. pszDataName - Pointer to the name of the nodelist .DAT file. pszV7Node - Pointer to a previously read node list record. ═══ Return Values ═══ V7NL_SUCCESS - Request was a success V7NL_NODEINDEX_OPENFAILED - Open of the node index failed. V7NL_SYSOPINDEX_OPENFAILED - Open of the SysOp index failed. V7NL_NODEDAT_OPENFAILED - Open of the DAT file failed. V7NL_NODEDAT_WRITEERROR - IO Error writing to the DAT file. V7NL_NODEINDEX_UPDATEERR- Error writing to the node index. V7NL_SYSOPINDEX_UPDATEERR - Error writing to the SysOp index. ═══ Notes ═══ The record to be deleted, must have been previously read, or a V7NODE record initialized with the complete key information, including the ulOffset field containing the offset to the nodes current entry in the DAT file. If there is a matching entry in the SysOp name index, it too is updated. The old information is not deleted or overlayed in the DAT file with the new information. Instead, the nodes new information is appended to the end of the DAT file, and the respective index entries updated with the new offset. ═══ Example ═══ This example reads a nodes entry, changes the phone number, then write the nodes data to the end of the DAT file. Both the node index and the SysOp index entries with the new offset into the DAT file. #include #include #include "v7nl.h" main() { PSZ pszNodeIndex = "C:\\Nodelist\\Nodex.ndx" ; PSZ pszNodeDat = "C:\\Nodelist\\Nodex.dat" ; V7RCB Vrcb ; /* request block */ V7NODE V7node ; /* V7 format node record */ V7RC V7rc ; /* return code */ V7Initialize() ; memset(&V7rcb, '\0', sizeof(V7RCB)) ; memset(&V7node, '\0', sizeof(V7NODE)) ; V7rcb.pszIndexName = pszNodeIndex ; V7rcb.pszSysOpIndex = pszSysOpIndex ; V7rcb.pszDatName = pszNodeDat ; V7rcb.pV7Node = &V7node ; V7node.ZoneNumber = 1 ; V7node.NetNumber = 106 ; V7node.NodeNumber = 202 ; V7node.HubNode = 1 ; V7node.NodeFlags != B_point ; . /*********************************************** * read the node list entry for 1:106/202.1 *********************************************** */ V7rc = V7FindNode(&V7rcb) ; if ( V7rc != V7NL_SUCCESS ) { } else { strcpy(V7node.PhoneNumber, "555-1234") ; V7UpdateNode(&V7rcb) ; } } ═══ Related Functions ═══ V7FindNode V7AddNode V7DeleteNode