![]() |
![]() |
ALLBASE/SQL COBOL Application Programming Guide: HP 9000 Computer Systems > Chapter 1 Getting Started with ALLBASE/SQL Programming in COBOL![]() ALLBASE/SQL COBOL Programs |
|
To write a COBOL application that uses an ALLBASE/SQL database, you embed SQL commands in the COBOL source wherever you want the program to:
You also embed special SQL commands known as preprocessor directives. The COBOL preprocessor uses these directives to:
The following skeleton program illustrates the relationship between COBOL statements and embedded SQL commands in an application program. SQL commands may appear in a program at locations highlighted.
To delimit SQL commands for the preprocessor, you put the prefix EXEC SQL and the suffix END-EXEC around each SQL command:
Most SQL commands appear within the Procedure Division where you establish DBEnvironment access and manipulate data in a database. You must always specify a DBEnvironment at preprocessing time. The preprocessor needs to access the DBEnvironment you specify in order to store a module containing permanent sections used by your application program at run time. In this example, the DBEnvironment is PartsDBE which is in the sampledb directory.
Your application program needs to access the DBEnvironment to perform its work. The CONNECT command starts a DBEnvironment session for a specific environment. The RELEASE statement terminates that session.
At run time, the program starts a DBE session in the DBEnvironment PartsDBE, where a module for the program has been stored. A program can accept a DBEnvironment name from the program user and dynamically preprocess the SQL command that starts a DBEnvironment session. Refer to the chapter, "Using Dynamic Operations," for more information on dynamically connecting to a database and refer to the chapter, "Host Variables," for more information on using a host variable to connect to a database. No matter how you access a DBEnvironment (dynamic or stored sections), you must always specify a DBEnvironment name when you preprocess. In some cases an ALLBASE/SQL program is used with one or more DBEnvironments in addition to the DBEnvironment accessed at preprocessing time. In these cases, you use ISQL to install the installable module created by the preprocessor into each additional DBEnvironment accessed by your program. You can also preprocess the same application repeatedly with different DBEnvironments. See the chapter, "Using the ALLBASE/SQL COBOL Preprocessor," for information on the installable module. An alternative method of accessing more than one DBEnvironment from the same program would be to separate the program into separate compilable files. Each source file would access a DBEnvironment. In each file you start and terminate a DBE session for the DBEnvironment accessed. You then preprocess and compile each file separately. When you invoke the preprocessor, you identify the DBEnvironment accessed by the source file being preprocessed. After a file is preprocessed, it must be compiled so that no linking is performed before the next source file is preprocessed. When all source files have been preprocessed and compiled, you link them to create the executable program. Note that a program which accesses more than one DBEnvironment must do so in sequence. Such program design may adversely affect performance and requires special consideration. To preprocess or to use an already preprocessed ALLBASE/SQL application program, you must satisfy the authorization requirements for each DBEnvironment accessed. During preprocessing, the preprocessor needs to access the same DBEnvironment your source code will access at run time. Therefore, when you invoke the preprocessor, the DBEnvironment your program accesses must exist and you must identify that DBEnvironment.
In addition, you define a DBEnvironment session for the same DBEnvironment in the source code:
At run time, the program starts a DBE session in mydbe, where a module for the program is stored. In some cases an ALLBASE/SQL program is used with a DBEnvironment named differently from the DBEnvironment accessed at preprocessing time. In these cases, you can accept a DBEnvironment name from the program user and dynamically preprocess the SQL command that starts a DBE session. Dynamic preprocessing is covered in the chapter, "Using Dynamic Operations." ALLBASE/SQL authorization governs who can preprocess, execute, and maintain a program that accesses an ALLBASE/SQL DBEnvironment. To preprocess a program for the first time, you need CONNECT or DBA authority in the DBEnvironment your program accesses. When you preprocess a program, ALLBASE/SQL stores a module for that program in the DBEnvironment's system catalog and identifies your userid as the owner of that module. Subsequently, if you have OWNER or DBA authority, you can re-preprocess the program. To run a program accessing an ALLBASE/SQL DBEnvironment, you need the authority to start the DBE session in the program:
Any SQL command in the program is executed only if the OWNER of the module has the authorization to execute the command at run time, and the individual running the program has RUN authority for it. However, any dynamic command is executed only if the individual running the program has the authority to execute the command at run time. A dynamic command is an SQL command entered by the user at run time. Maintaining an ALLBASE/SQL program includes such activities as modifying a program in production use and keeping runtime authorization current as program users change. For these activities, you need OWNER authority for the module or DBA authority. More on this topic appears later in this chapter under "Maintaining ALLBASE/SQL Programs." When you create a DBEnvironment, a DataBase Environment Configuration (DBECon) file is created. The absolute pathname of this DBECon file is stored in the DBECon file itself. Once the DBECon file is created, the user, in all subsequent references to files, may use either an absolute pathname or a pathname relative to that of the DBECon file. By default, all pathnames of files and directories are relative to the pathname stored in the DBECon file. Any file reference which does not begin with a slash (/) assumes a pathname relative to that of the DBECon file. For example, if a DBEnvironment was created with the following command:
and the user was currently in the directory /users/dbsupport/sql, the pathname /users/dbsupport/sql would be stored in the DBECon file. If the user were subsequently to create a DBEFile with the command:
the actual pathname of the file OrdersDF would be relative to the pathname stored in the DBECon file and would be /users/dbsupport/sql/OrdersDF. Relative pathnames are restricted to a maximum length of 128 bytes. If however, the user were to create a DBEFile with the command:
the pathname stored in the DBECon file would be ignored while creating this file. The user would need to fully qualify this pathname each time this file is referenced. Absolute pathnames are restricted to a maximum length of 128 bytes. In addition, if the DBEnvironment you want the preprocessor to access resides in a directory other than your current working directory, you will have to either absolutely or relatively qualify the pathname of that DBEnvironment. For example, if the DBEnvironment you want the preprocessor to access resides in a subdirectory of yours, you would invoke the preprocessor as follows:
ALLBASE/SQL uses two types of shared memory, DBCore shared memory and inter-process communication (IPC) shared memory. When you start a DBEnvironment with the START DBE command, a block of DBCORE shared memory is obtained for the current DBEnvironment session. Until the session ends, all users and programs accessing the DBEnvironment share this allocated memory, which includes:
The use of DBCore shared memory is illustrated in Figure 1-2. Since these are shared resources, your program cannot manipulate their size directly. However, a DBA can alter them with the SQLUtil ALTDBE command. Refer to "Estimating Shared Memory Requirements" in the "Physical Design" chapter of the ALLBASE/SQL Database Administration Guide. An IPC shared memory segment is allocated for each local access application accessing the DBEnvironment. IPC shared memory is mapped to the user's process. ALLBASE/SQL offers two interprocess communication options. Fast ipc is the default and is available for the E.1 release. The previously existing interprocess communication method, signal ipc, remains a viable alternative depending on your application requirements. Any applications developed with ALLBASE/SQL release E.1 will by default use fast ipc. Any existing applications developed on a prior release will by default use signal ipc unless they are relinked. Once an existing application has been relinked, fast ipc is in effect. You have the option of setting an environment variable to indicate which form of interprocess communication you wish to use. The following sections describe each option, how to set the environment variable, and debugging considerations:
Fast ipc offers the following features:
When signal ipc is in effect, the ALLBASE/SQL software uses the following system signals:
If your application also uses system signals, the fast ipc option might offer a solution to signal contention problems. However, if you choose to use the signal ipc option, it remains available. The following example illustrates how to set the HPSQLfast_ipc environment variable. Suppose you already have applications that must use signals and which were written prior to this release. Signal ipc is the default unless you relink your applications. In this case, you reset the signal ipc option by setting the environment variable, HPSQLfast_ipc to n or N. For the Bourne shell or Korn shell:
For the C shell:
Perhaps your existing applications do not use signals, and you decide to take advantage of the new option. To reset to the fast ipc option you must relink your applications.
Be aware that when you enter a debugging session, you must set the signal handling table for the xdb debugger, for example: z 18 rs
Dynamically allocated and freed semaphores coordinate access to resources. Each user session allocates a set of two semaphores. The HP-UX ipcs command displays information on semaphores. If you need more semaphores, explicitly increase the semaphore parameters in the kernel configuration file to a larger value (or twice the number of expected concurrent user sessions) and regenerate the kernel. For more information on semaphores, refer to the HP-UX System Administrator Manual. |