Ingres CL NM
From Ingres Community Wiki
|
Ingres Compatability Library |
Compatibility Library Specification - NM
Abstract
This is the specification of the NM facility provided by the compatibility library.
Revision: 1.2, 11-Nov-1997
Document History
- Revision 1.2, 11-Nov-1997
- Converted to HTML.
- Revision 1.1, 29-Jul-94
- ADMIN exists for NMloc. (27-mar-92)
- UTILITY exists for NMloc (27-mar-92).
- DBDBTMPLT is obsolete for NMloc (27-mar-92).
- NMgtAt expansion size may be up to 255 on VMS, maybe much larger elsewhere. (26-mar-93).
- Revision 1.0, last modified 29-Aug-91
- Added new NMgtInstAt.
- Added NMsetpart and NMgetpart.
Specification
Introduction
There are two sets of names (also called attributes or symbols). These are systemwide names, used by all invocations of Ingres on a system, and per-user names. Attributes are always string valued.
Library
CL
Example Versions
On systems, such as UNIX and MVS, where there is no concept of systemwide names the executables ingprenv, ingsetenv and ingunset are provided to look at (print), set and unset the names, respectively.
User names are inherited from the user environment on UNIX.
On VMS, NM names map directly to logical names. Users manipulate logical names through VMS system commands. NM searchs the logical name tables in the normal VMS order (process level first, job level next, group and finally system).
The CMS operating system has no built-in facility for logical names. They are implemented through CMS files. The system-wide logical names file, IISYSTEM LOGICAL, exists on the INGRES production minidisk. A group-level logical names file, IIGROUP LOGICAL, may exist on any accessed minidisk. A personal logical names file, IIUSER LOGICAL, may exist on a user's minidisk. All of these files are maintained via the system editor. IISYSTEM LOGICAL is configured during the INGRES installation procedure.
Header File <nm.h>
The header file <nm.h> must be included before using any of the functions provided.
Executable Interface
The following functions are provided.
NMf_open - open specified file in II_CONFIG
NOTE: Use of this routine is limited to existing instances. New uses are NOT allowed. Instead, client code should call NMloc(), followed by an appropriate call to open the file (such as SIfopen to open an SI file).
Open fname in II_CONFIG with specified mode. fptr is the file pointer associated with the opened file.
Inputs:
| mode | the mode to open the file, as in SIfopen ("r", "w", "a"). |
| fname | the name of the file to open. |
Outputs:
| fptr | a FILE pointer filled in with the value of the opened file. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS NMf_open(mode, fname, fptr) char *mode; char *fname; FILE **fptr;
NMgetpart - return the name of the invoking component/part
NMgetpart provides the ability to obtain the name of the invoking component/part, if it's been set earlier in the life of the application usign NMsetpart.
NMgetpart will return a pointer to a character buffer which contains the name of the invoking component/part, or NULL if it's not been set earlier by NMsetpart.
Inputs:
| None |
Outputs:
| None |
Returns:
| partname | if operation succeeded. |
| NULL | if NMsetpart wasn't invoked successfully earlier. |
Prototype:
char *NMgetpart(void);
NMgtAt - get attribute
Return the value of an attribute which may be systemwide or per-user. The per-user attributes are searched first. If name is undefined then the value of the quantity pointed to by ret_val is set to NULL or ret_val is set to NULL (ie. you get a NULL pointer or a pointer to an empty string). Both conditions should be checked.
As a global buffer is associated with ret_val in some implementations, it may be advisable to do an STcopy() upon return.
Symbol values may be up to 255 characters on VMS, and much longer on other systems. Unfortunately, there's no way to know beforehand how big the expansion may be. You could get it's STlength and allocate memory for a stable copy.
Inputs:
| name | A string identifying the attribute in question. |
Outputs:
| ret_val | a pointer that will be filled in with the location of the string value associated with the name. |
Returns:
| None |
Definition:
VOID NMgtAt(name, ret_val) char *name; char **ret_val;
NMgtInstAt - get installation-wide attribute
.mc + Return the value of an installation-wide attribute, ignoring any user settable value. This should be used for symbols that for security or consistancy reasons should only be set in a protected namespace. On UNIX this is the namespace in the "symbol.tbl" file that can only be altered by the "ingres" user. On VMS this means only allowing symbols set at "group" level or above.
If name is undefined then the value of the quantity pointed to by ret_val is set to NULL or ret_val is set to NULL (ie. you get a NULL pointer or a pointer to an empty string). Both conditions should be checked.
As a global buffer is associated with ret_val in some implementations, it may be advisable to do an STcopy() upon return. .nf
Inputs:
| name | A string identifying the attribute in question. |
Outputs:
| ret_val | a pointer that will be filled in with the location of the string value associated with the name. |
Returns:
| None |
Definition:
VOID NMgtInstAt(name, ret_val) char *name; char **ret_val; .br .mc
NMloc - set location to contain full path of a file
Set ploc to point to a location whose buffer contains the full path of fname. what takes its value from PATH and/or FILENAME which are defined in <lo.h>, combined as for LOfroms. which's value determines the path less fname. which's value, defined in <nm.h>, is one of:
| BIN |
| II_BINARY |
| DBTMPLT |
| II_TEMPLATE |
| FILES |
| II_CONFIG |
| LIB |
| II_LIBRARY |
| SUBDIR |
| II_SYSTEM, what must be PATH |
| TEMP |
| II_TEMPORARY or current directory |
As a global buffer is associated with ploc it may be advisable to do an LOcopy() upon return.
Note that fname may be NULL, in which case a path is built.
Inputs:
| which | is one of ADMIN, BIN, FILES, LIB, SUBDIR, UTILITY or TEMP. |
| what | combinations of NODE, PATH, FILENAME, using the C "&" operator as the conjunct. |
| fname | the file name of interest. |
Outputs:
| ploc | LOCATION filled in with a description of the file in the right directory. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS NMloc(which, what, fname, ploc) char which; LOCTYPE what; char *fname; LOCATION *ploc;
NMpathIng - get path of INGRES installation
Get full path of the INGRES installation. NOTE: As an implementation detail, it suffices to actually get the path once and save it in a static for later use.
Inputs:
| None |
Outputs:
| path | pointer filled in with a string representing the full path of the installation. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS NMpathIng(path) char **path;
NMsetpart - save the name of the invoking component/part
NMsetpart provides the ability to provide the CL, and any routines that use this interface, a way to know what major subsystem is calling it.
NMsetpart should be invoked as early during the life of the program as possible, certainly before any routines which call its retrieval counterpart (NMgetpart).
NMsetpart is intended to be invoked at most once during the life of a program, and will take no action (except to return an error) upon a subsequent invocation.
The partname should be eight alphanumeric characters or less in length.
Since UT and ER construct filenames using the first three characters as part of the filename, the part name must begin with a letter and be unique in the first three characters.
NMsetpart will copy the partname into an internal buffer and return OK upon successful completion.
Inputs:
| partname | C string containing the new part name. |
Outputs:
| None |
Returns:
| OK | If operation succeeded, otherwise system specific error status. |
Prototype:
STATUS NMsetpart(char *partname);
NMt_open - open unique file in II_TEMPORARY
NOTE: Use of this routine is limited to existing instances. New uses are NOT allowed. Instead, client code should call NMloc(), followed by an appropriate call to open the file (such as SIfopen to open an SI file).
Create fname, with (possibly NULL) suffix, in II_TEMPORARY with specified mode. fptr is the file pointer associated with the opened file. fname and suffix are used to construct a unique filename for the file to be created. t_loc is associated with a global buffer containing the full path of this unique filename.
Inputs:
| mode |
| fname |
| suffix |
| t_loc |
Outputs:
| see description. | |
| fptr | pointer to a FILE pointer that is filled in with the open file. |
Returns:
| OK | if operation succeeded, otherwise system specific error status. |
Definition:
STATUS NMt_open(mode, fname, suffix, t_loc, fptr) char *mode; char *fname; char *suffix; LOCATION *t_loc; FILE **fptr;
|
Ingres Compatability Library |
