| Previous | Contents | Index |
This appendix describes the callable interface that records build dependencies in the OpenVMS database. This interface allows the OpenVMS LINKER and various language processors to record the input and output modules of a given build step in the VDE database.
LIB$REC_DEPENDENCY records the input and output modules for the current build step and incorporates this information into the build dependency graph in the OpenVMS database. You must make a sequence of calls on LIB$REC_DEPENDENCY to record all dependency information for the current build step.This routine performs no action and consumes no time unless a build step is currently executing as part of a OpenVMS system build.
LIB$REC_DEPENDENCY func-code, name-string, lib-index
func-code
VMS usage: type: longword integer (signed) access: read only mechanism: by reference
A function code indicating the information that is passed to LIB$REC_DEPENDENCY. Table B-1 contains the list of defined values.
Table B-1 Dependency Codes Value Symbol Description 1 VDE$K_DEPEND_BEGIN_RECORD Begin dependency recording 2 VDE$K_DEPEND_END_RECORD End dependency recording 3 VDE$K_DEPEND_VERSION Record compiler or tool version 4 VDE$K_DEPEND_INPUT_FILE Record an input file 5 VDE$K_DEPEND_INPUT_LIBRARY Record an input library 6 VDE$K_DEPEND_INPUT_MODULE Record an input library module 7 VDE$K_DEPEND_OUTPUT_FILE Record an output file 8 VDE$K_DEPEND_OUTPUT_LIBRARY Record an output library 9 VDE$K_DEPEND_OUTPUT_MODULE Record an output library module The meanings of the remaining parameters depend on the value of the function code.
name-string
VMS usage: type: character string access: read only mechanism: by descriptor
An ASCII text string whose contents depend on the function-code parameter. For the VDE$K_DEPEND_VERSION function, this string contains the name and version number of the LINKER or language processor (for example, "VAX Linker V5.2-1"). For the VDE$K_DEPEND_BEGIN_RECORD and VDE$K_DEPEND_END_RECORD functions, this parameter is not used. For all other function codes, this string contains the name of a file, library, or library module that is an input to or output of the current build step.lib-index
VMS usage: type: longword integer (signed) access: read write mechanism: by reference
A library index whose use depends on the function-code parameter. For the VDE$K_DEPEND_INPUT_LIBRARY and VDE$K_DEPEND_OUTPUT_LIBRARY functions, this is an output parameter which receives a library index that uniquely identifies the specified input or output library (for example, an object library or a text library). For the VDE$K_DEPEND_INPUT_MODULE and VDE$K_DEPEND_OUTPUT_MODULE functions, this is an input parameter that specifies the index of the library that contains the library module specified by the name-string parameter. For all other function codes, this parameter is not used.
LIB$REC_DEPENDENCY records build dependency information in the OpenVMS database for the language processor or other tool that is performing the current build step in a system build. The processor or tool (for example, the LINKER) must perform a sequence of calls on LIB$REC_DEPENDENCY with different function codes to specify all input and output modules to the current build step. The required sequence of calls is as follows:
- Make one call with the VDE$K_DEPEND_BEGIN_RECORD function code. This call begins the recording of dependency information for the build step.
- Make as many calls as necessary to specify each input file, each input library, each input library module, each output file, each output library, and each output library module for the build step. These calls may appear in any order. Duplicate calls for the same input or output entity are also allowed; LIB$REC_DEPENDENCY eliminates any duplicates before recording the information in the database.
Also make one call with the VDE$K_DEPEND_VERSION function code. This call specifies the name and version of the compiler, LINKER, or other tool that performs the build step. This call may appear at any time with respect to the calls that specify inputs and outputs. (If several tools are used in the build step, you may make this call for each tool.)- Make one final call with the VDE$K_DEPEND_END_RECORD function code. This call ends the dependency recording session for the build step.
To begin recording the inputs and outputs of the current build step, make a call as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_BEGIN_RECORD) );This example (shown in Bliss) illustrates how a compiler or other tool begins recording dependency information. The function code is VDE$K_DEPEND_BEGIN_RECORD. The name-string and lib-index parameters are not used in this call.
Recording Tool Name and Version
To record the name and version number of the compiler or other tool performing the current build step, make a call as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_VERSION), %ASCID 'VAX-11 BLISS-32 V4.2-761' );This example illustrates how the Bliss compiler records its own name and version number. The function code is VDE$K_DEPEND_VERSION and the name-string parameter is the name and version number of the processor. The lib-index parameter is not used in this call.
To record a specific file as an input to the current build step, call LIB$REC_DEPENDENCY with the VDE$K_DEPEND_INPUT_FILE function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_INPUT_FILE), %ASCID 'DEVD$:[DIR.SRCDIR]MOD1.B32;3' );The name-string parameter is the full file specification of the input file; this is the resultant name string that RMS returns. The lib-index parameter is not used.
Recording Input Modules from Libraries
To record a specific module from a library as an input to the current build step, call LIB$REC_DEPENDENCY twice. The first call specifies the VDE$K_DEPEND_INPUT_LIBRARY function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_INPUT_LIBRARY), %ASCID 'DEVD$:[DIR.SRCDIR]SYSMACLIB.MLB;1', LIB_INDEX );The name-string parameter is the full file specification of the library that contains the input module. The input module can be from an object library, a text library, or a macro library; in this example the module is from a macro library. The lib-index parameter is an output parameter that receives a library index that uniquely identifies the library. A library index is an integer value selected by LIB$REC_DEPENDENCY to represent the library.
The second call specifies the VDE$K_DEPEND_INPUT_MODULE function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_INPUT_MODULE), %ASCID 'INMODNAME', LIB_INDEX );This time the name-string parameter is the name of the input module you wish to specify. Thus, the name-string parameter is the name of an object module in an object library, a text element in a text library, or a macro in a macro library. The lib-index parameter is an input parameter that specifies the library index that uniquely identifies the library to which the module belongs. This is the library index returned by the previous VDE$K_DEPEND_INPUT_LIBRARY call. The library index thus establishes the connection between the library module (or element or macro) and the library to which it belongs.
If you record many input modules from the same library, record the library only once, using the VDE$K_DEPEND_INPUT_LIBRARY function code. Then make one additional call for each library module (or element or macro), specifying the same library index for each such call.
To record a specific file as an output from the current build step, call LIB$REC_DEPENDENCY with the VDE$K_DEPEND_OUTPUT_FILE function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_FILE), %ASCID 'DEVD$:[DIR.OBJDIR]MOD1.LIS;3' );The name-string parameter is the full file specification of the output file; this is the resultant name string that RMS returns. The lib-index parameter is not used.
Recording Output Modules for Libraries
To record a specific module in a library as an output from the current build step, call LIB$REC_DEPENDENCY twice. The first call specifies the VDE$K_DEPEND_OUTPUT_LIBRARY function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_LIBRARY), %ASCID 'DEVD$:[DIR.OBJDIR]SYSOBJLIB.OLB;1', LIB_INDEX );The name-string parameter is the full file specification of the library that contains the output module. The output module can be from an object library, a text library, or a macro library; in this example the module is from an object library. The lib-index parameter is an output parameter that receives a library index that uniquely identifies this library. The library index is an integer value selected by LIB$REC_DEPENDENCY to represent the library.
The second call specifies the VDE$K_DEPEND_OUTPUT_MODULE function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_MODULE), %ASCID 'OBJMODNAME', LIB_INDEX );This time the name-string parameter is the name of the output module you wish to specify. Thus, the name-string parameter is the name of an object module in an object library, a text element in a text library, or a macro in a macro library. The lib-index parameter is an input parameter that specifies the library index that uniquely identifies the library to which the module belongs. This is the library index returned by the previous VDE$K_DEPEND_OUTPUT_LIBRARY call. The library index thus establishes the connection between the library module (or element or macro) and the library to which it belongs.
If you record many modules as outputs from the same library, record the library only once, using the VDE$K_DEPEND_OUTPUT_LIBRARY function code. Then make one additional call for each library module, specifying the same library index for each such call.
Object code that is used as input or output for a build step must be treated as a module in a library, even if the object code goes to or comes from an object file. In OpenVMS, an object file (such as MOD1.OBJ) contains one or more object modules. Each object module has its own module name; the object module is the unit that is copied to object libraries and is linked by the LINKER. OpenVMS stores dependency information for object code using object modules, not object files.
If an object file is an output of the build step, call LIB$REC_DEPENDENCY using the VDE$K_DEPEND_OUTPUT_LIBRARY function code to specify the object file, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_LIBRARY), %ASCID 'DEVD$:[DIR.OBJDIR]OBJFILE.OBJ;1', LIB_INDEX );In this call, the name-string parameter is the name of the object file. LIB$REC_DEPENDENCY returns a unique library index for the object file to the lib-index parameter.
Then call LIB$REC_DEPENDENCY using the VDE$K_DEPEND_OUTPUT_MODULE function code for each object module in the object file, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_MODULE), %ASCID 'OBJMODNAME', LIB_INDEX );To record object modules as inputs to a build step (as the LINKER must do), use the VDE$K_DEPEND_INPUT_LIBRARY and VDE$K_DEPEND_INPUT_MODULE function codes in the same way.
To end the recording of inputs and outputs for the current build step, make a final call using the VDE$K_DEPEND_END_RECORD function code, as in the following example:
LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_END_RECORD) );This call tells LIB$REC_DEPENDENCY that there are no more inputs or outputs to record for the current build step. The dependency information passed in so far can be recorded in the OpenVMS database when the build step completes. The name-string and lib-index parameters are not used in this call.
Recording Is Done Only for Build Steps
If the language processor or other tool calls LIB$REC_DEPENDENCY when the processor or tool is not performing a build step, LIB$REC_DEPENDENCY returns without performing any action. The VDE$K_DEPEND_BEGIN_RECORD function checks whether a OpenVMS build step is being performed. If not, the function sets a flag that causes the remaining function codes to return immediately without spending any further time in LIB$REC_DEPENDENCY. LIB$REC_DEPENDENCY determines whether a build step is currently active by checking whether logical name VDE$RECORD_DEPENDENCY is defined to be "TRUE" and whether logical name VDE$PAGEFILE_SECTION is defined at all. It also requires the shareable image VDE$RECDEP to be present on the system. The overhead of calling LIB$REC_DEPENDENCY is thus designed to be negligible when the processor or tool is not performing a OpenVMS build step.
|
this section under construction...
This appendix describes the VDE callable interface.
This interface is under development and is subject to change. Please contact VDE support before attempting to use this interface. |
Table C-1 contains the itemlist codes used by various callback routines. Not all callbacks need nor use all codes listed in the table.
| Symbol | Description |
|---|---|
| VDE$_CI_END_OF_LIST | |
| Signifies the end of the itemlist. | |
| VDE$_CI_CHAIN | |
| Reserved for future use. | |
| VDE$_CI_ITEMLIST | |
| Signifies the address of the itemlist. This entry allows the callback routine to locate the user-specified itemlist passed into the original call. | |
| VDE$_CI_VERSION | |
| Reserved for future use. | |
| VDE$_CI_USER_CONTEXT | |
| Ignored by VDE, available for any user purpose. | |
| VDE$_CI_LIBRARY | |
| Specifies the device and directory of the VDE library. | |
| VDE$_CI_STREAM | |
| Specifies the VDE stream. | |
| VDE$_CI_FACILITY | |
| Specifies the VDE facility. | |
| VDE$_CI_MODULE | |
| Specifies the VDE module. | |
| VDE$_CI_REMARK | |
| Specifies the remark assocated with the operation. | |
| VDE$_CI_OUTPUT | |
| Specifies the output device and directory specification. For operations such as fetches, this should contain only the device and directory; VDE will construct the file name and extension based on the module. | |
| VDE$_CI_INPUT | |
| Specifies the input device and directory. Do not specify a file name or extension. | |
| VDE$_CI_RESERVATION | |
| Specifies the name of the reservation. | |
| VDE$_CI_RESERVED | |
| Received by the callback routine. A boolean flag that specifies if the module is currently reserved. | |
| VDE$_CI_CAUSE | |
| Specifies the cause for the replacement. The item references a longword containing the replacement cause code: VDE$K_CI_CAUSE_FOLD, VDE$K_CI_CAUSE_SCT, or VDE$K_CI_CAUSE_OTHER. | |
| VDE$_CI_SCT_CONFERENCE | |
| Specifies the SCT conference associated with the replacement. | |
| VDE$_CI_SCT_NOTE | |
| Specifies the SCT conference note associated with the replacement. | |
| VDE$_CI_SCT_REMARK | |
| Specifies the SCT remark associated with the replacement. | |
| VDE$_CI_QAR_DATABASE | |
| Specifies the QAR database associated with the replacement. | |
| VDE$_CI_QAR | |
| Specifies the QAR number associated with the replacement. Must be associated with a preceeding VDE$_CI_QAR_DATABASE item. | |
| VDE$_CI_CLD | |
| Specifies the CLD number associated with the replacement. | |
| Previous | Next | Contents | Index |