----------------------------------------------------------- Using RTLink with Retail Application (RA) V1.03.00 or later ----------------------------------------------------------- VML (Virtual Memory Linking) in the Large Memory Model -------------------------------------------------------- NOTE: This README is not a substitute for reading the RTLink documetation. It is highly recommended that you read the RTLink documentation so you can get a full understanding of the RTLink environment. 1. Extended and Expanded memory: Please read the RTLink documentation for a better understanding of the use of Extended and Expanded memory in an RTLink program. | RA will run well in registers with as little as 2 MEG memory. | There are some special setup instructions for a register configuration | that meets ALL of the following conditions: | 1. DOS register with 2 MEG memory. | 2. Server using either Lantastic, Netware Lite, PowerLan, | Personal Netware, or any other DOS peer to peer networking software. | 3. Use of SMARTDRV or other disk caching program for LAN performance | improvements. | Previous setup instructions for this environment suggested limiting | the disk caching program's use of extended memory to allow RTLink to | use some of the extended memory. This setup was found to create | problems with the disk caching program and RTLink both trying to | share 1 MEG of upper memory. The suggested setup for this | configuration is to allow the disk caching program to use the entire | upper 1 MEG of memory. The disk caching program will probably do this | by default. This will cause RTLink to not use upper memory on the | DOS server but performance will still be good due to the use of | the caching program. Note that this configuration may be the same as | the configuration of DOS servers for previous releases of RA. In this | case, no configuration change is required. If you do not make use of | a disk caching program on the DOS server, then RTLink will make use of | the upper 1 MEG to cache the REGISTER.EXE program into extended memory | of the server. | On DOS clients where a disk caching program is not required, | RTLink will use the upper 1 MEG to cache the REGISTER.EXE program | into the extended memory of the client. | 2. The use of RTLink requires that the REGISTER.EXE be a READONLY file in a network environment. This may impact the process for upgrading the REGISTER.EXE file remotely at a customer location because the file will have a READONLY attribute which must be removed before an update can be applied. After the update has been applied the | READONLY attribute must be restored. 3. Internal Multitasker Considerations: Note: These precautions are only relevent if your user exit code does one of the following: 1. You use the RA Credit Auth Feature AND you have your own code in the user_dialer() TASK for credit auth dial out. Note that if you use a third party TSR credit auth solution or of you have a separate credit auth program that runs independently of the REGISTER.EXE program, then this item does not apply to you UNLESS you communicate with the credit auth TSR or stand alone program via the user_dialer() task. In other words if you have the user_dialer() task active then you need to read this. 2. You have created a user task via the user_create_task() function by issuing a mt_create(). If neither of the above 2 actions apply to you then you can skip this section. RTLink is not aware of the operations of the RA internal multitasker. Therefore, any functions that are specific to the credit auth task or a user task must be resident in memory. Any functions (including base functions) that the credit auth or user task uses must also be resident. An example of this is provided in the new copy of INCUSER.C. In this example, user_dialer() calls dialer_misc_function(). You will see in the RTLPRO.LNK file that both user_dialer() and dialer_misc_task() are forced to be resident. Note also that the RA libraries and many RA base functions are also forced resident. If you make a call to an RA function that is in an RA library, or if you call an RA base function that is already listed in the resident section of RTLPRO.LNK, then you do not have to add the function to the resident section again. In almost all cases, you will need to simply ensure that all of the functions you create for your task are specified in the resident section of RTLPRO.LNK. Special Considerations: 1. BTREE - Although POSLIB.LIB, which contains the RA Btree functionality, is made resident, you will see that we force the BTREE module into virtual memory via the command MODULE index.c which can be found in the virtual section of RTLPRO.LNK. If your task uses the RA btree (which is highly unlikely) then you will need to remove the above command from RTLPRO.LNK which will then cause the btree functions to become resident automatically. 2. Third party libraries: If you use any third party libraries (Greenleaf, etc.) in your task then you will also need to make the library resident in RTLPRO.LNK. | 4. OS/2 DOS Session Considerations: | If you are using a RTLink REGISTER.EXE on a 4694 running OS/2, then | you must make additional changes to the DOS settings of the DOS | session that is running REGISTER.EXE. The changes are as follows: | | DPMI_DOS_API = ENABLED | EMS_FRAME_LOCATION = NONE | MEM_EXCLUDE_REGIONS = D8000-DAFFF | | These changes may not be required in all configurations, but | they are recommended for all environments so problems are avoided. | These changes are in addition to the other changes for running | RA in an OS/2 DOS session which are documented in the RA Redbook. | 5. If you run the RTLink utility program OVPICT as follows: | | ovpict register.map 78 > out1 | | you will see that the POSA-SECTION of code is the largest virtual | section. If you review the output of the RTLink linker, you will see | that the Minimum Conventional VM Arena required to run is approximately | 47K. This is the size of the POSA-SECTION. You should try to keep the | size of the USER-SECTION and any NEW sections to no greater than the | size of the POSA-SECTION. If the size of the USER-SECTION or any other | NEW section is greater than the size of the POSA-SECTION then this will | increase the amount of resident memory required to run the REGISTER.EXE. | Any NEW sections that contain libraries or files which are larger the | POSA section may be broken apart into other NEW sections by using the | MODULE or FUNCTION commands to make each NEW section smaller. 6. There is a global flag called "RTLink" which will be binary 1 if you have linked under RTLink or binary 0 if you have linked with Microsoft. However, you should not need to use this variable for any program logic decisions since RTLink should be transparent to your code. 7. Due to the fact that the register program is now in the LARGE memory model, it is even more important that you prototype all functions that are called in your user exit code. This is very important because under the medium memory model, functions that took "char *" as parameters or returned "char *" worked OK without a prototype because the compiler assumed an "int" which is compatable with a "near char *". However, under the large memory model, this assumption will cause problems because the assumed "int" is not large enough to hold a "far char *". If you have properly prototyped all functions that you call then you should not have any problems. Note that if you use base functions, then you can pull in the prototypes for all base functions by adding the following statement to your user exits: include "proto.h" 8. Performance Tip: We have made the user_display_string() function a resident function since this function is called on every string display to the screen. If you have other functions which are called from user_display_string() then you may want to make them resident also to avoid memory page swapping on every screen display. Simple testing can determine whether or not there is a performance difference under your specific configuration. 9. RTLink provides a method for virtualizing DATA which may prove to be very useful in your user exists if you have large arrays or structures of static data that is only accessed by the user exists. We have taken advantage of this feature in the base for the new module INCTOUCH.OBJ which contains some large arrays to hold touch information. The process basically consists of forcing the data in the module to be STATIC and FAR and then reading the REGISTER.MAP file to determine the segment name that must be added to the RTLPRO.LNK. Please refer to the RTLink documentation and the example for the virtual inctouch page in RTLPRO.LNK for more information. 10. If you are using a third party library then you may be able to virtualize the library assuming the multitasking considerations above do not apply to you. Please refer to the RTLink documentation for additional information. 11. For fiscal printer implementations, the user exit interface function for SYSCALL must include the segment offset of the data string. This is due to the fact that the REGISTER program is now in the large memory model. The modified base function is as follows: inregs.x.bx = drvr_addr; inregs.h.ah = D_WRITE; inregs.x.cx = strlen(data); inregs.x.dx = FP_OFF(data); inregs.x.si = 0; segread(&segregs); NEW ----> segregs.ds = FP_SEG(data); G->rc = int86x(SYSCALL, &inregs, &outregs, &segregs);