| Previous[ | Contents] | Index |
BThis 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.
HLIB$REC_DEPENDENCY records the input and output modules for the current Gbuild step and incorporates this information into the build dependency Agraph in the OpenVMS database. You must make a sequence of calls Con LIB$REC_DEPENDENCY to record all dependency information for the current build step.DThis 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 wLIB$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 DThe 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 Gparameter. For the VDE$K_DEPEND_VERSION function, this string contains Ethe name and version number of the LINKER or language processor (for 1example, "VAX Linker V5.2-1"). For the FVDE$K_DEPEND_BEGIN_RECORD and VDE$K_DEPEND_END_RECORD functions, this Aparameter is not used. For all other function codes, this string Ccontains 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
FA library index whose use depends on the function-code parameter. For ?the VDE$K_DEPEND_INPUT_LIBRARY and VDE$K_DEPEND_OUTPUT_LIBRARY Ffunctions, this is an output parameter which receives a library index Dthat uniquely identifies the specified input or output library (for 7example, an object library or a text library). For the DVDE$K_DEPEND_INPUT_MODULE and VDE$K_DEPEND_OUTPUT_MODULE functions, Hthis is an input parameter that specifies the index of the library that -contains the library module specified by the Fname-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 Fis performing the current build step in a system build. The processor For tool (for example, the LINKER) must perform a sequence of calls on FLIB$REC_DEPENDENCY with different function codes to specify all input Gand output modules to the current build step. The required sequence of calls is as follows:G
- Make one call with the VDE$K_DEPEND_BEGIN_RECORD function code. I This call begins the recording of dependency information for the build step.H
- Make as many calls as necessary to specify each input file, each J input library, each input library module, each output file, each output J library, and each output library module for the build step. These calls H may appear in any order. Duplicate calls for the same input or output H entity are also allowed; LIB$REC_DEPENDENCY eliminates any duplicates F before recording the information in the database.
Also make one H call with the VDE$K_DEPEND_VERSION function code. This call specifies C the name and version of the compiler, LINKER, or other tool that I performs the build step. This call may appear at any time with respect F 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.)E- Make one final call with the VDE$K_DEPEND_END_RECORD function F code. This call ends the dependency recording session for the build step.
ETo begin recording the inputs and outputs of the current build step, (make a call as in the following example:
"7LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_BEGIN_RECORD) );GThis 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.
NRecording Tool Name and Version
DTo record the name and version number of the compiler or other tool Cperforming the current build step, make a call as in the following example:
"0LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_VERSION), 9 %ASCID 'VAX-11 BLISS-32 V4.2-761' );EThis example illustrates how the Bliss compiler records its own name Fand version number. The function code is VDE$K_DEPEND_VERSION and the Fname-string parameter is the name and version number Gof the processor. The lib-index parameter is not used in this call.
FTo record a specific file as an input to the current build step, call FLIB$REC_DEPENDENCY with the VDE$K_DEPEND_INPUT_FILE function code, as in the following example:
"3LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_INPUT_FILE), = %ASCID 'DEVD$:[DIR.SRCDIR]MOD1.B32;3' );<The name-string parameter is the full file Hspecification of the input file; this is the resultant name string that BRMS returns. The lib-index parameter is not used.
VRecording Input Modules from Libraries
FTo record a specific module from a library as an input to the current Hbuild step, call LIB$REC_DEPENDENCY twice. The first call specifies the FVDE$K_DEPEND_INPUT_LIBRARY function code, as in the following example:
"6LIB$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 Gspecification of the library that contains the input module. The input Amodule can be from an object library, a text library, or a macro Alibrary; in this example the module is from a macro library. The Alib-index parameter is an output parameter that Hreceives a library index that uniquely identifies the library. FA library index is an integer value selected by LIB$REC_DEPENDENCY to represent the library.
GThe second call specifies the VDE$K_DEPEND_INPUT_MODULE function code, as in the following example:
"5LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_INPUT_MODULE), ( %ASCID 'INMODNAME', ! LIB_INDEX );HThis time the name-string parameter is the name of the ,input module you wish to specify. Thus, the Gname-string parameter is the name of an object module Hin an object library, a text element in a text library, or a macro in a Dmacro library. The lib-index parameter is an input Hparameter that specifies the library index that uniquely identifies the Hlibrary to which the module belongs. This is the library index returned Hby the previous VDE$K_DEPEND_INPUT_LIBRARY call. The library index thus Eestablishes the connection between the library module (or element or +macro) and the library to which it belongs.
CIf you record many input modules from the same library, record the Glibrary only once, using the VDE$K_DEPEND_INPUT_LIBRARY function code. EThen make one additional call for each library module (or element or =macro), specifying the same library index for each such call.
DTo record a specific file as an output from the current build step, Ccall LIB$REC_DEPENDENCY with the VDE$K_DEPEND_OUTPUT_FILE function "code, as in the following example:
"4LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_FILE), = %ASCID 'DEVD$:[DIR.OBJDIR]MOD1.LIS;3' );<The name-string parameter is the full file Dspecification of the output file; this is the resultant name string Gthat RMS returns. The lib-index parameter is not used.
WRecording Output Modules for Libraries
GTo record a specific module in a library as an output from the current Hbuild step, call LIB$REC_DEPENDENCY twice. The first call specifies the GVDE$K_DEPEND_OUTPUT_LIBRARY function code, as in the following example:
"7LIB$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 Bspecification of the library that contains the output module. The Houtput module can be from an object library, a text library, or a macro Clibrary; in this example the module is from an object library. The Alib-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.
HThe second call specifies the VDE$K_DEPEND_OUTPUT_MODULE function code, as in the following example:
"6LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_MODULE), ) %ASCID 'OBJMODNAME', ! LIB_INDEX );HThis time the name-string parameter is the name of the -output module you wish to specify. Thus, the Gname-string parameter is the name of an object module Hin an object library, a text element in a text library, or a macro in a Dmacro library. The lib-index parameter is an input Hparameter that specifies the library index that uniquely identifies the Hlibrary to which the module belongs. This is the library index returned Dby the previous VDE$K_DEPEND_OUTPUT_LIBRARY call. The library index Gthus establishes the connection between the library module (or element .or macro) and the library to which it belongs.
HIf you record many modules as outputs from the same library, record the Hlibrary only once, using the VDE$K_DEPEND_OUTPUT_LIBRARY function code. FThen make one additional call for each library module, specifying the &same library index for each such call.
EObject code that is used as input or output for a build step must be Etreated 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 DMOD1.OBJ) contains one or more object modules. Each object Fmodule has its own module name; the object module is the unit that is @copied to object libraries and is linked by the LINKER. OpenVMS Hstores dependency information for object code using object modules, not object files.
7If an object file is an output of the build step, call GLIB$REC_DEPENDENCY using the VDE$K_DEPEND_OUTPUT_LIBRARY function code 8to specify the object file, as in the following example:
"7LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_LIBRARY), > %ASCID 'DEVD$:[DIR.OBJDIR]OBJFILE.OBJ;1', ! LIB_INDEX );HIn this call, the name-string parameter is the name of Gthe object file. LIB$REC_DEPENDENCY returns a unique library index for <the object file to the lib-index parameter.
BThen call LIB$REC_DEPENDENCY using the VDE$K_DEPEND_OUTPUT_MODULE Cfunction code for each object module in the object file, as in the following example:
"6LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_OUTPUT_MODULE), ) %ASCID 'OBJMODNAME', ! LIB_INDEX );GTo record object modules as inputs to a build step (as the LINKER must Fdo), use the VDE$K_DEPEND_INPUT_LIBRARY and VDE$K_DEPEND_INPUT_MODULE function codes in the same way.
GTo end the recording of inputs and outputs for the current build step, Fmake a final call using the VDE$K_DEPEND_END_RECORD function code, as in the following example:
"5LIB$REC_DEPENDENCY( %REF(VDE$K_DEPEND_END_RECORD) );DThis 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 Gname-string and lib-index parameters are not used in this call.
ZRecording Is Done Only for Build Steps
FIf the language processor or other tool calls LIB$REC_DEPENDENCY when 6the 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 Ebuild step is being performed. If not, the function sets a flag that Bcauses the remaining function codes to return immediately without Dspending any further time in LIB$REC_DEPENDENCY. LIB$REC_DEPENDENCY Hdetermines whether a build step is currently active by checking whether Elogical name VDE$RECORD_DEPENDENCY is defined to be "TRUE" Dand whether logical name VDE$PAGEFILE_SECTION is defined at all. It Balso requires the shareable image VDE$RECDEP to be present on the Gsystem. 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...
3This appendix describes the VDE callable interface.
EThis interface is under development and is subject to change. Please ;contact VDE support before attempting to use this interface. |
pTable C-1 contains the itemlist codes used by various callback Hroutines. 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 | |
| L Signifies the address of the itemlist. This entry allows the callback M routine to locate the user-specified itemlist passed into the original call. | |
| & VDE$_CI_VERSION | |
| Reserved for future use. | |
| + VDE$_CI_USER_CONTEXT | |
| 5 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 | |
| 8 Specifies the remark assocated with the operation. | |
| % VDE$_CI_OUTPUT | |
| N Specifies the output device and directory specification. For operations J such as fetches, this should contain only the device and directory; B VDE will construct the file name and extension based on the module. | |
| $ VDE$_CI_INPUT | |
| N 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 | |
| M Received by the callback routine. A boolean flag that specifies if the # module is currently reserved. | |
| $ VDE$_CI_CAUSE | |
| N Specifies the cause for the replacement. The item references a longword B containing the replacement cause code: VDE$K_CI_CAUSE_FOLD, 2 VDE$K_CI_CAUSE_SCT, or VDE$K_CI_CAUSE_OTHER. | |
| - VDE$_CI_SCT_CONFERENCE | |
| C Specifies the SCT conference associated with the replacement. | |
| ' VDE$_CI_SCT_NOTE | |
| H 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 | |
| A Specifies the QAR database associated with the replacement. | |
| " VDE$_CI_QAR | |
| H 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. | |
| PreviousX | Next[ | Contents] | Index |