Improving performance with system catalog caching
This topic includes the following sections:
- Caching system catalogs
- Using syngenload
- Using logging to determine if a system catalog is cached
- Troubleshooting system catalog caching
It is important that you carefully follow the instructions in this topic to ensure that system catalogs are loaded and unloaded correctly, and that shared memory is allocated and freed correctly. On UNIX, only system administrators should attempt to use system catalog caching. We’ve tested the procedures documented here on our systems, but don’t guarantee that they will work on all systems because shared memory mechanisms vary from one operating system to another. |
Caching system catalogs
You can improve performance by instructing xfODBC to cache system catalogs. When a system catalog is cached, the xfODBC driver consults the cached catalog in memory rather than rereading the catalog from disk for each new command.
To cache system catalogs,
1. | Add a syngenload command to one of the following files (which are in the synergyde\connect directory): |
- opennet.srv on Windows
- startnet on UNIX
- STARTNET.COM on OpenVMS
As distributed, these files include a sample syngenload command that’s been commented out. To use the command, uncomment the line and change the username, password, and connect file. See Using syngenload below for information on the syntax.
If necessary, you can run syngenload from the command line (see Running syngenload from the command line (Windows and OpenVMS) below). However, we recommend specifying the syngenload command in one of the above files, which are read each time the Synergy/DE OpenNet Server service (SynSQL) is started.
2. | On UNIX or OpenVMS, do one of the following: |
- On UNIX, verify that the following line is uncommented:
rm $GENESIS_HOME/synodbccache.dat
- On OpenVMS, verify that all three of the vortexipc lines in STARTNET.COM are uncommented:
$vortexipc:==$CONNECTDIR:vortexipc.exe $vortexipc /d $vortexipc /c 1000 0 0
Note the following:
- The SynSQL service must be running before you load a system catalog. For information on starting the SynSQL service, see Configuring Connectivity Series.
- You can load more than one system catalog at a time by issuing multiple syngenload commands.
- On Windows, when the SynSQL service is stopped, all loaded system catalogs are unloaded.
- To free shared memory on UNIX and OpenVMS, you must use the syngenload -u command to unload cached system catalogs. On UNIX and OpenVMS, stopping the SQL OpenNet server does not unload cached system catalogs.
- Do not delete the synodbccache.dat file unless instructed (as in Correcting other caching problems below, for example). This file is generated by xfODBC when a system catalog is cached. Deleting this file will corrupt the cache subsystem. Use the -u option for syngenload to unload a system catalog.
Using syngenload
To load (cache) a system catalog into memory or unload a system catalog from memory, use syngenload with the -l or -u option. The syngenload program is in the connect directory and has the following syntax:
syngenload -option
where option is one of the following:
-l "user/pswd" connect_file
Cache the system catalog stored in the directory specified in the dictsource line of connect_file. User must be one of the users defined in the system catalog, and pswd must be the password for the user. The quotes around user/pswd are required.
-m user/pswd connect_file base_size
Display shared memory segment addresses. User must be one of the users defined in the system catalog, and pswd must be the password for the user. See Adjusting the shared memory subsystem settings below for more information.
-u connect_file
Unload the system catalog stored in the directory specified in the dictsource line of connect_file.
/?
Display a list of syngenload options.
For example, the following command loads the system catalog specified by the sodbc_sa connect file using the default DBADMIN administrative user:
syngenload -l "DBADMIN/MANAGER" sodbc_sa
The next example unloads the system catalog specified by the sodbc_sa connect file:
syngenload -u sodbc_sa
When loading a system catalog, syngenload opens the system catalog files—just like an ODBC-enabled application. So if an ODBC-enabled application can’t open the system catalog, syngenload won’t be able to either.
Note the following:
- If you modify a system catalog while it’s cached, the copy on disk will be updated, but the cached version won’t be updated until it’s reloaded.
- In general, to unload a system catalog, you must be the user that loaded it. On UNIX, however, the root account can unload any system catalog.
- If syngenload is started by the Synergy/DE OpenNet Server service (SynSQL) on Windows, errors are written to the Windows event log.
- If you’re running syngenload from the command line, errors are written to the screen.
- For security reasons, the system catalog files that store user and group information (SODBC_USERS.* and SODBC_GROUPS.* or GENESIS_USERS.* and GENESIS_AUTHS.*) are not cached. xfODBC reads these from disk.
Running syngenload from the command line (Windows and OpenVMS)
If necessary, you can run syngenload from the command line for short-term testing purposes. However, we recommend putting the syngenload command in one of the files listed in step 1 above. These are read each time the SynSQL service is started. |
Before running syngenload from the command line on Windows or OpenVMS, you must set the VORTEX_SHM_FILE environment variable to synodbccache.dat in the connect\synodbc directory. (On UNIX, this is set for you.) For example:
set VORTEX_SHM_FILE=%GENESIS_HOME%\synodbccache.dat
On Windows, you must also stop and then restart vtxshm before running syngenload:
1. | If vtxshm is running (check this in Windows Task Manager), stop it by doing one of the following: |
- In Windows Task Manager, select the vtxshm.exe entry, and then click End Process.
- Enter the following at the command line:
vtxshm -t
Vtxshm is a part of the xfODBC caching mechanism and is automatically started by the SynSQL service. However, when vtxshm has been started by SynSQL, it isn’t available to syngenload if you start syngenload from the command line.
2. | Start vtxshm from the command line: |
start /B vtxshm -s
You can now run syngenload from the command line.
Using logging to determine if a system catalog is cached
To determine if a system catalog is cached or has been unloaded from shared memory, use Synergy driver logging or Synergy DBMS logging.
Synergy driver logging
Synergy driver logging lists the path and name of the shared memory file and lists errors encountered while attempting to use shared memory. To use Synergy driver logging, add the following lines to your connect file:
logfile file_spec
loglevel 1
where file_spec is the path and filename of the log file you want to create. For example, here’s the sample connect file with these lines:
dictsource "C:\Program Files\Synergex\SynergyDE\connect\synodbc\dict\" datasource ";C:\\Program Files\\Synergex\\SynergyDE\\connect\\synodbc\\dat;" XFDBTUT=C:\Program Files\Synergex\SynergyDE\connect\synodbc\dat logfile c:\temp\connect.log loglevel 1
Note the following:
- Add the logfile and loglevel lines to the connect file only after the sodbccache.dat file has been created. This file is created with the first syngenload -l command of the session. If you add syngenload commands to opennet.srv, startnet, or STARTNET.COM, add the logfile and loglevel lines to your connect file after the SQL OpenNet server has been started.
- The error “SHARED MEMORY error: Cannot attach to shared memory: Attempt to access invalid address” indicates that you need to set the VORTEX_SHM_BASE environment variable. Set it to address 80000000 (which on 32-bit Windows systems is 00000008 and on 64-bit Windows systems is 0000000800000000).
- The error “SHARED MEMORY error: Cannot open c:\...\syodbc\synodbccache.dat, No such file or directory” indicates that you need to set the VORTEX_SHM_FILE environment variable to the synodbccache.dat file. See Running syngenload from the command line (Windows and OpenVMS) above.
Synergy DBMS logging
Synergy DBMS logging tells you if the system catalog files are open and logs reads to the files. (These files are named GENESIS_* and are listed in the System Catalog Files table.) If the system catalog files are read as you access your database with xfODBC, the system catalog is not cached. (If the system catalogs are cached, the files will be read to create the cache, but not to access data.) For information on Synergy DBMS logging, see Synergy DBMS logging.
Troubleshooting system catalog caching
Following are some common problems that can occur with system catalog caching.
Cannot allocate shared memory
On Windows, if you get a “cannot allocate shared memory” error, the Synergy/DE OpenNet Server service (SynSQL) probably isn’t running. If you’re having trouble starting SynSQL, check the Windows event log for information. The sqld program has an -l option that writes more detailed information to the Windows event log. See sqld program for information.
On OpenVMS, this error may indicate that one or more of the vortexipc lines in STARTNET.COM is commented out. See step 2 in Caching system catalogs above for information.
Cannot attach to shared memory (Windows)
If you attempt to run syngenload from the command line, you may get the following error: “ERROR: SHARED MEMORY error: Cannot attach to shared memory: The operation completed successfully.” This may indicate that syngenload cannot access the vtxshm program. If you see this, follow the instructions in Running syngenload from the command line (Windows and OpenVMS) above.
Invalid parameter or argument (UNIX)
If you encounter an “Invalid Parameter” or “Invalid Argument” error when caching a system catalog on a UNIX system, you will need to adjust shared memory subsystem settings. The syngenload program uses this subsystem when you instruct it to load a system catalog. There are two shared memory subsystem settings for caching:
- To determine where to start the cache, syngenload uses the VORTEX_SHM_BASE environment variable, if set, for the cache’s base address. If this environment variable is not set (which is the default), the operating system determines which address the cache uses.
- To determine the amount of space for each shared memory segment used by the cache, syngenload reads the trim.ini file. As distributed (in the $TRIM_HOME/lib directory), the trim.ini file specifies a 500K shared memory segment size.
Before you make any adjustments, however, try caching your system catalog by using syngenload from the command line. If you get an “Invalid Parameter” or “Invalid Argument” error, follow the steps in Adjusting the shared memory subsystem settings below. If you don’t get an error, do the following:
1. | Set Synergy driver logging. (See Enabling Synergy driver logging.) |
2. | Use an ODBC-enabled application to connect to the database. Then check the file created by Synergy driver logging to see if there is an “Invalid Parameter” or “Invalid Argument” error after the synodbccache.dat entry. If there is, follow the steps in Adjusting the shared memory subsystem settings below. If you don’t see an error after this entry, caching is working correctly. |
3. | Turn off Synergy driver logging. |
Adjusting the shared memory subsystem settings
For most UNIX systems, you’ll need to adjust the shared memory segment size, but you may not need to set the base address. On Linux systems, however, it’s almost certain that you’ll need to set the base address as well. In either case, follow the instructions below.
1. | Reboot your machine. |
2. | Make sure there is no synodbccache.dat file in the $CONNECTDIR/synodbc directory. If it’s there, delete it. |
3. | Estimate the size of your cache by totaling the size (in bytes) of all the GENESIS*.is1 files in your system catalog. Then add 100,000 to the sum. You’ll use this figure as the base size (base_size in step 4 and step 6) for shared memory segment settings. |
4. | Use the tman utility, a memory analyzer, to determine if there is enough shared memory space. Use the following syntax: |
tman -n base_size base_size
If this causes an error, ask your system administrator to reconfigure the shared memory subsystem to allow a maximum size that’s at least twice as large as base_size. (This usually requires a system reboot.)
5. | Divide base_size by 1,024. Then open trim.ini in a text editor and set shmem_seg_size to the result of the calculation. (The shmem_seg_size setting specifies a value in kilobytes.) |
Note that the goal in setting shmem_seg_size is to create a shared memory segment that’s large enough for the entire system catalog, which is very important if you also set VORTEX_SHM_BASE. When this environment variable is set, the system catalog must be in a single shared memory segment. (If it’s split between two or more segments, they must be contiguous—something we can’t control.)
6. | Use syngenload to cache your system catalog. If you get an “Invalid Parameter” or “Invalid Argument” error, try increasing the shmem_seg_size setting in trim.ini by 500. Then go back to step 4, increasing base_size by 512,000. If you still get the error, use syngenload with the following syntax: |
syngenload -m user/pwd connect_file base_size
This will display three shared memory segment addresses.
VORTEX_SHM_BASE values for size 512000 SID: 1376262, VORTEX_SHM_BASE: 00303040 Native: 40303000 SID: 1409031, VORTEX_SHM_BASE: 00003840 Native: 40380000 SID: 1441800, VORTEX_SHM_BASE: 00D03F40 Native: 403FD000
Now set the VORTEX_SHM_BASE environment variable to the first address (in the example above, this is 00303040), and start again at step 4. (See VORTEX_SHM_BASE for information on setting this environment variable.)
Note that the goal in setting VORTEX_SHM_BASE is to set the base address to one that’s high enough to make the cache available to all programs that use it. (For example, if you don’t set this environment variable and the Synergy runtime is loaded into memory, the address may not be available; the runtime may have allocated it for something else before the cache is attached.) If you find in the final step that the first shared segment address listed isn’t high enough, set VORTEX_SHM_BASE to the second address listed—then the third if the second doesn’t work.
7. | Check the synodbccache.dat file to ensure that the shared memory ID is the same for all entries. (This file is generated in the $CONNECTDIR/synodbc directory when a system catalog is cached.) Check this by comparing values in the second column (the shared memory ID column) of the synodbccache.dat file. All entries in the second column must have the same value. For example: |
SODBC_SA_GENESIS_TABLES 1507332 00000008 65536 0 5048 SODBC_SA_GENESIS_COLUMNS 1507332 00000008 65536 5048 42108 SODBC_SA_GENESIS_INDEXES 1507332 00000008 65536 47156 7768 SODBC_SA_GENESIS_XCOLUMNS 1507332 00000008 65536 0 12004
(The third column lists base addresses. The sixth column lists the size of cached entries.)
8. | If the shared memory ID is not the same for all entries, the cache has been loaded into more than one segment, which may cause errors. In this case, add the total size of the generated cache (the sum of the values in the sixth column of the synodbccache.dat file), unload the cache using syngenload, and start again at step 4. |
9. | Once you’ve made it to this step, syngenload should be able to load the system catalog correctly. But we need to find out if the Synergy driver can access the cache. To do this, set Synergy driver logging, use an ODBC-enabled application to access your Synergy database, and then check the log. If you see an “Invalid Parameter” error after the synodbccache.dat entry, you need to use a higher address for shared memory; go back to step 6. If you don’t get this error after the synodbccache.dat entry, caching is working correctly. |
10. | Turn off Synergy driver logging. |
Viewing and removing shared segments
You can use the UNIX ipcs utility to view and remove shared memory segments that are in use. For example, if you’ve deleted the synodbccache.dat file, you can use ipcs to remove shared memory segments that are still allocated for caching. The second column lists shared memory IDs (which correspond to the shared memory IDs listed in synodbccache.dat).
------ Shared Memory Segments -------- key shmid owner perms bytes nattch status 0x00000000 196608 maryw 644 65536 0 0x00000000 229377 maryw 644 65536 0 0x00000000 491522 maryw 644 65536 0 0x00000000 524291 maryw 644 65536 0 0x00000000 1507332 root 644 10240000 0
Correcting other caching problems
If you find that system catalogs are not loading or unloading correctly, try the following.
On Windows,
1. | Stop the Synergy/DE OpenNet Server service (SynSQL). (See Stopping and removing SQL OpenNet.) |
2. | Open the Windows Task Manager and end the task named vtxshm if it exists. |
3. | Delete the synodbccache.dat file in your GENESIS_HOME directory. |
4. | Follow the caching instructions from the beginning. |
On UNIX and OpenVMS,
1. | Delete the synodbccache.dat file (in your GENESIS_HOME directory). |
2. | Reboot the system. |
3. | Follow the caching instructions from the beginning. |