0Creates a new module in the current VDE library.

+Requires CREMOD privilege.

Format

0

CREATE MODULE mod-name [, mod-name...]

Parameter



mod-name

HThe name of the module being created. The module name must consist of a Hmodule name and a module type separated by a period (as in MODNAM.FOR). DIt may optionally be preceded by a facility name enclosed in square Gbrackets (as in [ACCTNG]MODNAM.FOR where ACCTNG is the facility name). EIf no facility name is specified, the module is assumed to belong to Gthe current default facility. The facility name, module name, and type >name may each be up to 39 characters long and must follow VDE name syntax.

Description

>The CREATE MODULE command creates a new module in the current 2VDE library. It records the new module in the VDE Gdatabase, including its facility, name, type, remark string, and other Gattributes. Every module belongs to some facility, either the facility 7you explicitly specify or the current default facility.

>Modules are classified as source modules or derived modules. ACsource module is a text file (normally) which you Bcreate and modify manually with an editor. A source module can be 9reserved from and replaced into the VDE library with the GRESERVE and REPLACE commands. The text of each source module is stored 3in a delta file within a CMS library in the form ofa CMS "element."

BBy default, the CREATE MODULE command does not create the initial Dgeneration of a source module. Instead it records the module in the 5VDE database and reserves it for you in your default Fdevelopment stream. You must then use the REPLACE command to actually Gcreate the initial generation of the module. This should be the normal 4way of creating new modules once the VDE library is ?established. However, if you use the /INPUT or /FROM_DIRECTORY Hqualifier, the CREATE MODULE command creates the initial generations of @the new modules; these qualifiers are useful when you initially 9establish your VDE library. (Note that /INPUT may not be Havailable, depending on the setting of the queued-replacement option on Athe stream. If /INPUT is not accepted, you must use a subsequent FREPLACE command to specify the contents of the module under creation.)

CA derived module is a file or other entity that isDproduced by an automated build step, such as an object module or an Fexecutable image. A derived module cannot be reserved or replaced. In >most cases, VDE automatically enters derived modules into the <VDE database when the modules are produced; you seldom need Fto enter them with the CREATE MODULE command. However, when a derived Emodule needs to be entered into the database manually, you can do so 9with the /DERIVED qualifier to the CREATE MODULE command.

AIf a module is mistakenly created, one can use the DELETE MODULE Ccommand to reverse the action and delete it---the UNRESERVE commandE will refuse to delete modules that lack a first generation.

DThe DELETE MODULE command allows the creator of an errant module to Hcorrect simple mistakes---such as a misnamed module---without requiring Dunusual privileges. With the DELETE MODULE command, the creator can Ddelete the module prior to the initial module replacement. EDELETE MODULE will cancel the outstanding reservation on the module, Ewill remove the module from any reservation session that it might be Dincluded in, and will prevent the module from ever appearing in the :VDE library. For further information on the DELETE MODULE `command, see DELETE MODULE. (The DELETE MODULE! command normally requires DELMOD) privilege. In this particular situation,; CREMOD privilege is sufficient to permit module deletion.)

Qualifiers



/BINARY



/NOBINARY (default)

ASpecifies whether the source module is a binary file or not. The ?/BINARY qualifier specifies that the source module is a binary G(non-text) file. Binary source files cannot be reviewed or differenced Cwith the REVIEW REPLACEMENT command because they do not consist of Gordinary ASCII text. The /NOBINARY qualifier specifies that the source Amodule is an ordinary ASCII text file. These qualifiers are only meaningful for source modules.

ELarge files that undergo extensive changes at frequent intervals, or Care the output of a language or application, may not be suited for Astorage as standard delta files as the file delta is never used, Eoccupies a considerable amount of disk space, and grows rapidly. See Cthe /MARKER qualifier. Examples of files well-suited for storage asFmarker files include most executable images, object files, Postscript files, and BACKUP savesets.

/CONCURRENT(default)



/NOCONCURRENT

GSpecifies whether the module can be reserved concurrently by more than Eone user. The /CONCURRENT qualifier allows the module to be reserved Fconcurrently unless a user overrides this default with for a specific Creservation. The /NOCONCURRENT qualifier specifies that the module cannot be reserved concurrently.

/DELETE



/NODELETE

FControls whether the delete attribute is set for the Hnew facility. This attribute allows the facility to be deleted with the ?DELETE FACILITY command. The /DELETE qualifier sets the delete Aattribute so that the new facility can be deleted. The /NODELETE Fqualifier clears the delete attribute so that the new facility cannot Hbe deleted unless you first reset this attribute with a MODIFY FACILITY <command. Marking a facility as /NODELETE makes it harder to !accidentally delete the facility.

>If this qualifier is not specified, VDE uses the value of the Eallow-deletion library attribute. The library allow-deletion default Fattribute can be set or reset by using the /ALLOW_DELETE qualifier on 4the CREATE LIBRARY or on the MODIFY LIBRARY command.

/DERIVED



/SOURCE (default)

ASpecifies whether the new module is a source module or a derived Hmodule. By definition, a source module is a module that can be reserved Hfrom and replaced into the library. The generations of each such module Cis stored in a "delta file" (a CMS element). Most source ;modules are text files that you modify with an editor, but 3VDE also supports binary (non-text) source modules.

EA derived module is a module that is produced from source modules or Hother derived modules by an automated build step. It cannot be reserved For replaced, and is often ignored during command wildcard processing. 1Derived modules are automatically recorded in the=VDE database when they are produced; they are seldom entered Cinto a library with the CREATE MODULE command. However, new source ;modules are not automatically recorded in the VDE database Gand must be entered into a library with the CREATE MODULE command. For 2this reason, the /SOURCE qualifier is the default.!

/FROM_DIRECTORY=dir-spec

DSpecifies that modules be created for all files in a specified disk =directory. The dir-spec parameter gives the AOpenVMS directory specification of the disk directory. When this Equalifier is specified, the mod-name parameters are Comitted, and the CREATE MODULE command creates a new module in the Hcurrent default facility for each file in the specified directory. Each Efile becomes the initial generation of the corresponding module. The Edir-spec parameter may also consist of a wildcarded ;file specification, in which case VDE creates a module for Geach file that matches the specification. (This feature can be used to Gcreate modules for only those files in a directory that have a certain Dfile extension, for example.) This qualifier lets you enter a large 9number of new modules into the VDE library with a single Hcommand, provided that the initial versions of those modules are stored Cin a single disk directory and that all modules belong to the same facility.

EThe initial generation of each module created with this qualifier is Hinserted into (becomes the latest generation of) the stream you specify Fwith the /STREAM qualifier or into the default stream if you omit the C/STREAM qualifier. It is also inserted into all successors of that stream.

?This qualifier requires the PERFREP privilege.

/HISTORY[="string"]

(

/NOHISTORY[="string"] (default)

ASpecifies the CMS history string to be associated with the moduleHand whether history information should be included in source files when Amodules are retrieved with the FETCH or RESERVE command. History Hinformation gives a historical record of previous changes to the module.

DThe /HISTORY qualifier specifies that history information should be Gincluded in source files by default when such files are retrieved with Fthe FETCH or RESERVE command. The /NOHISTORY qualifier specifies that Chistory information should be omitted. The string Fparameter to either qualifier specifies the default history string if Dthe user specifies that history information should be included in a Gretrieved file. (If you specify the /NOHISTORY qualifier on the CREATE DMODULE command, you must use the /HISTORY qualifier on the FETCH or BRESERVE command to use the default history string.) If you do not <specify a string parameter, VDE supplies a 7default history string that depends on the module type.

FSee the CMS documentation for a description of the CMS history string and its format.

/INPUT[=file-spec]

DThe /INPUT qualifier causes the CREATE MODULE command to create the Hinitial generation of the new module. This qualifier is only applicable Fto source modules. The file-spec parameter gives the ?OpenVMS file specification of a file that contains the initial <generation of the module. If the file-name part of the file Especification is omitted, the file name is assumed to be the same as Ethe module name. If the directory specification part is omitted, the Efile is assumed to be in your current default directory. If you omit <the whole file-spec parameter, VDE creates Hthe initial generation from the file in your default directory with the same name as the new module.

HThe initial generation of each module created with the /INPUT qualifier Cis inserted into (becomes the latest generation of) the stream you Especify with the /STREAM qualifier or into the default stream if you Gomit the /STREAM qualifier. It is also inserted into all successors of that stream.

FIf neither /INPUT nor /FROM_DIRECTORY is specified, the CREATE MODULE <command records the module in the VDE database and marks it Fas reserved to you. You must then use the REPLACE command to actually Gcreate the initial generation of the module. This is the preferred way 4of creating new modules once a VDE library has been established.

:The /INPUT qualifier is rejected on any streams marked forF queued replacement. To create and insert a module on a stream marked I for queued replacement, omit the /INPUT qualifier, and specify the file 3 to load into the new module via a REPLACE command.

>This qualifier require the PERFREP privilege.

/LOG (default)



/NOLOG

EControls whether log messages are printed after the new modules have @been created. The /LOG qualifier prints the messages and /NOLOG Fsuppresses them. The messages indicate that the new modules have been ;added to the VDE library and that the database transaction has successfully committed.

/MARKER



/NOMARKER (default)

CSpecifies whether the source module uses a marker file or not. The G/MARKER qualifier specifies that the source module uses a marker file. DWhen a source module uses a marker file, the module is stored as an Gordinary file in one of the delta-file directories. A small text file, Ccalled the marker file, contains the full file name of that source Efile, and this marker file is stored in the module's delta file (CMS Celement). In short, the delta file contains a small text file that Hpoints to the module's actual source file. The marker-file mechanism is Anormally only used for large or frequently changed binary source Fmodules, for which the delta-file mechanism may give poor performance @or use excessive disk space. Executable images, object modules, 9Postscript files, and BACKUP savesets are all example of F"source" modules for which the marker-file mechanism may be appropriate.

DThe actual source files for modules that use marker files are stored;in a subdirectory for the module's facility within the VDE Elibrary's delta-file directory tree. This subdirectory must have the special4 directory symbol VDE$MARKER. See the description ofB the SET DIRECTORY command for an explanation of how to establish G subdirectories and assign them directory symbols. See the description G of the command SHOW DIRECTORY/DELTA for information on displaying the 8 current marker file directory (or directories) setting.

HThe /NOMARKER qualifier specifies that the source module does not use a Hmarker file and that its text is stored directly in the delta file (CMS Delement) for the module. Ordinary ASCII text modules should not use marker files.

#Also see the /[NO]BINARY qualifier.

/NOTES[="string"]

&

/NONOTES[="string"] (default)

DSpecifies the CMS notes string to be associated with the module and Fwhether CMS notes should be included in source files when modules are Hretrieved with the FETCH or RESERVE command. CMS notes indicate in what /module generation each source line was created.

@The /NOTES qualifier specifies that notes information should be Gincluded in source files by default when such files are retrieved with Dthe FETCH or RESERVE command. The /NONOTES qualifier specifies that Anotes information should be omitted. The string Hparameter to either qualifier specifies the default notes string if the Huser specifies that notes information should be included in a retrieved Bfile. (If you specify the /NONOTES qualifier on the CREATE MODULE Ccommand, you must use the /NOTES qualifier on the FETCH or RESERVE Bcommand to use the default notes string.) If you do not specify a :string parameter, VDE supplies a default -notes string that depends on the module type.

HSee the CMS documentation for a description of the CMS notes string and its format.*

/NOTIFY=(username [,username...])

ASpecifies users to notify of all changes to the new module. Each :username parameter specifies the OpenVMS Busername or mail address of a user who should be notified by mail <message each time the specified module is replaced into the VDE library.

GEach username parameter can specify the username of a 5user already recorded in the VDE database, a OpenVMS Email address with one or more node names (such as NODE::SMITH), or a Dmail forwarding alias, or a defined logical name bound to a list of Fusers to notify. If you specify a logical name, keep in mind that the Hlogical name must be defined when it is later used to send notification Hmessages. It should thus be a group or system logical name or a logical <name that is in some other way defined for all users of the VDE library.

EIf you specify only one username parameter, you may !omit the surrounding parentheses.

/POSITION=column-number

HSpecifies the default column number in which CMS notes are to be placed Fwhen this source module is retrieved with a FETCH or RESERVE command. DThe column number must be an integer in the range 1 to 511. If this Fqualifier is omitted, the default column number is 81. This qualifier Hhas no effect unless notes are enabled with the /NOTES qualifier on the 9CREATE MODULE command or on the FETCH or RESERVE command.

GSee the CMS documentation for a description of CMS notes and how notes *are formatted at the ends of source lines.

/PROPAGATE



/NOPROPAGATE

CSpecifies whether automatic change propagation is allowed for this Emodule when it is reserved and replaced into the library. /PROPAGATE Fallows automatic change propagation and /NOPROPAGATE disallows change 6propagation. If change propagation is disallowed, VDE Fautomatically inhibits change propagation when the module is reserved Hor replaced as if the /NOPROPAGATE qualifier had been specified for the FRESERVE or REPLACE command. If you omit both qualifiers, the value of Hthe facility's nopopulate attribute is used to set the 2new module's propogate attribute.

/REMARK="string"

FSpecifies a remark string to be stored for the new module. The quoted Gremark string, which can be up to 132 characters long, may contain any Dexplanatory remark about the new module that you want stored in the <VDE database. Typically the remark describes the purpose or content of the module.

EAlthough this qualifier is required, you can specify an empty remark 9string. If you do not specify the /REMARK qualifier, VDE prompts you for a remark string.,

/REVIEWER=(username [,username...])

<Specifies reviewers for all changes to the new module. Each :username parameter specifies the OpenVMS Busername of a user who should review all changes to the specified 5module. The user must already be recorded in the VDE ;database. When a change to the module is replaced into the 4VDE library, VDE notifies the user of the change by 4mail message. If the replacement is queued, the userEshould then review the queued replacement before it is performed. If ;the replacement is immediate, VDE notifies the user of the Fnew module generation that was created, and the user may then inspect that generation.

EIf you specify only one username parameter, you may !omit the surrounding parentheses.

/SESSION[=session-name]

BSessions are used to logically group a set of module reservations Htogether, typically to group all modules related to a particular source Acode alteration or enhancement together. It allows all component Amodules reserved to be treated as a single entity for subsequent Greplacement operations. A session also allows additional modules to be Creserved and incorporated into an existing session at a later time.

DIf the new module is being created such that the initial generation Ewill be created by a subsequent replacement, /SESSION specifies that =VDE should add the new module reservation to the reservation =session given by the session-name parameter.

GIf no session with the specified session-name session 9name currently exists, VDE will create a new reservation Bsession under the specified session name and will incorporate the module reservation(s) into it.

;If the session-name parameter is omitted, >VDE generates a unique session name, creates a new session by 1that name, and adds the module reservation to it.

CIf the /SESSION qualifier is omitted on the CREATE MODULE command, <VDE will reserve the module (as expected), and will not add *the new module reservation to any session.

HSessions can be manipulated via the REPLACE, RESERVE, UNRESERVE, MODIFY ?SESSION, MODIFY RESERVATION, CREATE MODULE, and CANCEL SESSION Hcommands. And modules created by CREATE MODULE (on a queued-replacement Gstream) and reserved via RESERVE can be combined into the same session.

/STREAM=stream-name

BSpecifies that the module be reserved for the stream given by the Fstream-name parameter or that the initial generation Bof the module be inserted into that stream. If neither /INPUT nor ;/FROM_DIRECTORY is specified, the /STREAM qualifier causes =VDE to mark the module as reserved for the specified stream. HIf the /INPUT or /FROM_DIRECTORY qualifier is specified, /STREAM causes Bthe the initial generation of the new module to become the latest Hgeneration of the module for the specified stream and all its successor streams.

CIf the /STREAM qualifier is omitted, the module is reserved for or *inserted into your current default stream.

Examples

NVDEä CREATE MODULE STGCVT.FOR /STREAM=FOO /REMARK="String conversion routines"E%VDE-I-RESERVED, generation [CODE]STGCVT.FOR reserved from stream FOOO%VDE-I-MUSTREPL, you must replace the new module to create its first generation>%VDE-I-MODADDED, module [CODE]STGCVT.FOR added to the database>%VDE-I-COMMIT, database transaction has successfully committedVDEä      



GThis example creates a new source module called STGCVT.FOR. The module Bis created in the current default facility, facility CODE, and is Ereserved from the specified stream FOO. A subsequent REPLACE command C(not shown) is needed to create the first generation of the module.

TVDEä CREATE MODULE/NOLOG STGCVT.FOR /STREAM=FOO /REMARK="String conversion routines"VDEä      



DHere the same module is created as in the previous example, but the -/NOLOG qualifier suppresses the log messages.

<VDEä CREATE MODULE STGCVT.FOR /NOLOG /INPUT=[MYDIR]FOO.FOR -BVDEä                          /REMARK="String conversion routines"VDEä      



GIn this example, the /INPUT qualifier causes the command to create the Cinitial generation of the module from file [MYDIR]FOO.FOR. In this +case, the module is not marked as reserved.

@VDEä CREATE MODULE [CODE]STGCVT.FOR /REMARK="String routines", -?_VDEä              [ACCTNG]SALES.COB /REMARK="Sales accounting"F%VDE-I-RESERVED, generation [CODE]STGCVT.FOR reserved from stream MAINO%VDE-I-MUSTREPL, you must replace the new module to create its first generation>%VDE-I-MODADDED, module [CODE]STGCVT.FOR added to the databaseG%VDE-I-RESERVED, generation [ACCTNG]SALES.COB reserved from stream MAINO%VDE-I-MUSTREPL, you must replace the new module to create its first generation?%VDE-I-MODADDED, module [ACCTNG]SALES.COB added to the database>%VDE-I-COMMIT, database transaction has successfully committedVDEä      



FThis example creates two new source modules, one in facility CODE and Cone in facility ACCTNG. Each module has its own remark string. The ?modules are reserved in the user's default stream, stream MAIN.

VDEä SET STREAM MAINVDEä SET FACILITY CODE;VDEä CREATE MODULE/FROM_DIRECTORY=[MYDIR.SOURCES]/REMARK=""G%VDE-I-GENINSERT, generation [CODE]A.REQ;1(1) inserted into stream MAIN9%VDE-I-MODADDED, module [CODE]A.REQ added to the databaseG%VDE-I-GENINSERT, generation [CODE]B.REQ;1(1) inserted into stream MAIN9%VDE-I-MODADDED, module [CODE]B.REQ added to the databaseG%VDE-I-GENINSERT, generation [CODE]C.B32;1(1) inserted into stream MAIN9%VDE-I-MODADDED, module [CODE]C.B32 added to the databaseG%VDE-I-GENINSERT, generation [CODE]D.B32;1(1) inserted into stream MAIN9%VDE-I-MODADDED, module [CODE]D.B32 added to the databaseG%VDE-I-GENINSERT, generation [CODE]E.B32;1(1) inserted into stream MAIN9%VDE-I-MODADDED, module [CODE]E.B32 added to the database>%VDE-I-COMMIT, database transaction has successfully committedVDEä      



FThis example uses the /FROM_DIRECTORY qualifier to create modules for Dall files in a given directory. The SET STREAM command makes stream DMAIN the default stream and the SET FACILITY command makes facility HCODE the default facility. The CREATE MODULE command reads all files in Ddirectory [MYDIR.SOURCES] and creates a module in facility CODE for ;each such file. VDE creates the initial generation of each Cmodule and inserts that generation into the default stream (stream FMAIN) and all successor streams. (No successor streams are defined in Ethis example.) The log messages confirm that the initial generations Ehave been inserted into the appropriate streams and that the modules have been added to the database.